Files
kandev/docs/plans/workflow-move-preview-stability/task-01-stabilize-invalidation.md
T
2026-09-18 10:33:59 +01:00

190 lines
9.4 KiB
Markdown

---
id: "01-stabilize-invalidation"
title: "Stabilize preview invalidation"
status: complete
wave: 1
depends_on: []
plan: "plan.md"
requirements:
- REQ-TASKS-WORKFLOW-MOVE-PREVIEW-001
- REQ-TASKS-WORKFLOW-MOVE-PREVIEW-002
acceptance_criteria:
- AC-TASKS-WORKFLOW-MOVE-PREVIEW-001.7
- AC-TASKS-WORKFLOW-MOVE-PREVIEW-001.8
- AC-TASKS-WORKFLOW-MOVE-PREVIEW-002.1
- AC-TASKS-WORKFLOW-MOVE-PREVIEW-002.2
- AC-TASKS-WORKFLOW-MOVE-PREVIEW-002.3
- AC-TASKS-WORKFLOW-MOVE-PREVIEW-002.4
system_design:
- ../../specs/tasks/system-design/workflow-move-preview.md
---
# Task 01: Stabilize preview invalidation
## Summary
Replace broad record invalidation with prediction-specific revisions. Prove
that harmless updates preserve visible success while real changes still refresh.
## In scope
- Typed revision projections, semantic candidate ordering, and map normalization.
- All regression cases in the [plan test matrix](plan.md#tests).
- Desktop and existing touch-drawer browser evidence, preserving move scenarios.
- Update this work order and plan with actual verification results.
## Out of scope
Backend policy/API changes, persistent caching, stale-result rendering, new copy,
layout changes, production instance mutation, and new navigation surfaces.
## Acceptance
1. The composed hook regression fails before the fix because a harmless update
clears success or issues another request. After the fix it retains success
and the request count across repeated updates in every existing store source.
2. Positive regressions prove relevant changes still invalidate, including
candidate-order changes and mixed eligible/terminal/completion-follow-up
inventories. Preserve cancellation, retry, queue, and generation guards.
3. Desktop and touch E2E keep the disclosure and selected details stable, then
prove a real model update refreshes. Existing move, focus, target-size, and
overflow assertions pass against freshly built assets.
## Implementation sequence
Use `/tdd`. First add the negative revision test and the composed request test
named in the plan; record the expected behavioral failures. Add positive field
and timestamp-order cases before removing broad inputs. Implement explicit
projections in the existing revision module, extracting a small adjacent helper
only if source-size limits require it. Follow the design's metadata and ordering
rules; use backend selectors as read-only references, not targets for edits.
Extend existing browser suites. The unit regression is the RED gate if the
browser fixture cannot reliably hold the pre-fix lifecycle; record that reason.
Run all commands below and record actual counts. Inspect desktop and touch
screenshots against UI-01/UI-02 without changing existing composition.
## ASCII UI preview
UI-01 and UI-02 excerpts; [full views and states](plan.md#ascii-ui-preview).
AC-TASKS-WORKFLOW-MOVE-PREVIEW-001.8 and -002.1 through .3.
```text
Desktop hover Touch drawer
+-------------------------+ +------------------------------+
| Move here | | Move to x |
| Options | | Implement |
| [step capabilities] | | [Options] [Move here] |
|-------------------------| | Reuse current session |
| Reuse current session | | Astra |
| Astra (i) | | [details stay open] |
+-------------------------+ +------------------------------+
Harmless update: both previews retain their current result.
Real input change: Checking session... -> fresh result or Retry.
```
Retain the existing drawer scroll owner, safe-area clearance, 44px touch targets,
and row alignment. Text is illustrative data or existing localized copy.
## Verification
Run from repository root. Install dependencies once if this worktree has no
workspace install. Run browser commands sequentially; managed runners rebuild.
```bash
(cd apps && pnpm install --frozen-lockfile)
(cd apps/web && pnpm exec vitest run hooks/domains/kanban/use-workflow-move-preview-revision.test.ts hooks/domains/kanban/use-workflow-move-preview.test.ts components/task/workflow-move-preview.test.tsx components/task/workflow-stepper.test.tsx components/task/workflow-move-proceed-button.test.tsx)
(cd apps/web && pnpm run typecheck)
(cd apps/web && pnpm exec eslint hooks/domains/kanban/use-workflow-move-preview-revision.ts hooks/domains/kanban/use-workflow-move-preview-revision.test.ts hooks/domains/kanban/use-workflow-move-preview.ts hooks/domains/kanban/use-workflow-move-preview.test.ts)
(cd apps/web && pnpm e2e:run --project chromium tests/workflow/workflow-move-preview.spec.ts)
(cd apps/web && pnpm e2e:run --project mobile-chrome tests/workflow/mobile-workflow-move-preview.spec.ts)
python3 scripts/list-docs.py validate
python3 scripts/lint-spec-files.test.py
python3 scripts/lint-spec-files.py --all
git diff --check
```
Add any extracted helper and changed suite to the lint/test commands before
completion. No new user-facing text is planned; if needed, localize it and run
the repository i18n checks. Record request counts, visible status, and screenshot
comparison. No live instance may be used for browser mutations.
## Files likely touched
- `apps/web/hooks/domains/kanban/use-workflow-move-preview-revision.ts`
- `apps/web/hooks/domains/kanban/use-workflow-move-preview-revision.test.ts`
- `apps/web/hooks/domains/kanban/use-workflow-move-preview.test.ts`
- `apps/web/hooks/domains/kanban/use-workflow-move-preview.ts` only if composed evidence requires it
- `apps/web/e2e/tests/workflow/workflow-move-preview.spec.ts`
- `apps/web/e2e/tests/workflow/mobile-workflow-move-preview.spec.ts`
- An adjacent shared E2E helper if both suites need the same stimulus/capture code
- This plan and work order for results
## Dependencies
None. Existing preview endpoint and consumers are already implemented.
## Risks
See [plan risks](plan.md#risks). Do not remove timestamp sensitivity without
proving candidate-order changes remain observable. Do not silence genuine
invalidations with a longer debounce or a persistent cache.
## Parallelism
`sequential`
## Inputs
- [Requirements](../../specs/tasks/requirements/workflow-move-preview.md).
- [Design](../../specs/tasks/system-design/workflow-move-preview.md#semantic-revision-inputs).
- Existing revision and request-hook suites, renderer/stepper/proceed-button suites.
- `workflow_move_preview.go`, `workflow_move_preview_settings.go`, and
`workflow_session_target.go` under `apps/backend/internal/orchestrator/`.
- Existing E2E specs and `apps/web/e2e/helpers/session-store.ts` for store access.
- `/tdd`, `/mobile-parity`, `/e2e`, and scoped frontend guidance.
## Results
Completed on 2026-09-18.
- TDD RED was confirmed for the new harmless-update and composed-hook cases.
- GREEN focused Vitest passed 74 tests across the revision, request-hook,
renderer, stepper, and proceed-button suites.
- The revision now projects prediction inputs, normalizes configuration maps,
and encodes current/original session identity plus reusable candidate order.
Task descriptions, status-summary bookkeeping, read cursors, command counts,
profile version churn, and timestamp changes that preserve candidate order do
not invalidate the preview. Routing, model, options, connection, context,
eligibility, and candidate-order changes still invalidate it.
- Touch disclosure hover and focus handlers are disabled while the existing
coarse-pointer drawer is active. This keeps the drawer and its details open
through harmless store rerenders while preserving explicit tap and Escape
behavior. Fine-pointer hover and focus behavior is unchanged.
- Desktop Chromium workflow move-preview E2E passed 3 tests. Mobile-chrome
workflow move-preview E2E passed 1 test. Each stability flow observed one
initial request, no request or loading state across three harmless updates,
then a second request and visible loading for a model change before the new
model appeared.
- Typecheck, changed-file ESLint, `pnpm run build:e2e`, `git diff --check`,
`python3 scripts/list-docs.py validate`, `python3 scripts/lint-spec-files.test.py`
(36 tests), and `python3 scripts/lint-spec-files.py --all` passed.
- Review remediation: task-session and indexed-session projections now calculate
current, original, and candidate-order dependencies per source. A duplicate
logical session is not counted twice, while timestamp changes in either source
remain observable when they change a real candidate order. The regression
covers separate timestamp updates, convergence, marked-original provenance,
and a genuine two-candidate reorder.
- Review remediation: profile revisions now include full settings-profile mode
and config options, with the normalized profile `updatedAt` as a scoped
fallback. The regression dispatches the real `agent.profile.updated` handler
for a mode/config-options-only edit, then proves an unrelated profile event
and global version bump do not invalidate the referenced preview.
- Review remediation: an initial-target profile from the durable
`workflow_initial_session` snapshot remains a revision dependency after the
historical session is deleted. The regression proves the missing-session
state and a real profile event invalidate the open preview.
- Review remediation: desktop and touch negative assertions use the shared
`dwell(..., "negative-assertion", ...)` observer window instead of treating a
request timeout as proof that no late refresh occurred.