docs: delivery plan for workbench phases 2–5 - #44
Merged
noodlemind merged 3 commits intoAug 7, 2026
Conversation
Records scope, acceptance criteria, verification, and risks for the knowledge operator, governed execution, durable runs, TUI, and plugin releases, carries every phase 1 deferral to the phase that inherits it, and keeps the settled TUI design direction with the work it belongs to.
📝 WalkthroughWalkthroughAdded a TUI command palette specification, a durable delivery plan for Workbench Phases 2–5, and a contract-test update that requires the new architecture document. ChangesHarness CLI Workbench documentation
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
…rammar Settles the TUI command surface against ground truth read from eight installed agent CLIs (pi, Claude Code, Codex, Cursor, Grok, Amp, Warp, Gemini) — binaries, bundles, settings schemas and shell completions. The CLI grammar does not change. An earlier proposal to collapse 91 command-specific flags into subcommands and a config store is rejected: it paid a full migration cost to serve one of three audiences. Models read a tool description per call; shell users have --help and completion; only the TUI lacked a discovery affordance, and an index supplies it. Contract additions: - palette is a flat searchable index over commands, verbs and skills - no "--" is ever typed in the TUI; noun+verb resolves to argv internally and the resolved command is echoed into the ledger - ":" namespaces (skill:consolidate), whitespace separates - sigils are /, @, !, !!; entry on / and Ctrl-P, never Ctrl-K - side-effect class shown per row Phase 2 picks up the registry metadata that feeds it: enumerate ~18 prose-only verbs, tag all 98 options verb/prompt/cli-only, add surfaces and userInvocable. Standalone value ahead of any TUI — richer help, and it closes a strict-validation gap where an option declared on a parent validates against a verb that cannot accept it. Phase 4b gains bidirectional assertions so the index cannot drift from dispatch — the failure mode every surveyed tool has already shipped.
Owner
Author
|
@coderabbitai review |
✅ Action performedReview finished.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/architecture/harness-cli-workbench-delivery.md`:
- Line 128: Replace the local ~/.gstack/projects/*/designs/harness-tui-*
reference in the “Design direction (settled)” section with a stable
repository-tracked reference. Move or copy the referenced mock and research into
the repository if needed, then link to that tracked location so contributors can
review and preserve it.
In `@docs/architecture/harness-cli-workbench.md`:
- Around line 429-450: Separate the no-flag restriction in
docs/architecture/harness-cli-workbench.md (lines 429-450) so it applies only to
palette selection and palette-generated argv; explicitly state that ! and !! use
the registry’s policy-gated bash execution path and may contain shell flags.
Update AC6 in docs/architecture/harness-cli-workbench-delivery.md (lines
132-140) to test only palette input and generated argv, excluding governed
shell-composer payloads.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: f9c55d02-ec24-4d06-b6a7-c3431ecfc4d1
📒 Files selected for processing (3)
docs/architecture/harness-cli-workbench-delivery.mddocs/architecture/harness-cli-workbench.mdpackages/harness/test/prompt-library-contracts.test.mjs
|
|
||
| **Goal.** `harness tui` performs the same search, lifecycle, and execution operations as the CLI, through one kernel and one behavior path. | ||
|
|
||
| **Design direction (settled).** Session Ledger — the flow-document form: a scrolling transcript in the terminal's main buffer (scrollback preserved; alt-screen a config, not a default), persistent chrome limited to a two-hairline editor and one dim status line, block meaning carried by faint background tints rather than boxes, near-monochrome with the harness v0.1 palette doing the semantic work, views dissolved into commands that print blocks, markdown plans rendered inline, ephemeral overlays for the command palette and run tree, editor border reflecting gate state, consequence context in the hint row, and an exit ritual that prints the closing tally and resume command into scrollback. Reference mock and research: the design session under `~/.gstack/projects/*/designs/harness-tui-*`. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Move the design reference into a tracked location.
The ~/.gstack/projects/*/designs/harness-tui-* path is local to one machine. Other contributors cannot review or preserve the referenced mock and research. Store the material in the repository, or replace this path with a stable repository reference.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/architecture/harness-cli-workbench-delivery.md` at line 128, Replace the
local ~/.gstack/projects/*/designs/harness-tui-* reference in the “Design
direction (settled)” section with a stable repository-tracked reference. Move or
copy the referenced mock and research into the repository if needed, then link
to that tracked location so contributors can review and preserve it.
Comment on lines
+429
to
+450
| **No `--` is ever typed in the TUI.** The index contains options so a capability can be *found*; it must never require one to be *written*. The palette presents **noun + verb**, and the registry maps the verb onto the argv the CLI already accepts: | ||
|
|
||
| ```text | ||
| index structural → harness index --structural | ||
| index status → harness index --status | ||
| learnings why → harness learnings --why <id> | ||
| knowledge promote → harness knowledge promote --branch <key> | ||
| ``` | ||
|
|
||
| The left column is the TUI's entire vocabulary. The resolved argv is echoed into the ledger after the run, so the surface stays auditable and the shell form is learned by observation rather than by being typed. | ||
|
|
||
| Contract: | ||
|
|
||
| - **One flat namespace.** Commands, their verbs, and skills are sibling entries — reaching a capability never requires knowing its parent. `structural` resolves without the user knowing it lives under `index`. | ||
| - **Skills are namespaced with `:`.** `/consolidate` is the deterministic command; `/skill:consolidate` is the workflow that calls it. The command owns the bare name; the qualified form is the escape hatch. | ||
| - **Ranking is word-boundary weighted**, not substring. Exact match preselects; declared aliases outrank prefix matches. | ||
| - **Values come from pickers.** A verb needing a value opens a chooser populated from live state (branch keys, learning ids, plan paths) — never a typed flag. | ||
| - **Dependent options are refinements, not entries.** An option valid only alongside another (`--since` requires `--structural`) attaches to its parent verb and is offered after selection, never listed independently. | ||
| - **Every row carries its side-effect class** — `read`, `mutate`, `execute` — so the consequence of a command is visible before it runs. This is possible because the registry already declares it per command. | ||
| - **Availability is explained, not hidden.** A command that cannot currently run stays listed and greyed, carrying its reason (`no plan under docs/plans/`). | ||
| - **Entry points:** `/` at line start, plus a configurable chord defaulting to `Ctrl-P` (`Cmd-K` aliased on macOS). `Ctrl-K` is reserved for readline's kill-to-line-end. | ||
| - **Composer sigils:** `!` runs a shell command and puts its output in context, `!!` runs it privately, `@` completes file paths. No other sigil dispatches. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Separate palette argv input from shell-composer input.
The documents prohibit -- in all accepted TUI input, but ! and !! accept shell commands that can contain flags. This makes Phase 4b AC6 impossible to satisfy and can incorrectly reject valid shell commands.
docs/architecture/harness-cli-workbench.md#L429-L450: Limit the no-flag rule to palette selection and palette-generated argv. State that!and!!resolve through the registry’s policy-gatedbashexecution path.docs/architecture/harness-cli-workbench-delivery.md#L132-L140: Change AC6 to test palette input and generated argv only. Exclude governed shell-composer payloads from this restriction.
📍 Affects 2 files
docs/architecture/harness-cli-workbench.md#L429-L450(this comment)docs/architecture/harness-cli-workbench-delivery.md#L132-L140
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/architecture/harness-cli-workbench.md` around lines 429 - 450, Separate
the no-flag restriction in docs/architecture/harness-cli-workbench.md (lines
429-450) so it applies only to palette selection and palette-generated argv;
explicitly state that ! and !! use the registry’s policy-gated bash execution
path and may contain shell flags. Update AC6 in
docs/architecture/harness-cli-workbench-delivery.md (lines 132-140) to test only
palette input and generated argv, excluding governed shell-composer payloads.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #43 (
feat/workbench-phase1-core) — review that one first; this branch contains Phase 1 plus one document.What
docs/architecture/harness-cli-workbench-delivery.md— the how-we-build companion to the workbench contract, covering the four remaining releases.Per release (2 knowledge operator, 3 governed execution, 4a durable runs, 4b TUI, 5 resources/plugins): goal, concrete scope, draft acceptance criteria, verification checks, and the risks worth budgeting for. Plus a sequencing graph showing what actually blocks what — Phase 3 doesn't depend on Phase 2; 4b depends on 4a and reads better after 3.
Two things it carries that only exist because Phase 1 happened
resultOfexpansion that reverses the AC3 lane-scope amendment (Phase 2), the ~20 legacywriteEventcall sites and theevents.jsonlretention contract (Phase 4a), the redaction residuals that start mattering once untrusted output flows (Phase 3). Nothing deferred gets quietly lost.It also writes the cross-model review pass into the standard execution recipe, since that's the step that caught Phase 1's systemic redaction gap.
Why one document instead of four plan files
prompt-library-contracts.test.mjsasserts at most one dated plan underdocs/plans/— plans are transient one-per-open-PR artifacts, deleted after merge. Each phase's dated plan gets cut from this document when its own PR opens. The contract test's architecture-doc listing is updated for the new file; suite green.Summary by CodeRabbit
Documentation
Tests