56 lines
4.7 KiB
Markdown
56 lines
4.7 KiB
Markdown
---
|
|
status: superseded
|
|
supersedes: 0001-workflow-architecture-24AUG2026.md
|
|
superseded-by: 0006-skill-led-development-workflow-04SEP2026.md
|
|
---
|
|
|
|
# Use drill-down overlays and bounded recovery
|
|
|
|
> Superseded by [ADR 0006](./0006-skill-led-development-workflow-04SEP2026.md). Retained as legacy custom-engine UI and recovery evidence.
|
|
|
|
This decision supersedes the dashboard, dirty-source, execution-timeout, and startup-ownership assumptions in [ADR 0001](./0001-workflow-architecture-24AUG2026.md). The persisted gated pipeline, worktree isolation, and independent-review decisions from ADR 0001 remain accepted.
|
|
|
|
## Context
|
|
|
|
Three managed runs exposed usability and liveness gaps:
|
|
|
|
- `512d6c31-5bde-4e93-8164-5d31fb684b00` reached Design, described prototype work, but emitted no `prototype` Assignment. The engine failed with `invalid-design-output: Design must select exactly one prototype Assignment`.
|
|
- `51b0c1cb-f5b2-47f9-8c0c-b323307b720b` was interrupted during Discovery.
|
|
- `ecb11e1e-fe38-4076-862e-739498dbe33b` completed Discovery, then remained in the feature-designer Assignment for nearly five minutes before interruption.
|
|
|
|
The prior focused dashboard did not scale cleanly from run selection through Gate decisions and long verified artifacts. Fresh-session selection returned instructions instead of entering the already implemented continuation path. A dirty source checkout blocked all starts even when the user understood that a new worktree starts from `HEAD`. Internal Git calls and child Assignments lacked complete deadlines.
|
|
|
|
Static prototypes compared a centered compact modal, a near-full-screen workspace, and shallow drill-down overlays with a dedicated reader. Direction C provided the clearest responsive behavior without a permanent side pane.
|
|
|
|
## Decision
|
|
|
|
- TUI run selection, actions, Gates, confirmations, questions, and feedback use shallow popup overlays. Escape returns one level.
|
|
- Verified plans, reports, prototype evidence, and Assignment transcripts use a sanitized full-screen reader. It shows an H1-H3 outline at 80 columns and wider, uses one document pane from 60 through 79 columns, and reports a 48x12 minimum below either boundary.
|
|
- RPC, print, and JSON interfaces remain linear and never invoke custom TUI overlays.
|
|
- A dashboard fresh-session action immediately calls the existing `/workflow continue` handler and `newSession()` flow. Noninteractive callers continue with an explicit run ID.
|
|
- One widget above Pi's editor shows the newest active run attached to the current session. Persisted state drives refresh and terminal state clears it.
|
|
- Startup may adopt a continuable run when its recorded process is dead or its lease is absent. Adoption atomically rotates the lease and Implementation Context active-parent IDs. Live processes and live Assignments remain fail-closed.
|
|
- Worktrees continue to start from a pinned source `HEAD`. Ordinary staged, unstaged, and untracked changes produce bounded path/status evidence and require explicit authorization because those changes are omitted. Unmerged paths remain blocked.
|
|
- Internal Git calls have a 30-second timeout. Approved host commands retain their three-minute timeout. Process-tree termination has a separate deadline and distinguishes command timeout exit `124` from cleanup failure exit `125`.
|
|
- Child Assignment execution has a five-minute deadline and persists timeout/interruption evidence.
|
|
- The feature-designer contract requires exactly one eligible, isolated prototype Assignment for non-trivial UI work, plus explicit implementation, verification, and independent-review Assignments.
|
|
|
|
## Consequences
|
|
|
|
- Dashboard behavior is easier to reason about because each overlay has one local task and the verified reader owns long-document navigation.
|
|
- Interactive continuation no longer requires a second command, while the persisted handoff and revision fences remain authoritative.
|
|
- Dead ownership can recover without manual state surgery. A running process or Assignment cannot be displaced based only on an old heartbeat.
|
|
- Users may proceed from a dirty source checkout without copying local changes into the worktree. Persisted evidence records what was knowingly omitted.
|
|
- Git, host-command cleanup, and child execution now have bounded failure paths rather than indefinite waits.
|
|
- Direction C has automated renderer and orchestration coverage. Its completed manual application validation is recorded below. The static frames in `docs/workflow/dashboard-mocks.md` remain labeled prototype evidence, not production screenshots.
|
|
|
|
## Manual application validation
|
|
|
|
An actual Pi TUI session driven through a PTY passed these checks:
|
|
|
|
- Plan reader at `120x30`, `80x24`, `60x24`, and `47x11`.
|
|
- Selection popup at `60x24`.
|
|
- Input popup at `80x24`.
|
|
|
|
This record does not claim manual validation of other dashboard or workflow paths.
|