104 lines
7.2 KiB
Markdown
104 lines
7.2 KiB
Markdown
# 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](../../skills/develop/develop-workflow/SKILL.md) under [ADR 0006](../adr/0006-skill-led-development-workflow-04SEP2026.md). 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.
|