Converge canonical DataOps surfaces on one operator design system

Converge canonical DataOps surfaces on one operator design system

Status: in progress — Wave A #218–#221 are accepted and committed locally/unpushed; #222 is held at immutable checkpoint 65fb9a8392ed76cc55e74a9b783e352914169411 with final verification and Designer/Tester/PM reviews pending; nothing is shipped
Tags: enhancement, portal, frontend, testing, design, P1
Depends on: #180 is complete on baseline 78e9122; #161 is accepted/integrated locally but unpushed; accepted #164 (3e835a19017da18f2177d81fb7e084764970dee3) and #158 (8839fcfb39a3553a673d395a7b3746e2c92218cd) remain on held branches pending reviewed integration; #222 final gates and #166-safe release sequencing remain open
Blocks: serialized Wave A children #218–#222, dependency-coupled Wave B slices, and final integrated design-system acceptance
Next owner: #222 Software Engineer after the documented quiescence prerequisite, then fresh Designer → independent Tester → PM review on immutable checkpoint 65fb9a8392ed76cc55e74a9b783e352914169411; Orchestrator release integration only after acceptance, preserving the reviewed containing sequence and #166 gates
Implementation baseline: clean local 78e9122 contains accepted #180 and #161. Serialized Wave A then records accepted local commits #218 0c89588df809b2e84af02e796d1910a25eea0165 → #219 9d204d208820e3d842a3d3fc83493c230bcadaa5 → #220 d334020ca5a582d31a81b371988169cab4e7f6b2 → #221 8c3b110c8aa138d95385a89fe3328749bdf47250, followed by #222 immutable checkpoint 65fb9a8392ed76cc55e74a9b783e352914169411. All are local/unpushed and unshipped; #158/#164 remain accepted held branches. Release integration must preserve reviewed containing order and cannot claim shipped before push plus source CI/On-Call evidence.

Product outcome

DataOps feels like one internal operations system, not a collection of imported products. Every canonical surface helps an operator answer:

1. What needs attention now?
2. What is the next safe action?
3. What process, relationship, evidence, or history is relevant?
4. What already happened?
5. What can automation prepare for review?

This is now a convergence epic over the existing canonical TypeScript-backed frontend. It is not authorization to build a second shell, replay prototype branches, replace the router, introduce a framework, invent browser-only behavior, or redesign all surfaces in one change.

Reconciled current state

The original epic assumed most surface work was still greenfield and globally blocked on #156 → #159 → #158 → #161. That is stale:

• #156 and #159 are closed and their canonical route, behavior, artifact, and source/SAM parity foundations are already integrated.
• Clean local baseline 78e9122 has one top-level frontend, one canonical route contract, the Today/Home direction, account and selected-owner composition, and modular shell, runtime, Home, work detail, operations, task, finance, planning, knowledge, and admin surfaces.
• Existing prototypes and subsequent module/coverage commits are current-source inputs, not automatically accepted #162 deliverables. Each slice must map this issue's criteria to production modules and behavior tests before proposing code.
• #180 Stage 0 is closed and complete through reconstructed accepted increments e684162 and b045739, both present on clean local baseline 78e9122.
• Wave A #218–#221 are accepted and committed in one serialized local chain: 0c89588 → 9d204d2 → d334020 → 8c3b110. #222 is the current immutable checkpoint 65fb9a8; final verification and fresh Designer, independent Tester, and PM reviews remain pending. Every Wave A commit is unpushed and unshipped.
• #161 is accepted and integrated into local baseline 78e9122, but that integration is unpushed and not shipped. #162 preserves its accepted result.
• #164 is accepted and committed at 3e835a19017da18f2177d81fb7e084764970dee3 on a held branch, but is not integrated or pushed; slices 7–8 remain gated until reviewed integration.
• #158 is accepted and committed at 8839fcfb39a3553a673d395a7b3746e2c92218cd on a held branch, but is not integrated or pushed; slice 9 remains gated until reviewed integration.
• #166 gates coordinated publication/production sequencing, not read-only grooming or later isolated local implementation. No #162 slice may push an ahead-of-origin chain or claim shipped before its containing reviewed integration reaches origin and source CI/On-Call completes.

