Converge Process Docs and search operator flows

[alexeygrigorev]

Converge Process Docs and search operator flows

Status: accepted and committed locally — exact accepted commit d334020ca5a582d31a81b371988169cab4e7f6b2; not merged, pushed, deployed, shipped, or closed
Tags: enhancement, docs, portal, frontend, testing, design, P1
Parent: #162, Wave A slice 3
Depends on: satisfied — accepted containing commits #218 0c89588df809b2e84af02e796d1910a25eea0165 and #219 9d204d208820e3d842a3d3fc83493c230bcadaa5, with accepted #180/#161 foundations
Blocks: #162 final integrated design-system acceptance for Process Docs and search
Next owner: Orchestrator — when coordinated publication resumes, merge the accepted local Wave A chain in order, push main, then hand off to On-Call; no implementation or review rerun is pending for #220
Resume condition: local main is clean and the Orchestrator is ready to publish the accepted Wave A chain; #220 requires no rerun unless commit d334020ca5a582d31a81b371988169cab4e7f6b2 changes

Product outcome

Make Process Docs a coherent operator flow from discovery to use: browse the document library, search across process context and executable work, open a readable document, return to the exact originating Task, intentionally enter edit/create, and recover local drafts without losing work.

The interface must distinguish an empty result from an unavailable source, keep successful search groups usable during partial failure, and expose human labels before repository paths or IDs. It must use #218's accepted shared page-header, action-row, form, semantic-status, and honest-state primitives rather than creating Process-Docs-only variants.

This is a frontend presentation, navigation-context, and evidence slice over the existing authenticated contracts. It does not add or move operational content. Raw operational knowledge remains in the separate private knowledge repository; this public repository may contain only product code and synthetic public-safe fixtures/evidence.

Frozen baseline and dependency reconciliation

PM inventory was performed read-only at clean baseline 78e91223203aa54376a318fd1a3214ce0242e0c3.

That baseline already contains:

• accepted Restore behavior-based browser coverage and fix canonical UI accessibility races #180 increments e684162 and b045739, including focus, browser isolation/diagnostics, and behavior-level canonical journey foundations;
• accepted Finalize the canonical scan-first Operations Home #161 Home/shared-shell work, finalized by 7d77632 and closed by 64476d2;
• the Restore canonical frontend behavior coverage and SAM parity gates #159 durable capability and source/SAM parity contract;
• canonical Process Docs routes and existing /docs, /search, /docs/registry, /docs/backlinks, and content-read behavior.

#220 does not reopen those foundations. #218 owns shared presentation convergence and overlaps frontend/src/styles.css, frontend/src/surfaces/knowledge/list.js, process-docs.js, search.js, navigation.js, focused tests, and browser evidence. Therefore implementation starts after #218's accepted commit by default. An earlier start is allowed only if the Orchestrator records exact disjoint write ownership; sharing any listed path is proof that it is not disjoint. If another accepted branch is integrated first, refresh this issue's gap inventory on the containing SHA and implement only gaps that remain. Never resolve overlap by reverting or absorbing dependency-owned behavior.

Criterion-to-current-source/test inventory

Already compliant — preserve, do not rebuild

Criterion	Current production source at 78e9122	Current proof	Required treatment
Canonical library/filter route	frontend/src/surfaces/knowledge/process-docs.js, filters.js, navigation.js retain /#/processes, canonical metadata filters, loading/empty/unavailable distinctions, and document deep links	frontend/test/knowledge-surface.test.mjs covers catalog loading, stale responses, empty versus outage, filter URLs/reload/clear, folder return URLs, and deep links; canonical browser journey covers filter round trips	Preserve route, query, stale-response, and availability behavior
Reader/editor/create lifecycle	frontend/src/surfaces/knowledge/navigation.js loads exact documents with stale-request guards and loading/not-found/error recovery; frontend/src/surfaces/document-editor/lifecycle.js owns guarded create/save/discard and value retention	frontend/test/knowledge-surface.test.mjs, frontend/test/document-editor-surface.test.mjs, and the real-server canonical journey cover create/read/edit, save failure/retry, not-found, and stale responses	Converge hierarchy and semantics only; no new API or lifecycle
Local draft durability	document-editor/lifecycle.js stores per-path local drafts; document-editor/changes.js lists, opens, diffs, saves, partially fails, and discards them	Editor unit tests cover dirty state, single/all save, partial failure, discard cancellation, rename/delete cleanup, and validation/conflict/network/permission retention; canonical browser evidence covers draft management and partial-save failure	Preserve keys, retention, at-most-once guards, and partial outcome truth
Task/Card return affordance	knowledge/navigation.js::renderDocReturnContext; Task/Card panels pass typed return context into openDocument	frontend/test/knowledge-surface.test.mjs covers Task return and missing-document recovery	Preserve Card behavior; close the Task-context continuity gap below
Grouped ranked search	knowledge/search.js ranks and groups Tasks, Cards, Templates, Process Docs, Artifacts, Files, and Assistant Jobs and opens canonical destinations	Knowledge unit tests cover grouping/ranking, exact document open, stale queries, canonical filters, and source attribution; canonical browser journey proves a filtered document result	Preserve ranking, destination contracts, and loaded groups
Partial-source honesty	knowledge/search.js::searchStateFor and renderSearchSourceState distinguish full outage, partial-with-results, partial-empty, filter-empty, and query-empty and retry the same query/filters	Knowledge unit tests cover named unavailable sources, partial groups, retry, and all empty states	Preserve successful data and exact retry input; add durable real-server coverage below
Existing capability identity	backend/e2e/frontend-capabilities.json defines process-docs.*; backend/e2e/canonical-capability-behavior.spec.js emits current Process Docs states	Normal capability reporter and source/SAM parity machinery	Extend the existing capability only for genuinely distinct changed states; do not create a parallel schema or reporter

