source: .forge/design/harness/person-run-work-items.md · generated — edit the markdown, not this file

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 one chore: PR, with a .forge/lessons.md entry 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.

  1. No work item a person carries out. Stage 7 Step 3 dispatches every approved type: sub WI 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 or general-purpose agent. That agent cannot do the check, and it may write evidence of a run that never happened.
  2. 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 on main; F11-a’s Wave 1 needed F39’s audit service on main.
  3. 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 on main. Check with gh 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 trusts touched_repos, which only forge-worktree-up fills in.

Workarounds in use today.

  • F5-i. The Decomposition Plan (on branch feature/F5-i-plan at cc3b338; .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 with gh, 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 a grep for AuditService in forge-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. type gains the value manual. A manual WI has tier: none, a new tier value allowed only on manual WIs. 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 in forge-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.
  • FR-2 — New WI fields and status.

    • impl_status gains with-person, used only by manual WIs. A manual WI’s lifecycle is pending → 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 — the origin/main commit 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: manual row 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 a planned manual wave whose run sheets are all approved and whose gates are met (FR-6). The orchestrator:

      1. creates feature/<ticket>-wave-<N> in forge-et-harness from origin/main and 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 runs git fetch -q origin feature/<ticket>-wave-<N>, then takes handoff_sha from git merge-base origin/main origin/feature/<ticket>-wave-<N>;
      2. asks, with AskUserQuestion, who carries out each WI;
      3. writes to the tracker in its own checkout, with the Edit tool:
        • per WI: run_by, handoff_sha (the cut commit), impl_status: with-person and touched_repos: [forge-et-harness];
        • for the wave: status: in-progress;
      4. commits those writes to feature/<ticket>-plan and 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;
      5. 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 pulling feature/<ticket>-plan.

      M1 is a hard boundary, like Stage 13.

    • M2 — close. The orchestrator fetches origin and, for each WI:

      1. checks that the record commits exist: git log <handoff_sha>..origin/feature/<ticket>-wave-<N> -- .forge/plans/<ticket>/<wi-id>-record.md must be non-empty;
      2. reads the record with git show origin/feature/<ticket>-wave-<N>:.forge/plans/<ticket>/<wi-id>-record.md;
      3. 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, whether run_by carried 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.md requires: one dated line at the head of ## Acceptance Criteria pointing at the <wi-id>-record.md files, 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.

    • M3 — open the wave PR. The orchestrator invokes forge-pr-open <ticket> --artifact code --wave <N> (FR-8), then pushes feature/<ticket>-plan, because forge-pr-open commits 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 still in-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-pr does 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-progress wave) 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, runs git 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 after handoff_sha) → re-create the branch from origin/main as M1 does, keep handoff_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’s git log is empty → the person has not recorded yet. If the local plan branch is ahead of origin (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 between gh pr create and its step 5.
    • The last wave merged. The top-level Resume Protocol gains a row: “phase: dev, decomposed, every wave merged → Stage 15”. Stage 15’s Step 1b already flips dev → 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 to merged before 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 planned manual wave reaches M1 through wave selection (FR-6), not through this table.
    • Stage 0. Stage 0 reconciles a manual WI 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-person WI is never reset to pending or re-dispatched. The “dispatched with nothing pushed” heal applies to dispatched only.
      • A manual WI at pr-open or 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_merge is on), so after the merge only the PR remains.
  • FR-6 — Per-wave gates. waves[].gate is an optional list. Each entry is exactly one of these kinds, plus a one-line means: that is printed while waiting:

    Kind Shape Met when How it is evaluated
    Feature phase {feature: F5-k, phase: [done]} that feature’s phase on main is one of those listed git fetch -q origin, then git show origin/main:.forge/tracker.yaml | yq '.features["F5-k"].phase', from the harness checkout. It reads main, never the orchestrator’s own checkout, which may be behind
    Wave 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 merged flag reaches main late
    PR merged {pr_merged: {repo: forge-et-be, number: 72}} that PR’s state is MERGED gh pr view 72 --repo <github_org>/forge-et-be --json state --jq .state
    Text on main {on_main: {repo: forge-et-be, path: src/main/resources, contains: "crm01@empire.lk"}} origin/main of that repo has that text under that path git -C "$WS/<repo>" fetch -q origin, then git -C "$WS/<repo>" grep -q -F -e "$GATE_TEXT" origin/main -- "$GATE_PATH", with the values passed as quoted variables, never pasted into the command

    Reading a wave’s PR state — defined once in forge-deliver.md and used by the wave_merged gate, 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:

      • OPEN if any PR is open;
      • otherwise MERGED if any PR is merged;
      • otherwise CLOSED if 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, not CLOSED.

    Validation, before anything runs. The orchestrator validates every value first:

    • feature must be an existing tracker key;
    • wave and number must be positive integers;
    • repo must be one of the delivery repos;
    • path must not start with -, contain .. or contain a newline;
    • contains must contain no newline;
    • phase values 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 → done in one session on the plan branch, so on main a feature goes straight to done. A feature-phase gate therefore means “that feature is closed”, which is later than “its code is on main”. For the code itself, use on_main or wave_merged.

    Behaviour.

    • Wave selection — one rule.
      1. If every wave is merged, go to Stage 15, whose Step 1b flips dev → review.
      2. Otherwise, pick the lowest-numbered wave that is not merged and whose depends_on waves are all merged.
      3. If that wave has plans at backlog, draft or in-review, run Steps 1–3 for it whatever its gates say. A gate never blocks plan authoring or review.
      4. 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.
    • 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, MERGED in every repo → merged). This replaces its current gh 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 whose touched_repos union is empty. As written today, “all MERGED” is vacuously true over an empty list. It computes the union with the map-keyed lookup yq '.features["<ticket>"].waves[] | select(.wave == <N>) | .workitems[].touched_repos[]', because features is a map keyed by id.
  • FR-8 — /forge-pr-open --wave handles a harness-only wave. For a manual wave, /forge-pr-open --wave:

    • resolves REPO_PATH for forge-et-harness to the harness checkout, which is only used for git fetch and gh. gh pr create --head needs no checkout of the wave branch;

    • skips per-WI PR closing, because manual WIs have none;

    • uses a manual-wave PR body that lists each WI, its run_by and 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-open and each WI’s impl_status: wave-closed are 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_REPOS union;
      • the wave-status write;
      • the WI loop;
      • the per-WI branch and touched_repos reads inside the loop;
      • the impl_status write.

      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-closed while their per-WI PRs stay open.

    For every wave, /forge-pr-open --wave refuses an empty touched_repos union, 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-author gains a run-sheet case for type: manual. It fills the FR-1 sections and writes no test table.
    • .forge/plans/_TEMPLATE-plan.md notes which sections a run sheet fills and how.
    • .claude/rules/plans.md changes for type: manual:
      • it accepts “none — person-run” in ## Decisions, ## Risks and ## Test Approach;
      • it says ## Approach holds one short paragraph: what the run proves and against which real system.
    • 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.md and specs.md point at that sentence rather than restating it.
  • FR-10 — /forge-wave-decompose proposes 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: manual and tier: 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_main or wave_merged over 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 manual WI’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.
  • FR-11 — The Decomposition Plan template.

    • ## Workitem Inventory documents type: manual and tier: none.
    • ## Workitem Dependency Graph notes that a manual wave holds only manual WIs, with no within-wave depends_on.
    • ## Test Strategy Map shows tier: none.
    • ## Wave Ship Plan gains a Gate column (— 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 Checklist gains two items: manual waves are all-manual, with run sheets; every soft dependency is a gate.
    • The tracker’s waves[].gate is authoritative. The Gate column is a mirror, written by /forge-wave-decompose.
  • FR-12 — plan-reviewer gains two §11 checks and the run-sheet reading.

    • WS-9 — manual-wave validity.
      • Blocker:
        • a manual WI shares a wave with a non-manual WI;
        • a manual WI has a within-wave depends_on;
        • a manual WI’s run sheet lists a file outside forge-et-harness.
      • 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.
    • 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 Gate column.
      • 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.
  • FR-13 — The orchestrator’s own Notes, the tracker schema, and metrics.

    • forge-deliver.md Notes. Two lines are updated: “emits no inline yq -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_status with-person and pr-open, the wave’s status: in-progress, M2’s ticks, and the last_updated bump every tracker write carries. Edit-tool writes are not flock-guarded, like the existing Step 3 writes.
    • The tracker schema. The schema comment block in .forge/tracker.yaml and .claude/rules/tracker.md document type: manual, tier: none, impl_status: with-person, run_by, handoff_sha and waves[].gate. The gate kinds are documented by reference to forge-deliver.md. The same edit fixes the block’s wave status list to planned | in-progress | pr-open | merged: it omits in-progress, which /forge-deliver already writes.
    • The metrics README. .forge/metrics/README.md documents:
      • a wi_handed_off event, written at M1;
      • tier: none;
      • a wave_kind: manual field on wave_pr_opened and wave_merged.
    • Two exemptions for manual waves. In forge-deliver.md, Stage 12b skips tier: none WIs: 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.html scores with-person in WI_IMPL_SCORE the same as dispatched: one third, so a manual wave’s meter moves.
    • Nothing else changes. No other dashboard code reads WI type or tier. grep -n "impl_status\|\.type\|\.tier" .forge/dashboard/index.html finds only WI_IMPL_SCORE, its use in wiCompletion, and an unrelated c.type (checked 2026-09-27; the implementer re-runs it).
  • 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.md lists the places the enums are restated; the implementer re-runs it.

    • Known hits:
      • forge-deliver.md: the specialist table, the impl_status enum note in Stage 11, and the Notes;
      • forge-wave-decompose.md step 5.e;
      • forge-plan-author;
      • forge-pr-open;
      • plans.md;
      • forge-test-verify’s wi_type enum;
      • .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-verify gains one line saying manual WIs never run it;
      • the agent prompt template needs no change, because a manual WI is never dispatched.
  • FR-16 — Records.

    • .forge/lessons.md gains an entry (Sync target: upstream).
    • .forge/design/README.md lists the new harness/ 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 manual WI is left at pending and 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 manual WI’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 manual WI and no gate behaves exactly as it does today. Every existing tracker entry stays valid without edits: gate is 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.

