15 KiB
created, status, requirements, system_design, legacy_specs
| created | status | requirements | system_design | legacy_specs | |||||
|---|---|---|---|---|---|---|---|---|---|
| 2026-09-11 | implemented |
|
|
Implementation Plan: Plan comment recovery
Overview
Keep ordinary chat usable when background plan-comment reads fail, and recover actual legacy feedback without a manual Retry action. One focused work order owns the frontend correction and its desktop/mobile regression evidence. The task system owns this repair because it controls feedback persistence and delivery; the existing Plan and composer surfaces present that state.
This follows the completed task-owned plan-comment package, especially its migration work and responsive scenarios. The earlier verification results are historical and do not certify this repair.
Confirmed defect
PR #3332, commit f45450fe8, added an unconditional comment-list request after
legacy migration, including when the legacy collection is empty. Its failure
marks the task's migration failed. Session discovery and ordinary plan/comment
read errors can set the same failure before a single legacy row is identified.
The effect then exits on failed, so a later successful read cannot release
the gate. Structured and passthrough Send reject every message on that gate.
A temporary harness executed the actual migration source with simulated transport and hook/state boundaries. It reproduced empty-storage failure, successful refresh leaving Send blocked, explicit Retry recovery, and failed plan discovery staying blocked after confirming there is no plan. These are source-level reproductions, not a completed React or browser regression suite. The live frontend diagnostic bundle contained no browser logs, so the exact network event on the reporting phone remains unconfirmed.
Scope
In scope
- Background task-scoped legacy discovery, exact acknowledgement cleanup, quiet transient recovery, and bounded retries.
- Separate ordinary snapshot loading from legacy recovery restrictions.
- Standard and passthrough Send, selected-comment Run, and inline actionable recovery feedback in Plan and chat.
- Shared desktop/phone behavior, translated pending-action copy, focused tests, and one recovery paragraph in the existing public task guide.
Out of scope
- Backend schema, WebSocket payloads, queue admission, primary routing, or comment ownership changes.
- Global WebSocket timeout/retry changes, browser-wide storage migration, recovery modals, new settings, or layout redesign.
- Reconstructing drafts already deleted by older releases or changing other comment types' persistence.
- Creating platform tasks/sessions, delegation, publication, or changes to the user's running instance.
Technical approach
- Replace the task-plan status-only migration map with the recovery projection described in the system design. Remove all consumers of the old map; do not keep parallel readiness flags.
- Keep orchestration behind
usePlanCommentMigration. A small adjacent coordinator can hold store-scoped promises, timers, known pending records, and subscriptions. Use the existinguseForegroundRefreshpattern and connection state; coalesce duplicate consumers and foreground signals. - Stop importing
getTaskPlanCommentsinto migration merely for a final refresh. Reconcile acknowledged create snapshots, and finish empty scans without a migration network request.usePlanCommentsremains the read owner. - Preserve identified pending records across failed storage reads, partial upload, task/plan changes, and retry. Never treat another session's row or a generic load error as proof of drafts belonging to this task.
- Share the ordinary-Send restriction predicate between structured and passthrough consumers. Keep displayed persisted refs and backend validation. Run checks only its selected persisted comment and primary destination.
- Render
PlanCommentMigrationNoticeonly for actionable identified draft recovery. Background phases have no banner. Pending-Send feedback preserves the draft and explains recovery without requiring migration terminology.
The accepted ownership/admission ADR still applies. The recovery rationale fits the requirement/design; no new ADR is needed.
ASCII UI preview
UI-01: Empty task, or no identified legacy feedback
Entry: open any task composer, including after a failed background read. The current failure and corrected shared composition are:
Before (source-confirmed):
[Some saved plan comments could not be restored.] [Retry]
[Your message ] [Send]
-> rejected
After (desktop and phone):
[Existing context, when present]
[Your message ] [Send]
-> delivered
Required: no restoration banner or migration restriction solely from a pending
or failed read. This does not override actual offline/session input constraints.
The phone uses the current task chat layout and its existing reachable Send
control; the diagram describes hierarchy, not a new horizontal phone layout.
Maps to AC-TASKS-PLAN-COMMENTS-004.5, .6, and .8.
UI-02: Actual legacy feedback requires attention
Entry: the same Plan or chat surface, after known draft recovery exhausts its initial retry burst or encounters an actionable rejection.
Desktop:
[Saved plan feedback needs attention. ] [Retry]
[Your retained message ] [Send blocked]
Phone (same inline region, wrapping when needed):
[Saved plan feedback needs attention.]
[Retry: touch target >=44px ]
[Your retained message ]
[Existing composer actions + Send blocked]
Required: only genuine unresolved task feedback can produce this row; Send
preserves the draft while that feedback would be omitted. Automatic transient
attempts do not mount the row. A persisted selected-comment Run remains usable
if its other eligibility conditions pass. Copy is illustrative and localized;
reuse the existing actionable copy where it already describes the state.
Maps to AC-TASKS-PLAN-COMMENTS-004.1, .3, .4, .7, and .8.
The closest shipped composition is task-layout.tsx with its dedicated mobile
chat and Plan Drawer; the existing PlanCommentMigrationNotice is the inline
region being corrected. Inline feedback fits a brief recovery action without
displacing chat. Preserve its scroll owner, keyboard focus, and safe-area
clearance. Keep desktop Retry at 28 px and coarse-pointer Retry at least 44 px;
do not create an overlay, navigation destination, or extra scroll region.
Tests
| Regression evidence | Acceptance criteria |
|---|---|
use-plan-comment-migration.test.tsx: no legacy rows, unknown/absent/current plan, failed discovery, later successful empty read, unrelated task records |
004.5, 004.6 |
| Migration coordinator and persistence tests: partial success, same-UUID replay, unreadable storage after discovery, conflict, missing plan, plan change, unmount, simultaneous consumers | 004.1, 004.2, 004.3, 004.6, 004.7, 004.8 |
use-plan-comments.test.tsx: connected/foreground retries, coalescing, empty success, preserved displayed snapshot, no migration failure from a read error |
001.3, 004.5, 004.6, 004.7 |
| Structured/passthrough submission tests and Run tests: plain Send allowed, identified unresolved row blocks Send, persisted selected Run allowed, retained text and refs | 002.2, 002.6, 003.1, 003.6, 004.7 |
| Notice component tests: quiet background phases, actual actionable state, manual Retry, focus and draft preservation | 004.4, 004.8 |
All abbreviated IDs in this table use the prefix AC-TASKS-PLAN-COMMENTS-.
The work order names the mandatory
RED cases and exact commands. Preserve existing scenario coverage.
E2E tests
Extend the existing files, with shared failure-injection helpers beside them:
apps/web/e2e/tests/session/task-plan-comments.spec.ts, projectchromium: keep the existing Send/Run routing scenario. Add no-draft failures for a present plan and a lookup eventually confirming no plan. Leave chat transport healthy and prove ordinary Send works without Retry. Add actual mixed legacy recovery, preserving a colocated diff comment and preventing omission.apps/web/e2e/tests/session/mobile-task-plan-comments.spec.ts, projectmobile-chrome: retain the current session-picker/Plan-Drawer migration and routing scenario. Exercise a foreground/reconnect sequence with no drafts, then send through the visible phone control without manual recovery. In a separate scenario, fail one real legacy upload, allow recovery, and prove the comment appears and is delivered once. Check the genuine failure Retry target and absence of horizontal overflow.
Use a correlated page.routeWebSocket interceptor following ws-response-hold.ts
and ws-drop.ts. Target the exact task and action, leaving unrelated frames
live; cover session-discovery failure separately at the useTaskSessions hook
boundary. Record the injected
failure before allowing success. Prove automatic requests and passive backend
state before any helper that can reload or click Retry. Arm causal waits before
the stimulus; no wall-clock success sleeps. Scope controls to the active chat.
These flows cover AC-TASKS-PLAN-COMMENTS-004.1 through .8 and preserve the
existing 001/002/003 routing coverage. Rendered phone checks compare UI-01
and UI-02 with the existing composition, not a new layout.
Work orders
Execution is sequential in the primary conversation. No subagents authorized.
Verification results
Design-package checks on 2026-09-11:
python3 scripts/lint-spec-files.test.py: passed all 36 tests.python3 scripts/lint-spec-files.py --all: all specification files passed.- Read-only local-link and work-order reference audit: 31 local document links and all 18 requirement/acceptance references passed.
git diff --check -- docs/specs docs/plans: passed.git status --short -- docs/specs docs/plans: confirmed both new package files and the intended existing specification/companion-plan edits.
Implementation is complete. The final focused suite passes all 130 tests across 13 files. Changed-file ESLint, TypeScript, i18n checks and ratchet, specification validation, and public-doc validation pass. The final desktop build passes all four browser scenarios. The final phone rerun also passed all four scenarios against that fresh build after a rebuild was terminated before tests started. The states captured on desktop and phone were inspected; draft retention, partial recovery, Retry sizing, and absence of horizontal overflow were verified. The work order records the final results and the scoped public-guide update.
PR review follow-up on 2026-09-12 adds regressions for unknown-plan failures, known-session discovery, concurrent local edits, resume coalescing, retained locales, and stale loading flags. The focused suite now passes 145 tests across the same 13 files; 24 locale-generator tests also pass. Changed-file lint, typecheck, i18n, specification and public-doc checks pass. The work order records review dispositions and scoped validation. Remote CI/review completion remains an exact-head delivery check, not a claim made by this tracked plan.
Claude's follow-up suggestions are addressed with invariant comments for shared discovery, store-lifetime task caches, and authoritative cleanup readback. No executable behavior changed. All 55 focused tests across the five affected coordinator, hook, and persistence test files pass, as does changed-file ESLint.
Post-update review remediation on 2026-09-13 preserves the user's base merge, recognizes actual uppercase transient wire errors, and retains missing-plan refresh intent during manual Retry. Stronger deferred-read and conflict tests confirm serialized loading cleanup and the existing no-overwrite contract. The browser assertion now requires delivery of both plan and diff feedback. The focused suite passes 151 unit/component tests plus 24 locale-generator tests; static and documentation checks pass. All eight Chromium/Pixel 5 scenarios pass with zero retries. The work order records local verification; exact-head remote delivery checks remain a separate gate.
The next review follow-up scopes Run eligibility to cleanup of its selected legacy ID, preserves in-flight uploads when a load confirms the same plan, and uses neutral blocked-Send copy for every recovery failure class. The work order records RED-to-GREEN evidence, 159 focused unit/component tests plus 24 locale-generator tests, and eight zero-retry desktop/phone scenarios. The public Run guidance and blocked-Send previews now state their eligibility conditions explicitly. Remote exact-head checks remain separate delivery gates.
Further current-head review distinguishes unknown from confirmed-absent plan state, retaining the same-ID metadata exception. CI also exposed an unchanged readiness helper matching overlapping Resume controls during SSH reconnect. The helper now observes the first visible active-chat recovery action. The work order records both reproductions and their scoped validation; SSH product behavior and CI timeout/retry policy are unchanged.
The final retry-scope follow-up resets accumulated failures when a plan is replaced, preserving a fresh quiet burst without resetting the budget on same-ID metadata confirmation. The work order records both failing regressions, 186 focused tests, and eight fresh zero-retry desktop/phone scenarios. Completion wording now requires selective browser cleanup, and the plain-Send discovery regression explicitly excludes tasks with identified unresolved drafts.
Risks
- Unknown ownership must not be mistaken for task-owned feedback. Plain Send before legacy discovery includes only visible persisted context; later recovery never amends or resends that prompt.
- A successful subset must not release a Send that would omit the remaining legacy rows. A failed subsequent storage read must not forget known rows.
- Retry promises and timers must remain shared across mounted Plan/composer consumers and stop when their scope is gone.
- New retries apply to reads and idempotent draft promotion only. They must not replay user messages, Run actions, or accepted queue entries.
- A fresh worktree needs its own frozen-lockfile install. The interrupted diagnostic install was completed successfully before product tests.