Concrete unmet gaps owned by #220

1. Library hierarchy and discoverability. renderDocsSurface leads with quality findings/reference cards while the complete filtered document collection is not a dominant, semantically labelled library region. Make the current filtered catalog browsable from the Process Docs surface, with document count, active-filter truth, a visible first result or recovery action, and one clear New process doc action. Keep quality/reference context secondary; do not remove its behavior or move it to Home/Admin.
2. Native document-row and grouping semantics. list.js makes an article[tabindex=0] emulate a control, and search groups append button rows without list semantics or an accessible group count. Use native actionable/list structure, one useful accessible name per result, correct heading order, keyboard behavior without custom Space/Enter emulation, and programmatic group/source status.
3. Reader-to-editor intent. The current shared editor view exposes document path and editing controls as equal-weight content even in rendered mode. Make reading the default dominant state, demote repository path/technical metadata, and make entering edit mode intentional while retaining exact content, scroll restoration, warnings, backlinks, related-document navigation, and save/discard behavior. Do not replace the existing structured/raw editor implementation.
4. Local-draft discoverability. Existing drafts are durable but primarily surfaced inside the editor's Pending Changes panel. Expose an honest local-only draft count/entry point from the Process Docs library and a clear local-draft indicator in the reader/editor. Opening, saving, partially saving, discarding, renaming, and deleting must continue to use the existing draft store and confirmation rules. Never label a local draft as server-saved or shared.
5. Task return-context continuity. openDocument replaces docReturnContext with null whenever an internal document link, related document, backlink, retry, or search result opens without a new context. Preserve the exact originating Task ID/title and return action across in-knowledge document navigation, loading, retryable failure, not-found recovery, edit/read toggles, and browser Back/Forward until the operator explicitly leaves Process Docs or returns. Returning reopens that Task through the canonical panel path and restores useful focus. Do not infer authorization, actor identity, or teammate scope client-side; preserve existing Card behavior without expanding it.
6. Human-first, boundary-safe result presentation. Search/document rows currently promote raw paths and may display raw Card IDs or source error strings. Lead with safe titles, source/type, semantic status, and due/owner labels only when already present in the authenticated response. Keep repository paths available only where needed for document disambiguation/edit/create, visually secondary and not copied into announcements. Do not render opaque IDs, storage URIs, provider codes, stack/error details, private links, or raw backend diagnostics as routine result metadata.
7. Durable grouped/partial-search evidence. Unit tests prove partial behavior, but the existing process-docs capability has no distinct grouped-ready, partial-with-results, partial-empty, or retry-recovery state, and the canonical browser journey does not prove those states through the real local server. Add bounded capability entries and real-server behavior evidence for the exact changed states, then include them in normal source/SAM parity accounting.
8. Responsive and visual convergence after Converge Wave A surfaces on bounded shared UI primitives #218. Apply Converge Wave A surfaces on bounded shared UI primitives #218's accepted primitives to only the Process Docs/library/reader/editor/create/search gaps above. At mobile width the first document, draft recovery action, or partial-search result must not be pushed below decorative/empty sections; editor/create actions remain reachable without horizontal scrolling.

Dependency-owned — preserve exactly

• Converge Wave A surfaces on bounded shared UI primitives #218: shared page-header, action-row, form/footer, status, honest-state, token, and responsive presentation contracts.
• Restore behavior-based browser coverage and fix canonical UI accessibility races #180: shell/search focus, mobile drawer, notifications, browser isolation, diagnostics, and canonical race protections.
• Finalize the canonical scan-first Operations Home #161: Home composition, Home Docs-control isolation, global shell integration, and Home route/history/focus.
• Show signed-in identity and authorized teammates’ Task/Card work #164: actor/selected-owner identity, teammate authorization, Task visibility, attribution, Users/Admin, and delegated actions.
• Make assistant output review safe and lifecycle-complete #158: Assistant/Artifact lifecycle, access, review, archive, and rehydration.
• Restore canonical frontend behavior coverage and SAM parity gates #159: capability schema, collector/reporter, evidence policy, and source/SAM parity machinery.
• Existing backend document/search/index contracts and private knowledge storage boundary.

Exact bounded write ownership

Production edits are limited to these paths, and only for the concrete gaps above:

• frontend/index.html
• frontend/src/styles.css
• frontend/src/surfaces/knowledge/list.js
• frontend/src/surfaces/knowledge/navigation.js
• frontend/src/surfaces/knowledge/process-docs.js
• frontend/src/surfaces/knowledge/search.js
• frontend/src/surfaces/document-editor/changes.js
• frontend/src/surfaces/document-editor/lifecycle.js

Allowed test/evidence edits:

• frontend/test/knowledge-surface.test.mjs
• frontend/test/document-editor-surface.test.mjs
• frontend/test/frontend-architecture.test.mjs only if static ownership assertions must change
• backend/e2e/frontend-capabilities.json
• backend/scripts/frontend-capabilities.test.mjs only to append library-ready, local-draft-recovery, task-return-continuity, grouped-ready, partial-with-results, partial-empty, and retry-recovered to the existing process-docs expected-state suffix list; no other edit in this file is authorized
• one dedicated backend/e2e/issue-220-process-docs-search.spec.js
• existing canonical/parity journey files only when required to emit the new bounded state IDs through the normal reporter
• backend/scripts/sam-workspace-isolation.test.mjs only to replace the hard-coded root js-yaml path with package-scoped resolution of the workspace-owned dependency from backend/node_modules after clean npm ci; preserve root/tracked-input snapshots, import isolation, overlap checks, artifact identity, and process/leak checks; no fallback, probing chain, or dual resolution is authorized