Historical prototype branches are not implementation baselines. The reviewed local containing sequence is 78e9122 → #218 0c89588 → #219 9d204d2 → #220 d334020 → #221 8c3b110 → #222 checkpoint 65fb9a8. The #222 checkpoint is not accepted; final verification and reviews remain. No commit in this sequence is pushed or shipped.

Design grammar

• One shell and route contract. Keep one DataOps identity, desktop sidebar, mobile shell/drawer, shared authenticated session, and canonical hash routes. No domain creates another shell, entry point, router, or navigation model.
• One dominant operator question. Lead with the queue, decision, or selected object. Avoid equal-weight dashboard collections and hide document controls outside Process Docs.
• One primary action per decision region. Secondary actions stay quiet. Destructive or provider-adjacent actions are separated, precisely named, confirmed, and never implied to have occurred before authoritative success.
• Consistent detail ownership. Desktop may use intentional list/detail. Mobile uses one pane and canonical history/return behavior. Entity details order identity, relationship, evidence, activity, then state-valid action.
• Human labels first. Resolve safe display names and Card/Task/process/artifact labels. Use semantic Europe/Berlin dates. Do not expose routine raw IDs, provider codes, storage paths, metadata, emails, or reason codes.
• Progressive density and shared primitives. Queue rows carry only decision fields. Details own history/evidence/diagnostics. Reuse tokens, headers, queue rows, status strips, tabs, sheets/dialogs, forms, responsive cards, skeletons, toasts, and honest-state components.
• One honest-state language. Loading, empty, unavailable, partial failure, validation, conflict, forbidden, not found, retrying, success, and destructive confirmation are explicit. A failed source is unavailable, never zero; successful sources remain usable.
• Public-safe evidence. Tests, fixtures, screenshots, comments, and logs use synthetic records only. No operational corpus, private link/contact, sponsor or finance fact, production identifier, credential-adjacent note, or generated operational artifact enters this public repository or issue.

Dependency partition

Dependency	What it gates	What it does not gate
#180 complete: accepted increments e684162 and b045739 on clean baseline 78e9122	Wave A implementation is now eligible; the baseline supplies common focus, refresh, recurring semantics, browser diagnostics, and behavior assertions	Nothing remains blocked on #180
#161 accepted and integrated locally at 78e9122, unpushed	Today/Home and shell slice 6 may build on the reviewed local integration, but cannot claim shipped status before push/source gates	Wave A domain-surface gap work that leaves Home/account/navigation untouched
#164 accepted branch commit 3e835a19017da18f2177d81fb7e084764970dee3, integration pending	Teammate-aware Inbox/Task/Card execution; Users/access management; owner filters/deep links; identity/team projections; delegated-action authorization	Wave A work; slices 7–8 stay gated until reviewed integration
#158 accepted branch commit 8839fcfb39a3553a673d395a7b3746e2c92218cd, integration pending	Assistants and Artifacts review/lifecycle/access redesign	Wave A work; slice 9 stays gated until reviewed integration
#166 repaired rollout	Merge/push/deploy/On-Call ordering for accepted local work	Local PM grooming and later isolated implementation/review
#159 complete	Durable capability map and source/SAM parity contract used by every slice	Nothing remains blocked on #159

If a slice discovers a missing API, persisted field, permission rule, or lifecycle contract, stop and amend/file a separate backend issue. #162 does not authorize compatibility shims, dual behavior, migration machinery, imports, restores, or browser-only simulated success.

Staged implementation slices

This epic is a tracker and final acceptance gate. Do not implement it as one mega-change. Child issues are raw intake first, then separately PM-groomed and lifecycle-gated.

