source: .forge/design/harness/forge-deliver-f38-follow-ups.md · generated — edit the markdown, not this file
#/forge-deliver after F38 — main-session work items, dispatch re-reads, the forge-et-iaac route and status checkpoints — Design
Status: in review — implemented in the same PR; the lead approves it by merging
Author: Tharinda Rajapaksha (drafted by Claude in the lead’s session)
Reviewed by: one fresh-context pass of the first draft, 2026-10-27 (.claude/CLAUDE.md § Compounding Engineering, item 6): 0 Blockers, 11 Important, 6 Nits — every Important fixed (Stage 0 rows named instead of counted; the checkpoint’s exits, its open-PR case and its skip rule narrowed; the empty commit dropped and /et-cleanup taught to keep a live wave branch; the re-read made to catch late-merged PRs and to stop repeating after a confirmation; resume paths for main-session and stacked WIs; waits_on_pr validated; who sets the new fields), and the Nits applied; then a verification pass of those fixes (9 closed, 1 partly; 2 new Important — completion marks reaching main early, now D-14a with a tracker.md exception, and the main-session Stage 0 row’s precedence — both fixed, with the same-day re-read gap and the Nits)
Date: 2026-10-27
Scope: the delivery harness itself — .claude/commands/forge-deliver.md (Stage 0, Stage 7, the manual sub-states, Stage 13, a new status-checkpoint step), .claude/lib/cleanup.sh (one remote-branch rule), .claude/rules/tracker.md § Workitem decomposition, plan-reviewer WS-9, .claude/CLAUDE.md § Active Context, and .forge/owed.md (four rows close)
#Context
The F38 cloud bring-up ran several work items (WIs) that /forge-deliver had no route for, and each feature wrote its route into its own Decomposition Plan’s ## Notes instead. Four .forge/owed.md rows asked for the harness to take them over; a fifth problem was raised by the developer on 2026-10-26:
- A
sub WI that must run in the main session (owed row “Let /forge-deliver run a work item in the main session”). F38-d WI-6.1 and WI-7.1 changed dev, ECR and PR descriptions, and each write needed the lead’s approval at the time. A background agent cannot ask, and Stage 7 Step 3 dispatches every approved sub WI to one. The route used instead is in .forge/plans/F38-d/F38-d-decomposition-plan.md § Notes, “How WI-6.1 and WI-7.1 run in the main session”; it worked twice.
- A plan gone stale while its wave waited (owed row “Make
/forge-deliver re-read a gated plan’s target files at dispatch”; lesson L-236). F38-d WI-4.1’s four task-definition values were set on main by forge-et-be#300 while its wave waited on a gate; only the orchestrator’s own re-read caught it before dispatch.
forge-et-iaac WIs (owed row “Give /forge-deliver a route for a forge-et-iaac work item”). forge-worktree-up, Stage 11 and forge-pr-open --wave handle only repos that branch from main; forge-et-iaac branches from dev. F38-b, F38-d and F38-h used a hand route (.forge/plans/F38-b/F38-b-decomposition-plan.md § Notes, “How WI-1.1 runs in forge-et-iaac”). F38-h wave 3 added a case the route did not cover: an forge-et-iaac WI stacked on an earlier wave’s unmerged branch ends at the push with no PR, which Stage 0 reads as an agent that died.
main lags the live state. Once a feature’s plan PR has merged, its tracker row, run sheets, records and decisions are written on the live harness wave branch (Stage 0 Step 0a, lesson L-086) and reach main only when that wave’s PR merges — after a person’s manual run, or after another repository’s review. On 2026-10-26 four F38 features had state that main did not show, and a reading of main reported paused work that had been restarted and run sheets that were already approved and handed off. The developer asked for main to show the current state, with each wave picking up where it left off once its blocker clears. forge-et-harness#969 made a one-time checkpoint of those four branches; this design makes it standing.
- The Active Context in
.claude/CLAUDE.md still named F38-a → F38-b → F38-d as the critical path (owed row “Bring .claude/CLAUDE.md’s Active Context up to date after F38-d closed”). This is a text correction, made in the same PR, with no design decision.
#Decisions
#A — A sub WI run in the main session
| # |
Decision |
Why |
| D-1 |
run_by: main-session on a type: sub WI marks it as run by the orchestrator’s own session, not a background agent. The developer sets it by hand at decomposition (the tracker and the Decomposition Plan’s inventory) and writes the plan header “Not dispatched — run by the main session; ask before each write”, because /forge-wave-decompose and forge-plan-author do not set them. run_by keeps its meaning for manual WIs (a person’s name); main-session is the only value it takes on a sub WI. |
One field the command recognises, in place of a route copied into each Decomposition Plan. The value is not a person, so it cannot be confused with a manual hand-off. Teaching the two skills to set it can wait until a second feature needs it. |
| D-2 |
Stage 7 Step 3 does not dispatch it. Once its plan is approved and the wave’s gates are met, the orchestrator provisions the worktree as for a dispatched WI (forge-worktree-up from the WI’s base_branch, or the forge-et-iaac route, D-9), sets impl_status: pending → dispatched, and carries out the plan’s subtasks itself, then the finalize skills (/forge-test-verify, /forge-pre-pr-review, /forge-pr-open) as an agent would. Steps 5a onward treat it like any sub WI, and Stage 11 Pass 1 integrates it. Resume: Stage 0 leaves a main-session WI at dispatched alone, and the next run continues it from its plan’s ## Progress. Under --no-implement it is not run. |
Keeps every later stage unchanged: the WI reaches pr-open the same way. F38-d’s hand route cut the branch from the live harness wave branch and fast-forwarded it in; the standard path is used deliberately, so a main-session WI differs from a dispatched one only in who runs it. |
| D-3 |
Each write is asked at the time. Before each subtask that changes anything outside the WI’s worktree (an AWS resource, a GitHub Environment, a PR description, a branch), the orchestrator asks with AskUserQuestion and records the answer in the plan’s ## Progress. Steps that must follow one another within seconds are asked together in one call, each answered on its own. A write found while running that the plan does not list is asked and recorded the same way. |
F38-d wave 6 and 7’s lessons (owed row updates of 2026-10-26). |
| D-4 |
plan-reviewer WS-9 checks it. Blocker: run_by: main-session on a WI that is not type: sub. Important: the plan header lacks the “Not dispatched” line; a subtask that writes outside the worktree does not say so; a step that names a screen or command is not checked to exist. |
A plan that names a screen the app does not have (F38-d W-12) fails in the session, in front of the person approving. |
#B — Re-reading a plan’s target files at dispatch
| # |
Decision |
Why |
| D-5 |
Before each dispatch in Steps 3, 5c and 5e (and before a main-session WI starts), when the plan was approved on an earlier day than today, the orchestrator lists, for each repo in the plan’s ## Files to Modify, the commits that touch a listed file on that repo’s trunk (origin/main; origin/dev for forge-et-iaac) since the trunk as it stood on the from-date: BASE=$(git rev-list -1 --first-parent --before="<from date> 00:00" origin/<trunk>), then git log --oneline "$BASE..origin/<trunk>" -- <files>. The from-date is the plan’s approval date; when the plan’s ## Notes has a “Target files re-read” confirmation, BASE is instead the trunk commit that line names. No trunk commit before the date halts. Files the plan creates have no history and print nothing. |
The owed row named the gated case; any delay between approval and dispatch has the same risk, and a gate is only the usual cause. Same-day dispatch is excluded because the review read those files that day. A base taken on the first-parent line lists a PR whose commits were made before the date but merged after it, which a --since filter on commit dates would miss. |
| D-6 |
Any commit printed halts the dispatch. The orchestrator prints the commits and stops. The developer either re-reviews the plan (/forge-plan-review, with a ## Revisions entry when the plan changes) or confirms the commits do not affect it, which is recorded in the plan’s ## Notes as “Target files re-read at @: do not affect this plan ()”; the next run reads from that commit, so it does not halt on the same commits again (a date alone would list a commit merged that same morning again). |
The orchestrator cannot judge whether another change invalidates a plan; a person decides, and the record makes the decision visible. The owed row asked only for a send-back to review; the confirmation path is added so that an unrelated commit does not force a review. |
#C — The standing forge-et-iaac route
| # |
Decision |
Why |
| D-7 |
The hand route becomes the command’s standing route, written once in /forge-deliver Stage 7 (“Work items in forge-et-iaac”), rather than adding forge-et-iaac to forge-worktree-up, Stage 11 and forge-pr-open. A Decomposition Plan cites it instead of restating it. |
Three features used the same route without failure. forge-et-iaac is the DevOps team’s repository with different rules (no required checks, dev as trunk, every push to dev applies); teaching three skills those rules costs more than one written route. |
| D-8 |
A wave holds forge-et-iaac WIs only (plus their harness halves), never an app-repo WI. |
Stage 11 and forge-pr-open --wave are not asked to mix a dev-based repo with main-based ones (F38-d wave 3’s reason). |
| D-9 |
The route’s steps: the worktree is cut by hand from origin/dev (or from the earlier wave’s branch when the plan stacks it, D-11) on the wave branch’s own name, feature/<ticket>-wave-<N>, at $WS/worktrees/<ticket>/wave-<N>/forge-et-iaac; commits carry git -c user.name=… -c user.email=… taken from the harness checkout’s git config, because a forge-et-iaac worktree has no identity; no skip-CI marker in commits or title; the checks are the plan’s (for Terraform: terraform fmt -check -recursive, then terraform init -backend=false and terraform validate in the overlay, with the version CI uses, each with its exit status); /forge-test-verify records totals: null with that evidence, and Stage 12b harvests the WI’s audit block as for any WI; /forge-pre-pr-review runs on the diff; the PR is one gh pr create --repo <github-org>/forge-et-iaac --base dev --head feature/<ticket>-wave-<N> --body-file <literal path> with --reviewer per .claude/rules/forge-et-iaac.md; no Forge review or Test record (not required there); the tracker writes /forge-pr-open --wave would make are made by hand inside the tracker lock (branch, base_branch: dev, touched_repos, impl_status through pr-open to wave-closed, pr_url, the wave’s status: pr-open); the harness half ships as a harness PR from the harness branch of the same name, opened in the same step as the forge-et-iaac PR, so Stage 14’s per-repo poll finds both; after the merge the forge-et-iaac branch is deleted by hand, because Stage 14’s cleanup reads main. |
Every step is one F38-b, F38-d or F38-h needed (owed row findings (2)–(4) and the F38-b Reflect update). Opening the harness PR with the forge-et-iaac PR closes the gap F38-h wave 1 hit: a wave whose harness side had no PR, on which Stage 14 halts. |
| D-10 |
The merge is a merge commit by anyone with write access after Shyamin Ayesh’s approval (.claude/rules/forge-et-iaac.md); squash and rebase would carry branch commits onto dev without a merge commit. Its post-merge dev.yaml run applies the change; a manual run is asked of the lead first (.claude/CLAUDE.md § ASK FIRST). |
Restates the rule in force so the route is complete in one place. |
| D-11 |
A stacked WI waits on another PR in a state of its own. A forge-et-iaac WI whose branch is cut from an earlier wave’s unmerged branch (a compile coupling, recorded as a --wave override in .forge/engagement-gate-runs.md) is pushed with no PR and gets waits_on_pr: "forge-et-iaac#<number>" in the tracker, naming the PR it is stacked on. Stage 0 validates the value (^forge-et-iaac#[1-9][0-9]*$, passed to gh as quoted variables, never pasted into a command) and treats impl_status: dispatched, branch pushed, no PR, waits_on_pr set as a no-op; while that PR is open, each run exits cleanly with “waits on”. Once it is MERGED, the next run does the rest in the main session, since it is commands, not code: merge origin/dev into the branch, re-run the plan’s checks, open the PR by D-9, make the tracker writes and remove waits_on_pr. A CLOSED base PR halts. |
F38-h wave 3 (owed row update of 2026-10-26): without a state of its own the stacked WI reads as a dead agent and halts every run. |
#D — Status checkpoints to main
| # |
Decision |
Why |
| D-12 |
When. Each time /forge-deliver ends a run that reached Stage 7 — a hard boundary (M1’s hand-off, Stage 13), a halt, or a clean exit on an unmet gate or a stacked WI’s wait — it checks each live harness wave branch of the ticket (Stage 0 Step 0a’s definition). Never on a Step 0-claim halt (the ticket may be someone else’s), any Stage 0 halt including the two-live-wave-branches halt (a person must first decide which state is right), or a halt over a person’s uncommitted changes. A branch with commits not on origin/main gets a checkpoint PR, except when the wave touches only the harness and its harness wave PR is open (it merges on a green Repo hygiene); a wave PR that waits on an app repo’s or forge-et-iaac’s review does not skip it. When an open checkpoint PR already exists for the ticket, the branch is merged into it again instead of a second PR being opened. The plan branch is out of scope: its plan PR is open from the start. |
main then shows the live state whenever a feature is waiting on anything outside the session, including another repository’s review. Checking at exit catches every waiting state without listing them. Reusing an open checkpoint PR keeps it to one CI run per push, not one PR per exit. |
| D-13 |
How. In a worktree of its own, the orchestrator cuts chore/<ticket>-checkpoint-<YYYYMMDD> (a -2 suffix when that name exists) from origin/main, merges the wave branch into it (--no-ff), resolves any conflict on the checkpoint branch only with the resolve-prove-commit rule (.claude/rules/git-conventions.md § Branching: the tracker by hand with the Edit tool keeping every notes entry; append-only logs keeping both sides), runs the Repo hygiene checks locally, pushes, and opens a harness PR titled chore(<ticket>): checkpoint feature/<ticket>-wave-<N> to main whose body names the branch, its head and what the wave is waiting on. The developer who ran the command merges it by hand once Repo hygiene is green, and the run’s closing message asks them to. |
The copy branch leaves the wave branch untouched (a person may be recording in it). /et-cleanup matches a PR by head name and commit, so the checkpoint PR (head chore/…) never stands in for the wave branch’s own PR. Merging by hand follows .claude/rules/git-conventions.md § Pull Requests. |
| D-14a |
Completion marks may reach main early. A checkpoint of a wave waiting on an app repo’s or forge-et-iaac’s review copies marks already on the wave branch (a WI’s wave-closed, ticked success criteria) to main before the code merges. .claude/rules/tracker.md § Update Rules states this as an exception to “Mark completion in the delivering PR”: the wave’s own status stays pr-open on main until its wave PR merges, so a reader takes a WI’s terminal value together with its wave’s status. |
The alternative, leaving code waves at Stage 13 out of the checkpoint, keeps main behind for the whole of another repository’s review, which is the case this design exists for. |
| D-14 |
What does not change. The wave still closes through its own wave PR, opened from feature/<ticket>-wave-<N>; gates (wave_merged), Stage 0 and Stage 14 read wave PRs by that head name, so a checkpoint PR never counts as a wave’s merge. Stage 0 Step 0a still reads the live row from the wave branch, and when the branch carries no tracker write ahead of main it already reads main’s row, which the checkpoint made current. M2 reads the record with git log "$HANDOFF_SHA..origin/<wave branch>", which still finds the record commits after a checkpoint. Code in the app repos and forge-et-iaac is never checkpointed: it reaches its trunk only through its reviewed PR. |
The checkpoint is a copy of state, not a step in the delivery flow. |
| D-15 |
A checkpointed wave branch stays on the remote, and losing it loses nothing. /et-cleanup deletes a remote branch that reached the base through a merge and had no commit for seven days (note 2026-11-06: one day since then, MERGED_IDLE_DAYS in cleanup.sh; the wave-branch exception below is unchanged); after a checkpoint, an idle wave branch (a manual wave waiting days for a person, F38-h waiting on Empire) would qualify. .claude/lib/cleanup.sh therefore keeps a harness feature/<ticket>-wave-<N> branch with no PR under its own name (the app repos’ wave branches are not checkpointed, so the rule does not apply there). If one is deleted by hand, the manual sub-states’ “evidence that a record was pushed” counts only commits not on origin/main, so the branch is re-created from origin/main, which holds the checkpointed records, and the run goes on to M2 when every record is already there; the hand-off block tells the person to git pull --no-rebase before pushing. |
A wave branch exists only while its wave is open (GitHub deletes it when its PR merges), so a wave branch with no PR is live by definition. Without the evidence change, a re-cut branch would halt with a drift report over records that are safe on main. |
| D-16 |
Cost. One Repo hygiene run (about a minute) per checkpoint, at most one per run of /forge-deliver per ticket. |
Within the CI-minutes rule (.claude/CLAUDE.md § ALWAYS DO, AWS bill and CI minutes); a checkpoint happens only when a wave is about to wait. |
#Requirements
- R-1
.claude/rules/tracker.md § Workitem decomposition documents run_by: main-session on a sub WI (D-1) and waits_on_pr (D-11).
- R-2
/forge-deliver Stage 7 Step 3 skips a run_by: main-session WI and a new “Work items run in the main session” block states D-2 and D-3.
- R-3 Steps 3, 5c and 5e, and the main-session block, carry the re-read of D-5 and D-6.
- R-4 A new “Work items in
forge-et-iaac” block in Stage 7 states D-7 to D-11; the specialist table points forge-et-iaac WIs at it.
- R-5 Stage 0’s reconciliation table gains the
waits_on_pr row (D-11) and the main-session row (D-2), and names the rows it defers to instead of counting them.
- R-6 A new “Status checkpoint at every exit” section states D-12 to D-14, and M1, Stage 13 and the halt conditions point at it.
- R-7 The manual sub-states’ evidence rule counts only commits not on
origin/main, and the re-create row goes on to M2 when the records are already there (D-15).
- R-8
plan-reviewer WS-9 checks D-4.
- R-9 The four
.forge/owed.md rows close in the same PR; .claude/CLAUDE.md § Active Context is corrected (Context item 5).
- R-10
.claude/lib/cleanup.sh keeps a remote feature/<ticket>-wave-<N> branch with no PR under its own name (D-15).
#Alternatives considered
- Merge the wave branch itself to
main at each halt. Rejected: GitHub deletes a merged PR’s head branch, which removes a branch a person may be recording in, and /forge-deliver reads a merged wave-branch PR as a finished wave (Stage 14, wave_merged gates).
- Copy only the tracker row to
main. Rejected: the same tracker lines then change on both sides, so the wave PR conflicts on every copied line, and run sheets, records and decisions still lag.
- Add
forge-et-iaac to forge-worktree-up, Stage 11 and forge-pr-open. Deferred, not rejected: worth doing if forge-et-iaac WIs become common outside F38. Three features’ use does not justify the change to three skills yet.