Skip to content

Finalize the canonical scan-first Operations Home #161

Description

@alexeygrigorev

Finalize the canonical scan-first Operations Home

Status: blocked for coordinated release — Designer/Tester/PM accepted; implementation commit 7d77632 and closeout commit 64476d2 are in local main ancestry, held and unpushed; no shipped/deployed claim
Tags: enhancement, portal, frontend, testing, design, P1
Depends on: #217 preview/deployment/post-deployment identity gate for coordinated publication; #159 and #180 implementation dependencies are satisfied
Blocks: None — #164 Stage B is already Tester/PM accepted and committed locally
Next owner: Orchestrator after #217 release/identity PASS, for safe coordinated push; then On-Call
Resume condition: #217 completes its HUMAN preview, ordinary main/OIDC deployment, terminal On-Call result, and HUMAN identity verification; then resume coordinated publication without carrying the rejected old #146 candidate.

Product outcome

The canonical top-level Home route is a calm, scan-first daily queue: a Today heading, New task/Create card actions, one compact Overdue/Due today/Waiting summary, and one readable Needs your attention list. Operators see the most urgent Tasks once, with a resolved Card label, human timing, at most one exception, and one action that opens the canonical Task detail without mutating it.

This issue now finalizes and proves the current implementation. It is not a greenfield redesign and must not restore the old monolithic frontend or replay the historical prototype patch.

Current implementation and evidence inventory

Code already present