Stage 0 — complete

• #180 passed independent Tester review, received PM acceptance, and closed through accepted increments e684162 and b045739.
• Clean local 78e9122 records the reviewed containing integration as the common baseline.
• Wave A implementation remained held until this gate completed.

Wave A — accepted through #221; #222 final verification pending

Children #218–#222 are filed and PM-groomed. #218–#221 completed their required reviews and are committed locally/unpushed in serialized order as 0c89588 → 9d204d2 → d334020 → 8c3b110. #222 is held at immutable checkpoint 65fb9a8; its final verification and fresh Designer, independent Tester, and PM reviews remain pending. These slices do not wait for #158, #161, or #164, provided their PM scope explicitly excludes Home, account/team scope, global navigation, accepted #180 behavior, and missing backend contracts.

1. #218 — Shared visual primitives inventory and bounded convergence — accepted; committed locally/unpushed as 0c89588df809b2e84af02e796d1910a25eea0165. Audit current tokens and existing primitives; consolidate only proven duplication needed by Wave A surfaces. No shell IA, account, Home, routing, or broad CSS rewrite.
2. #219 — Templates and Recurring — accepted; committed locally/unpushed as 9d204d208820e3d842a3d3fc83493c230bcadaa5. Converge list/editor, clean/dirty/saving/validation/conflict states, mobile disclosure, pause/resume, and safe delete/409 guidance while preserving canonical Template/Card/Task contracts and #180 recurring semantics.
3. #220 — Process Docs and search — accepted; committed locally/unpushed as d334020ca5a582d31a81b371988169cab4e7f6b2. Converge library/reader/editor/create, local drafts, Task return context, grouped result presentation, and partial-source honesty. Operational knowledge remains in the private knowledge repository.
4. #221 — Bookkeeping and Sponsors — accepted; committed locally/unpushed as 8c3b110c8aa138d95385a89fe3328749bdf47250. Converge Ledger/Evidence/Monthly package and Sponsor Overview/Finance/Communications/History presentation using existing authenticated contracts. No live payment, provider send, migration, import, or data-model expansion.
5. #222 — Newsletter, Calendar, and Mailing Exports — immutable checkpoint 65fb9a8392ed76cc55e74a9b783e352914169411; final verification and fresh Designer/Tester/PM reviews pending. Converge chronological planning, desktop calendar/mobile agenda, overlay/unavailable states, and explicit Wait/Retry/Fix authorization/Download language while preserving accepted #108/#134 behavior.

Wave A remains serialized in one reviewed containing chain. #218–#221 are accepted and locally committed but unpushed/unshipped. #222 is the current immutable checkpoint, not an accepted candidate; after its final verification and fresh reviews, the Orchestrator must preserve the containing order through coordinated #166-safe integration, push, and On-Call verification.

Wave B — dependency-coupled

6. Today and shared shell integration — #161 accepted/integrated locally, publication pending. Integrate the accepted scan-first Home with contextual desktop/mobile navigation and shared state primitives. Preserve #161 queue priority/count/state/evidence and #180 focus behavior. Do not implement teammate authorization here.
7. Inbox, Task, and Card execution — after reviewed integration of accepted #164 commit. Apply compact queues, state-aware details, relationships/evidence/activity, mobile one-pane flows, mismatch/not-found, retry-safe errors, and the accepted safe owner/team contract. Preserve #179 Task concurrency and #168 Card lifecycle.
8. Admin, Users, Settings, and system feedback — after reviewed integration of accepted #164 commit. Converge identity, appearance, version, sign-out, role-aware user management, small health/action hub, notifications, dialogs, and toasts without exposing the administrative /api/users projection as a general teammate directory.
9. Assistants and Artifacts — after reviewed integration of accepted #158 commit. Apply review-first inputs/output/artifacts/activity, safe approval language, needs-review/archive separation, authoritative lifecycle rehydration, and mediated access without changing #158 lifecycle or permission guarantees.