Do not edit content/**, docs/** operational content, backend runtime/API/search/index code, fixtures outside the dedicated synthetic browser setup, capability reporter/schema machinery, shell/Home/account/team modules, or infrastructure. A newly required production path needs a PM amendment before editing.

Acceptance criteria

Library, reader, editor, and create

• The engineer posts a refreshed criterion-to-source/test inventory at the exact starting SHA before editing and classifies each item as already compliant, concrete gap, dependency-owned, or out of scope.
• /#/processes presents one dominant Process Docs library with an accurate visible count, active-filter state, semantically grouped native document actions, and either the first meaningful document or an honest empty/unavailable recovery action in the initial viewport.
• Reading is the default dominant document mode. Title and content lead; repository path and technical metadata are secondary; Edit is explicit; read/edit transitions preserve the exact document, scroll position, focus, warnings, links, backlinks, and unsaved values.
• Create has one clear heading and primary action, title-first reading order, an explicitly labelled repository-path field required by the current contract, retained entered values on validation/conflict/network failure, duplicate-submit prevention, and focus/announcement on the first useful error.
• Existing create/save/discard/rename/delete/API contracts and stale-request guards remain unchanged. No browser-only success, implicit publish, or provider action is introduced.

Local drafts and Task return context

• The library exposes the exact count of local drafts and a clear route/action to resume them; each draft is labelled local/unsaved and never represented as durable server state.
• Reader/editor state visibly distinguishes clean, local draft, saving, saved, validation failure, conflict, unavailable, and not found using Converge Wave A surfaces on bounded shared UI primitives #218 primitives and text/programmatic state rather than color alone.
• Save one/save all preserves failed and unrelated drafts, names saved/failed counts, prevents duplicate mutation, and retains retryable content and useful focus. Discard remains explicit and confirmed.
• A Process Doc opened from a Task retains that exact Task return context across internal links, related documents, backlinks, retry, not-found recovery, read/edit, refresh where the canonical route supports it, and browser Back/Forward.
• Back to Task reopens the exact originating Task through the canonical panel behavior and restores focus to a useful origin/return control; context clears only on explicit return or explicit departure from Process Docs. Existing Card return behavior does not regress.

Grouped search and honest states

• Search retains the exact query and active metadata filters through loading, partial failure, retry, and stale-response races, with no fixed-delay or test-order dependency.
• Results are grouped by existing type, ordered by existing relevance, expose an accessible group label/count and native result actions, and lead with safe human labels. Raw IDs, storage URIs, provider codes, and backend diagnostics are not routine metadata.
• When one source fails, successful groups remain fully actionable and the unavailable source is named with sanitized guidance. Zero matches is claimed only for sources that answered; partial-empty explicitly says unavailable sources may contain results.
• When all sources fail, no empty/zero/success result is fabricated; one retry action reruns the same query/filters, is busy/disabled during the request, and returns focus to the updated state.
• Empty query, query-empty, filter-empty, partial-with-results, partial-empty, full-unavailable, stale request, and retry-recovered states remain distinct in text, DOM state, and durable capability evidence.

Desktop, mobile, accessibility, and privacy

• At 1440×900, library/search use an intentional list/detail hierarchy; reader/editor/create have one dominant heading and one primary action per decision region; local draft and partial-source status is visible without overwhelming content.
• At 390×844, the flow is one pane; the first meaningful document/result/draft recovery action appears within the initial viewport after heading and essential controls; controls are at least 44×44 CSS pixels; no page-level horizontal scroll, clipping, overlap, squeezed desktop grid, or unreachable footer action exists.
• One main, correct heading nesting, native lists/actions/forms/dialogs, explicit labels/descriptions, aria-busy, appropriate status versus alert, visible focus, keyboard operation, focus restoration, 200% zoom, reduced motion, and light/dark tokens remain correct. Automated scans report zero critical/serious WCAG A/AA findings on every captured state.
• All source, tests, logs, screenshots, and issue comments use synthetic public-safe names and content. No raw SOP, workflow template, private link/contact, sponsor/finance fact, production identifier, credential-adjacent setup, provider payload, or generated operational artifact enters this public repository or public issue.
• No file under content/** is added or modified. Runtime operational knowledge remains sourced through the existing authenticated boundary backed by the separate private knowledge repository; this issue does not copy, seed, migrate, index, or publish that corpus.

Evidence and parity

• Focused production-module unit tests prove every changed state and regression, including context continuity and draft retention.
• A real-server Playwright journey covers library, reader, editor/create, Task return, drafts, grouped search, partial-with-results, partial-empty, full outage, and retry recovery without request interception, fixed sleeps, source-string assertions, incidental copy/whitespace pins, history-length arithmetic, broad 404 swallowing, serial fallout, or screenshot assertions.
• The successful full browser run emits passing evidence for every existing and new process-docs.* capability state for each declared role; screenshots or source inspection never substitute for runtime state evidence.
• Source, backend/dist, and packaged SAM frontend assets are identical for every changed asset; normal frontend parity passes with every capability/evidence record accounted for.

Test scenarios

Browse, read, edit, and create

Given an authenticated synthetic operator and a populated Process Docs catalog
When the operator opens /#/processes, filters the library, opens a document, enters and leaves edit mode, and starts a new document
Then one coherent hierarchy preserves route, document, values, scroll, focus, and exact server behavior at both widths

Resume local work safely

Given three synthetic local drafts where one save will fail
When the operator opens draft recovery and chooses Save all
Then successful drafts clear, the failed draft and its content remain, exact counts are announced, no duplicate write occurs, and discard still requires confirmation

Return to originating Task

Given a synthetic Task with a Process Doc and related internal documents
When the operator opens the doc from the Task, follows an internal link, encounters and retries a recoverable document failure, uses Back/Forward, and chooses Back to Task
Then the exact Task context remains visible throughout and the same Task reopens with useful focus

Grouped search with partial availability

Given synthetic Process Docs and work matches while one local search source is unavailable
When the operator searches and retries with active metadata filters
Then loaded groups stay actionable and relevance-ordered, unavailable-source copy is sanitized and explicit, no false zero appears, and the same query/filters recover without stale results

Private-knowledge boundary

Given the public repository diff, generated fixtures, screenshots, logs, and issue evidence
When Tester inventories content and identifiers
Then every record is synthetic/public-safe, content/** is untouched, and no private operational corpus or provider data is present

Source/SAM identity

Given the frozen accepted candidate and a clean SAM build
When the same Process Docs/search capability journeys run against source and packaged frontend targets
Then changed assets are byte-identical and every declared state/role produces matching normal parity evidence

Synthetic screenshot inventory

Capture exactly these 10 untracked native-size PNGs under .tmp/screenshots/issue-220/; remove stale extras before review:

• 01-library-ready-desktop-1440x900.png
• 02-library-ready-mobile-390x844.png
• 03-reader-task-return-desktop-1440x900.png
• 04-reader-task-return-mobile-390x844.png
• 05-editor-local-draft-failure-desktop-1440x900.png
• 06-editor-local-draft-failure-mobile-390x844.png
• 07-create-validation-desktop-1440x900.png
• 08-create-validation-mobile-390x844.png
• 09-search-partial-results-desktop-1440x900.png
• 10-search-partial-results-mobile-390x844.png

Use normal local TypeScript backend behavior and synthetic records only. Designer and Tester inspect every image at native resolution for hierarchy, state truth, readable labels, privacy, target size, focus visibility, overflow, clipping, overlap, and first-decision visibility. Screenshots are visual evidence only: do not commit them, attach them publicly, use them as behavior assertions, or treat them as source/SAM proof. Normal parity evidence supplies source/SAM behavior and asset identity.

Exact verification commands

Engineer may run narrower tests while iterating. Independent Tester runs the complete workflow below on one frozen diff/status/content fingerprint and records commands, exit codes, test counts, capability-state/role accounting, artifact hashes, and evidence paths:

node --check frontend/src/surfaces/knowledge/list.js
node --check frontend/src/surfaces/knowledge/navigation.js
node --check frontend/src/surfaces/knowledge/process-docs.js
node --check frontend/src/surfaces/knowledge/search.js
node --check frontend/src/surfaces/document-editor/changes.js
node --check frontend/src/surfaces/document-editor/lifecycle.js
node --test frontend/test/knowledge-surface.test.mjs frontend/test/document-editor-surface.test.mjs frontend/test/knowledge-menus.test.mjs frontend/test/frontend-architecture.test.mjs
npm run test:frontend:unit
npm run test:frontend:coverage
npm --prefix backend test
npm --prefix backend run typecheck
npm --prefix backend run build
node backend/scripts/verify-frontend-artifact.mjs --source frontend --artifact backend/dist
node --check backend/scripts/sam-workspace-isolation.test.mjs
(cd backend && npx playwright test e2e/docs-outage.spec.js e2e/issue-204-slice4-knowledge-feedback.spec.js e2e/issue-204-slice5-editor-feedback.spec.js e2e/issue-220-process-docs-search.spec.js --retries=0)
(cd backend && npx playwright test e2e/issue-218-shared-primitives.spec.js e2e/canonical-capability-behavior.spec.js e2e/canonical-task-workflow-behavior.spec.js e2e/issue-220-process-docs-search.spec.js --retries=0)
DATAOPS_CAPABILITY_COVERAGE=1 npm --prefix backend run test:e2e -- --retries=0
npm --prefix backend run test:e2e:frontend-parity
make sam-validate
make sam-build
node backend/scripts/verify-frontend-artifact.mjs --source frontend --artifact .aws-sam/build/BackendFunction
npm ci && make test-sam-workspace-isolation
make ci
git diff --check
git status --short

The two focused browser recipes run from backend/ with direct npx playwright test, --retries=0, and no DATAOPS_CAPABILITY_COVERAGE. Their exit-zero result proves only the named focused journeys. The full DATAOPS_CAPABILITY_COVERAGE=1 npm --prefix backend run test:e2e -- --retries=0 command is the sole 154-state completeness gate and remains mandatory.

After any repair, SWE must regenerate exactly the ten #220 screenshots, rerun the complete workflow from a fresh npm ci, remove generated artifacts, and post new HEAD/diff/status/content/screenshot fingerprints. Designer, independent Tester, and PM then review that same refrozen candidate. The unresolved product repairs remain: hide Save/Discard in read mode, render one Type selector, and expose one mobile notification/account chrome set on Create.

The dedicated #220 spec must run inside the normal full browser command. Existing behavior suites remain authoritative for unchanged states. Do not execute import/export/migration/restore scripts, use provider credentials, or run production-data operations.

Lifecycle gates

• PM inventory completed read-only at 78e9122
• Accepted Restore behavior-based browser coverage and fix canonical UI accessibility races #180/Finalize the canonical scan-first Operations Home #161 foundations and PM-groomed Converge Wave A surfaces on bounded shared UI primitives #218 reconciled
• Converge Wave A surfaces on bounded shared UI primitives #218 receives Designer PASS, independent Tester PASS, PM acceptance, and an exact commit, or the Orchestrator records reviewed proof that Converge Process Docs and search operator flows #220 is path-disjoint
• Orchestrator records the exact Converge Process Docs and search operator flows #220 starting SHA and resolves every concurrent shared-path writer
• Narrow PM amendment authorizes only the seven groomed process-docs expected-state suffixes in backend/scripts/frontend-capabilities.test.mjs; Restore canonical frontend behavior coverage and SAM parity gates #159 schema/reporter/roles/routes/API boundaries and ownership remain unchanged
• Software Engineer posts the refreshed gap inventory, implements only unmet criteria, and posts frozen fingerprints plus READY FOR TEST
• Tester-blocker PM amendment authorizes only package-scoped backend js-yaml resolution in the SAM workspace verifier, corrects focused Playwright recipes, retains the full 154-state completeness gate, and requires a full refreeze after the three blocking Designer repairs
• Designer inspects exactly 10 native-size screenshots and posts DESIGN PASS on the frozen fingerprint
• Independent Tester verifies every criterion, full command workflow, capability coverage, privacy inventory, and source/SAM parity and posts TESTER PASS on the same fingerprint
• PM performs user-perspective acceptance and posts ACCEPTED on the same fingerprint
• Software Engineer commits only accepted issue-owned paths with Closes #220
• Orchestrator merges locally in the recorded Replace the transitional Tasks table with the final cardId schema #166-safe publication order and pushes main
• On-Call verifies CI/CD, deployment, source/SAM identity, and smoke evidence before Converge Process Docs and search operator flows #220 is called shipped or closed

No HUMAN gate is required for this local, synthetic, provider-free slice.

No-backcompat boundary

• Replace an obsolete presentation/interaction shape everywhere in this bounded surface and delete it in the same change.
• Do not add alias-only selectors, dual old/new result markup, compatibility shims, legacy route/query fallbacks, duplicate draft stores, dual-read/dual-write behavior, deprecated fields, or permanent migration guards.
• If the existing frontend contract cannot meet a criterion without an API/schema/storage change, stop and file/amend a separate backend issue; do not simulate the missing contract in the browser.

Explicit exclusions

• Raw operational content, SOPs, workflow templates, private screenshots/links/contacts, production identifiers, sponsor/finance context, provider payloads, and generated operational artifacts.
• Any edit under content/**, backend runtime/API/data/search/index code, DynamoDB, persisted schemas, infrastructure, AWS, OIDC, private-knowledge repository, backups, migrations, imports, restores, exports, or source-system repositories.
• Home, shell information architecture, account/team identity, owner selection, Users/Admin, notifications, mobile drawer, global navigation, Task/Card authorization or lifecycle, Assistant/Artifact behavior, and provider actions.
• Search relevance algorithm changes, new result types, new APIs, new persisted fields, corpus indexing/movement, or server-side permission work.
• Broad CSS cleanup, stylesheet split, framework/component-library adoption, router/runtime rewrite, new global token vocabulary, or redesign outside the bounded Process Docs/search paths.
• Commit/push/deploy/provider/HUMAN activity during implementation or review; those occur only at their explicit lifecycle stage.

[alexeygrigorev]

PM GROOMED — agent-ready Wave A slice

Groomed read-only from clean baseline 78e9122 after reconciling parent #162, accepted #180/#161 foundations, and PM-groomed #218.

Bounded outcome: converge only the existing Process Docs library/reader/editor/create flow, local-draft recovery, exact Task return context, grouped search presentation, and partial-source honesty. The issue inventories current compliant source/tests and limits implementation to concrete gaps: dominant browsable library hierarchy, native row/group semantics, intentional read-to-edit hierarchy, library-visible local drafts, Task context continuity across document navigation/recovery, human-first boundary-safe metadata, and durable real-server capability/source-SAM evidence.

Implementation is sequenced after #218 by default because shared styles, knowledge modules, focused tests, and browser evidence overlap. An earlier start requires the Orchestrator to record exact path-disjoint proof. The issue includes exact production/test write ownership, ten synthetic public-safe screenshots, desktop/mobile/accessibility behavior, complete verification commands, lifecycle gates, a no-backcompat boundary, and explicit exclusions for operational content, backend/data/search-index changes, Home/shell/account/team identity, providers, infrastructure, and broad CSS work.

Labels are final and needs grooming is removed. No repository file, worktree, commit, push, deploy, provider, or HUMAN action was performed.

[alexeygrigorev]

SWE criterion-to-current-source/test inventory — exact accepted starting SHA

Pre-edit inventory completed against clean branch issue-220-process-docs-search at exact HEAD/base 9d204d208820e3d842a3d3fc83493c230bcadaa5 (tree e3e1633f5324e74caa259989b9d3fbec31447859). This is the requested accepted chain: #218 commit 0c89588df809b2e84af02e796d1910a25eea0165, followed by accepted #219 commit 9d204d208820e3d842a3d3fc83493c230bcadaa5. The worktree has zero tracked, untracked, staged, or unmerged changes. #219 is fully contained in the base; no concurrent writer owns this #220 worktree or candidate path set.

Already compliant — preserve, do not rebuild

Criterion	Exact current production source	Current proof	Treatment
Canonical library/filter/deep-link contracts and stale/unavailable distinction	frontend/src/surfaces/knowledge/process-docs.js, list.js, filters.js, navigation.js	frontend/test/knowledge-surface.test.mjs covers catalog loading, filtering, URL round trips, stale responses, empty/outage, and exact document open; canonical real-server journeys retain route behavior	Preserve routes, query shape, load guards, filters, and destinations
Existing reader/editor/create lifecycle	knowledge/navigation.js plus document-editor/lifecycle.js retain guarded load/create/save/discard, structured/raw rendering, warnings, and entered values	Knowledge/editor unit suites and canonical browser journey cover read/create/edit, not-found, save failure/retry, and stale load behavior	Change hierarchy, semantics, and focus only; no API/lifecycle expansion
Durable per-path local drafts and partial save ownership	document-editor/lifecycle.js::draftKey/listDraftPaths/storeDraft; changes.js::refreshChangesPanel/saveAllDrafts/discardAllDrafts	frontend/test/document-editor-surface.test.mjs covers local retention, save one/all, partial failure, confirmation, rename/delete cleanup, and guarded mutations	Reuse the one store and mutation guards; expose it from the library without a second state model
Existing Task/Card return affordance	knowledge/navigation.js::renderDocReturnContext; Task/Card callers pass typed return context to openDocument	Knowledge tests cover direct Task return and missing-document recovery	Preserve Card behavior; repair Task continuity only where context is currently cleared by knowledge-internal navigation
Existing grouped relevance and canonical destinations	knowledge/search.js maps/ranks existing Tasks, Cards, Templates, Process Docs, Artifacts, Files, and Assistant Jobs	Knowledge tests cover grouping, ranking, filters, destination routing, exact doc open, and stale-query rejection	Preserve result types, ordering algorithm, API/query contracts, and destinations
Partial/full outage state model and same-input retry	search.js::searchStateFor/renderSearchSourceState distinguishes partial results, partial empty, full unavailable, query/filter empty, and retry	Knowledge unit tests cover named unavailable sources, retained successful groups, retry, and empty states	Preserve state distinctions and same query/filter retry; sanitize routine copy and add real-server capability evidence
Accepted #218 shared primitives	frontend/src/styles.css; Process Docs/search already use surface-page-header, surface-action-row, surface-section-frame, honest-state, and status-label in their current bounded presentation	Accepted #218 focused/unit/browser/parity evidence is contained in 0c89588; current knowledge unit assertions cover the shared classes	Extend only the #220 Process Docs/search selectors; do not create a parallel primitive or alter excluded surfaces
Existing capability identity and parity plumbing	backend/e2e/frontend-capabilities.json and canonical-capability-behavior.spec.js own existing process-docs.* states and normal reporter/parity behavior	#159 capability checks and current source/SAM parity suite	Add only distinct #220 states and use the existing reporter/schema; no machinery changes

Concrete gaps owned by #220

1. renderDocsSurface still makes quality/reference material dominant instead of presenting the complete filtered catalog as one labelled library with accurate count/filter truth and a visible first meaningful row or recovery action.
2. list.js still uses article[tabindex=0] plus custom Enter/Space emulation, and grouped search rows lack native list semantics and programmatic group counts.
3. Reader mode still gives repository path/editing chrome too much weight; entering edit must become intentional while preserving document, scroll, warnings, links/backlinks, focus, and unsaved values.
4. Drafts remain discoverable mainly inside Pending Changes. The library needs the exact local-only count/resume entry, and reader/editor needs explicit clean/local/saving/saved/failure state language without claiming server durability.
5. openDocument currently executes knowledgeState.docReturnContext = options.returnContext || null; internal links, related docs, backlinks, and search therefore erase an originating Task. Preserve the exact Task context through knowledge-internal navigation/retry/not-found/read-edit/history until explicit return/departure, while leaving Card semantics unchanged.
6. Rows and source-state copy still promote paths/opaque IDs and interpolate raw source error strings. Results must lead with authenticated human labels and stable sanitized consequences, with paths secondary only where required.
7. Partial/grouped search is unit-covered but lacks distinct real-server process-docs.* states for grouped ready, partial-with-results, partial-empty, full outage, and retry recovery through normal capability/source-SAM parity accounting.
8. The bounded library/reader/editor/create/search layouts still need Converge Wave A surfaces on bounded shared UI primitives #218-aligned desktop/mobile convergence so the first meaningful row/draft recovery/partial result is visible initially, controls remain 44px on mobile, and no horizontal overflow or unreachable action remains.

Dependency-owned — preserve exactly

• Converge Wave A surfaces on bounded shared UI primitives #218: shared page-header, action-row, form/footer, semantic status, honest-state, token, and responsive primitives.
• Converge Templates and Recurring operator flows #219: accepted Template/Recurring behavior and its contained shared-style cascade.
• Restore behavior-based browser coverage and fix canonical UI accessibility races #180/Finalize the canonical scan-first Operations Home #161: shell, global search focus, mobile drawer, route/history foundations, notifications, and Home isolation.
• Show signed-in identity and authorized teammates’ Task/Card work #164: identity, selected owner, teammate authorization, Task visibility/attribution, Users/Admin, and delegated actions.
• Make assistant output review safe and lifecycle-complete #158: Assistant/Artifact lifecycle, access, review, archive, and rehydration.
• Restore canonical frontend behavior coverage and SAM parity gates #159: capability schema, collector/reporter, evidence policy, and source/SAM parity machinery.
• Existing authenticated backend docs/search/index contracts and the private knowledge storage boundary.

Out of scope / untouched

• content/**, raw SOPs/workflow templates, private links/contacts, production/provider facts, generated operational artifacts, and the private knowledge repository.
• Backend runtime/API/search/index/data contracts, fixtures outside the dedicated synthetic Converge Process Docs and search operator flows #220 browser setup, DynamoDB, schemas, infrastructure, AWS/OIDC, providers, migrations/import/export/restore, and source repositories.
• Home/shell/navigation/account/team/Show signed-in identity and authorized teammates’ Task/Card work #164, Task/Card authorization or lifecycle, Make assistant output review safe and lifecycle-complete #158 Assistant/Artifact behavior, search relevance/new result types, broad CSS cleanup, router/framework/token rewrites, and compatibility layers.

No production or test file has been edited, staged, committed, merged, pushed, deployed, or sent to a provider at this point. Implementation will stop for a PM amendment if the bounded write set cannot satisfy a criterion.

[alexeygrigorev]

SWE BLOCKED — narrow PM amendment required for authoritative regression paths

Implementation paused exactly as the groomed issue requires when a path/contract conflict appears.

Exact candidate state

• Branch/base remains issue-220-process-docs-search at 9d204d208820e3d842a3d3fc83493c230bcadaa5.
• Current candidate has 10 allowed paths only: the eight production paths plus frontend/test/knowledge-surface.test.mjs and frontend/test/document-editor-surface.test.mjs.
• Nothing is staged, committed, merged, pushed, deployed, sent to a provider, or advanced through a HUMAN gate.
• Syntax and git diff --check pass.
• Current focused production-module workflow passes 57/57 after adding bounded regression coverage for native library actions, local-only draft recovery, human-safe failures, exact Task return context through internal navigation/history/retry, and explicit read-to-edit intent.

Conflict

#220 explicitly requires sanitized search/document failure guidance, no raw backend diagnostics in routine presentation, and intentional entry into editing. Three authoritative real-server E2E files outside the exact allowed test write set assert the obsolete behavior:

1. backend/e2e/docs-outage.spec.js
   • requires the raw Docs content root is unavailable: ... DTC_CACHE_ROOT diagnostic in Process Docs, grouped search, and bookmarked-reader UI;
   • requires the old top-level outage ordering/selector instead of the new library-owned honest state;
   • specifically requires each unavailable search source row to interpolate the raw backend message.
2. backend/e2e/issue-204-slice4-knowledge-feedback.spec.js
   • requires Synthetic route failure (503) in a document-unavailable reader state.
3. backend/e2e/issue-204-slice5-editor-feedback.spec.js
   • enters inline editing by clicking document content without first choosing Edit document;
   • requires Synthetic route failure (503) in the editor live region after save failure.

Keeping those assertions true would require a compatibility branch that leaks raw diagnostics and preserves implicit editing, directly contradicting #220’s acceptance and no-backcompat boundary. Updating them without PM authorization would violate the exact write set.

The already-authorized “existing canonical/parity journey files” allowance is sufficient for the corresponding stale assertions in canonical-capability-behavior.spec.js and canonical-task-workflow-behavior.spec.js; it does not cover the three issue-specific files above.

Requested narrow amendment

Authorize assertion/journey-only edits to exactly:

• backend/e2e/docs-outage.spec.js
• backend/e2e/issue-204-slice4-knowledge-feedback.spec.js
• backend/e2e/issue-204-slice5-editor-feedback.spec.js

The edits would only:

• preserve outage-vs-empty, disabled-editor, retained-draft, same-query retry, and real-server behavior;
• replace raw diagnostic expectations with stable operator-safe consequence/recovery copy and explicit negative checks for the raw payload/status/path;
• update the Process Docs library-owned outage selector/hierarchy;
• choose Edit document before inline edits;
• retain all existing source/SAM, focus, pending, retry, screenshot, and HTTP-failure accounting.

No fixture, API, route, backend, provider, content, capability machinery, screenshot inventory, or production path expansion is requested. After amendment, SWE will update only these assertions/journey steps, add the dedicated #220 capability journey, refreeze, and run the complete required workflow.

[alexeygrigorev]

PM AMENDMENT — migrate authoritative #204 regression contracts with #220

Decision: approved, narrowly.

I reconciled the groomed #220 contract and parent #162 sequencing with the SWE conflict report, the current assertions in all three named specs, and the accepted #204 Slice 4 and Slice 5 behavior. The conflict is real: keeping the current raw-diagnostic and implicit-edit assertions would require #220 either to violate its boundary-safe/intentional-editor acceptance criteria or to add a compatibility branch. Neither is allowed.

These files remain authoritative regression owners for the behavior accepted under #204. Updating their expected public contract does not transfer #204 behavior ownership to #220 and does not reopen #204. #220 may migrate only the assertions and journey entry needed for its new safe presentation and explicit reader-to-editor intent while retaining every owning-surface invariant below.

Exact write-ownership amendment

Add exactly these three test-only paths to #220's allowed test/evidence write set:

• backend/e2e/docs-outage.spec.js
• backend/e2e/issue-204-slice4-knowledge-feedback.spec.js
• backend/e2e/issue-204-slice5-editor-feedback.spec.js

No additional production, fixture, helper, reporter, schema, backend, content, or infrastructure path is authorized by this amendment.

Allowed changes

backend/e2e/docs-outage.spec.js

Only for the Process Docs library, unified-search, and bookmarked-document portions of the existing journeys:

• update selectors/order assertions to the Converge Process Docs and search operator flows #220 library-owned honest-state hierarchy;
• replace positive assertions for backend paths, environment-variable names, raw messages, status text, or other diagnostics with stable operator-safe consequence/recovery assertions;
• add explicit negative UI assertions proving raw payload/path/status details are absent;
• continue to distinguish outage from answered-empty;
• continue to name the unavailable source, retain successful search groups, preserve the same query/filters, expose one usable retry, and prove recovery;
• retain the real 503 observation/accounting so the journey cannot pass against a healthy server.

The Home portion is dependency-owned and excluded from #220. Do not rewrite Home behavior or use this amendment to change its production contract. A mechanically shared test-local constant may be split only where needed to express the Process Docs/search assertions without changing the Home journey.

backend/e2e/issue-204-slice4-knowledge-feedback.spec.js

Only for the accepted single-document unavailable/retry contract:

• replace Synthetic route failure (503) with stable operator-safe unavailable/recovery expectations;
• add a negative assertion that the raw synthetic route message/status is not rendered;
• update a selector only if Converge Process Docs and search operator flows #220's intentional reader hierarchy requires it.

Preserve the accepted Slice 4 ownership and behavior: loading/not-found/unavailable remain distinct; the document editor remains disabled until a successful document response; a direct document failure does not poison catalog availability; retry remains visible and restores the document; stale-response protection, focus/keyboard behavior, partial-search success retention, same-query retry, HTTP-failure accounting, mobile containment, and existing source/SAM evidence remain intact.

backend/e2e/issue-204-slice5-editor-feedback.spec.js

Only for explicit edit intent and safe editor-owned failure feedback:

• choose the visible Edit document action before every inline-edit interaction that currently begins by clicking rendered document content, including the stale-save journey;
• replace the raw Synthetic route failure (503) expectation with stable operator-safe save-failure guidance;
• add a negative assertion that raw route/status details are not rendered;
• update selectors only where required by the explicit read/edit lifecycle.

Preserve the accepted Slice 5 ownership and behavior: save feedback remains in #editor-inline-status; blocking failure remains an assertive alert; the valid local draft and unsaved values remain; save controls recover correctly; focus returns to a useful editor-owned state; pending and success states remain polite; duplicate-submit protection, authoritative refresh, route/entity freshness, stale-save rejection, keyboard Escape/Ctrl+Enter behavior, dirty-document confirmation, and mobile containment remain covered. Do not move feedback into a global banner/toast or create another writer.

Test-local expected-copy constants or forbidden-diagnostic sentinels may be adjusted solely for these assertions. The synthetic documents, fault routes, response statuses/delays, authenticated role, screenshot locations/counts, and server setup are not authorized for semantic change.

Prohibited changes

• No rewrite of these specs, no deletion or weakening of accepted Own visible feedback in each workspace surface #204 scenarios, and no ownership transfer to the dedicated Converge Process Docs and search operator flows #220 spec.
• No change to API routes, fault meaning, backend responses, search relevance/result types, document mutation semantics, capability reporter/schema, source/SAM machinery, or browser interception policy.
• No compatibility alias, dual assertion, raw-detail fallback, source-string pin, broad 404 swallowing, fixed sleep, history-length arithmetic, or test-order dependency.
• No raw operational knowledge, private link/contact, provider payload, production identifier, credential-adjacent detail, or generated operational artifact in source, fixtures, screenshots, logs, or issue evidence.
• No changes to Home, shell, identity/team, Task/Card authorization/lifecycle, Converge Wave A surfaces on bounded shared UI primitives #218/Converge Templates and Recurring operator flows #219 behavior, or any path outside Converge Process Docs and search operator flows #220's original write set plus the three test paths above.

Acceptance-command amendment

No existing #220 command or evidence requirement is removed or weakened. Add syntax checks for the three amended specs and run this focused real-server regression command during implementation and independent Tester verification:

node --check backend/e2e/docs-outage.spec.js
node --check backend/e2e/issue-204-slice4-knowledge-feedback.spec.js
node --check backend/e2e/issue-204-slice5-editor-feedback.spec.js

DATAOPS_CAPABILITY_COVERAGE=1 npm --prefix backend run test:e2e -- \
  e2e/docs-outage.spec.js \
  e2e/issue-204-slice4-knowledge-feedback.spec.js \
  e2e/issue-204-slice5-editor-feedback.spec.js \
  e2e/issue-220-process-docs-search.spec.js \
  --retries=0

The full DATAOPS_CAPABILITY_COVERAGE=1 npm --prefix backend run test:e2e -- --retries=0, full frontend unit/coverage, backend test/typecheck/build, artifact identity, parity, SAM, isolation, make ci, diff/status, exact ten-image #220 inventory, privacy inventory, and native Designer/Tester inspection remain mandatory on one frozen fingerprint.

Refreeze authorization

SWE is authorized to continue from exact base 9d204d208820e3d842a3d3fc83493c230bcadaa5, update only the original #220 paths plus these three test files as bounded above, complete the dedicated #220 capability journey, regenerate exactly the ten required #220 screenshots, and post a fresh frozen diff/status/content fingerprint with terminal command evidence.

The current 57/57 focused result is useful implementation evidence but is not a review verdict. After refreeze, the normal Designer → independent Tester → PM acceptance gates run on the same fingerprint. No commit, merge, push, deploy, provider action, or HUMAN gate is authorized at this stage.

PM AMENDMENT APPROVED — resume implementation and refreeze.

[alexeygrigorev]

SWE STOP — exact write-path amendment required

The mandated backend gate now fails because #220 adds the seven groomed Process Docs capability states to backend/e2e/frontend-capabilities.json, while backend/scripts/frontend-capabilities.test.mjs owns an exact hard-coded Process Docs state-ID allowlist.

Observed isolated failure:

• command: node --test backend/scripts/frontend-capabilities.test.mjs
• result: 4 passed, 1 failed
• assertion: process-docs state coverage drifted
• rejected required IDs: library-ready, local-draft-recovery, task-return-continuity, grouped-ready, partial-with-results, partial-empty, retry-recovered

The current exact write set names backend/e2e/frontend-capabilities.json, but not backend/scripts/frontend-capabilities.test.mjs, and excludes capability reporter/schema machinery. Per the stop-on-path-conflict rule, SWE has not edited this file or continued gates.

Requested minimal amendment: authorize only backend/scripts/frontend-capabilities.test.mjs to extend its existing process-docs expected-state suffix list with those seven already-groomed IDs. No reporter/schema behavior, routes, APIs, roles, or ownership changes.