Acceptance criteria

  • [ ] AC-1 (FR-1, FR-2, FR-13) The tracker schema block and .claude/rules/tracker.md list type: manual, tier: none, impl_status: with-person, run_by, handoff_sha and waves[].gate, and the wave status list includes in-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 manual row.
  • [ ] AC-3 (FR-4, FR-5) forge-deliver.md has:

    • M1–M3, with D-5’s single tracker home, the record file, the $WS worktree path, the touched_repos write and the --no-implement skip;
    • the manual first row in the sub-state table, with its git fetch before evaluation; the “every wave merged” 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.

  • [ ] 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 --wave override with its audit entry;
    • has Stage 14’s re-entry to wave selection, its PR-state read through gh pr list … --head … (not gh pr view --head), and the empty-touched_repos refusal using the map-keyed lookup.
  • [ ] AC-5 (FR-8) forge-pr-open’s --wave process:

    • resolves REPO_PATH for the harness;
    • skips per-WI PR closing for manual WIs;
    • 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_repos union.
  • [ ] AC-6 (FR-9, FR-10, FR-11) forge-plan-author, _TEMPLATE-plan.md, plans.md, forge-wave-decompose.md and _TEMPLATE-decomposition-plan.md carry:

    • the run-sheet case;
    • the detection and gate steps;
    • the Gate column 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.md has:

    • 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.md Notes are updated;
    • the metrics README documents wi_handed_off, tier: none and wave_kind;
    • Stage 12b and the ledger check carry their exemptions;
    • WI_IMPL_SCORE has with-person;
    • the dashboard renders a tracker containing a with-person WI without error. Check this by regenerating the dashboard data from a scratch copy of the tracker with one such WI, then opening the page.
  • [ ] AC-9 (FR-15, NFR-5) The FR-15 grep shows 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 main and F5-i’s on feature/F5-i-plan at cc3b338 are 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.

    • 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 hygiene CI is green. The generators are:

    • python3 .claude/lib/harness-graph.py --convention
    • node .claude/lib/render-docs-html.js
    • bash .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.md and .claude/rules/specs.md (one pointer).
  • Templates: .forge/plans/_TEMPLATE-plan.md and .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 verify or e2e. 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 a manual WI 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 .claude use it; they are found with grep -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-estimate excluding manual or gated waves from its cycle medians. The wave_kind field (FR-13) makes it possible; changing the estimator is a follow-up.
  • Upstream forge-harness itself. 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 --wave override 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_repos was 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.md file, 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 to forge-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 pending row are dropped.
    • Gate kinds (FR-6). wave_merged is 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 the flock claim for Edit-tool writes.
    • F11-a’s gate (AC-11). It is re-expressed as on_main on AuditService.
  • 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 merged flag reaches main late; 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 wave merged” 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 invalid gh pr view --head.
    • FR-8 (forge-pr-open). The three tracker lookups in forge-pr-open step 5 are pinned to the map-keyed form.
    • FR-9 (run sheets). FR-9 covers ## Approach and 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_merged gate, Stage 0 and Stage 14.
    • forge-pr-open lookups (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, in tracker.md; specs.md joins 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-wave depends_on”. The wave’s depends_on carries 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 feature value must match ^[A-Za-z0-9-]+$, and yq reads it with strenv, 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-open step 1 also aborts on with-person;
      • the wave-PR body gains the Gate column;
      • app-repo REPO_PATH is $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.
  • Why: the independent review of the implementation diff (0 Blockers, 2 Important, 3 Nits). It found the two depends_on wordings, 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 --heads before the worktree 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-person whose wave branch is missing from the remote: re-create it from origin/main when 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 after handoff_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-person row says the manual sub-states handle a missing wave branch.
  • Why: F5-i finding F-007 (.forge/specs/F5-i-findings.md). feature/F5-i-wave-2 had no commits of its own and was deleted from the remote before the person pushed the record. It was re-created by hand from origin/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.md row 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.

Generated from .forge/design/harness/person-run-work-items.md by .claude/lib/render-docs-html.js. Markdown is canonical.