--- id: "01-show-progress" title: "Show workflow step progress" status: done wave: 1 depends_on: [] plan: "plan.md" requirements: - REQ-TASKS-WORKFLOW-STEP-PROGRESS-001 acceptance_criteria: - AC-TASKS-WORKFLOW-STEP-PROGRESS-001.1 - AC-TASKS-WORKFLOW-STEP-PROGRESS-001.2 - AC-TASKS-WORKFLOW-STEP-PROGRESS-001.3 - AC-TASKS-WORKFLOW-STEP-PROGRESS-001.4 - AC-TASKS-WORKFLOW-STEP-PROGRESS-001.5 - AC-TASKS-WORKFLOW-STEP-PROGRESS-001.6 - AC-TASKS-WORKFLOW-STEP-PROGRESS-001.7 - AC-TASKS-WORKFLOW-STEP-PROGRESS-001.8 - AC-TASKS-WORKFLOW-STEP-PROGRESS-001.9 - AC-TASKS-WORKFLOW-STEP-PROGRESS-001.10 - AC-TASKS-WORKFLOW-STEP-PROGRESS-001.11 system_design: - ../../specs/tasks/system-design/workflow-step-progress.md --- # Task 01: Show workflow step progress ## Summary Implement the shared progress derivation and display it through the existing marker and disclosures. Verify desktop, preview, tablet, and phone outcomes with controlled lifecycle evidence. ## In scope All criteria in [requirements](../../specs/tasks/requirements/workflow-step-progress.md), following the paired design. Add regression tests before production changes with TDD. Use existing translations and add new keys in all five supported language catalogs. Generate Traditional Chinese with `pnpm run i18n:zh-hant` from `apps/web`. ## Out of scope Backend changes, new lifecycle fields, startup optimization, new overlays, inline status rows, and retry actions. ## Acceptance 1. Correct task/step progress survives request settlement and follows current lifecycle evidence, including all failure and stale-state cases. 2. Spinner geometry preserves the existing layout; status and agent details appear only in existing disclosures, with keyboard and touch parity. 3. Targeted tests pass for every mapped criterion; translations and public documentation reflect the final behavior. ## ASCII UI preview ### UI-01: Desktop stepper, preparation ```text Before: o Analysis ---- O Implement ---- o Review After: o Analysis ---- @ Implement ---- o Review +-----------------------+ Existing hover card: | Current step | | Preparing agent | | | | [capability icons] | +-----------------------+ ``` `@` means the spinner, not a literal glyph. `O` means the current dot and ring. The marker, label, and connectors retain their existing positions and dimensions. Only the existing hover card grows to contain details. Spacing in this sketch is illustrative. ### UI-02: Existing hover card, move request ```text +-----------------------+ | [-> Moving...] | | [Options] | | Moving to this step | | [capability icons] | +-----------------------+ ``` Keep the existing button/option eligibility and pending labels. When the step becomes current, its existing controls change as today; the status block remains. After startup, restore the dot and show `Agent running` only inside the card. For failure, show `Agent failed` there and stop the spinner. Existing move errors remain in their current surface. ### UI-03: Compact and phone disclosure ```text Tablet closed: @ Implement 3/6 v Tablet open: [existing workflow Drawer] @ Implement Current step Starting agent Phone closed: [existing task chrome, unchanged] Phone open: [Task actions > Move to] Implement Current Starting agent Review [existing action] ``` Details appear only after opening the existing surface. The phone does not gain a stepper. The drawer owns scrolling and retains its safe-area clearance and touch hit areas. These structures are required by AC .2-.4 and .10; example names and text wrapping are illustrative. See the [complete plan](plan.md#ascii-ui-preview) for shared context and test mapping. ## Verification Run from the repository root. Install dependencies once in a fresh worktree. The managed E2E runner rebuilds the app; do not use stale build artifacts. ```bash (cd apps && pnpm install --frozen-lockfile) (cd apps/web && pnpm exec vitest run hooks/domains/kanban/use-workflow-step-progress.test.ts hooks/domains/kanban/use-workflow-step-move.test.ts components/task/workflow-stepper.test.tsx components/task/workflow-stepper-keyboard.test.tsx components/task-preview-panel-step-indicator.test.tsx) (cd apps/web && pnpm run typecheck) (cd apps/web && pnpm run lint) (cd apps/web && pnpm run i18n:check) (cd apps/web && pnpm run i18n:ratchet) (cd apps/web && pnpm run build:e2e) (cd apps/web && pnpm e2e:run --host --no-build --project chromium tests/layout/task-topbar-workflow-stepper.spec.ts tests/kanban/preview-workflow-step-navigation.spec.ts tests/workflow/workflow-step-progress.spec.ts) (cd apps/web && pnpm e2e:run --host --no-build --project mobile-chrome tests/workflow/mobile-workflow-step-progress.spec.ts) python3 scripts/list-docs.py validate python3 scripts/lint-spec-files.py --all git diff --check ``` If public docs change, also run: ```bash node --test scripts/validate-public-docs.test.mjs node scripts/validate-public-docs.mjs ``` ## Files likely touched - `apps/web/hooks/domains/kanban/use-workflow-step-progress.ts` and `.test.ts` (new). - `apps/web/hooks/domains/kanban/use-workflow-step-move.ts` and `.test.ts`. - `apps/web/hooks/domains/kanban/use-preview-workflow-step-move.ts`. - `apps/web/components/task/workflow-stepper.tsx` and `.test.tsx`. - `apps/web/components/task/workflow-step-disclosure.tsx`. - `apps/web/components/task-preview-panel.tsx` and `task-preview-panel-step-indicator.test.tsx`. - `apps/web/components/task/task-management-drawer.tsx`. - `apps/web/src/locales/` task catalogs and generated Traditional Chinese values. - The four E2E files named in the verification block; the two progress specs are new. - Existing public workflow navigation documentation if its explanation needs an update. ## Dependencies None. Reuse existing lifecycle projections and task/session merge ordering. ## Risks See [plan risks](plan.md#risks). Do not work around missing state with timers or guessed agent phases. If existing projections cannot satisfy a criterion, record the exact gap before widening the backend contract. ## Parallelism Sequential. No delegation is authorized by this package. ## Inputs - [Requirements](../../specs/tasks/requirements/workflow-step-progress.md). - [System design](../../specs/tasks/system-design/workflow-step-progress.md). - Existing stepper/preview tests and compact disclosure controls. - `apps/web/AGENTS.md`, mobile-parity, and E2E skills. ## Results Implemented the shared lifecycle progress presentation across the desktop stepper, compact disclosure, preview, tablet drawer, and phone Move to drawer. The move hook now clears a settled target when the authoritative task advances past it or becomes terminal, while late responses remain scoped to their request and presentation. The progress resolver carries the existing primary session `cancellation_pending` evidence and reports an explicit stopping state before terminal cancellation. Non-current spinners keep the 8px painted and in-flow bounds; the current marker keeps its existing 14px decoration. The full stepper trigger is keyboard-focusable and opens the existing controlled Popover without closing as focus enters its move controls. Focused coverage includes request settlement through SCHEDULING, STARTING, and RUNNING; no-auto-start; failure and cancellation; direct supersession; terminal cleanup; stale response ownership; ambiguous primary-session ownership; bounded task-summary precedence; stale terminal-session suppression; marker, label, and connector geometry; reduced motion; the disabled phone choice status boundary; and the full Popover after the destination becomes current. The desktop browser suite holds the move request, verifies the 8px SVG bounds and stable layout, then completes the move and checks the current destination disclosure. The mobile browser test verifies the existing phone Move to drawer and touch dimensions. Final verification passed: - Focused Vitest: 6 files, 65 tests. - `pnpm run typecheck`, full `pnpm run lint`, `pnpm run i18n:check`, and `pnpm run i18n:ratchet`. - `pnpm run build:e2e`. - Desktop Chromium E2E: 8 tests across top-bar, preview, and workflow-progress suites. - Mobile Chromium E2E: 1 workflow-progress test. - `python3 scripts/list-docs.py validate`, `python3 scripts/lint-spec-files.py --all`, public-doc validators, and `git diff --check`.