8.4 KiB
created, status, requirements, system_design, legacy_specs
| created | status | requirements | system_design | legacy_specs | ||
|---|---|---|---|---|---|---|
| 2026-09-13 | implemented |
|
|
Implementation Plan: Plan comment foreground preservation
Overview
Keep unfinished comments intact when returning to the browser triggers plan refresh. One sequential work order owns the panel correction and component, loader, desktop, and phone evidence. Tasks owns the contract because these comments are feedback on its current plan.
Confirmed defect and evidence
Read-only source trace on 2026-09-13:
use-plan-comments.tsregistersuseForegroundRefresh(wake, ...).use-foreground-refresh.tshandles focus, visible visibilitychange, pageshow, and online.PlanCommentLoader.wake()callsload(true).plan-comment-loading.ts:resolvePlansets task-plan loading to true even with a cached plan, retaining the cached plan during the request.task-plan-panel.tsx:TaskPlanPanelreturns only a spinner for any loading state, unmountingPlanPanelContentand the comment input. Its parent hookusePlanSelectionretains the selection for the same task and plan.- After loading, both variants in
plan-selection-popover.tsxremount with local text initialized fromeditingCommentor an empty string. New text disappears; an unsaved edit reverts to saved text.
Reproduce: open a plan, select text, open Comment, type without Add, switch browser focus away and back. The refresh spinner destroys the draft. Editing an existing comment takes the same path. This sequence was established by source trace and subsequently reproduced by the component tests and a Chromium regression before the correction.
Scope
In scope
- Preserve new-comment and edit-comment text through same-plan foreground, reconnect, and background reads, including failure.
- Keep initial loading and task/plan identity isolation correct.
- Preserve existing desktop Popover and phone Drawer behavior.
Out of scope
Draft recovery across reload, explicit dismissal, or task navigation; backend, API, storage, delivery, mutation concurrency, and layout changes.
Technical approach
In apps/web/components/task/task-plan-panel.tsx, restrict the full-panel
loading placeholder to loading without a current plan. Keep the content
subtree mounted when the current task has a cached plan. Leave shared loader
network-state semantics intact. Use current task plan state, not a sticky
"ever loaded" flag that could show task A's content for task B.
Keep usePlanSelection resets for task change and confirmed deletion or
replacement. While loading, keep plan content read-only and hide its editing
controls; leave the comment input editable. Restore plan editing on settlement.
Do not add autosave for unfinished comments or disable refresh.
This follows completed task-owned comments and recovery packages. Their results remain historical. Existing affected desktop/phone suites are rerun for this package; no backend or migration work orders are reopened.
ASCII UI preview
UI-01: Desktop, Plan > select text > Comment, after browser return.
Before: [Plan] -> [Loading plan...] -> [Comment: empty]
After:
Plan remains visible
+----------------------------------+
| "Selected plan text" |
| Keep this unfinished feedback... |
| [Add] [Run] |
+----------------------------------+
UI-02: Phone, Plan destination > Comment, after foreground return.
| Plan |
| |
| +--------------------------+ |
| | Comment | |
| | "Selected plan text" | |
| | Unfinished feedback... | |
| | [Add] [Run] | |
| +--------------------------+ |
| safe-area clearance |
Both views map to AC-001.9 through .11 below. Editing retains Update/Delete and existing inline failure feedback. Continuous input identity, preserved text/selection, and explicit actions are requirements; spacing is illustrative.
The shipped PlanSelectionDrawer is the phone exemplar: a focused bottom
drawer for a short comment, header, one internal scroll owner, dynamic height,
safe-area padding, and 44 px actions. Keep the desktop anchored Popover.
Shared panel/loader logic owns preservation. Do not forcibly reclaim focus
from another application; the user can resume typing once foregrounded.
Tests
New apps/web/components/task/task-plan-panel.refresh.test.tsx:
preserves a new comment during plan refreshandpreserves unsaved edits during plan refresh, parameterized over desktop/phone and success/failure. Hold the read pending and assert the same textarea node, exact text, and selected plan text before and after settlement (AC-001.9).- No create/update/Run during refresh; one explicit Add/Update receives the preserved body. Existing popover mutation-failure tests remain green (.10).
- Initial loading retains its placeholder. Task change and confirmed plan deletion/replacement clear outgoing selection without stale submission (.11).
Keep the actual panel and comment input; mock heavyweight editor/transport
boundaries. Add a real-hook/loader focus case to
hooks/domains/comments/use-plan-comments.test.tsx proving a request actually
occurs. Rerun loader and same-task session-switch coverage.
All abbreviated ACs in this package refer to AC-TASKS-PLAN-COMMENTS-001.
E2E tests
Extend apps/web/e2e/tests/session/task-plan-comments.spec.ts (chromium)
and mobile-task-plan-comments.spec.ts (mobile-chrome) for new and edited
comments surviving pending, successful, and failed foreground reads (.9, .10).
Use correlated transport interception and causal waits to hold/release the
refresh response. Desktop uses a second page and bringToFront where
supported; deterministic foreground events supplement the loader evidence.
A synthetic event alone does not prove OS Alt-Tab behavior. Phone uses the
actual Drawer and proves preserved text, reachable actions, and no overflow.
Work orders
Verification results
Pre-implementation artifact checks passed on 2026-09-13: python3 scripts/list-docs.py validate
(267 decisions, 868 specifications), python3 scripts/lint-spec-files.py --all,
and git diff --check. The added design section was shortened to satisfy the
existing size limit. Work-order requirement IDs, design paths, and existing
verification inputs were checked. That design-only step changed no production
or permanent tests; implementation subsequently changed the panel and added
the refresh regression file.
Implementation complete: 48 targeted tests across five files, TypeScript,
zero-warning changed-file ESLint, and both full browser suites pass. Chromium
passes 8 scenarios (2.1 minutes); Pixel 5 passes 8 (1.3 minutes), both with
zero retries and E2E_PORT_OFFSET=17. The managed RED run built backend and
fixture artifacts; a fresh build:e2e after the frontend-only fix supplied
both final --no-build browser runs. Desktop and phone screenshots were
inspected. See the work-order results
for exact commands, initial test-setup corrections, and headless limitations.
Public docs are unchanged because this package records implementation intent.
Risks
- Mocking the input hides its local-state loss. Assert actual DOM identity.
- An overbroad loading guard can expose stale content for another task.
- Headless focus differs from OS Alt-Tab; record the event mechanism tested and a manual return check when available.
Review remediation
Plan content is temporarily read-only during background reads, while comment input remains editable. Formatting, slash, and drag controls pause until the read settles. A browser regression failed before this guard; all 16 desktop/ phone scenarios and 69 focused tests now pass. See the work order for exact checks. PR CI and review completion are tracked separately.
CI fixture correction
The full CI suite exposed a last-card assertion using a nondeterministically ordered seed batch in the existing swimlane height test. The exact failure was reproduced locally, then corrected by creating the final card after the batch. All six swimlane cases pass with retries disabled. This test-only remediation preserves the runtime scope; the work order records the failure and evidence.