#161 is accepted and integrated locally, so slice 6 is dependency-eligible on that reviewed local baseline but remains subject to Wave A serialization and publication gates. Slices 7–8 remain blocked until accepted #164 is reviewed and integrated; slice 9 remains blocked until accepted #158 is reviewed and integrated.

Wave C — integrated acceptance

10. Cross-surface accessibility, responsive, route, and source/SAM audit. Start only after accepted slices 1–9 are integrated. Repair only integrated design-system regressions; do not hide child-slice failures in a final mega-patch.

Per-slice acceptance contract

Every child issue must:

• Post a criterion-to-current-production-source/test inventory before implementation, classifying each item as already compliant, concrete gap, dependency-owned, or out of scope.
• Preserve the one canonical frontend, route/deep-link/history/close-return contract, shared login/logout, and source/SAM asset identity.
• Implement only concrete gaps in current modular files. Do not replay old prototype commits or restore monolithic frontend code.
• Preserve exact selected entity, relationship context, entered retryable values, authoritative server state, and useful focus through loading, validation, conflict, non-404 failure, stale/not-found, close, Back, and Forward.
• At 1440x900 provide one dominant column or intentional master/detail; at 390x844 provide intentional cards/agenda/one-pane detail, 44px touch targets, and no overflow, clipping, overlap, or unreachable action.
• Provide correct landmarks/headings/list or table semantics, names/descriptions, live/busy/error state, visible focus, keyboard operation, focus trap/restoration, reduced motion, light/dark tokens, and zero critical/serious WCAG A/AA findings on changed states.
• Use normal local TypeScript backend behavior and synthetic public-safe records. Core success behavior cannot rely on request interception, source-string assertions, fixed sleeps, history-length arithmetic, serial fallout, broad 404 swallowing, exact incidental copy/whitespace, byte pins, or screenshot pixel goldens.
• Add/update focused production-module unit tests, behavior-level real-server browser journeys, and durable #159 capability pointers for exact changed states.
• Prove source and packaged SAM frontend parity for changed routes/assets.
• Capture and inspect only the child issue's exact desktop/mobile ready and critical state screenshots under .tmp; do not commit or publicly attach them.
• Receive Designer review where visual hierarchy changed, independent Tester PASS, and PM acceptance on a frozen fingerprint before commit.
• Commit only accepted issue-owned paths, then merge/push/On-Call through the coordinated #166-safe publication order. Local acceptance is not shipped status.

Integrated acceptance scenarios

One shell across direct routes

Given an authenticated synthetic operator/admin fixture and every canonical route/parameter combination
When each route is opened directly, refreshed, reached from the shell, followed through relationships, closed, and revisited through Back/Forward
Then the exact surface/entity/context renders inside one shell, URL and focus remain synchronized, and unsupported/stale input follows honest recovery

Responsive decision hierarchy

Given deterministic ready fixtures at 1440x900 and 390x844
When every surface and its primary detail/overlay is opened
Then the next decision is visually first, mobile reflows rather than squeezing desktop layout, targets meet size requirements, and no content becomes unreachable

Honest failure and mutation state

Given empty, partial outage, full outage, forbidden, validation, version conflict, stale entity, and double-submit fixtures through the real local server
When the page loads or the operator attempts its state-valid action
Then successful data and recoverable input remain, false zero/success never appears, duplicate writes are prevented, and focus moves to useful status/error guidance

Identity and teammate boundary

Given a signed-in actor and selected authorized teammate after #164
When visible work scope changes and a delegated Task action is attempted
Then the actor never changes, safe server projections and filters bound visible work, authorization is enforced server-side, actor attribution is authoritative, and raw ID/email is not exposed

Keyboard and assistive technology

