Person-run work items and per-wave gates — Design
Status: approved Author: Tharinda Rajapaksha Reviewed by: four fresh-context review passes, 2026-09-27 (see ## Revisions). Approved by Tharinda Rajapaksha (lead), 2026-09-27, on the fourth pass’s “no Blockers; Importants are short text fixes” — which Draft 5 applies Date: 2026-09-27 Scope: the delivery harness itself —
/forge-deliver,/forge-wave-decompose,/forge-pr-open,forge-plan-author, the plan and Decomposition Plan templates,plan-reviewer, the tracker schema and its rules, the metrics README and the dashboard. No app-repo change. Ships as onechore:PR, with a.forge/lessons.mdentry so the change can flow back to the upstream template.
Context
/forge-deliver assumes every work item (WI) is carried out by an agent. Three gaps follow from that. The first real case is F5-i.
- No work item a person carries out. Stage 7 Step 3 dispatches every approved
type: subWI in a wave whose dependency waves are merged, and Stage 14 goes from a merged wave straight to Stage 7 for the next wave (.claude/commands/forge-deliver.md, Stage 7 Step 3 and Stage 14). An evidence-only WI — a manual live check against a real external system, such as signing in to the real Microsoft tenant as a test account — would therefore be sent to an implementer orgeneral-purposeagent. That agent cannot do the check, and it may write evidence of a run that never happened. - No way to hold one wave for an outside condition. A feature can depend on another only through
blocked_by, which blocks the whole feature. A soft dependency that matters to one wave only has nowhere to live, so the orchestrator cannot see it. Two cases so far: F5-i’s Wave 2 needs F5-k onmain; F11-a’s Wave 1 needed F39’s audit service onmain. - No supported path for a harness-only wave. Harness wave PRs exist when a wave also touches app repos — for example
forge-et-harness#211 (feature/F39-wave-2) and #215 (feature/F11-a-wave-1), both based onmain. Check withgh pr view <n> --json headRefName,baseRefName. But/forge-pr-open --artifact code --wave <N>assumes code WIs: it pre-ticks lint and unit-test claims, closes per-WI PRs, and truststouched_repos, which onlyforge-worktree-upfills in.
Workarounds in use today.
- F5-i. The Decomposition Plan (on branch
feature/F5-i-planatcc3b338;.forge/plans/F5-i/F5-i-decomposition-plan.md## Notes, “Running Wave 2”) runs Wave 2 by hand. It defers Wave 2’s plan-shaping, closes Wave 1 by hand, opens Wave 2’s PR withgh, then lets Stage 14 → 15 close it. In between, it forbids running/forge-deliver F5-i. - F11-a. The Decomposition Plan (
## Notes, “Dispatch order and the F39 gate”) records the same gate limitation, and ran its gate by hand as agrepforAuditServiceinforge-et-be/src/main/java.
Decisions
| # | Decision | Why | Status |
|---|---|---|---|
| D-1 | A person-run WI is a new type: manual, not a separate executor: field. |
Every dispatch site keys on type: Step 3 dispatches only sub, Step 5c only verify, Step 5e only e2e, and Stage 10 only a single plan. So a manual WI is ignored by all of them by construction, and a site this change forgets to update does nothing, which is safe. |
Lead, 2026-09-27 |
| D-2 | A manual WI lives only in a manual wave: a wave whose WIs are all type: manual. Mixed waves are out of scope. |
A manual wave has no seam contract, no two-pass integration, no live-suite repair loop and no per-WI PRs. So Stage 7 needs one small separate path rather than changes inside the agent path. | Lead, 2026-09-27 |
| D-3 | A wave may carry a gate: list of structured checks: a fixed set of named kinds, each evaluated in one fixed way (FR-6). There is no free-form command form. |
The lead chose “feature phase + read-only check command” on 2026-09-27. Review then showed that no word-based command rule is both safe and usable. A denylist refused F11-a’s own gate check (git merge-base --is-ancestor contains merge and -i), while test -f x; git clean -fdx passed it. Structured kinds cover both known cases, and they run only fixed read-only commands on validated values. |
Lead, 2026-09-27 (revised from the command form and confirmed — Q-1) |
| D-4 | The design lives here, in .forge/design/harness/, reviewed by fresh-context reviewers before implementation, in the same chore PR. |
The harness has no spec format for its own framework changes, and /forge-spec-review is feature-only. |
Lead, 2026-09-27 |
| D-5 | The tracker is written in one place only. As for every other wave, all of a manual wave’s tracker writes happen in the orchestrator’s own checkout and are committed to feature/<ticket>-plan. Only the person’s record lives on the harness wave branch feature/<ticket>-wave-<N>, which is cut from main. The record is a file of its own, never an edit to the run sheet. |
Every reader (Stage 0, the Resume Protocol, wave selection, forge-pr-open --wave, Stage 14, Stage 15) reads the orchestrator’s checkout. Code waves already work this way: code lives on the wave branch and status lives on the plan branch. A record file that exists only on the wave branch cannot conflict with the plan branch’s copy of the run sheet. |
Proposed here |
Requirements
Functional requirements
-
FR-1 —
type: manual,tier: none, and the run sheet.typegains the valuemanual. AmanualWI hastier: none, a new tier value allowed only onmanualWIs. Its plan is a run sheet built from the ordinary plan sections:- Subtasks (
## Subtasks) — the steps the person follows, numbered. - Success criteria (
## Success Criteria) — what to record for each result. - Files to modify (
## Files to Modify) — the harness files the record lands in, which must include the record file.forge/plans/<ticket>/<wi-id>-record.md. Every listed file is inforge-et-harness. - Test approach (
## Test Approach) — reads “none — person-run”. - Decisions and risks (
## Decisions,## Risks) — may read “none — person-run”. - Progress (
## Progress) — carries the plan-authoring rows only. The results go in the record file, not here.
- Subtasks (
-
FR-2 — New WI fields and status.
impl_statusgainswith-person, used only bymanualWIs. A manual WI’s lifecycle ispending → with-person → pr-open → wave-closed.- Two new WI fields are set at M1:
run_by— the name of the person running the WI;handoff_sha— theorigin/maincommit the harness wave branch was cut from.
-
FR-3 — What agents may and may not do for a manual WI.
- A plan-author agent may draft its run sheet in Stage 7 Step 1, as for any WI.
- No implementation, verify or e2e agent is dispatched for it.
- No dispatched agent, and not the orchestrator, writes, completes or paraphrases its record. (Rev 3:) Claude in the person’s own run session may run the steps the sheet allows it and draft the record at the person’s direction, from what was run and seen in that session; the record’s header names who ran each step and who drafted it, and the person adds a dated, named acceptance line.
These rules appear in two places:
- the Dispatch invariants section, as invariant 4;
- the specialist-selection table, as a
type: manualrow reading “none — handed to a person (the manual-wave path)”.
-
FR-4 — The manual-wave path in Stage 7. When the selected wave is a manual wave, Stage 7 changes as follows:
-
Step 0 (the seam contract) is skipped.
-
Steps 1–3 author and review the run sheets as usual, but approving a run sheet never dispatches anything.
-
Step 2’s file-collision check is skipped, because the WIs of a manual wave share one record branch.
-
Step 4’s overlap may shape a manual wave’s run sheets while an earlier wave implements.
-
Steps 5a–6 are replaced by M1–M3 below.
-
M1 — hand-off. Skipped under
--no-implement. It runs when wave selection picks aplannedmanual wave whose run sheets are all approved and whose gates are met (FR-6). The orchestrator:- creates
feature/<ticket>-wave-<N>inforge-et-harnessfromorigin/mainand pushes it. If that branch already exists on the remote — for example after an interrupted M1 — it reuses the branch instead of re-cutting it: it runsgit fetch -q origin feature/<ticket>-wave-<N>, then takeshandoff_shafromgit merge-base origin/main origin/feature/<ticket>-wave-<N>; - asks, with
AskUserQuestion, who carries out each WI; - writes to the tracker in its own checkout, with the Edit tool:
- per WI:
run_by,handoff_sha(the cut commit),impl_status: with-personandtouched_repos: [forge-et-harness]; - for the wave:
status: in-progress;
- per WI:
- commits those writes to
feature/<ticket>-planand pushes it, so that any teammate’s checkout, once pulled, sees the hand-off. If the push fails, M1 halts and says so: the hand-off is not complete until it is pushed; - prints a hand-off block, then ends the turn. The block gives:
- each run sheet’s path and the record file to create;
- the wave branch, and the command to check it out in a worktree at
"$WS/worktrees/<ticket>/wave-<N>/forge-et-harness"; - the no-fabrication rule;
- how to finish: commit the record, and any register rows the run sheet names, on the wave branch; push; then re-run
/forge-deliver <ticket>, either from the checkout that ran M1 or from any harness checkout after pullingfeature/<ticket>-plan.
M1 is a hard boundary, like Stage 13.
- creates
-
M2 — close. The orchestrator fetches
originand, for each WI:- checks that the record commits exist:
git log <handoff_sha>..origin/feature/<ticket>-wave-<N> -- .forge/plans/<ticket>/<wi-id>-record.mdmust be non-empty; - reads the record with
git show origin/feature/<ticket>-wave-<N>:.forge/plans/<ticket>/<wi-id>-record.md; - checks that the record has one entry per success criterion, each carrying a name and a date, and, when Claude drafted it,
run_by’s dated, named acceptance line (FR-3, Rev 3). It does not write or complete those entries.
Then it asks, with
AskUserQuestion, whetherrun_bycarried out the run themselves or directed it in their own session, and whether they recorded every result or read and accepted the record drafted for them. Only on “yes” to both does it act, in its own checkout, and commit and push the result to the plan branch:- it sets the WIs to
impl_status: pr-open; - it ticks the WIs’ success-criteria boxes in their run sheets;
- it ticks the spec acceptance criteria those WIs own, in the format
specs.mdrequires: one dated line at the head of## Acceptance Criteriapointing at the<wi-id>-record.mdfiles, not a pointer per box. These ticks are status marks, not evidence — the evidence is the person’s record.
On anything else it halts and names what is missing.
- checks that the record commits exist:
-
M3 — open the wave PR. The orchestrator invokes
forge-pr-open <ticket> --artifact code --wave <N>(FR-8), then pushesfeature/<ticket>-plan, becauseforge-pr-opencommits but does not push, and then halts at Stage 13. Without the push, a teammate who re-runs from another checkout after the merge would find the wave stillin-progress. The run would go to M3, and M3 would fail because GitHub had already deleted the wave branch. Stage 13’s printed block gains a manual-wave line:/forge-review-prdoes not apply, because the PR is a harness PR, not a code PR (.claude/CLAUDE.md§ Quality Gates). The hand-off block and the Stage 13 block both remind the person to remove their wave worktree once the PR is open; Stage 14’s branch cleanup cannot delete a branch that a worktree still has checked out.
The Human Checkpoints list, the session-unit table and the Stage map all gain M1’s boundary.
-
-
FR-5 — Resume and reconciliation know the manual states.
- Resume sub-states. The Step 5a–6 resume sub-state table (used for an
in-progresswave) gains a first row: “the wave is a manual wave → use the manual sub-states”. Without that row, an all-manual wave would fall into the existing rows vacuously. Before evaluating the manual sub-states, the step checks the wave branch is on the remote (git ls-remote --exit-code --heads) and, if it is, runsgit fetch -q origin feature/<ticket>-wave-<N>, so that a stale remote-tracking ref cannot hide a record the person has already pushed (Rev 2). The manual sub-states are:- WIs at
with-person, the wave branch missing from the remote, and no evidence that a record was pushed (no wave PR in any state, and no local copy of the branch with commits afterhandoff_sha) → re-create the branch fromorigin/mainas M1 does, keephandoff_sha, print the hand-off block again and exit (Rev 2). - WIs at
with-person, the wave branch missing from the remote, and evidence that a record was pushed → halt with a drift report; never re-create the branch (Rev 2). - WIs at
with-person, and FR-4 M2’sgit logis empty → the person has not recorded yet. If the local plan branch is ahead oforigin(M1’s push failed), push it first. Then print the hand-off block again and exit. - WIs at
with-person, and that log is non-empty → M2. - WIs at
pr-open→ M3.forge-pr-open’s existing open-PR pre-check makes this safe to re-enter, including after an interruption betweengh pr createand its step 5.
- WIs at
- The last wave merged. The top-level Resume Protocol gains a row: “
phase: dev, decomposed, every wavemerged→ Stage 15”. Stage 15’s Step 1b already flipsdev → review. The Stage map is updated to match, as the file’s INVARIANT comment requires. The row is needed because Stage 0 usually heals the last wave tomergedbefore Stage 14 runs, and no current row routes that state onward. The gap exists today for every wave-mode feature, not only manual ones. - Planned manual waves. A
plannedmanual wave reaches M1 through wave selection (FR-6), not through this table. - Stage 0. Stage 0 reconciles a
manualWI against the wave branch and the wave PR, because a manual WI has no per-WI branch or PR. It gains two rows:- A
with-personWI is never reset topendingor re-dispatched. The “dispatched with nothing pushed” heal applies todispatchedonly. - A manual WI at
pr-openor later with no wave branch and no wave PR in any state → halt. This is the existing rule for artifacts that don’t exist, stated for the wave. It must require both to be missing, because GitHub deletes a merged PR’s head branch (delete_branch_on_mergeis on), so after the merge only the PR remains.
- A
- Resume sub-states. The Step 5a–6 resume sub-state table (used for an
-
FR-6 — Per-wave gates.
waves[].gateis an optional list. Each entry is exactly one of these kinds, plus a one-linemeans:that is printed while waiting:Kind Shape Met when How it is evaluated Feature phase {feature: F5-k, phase: [done]}that feature’s phaseonmainis one of those listedgit fetch -q origin, thengit show origin/main:.forge/tracker.yaml | yq '.features["F5-k"].phase', from the harness checkout. It readsmain, never the orchestrator’s own checkout, which may be behindWave merged {wave_merged: {feature: F39, wave: 1, repos: [forge-et-be, forge-et-harness]}}every listed repo reduces to MERGED(see “Reading a wave’s PR state” below)for each repo, the wave-PR state query below. This uses GitHub itself, the ground truth Stage 0 already uses, because the tracker’s mergedflag reachesmainlatePR merged {pr_merged: {repo: forge-et-be, number: 72}}that PR’s state is MERGEDgh pr view 72 --repo <github_org>/forge-et-be --json state --jq .stateText on main {on_main: {repo: forge-et-be, path: src/main/resources, contains: "crm01@empire.lk"}}origin/mainof that repo has that text under that pathgit -C "$WS/<repo>" fetch -q origin, thengit -C "$WS/<repo>" grep -q -F -e "$GATE_TEXT" origin/main -- "$GATE_PATH", with the values passed as quoted variables, never pasted into the commandReading a wave’s PR state — defined once in
forge-deliver.mdand used by thewave_mergedgate, Stage 0 and Stage 14.-
The query, per repo:
gh pr list --repo <github_org>/<repo> --head feature/<ticket>-wave-<N> --state all --json state --jq '[.[].state]'. It works after GitHub has deleted the merged head branch (checked 2026-09-27 on #215). -
The reduction. The query returns every PR ever opened on that head, so the list is reduced to one state:
OPENif any PR is open;- otherwise
MERGEDif any PR is merged; - otherwise
CLOSEDif the list is not empty; - otherwise no PR.
A wave whose first PR was closed and then re-opened as a new, merged PR therefore reads
MERGED, notCLOSED.
Validation, before anything runs. The orchestrator validates every value first:
featuremust be an existing tracker key;waveandnumbermust be positive integers;repomust be one of the delivery repos;pathmust not start with-, contain..or contain a newline;containsmust contain no newline;phasevalues must be in the phase enum.
An entry that is not exactly one kind, or that fails validation, is refused as malformed. The orchestrator never runs a command taken from the tracker. Apart from
git fetch, which updates only remote-tracking refs, every command is read-only.A note on the feature-phase gate. Stage 15 flips
review → ship → donein one session on the plan branch, so onmaina feature goes straight todone. A feature-phase gate therefore means “that feature is closed”, which is later than “its code is on main”. For the code itself, useon_mainorwave_merged.Behaviour.
- Wave selection — one rule.
- If every wave is
merged, go to Stage 15, whose Step 1b flipsdev → review. - Otherwise, pick the lowest-numbered wave that is not
mergedand whosedepends_onwaves are allmerged. - If that wave has plans at
backlog,draftorin-review, run Steps 1–3 for it whatever its gates say. A gate never blocks plan authoring or review. - Before any dispatch (Step 3, 5c, 5e) or hand-off (M1), evaluate the wave’s gates. If one is unmet, print “Wave
<N>waits on:<means>” and exit cleanly, without escalating.
- If every wave is
- Gates are evaluated at that point, and again immediately before each individual dispatch. The result, with each gate’s
means, is printed. - Under
--wave <N>, unmet gates join the existing soft dependency check. Proceeding past one needs an explicit “y”, and appends an override block to.forge/engagement-gate-runs.md, as the dependency override already does.
-
-
FR-7 — Stage 14 follows the gates and refuses an empty wave.
- No automatic next wave. After recording a merged wave, Stage 14 re-enters Stage 7’s wave selection (FR-6), which also covers the all-merged exit. It no longer says “proceed to Stage 7 for wave N+1 (or Stage 15 if last wave)”.
- Reading the wave PR’s state. Stage 14 reads each repo’s wave PR state with FR-6’s shared query and reduction, and acts on the reduced value (
OPEN→ wait,CLOSED→ halt and escalate,MERGEDin every repo → merged). This replaces its currentgh pr view --repo … --head …, which fails with “unknown flag: --head” (checked 2026-09-27). Because that error is sent to/dev/null, every state reads empty, and the current code can mark an open wave PR as merged. This is an existing bug that affects every wave. - Empty
touched_repos. Stage 14 refuses a wave whosetouched_reposunion is empty. As written today, “all MERGED” is vacuously true over an empty list. It computes the union with the map-keyed lookupyq '.features["<ticket>"].waves[] | select(.wave == <N>) | .workitems[].touched_repos[]', becausefeaturesis a map keyed by id.
-
FR-8 —
/forge-pr-open --wavehandles a harness-only wave. For a manual wave,/forge-pr-open --wave:-
resolves
REPO_PATHforforge-et-harnessto the harness checkout, which is only used forgit fetchandgh.gh pr create --headneeds no checkout of the wave branch; -
skips per-WI PR closing, because
manualWIs have none; -
uses a manual-wave PR body that lists each WI, its
run_byand its record file, and pre-ticks nothing about lint or tests; -
uses the title
docs(<ticket>): wave <N> — <ship state>; -
keeps its step 5 behaviour:
waves[N].status: pr-openand each WI’simpl_status: wave-closedare written and committed in the orchestrator’s checkout, on the plan branch, as for every wave. -
pins every tracker lookup in its steps 2 and 5 to the map-keyed form (
.features["<ticket>"].waves[] | select(.wave == <N>) …):- the
TOUCHED_REPOSunion; - the wave-status write;
- the WI loop;
- the per-WI
branchandtouched_reposreads inside the loop; - the
impl_statuswrite.
On a scratch copy of this tracker, the current sequence form changes nothing and exits 0. Pinning only some of the lookups would be worse than pinning none: a fixed loop over unfixed branch reads would mark code WIs
wave-closedwhile their per-WI PRs stay open. - the
For every wave,
/forge-pr-open --waverefuses an emptytouched_reposunion, computed with the FR-7 lookup. Fixing the same broken lookup at the skill’s other sites is a separate task (Out of scope). -
-
FR-9 —
forge-plan-author, the plan template and the plan rules know run sheets.forge-plan-authorgains a run-sheet case fortype: manual. It fills the FR-1 sections and writes no test table..forge/plans/_TEMPLATE-plan.mdnotes which sections a run sheet fills and how..claude/rules/plans.mdchanges fortype: manual:- it accepts “none — person-run” in
## Decisions,## Risksand## Test Approach; - it says
## Approachholds one short paragraph: what the run proves and against which real system.
- it accepts “none — person-run” in
- The ticking rule has one stated exception, written once.
.claude/rules/tracker.md§ “Mark completion in the delivering PR” gains it: for a manual wave, the success criteria and the spec ACs are ticked in the plan branch’s M2 commit, after the person’s confirmation, not in the delivering harness wave PR. The reason is that no dispatched agent, and not the orchestrator, may complete the person’s record, and the run sheet and spec are not on the wave branch.plans.mdandspecs.mdpoint at that sentence rather than restating it.
-
FR-10 —
/forge-wave-decomposeproposes manual waves and gates.- Detecting manual waves. Step 5.b gains a detection step: for each spec AC, ask whether only a person can meet it — live credentials, a real external account, a physical device, or a human judgment. If any does, propose a manual wave after the waves whose output it checks, with
type: manualandtier: none. - Recording gates. A second step asks, per wave, whether it waits on anything outside the feature, and records each answer as a gate of one of the FR-6 kinds. When the thing waited on is code, it recommends
on_mainorwave_mergedover a feature-phase gate. - Downstream steps. The inventory, AC coverage, Test Strategy Map, Wave Ship Plan and tracker-write steps carry the new values. Step 6.d’s wave hand-off describes a
manualWI’s plan as a run sheet. - Stage 6. The orchestrator’s single-WI-wave warning (
forge-deliver.md, Stage 6) does not apply to a manual wave.
- Detecting manual waves. Step 5.b gains a detection step: for each spec AC, ask whether only a person can meet it — live credentials, a real external account, a physical device, or a human judgment. If any does, propose a manual wave after the waves whose output it checks, with
-
FR-11 — The Decomposition Plan template.
## Workitem Inventorydocumentstype: manualandtier: none.## Workitem Dependency Graphnotes that a manual wave holds only manual WIs, with no within-wavedepends_on.## Test Strategy Mapshowstier: none.## Wave Ship Plangains aGatecolumn (—when none) and defines a manual wave’s row:ship_type: vertical;- C1 ✓ (no code) and C3 ✓ (no surface);
- C2 reasoned as for any wave;
- C4 ✓ with
Verification: see <WI> run sheet.
## Review Checklistgains two items: manual waves are all-manual, with run sheets; every soft dependency is a gate.- The tracker’s
waves[].gateis authoritative. TheGatecolumn is a mirror, written by/forge-wave-decompose.
-
FR-12 —
plan-reviewergains two §11 checks and the run-sheet reading.- WS-9 — manual-wave validity.
- Blocker:
- a
manualWI shares a wave with a non-manualWI; - a
manualWI has a within-wavedepends_on; - a
manualWI’s run sheet lists a file outsideforge-et-harness.
- a
- Important:
- its tier is not
none; - its success criteria do not say what is recorded, in which file, and that each entry carries who ran it and when.
- its tier is not
- Blocker:
- WS-10 — gate validity.
- Blocker: an entry is not exactly one FR-6 kind, or fails FR-6’s validation.
- Important: the plan’s text names a soft dependency or external condition for a wave, and that wave has no gate for it.
- Changes to existing checks.
- WS-1 lists the
Gatecolumn. - WS-2 applies FR-11’s manual-wave row rule instead of recomputing C1 and C3.
- §3–§6 and §10 read a run sheet per FR-1: numbered person steps count as subtasks, and “none — person-run” is valid in Decisions, Risks and Test Approach. They raise no test findings for it.
- WS-1 lists the
- WS-9 — manual-wave validity.
-
FR-13 — The orchestrator’s own Notes, the tracker schema, and metrics.
forge-deliver.mdNotes. Two lines are updated: “emits no inlineyq -i… all structural writes are delegated” and “writes nothing structural itself”. The updated lines say that the orchestrator writes the manual-wave fields itself, with the Edit tool:run_by,handoff_sha,touched_repos,impl_statuswith-personandpr-open, the wave’sstatus: in-progress, M2’s ticks, and thelast_updatedbump every tracker write carries. Edit-tool writes are notflock-guarded, like the existing Step 3 writes.- The tracker schema. The schema comment block in
.forge/tracker.yamland.claude/rules/tracker.mddocumenttype: manual,tier: none,impl_status: with-person,run_by,handoff_shaandwaves[].gate. The gate kinds are documented by reference toforge-deliver.md. The same edit fixes the block’s wavestatuslist toplanned | in-progress | pr-open | merged: it omitsin-progress, which/forge-deliveralready writes. - The metrics README.
.forge/metrics/README.mddocuments:- a
wi_handed_offevent, written at M1; tier: none;- a
wave_kind: manualfield onwave_pr_openedandwave_merged.
- a
- Two exemptions for manual waves. In
forge-deliver.md, Stage 12b skipstier: noneWIs: they get no test-stats line and count as no coverage gap. The pre-Stage-12 agent-run ledger check exempts manual waves, which have no agent runs.
-
FR-14 — The dashboard.
- The change.
.forge/dashboard/index.htmlscoreswith-personinWI_IMPL_SCOREthe same asdispatched: one third, so a manual wave’s meter moves. - Nothing else changes. No other dashboard code reads WI
typeortier.grep -n "impl_status\|\.type\|\.tier" .forge/dashboard/index.htmlfinds onlyWI_IMPL_SCORE, its use inwiCompletion, and an unrelatedc.type(checked 2026-09-27; the implementer re-runs it).
- The change.
-
FR-15 — Every restated enum is updated or turned into a pointer.
grep -rn "sub | verify | e2e\|sub, verify\|pending | dispatched\|pending → dispatched\|T1 | T2 | T3" .claude .forge/plans/_TEMPLATE* .forge/metrics/README.mdlists the places the enums are restated; the implementer re-runs it.- Known hits:
forge-deliver.md: the specialist table, theimpl_statusenum note in Stage 11, and the Notes;forge-wave-decompose.mdstep 5.e;forge-plan-author;forge-pr-open;plans.md;forge-test-verify’swi_typeenum;.claude/lib/forge-deliver/agent-prompt-template.md.
- What to do with each hit: update it to include the new values, or replace it with a pointer to
.claude/rules/tracker.md. - Two exceptions:
forge-test-verifygains one line sayingmanualWIs never run it;- the agent prompt template needs no change, because a
manualWI is never dispatched.
- Known hits:
-
FR-16 — Records.
.forge/lessons.mdgains an entry (Sync target: upstream)..forge/design/README.mdlists the newharness/folder..claude/CLAUDE.md§ Reference Map gains a row for.forge/design/harness/.
Non-functional requirements
-
NFR-1 — Fails safe. If any site is missed, a
manualWI is left atpendingand never dispatched (D-1). The first review traced Steps 3, 5c and 5e, the repair loop and Stage 10, and confirmed this. -
NFR-2 — No fabricated evidence. No dispatched agent, and not the orchestrator, writes, completes or paraphrases a
manualWI’s record; a record Claude drafted in the person’s own run session carries the person’s acceptance line (FR-3, Rev 3). The M2 confirmation is asked of the human in the session, never inferred. -
NFR-3 — Nothing changes for existing features. A Decomposition Plan with no
manualWI and nogatebehaves exactly as it does today. Every existing tracker entry stays valid without edits:gateis optional, and the new enum values are additions. -
NFR-4 — Gates never run a command taken from data. Only the fixed commands in FR-6’s table run, and only on validated values, passed as quoted variables. The orchestrator refuses a malformed gate, and WS-10 refuses it at plan review.
-
NFR-5 — One statement per rule. Each rule is written once, in the file that owns it, and the others point at it (
.claude/CLAUDE.md§ Compounding Engineering, item 4):- the orchestrator’s behaviour and the gate kinds in
forge-deliver.md; - the schema in
tracker.md; - the review checks in
plan-reviewer.md.
FR-15 removes the existing restatements.
- the orchestrator’s behaviour and the gate kinds in
Acceptance criteria
-
[ ] AC-1 (FR-1, FR-2, FR-13) The tracker schema block and
.claude/rules/tracker.mdlisttype: manual,tier: none,impl_status: with-person,run_by,handoff_shaandwaves[].gate, and the wavestatuslist includesin-progress. -
[ ] AC-2 (FR-3, NFR-1) In
forge-deliver.md:- every dispatch site (Step 3, Step 5c, Step 5e, Stage 10) still keys on its own type, and none dispatches for
manual; - invariant 4 is present;
- the specialist table has the
manualrow.
- every dispatch site (Step 3, Step 5c, Step 5e, Stage 10) still keys on its own type, and none dispatches for
-
[ ] AC-3 (FR-4, FR-5)
forge-deliver.mdhas:- M1–M3, with D-5’s single tracker home, the record file, the
$WSworktree path, thetouched_reposwrite and the--no-implementskip; - the manual first row in the sub-state table, with its
git fetchbefore evaluation; the “every wavemerged” row in the top-level Resume Protocol; and the two Stage 0 rows (the halt row requires both the wave branch and the wave PR to be missing); - the Stage 13 manual-wave line;
- M1 in the Human Checkpoints list, the session-unit table and the Stage map.
The Stage map and the resume table agree, as the file’s own INVARIANT comment requires.
- M1–M3, with D-5’s single tracker home, the record file, the
-
[ ] AC-4 (FR-6, FR-7, NFR-4)
forge-deliver.md:- states the four FR-6 gate kinds once, with their evaluation commands and value validation;
- says a gate blocks only dispatch and hand-off;
- has the non-merged-only wave selection, the waiting rule and the all-merged Termination exit;
- has the
--waveoverride with its audit entry; - has Stage 14’s re-entry to wave selection, its PR-state read through
gh pr list … --head …(notgh pr view --head), and the empty-touched_reposrefusal using the map-keyed lookup.
-
[ ] AC-5 (FR-8)
forge-pr-open’s--waveprocess:- resolves
REPO_PATHfor the harness; - skips per-WI PR closing for
manualWIs; - has the manual-wave body and title;
- keeps step 5’s plan-branch commit, with every tracker lookup in steps 2 and 5 in the map-keyed form;
- refuses an empty
touched_reposunion.
- resolves
-
[ ] AC-6 (FR-9, FR-10, FR-11)
forge-plan-author,_TEMPLATE-plan.md,plans.md,forge-wave-decompose.mdand_TEMPLATE-decomposition-plan.mdcarry:- the run-sheet case;
- the detection and gate steps;
- the
Gatecolumn and the manual-wave ship row; - the two checklist items.
The Stage 6 single-WI warning exempts manual waves.
-
[ ] AC-7 (FR-12)
plan-reviewer.mdhas:- WS-9 and WS-10, with their severities;
- the WS-1 and WS-2 changes;
- the run-sheet reading in §3–§6 and §10.
-
[ ] AC-8 (FR-13, FR-14) The metrics and dashboard changes are in place:
- the
forge-deliver.mdNotes are updated; - the metrics README documents
wi_handed_off,tier: noneandwave_kind; - Stage 12b and the ledger check carry their exemptions;
WI_IMPL_SCOREhaswith-person;- the dashboard renders a tracker containing a
with-personWI without error. Check this by regenerating the dashboard data from a scratch copy of the tracker with one such WI, then opening the page.
- the
-
[ ] AC-9 (FR-15, NFR-5) The FR-15
grepshows every restatement updated or turned into a pointer, and the PR body lists them. -
[ ] AC-10 (FR-16) The lessons entry, the design README line and the Reference Map row exist.
-
[ ] AC-11 (NFR-3) The PR body records a walk-through on paper, covering:
-
F11-a’s tracker entry on
mainand F5-i’s onfeature/F5-i-planatcc3b338are read under the new rules and need no edit; -
F5-i re-expressed:
- WI-2.1 as
type: manual; - Wave 2 gated on
{feature: F5-k, phase: [done]}and{on_main: {repo: forge-et-be, path: src/main/resources, contains: "crm01@empire.lk"}};
The re-expressed F5-i would never dispatch WI-2.1, would wait on F5-k, and would close through M1–M3 and Stage 14 without the hand-run procedure.
- WI-2.1 as
-
F11-a’s gate re-expressed as
{on_main: {repo: forge-et-be, path: src/main/java, contains: "AuditService"}}.
Neither plan is changed.
-
-
[ ] AC-12 The generators run clean on the PR’s tree, and
Repo hygieneCI is green. The generators are:python3 .claude/lib/harness-graph.py --conventionnode .claude/lib/render-docs-html.jsbash .claude/hooks/regen-tracker-dashboard.sh </dev/null
Scope
In scope
Only these files change:
- Commands, skills and agents:
.claude/commands/forge-deliver.md.claude/commands/forge-wave-decompose.md.claude/skills/forge-pr-open/SKILL.md.claude/skills/forge-plan-author/SKILL.md.claude/skills/forge-test-verify/SKILL.md(one line).claude/agents/plan-reviewer.md
- Rules:
.claude/rules/tracker.md,.claude/rules/plans.mdand.claude/rules/specs.md(one pointer). - Templates:
.forge/plans/_TEMPLATE-plan.mdand.forge/plans/_TEMPLATE-decomposition-plan.md. - Tracker, metrics and dashboard:
.forge/tracker.yaml(the schema comment block only).forge/metrics/README.md.forge/dashboard/index.html(one map entry)
- Records:
.forge/lessons.md.forge/design/README.md.claude/CLAUDE.md(one Reference Map row)- this file
- Any other file that FR-15’s grep shows restating the enums.
Out of scope
- F5-i’s and F11-a’s own plans and tracker entries. Moving F5-i’s “Running Wave 2” procedure onto this mechanism is a follow-up once this lands. F11-a is done.
- Mixed waves (D-2), and a person-run
verifyore2e. A manual check of an integrated build goes in a manual wave after the code wave. forge-worktree-up. M1 creates the wave branch itself, and amanualWI gets no per-WI branch.- The single-plan path (Stage 10). A feature that needs a manual wave is multi-plan.
- Fixing the broken
.features[] | select(.id == …)lookup across the harness. It returns nothing on this map-keyed tracker. About 26 sites under.claudeuse it; they are found withgrep -rn 'select(.id ==' .claude. This design pins the map-keyed form only at the sites it edits (FR-7, FR-8). The rest is a separate chore task. forge-estimateexcluding manual or gated waves from its cycle medians. Thewave_kindfield (FR-13) makes it possible; changing the estimator is a follow-up.- Upstream
forge-harnessitself. The lessons entry queues the change; porting it is a later sync.
Where each rule lives
| Rule | Owning file | Pointed at from |
|---|---|---|
type: manual, tier: none, with-person, run_by, handoff_sha, waves[].gate — the schema |
.claude/rules/tracker.md (+ the tracker’s schema comment) |
the templates, forge-wave-decompose.md, forge-plan-author, plans.md |
The manual-wave path (M1–M3), D-5’s single tracker home, the gate kinds and their evaluation, invariant 4, the empty-touched_repos refusal |
.claude/commands/forge-deliver.md |
forge-pr-open (--wave), plan-reviewer WS-10 |
| The harness-only wave PR | .claude/skills/forge-pr-open/SKILL.md |
forge-deliver.md M3 |
| The run sheet | .claude/skills/forge-plan-author/SKILL.md + _TEMPLATE-plan.md |
forge-wave-decompose.md 6.d, plans.md, plan-reviewer |
| Proposing manual waves and gates | .claude/commands/forge-wave-decompose.md |
the Decomposition Plan template’s comments |
| WS-9, WS-10 and the run-sheet reading | .claude/agents/plan-reviewer.md |
the Decomposition Plan template’s Review Checklist |
| The metrics fields | .forge/metrics/README.md |
forge-deliver.md (the append points) |
Open questions
Q-1 — D-3. Structured gate kinds replace the free-form read-only command the lead chose on 2026-09-27. Confirm.Resolved 2026-09-27 (Tharinda): confirmed — structured kinds only, no command form.Q-2 — logging gate evaluations. Should gate evaluations be logged anywhere beyond the printed message?Resolved 2026-09-27 (Tharinda): no. They are printed only. A--waveoverride of an unmet gate is written to.forge/engagement-gate-runs.md, as in FR-6.
Revisions
Draft 2 — 2026-09-27 (before approval)
- Changed:
- D-3 revised to structured gate kinds, and D-5 added (one harness wave branch per manual wave).
- The requirements were reworked around those two decisions, with new FRs for run sheets and for restated enums.
- The scope was widened to match.
- Why: a first fresh-context review found three Blockers:
- the command rule both refused F11-a’s gate and admitted write commands;
- the run sheet, the person’s record and the tracker writes landed on different branches;
touched_reposwas never set for a manual WI, so Stage 14 could mark a wave merged with nothing shipped.
Draft 3 — 2026-09-27 (before approval)
- Changed:
- D-5, where things are written. The tracker is written only in the orchestrator’s checkout, on the plan branch, as for every wave. Only the person’s record, in its own
<wi-id>-record.mdfile, lives on the harness wave branch, and the run sheet is no longer copied. - Run sheets (FR-1). The person’s steps go in
## Subtasks, and a manual WI’s files are restricted toforge-et-harness. - M1–M3 (FR-4). M1 no longer creates a worktree for the orchestrator, M2 reads the record with
git show, and the Stage 13 and worktree-removal lines are added. - Resume and Stage 0 (FR-5). The duplicated M3 routing and the unreachable
pendingrow are dropped. - Gate kinds (FR-6).
wave_mergedis read from GitHub. The yq lookups use the map-keyed form. Every value is validated, and passed as a quoted variable. The note on the feature-phase gate is added. - Wave selection (FR-6, FR-7). Selection considers only non-merged waves and keeps the all-merged Termination exit, and Stage 14 re-enters selection.
- The wave PR (FR-8). It uses the plan-branch commit, as for any wave.
- Reviewer and orchestrator notes (FR-12, FR-13).
plan-reviewer’s run-sheet reading now covers §3–§6, and FR-13 updates the orchestrator’s two Notes lines and drops theflockclaim for Edit-tool writes. - F11-a’s gate (AC-11). It is re-expressed as
on_mainonAuditService.
- D-5, where things are written. The tracker is written only in the orchestrator’s checkout, on the plan branch, as for every wave. Only the person’s record, in its own
- Why: a second fresh-context review found one Blocker and nine Importants:
- The Blocker. Draft 2 wrote the tracker on the wave branch, while every reader reads the orchestrator’s checkout, so the path looped at M1 and could never close a wave.
- Gate issues. The tracker’s
mergedflag reachesmainlate; the yq lookup returns nothing on the map-keyed tracker; gate values were unvalidated. - State-machine issues. Stage 14 lost its last-wave exit; a manual WI could list an app-repo file, but no app-repo wave branch exists for it; no worktree cleanup was specified.
- Documentation issues. Run sheets conflicted with the plan rules, and the orchestrator’s own Notes contradicted M1 and M2.
Draft 4 — 2026-09-27 (before approval)
-
Changed:
- FR-4 (M1–M2). M1 pushes the plan branch, reuses an existing remote wave branch rather than re-cutting it, and tells the person where to re-run from. M2 ticks the run-sheet success criteria and the spec ACs, pointing at the record, after the person’s confirmation.
- FR-5 (routing and halts). The manual sub-states fetch the wave branch first. “WIs at
pr-open→ M3” no longer requires the PR to be absent. The Resume Protocol gains an “every wavemerged” row. The Stage 0 halt row now requires the branch and the PR to be missing. - FR-6 (gates at selection). Wave selection may pick a gated wave for Steps 1–3.
- FR-7 (Stage 14). Stage 14 reads PR state with
gh pr list --head, not the invalidgh pr view --head. - FR-8 (
forge-pr-open). The three tracker lookups inforge-pr-openstep 5 are pinned to the map-keyed form. - FR-9 (run sheets). FR-9 covers
## Approachand the rule for ticking success criteria. - FR-13. FR-13’s list of fields the orchestrator writes is completed. The ACs are updated to match.
-
Why: a third, short verification pass traced one manual wave end to end and ran all four gate commands for real. It found:
- one Blocker: the Stage 0 halt row fired on every merged wave, because GitHub deletes the head branch on merge;
- five Importants:
- a stale remote-tracking ref;
- a plan branch that was committed but not pushed;
- two existing bugs on this path: Stage 14’s invalid
gh pr view --head, and step 5’s lookups, which silently match nothing; - no route to Stage 15 once the last wave is healed to
merged.
Its verdict on D-5 and the gate commands was sound.
Draft 5 — 2026-09-27 (approved)
- Changed:
- Wave selection (FR-6). It is one ordered rule: all merged → Stage 15; otherwise the lowest eligible wave; plans are authored whatever the gates say; gates are checked before dispatch or hand-off.
- Wave PR state (FR-6, used by FR-7). One shared query and reduction (OPEN, MERGED, CLOSED or no PR) serves the
wave_mergedgate, Stage 0 and Stage 14. forge-pr-openlookups (FR-8). Every lookup in steps 2 and 5 is pinned, not three of them.- Pushes (FR-4, FR-5). M3 pushes the plan branch. M1 halts if its push fails. The “not recorded yet” sub-state re-pushes if needed.
- Ticking (FR-4, FR-9). Spec ACs are ticked in
specs.md’s format. The ticking exception is stated once, intracker.md;specs.mdjoins the scope with a pointer. - Resume row (FR-5). The “every wave merged” row goes straight to Stage 15.
- Fetches. M1’s branch reuse fetches before
merge-base. - Field list (FR-13). It includes
last_updated.
- Why: a fourth, short verification pass found no Blockers and five Importants:
- selection rules that contradicted one another;
- a spec-tick format that clashed with
specs.md; - two step-5 lookups left unpinned;
- unpushed state that a teammate’s checkout could not see;
- Stage 14’s array states read as a single state.
Rev 1 — 2026-09-27 (implementation clarifications)
- Changed:
- A manual WI’s
depends_on. It is stated as empty, not “no within-wavedepends_on”. The wave’sdepends_oncarries a manual wave’s order after earlier waves. FR-11’s graph note and WS-9’s first Blocker are read this way, and the implemented files use this wording throughout. - Validating a feature gate’s id. The
featurevalue must match^[A-Za-z0-9-]+$, and yq reads it withstrenv, so the value is never pasted into the expression. This follows NFR-4. - Ten implementation gap-fills, as listed in the PR body:
- run sheets carry no pre-PR-review or PR-opened subtasks;
- Stage 14 halts when a repo has no wave PR;
- M2 runs only when every WI has a record;
forge-pr-openstep 1 also aborts onwith-person;- the wave-PR body gains the
Gatecolumn; - app-repo
REPO_PATHis$WS/<repo>; - WS-10 reads gate entries with Read/Grep;
- there is no manual example row in the template’s Wave Ship Plan;
- gate validation points at existing lists;
- M1 cuts the wave branch with a SHA push.
- A manual WI’s
- Why: the independent review of the implementation diff (0 Blockers, 2 Important, 3 Nits). It found the two
depends_onwordings, the pasted yq value and the gap-fills, and judged every gap-fill acceptable. - Approved by: Tharinda Rajapaksha (lead) — within the approved design’s intent; recorded 2026-09-27.
Rev 2 — 2026-10-01 (a deleted wave branch)
- Changed:
- The M1 hand-off block tells the person to confirm the wave branch is on the remote with
git ls-remote --exit-code --headsbefore theworktree add, and, if it is not, to re-run/forge-deliver <ticket>rather than create the branch by hand. - The manual sub-states (FR-5) gain two rows for WIs at
with-personwhose wave branch is missing from the remote: re-create it fromorigin/mainwhen nothing shows a record was pushed, and halt with a drift report when a wave PR exists or a local copy of the branch holds commits afterhandoff_sha. The fetch before the table runs only when the branch is on the remote, and nothing prunes, so a stale remote-tracking ref stays available as evidence. - Stage 0’s
with-personrow says the manual sub-states handle a missing wave branch.
- The M1 hand-off block tells the person to confirm the wave branch is on the remote with
- Why: F5-i finding F-007 (
.forge/specs/F5-i-findings.md).feature/F5-i-wave-2had no commits of its own and was deleted from the remote before the person pushed the record. It was re-created by hand fromorigin/main, which was safe only because it had no commits. - Approved by: Tharinda Rajapaksha (lead) — merged as
altrium-io/forge-et-harness#336; recorded 2026-10-02.
Rev 3 — 2026-11-18 (a record Claude drafts in the person’s own session)
- Changed:
- FR-3, FR-4’s M2 and NFR-2: the ban on an agent writing a manual WI’s record now names dispatched agents and the orchestrator. Claude in the person’s own run session may run the steps the sheet allows it and draft the record at the person’s direction, from what was run and seen in that session. The record’s header names who ran each step and who drafted it, and the person adds a dated, named acceptance line.
/forge-deliver: invariant 4, the specialist-selection row, M1’s rule line and M2. M2’s check 3 looks for the acceptance line on a drafted record, and its two questions accept “directed it in their own session” and “read and accepted the drafted record”.forge-plan-author’s two run-sheet lines say the same.
- Why: an
owed.mdrow raised by F20-c’s Reflect (2026-10-14). Claude ran steps or drafted the record, at the owner’s direction, for F20-c WI-2.1, F20-h WI-2.1, F20-g WI-3.1, F38-g WI-4.1 (commands only) and F38-h WI-5.2 (partial, before M2). The owner accepted F20-c’s record in its header and F20-h’s and F20-g’s in the session; no earlier record carried the acceptance line this revision now requires. F40 FR-19 Rev 3 had already allowed it for an agent-driven keyboard walk. The risk the rule guards against, an agent writing evidence of a run nobody saw, stays excluded: the person directs the run, sees its results in the session and accepts the record by name. - Approved by: Tharinda Rajapaksha (lead), 2026-11-18, chosen in the session that made the change.