harness-tools/docs/workflow/usability-plan.md

workflow usability update plan

Historical reference, superseded for new development: This plan describes legacy workflow extension recovery and TUI work. New feature work uses the model-invoked develop-workflow skill under ADR 0006. Retain it only as failure and pilot evidence.

Status: historical manual recovery plan after managed Workflow Runs 512d6c31, 51b0c1cb, and ecb11e1e failed or were interrupted before implementation.

Locked decisions

• The interactive dashboard automatically enters a fresh plan-seeded session. Tool and RPC callers receive /workflow continue <run-id> instead.
• Startup may adopt a continuable run only when its prior owner is stale or dead. A live owner remains fail-closed.
• The widget above Pi's editor shows only the newest attached active run.
• Dashboard navigation, action sheets, Gates, confirmations, questions, and feedback use popup overlays in TUI mode. RPC, print, and JSON paths remain linear.
• The plan reader is a full-screen overlay with an H1-H3 outline, current-section highlight, arrows, Page Up/Page Down, Home/End, and Escape.
• The outline is visible at 80 columns and wider, hidden from 60 through 79 columns, and replaced by a truthful minimum-size message below 48x12.
• Dirty source changes require a bounded TUI warning and explicit confirmation when allowDirtySource is omitted. TUI starts honor an explicit allowDirtySource: true without prompting. Non-TUI tool, RPC, print, and JSON starts require allowDirtySource: true. Approval is not tied to a later status digest recheck.
• Approved host commands retain a three-minute timeout. Internal Git commands receive a 30-second timeout. Process-tree termination is bounded on every platform.
• Prototype direction C, drill-down overlays with a dedicated full-screen reader, is the baseline after comparing A, B, and C.

Failure evidence captured during this change

• Run 512d6c31-5bde-4e93-8164-5d31fb684b00 reached design, described a prototype phase, but emitted no prototype assignment. The engine terminated with invalid-design-output: Design must select exactly one prototype Assignment.
• Run 51b0c1cb-f5b2-47f9-8c0c-b323307b720b was interrupted during discovery.
• Run ecb11e1e-fe38-4076-862e-739498dbe33b completed discovery, then remained in the feature-designer assignment for nearly five minutes until interrupted.

These failures are acceptance-test inputs for assignment timeout handling and designer guidance.

Implementation phases

1. Prototype overlays

Own only docs/workflow/dashboard-mocks.md and isolated prototype artifacts. Compare:

• A: centered compact modal
• B: near-full-screen workspace with list/detail panes
• C: drill-down overlays with a dedicated full-screen plan reader

Validate wide, 80x24, 60-column, and 47x11 frames. Production TypeScript remains untouched until the prototype direction is accepted.

2. Session lifecycle and recovery

• Route the dashboard's fresh-session action through the existing handleContinue() and ctx.newSession({ withSession }) path.
• Add an integration test proving a dashboard result triggers session replacement without a second command.
• During absent/dead startup adoption, atomically rotate both lease.activeParentSessionId and implementationContext.activeParentSessionId.
• Preserve live-owner, active-assignment, and historical-session fences.

Primary files: dashboard.ts, context-transition.ts, continuation.ts, engine.ts, and focused tests.

3. Worktree safety and command deadlines

• Return bounded dirty path/status evidence instead of rejecting all ordinary source dirt.
• Keep conflicts, unmerged entries, repository identity, ignored-root, branch collision, and target-path checks fail-closed.
• Create the worktree from the pinned HEAD; warning copy states source-only changes are omitted.
• Add allowDirtySource to tool/domain inputs and idempotency fingerprints.
• Apply 30-second timeouts to every internal Git invocation.
• Keep approved commands at three minutes and bound Windows taskkill itself.
• Preserve exit 124 for timeout and 125 for termination failure.

Primary files: workspace.ts, domain.ts, tool.ts, engine.ts, and focused tests.

4. Popup TUI and plan reader

• Add reusable, modeless overlay components with one earned border, visible selection, keyboard hints, width-safe rendering, and focus propagation for embedded Input or Editor children.
• Use a drill-down stack: run list to run detail to action/Gate overlay. Escape always returns one level or closes.
• Parse Markdown H1-H3 headings into a pure outline model.
• Render only the current plan viewport, not the entire artifact.
• Sanitize untrusted transcript/plan control sequences before rendering.
• Keep ctx.ui.custom() guarded by ctx.mode === "tui".

Primary files: new tui.ts and tests, plus orchestration changes in dashboard.ts.

5. Persistent progress widget

• Add a pure projection for readable label, active stage, completed/total core stages, and open Gate.
• Refresh from persisted attached runs after afterRunPersist and session_start.
• Clear after terminal state and session_shutdown.
• Render one bounded line at narrow widths.

Primary files: new progress.ts and tests, plus registration in index.ts.

6. Design-contract and timeout regression

• Strengthen the bundled feature-designer instructions so non-trivial UI plans explicitly select exactly one eligible prototype assignment with isolated ownership.
• Add a focused test for the exact missing-prototype failure and guidance contract.
• Ensure assignment execution cannot wait forever; surface timeout/interruption evidence without falsely reporting success.
• Record any behavior that cannot be safely fixed in this slice in docs/todo.md with the three run IDs above.

Primary files: agents/feature-designer.md, engine/execution tests, and related runtime code.

7. Documentation, verification, and review

Update the README, design document, dashboard mocks, and a superseding ADR. Run focused tests, typecheck, full tests, and manual Pi validation at wide, 80x24, 60-column, and 47x11 sizes. An agent that did not implement the change performs the final standards and specification review.

Acceptance criteria

• Fresh-session selection continues automatically in interactive Pi without restart or a second command.
• A new Pi process can adopt an absent/dead continuable run but cannot steal one from a live owner.
• Exactly one newest active-run widget is visible above the editor and clears promptly.
• Every bounded TUI interaction is an overlay; RPC/print/JSON remain usable and never call unsupported custom overlays.
• The full-screen plan reader meets the locked outline, navigation, responsive, and width contracts.
• Dirty source starts are warned and explicitly authorized while conflicts remain blocked.
• No internal Git or approved host subprocess can wait indefinitely, and process cleanup is bounded.
• The designer contract prevents the missing-prototype-assignment failure, while assignment execution has a bounded failure path.
• Focused tests, typecheck, full tests, manual Pi validation, and independent review pass.