bmad-module-ultracode-goal 3.0.0 → 3.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -8,16 +8,26 @@ Preconditions (asserted, not assumed): you are on the Epic branch (`{workflow.ep
8
8
 
9
9
  **A decomposed child's ATDD run** (the precondition's case above) follows `references/define-done.md` step 2's rule for a decomposed child: under the child's own key, so the checklist the commit guard reads is the child's; the parent's story file read for the text of the parent ACs the child claims, never edited; and, on a halt over vague criteria, an escalation, never a `ucg-create-story` run for the child.
10
10
 
11
- **On resume, re-enter Execute at the first story whose last logged gate verdict is not advance; advanced stories are not re-run; re-assert (do not rebuild) the Epic branch, hooks, the allowlist, the `.mem-state.json` recall latch, and the in-flight story's baseline marker before continuing**, and read the story's recorded turn count before driving it ("Authoring the `/goal` condition" below says when a resumed count escalates instead). Before the next story's step 0, also check whether the last advanced story's gate evidence is still uncommitted, and if it is, make that evidence commit first, exactly as `references/gate.md`'s "Commit the gate's evidence before the next story starts" describes (and when that story advanced with its count at or past the turn ceiling and no sizing note was logged, log it now, per "Promoting the turn-budget marker"): a resume enters here, before Stage 5 is ever loaded, so this is where that rule has to be met. And "re-assert the hooks" means preflight step 5's assertion, not a presence check: both script paths appear in the resolved settings **and** the PreToolUse group's matcher is the all-tools form (`references/preflight.md`, "Arm the PreToolUse group with a matcher that covers EVERY tool"). A presence-only read passes on a prior run's `Bash`-only arming, and a resume that skips Stage 2 never meets the bullet where that requirement lives, so this is the one place it binds a resumed run, and without it the Cross-Session Recall invariant enforces nothing outside Bash for the whole session while every log line says the hooks are armed. The latch is *re-written* by re-running Stage 1's latch step (`references/ingest-and-scope.md`, its `mem_recall.py latch` command) with this invocation's own run id, minted first by Stage 1's convention and logged. A resume never reuses an id an earlier invocation logged: the run's record file is named after it and never rewritten, so a reused id turns this run's Finalize write into `skipped-existing` and loses its record. It is re-written because every terminal removes it with `mem_recall.py unlatch` (Stage 6 at every close-out), and the PreToolUse hook reads an absent latch as "no run active" and stops gating recall entirely. A latch already on disk whose `run_id` is not this run's is **another run's (or a spawning wrapper's) artifact, never evidence**: re-latch from this run's own measurement, which replaces it, and never inherit its `store_ok` colour, because an inherited green latch certifies a store this run never checked. Never delete that latch to make room for this run's: the guard refuses it while a latch is present, and the latch command is what replaces it. The baseline marker is the opposite of the latch, split by which case the resume is, and the test is simply whether `.baseline-<story_id>` exists. **Mid-story (it exists):** *re-read* and never regenerate: the story may already carry commits, and a rebuilt baseline silently re-anchors its evidence range to a mid-story HEAD. **Story boundary (it does not exist**, the NORMAL case under `--max-stories N`, where every invocation after the first resumes at a fresh story): there is nothing to re-read; write it fresh at `HEAD` exactly as step 0 does for a first-run story, because the PreToolUse marker-freshness gate fail-closes without it.
11
+ **On resume, re-enter Execute at the first story whose last logged gate verdict is not advance; advanced stories are not re-run; re-assert (do not rebuild) the Epic branch, hooks, the allowlist, the `.mem-state.json` recall latch, and the in-flight story's baseline marker before continuing**, and read the story's recorded turn count before driving it ("Authoring the `/goal` condition" below says when a resumed count escalates instead). Before the next story's step 0, also check whether the last advanced story's gate evidence is still uncommitted, and if it is, make that evidence commit first, exactly as `references/gate.md`'s "Commit the gate's evidence before the next story starts" describes (and when that story advanced with its count at or past the turn ceiling and no sizing note was logged, log it now, per "Promoting the turn-budget marker"): a resume enters here, before Stage 5 is ever loaded, so this is where that rule has to be met. That story carries an `evidence-commit-rejected` escalation when a repo commit hook rejected that commit in a way the gate may not answer, so run the `--assert-armed` call below with `--story` naming that story first: while its `escalation` reads `open`, make no commit and take the `decision-pending` route below for that story, and once `/ucg-resolve` has closed it (its sidecar is gone, and `.evidence-owed-<story_id>` is still on disk), make the commit and remove that marker. Check every `.evidence-owed-<story_id>` of this Epic's stories this way, not only the last advanced story's: a marker whose evidence was committed some other way is removed as `references/gate.md` says, with no commit. When that story is the Epic's last, so every story reads `done`, no story is left to drive: after the commit go to Stage 6 (`references/finalize.md`) with the Epic-level verdict the log holds, and run neither a story nor the Epic-level gate again. Stage 1 resolved no in-scope story for that resume, so Finalize passes that story as its one `--story` to `scripts/gate_trail.py`, whose range then ends at the commit this resume made, and the run report names the route as the owed evidence commit made and the Epic complete. And "re-assert the hooks" means preflight step 5's assertion, not a presence check: both script paths appear in the resolved settings **and** the PreToolUse group's matcher is the all-tools form (`references/preflight.md`, "Arm the PreToolUse group with a matcher that covers EVERY tool"). A presence-only read passes on a prior run's `Bash`-only arming, and a resume that skips Stage 2 never meets the bullet where that requirement lives, so this is the one place it binds a resumed run, and without it the Cross-Session Recall invariant enforces nothing outside Bash for the whole session while every log line says the hooks are armed. The latch is *re-written* by re-running Stage 1's latch step (`references/ingest-and-scope.md`, its `mem_recall.py latch` command) with this invocation's own run id, minted first by Stage 1's convention and logged. A resume never reuses an id an earlier invocation logged: the run's record file is named after it and never rewritten, so a reused id turns this run's Finalize write into `skipped-existing` and loses its record. It is re-written because every terminal removes it with `mem_recall.py unlatch` (Stage 6 at every close-out), and the PreToolUse hook reads an absent latch as "no run active" and stops gating recall entirely. A latch already on disk whose `run_id` is not this run's is **another run's (or a spawning wrapper's) artifact, never evidence**: re-latch from this run's own measurement, which replaces it, and never inherit its `store_ok` colour, because an inherited green latch certifies a store this run never checked. Never delete that latch to make room for this run's: the guard refuses it while a latch is present, and the latch command is what replaces it. The baseline marker is the opposite of the latch, split by which case the resume is, and the test is simply whether `.baseline-<story_id>` exists. **Mid-story (it exists):** *re-read* and never regenerate: the story may already carry commits, and a rebuilt baseline silently re-anchors its evidence range to a mid-story HEAD. **Story boundary (it does not exist**, the NORMAL case under `--max-stories N`, where every invocation after the first resumes at a fresh story): there is nothing to re-read; write it fresh at `HEAD` exactly as step 0 does for a first-run story, because the PreToolUse marker-freshness gate fail-closes without it.
12
12
 
13
13
  **The cursor passes over a decomposed parent.** A story whose row is `done` and whose split is recorded (its split record (`.split-<key>.json` beside `sprint-status.yaml`) names it, a child row cites the parent ACs it claims, or `.decision-log.md` names it and the ACs each child claims) never gets a gate verdict of its own: its children carry its contract, and on its split record the Epic-level roll-up reads their gates in its place (`references/gate.md`). So it is never "a story whose last logged gate verdict is not advance" in the sense above: pass over it and re-enter at the next story, and never drive it. This is the shape a sizing decomposition leaves (below): the invocation that split the row ends without a verdict, the next one re-enters at the first child, since the child rows sit above the parent's, and once every child has advanced the cursor reaches the parent's row and passes over it. A `done` row with no recorded split is not passed over on this rule; Stage 1 rule 3's `skipped-already-done` log is what keeps a fresh run from re-driving one.
14
14
 
15
15
  **A resume owes the stall check first.** Before the re-assertions below, apply the per-step heartbeat's gap rule (the "Run-status heartbeat" section): when the in-flight story's `.heartbeat-<story_id>` exists and its last line is older than 30 minutes, write the `.stall-<story_id>` line before driving anything — the resume is the only reader positioned to see the gap while its cause is still nearby.
16
16
 
17
- **The re-assertion sweep is one script call, not a tool action per fact.** Run `uv run {skill-root}/scripts/preflight_check.py --assert-armed --project-root {project-root} --impl-artifacts {workflow.implementation_artifacts} --epic-branch-prefix {workflow.epic_branch_prefix} --story <the story about to be driven> --run-id <this run's id> --trace-output {workflow.trace_output_dir}` (plus one `--protected-branch <name>` per protected branch, as Stage 2's step 1 passes them: the prefix and the protected list are resolved scalars, and omitting either would assert the branch against a default the operator may have overridden). Exit 0 asserts the branch, both hooks with the all-tools matcher, the five injected hook env vars, and that `ucg-create-story` and `ucg-dev-story` are still installed (a manual deletion, or a UCG install or update interrupted between removing the UCG skills and copying them back, between spawns, can leave a run without them) in one read, and the `story` block returns the artifact-derived route this paragraph defines: `story-boundary`, `mid-story`, or `gate-owed` (the committed-green-un-gated third case below; the script only ever returns it when `--trace-output` named the run's real, readable trace dir and the artifact evidence held in full, while an unverifiable location reads `unknown` and routes to the ordinary loop, so lack of evidence never skips steps 1 through 4). Three things the manifest deliberately does **not** cover: the latch is **reported, never certified** (whatever the JSON shows, re-latch from this run's own measurement exactly as above); a boundary story's fresh baseline is still written by step 0; and the **allowlist** is neither asserted nor reported (it lives in permission settings the script does not read), so re-assert it exactly as the list at the top of this paragraph requires. A non-zero exit is the resume's RED: fix what the `reasons` name before continuing, and never narrate around it. A fix that writes `.claude/settings.local.json` (a hook, its env, the allowlist) follows `references/preflight.md`'s "A refused settings write" rule if the write, or a call after it, is refused: stop, never work around it, and in headless take the escalation route below for the story about to be driven, naming the refused write. The one reason a resume never fixes is a skills failure (`checks.skills.ok: false`): installing UCG's story skills is the operator's call, so do not run the installer command that reason names, do not substitute another skill (`bmad-build`, `bmad-build-auto`, or BMAD's deprecated `bmad-create-story` and `bmad-dev-story`), and do not hand-author the story or the code. Take the sub-skill halt catch-all's route (below) for the story about to be driven: write `escalation-<story_id>.json` with `decision_needed` quoting that reason, then stop.
17
+ **The re-assertion sweep is one script call, not a tool action per fact.** Run `uv run {skill-root}/scripts/preflight_check.py --assert-armed --project-root {project-root} --impl-artifacts {workflow.implementation_artifacts} --epic-branch-prefix {workflow.epic_branch_prefix} --story <the story about to be driven> --run-id <this run's id> --trace-output {workflow.trace_output_dir}` (plus one `--protected-branch <name>` per protected branch, as Stage 2's step 1 passes them: the prefix and the protected list are resolved scalars, and omitting either would assert the branch against a default the operator may have overridden). Exit 0 asserts the branch, both hooks with the all-tools matcher, the five injected hook env vars, and that `ucg-create-story` and `ucg-dev-story` are still installed (a manual deletion, or a UCG install or update interrupted between removing the UCG skills and copying them back, between spawns, can leave a run without them) in one read, and the `story` block returns the artifact-derived route this paragraph defines: `decision-pending` (the next paragraph), `story-boundary`, `mid-story`, or `gate-owed` (the committed-green-un-gated third case below, or the re-gate a closed `operator-evidence-owed` escalation owes, the fourth case after it; for the third case the script only ever returns it when `--trace-output` named the run's real, readable trace dir and the artifact evidence held in full, while an unverifiable location reads `unknown` and routes to the ordinary loop, so lack of evidence never skips steps 1 through 4). Three things the manifest deliberately does **not** cover: the latch is **reported, never certified** (whatever the JSON shows, re-latch from this run's own measurement exactly as above); a boundary story's fresh baseline is still written by step 0; and the **allowlist** is neither asserted nor reported (it lives in permission settings the script does not read), so re-assert it exactly as the list at the top of this paragraph requires. A non-zero exit is the resume's RED: fix what the `reasons` name before continuing, and never narrate around it. A fix that writes `.claude/settings.local.json` (a hook, its env, the allowlist) follows `references/preflight.md`'s "A refused settings write" rule if the write, or a call after it, is refused: stop, never work around it, and in headless take the escalation route below for the story about to be driven, naming the refused write. The one reason a resume never fixes is a skills failure (`checks.skills.ok: false`): installing UCG's story skills is the operator's call, so do not run the installer command that reason names, do not substitute another skill (`bmad-build`, `bmad-build-auto`, or BMAD's deprecated `bmad-create-story` and `bmad-dev-story`), and do not hand-author the story or the code. Take the sub-skill halt catch-all's route (below) for the story about to be driven: write `escalation-<story_id>.json` with `decision_needed` quoting that reason, then stop.
18
+
19
+ **A re-entry story with an open escalation is not re-entered.** The `story` block also reports `escalation`: `null` when no `escalation-<story_id>.json` exists, and otherwise its `state`. It reads `open` when the sidecar is on disk and the id `/ucg-resolve` keys its answer by (`red_ids.py`'s, minted from the sidecar's own `kind`, `source` and `decision_needed`; a close keyed by the sidecar file's own path, as earlier passes keyed some, counts too) is not closed in `.decisions.json`, or when the sidecar cannot be read or no id can be minted from its fields, and the route is then `decision-pending`, ahead of the other three. `/ucg-resolve` deletes the sidecar when it closes the decision and leaves it in place on a `defer`, so a sidecar still on disk is a decision nobody closed: an answer written anywhere else (the story file, a ruling, the ledger) has not closed it. On `decision-pending`, do not drive or gate the story and write no sidecar: the open one is the record, and the skills, refused-write and turn-ceiling routes in this file each write `escalation-<story_id>.json` and would overwrite it. Attended, show the sidecar's `kind` and `decision_needed`, offer `/ucg-resolve`, and continue only once a fresh `--assert-armed` call no longer reads `decision-pending`. Headless, or when the operator leaves it open, end the invocation `blocked` as `references/gate.md`'s `escalate` does, handing the block's `escalation.blocker` to the headless adapter as the one blocker, so the envelope's `reason` names the sidecar. Two states never set the route: `handoff`, a `story-decomposed` or `defined-not-driven` sidecar, which hands this invocation work to pick up rather than a decision (an `operator-evidence-owed` sidecar is not one of them: `scripts/drive_epic.py` reports it as a handoff, but re-driving the story cannot record the evidence an operator owes, so it routes `decision-pending` until `/ucg-resolve` closes it); and `closed`, a sidecar whose id `/ucg-resolve` already closed, the residue of an answered decision that `/ucg-resolve` would not offer again.
18
20
 
19
21
  **A third case: a story already committed, green and un-gated.** The routing above sorts stories into two classes — re-drive, and do not re-run — and a session that died between its commit and its gate belongs to neither. Recognise it by artifacts, never by prose: the row carries commits past its baseline marker **and** a `.tests-ran-<story_id>` marker whose `baseline=` line still matches that marker, **and** neither `trace-<story_id>.md` nor `gate-decision-<story_id>.json` exists under `{workflow.trace_output_dir}`. That story owes **evidence and a gate, not implementation**. Re-set the `.current-story` pointer (the pointer half of step 0 only — the baseline marker is still re-read, never rewritten), skip steps 1 through 4, and enter at **step 5**, re-measuring the committed HEAD rather than reading the tests-ran marker's numbers back — at FULL scope, since no step 2 ran this session to inherit from — and once green, rewrite the tests-ran marker fresh (same `baseline=` line, `scope=full`) **even on a green first try**: the inherited marker may predate the scope contract or carry a mid-loop `scope=scoped`, and the gate reads the marker THIS session leaves behind, not the dead one's; then continue into Stage 5 as normal. Trust the artifacts and the `sprint-status.yaml` row, never the story file's own prose: such a file routinely carries a close-out asserting a gate `PASS` that no artifact backs, which is precisely the claim this stage does not get to make. **The discriminator must hold in full.** A tests-ran marker with no commits, or commits with no marker, is a story that died before or during the sweep, and it takes the ordinary loop from step 0.
20
22
 
23
+ **A fourth case: a closed `operator-evidence-owed` story owes a re-gate, not a re-drive.** Its FAIL gate left `trace-<story_id>.md` and `gate-decision-<story_id>.json` on disk, so the third case never fires for it. When `/ucg-resolve` closes that escalation, it deletes the sidecar, resets the story's turn counter (waiting for operator evidence is not the story's work) and writes `{workflow.implementation_artifacts}/.regate-<story_id>`, holding `sha=` the assessed commit and `decision=` the closed id. The `story` block reports that marker as `regate`: `null` when there is none, otherwise its `state`. While it reads `fresh` (its `sha=` resolves to `HEAD`) and the baseline marker exists, the route is `gate-owed`: enter exactly as the third case does, re-setting the pointer, skipping step 0's turn-ceiling read and steps 1 through 4, re-measuring `HEAD` at step 5, then re-gating it in Stage 5, whose trace counts the operator's records. Commit nothing before that gate while step 5's re-measure is green, since a commit past the assessed commit makes the records stale. On a red, take step 5's red route (remediate, write a fresh `.tests-ran-<story_id>` marker, re-commit): that commit moves `HEAD` past the assessed commit, so the records no longer count and the `.regate-<story_id>` marker is stale, and the re-gate at the new `HEAD` escalates `operator-evidence-owed` again at the new commit. A `stale` marker (one naming another commit, or no commit id) routes as if it were absent, normally `mid-story`: a later commit already made the records stale. On either route the gate deletes the marker once this story's verdict is logged (`references/gate.md`, "A logged verdict settles an owed re-gate").
24
+
25
+ **A fifth case: a gate stopped between automate and trace.** `preflight_check.py` reads no log, so its `story` block cannot see this case and reads such a story as `gate-owed` or `mid-story`; take this case instead of either, but never instead of `decision-pending`. It takes three forms, each read from the story's `.decision-log.md`:
26
+
27
+ - **A backfill with no verdict after it.** `references/gate.md`'s "When automate backfills" logs `gate-backfill-base:` once automate has finished with a backfill, and `gate-backfill:` once that backfill is committed. When the log holds either line with no verdict logged after it (when it holds both, the later one decides), the story owes the rest of that gate cycle: not a re-drive, and not a second automate pass. Re-set the `.current-story` pointer (the pointer half of step 0 only), skip step 0's turn-ceiling read and steps 1 through 5, and enter Stage 5 at gate.md's "A resume after a backfill does not run automate again", which says at which `HEAD` the case holds and sends a story at any other `HEAD` back to the route the script reports.
28
+ - **A re-loop that ended its cycle before trace.** gate.md's "A red backfill sweep ends the cycle at a re-loop" logs a `reloop` verdict whose JSON holds no `gate_status`, since no trace ran, beside an `assessed-commit:` line. When that is the story's last logged verdict and `HEAD` is still the commit its `assessed-commit:` line names, the re-loop has committed nothing yet, and the story owes that re-loop, not a gate: re-set the `.current-story` pointer (the pointer half of step 0 only), then resume gate.md's `reloop` route where the log stopped, its turn-ceiling check included (the generalize step when this re-loop's `class:` lines are not logged yet, then `bmad-correct-course`, then the story's re-run through the story loop below).
29
+ - **An automate pass with no verdict after it.** gate.md's "A summary already at that name is this cycle's own" logs `gate-automate: <sha>` right before it delegates automate, naming the commit automate measures. When the log holds a `gate-automate:` line with no verdict and no `gate-backfill-base:` or `gate-backfill:` line logged after it (a backfill line after it means the first form applies instead), and that line names the commit `git rev-parse HEAD` prints, the session ended while automate ran, or after it finished but before anything was committed, and the story owes the rest of that gate cycle, not a re-drive. Re-set the `.current-story` pointer (the pointer half of step 0 only), skip step 0's turn-ceiling read and steps 1 through 5, and enter Stage 5 at gate.md's "Backfill the gate evidence", whose paragraph "A summary already at that name is this cycle's own", read before automate is delegated, reuses the pass's summary when it is complete and runs automate again only when the summary is unfinished or absent. When that line names any other commit, the story is not in this form: take the route the script reports.
30
+
21
31
  ## Default — Sequential `/goal` spine
22
32
 
23
33
  ### Sizing: a story too large to drive
@@ -51,9 +61,13 @@ Then terminate as the work-bound section below describes for an invocation that
51
61
  For each in-scope story, in sprint order, run this loop (leave out a decomposed parent: one preflight step 2 set `done` as a container, or a `done` row whose split is recorded, as the resume cursor above passes over):
52
62
 
53
63
  0. **Set the current story and record its baseline commit** — both **before any implementation**, before step 1 touches a single file. (First read the story's recorded turn count, per "Authoring the `/goal` condition" below: a resumed story already at or over the ceiling escalates instead.) First, so the PreToolUse hook can locate this story's marker: write the story id to `{workflow.implementation_artifacts}/.current-story`. Both hooks read the story id from `ULTRACODE_STORY_ID` when their own environment carries it, falling back to that `.current-story` file, and an `export` inside a Bash call never reaches their processes, so the file is the route that works. Skip the write and both hooks keep reading whatever the file last named: no story at all after preflight's purge, so the guard denies every commit and the Stop hook counts nothing, or the previous story, whose markers and counter then stand in for this one's. Then anchor the story: **if `{workflow.implementation_artifacts}/.baseline-<story_id>` is absent, write it now** with the output of `git rev-parse HEAD` — **exactly one newline-terminated line carrying the full 40-hex SHA**. This format is a contract, not a style choice: later stages bound this story's commit range from it and compare it as a verbatim whitespace-stripped string, so a `git rev-parse --short` abbreviation or a write with no trailing newline is a silent breakage, not a cosmetic one. **If the marker is already present, this story is a resume: read it and keep it — never overwrite it.** No later step refreshes it; a multi-commit story must keep the SHA it started from even after HEAD moves. **Scratch build space, if the story needs any.** A story that must build and run a throwaway program to produce a committed artifact puts it in `{workflow.implementation_artifacts}/.scratch-<story_id>/` and nowhere else. Not an improvised repo-root directory — that is one careless `git add` away from being committed, and only step 4's explicit per-path staging would catch it. Not `/tmp` either: it survives no audit, belongs to no run, and buys nothing the run folder does not. What this location buys is containment: the dot prefix and the run folder keep it out of every default source glob and out of the commit. What it does **not** buy is runnability — a headless permission layer gates on command **shape**, not path, so a compound `bash <scratch>/script.sh 2>&1 | tee …`, a `for` loop over gate names, or a `$(…)` substitution can each be refused wherever the file sits. Keep scratch work invocable as one simple command per call, and expect to run its steps as separate calls rather than through one orchestrating script. The directory outlives the step-4 commit **deliberately**: step 5 re-runs the same declared-gate sweep on the committed tree, so a runner or harness built here is still needed there, and one deleted at step 4 gets re-authored verbatim at step 5 — a real, measured cost. **Remove the directory after step 5's re-verify goes green, before the story advances** — never earlier, and never later: the next story's step 0 must not find it.
54
- 1. `ucg-create-story` (if not already current) → `ucg-dev-story` implementing the feature and **un-skipping** the story's ATDD acceptance tests (remove `test.skip()`; **production only**): under `--light` there are no ATDD tests to un-skip, so the DoD is the story's acceptance criteria satisfied with lint and build green. **For a decomposed child row, skip `ucg-create-story` entirely**: the child has no story file and must never get one (running the sub-skill would duplicate the contract, which the sizing conventions above forbid); its owed criteria are its sprint-status row comment plus the parent story file it cites by AC number, and the parent file is read for the AC text only, with its Dev Notes as guidance. Pass both story skills `implementation_artifacts` set to `{workflow.implementation_artifacts}` on every call, so the story file and the sprint-status row they touch are the ones this run reads. Hand `ucg-dev-story` the child's input in place of a story path: `story_key` the child's row key, `parent_story_path` the parent's story file, and `claimed_acs` the parent AC ids the child's row claims, taken from the row as the sizing section above requires. On a re-loop, also hand it `review_findings`: the `reasons` of the gate verdict that sent the child back and the findings of that cycle's reviews, which no review can write into a story file the child does not have. Its "Decomposed Child" section keeps it to those ACs, has it write no story file, and has it move only the child's row (to `in-progress`, then `review`), so the parent's row stays `done` and the parent's file unedited. A halt there over a claimed AC takes the sub-skill halt catch-all's route below, naming the parent ACs concerned: never a `ucg-create-story` run for the child, and never an edit to the parent's file. **On a stack where Stage 3 could not generate the ATDD scaffold** (the non-web case), the story still owes a red phase and it is owed **now, before the first implementation edit**: author the acceptance cases with real assertions, RUN them, and capture that run's raw output to a file under `{workflow.implementation_artifacts}`. `references/gate.md`'s non-web section is the authority on the shape, but by the time that file is read at Stage 5 the window this rule governs has already closed. Before delegating, check the run's `.decision-log.md` for an **Operator notes** entry naming this story (a pre-launch hint like "watch the auth flow in story 3") and surface that note into the `ucg-dev-story` / review context for this story so the operator's last words actually reach the work. Read `{workflow.implementation_artifacts}/.class-ledger-<epic_id>.md` the same way when it exists (the defect classes this Epic's reviews have already caught, appended by the gate's re-loop route, `references/gate.md`) and surface it into the same context: a class named there is a class the reviewers will look for again, and code written blind to it is a re-loop pre-booked. (A story otherwise inherits nothing from its siblings' reviews: a measured run re-found the previous story's review finding on its very first cycle, so the ledger is the one artifact that crosses that boundary.)
64
+ 1. `ucg-create-story` (if not already current) → `ucg-dev-story` implementing the feature and **un-skipping** the story's ATDD acceptance tests (remove `test.skip()`; **production only**): under `--light` there are no ATDD tests to un-skip, so the DoD is the story's acceptance criteria satisfied with lint and build green. The commit guard reads the story's acceptance-test files from the checklist's `generatedTestFiles` frontmatter, so a test file the story adds to hold acceptance cases (a scaffolded file split in two, say) goes into that list as a repo-relative path. **For a decomposed child row, skip `ucg-create-story` entirely**: the child has no story file and must never get one (running the sub-skill would duplicate the contract, which the sizing conventions above forbid); its owed criteria are its sprint-status row comment plus the parent story file it cites by AC number, and the parent file is read for the AC text only, with its Dev Notes as guidance. Pass both story skills `implementation_artifacts` set to `{workflow.implementation_artifacts}` on every call, so the story file and the sprint-status row they touch are the ones this run reads. Hand `ucg-dev-story` the child's input in place of a story path: `story_key` the child's row key, `parent_story_path` the parent's story file, and `claimed_acs` the parent AC ids the child's row claims, taken from the row as the sizing section above requires. On a re-loop, also hand it `review_findings`: the `reasons` of the gate verdict that sent the child back and the findings of that cycle's reviews, which no review can write into a story file the child does not have. Its "Decomposed Child" section keeps it to those ACs, has it write no story file, and has it move only the child's row (to `in-progress`, then `review`), so the parent's row stays `done` and the parent's file unedited. A halt there over a claimed AC takes the sub-skill halt catch-all's route below, naming the parent ACs concerned: never a `ucg-create-story` run for the child, and never an edit to the parent's file. **On a stack where Stage 3 could not generate the ATDD scaffold** (the non-web case), the story still owes a red phase and it is owed **now, before the first implementation edit**: author the acceptance cases with real assertions, RUN them, and capture that run's raw output to a file under `{workflow.implementation_artifacts}`. `references/gate.md`'s non-web section is the authority on the shape, but by the time that file is read at Stage 5 the window this rule governs has already closed. Before delegating, check the run's `.decision-log.md` for an **Operator notes** entry naming this story (a pre-launch hint like "watch the auth flow in story 3") and surface that note into the `ucg-dev-story` / review context for this story so the operator's last words actually reach the work. Read `{workflow.implementation_artifacts}/.class-ledger-<epic_id>.md` the same way when it exists (the defect classes this Epic's reviews have already caught, appended by the gate's re-loop route, `references/gate.md`) and surface it into the same context: a class named there is a class the reviewers will look for again, and code written blind to it is a re-loop pre-booked. (A story otherwise inherits nothing from its siblings' reviews: a measured run re-found the previous story's review finding on its very first cycle, so the ledger is the one artifact that crosses that boundary.)
55
65
  **On a gitignored artifact tree** (`impl_artifacts_tracked: false`, which preflight step 1 reports and a resumed session reads in its `--assert-armed` manifest's `checks`), no test this story writes or un-skips may read a file under that tree, or any other path `git check-ignore` reports, at run time: it does not exist in CI. Point the test at a tracked fixture instead. Preflight step 2 states the rule ("A gitignored artifact tree"); a session that resumed straight into this stage may not have read it.
56
66
 
67
+ **An operator-evidence AC is not `ucg-dev-story`'s to satisfy.** When the story carries an AC tagged `**Gate-ability:** operator-evidence` (`references/define-done.md`, step 1), say so when you hand it the story: that AC is proven at the gate by a live result a person records (`references/gate.md`), so it builds nothing for it and does not hold the story's completion on it. An AC tagged plain `**Gate-ability:** operator` is not one: it is work `ucg-dev-story` builds like any other AC, which a person or a script then verifies.
68
+
69
+ **Get an AC narrowed in writing before committing a case that pins behaviour it forbids.** A stated bound (a case asserting an outcome an AC rules out, because the story keeps that behaviour on purpose) leaves the AC PARTIAL in trace, which reads the AC as written, and no re-loop changes the AC. Narrowing it is the operator's decision, so escalate for it as the sub-skill halt catch-all below does, naming the AC, the behaviour and the narrowing you propose, and commit the case only once the story file states the narrowed AC.
70
+
57
71
  2. Run the tests, lint, and build, and **PRINT the raw output** (pass/fail counts, lint result, build result) into the transcript. **In a monorepo, scope that test run wide enough to catch cross-package regressions** — run the full suite, or the changed package(s) plus everything downstream of them (e.g. an `--affected` set *and its dependents*), not just this story's own package. A story's change can regress a *sibling* package's conformance gate (a cross-package RBAC, ownership, or architecture-boundary check), and a run scoped to only this story's package reports green while that sibling gate is red — deferring the red (and its fix) to a later story or the Epic gate instead of catching it at the story that caused it. This printed evidence is what keeps the run judgeable mid-flight, and what a `/goal` evaluator reads when the operator started one — but it is *evidence*, not the gate. **Once all three go green, write the tests-ran marker** `{workflow.implementation_artifacts}/.tests-ran-<story_id>` — the PreToolUse guard denies the step-4 commit unless this marker exists for the current story, so write it only after a real green run. **That marker must carry a `baseline=<sha>` line** whose value is the verbatim, whitespace-stripped content of `{workflow.implementation_artifacts}/.baseline-<story_id>` written at step 0 — **copied, never re-derived from `git rev-parse HEAD`** at marker-write time. The guard compares the two strings character for character and denies the commit when they differ or when the line is missing, which is what stops a marker written against an older code state from being replayed to satisfy a later commit. Re-deriving the value here instead of copying it is the trap: on a story that commits more than once, HEAD has already moved past the baseline, so a re-derived line denies the story's own second commit. **Write that marker with the Write tool**, after Reading the baseline file and pasting its line unchanged — for the same reason step 4 writes the decision log with Write/Edit. The obvious Bash form, `printf 'baseline=%s\n' "$(cat …/.baseline-<story_id>)" > …/.tests-ran-<story_id>`, is a command substitution that a harness which statically analyses Bash strings refuses outright (the PreToolUse guard permits it; the refusal comes from above). Hand-retyping the forty hex characters instead is precisely the transcription error the freshness clause exists to catch, and its denial says only that the SHAs differ, never that one was mistyped. **The marker carries the sweep's scope beside its baseline** — two more lines, same file: `scope=<full|scoped>` naming which sweep form this green run was (the re-loop rule below is the only thing that ever writes `scoped`; a first pass writes `scope=full`), and — scoped only — `packages=<the resolved package list>` copied from the runner's own printout, never hand-typed. The gate reads the `scope=` line through `gate_eval.py --tests-ran` and caps a scoped cycle's verdict at `reloop` (`references/gate.md`, the sweep-scope AND), which is what stops a scoped sweep from impersonating a full one at the only place the distinction pays.
58
72
 
59
73
  **Scope the sweep on three axes, not one.** Package breadth above is the first; the other two are how a green sweep is most often blind:
@@ -72,7 +86,7 @@ For each in-scope story, in sprint order, run this loop (leave out a decomposed
72
86
  **A repo with commit hooks carries gates this sweep structurally cannot see.** `lefthook` / `husky` / `.git/hooks/pre-commit` jobs — typos, formatters, staged-file linters, clippy — run against the staged index and are reachable from no script you can invoke here. So the step-4 commit attempt is itself part of verification rather than the end of it: a rejection there is expected traffic, not a failure of this sweep. What that rejection does to the tests-ran marker is step 4's problem, and it is not the obvious answer.
73
87
 
74
88
  3. **Production profile only:** `bmad-testarch-test-review`, then `bmad-code-review`. A `CONCERNS`-grade or non-critical finding appends to `{workflow.deferred_work_path}` and the story proceeds. A **P0 / critical FAIL never defers** — re-loop within the turn budget or escalate.
75
- 4. **Commit at green** (one implementation commit per green story; the gate's evidence commit follows inside the same story boundary, per `references/gate.md`'s advance route). The PreToolUse hook blocks a commit on a protected branch, blocks a commit when no "tests-ran" marker exists for the current story, and (its marker-freshness clause) blocks a commit when that marker's `baseline=` line does not match the story's recorded baseline, so step 0 must have set the current story and step 2 must have actually run and written `{workflow.implementation_artifacts}/.tests-ran-<story_id>`, in the format step 2 pins, **in a prior, SEPARATE command**. The guard pre-evaluates the command *string* before it runs, so a marker written by a `printf`/`echo` in the SAME compound command as the commit (e.g. `printf … > .tests-ran-<id> && git commit …`) does not yet exist at hook-eval time and the commit is denied. Write the marker, then commit: two distinct tool calls. **A commit can also be rejected by something that is NOT the guard, and the marker rule inverts there.** A repo-side `pre-commit` hook (lefthook, husky, a plain `.git/hooks/pre-commit`) running clippy, rustfmt, typos or a staged-file linter rejects the commit without moving anything: HEAD is where it was, so the tests-ran marker's `baseline=` line still matches character for character and the guard will wave the retry straight through, carrying evidence collected *before* the fix. The freshness clause keys on the BASELINE, not on the code state, so it cannot see this case by construction. Treat a hook rejection exactly as step 5 treats a post-commit red: remediate, re-run the story's tests/lint/build to green, write a **fresh** `.tests-ran-<story_id>` (same `baseline=` line, still copied and never re-derived; `scope=`/`packages=` re-stated for what the re-run actually was), and only then retry the commit. **Append `.decision-log.md` with Write/Edit, never a Bash heredoc.** Stages 4 and 6 require a log of what happened during the run, and what happened *is* commit behaviour, so the log quotes the verbs. The guard evaluates Bash command strings, and a heredoc carrying that prose is a Bash command string: a line leading with the verb is a verb-leading segment, and backticked identifiers or an apostrophe send the whole segment down the fail-closed matches-anywhere path. Its git gates read **Bash command strings alone**, so writing the log with the file tools removes the collision instead of phrasing around it, and keeps Bash for commands you actually mean to run. Said that way rather than "the guard never sees Write/Edit", because preflight arms the hook for EVERY tool: the hook IS invoked for a `Write`, and it does decide on file tools, but only through its Cross-Session Recall rules, which deny a file-tool call that names the recall store or would change the run latch (`references/preflight.md`). A decision-log append is neither, so the conclusion is unchanged, but a reader who believes the guard cannot see a `Write` and then meets the all-tools matcher will try to resolve the contradiction by narrowing the matcher back, and that leaves the recall rules enforcing nothing. **Once the log is too large to Read affordably, do not Read it.** It grows monotonically, one session's prose per invocation, and both file tools refuse a file that has not been Read in this session, so on a long-running Epic (288 KB by its eleventh invocation) the two sanctioned paths are both closed at once. Compose this session's entry with Write into a NEW sibling file in the run folder, `{workflow.implementation_artifacts}/dlog-slice-<story_id>-<n>.md`, where `<n>` increments per append: the name has to be unique per append, not per story, or a story's SECOND entry finds the slice already on disk and walks straight back into the Read it was escaping; then append it in one Bash call, `cat <slice> >> .decision-log.md`. That command's leading token is `cat`, it carries no backtick, no `$(`, and no verb-leading segment, so the guard makes no decision on it and the prose never enters a Bash command string at all. Keep the slice beside the log rather than deleting it: it is the only per-session copy if the append is ever interrupted. **Stage only the current story's paths.** In production, Stage 3 generated *every* in-scope story's red-phase tests up front, so a sibling story's still-skipped tests can co-reside in the same shared dirs as this story's (one `test/` package may hold two stories' acceptance specs before either commits). A blanket `git add -A` here sweeps those uncommitted sibling tests into this story's commit and pollutes the per-story boundary: stage this story's source + test paths explicitly (`git add <this story's paths>`) instead. The allowlist ships plain `git add` (a prefix covering both `-A` and a scoped `git add <paths>`) so the targeted add needs no extra approval. **Staging is itself a prior, SEPARATE tool call**: `git add <this story's paths>` as one call, then `git commit` as a second: the same two-distinct-tool-calls rule the marker follows, and for the same reason. The guard also denies a commit whose staged index is empty, and a chained `git add … && git commit` has staged nothing at the moment it pre-evaluates that command string, so the chained form is denied even though the add would have worked. `git commit -a` and commit-time pathspecs (`git commit <paths>`) are unsupported inside the story loop for exactly that reason. (Under `--light` no ATDD tests are generated, so the collision cannot arise.) **Once the commit lands, record the story's END sha.** Write `{workflow.implementation_artifacts}/.commit-<story_id>` with the output of `git rev-parse HEAD`, in exactly the format step 0 pins for the baseline: one newline-terminated line carrying the full 40-hex SHA. Unlike the baseline, **this marker is refreshed, not preserved**: step 5 rewrites it after any remediation re-commit or amend, and the gate's advance route rewrites it after its evidence commit, so it always names the story's last commit rather than its first. It exists to close the story's commit range explicitly: without it the evidence trail has to *infer* a range end from the NEXT story's baseline marker, and a later story anchored at this story's own SHA collapses that range to `X..X`, so a story that did commit renders as having committed nothing.
89
+ 4. **Commit at green** (one implementation commit per green story; the gate's evidence commit follows inside the same story boundary, per `references/gate.md`'s advance route, and when the gate's `bmad-testarch-automate` backfills a test, a commit of that backfill comes before it, per gate.md's "When automate backfills"). The PreToolUse hook blocks a commit on a protected branch, blocks a commit when no "tests-ran" marker exists for the current story, and (its marker-freshness clause) blocks a commit when that marker's `baseline=` line does not match the story's recorded baseline, so step 0 must have set the current story and step 2 must have actually run and written `{workflow.implementation_artifacts}/.tests-ran-<story_id>`, in the format step 2 pins, **in a prior, SEPARATE command**. The guard pre-evaluates the command *string* before it runs, so a marker written by a `printf`/`echo` in the SAME compound command as the commit (e.g. `printf … > .tests-ran-<id> && git commit …`) does not yet exist at hook-eval time and the commit is denied. Write the marker, then commit: two distinct tool calls. **A commit can also be rejected by something that is NOT the guard, and the marker rule inverts there.** A repo-side `pre-commit` hook (lefthook, husky, a plain `.git/hooks/pre-commit`) running clippy, rustfmt, typos or a staged-file linter rejects the commit without moving anything: HEAD is where it was, so the tests-ran marker's `baseline=` line still matches character for character and the guard will wave the retry straight through, carrying evidence collected *before* the fix. The freshness clause keys on the BASELINE, not on the code state, so it cannot see this case by construction. Treat a hook rejection exactly as step 5 treats a post-commit red: remediate, re-run the story's tests/lint/build to green, write a **fresh** `.tests-ran-<story_id>` (same `baseline=` line, still copied and never re-derived; `scope=`/`packages=` re-stated for what the re-run actually was), and only then retry the commit. This rule binds the story's own commits: this step's, and any re-commit or amend step 5 makes. The gate's two commits keep their own rules in `references/gate.md`: "When automate backfills" reads a hook rejection of its commit of a test `bmad-testarch-automate` backfilled as its backfill sweep's red, which it fixes only in the backfilled test files and otherwise ends the cycle at a re-loop, and the advance route says how to answer a hook rejection of its evidence commit. **Append `.decision-log.md` with Write/Edit, never a Bash heredoc.** Stages 4 and 6 require a log of what happened during the run, and what happened *is* commit behaviour, so the log quotes the verbs. The guard evaluates Bash command strings, and a heredoc carrying that prose is a Bash command string: a line leading with the verb is a verb-leading segment, and backticked identifiers or an apostrophe send the whole segment down the fail-closed matches-anywhere path. Its git gates read **Bash command strings alone**, so writing the log with the file tools removes the collision instead of phrasing around it, and keeps Bash for commands you actually mean to run. Said that way rather than "the guard never sees Write/Edit", because preflight arms the hook for EVERY tool: the hook IS invoked for a `Write`, and it does decide on file tools, but only through its Cross-Session Recall rules, which deny a file-tool call that names the recall store or would change the run latch (`references/preflight.md`). A decision-log append is neither, so the conclusion is unchanged, but a reader who believes the guard cannot see a `Write` and then meets the all-tools matcher will try to resolve the contradiction by narrowing the matcher back, and that leaves the recall rules enforcing nothing. **Once the log is too large to Read affordably, do not Read it.** It grows monotonically, one session's prose per invocation, and both file tools refuse a file that has not been Read in this session, so on a long-running Epic (288 KB by its eleventh invocation) the two sanctioned paths are both closed at once. Compose this session's entry with Write into a NEW sibling file in the run folder, `{workflow.implementation_artifacts}/dlog-slice-<story_id>-<n>.md`, where `<n>` increments per append: the name has to be unique per append, not per story, or a story's SECOND entry finds the slice already on disk and walks straight back into the Read it was escaping; then append it in one Bash call, `cat <slice> >> .decision-log.md`. That command's leading token is `cat`, it carries no backtick, no `$(`, and no verb-leading segment, so the guard makes no decision on it and the prose never enters a Bash command string at all. Keep the slice beside the log rather than deleting it: it is the only per-session copy if the append is ever interrupted. **Stage only the current story's paths.** In production, Stage 3 generated *every* in-scope story's red-phase tests up front, so a sibling story's still-skipped tests can co-reside in the same shared dirs as this story's (one `test/` package may hold two stories' acceptance specs before either commits). A blanket `git add -A` here sweeps those uncommitted sibling tests into this story's commit and pollutes the per-story boundary: stage this story's source + test paths explicitly (`git add <this story's paths>`) instead. The allowlist ships plain `git add` (a prefix covering both `-A` and a scoped `git add <paths>`) so the targeted add needs no extra approval. **Staging is itself a prior, SEPARATE tool call**: `git add <this story's paths>` as one call, then `git commit` as a second: the same two-distinct-tool-calls rule the marker follows, and for the same reason. The guard also denies a commit whose staged index is empty, and a chained `git add … && git commit` has staged nothing at the moment it pre-evaluates that command string, so the chained form is denied even though the add would have worked. `git commit -a` and commit-time pathspecs (`git commit <paths>`) are unsupported inside the story loop for exactly that reason. (Under `--light` no ATDD tests are generated, so the collision cannot arise.) **Once the commit lands, record the story's END sha.** Write `{workflow.implementation_artifacts}/.commit-<story_id>` with the output of `git rev-parse HEAD`, in exactly the format step 0 pins for the baseline: one newline-terminated line carrying the full 40-hex SHA. Unlike the baseline, **this marker is refreshed, not preserved**: step 5 rewrites it after any remediation re-commit or amend, the gate rewrites it after the commit of a test `bmad-testarch-automate` backfilled (gate.md's "When automate backfills"), and the gate's advance route rewrites it after its evidence commit, so it always names the story's last commit rather than its first. It exists to close the story's commit range explicitly: without it the evidence trail has to *infer* a range end from the NEXT story's baseline marker, and a later story anchored at this story's own SHA collapses that range to `X..X`, so a story that did commit renders as having committed nothing.
76
90
 
77
91
  **Check the record's claims before the commit.** Gate reviews keep finding one shape of defect in the record: a commit message, a code comment or a story sentence that asserts a property the code does not hold, written by the author who just built it. A catch after the commit costs a re-loop, so check between the staging call and the commit call. Write the commit message with Write to `{workflow.implementation_artifacts}/.scratch-<story_id>/message.txt`, and the story-record notes this cycle added (completion notes, a re-loop's notes, File List entries; for a decomposed child, which has no record, the File List and completion notes from `ucg-dev-story`'s step 10 summary; an empty file when the cycle added none) to `record-notes.md` beside it, Reading either first if an earlier session left it, then run:
78
92
 
@@ -86,6 +100,13 @@ The second `--message` is there because the record names files the message may o
86
100
 
87
101
  **Sub-skill halt catch-all.** If any orchestrated sub-skill blocks on interactive input mid-run, treat it as escalate for that story: write the typed escalation sidecar `{workflow.implementation_artifacts}/escalation-<story_id>.json` (shape below, under "Escalation sidecar") and stop; do not answer its prompt blind. A sub-skill that is not installed at all (the Skill tool does not know its name) takes the same route: escalate, and never substitute another skill (`bmad-build`, `bmad-build-auto`, or BMAD's deprecated `bmad-create-story` and `bmad-dev-story` for UCG's story skills) or hand-author the work it would have produced.
88
102
 
103
+ **Waiting spends turns.** The Stop hook counts one turn per response, whatever the response did. A background task's notification (a background command exiting, a background subagent or workflow reporting back, a watch's event) that lands while the session is idle starts a response of its own, so each such wake-up costs a turn even when all it does is say a sweep is still running. A notification that lands while a response is still working can be taken into that response at no cost. A full sweep can outlast a foreground command's time limit, and an attended session often cannot wait for a subagent in the foreground, so the waits in this loop (the step 2 sweep, the step 3 reviews, the step 5 re-verify, Stage 5's assessors) are real. What the run controls is how many wake-ups they cost:
104
+
105
+ - **Make each wait report once.** Start what the next step needs in one response and have it come back as one notification: concurrent commands as one subagent the session waits for, which runs each as its own simple command and reports every exit status in its one reply, and concurrent subagents as one workflow, or as calls the session waits for where it can (a `-p` run can). One compound shell command that starts them together and collects their exit statuses (`&`, `wait`, `$!`, `$?`) is not an option: under `scripts/drive_epic.py`'s default spawn mode, `acceptEdits`, with the default allowlist, Claude Code refuses it before it runs, as step 0 says of compound commands. Separate background tasks each wake the session when they end.
106
+ - **Watch for completion, not progress.** A watch that emits an event per log line or per stage wakes the session on every event. Add no background wait command beside a task that already reports when it ends, and schedule no wake-up only to check progress.
107
+ - **Spend a wake-up on work.** A wake-up while the next step still needs a running task is a turn spent whatever it does, so do in it the work that does not depend on that task (record the finished result, prepare the next command).
108
+ - **Keep another story's work off this story's count.** The hook books every Stop to the story `.current-story` names, so a background task for another story (refining the next one, say) started while this one is current spends this story's turns. Start such work in that story's own loop, once its step 0 has made it current.
109
+
89
110
  ### The per-invocation work bound (`--max-stories N`)
90
111
 
91
112
  When the operator passed `--max-stories N`, count the stories this **invocation** has taken all the way to a Stage-5 verdict, and once that count reaches N with in-scope stories still remaining, leave the spine and go to Stage 6. **Not "as if the Epic had run out of stories" — it has not.** The Epic-level trace gate is triggered by `references/gate.md`'s own condition (*every* story of the Epic is `done`), which a bounded stop leaves false, so that gate does not fire and Stage 6 must not author one: an Epic-level PASS over an Epic that still owes stories is precisely the misrepresentation `gate.md`'s partial-by-design exception exists to prevent. That sentence has one boundary case it must not swallow: **when the bounded lap drives the Epic's last in-scope story, the bound never fires** — its trigger is "N reached *with in-scope stories still remaining*", and none remain — so that invocation is an ordinary Epic completion: every story is `done`, `gate.md`'s own condition holds, and the Epic-level gate runs normally. Under `--max-stories 1` driving this is how every Epic ends, so reading this paragraph as "a bounded invocation never runs the epic gate" skips the roll-up on the one invocation that earned it.
@@ -98,7 +119,7 @@ When the operator passed `--max-stories N`, count the stories this **invocation*
98
119
 
99
120
  **An invocation can also finish having done durable work and advanced no row** — it decomposed an oversized story (above), or spent its budget authoring a story definition a resume will drive next. Neither is `complete`: no story reached a Stage-5 verdict, and `complete` with zero rows advanced is indistinguishable in the envelope from a run that drove its story successfully. Neither is a failure either.
100
121
 
101
- Emit **`blocked`**, and carry the distinction in the typed escalation sidecar rather than in a new status value: `kind` is `"story-decomposed"` for a split or `"defined-not-driven"` for an authored-but-undriven story, `decision_needed` names what the next invocation should pick up, and `evidence` names the artifacts written. `kind` is open vocabulary by design (see "Escalation sidecar"), so this invents nothing. `scripts/drive_epic.py` reads those two kinds and reports the stop as a **handoff** rather than a bare halt — it still stops, and still exits non-zero, because a human does need to look at a decomposition before the drive continues.
122
+ Emit **`blocked`**, and carry the distinction in the typed escalation sidecar rather than in a new status value: `kind` is `"story-decomposed"` for a split or `"defined-not-driven"` for an authored-but-undriven story, `decision_needed` names what the next invocation should pick up, and `evidence` names the artifacts written. `kind` is open vocabulary by design (see "Escalation sidecar"), so this invents nothing. `scripts/drive_epic.py` reads those two kinds, and `operator-evidence-owed` (`references/gate.md`), and reports the stop as a **handoff** rather than a bare halt. It still stops, and still exits non-zero, because a human does need to look at a decomposition, or record the evidence, before the drive continues.
102
123
 
103
124
  `scripts/drive_epic.py` is the intended caller: it spawns one `claude -p` per story under `--max-stories 1`, deleting the pinned `run-result.json` before each spawn so the file's presence means *that* spawn reached a terminal, and it stops the drive if a session reports `complete` without its story having advanced to `done`. That last check is only sound because Stage 5's `advance` route **writes** the `done` row itself (`references/gate.md`) — the sub-skills leave a passing story at `review` or `in-progress`. If that sync is ever dropped, the driver's progress check goes with it: an unattended loop would read a healthy advance as no progress and halt.
104
125
 
@@ -109,7 +130,7 @@ Emit **`blocked`**, and carry the distinction in the typed escalation sidecar ra
109
130
  **The conductor cannot start `/goal` itself.** It is a built-in slash command with no tool surface, so in an attended session, a `-H` session or a `drive_epic.py` spawn alike, a `/goal` is active only when the operator started one (typing `/goal <condition>`, or launching `claude -p "/goal …"`). Write the condition below either way, and record it in `.decision-log.md` at step 0 as the story's contract. When an operator did start a `/goal`, at launch or mid-session, that loop runs on the operator's own condition, not this one, and a turn clause in it bounds the session rather than the story. Keep it **under 4000 characters**, encoding the per-story Definition-of-Done as the success criterion with an explicit escape clause. The condition must:
110
131
 
111
132
  - State the DoD in checkable terms: ATDD acceptance tests for the story un-skipped and **passing** (production) — or, under `--light`, the story's acceptance criteria demonstrably satisfied — plus lint clean, build green, and (production) test-review + code-review passed — mirroring the printed evidence so the transcript-only evaluator can corroborate it.
112
- - Include the literal escape: **"…or stop after {workflow.max_turns_per_story} turns."** It belongs in the story's written contract, but it bounds nothing on its own, since no `/goal` runs on this condition. The only turn count every session keeps is the one the `budget_stop.py` Stop hook records in `{workflow.implementation_artifacts}/.budget-<story_id>.json` (`run-status.json` copies it into `budget_used.turns`, and when the two disagree the hook file wins). It advances once per Stop, that is once per response the session ends, so it cannot see re-loops spent inside a single response. Read it, never a count of your own, at two points. **Before a story's step 0** on the `story-boundary` and `mid-story` resume routes: a resume can inherit a counter already at or over `{workflow.max_turns_per_story}`, and then you escalate instead of driving that story (write `escalation-<story_id>.json` with `kind` `budget-overrun`, the kind `/ucg-resolve` resets the counter for, and end the invocation `blocked`, as `references/gate.md`'s `escalate` does). A `gate-owed` story is exempt and goes straight to step 5 and the gate, because its work is already committed. **Before each re-loop**, where `references/gate.md` turns a re-loop that would exceed the ceiling into `escalate` (a cap-only re-gate, which re-measures without re-driving, excepted). The hook itself only records and warns (a Stop hook **cannot force `/goal` to halt mid-condition**, and it never blocks), and the marker it writes on an overrun becomes an escalation only as described below: a story that then advances at its gate gets a sizing note instead. In a single attended or `-H` session with no operator `/goal`, nothing bounds re-loops spent inside one response; for `drive_epic.py` spawns, the `--session-timeout` wall clock is the backstop that holds whatever the count says (unless it is set to `0`). State the clause anyway.
133
+ - Include the literal escape: **"…or stop after {workflow.max_turns_per_story} turns."** It belongs in the story's written contract, but it bounds nothing on its own, since no `/goal` runs on this condition. The only turn count every session keeps is the one the `budget_stop.py` Stop hook records in `{workflow.implementation_artifacts}/.budget-<story_id>.json` (`run-status.json` copies it into `budget_used.turns`, and when the two disagree the hook file wins). It advances once per Stop, that is once per response the session ends, so it cannot see re-loops spent inside a single response. It counts responses, not work: a response that only acknowledges a background task's notification counts the same as one that edits code, so a story's waits spend its ceiling too ("Waiting spends turns" in the story loop above says how to keep that small). Read it, never a count of your own, at two points. **Before a story's step 0** on the `story-boundary` and `mid-story` resume routes: a resume can inherit a counter already at or over `{workflow.max_turns_per_story}`, and then you escalate instead of driving that story (write `escalation-<story_id>.json` with `kind` `budget-overrun`, the kind `/ucg-resolve` resets the counter for, and end the invocation `blocked`, as `references/gate.md`'s `escalate` does). A `gate-owed` story is exempt and goes straight to step 5 and the gate, because its work is already committed, and so is a story the fifth resume case's first or third form (a backfill, or an automate pass, with no verdict after it) sends into Stage 5, whatever route the script reports for it, because its gate cycle is already under way. The fifth case's second form reads the count at its re-loop's turn-ceiling check instead. **Before each re-loop**, where `references/gate.md` turns a re-loop that would exceed the ceiling into `escalate` (a cap-only re-gate, which re-measures without re-driving, excepted). The hook itself only records and warns (a Stop hook **cannot force `/goal` to halt mid-condition**, and it never blocks), and the marker it writes on an overrun becomes an escalation only as described below: a story that then advances at its gate gets a sizing note instead. In a single attended or `-H` session with no operator `/goal`, nothing bounds re-loops spent inside one response; for `drive_epic.py` spawns, the `--session-timeout` wall clock is the backstop that holds whatever the count says (unless it is set to `0`). State the clause anyway.
113
134
  - Make explicit that **passing the condition is not completion** — the authoritative verdict is Stage 5's `gate_eval.py`. The `/goal` condition gets a story to a *plausibly* done, evidence-printed state; the gate decides.
114
135
 
115
136
  Keep it under the character limit by referencing the story's `atdd-checklist` (or, under `--light`, its acceptance criteria) and printed test output rather than restating ACs verbatim.
@@ -133,7 +154,7 @@ It is a single JSON object, exactly these four string fields and no fifth:
133
154
 
134
155
  One object, never an array: the file is already named per story, so a list would only re-encode the story id inside a file that carries it in its name.
135
156
 
136
- `kind` is **open vocabulary**. A reader renders whatever string it finds and never validates it against a fixed list — in particular never against the red-kind vocabulary the semantic scan returns in `references/preflight.md`, which classifies *planning-artifact* reds and has no term for anything that happens at run time. `budget-overrun` is a live `kind` and sits deliberately outside that vocabulary; a reader that validated against it would silently drop the most common escalation there is.
157
+ `kind` is **open vocabulary**. A reader renders whatever string it finds and never validates it against a fixed list, in particular never against the red-kind vocabulary the semantic scan returns in `references/preflight.md`, which classifies *planning-artifact* reds and has no term for anything that happens at run time. `budget-overrun` is a live `kind` and sits deliberately outside that vocabulary; a reader that validated against it would silently drop the most common escalation there is. `operator-evidence-owed` is a live `kind` too: the story is delivered and gated except evidence only a person can record (`references/gate.md`). So is `evidence-commit-rejected`: the story advanced, and a repo commit hook rejected its evidence commit in a way the gate may not answer, so that evidence waits, uncommitted, for the operator (`references/gate.md`'s advance route).
137
158
 
138
159
  **Promoting the turn-budget marker.** The `budget_stop.py` Stop hook writes only its own markdown, `{workflow.implementation_artifacts}/.escalation-<story_id>.md`. It stays a recorder: it emits no JSON and starts no process, and its marker records a count without stopping the drive, so the story still goes on to its gate. **Execute is the sole promoter of that markdown, and the story's gate decides whether it promotes.** A marker counts only while the story's recorded count (`turns` in `{workflow.implementation_artifacts}/.budget-<story_id>.json`) is at or past `{workflow.max_turns_per_story}`: after `/ucg-resolve` closes a `budget-overrun` escalation and resets that counter, the marker left on disk is the answered escalation's residue, and nothing below applies to it. **When the gate advances the story (`advance`, or `defer`, whose route advances anyway), do not promote the marker.** The gate decides completion, and none of the decisions the marker asks for has anything left to act on once the story is done: in a real project, every overrun escalation written for a story that then passed its gate was left open and never answered. Log a sizing note in `.decision-log.md` instead, naming the story and the hook's count against `{workflow.max_turns_per_story}`, and saying that a story of this shape should be split smaller next time; Finalize's run report carries it. **When the gate escalates the story on the turn count** (a re-loop that would exceed the ceiling, which `references/gate.md` turns into `escalate`), promote the marker as that escalation's sidecar: read the `.escalation-<story_id>.md` the hook left behind and write the typed sidecar from it, mapping `source` to that markdown's path, `kind` to `budget-overrun`, `decision_needed` to the human decision the marker asks for (re-scope, split, or hand off), and `evidence` to one line quoted from the marker. The gate can escalate on the count before the hook has written a marker (a re-loop expected to take several responses, from a count still under the ceiling); write the same `budget-overrun` sidecar then from `{workflow.implementation_artifacts}/.budget-<story_id>.json`, with `source` that file's path and `evidence` its count, so `/ucg-resolve` still resets the counter when it closes it. A cap-only `reloop` (a sweep-scope or delta cap) is not that verdict: the full re-gate it leads to decides. A story that escalates for its own reason (a gate file that cannot be read, a sub-skill halt) keeps that reason's sidecar, and the marker's count goes into the decision log beside it. A resume that finds the count already at or past the ceiling escalates before step 0 with the same `kind`, as "Authoring the `/goal` condition" above says. Keeping promotion here means one code path produces the typed JSON whatever the escalation's origin, instead of two writers racing on a file three readers depend on.
139
160
 
@@ -171,7 +192,7 @@ As the spine advances — each time you move to a new story, log a gate verdict,
171
192
  "updated": "<ISO-8601 timestamp>"}
172
193
  ```
173
194
 
174
- `last_reasons` and `budget_used` are machine-derived, not narrated. `last_reasons` is the `reasons` array from the `gate_eval.py` result the spine just read, copied across unedited, so a poller sees *why* the last verdict landed instead of only the verdict word; `stories` carries one entry per in-scope story on the same cadence, so an entry appears as soon as the spine reaches that story and its `verdict` stays null until the gate runs. The two `reloop_count`s are deliberately the same name at two nesting levels and are not duplicates: the top-level one is **run-scoped** (every re-loop spent this run), the one inside a `stories` entry is **story-scoped** (that story's own re-loops).
195
+ `last_reasons` and `budget_used` are machine-derived, not narrated. `last_reasons` is the `reasons` array from the `gate_eval.py` result the spine just read, copied across unedited, so a poller sees *why* the last verdict landed instead of only the verdict word (after a re-loop `references/gate.md` logs before trace, in "A red backfill sweep ends the cycle at a re-loop", no `gate_eval.py` result exists, and it is the `reasons` array of the verdict object logged there); `stories` carries one entry per in-scope story on the same cadence, so an entry appears as soon as the spine reaches that story and its `verdict` stays null until the gate runs. The two `reloop_count`s are deliberately the same name at two nesting levels and are not duplicates: the top-level one is **run-scoped** (every re-loop spent this run), the one inside a `stories` entry is **story-scoped** (that story's own re-loops).
175
196
 
176
197
  `budget_used` has exactly two sub-keys and no third: `turns`, copied from the `turns` value in `{workflow.implementation_artifacts}/.budget-<story>.json` that the Stop hook maintains, and `max_turns`, the resolved `{workflow.max_turns_per_story}` — the same value preflight already injects into the hook environment, so the ceiling reported here and the ceiling the hook enforces cannot drift apart.
177
198
 
@@ -24,7 +24,7 @@ Walk every entry **this invocation wrote** (scope, preflight verdict, each gate
24
24
  Produce a report (write it as a peer of `.decision-log.md` in the run folder, e.g. `run-report.md`) covering the list below. **A prior invocation's report already sitting at that path is the NORMAL state, not a surprise**: under `--max-stories N` the run folder persists across invocations, the Write tool refuses a file that has not been Read this session, and on a mature Epic the prior report cannot be Read cheaply either. Do not Read it and do not improvise a name — archive it first with one Bash move to the next free `run-report-<n>.md` (`<n>` increments per archive; list the folder to find the free slot), then write this invocation's report at `run-report.md`. The latest account is always `run-report.md`; the archives are prior invocations' accounts, ordered by `<n>` — one scheme, stated here, instead of one invented per session.
25
25
 
26
26
  - Epic and profile (production / `--light`), branch off `{workflow.epic_branch_prefix}`.
27
- - **The terminal route this run took** — Epic complete, work-bounded, `partial-complete`, handoff, or escalated (the five named at the top of this stage). When the Epic still owes stories, give how many and their ids: under `--max-stories N` the conductor already logged the bound and the carried-over ids to `.decision-log.md` (`references/execute.md`), and a handoff names them in its escalation sidecar. The status word cannot carry this — a work-bounded run ends `complete` — so the report is where a returning reader learns whether the Epic is finished.
27
+ - **The terminal route this run took**: Epic complete, work-bounded, `partial-complete`, handoff, or escalated (the five named at the top of this stage). When the Epic still owes stories, give how many and their ids: under `--max-stories N` the conductor already logged the bound and the carried-over ids to `.decision-log.md` (`references/execute.md`), and a handoff names them in its escalation sidecar. The status word cannot carry this (a work-bounded run ends `complete`), so the report is where a returning reader learns whether the Epic is finished. An `operator-evidence-owed` escalation takes the escalated route even though `scripts/drive_epic.py` prints it as a handoff, because its story reached a Stage-5 verdict: say the story is delivered and gated except the evidence its sidecar names.
28
28
  - Per-story outcome: gate_status and verdict (advance / defer / reloop / escalate), and any re-loops spent against budget. For a story that advanced with its count at or past the turn ceiling, its sizing note: the Stop hook's count against `{workflow.max_turns_per_story}`, which raised no escalation because the gate advanced the story, taken from `.decision-log.md`, or from `{workflow.implementation_artifacts}/.budget-<story_id>.json` when the session ended before the note was logged.
29
29
  - **Gate provenance per story** — `tea` or `hand-authored`, copied from the `gate-provenance:` line Stage 5 logged (`references/gate.md`). Say it per story rather than once for the run: a mixed Epic is the common shape, and a reader who is told only "production profile" cannot tell which stories the model itself supplied the gate file for. If every story reads `hand-authored`, say that in one sentence — an Epic gated entirely on artifacts the run wrote for itself is the single most important caveat on its own report.
30
30
  - The `epic-<id>` row's value in `sprint-status.yaml` at close: `done` only when the Epic-level gate advanced, on an `advance` or on a `defer`, whose route advances anyway (`references/gate.md`). BMAD Method 6.12 has no other writer of that `done`, so never tell the operator `bmad-retrospective` will close the row; it writes only the retrospective row.
@@ -70,7 +70,7 @@ Whichever case applies, repeat in the run report a `NOTE recall-latch-visible` l
70
70
  uv run {skill-root}/scripts/mem_observation.py drain --impl-artifacts {workflow.implementation_artifacts} --store '{workflow.cross_session_recall_store}' --project-root {project-root}
71
71
  ```
72
72
 
73
- 2. **Write this run's record**: epic, run-id (this invocation's own, minted at Stage 1 or at a resume's re-entry and reused verbatim: the record file is named after it), gate-status, verdict, the deferred-work path, any root causes by taxonomy class, and the mechanical `recurred` yes/no for each Stage 1 advisory consumed. Pass no project name: the script takes it from the main worktree's directory, and the store tells repos apart by fingerprint alone.
73
+ 2. **Write this run's record**: epic, run-id (this invocation's own, minted at Stage 1 or at a resume's re-entry and reused verbatim: the record file is named after it), gate-status, verdict, the deferred-work path, any root causes by taxonomy class, and the mechanical `recurred` yes/no for each Stage 1 advisory consumed. Pass no project name: the script takes it from the main worktree's directory, and the store tells repos apart by fingerprint alone. When the run stopped on a story that has no gate status (it escalated or handed off before that story's gate ran, or the gate came back `NOT_EVALUATED`), pass `--gate-status NOT_EVALUATED --verdict blocked`: the script writes that record like any other, so the next run's recall sees that this one blocked. Name a root cause for an escalation as for any blocked run, and none for a handoff. Name none either for a run that stopped on `decision-pending` (a resume that found the re-entry story's escalation still open, per `references/execute.md`): the run that raised that escalation recorded its root cause, and naming it again would make recall count one failure as recurring.
74
74
 
75
75
  ```
76
76
  uv run {skill-root}/scripts/mem_observation.py write --impl-artifacts {workflow.implementation_artifacts} --store '{workflow.cross_session_recall_store}' --project-root {project-root} --epic <id> --run-id <run-id> --gate-status <status> --verdict <advance|blocked> --deferred {workflow.deferred_work_path} [--root-cause class=<taxonomy>,path=<artifact>]… [--advisory sig=<s>,recurred=<yes|no|unknown>]…
@@ -119,13 +119,15 @@ The delegation is hard time-boxed by the `timeout 300` wrapper above and is **no
119
119
 
120
120
  Execute maintains the heartbeat `{workflow.implementation_artifacts}/run-status.json` as the spine advances (shape: `{epic, story, index, total, last_verdict, last_reasons, reloop_count, stories, budget_used, profile, updated}`). At close, write its **terminal** state — the final story/index, the `last_verdict` (`advance` when the Epic completed, the escalating story's verdict when blocked, or the last in-scope story's `advance` for a `partial-complete` run — a deliberate strict subset of the Epic delivered with no Epic-level gate), and a fresh `updated` timestamp — so a poller reading the file after the run sees the settled outcome, not a stale mid-run snapshot. **Write the whole shape, not a subset.** This write overwrites the file, so a narrower object silently strips keys a poller was reading mid-run: carry `last_reasons` and `stories` through from the last heartbeat rather than dropping them off the artifact at the moment the run settles — those two have no fresher source than the snapshot. **`budget_used` does have one, so it is re-derived, never carried**: re-read the final story's `{workflow.implementation_artifacts}/.budget-<story>.json` exactly as every heartbeat write does (execute.md's hook-file-wins rule — "never carry the snapshot's own number forward"). The terminal write is the write most likely to land after turns the last heartbeat never saw — this stage's own — and a carried-forward number under-reports precisely there, in the one direction that matters: a run that ran close to its ceiling reports headroom, and that figure feeds the sizing decisions the next Epic makes. **The enumerated keys are the whole shape.** This file is a single live snapshot, not an accumulating record: do not add a key the shape does not name, and do not carry one forward from an earlier run's write. Dropping an unenumerated key is not narrowing — narrowing loses a key this shape defines and a poller was reading, whereas an unenumerated key has no reader (`scripts/status_render.py` renders exactly these keys and ignores anything else) and no consumer may pin against it (`docs/_internal/STABILITY.md` places this file outside the consumable contract).
121
121
 
122
+ A run that stopped on an `evidence-commit-rejected` escalation keeps that story's `advance` as `last_verdict`, since the story advanced, so its terminal `last_reasons` carries one reason naming that story's `escalation-<story_id>.json` and saying its gate evidence is not committed: without it, the last story's stop would read exactly like a completed Epic. The resume that later makes that commit replaces those reasons with one naming the commit it made, rather than carrying the blocked run's forward.
123
+
122
124
  ## Surface the deferred-work ledger
123
125
 
124
126
  Show the user **this run's Epic heading** from the ledger at `{workflow.deferred_work_path}` — the open items under that one heading, their severity and suggested actions — so nothing parked during the run is invisible at handoff. The ledger holds one heading per Epic across runs; do not surface other Epics' parked work. If the file (or this Epic's heading) does not exist, say so plainly: nothing was deferred this run.
125
127
 
126
128
  ## Epic-complete hook
127
129
 
128
- This hook fires **only when the Epic-level gate verdict was `advance`** (a `complete` run). On a `blocked` run — a story escalated and the Epic never advanced — skip this step entirely; a "notify success" command must not fire on a blocked Epic.
130
+ This hook fires **only when the Epic-level gate verdict was `advance`** (a `complete` run) and its evidence is committed. On a `blocked` run (a story escalated, so the Epic never advanced or the evidence commit of its last story waits on the operator), skip this step entirely; a "notify success" command must not fire on a blocked Epic.
129
131
 
130
132
  When the Epic advanced, run: `uv run --no-project {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_epic_complete`
131
133
 
@@ -133,7 +135,7 @@ If the resolved `{workflow.on_epic_complete}` is non-empty, follow it as the fin
133
135
 
134
136
  ## Escalation hook
135
137
 
136
- The mirror of the epic-complete hook at the opposite terminal. This hook fires **only on a `blocked` run** — a story escalated and the Epic never advanced — and never on a clean advance, so an operator who walked away learns that the run stopped being able to make progress on its own.
138
+ The mirror of the epic-complete hook at the opposite terminal. This hook fires **only on a `blocked` run** (a story escalated, so the Epic never advanced or the evidence commit of its last story waits on the operator) and never on a clean advance, so an operator who walked away learns that the run stopped being able to make progress on its own.
137
139
 
138
140
  Execute may already have pinged when the gate escalated a story on its turn count, so this site is deduped against that same run-scoped marker, `{workflow.implementation_artifacts}/.on-escalation-fired-<run-id>`, **check-then-write**, at that byte-identical path, where `<run-id>` is this invocation's run id, minted at Stage 1 or at a resume's re-entry and carried forward verbatim. If the marker is already present, skip silently: the other fire site already pinged for this run. If it is absent, run: `uv run --no-project {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_escalation`
139
141
 
@@ -143,7 +145,7 @@ This is a side effect on the way out, never a gate on the exit: a hook that erro
143
145
 
144
146
  ## Headless output
145
147
 
146
- In headless (`-H`), build the final JSON **through the `scripts/headless_envelope.py` adapter** — never hand-composed here — run the Workflow health check (below) in its unattended queue-only mode, then emit the JSON and stop. `status` is `complete` when the Epic-level gate advanced, or `blocked` when a story escalated, and the adapter has one entry point per shape:
148
+ In headless (`-H`), build the final JSON **through the `scripts/headless_envelope.py` adapter** (never hand-composed here), run the Workflow health check (below) in its unattended queue-only mode, then emit the JSON and stop. `status` is `complete` when the Epic-level gate advanced and its evidence is committed, or `blocked` when a story escalated, the last story's `evidence-commit-rejected` included, though the Epic-level gate advanced before it (`references/gate.md`), and the adapter has one entry point per shape:
147
149
 
148
150
  ```
149
151
  build_complete_envelope(<path to this run's .decision-log.md>, report=<run-report.md path or None>, deferred_work=<{workflow.deferred_work_path} or None>, impl_artifacts={workflow.implementation_artifacts})