Harness-only type: sub work items — Design
Status: in review — implemented in the same PR; the lead approves it by merging Author: Tharinda Rajapaksha (drafted by Claude in the lead’s session) Reviewed by: three fresh-context passes, 2026-10-26 — of Draft 1 (1 Blocker, 5 Important, 5 Nits), of the Draft 2 diff (1 Blocker, 5 Important, 8 Nits), and a verification pass of the Draft 3 fixes (all six closed; 2 new Important, both fixed: a wave with no
subWI resuming without its wave branch, and Step 0a halting on a live wave branch with no tracker writes); see ## Revisions Date: 2026-10-26 Scope: the delivery harness itself —/forge-deliver(Stage 0, Stage 7, Stage 12, Stage 12b, Stage 13), Stage 11’s Pass 1 scaffold, the implementation-agent prompt template,forge-worktree-up,/forge-test-verify,/forge-pre-pr-review,/forge-pr-open,forge-plan-author,plan-reviewer,.claude/rules/tracker.md,check-test-stats.py, and the plan and test-report templates. No app-repo change. Ships as onechore:PR.
Context
A type: sub work item (WI) whose ## Files to Modify lists only forge-et-harness changes harness documents and nothing in an app repo — for example a WI that reads a cloud account and records what it finds in environments-and-identity.md. F38-a ran two (WI-1.1 on 15 Oct, WI-3.1 on 21 Oct). /forge-deliver was written for app-repo WIs, and every step needed a workaround (.forge/owed.md, “Check that /forge-deliver can run a harness-only type: sub work item”; F38-a’s Decomposition Plan ## Notes, “How a harness-only sub WI runs”):
forge-worktree-uprefuses the harness. Its step 2 accepts only the three app repos in theRepocolumn, so the WI worktree was cut by hand.- The prompt template treats the harness as read-only. Its
# Scope disciplineallows writes in the harness only to the WI’s own plan## Progressand## Notes, so both dispatches had to override it. /forge-test-verifyhas nothing to run. Its Step 5a runs a backend or frontend test command for T1; a harness WI has none. The WIs recorded their hygiene checks in## Progressand did not run the skill.- Stage 12b’s
gap_reasonhas no value for “no test suite”. Onlyno-auditandunparseableexist, so F38-a usedno-audit, which says the guard did not run rather than that there was nothing to count. - No per-WI PR, and no stated path for the wave PR.
/forge-pr-open --wavenames the harness as a manual wave’s repo only. F38-a opened no per-WI PR and made the wave branch a fast-forward of the WI branch by hand.
Decisions
The principle: a harness-only sub WI runs like an app-repo WI whose repo happens to be the harness. Its branch and worktree carry only its deliverable documents; its plan’s ## Progress and ## Notes, its test-verify audit and its tracker fields are written in the orchestrator’s harness checkout, exactly where an app-repo WI’s are.
| # | Decision | Why |
|---|---|---|
| D-1 | Branch and worktree as for an app repo. The WI branch is feature/<ticket>-WI-<w>.<i>-<slug> in forge-et-harness, cut from the WI’s tracker base_branch (main, as /forge-wave-decompose writes it) at $WS/worktrees/<ticket>/<wi-id>/forge-et-harness. No wait for the plan PR. |
The plan branch or harness wave branch keeps the orchestrator’s writes, as today; the WI branch holds only its documents, so it merges into the harness wave branch like any WI branch. |
| D-2 | Two harness paths in the dispatch prompt. # Paths names the orchestrator’s harness checkout (<harness>), where the agent reads its plan and writes its ## Progress and ## Notes. # Working directories names the WI worktree, where it writes its ## Files to Modify rows. |
The same split an app-repo WI has; F38-a’s Blocker-shaped mistake was putting the tracker flip on the WI branch, where the orchestrator never reads it. |
| D-3 | Scope. The agent writes only its ## Files to Modify rows (repo forge-et-harness, in the WI worktree) and its own plan’s ## Progress and ## Notes (in <harness>). Still forbidden: .claude/**, tracker.yaml, any other plan or spec, and a frozen contract. A ## Files to Modify row under .claude/ is a plan defect. When the WI’s finding changes a fact stated in .claude/CLAUDE.md (for example § Active Context), the agent records the needed edit in its plan’s ## Notes, and the orchestrator makes it on the harness wave branch, which ships it, before the harness wave PR opens (Stage 12) (.claude/CLAUDE.md § Boundaries, “Record a decision or a finding … in the session it happens”). |
Framework files keep their own review route; the fact still reaches .claude/CLAUDE.md in the delivering PR. |
| D-4 | /forge-test-verify runs the plan’s checks. For a T1 WI whose ## Files to Modify touches only the harness, each ## Test Approach row is either a command, which the skill runs in the WI worktree and records with its exit status (and, where the row names an expected output such as “Isolated machinery count is 0”, checks that output), or an evidence location written as <path> § <heading>, which the skill checks exists in the WI worktree. Every AC on hook must appear in some row’s “What it covers”. The audit’s stats block has "test_suite": "none" and "runs": []. |
The guard runs and leaves an audit; there is no suite, so no counts. |
| D-5 | Stage 12b gains gap_reason: "no-tests". A WI whose latest stats block carries "test_suite": "none" gets a ledger line with totals: null and gap_reason: "no-tests"; the report lists it under coverage gaps. |
It says what is true and keeps no-audit meaning the guard did not run. |
| D-6 | No per-WI PR. /forge-pr-open in WI mode, on a branch in forge-et-harness, pushes the WI branch once, after its last commit, opens no PR, and in <harness> flips impl_status: dispatched → pr-open, leaving pr_number, pr_url and pr_role unset. Stage 7 Step 5a counts a harness sub WI as finished at pr-open with no PR URL. |
The wave PR is the review surface; a per-WI PR would be a second PR over the same documents. |
| D-7 | Stage 0 knows the shape. For a harness sub WI: pr-open with its branch pushed and no PR is a no-op; dispatched with its branch pushed and no PR heals to pr-open when <harness> holds the WI’s test-verify audit with verdict Pass on the pushed head, a ## Pre-PR Review verdict in its plan’s ## Notes, and the WI worktree has nothing unpushed; it halts otherwise. Resume counts Pass 1 as done when the wave branch is on the remote and each sub WI branch is an ancestor of it, not by the wave branch existing alone; and Step 0a reads the row from a live wave branch only when that branch carries tracker writes — otherwise from origin/main — while the branch stays live for the session’s work. |
Without these rows the existing “branch pushed and no PR → halt” row halts every resume; and once the plan PR has merged the harness wave branch exists from dispatch, so “wave branch on the remote” no longer means Pass 1 ran. |
| D-8 | Pass 1 and the harness wave branch. Pass 1 treats the harness like any touched repo: it reuses $WS/worktrees/<ticket>/wave-<N>/forge-et-harness when it exists (the orchestrator’s own harness wave worktree once the plan PR has merged — Stage 0 Step 0a) and otherwise cuts the harness wave branch there from origin/main. A tracker conflict cannot arise, because the WI branch carries no tracker change. |
One rule for every repo. |
| D-9 | The harness wave PR. /forge-pr-open --wave uses that wave worktree as REPO_PATH for the harness (falling back to the harness checkout for a manual wave with no such worktree), a docs(<ticket>): title, and a body whose harness rows list the hygiene commands and “no per-WI PR” instead of lint and unit-test claims. Before it opens, Stage 12 confirms Pass 1 merged each harness WI and runs the locally runnable Repo hygiene checks on the harness wave head (named in Stage 12; CI runs its gitleaks download and the PR-number check). The PR opens as a draft; after Stage 12b the harness wave branch is pushed and the PR is marked ready, so the wave-closed flips, the pre-PR verdicts and the ledger lines are in it before anyone can merge it. It needs no Forge review or Test record status (.claude/CLAUDE.md § Quality Gates). |
The harness’s required check is Repo hygiene; an unpushed commit would let the PR merge without its records. |
| D-10 | /forge-pre-pr-review on a harness diff reads .claude/CLAUDE.md and .claude/rules/ as the conventions and the plan’s ## Test Approach rows as the checks. |
The harness has no root CLAUDE.md or Stack Profile. |
| D-11 | Stage 7’s specialist table gains a row: a sub WI touching only forge-et-harness goes to general-purpose. |
No specialist agent matches; F38-a used general-purpose. |
| D-12 | The check-row shape is stated where plans are written and reviewed: the plan template’s ## Test Approach comment, forge-plan-author’s special case and plan-reviewer TC-1b. |
/forge-test-verify checks the shape at finalize; a plan that does not follow it would fail only after the work is done. |
Requirements
- R-1
forge-worktree-upacceptsforge-et-harnessin theRepocolumn for atype: subWI when it is the only repo (a harness row beside an app-repo row is refused as a plan defect), provisions it as D-1 says, and installs no dependencies for it. - R-2 The prompt template states D-2 and D-3 for a harness WI and the D-6 final-subtask line.
- R-3
/forge-test-verifyhandles a harness-only T1 WI as D-4 says:Pass, orFailwhen a command exits non-zero or misses its expected output, an evidence location is missing, or an AC on hook has no row. Its schema notes nametest_suite. - R-4
/forge-deliverStage 12b and.forge/plans/_TEMPLATE-test-report.mdknowno-tests(D-5);check-test-stats.pykeeps passingruns: [], with a self-test case. - R-5
/forge-pr-openhandles the harness as D-6 and D-9 say, and its--wavestep 1 no longer says “not in a worktree”. - R-6
/forge-delivernames the agent (D-11), Step 5a’s harness case (D-6), the Stage 0 rows (D-7), the D-3 hand-over of a.claude/CLAUDE.mdedit, and Stage 12’s hygiene run and push (D-9); the Pass 1 scaffold states D-8. - R-7
.claude/rules/tracker.md’simpl_statusandpr_*text allows a harness WI’spr-openwith no PR;/forge-pre-pr-reviewstates D-10. - R-8 The
.forge/owed.mdrow is removed in the same PR.
Acceptance criteria
- AC-1 Read on the merged tree, every step a harness-only
subWI passes through — Stage 0, Stage 7 dispatch and Step 5a,forge-worktree-up, the prompt template,/forge-test-verify,/forge-pre-pr-review,/forge-pr-open, Stage 11 Pass 1, Stage 12, Stage 12b, Stage 14 — names what it does for such a WI, and none of F38-a’s five workarounds is needed. - AC-2 A fresh-context reviewer, given this design and the diff, classes each changed rule as faithful, narrowed, widened, dropped or reversed (
.claude/CLAUDE.md§ Compounding Engineering, rule 6) and finds no Blocker. - AC-3
Repo hygiene’s commands exit 0 on the PR’s tree.
Scope
In: the files named in Scope above. Out: a WI that touches the harness and an app repo (refused, R-1); a harness verify or e2e WI; harness WIs in single-plan features (Stage 10 has no WI); a new gate kind for outside waits (L-235 covers that case by moving the check to the register).
Revisions
Draft 3 — 2026-10-26
- Changed: D-7 gains the resume rules (Pass 1 detected by ancestry; Step 0a reads a wave branch’s row only when it carries tracker writes) and a stricter heal condition; D-9 opens the harness wave PR as a draft, marked ready after Stage 12b, and names the locally runnable checks; D-3 puts the
.claude/CLAUDE.mdedit on the harness wave branch; D-12 added; Step 0a’s per-WI harness-branch rule names the harness-only exception; the sweep commit stages by path. - Why: the review of the Draft 2 diff — its Blocker (a resumed session could skip Pass 1 because the harness wave branch exists from dispatch, and open the wave PR without the WI’s documents) and its Importants (Step 0a still told WIs to branch from the wave branch; “every
run:step” ofrepo-hygiene.ymlcannot run on macOS or before the PR exists; the ready harness PR could merge before Stage 12b’s commits; the plan shape was stated only at finalize; Step 0a could read an older row from a wave branch with no tracker writes).
Draft 2 — 2026-10-26
- Changed: the WI branch is cut from
mainand carries only its documents; its plan notes, audit and tracker fields are written in the orchestrator’s harness checkout (D-1, D-2), replacing Draft 1’s “cut from the harness wave branch, write everything in the WI worktree” and its wait for the plan PR. Added D-7 (Stage 0 rows), D-8 (Pass 1), D-10 (pre-PR review), the.claude/CLAUDE.mdhand-over in D-3, the hygiene run and push in D-9, andtracker.mdandcheck-test-stats.pyto the scope. - Why: the Draft 1 review’s Blocker — the orchestrator never saw the WI reach
pr-open, because the flip stayed on the WI branch, so Step 5a waited forever and Stage 0 halted every resume — and its Importants: the branch cut before the dispatch flip; the wait resting on a false premise (Pass 1 already cuts a wave branch in every touched repo); D-3 against the rule that a settled fact reaches.claude/CLAUDE.mdin the same change; the harness wave branch’s later commits unpushed; and files that state the old behaviour.