Given desktop/mobile viewports, both themes, and reduced motion
When keyboard-only navigation traverses shell, list/detail, tabs/disclosures, dialogs, destructive confirmations, close, and Back
Then names/roles/states are announced, focus order/ownership/restoration is correct, and scans report no critical/serious findings

Verification contract

Each child records exact commands, exit codes, test counts, behavior titles, and evidence paths appropriate to its bounded diff. The final integrated audit runs, at minimum:

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
npm --prefix backend run test:e2e
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
make ci
git diff --check

A PM may narrow iteration commands per child, but Tester acceptance must cover the changed behavior and its integration seams. Never execute raw import/export/migration/restore scripts or one-off data-movement tests for this epic.

Final screenshots are untracked, public-safe, native-size evidence under .tmp/screenshots/issue-162-final, with source/SAM desktop 1440x900 and mobile 390x844 pairs for every changed canonical surface plus notifications, Settings, mobile navigation, and critical empty/error/dialog states. The final child defines the exact finite filenames from the then-integrated surface inventory; the directory has no stale extras. Screenshots support behavior evidence and never replace it.

Lifecycle gates

• #156 canonical route/behavior foundation integrated and closed
• #159 capability/parity foundation integrated, source-gated, and closed
• Canonical modular shell and domain surfaces exist as current-source candidates
• #180 Tester PASS, PM accepted, closed via e684162 and b045739, with containing baseline 78e9122 recorded
• Wave A child issues #218–#222 filed and PM-groomed from the accepted #180 baseline
• #161 accepted and integrated locally before slice 6; unpushed and not shipped
• #164 accepted/committed at 3e835a19017da18f2177d81fb7e084764970dee3; reviewed integration still required before slices 7–8
• #158 accepted/committed at 8839fcfb39a3553a673d395a7b3746e2c92218cd; reviewed integration still required before slice 9
• #218 completed Designer → Tester → PM → commit locally as 0c89588df809b2e84af02e796d1910a25eea0165; unpushed and not shipped
• #219 completed required reviews and committed locally as 9d204d208820e3d842a3d3fc83493c230bcadaa5; unpushed and not shipped
• #220 completed required reviews and committed locally as d334020ca5a582d31a81b371988169cab4e7f6b2; unpushed and not shipped
• #221 completed required reviews and committed locally as 8c3b110c8aa138d95385a89fe3328749bdf47250; unpushed and not shipped
• #222 is held at immutable checkpoint 65fb9a8392ed76cc55e74a9b783e352914169411; final verification and fresh Designer, independent Tester, and PM reviews remain
• Slices 1–9 each complete implement → Designer as applicable → Tester → PM → commit
• Accepted slices integrated through coordinated #166-safe publication
• Final cross-surface audit passes on one frozen fingerprint
• PM accepts the integrated epic
• Source CI/CD and On-Call evidence recorded before shipped/closure claim

Out of scope

• Reopening or weakening accepted #180 behavior inside a #162 child.
• Rebuilding already compliant surfaces solely to match a prototype or achieve visual novelty.
• A second frontend/shell/router, framework rewrite, new global data model, browser-only success, or compatibility/legacy layer.
• Extending the current /api/users teammate prototype or claiming client-side filtering is a security boundary.
• #158 lifecycle/access implementation, #161 Home implementation, #164 identity/team/authorization implementation, or #180 bug fixes inside this epic.
• New API/persisted fields without a separately groomed backend contract.
• Migration frameworks, migration-only routes, imports, restores, exports, one-off data tests, production writes, AWS changes, manual deploys, workflow dispatch, or source-repository edits.
• Raw operational knowledge, private/provider data, production identifiers, or tracked screenshots/generated design boards.

This is an in-progress convergence epic tracked through child issues #218–#222 rather than a standalone implementation task. Read the staged implementation slices and the current #222 checkpoint 65fb9a8, then verify the pending Designer, Tester, and PM reviews; done requires accepted reviewed integration, push, source CI, and On-Call evidence.