Public main already contains the supervised Home direction beginning with 4a38479 and its subsequent visual, navigation, teammate-scope, modularization, and coverage checkpoints. The current canonical implementation lives primarily in:

  • frontend/src/surfaces/home.js
  • frontend/src/core/workspace.js
  • frontend/src/core/operations-model.js
  • frontend/src/shell/account.js
  • frontend/src/runtime/*
  • frontend/index.html and frontend/src/styles.css
  • frontend/test/home-surface.test.mjs
  • frontend/test/work-model.test.mjs
  • frontend/test/account-shell.test.mjs
  • backend/e2e/frontend-capabilities.json
  • backend/e2e/canonical-capability-behavior.spec.js
  • backend/e2e/frontend-module-characterization.spec.js
  • backend/e2e/canonical-route-parity.spec.js

The current source already has the Today composition, semantic date, quick actions, compact status strip, six-row queue, task action/deep link, honest unavailable values, partial-source state, selected-teammate UI scope, responsive styling, focused Home unit tests, and a durable Home capability entry. These are staged candidate behavior, not accepted #161 evidence.

Stale worktree

The clean worktree .tmp/worktrees/issue-161 points to c0778c394ef6b104c392bd64ff090a29932e32e5. Its three-file patch is byte-for-byte equivalent to public-main checkpoint 4a38479, but c0778c3 itself is not an ancestor of current main. It has no unique implementation to preserve.

Do not merge, rebase, or cherry-pick c0778c3 and do not use its old frontend/index.html, frontend/src/app.js, or frontend/src/styles.css snapshot as the implementation baseline. Worktree/branch removal is separate recoverable housekeeping after the owner confirms it is no longer needed; this issue does not delete it.

Formal gap

#161 has no Designer PASS, independent Tester PASS, PM acceptance, issue-scoped screenshot packet, or accepted closeout commit. The current durable Home browser evidence still points at a canonical-capability journey containing obsolete pre-redesign Home selectors/copy. That evidence cannot prove the current queue until #180 completes its browser-suite repair and #161 updates/revalidates the Home behavior pointer.

Current presence in public main is not retrospective acceptance and does not close the issue.

Sequencing and ownership boundaries

#180 first

#180 currently owns active, uncommitted UI/accessibility and behavior-test fixes in shared runtime/shell/navigation/notification state, Inbox and Recurring surfaces, navigation/runtime/task/operations unit tests, and canonical browser specs. Those changes include focus restoration and removal of stale browser assumptions that overlap #161 shell/accessibility/parity evidence.

Do not edit, stage, revert, absorb, or test-drive #180 paths for #161 while that implementation is active. Resume #161 only after #180 has an exact Tester/PM-accepted commit. Reuse its final behavior-based browser harness; do not reintroduce brittle text/selector pins, serial fallout, fixed sleeps, history arithmetic, or broad 404 swallowing.

#164 after #161

The account control and Show work for interface from the #164 UI-only prototype are already present in canonical source and Home currently scopes its in-memory model to the selected teammate. #161 must preserve that visible separation:

  • the signed-in actor does not change;
  • selecting a teammate changes only the visible Home scope;
  • no raw user ID or teammate email appears in Home;
  • a Task action still opens the canonical detail.

#161 must not claim or implement #164's missing end-to-end guarantees: /api/team-members, server-side owner filters/deep links, persisted Card owner, safe teammate projections, delegated-action authorization, actor attribution, disabled/stale owner behavior, or spoofing protection. It must not treat /api/users or client-side filtering as a security boundary.

#164 remains blocked until #161 is accepted, integrated, pushed, and source-gated as its own tracker specifies. It then implements the backend/security contract on the accepted Home/shell baseline rather than changing #161 queue priority or layout.

Publication

Local implementation/review may resume after the accepted #180 commit. Any eventual #161 push and On-Call evidence must use the coordinated #166 publication sequence; do not push the current ahead-of-origin main wholesale or claim source/production rollout before the containing reviewed integration reaches origin.

Scope

  1. Freeze a read-only acceptance map from every criterion below to current production source and tests after Restore behavior-based browser coverage and fix canonical UI accessibility races #180 lands.
  2. Keep existing compliant behavior. Implement only concrete gaps in current modular files.
  3. Replace stale Home browser assertions with behavior-level coverage against the normal local TypeScript backend and synthetic records.
  4. Update the durable home.loading, home.empty, home.ready, and home.partial-failure capability evidence to exact passing titles.
  5. Complete responsive/accessibility/source-SAM evidence and formal Designer → Tester → PM gates.
  6. Commit only reviewed gap/test/capability changes with Closes Finalize the canonical scan-first Operations Home #161. Do not rewrite historical prototype commits.

Acceptance criteria

Scan-first queue

  • Home renders one readable single-column Needs your attention queue rather than the multi-lane Tasks layout.
  • It merges open overdue Tasks, follow-ups due on/before today, Tasks due today, and missing-proof Tasks; duplicates resolve by overdue → follow-up due → due today → missing proof, then applicable date and stable title.
  • At most six Tasks render. View all tasks uses the canonical Tasks route and preserves Back/Forward/return behavior.
  • Each row shows only Task title, resolved Card name or Independent task, semantic human timing, at most one exception, and one accessible action. Raw Task/Card/user IDs never render.
  • Each valid date has a semantic time datetime value. The action opens the exact canonical Task panel and performs no immediate mutation.
  • Quick actions are New task and Create card, matching current Template/Card/Task vocabulary.

Honest state and shell behavior

  • Overdue, Due today, and Waiting counts come from the same hydrated snapshot, include records beyond the six visible rows, and use unavailable—not zero—when their source failed or has not loaded.
  • Loading, honest empty, ready, and one-source-failed states show no synthetic rows or false zeroes; successful rows/counts remain usable during a partial failure.
  • Home hides document-only tree/filter/back/edit controls; Docs retains them.
  • Restore behavior-based browser coverage and fix canonical UI accessibility races #180 focus fixes survive: Task close/route fallback restores focus to a connected visible control, notification retry focus remains stable, and no Home navigation change regresses the repaired shell.
  • No Done lane/column, direct Home Task mutation, new API, persisted-field change, compatibility fallback, migration, import, restore, or alternate frontend is introduced.

Responsive and accessibility

  • At 1440x900 the heading, actions, summary, and queue form one readable column without narrow-lane sizing, overlap, clipping, or horizontal overflow.
  • At 390x844 the summary, quick actions, queue heading, and first three Task titles/actions fit the initial viewport; touch controls are at least 44px and the page has no horizontal overflow.
  • Summary, queue, messages, View all, quick actions, and Task actions have correct heading/list/time/button semantics, visible focus, keyboard operation, and zero critical/serious WCAG A/AA findings.
  • Light/dark tokens and the current canonical shell remain consistent. No private screenshot, private link, production identifier, generated reference board, or operational content enters tracked files or fixtures.

Teammate prototype boundary

Durable evidence

  • Home unit/model tests cover priority, deduplication, six-item cap, semantic dates, exact task/Card labels, selected-owner composition, unavailable counts, empty state, and partial-source recovery through production module imports.
  • A normal real-server browser journey without request interception for core success behavior proves loading → ready, exact visible order/copy, task open/close/history, View all routing, quick actions, empty state, one-feed failure, recovery, keyboard/focus, and no page/console errors.
  • The Restore canonical frontend behavior coverage and SAM parity gates #159 capability map points home.loading, home.empty, home.ready, and home.partial-failure only to passing behavior titles that exercise the current Home DOM; no obsolete .ops-summary/.ops-lane-item or exact legacy copy assertion remains.
  • Source and packaged frontend have identical manifests/assets and pass the same Home route/behavior assertions.
  • Designer, Tester, and PM evidence is posted before a closeout commit. Existing prototype comments or screenshots cannot substitute for those gates.

Test scenarios

Prioritized queue

Given synthetic canonical Tasks covering all four reasons, duplicate reasons, more than six records, equal dates, Card-linked and independent work
When Home hydrates at a frozen Europe/Berlin date
Then each Task appears once in exact priority/date/title order, six are visible, counts include all loaded records, and compact public-safe fields/actions are correct

Honest degradation

Given loading, all-empty, and one failed Task/Card feed states from the normal local backend
When Home renders and later recovers
Then unavailable sources never show false zeroes, successful work stays visible, recovery removes the source error, and no synthetic row flashes

Canonical navigation and focus

Given an exact Home Task and more than six actionable Tasks
When the operator opens/closes the Task, uses Back/Forward, selects View all tasks, and returns
Then canonical routes and detail identity remain synchronized and focus returns to a connected visible target under #180's repaired contract

Responsive and teammate composition

Given desktop/mobile synthetic signed-in and selected-teammate fixtures
When the operator changes visible scope and scans Home
Then the actor remains unchanged, only visible composition changes, three rows remain in the mobile fold, no raw ID/email appears, and no backend authorization guarantee is implied

Required verification after #180 is accepted

First post a criterion-to-current-source/test inventory. Then implement only unmet items and have Tester report exact commands, exit codes, counts, accessibility output, and evidence paths.

Required commands:

  • npm run test:frontend:unit
  • npm run test:frontend:coverage
  • npm --prefix backend run typecheck
  • npm --prefix backend run build
  • node backend/scripts/verify-frontend-artifact.mjs --source frontend --artifact backend/dist
  • focused Home model/surface/account tests
  • focused Restore behavior-based browser coverage and fix canonical UI accessibility races #180-accepted real-browser titles plus the new exact Home behavior title
  • 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
  • git diff --check

Do not run raw import/export/migration/restore tools or one-off data-movement tests. Use only synthetic public-safe local records.

Tester captures and reads these untracked native-size images under .tmp/screenshots/issue-161/:

  • source-home-ready-desktop-1440x900.png
  • sam-home-ready-desktop-1440x900.png
  • source-home-ready-mobile-390x844.png
  • sam-home-ready-mobile-390x844.png
  • source-home-empty-mobile-390x844.png
  • source-home-partial-failure-desktop-1440x900.png
  • source-docs-controls-retained-desktop-1440x900.png

Source/SAM ready pairs use identical fixtures and prove matching route, visible Task order/copy, action result, accessible-name summary, console/page-error result, and asset hashes. Images are evidence, not behavior proof or tracked artifacts.

Lifecycle gates

Out of scope

  • Replaying or accepting c0778c3 as new work, restoring monolithic app.js, or deleting the stale worktree during grooming.
  • Replacing the current sidebar/IA, adding a frontend framework, a second router/shell, or a new Home data model.
  • Show signed-in identity and authorized teammates’ Task/Card work #164 backend identity/team projection, server owner filters, persisted Card ownership, authorization, delegated-action audit, disabled/stale owner states, or security evidence.
  • Restore behavior-based browser coverage and fix canonical UI accessibility races #180 Inbox/Recurring/notification/focus/browser repair implementation.
  • Direct Task mutation from Home; task-proof redesign; broad Tasks/Card/Template redesign; or changes to assistant, sponsor, finance, bookkeeping, newsletter, calendar, admin, or knowledge behavior.
  • Private operational content, private/generated design assets, external providers, production data, AWS, manual deploy, workflow dispatch, import, export, migration, restore, or source-repository edits.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P1ImportantdesignDesign and UXenhancementNew or improved functionalityfrontendFrontend UIportalShared portal shell and UXtestingTests and QA

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions