bmad-module-ultracode-goal 2.0.0 → 2.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.
- package/.claude-plugin/marketplace.json +1 -1
- package/README.md +5 -5
- package/docs/404.md +1 -1
- package/docs/_internal/STABILITY.md +13 -9
- package/docs/architecture.md +17 -12
- package/docs/comparison.md +19 -11
- package/docs/gate-model.md +24 -0
- package/docs/getting-started.md +1 -1
- package/docs/how-it-works.md +3 -3
- package/docs/index.md +0 -1
- package/docs/operating-tips.md +4 -2
- package/docs/troubleshooting.md +9 -5
- package/docs/why-ultracode-goal.md +1 -1
- package/package.json +5 -4
- package/skills/ucg-formalize/SKILL.md +136 -39
- package/skills/ucg-resolve/SKILL.md +86 -58
- package/skills/ucg-status/SKILL.md +64 -30
- package/skills/ultracode-goal/SKILL.md +9 -11
- package/skills/ultracode-goal/assets/module-help.csv +1 -1
- package/skills/ultracode-goal/assets/module.yaml +8 -3
- package/skills/ultracode-goal/assets/ucg-awareness/bmad-testarch-test-design.toml +8 -0
- package/skills/ultracode-goal/customize.toml +12 -7
- package/skills/ultracode-goal/references/define-done.md +3 -3
- package/skills/ultracode-goal/references/execute.md +40 -53
- package/skills/ultracode-goal/references/finalize.md +12 -12
- package/skills/ultracode-goal/references/gate.md +42 -11
- package/skills/ultracode-goal/references/health-check.md +7 -4
- package/skills/ultracode-goal/references/ingest-and-scope.md +4 -4
- package/skills/ultracode-goal/references/preflight.md +10 -9
- package/skills/ultracode-goal/scripts/gate_eval.py +684 -39
- package/skills/ultracode-goal/scripts/gate_trail.py +131 -32
- package/skills/ultracode-goal/scripts/health_check_fp.py +98 -3
- package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +56 -14
- package/skills/ultracode-goal/scripts/mem_observation.py +48 -10
- package/skills/ultracode-goal/scripts/mutate_check.py +353 -0
- package/skills/ultracode-goal/scripts/preflight_check.py +397 -3
- package/skills/ultracode-goal/scripts/status_render.py +20 -2
- package/skills/ultracode-goal/scripts/story_sizing.py +193 -0
- package/tools/build-docs.js +24 -1
- package/tools/validate-docs-links.js +169 -8
- package/website/astro.config.mjs +0 -1
- package/docs/parallel-mode.md +0 -68
- package/skills/ultracode-goal/assets/execute-epic.workflow.js +0 -249
|
@@ -2,17 +2,23 @@
|
|
|
2
2
|
|
|
3
3
|
Drive each in-scope story from its red-phase acceptance tests (generated in Stage 3) to a green, committed state. This stage **produces and prints evidence**; it does **not** decide completion. The completion verdict belongs to Stage 5 (`scripts/gate_eval.py` reading TEA's `gate-decision.json`) — never the `/goal` transcript evaluator, which can only see what you surface and cannot read the gate file. Run prose in `{communication_language}`.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
One path: the **sequential `/goal` spine**. (The experimental `--parallel` worktree fan-out is retired; the flag is still accepted so an old invocation does not error — see "Retired — `--parallel`" below.)
|
|
6
6
|
|
|
7
|
-
Preconditions (asserted, not assumed): you are on the Epic branch (`{workflow.epic_branch_prefix}…`, off a `{workflow.protected_branches}` branch), PreToolUse + Stop hooks are active in `.claude/settings.local.json`, the allowlist is pre-populated, and — **in production** — every in-scope story has an `atdd-checklist-{story_key}.md` with `test.skip` acceptance tests. (Under `--light` there is no atdd-checklist by design; the story file's clear acceptance criteria are the Stage-5 trace oracle instead — see define-done.md's `--light` note. The clear-ACs precondition still holds.) If any is false, return to Stage 2.
|
|
7
|
+
Preconditions (asserted, not assumed): you are on the Epic branch (`{workflow.epic_branch_prefix}…`, off a `{workflow.protected_branches}` branch), PreToolUse + Stop hooks are active in `.claude/settings.local.json`, the allowlist is pre-populated, and — **in production** — every in-scope story has an `atdd-checklist-{story_key}.md` with `test.skip` acceptance tests. (Under `--light` there is no atdd-checklist by design; the story file's clear acceptance criteria are the Stage-5 trace oracle instead — see define-done.md's `--light` note. The clear-ACs precondition still holds. **On a stack whose ATDD generator cannot run** — the non-web case `references/gate.md`'s hand-authoring section carves out — there is no atdd-checklist either, and that is not a failed precondition: the checklist is replaced by a red phase established BY HAND, authored, RUN and captured before the story's first implementation edit, per gate.md's non-web section and step 1 below. Routing such a run back to an earlier stage cannot produce the artifact and never terminates.) If any is false, return to the stage that produces the missing piece: branch, hooks or allowlist to Stage 2; a genuinely missing atdd-checklist to **Stage 3** (define-done — the only stage that generates it; Stage 2 cannot). Two legitimate ways a story reaches this stage checklist-less, neither of which is a bounce: a **decomposed child row** (created after Stage 3 ran — run `bmad-testarch-atdd` scoped to that story before its step 0, or hand-establish the red phase where ATDD cannot run) and the **non-web stack** above. Record which case it was, and what replaced the checklist, in `.decision-log.md`.
|
|
8
8
|
|
|
9
|
-
**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** — the latch is *re-written* by re-running Stage 1's latch step (`references/ingest-and-scope.md`), because Stage 6 removes it at every close-out and the PreToolUse hook reads an absent latch as "no run active" and stops gating claude-mem entirely
|
|
9
|
+
**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 "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 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`), because Stage 6 removes it at every close-out and the PreToolUse hook reads an absent latch as "no run active" and stops gating claude-mem entirely — and 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 and never inherit its `claude_mem` value, because an inherited green latch is a capability claim this run never made, which is exactly what ingest-and-scope.md's never-synthesize-a-probe rule forbids. 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.
|
|
10
|
+
|
|
11
|
+
**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.
|
|
12
|
+
|
|
13
|
+
**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, and the five injected hook env vars 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 — 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.
|
|
14
|
+
|
|
15
|
+
**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.
|
|
10
16
|
|
|
11
17
|
## Default — Sequential `/goal` spine
|
|
12
18
|
|
|
13
19
|
### Sizing: a story too large to drive
|
|
14
20
|
|
|
15
|
-
**Before step 0 writes any marker, size the row.** Count its acceptance criteria and tasks. When the count is implausible against `{workflow.max_turns_per_story}`, **do not start the story** — decompose it into child rows and terminate the invocation.
|
|
21
|
+
**Before step 0 writes any marker, size the row.** Count its acceptance criteria and tasks. **Take that set from the ROW, not from a neighbour's prose.** The `sprint-status.yaml` row is the authority on *which* acceptance criteria a story owes; the story file it cites (its own, or the parent it was split from) is only where those criteria's text lives. A decomposed child has no story file of its own by the convention below, so its contract exists solely as the criteria its row cites. A sibling's ledger entry, or a decision-log entry, names what that sibling **handed off** — a different set, with no reason to be complete — and a scope read from one undersizes the row here and under-delivers it at step 1. Nothing downstream catches that: the trace, the gate-decision file and the gate verdict are all written from this same reading, so they come out green over a missing criterion by construction. When the count is implausible against `{workflow.max_turns_per_story}`, **do not start the story** — decompose it into child rows and terminate the invocation. "Implausible" has a first-pass test, not just a judgment: a driven story spends a turn or more per acceptance criterion once implementation, verification and the gate artifacts are counted, so **when the row's AC count plus task count reaches roughly half of `{workflow.max_turns_per_story}`, treat the row as implausible**, and tie-break against this Epic's own record — the AC/task counts of rows already driven cleanly versus rows already split; a row matching an already-split parent's shape is answered by that precedent. The judgment word stays as the override in both directions (a count under the threshold can still be implausible when each AC owes an executed artifact; over it can be plausible when the ACs are one-line checklist items), but an override is a recorded reason in `.decision-log.md`, never the whole method — two conductors meeting the same row must be able to reach the same verdict.
|
|
16
22
|
|
|
17
23
|
Nothing else in this stage covers that case, and the two routes it seems to offer are both wrong. Driving it reaches the turn bound with a baseline marker and a tests-ran marker on disk and no commit, which is exactly the abandoned-mid-story outcome the work bound below exists to avoid. Escalating reaches the same conclusion having first spent the whole budget proving what an AC count showed in five minutes. **A decomposition writes no baseline and no tests-ran marker at all**, so the abandoned-story shape cannot arise from it.
|
|
18
24
|
|
|
@@ -24,38 +30,48 @@ Three conventions, and they are **properties of `scripts/drive_epic.py`** rather
|
|
|
24
30
|
- **Set the parent row to `done` once its children exist.** Same mechanism, one lap later: a parent left not-`done` sits ahead of nothing once the children are consumed, but it is still a not-`done` row the driver will select and no session will advance. The parent is now a container, and its contract lives in the child rows that cite it.
|
|
25
31
|
- **Do not edit the parent story file.** Each child row cites it by AC number. Editing it to match the split creates a second copy of the contract, and then two artifacts disagree about what the story owes.
|
|
26
32
|
|
|
27
|
-
Record the split in `.decision-log.md`: the parent, the children in order, and which parent ACs each child claims. **Check that mapping mechanically
|
|
33
|
+
Record the split in `.decision-log.md`: the parent, the children in order, and which parent ACs each child claims. **Check that mapping mechanically with `scripts/story_sizing.py`** — every parent AC claimed exactly once — never by eye and never with a parser written for the occasion. One improvised for this on a real run produced two false double-claims by matching the `1` inside `REQ-1`; the script compares whole ids, so `AC-1`, `REQ-1` and `1` are three ids and no substring makes them one:
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
uv run {skill-root}/scripts/story_sizing.py --parent-acs '<the parent row's ACs>' --child '<child-row-id>=<ACs it claims>' --child '…' --tasks <n> --turn-ceiling {workflow.max_turns_per_story}
|
|
37
|
+
```
|
|
28
38
|
|
|
29
|
-
|
|
39
|
+
It exits 0 when the map reconciles and 1 when it does not, printing `unclaimed`, `double_claimed` and `unknown_claims` (an AC no parent row owns) either way — **a non-zero exit means the split is wrong and must be fixed before the child rows are written**, not a warning to log past. Called without `--child` before the split it does the sizing half only, returning `load`, `ratio` and `implausible` against the same threshold this section states, and it says `reconciled: false` rather than reporting a clean claim map it never checked. The judgment stays here: `implausible` is an override in both directions with a recorded reason, and which child owns which AC is an authoring decision the script never makes.
|
|
40
|
+
|
|
41
|
+
Then terminate as the work-bound section below describes for an invocation that advanced no row. The Stage 6 gate trail still covers the in-scope set **as resolved at Stage 1** — the parent's id, never the just-created children: they were resolved by no Stage 1 and driven by nothing here, so they belong to the next invocation's trail (`references/finalize.md`, Gate trail).
|
|
30
42
|
|
|
31
43
|
### The story loop
|
|
32
44
|
|
|
33
45
|
For each in-scope story, in sprint order, run this loop:
|
|
34
46
|
|
|
35
|
-
0. **Set the current story and record its baseline commit** — both **before any implementation**, before step 1 touches a single file. First, so the PreToolUse hook can locate this story's marker: write the story id to `{workflow.implementation_artifacts}/.current-story` (or export `ULTRACODE_STORY_ID=<story_id>` for the run). The guard reads the story id from `ULTRACODE_STORY_ID`, falling back to that `.current-story` file — without one set, it cannot find the marker and denies every commit. 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
|
|
36
|
-
1. `bmad-create-story` (if not already current) → `bmad-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. 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 `bmad-dev-story` / review context for this story so the operator's last words actually reach the work.
|
|
37
|
-
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 the `/goal` driver reads to pace itself — but it is *evidence*, not the gate. **Once all three go green, write the tests-ran marker** `{workflow.implementation_artifacts}/.tests-ran-<story_id>`
|
|
47
|
+
0. **Set the current story and record its baseline commit** — both **before any implementation**, before step 1 touches a single file. First, so the PreToolUse hook can locate this story's marker: write the story id to `{workflow.implementation_artifacts}/.current-story` (or export `ULTRACODE_STORY_ID=<story_id>` for the run). The guard reads the story id from `ULTRACODE_STORY_ID`, falling back to that `.current-story` file — without one set, it cannot find the marker and denies every commit. 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.
|
|
48
|
+
1. `bmad-create-story` (if not already current) → `bmad-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 `bmad-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. **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 `bmad-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.)
|
|
49
|
+
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 the `/goal` driver reads to pace itself — 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.
|
|
38
50
|
|
|
39
51
|
**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:
|
|
40
52
|
|
|
41
53
|
- **Language.** An aggregate task runner only runs the tasks packages *declare* to it, so in a polyglot repo the wide run can report every task green while an entire language's suite was never invoked. Read the runner's executed-task list against the languages actually present: a Rust crate with no `test` task simply does not appear in a turbo task count, and "8 of 8 tasks passed" says nothing about it. Run each uncovered language's suite explicitly (`cargo test`, `go test ./...`, `pytest`) and print those results alongside. **A task count is not a coverage claim.**
|
|
42
54
|
- **The repo's DECLARED gate set, not its default task.** Enumerate the quality tasks the repo actually declares (its `package.json` scripts, the turbo/nx pipeline, the CI workflow's jobs) and name, in the printed evidence, every one the default task excludes. A `test:storybook` or a `test:coverage`/coverage-ratchet that is a *sibling* task rather than a dependency of `test` is invisible to `run test`, and can sit red across an entire Epic while every sweep prints green. Run the excluded ones too, or state explicitly which you are not running and why.
|
|
43
55
|
|
|
44
|
-
**Defeat the build cache at least once.** In a content-addressed task runner (turbo, nx, bazel) a cache hit is precisely the state in which a sibling package's gate is *not* re-executed, which is the cross-package regression this step exists to catch. Run the authoritative sweep cache-defeating (turbo's `--force`, nx's `--skip-nx-cache`, bazel's `--nocache_test_results`, or the package's own runner directly) and **state in the printed evidence whether the run was cached** — a task count that is entirely cached, returning in under a second, is the signature of a replay (turbo prints a `FULL TURBO` line for it), and a run that is green cached and red forced is indistinguishable from a green one in the transcript.
|
|
56
|
+
**Defeat the build cache at least once.** In a content-addressed task runner (turbo, nx, bazel) a cache hit is precisely the state in which a sibling package's gate is *not* re-executed, which is the cross-package regression this step exists to catch. Run the authoritative sweep cache-defeating (turbo's `--force`, nx's `--skip-nx-cache`, bazel's `--nocache_test_results`, or the package's own runner directly) and **state in the printed evidence whether the run was cached** — a task count that is entirely cached, returning in under a second, is the signature of a replay (turbo prints a `FULL TURBO` line for it), and a run that is green cached and red forced is indistinguishable from a green one in the transcript. **The same rule binds any harness the story itself drives through the task runner** — mutation, fault injection, a twin-verification loop — and there the replay is worse than a false green: an unchanged task hash replays the pre-mutation GREEN for every mutation, so every mutation "survives" with zero failing cases, which reads as a devastating vacuity finding about the suite rather than as a cache hit. A subject **outside** the filtered package's tree (a repo-root script, a shared config, a generated artifact) never changes that package's task hash at all, so filter-plus-mutate is the specific combination that always needs the cache defeated. A string-replacement harness additionally owes its anchors a uniqueness assertion before mutating: an anchor that occurs more than once mutates a different site than it reports, and a `KILLED` earned against the wrong layer is the same silent inversion from the other side. **The module ships that harness — use it instead of hand-rolling one into scratch space.** `uv run {skill-root}/scripts/mutate_check.py --table <rows.json>` drives a JSON table of `{file, anchor, replacement, command, expect_red}` rows with the properties every hand-rolled version eventually lost, built in as refusals: a green-baseline precheck (a mutation over a red baseline proves nothing, exit 2), per-row anchor uniqueness (0 occurrences reported distinctly as the formatter-reflow signature), an ATTRIBUTABLE red (the expected case named in the output, extra reds surfaced), and a byte-identical restore verification. Its generated ledger leads with GREEN survivors, because each green is a finding — a guard that cannot fail — and exit 1 on any green, misattributed red, or unheld anchor makes the runner gate-able. **Every guard or assertion this story adds or changes appears as a table row with an attributable red BEFORE the gate runs**, and the generated ledger is a story artifact the reviewers read: write it with `--output {workflow.implementation_artifacts}/mutation-ledger-<story_id>.md` — name-pinned per story like every artifact a later stage resolves, never scratch space (scratch dies at story end, which is exactly how the harness kept getting re-rolled) — and surface it into the step-3 test-review context in production, citing it in the story record either way. The cache rule above binds the table's `command` verbatim: the runner cannot defeat the task-runner cache for you. A repo may substitute its own runner only when it meets the same properties.
|
|
57
|
+
|
|
58
|
+
**A re-loop iteration may scope the sweep; the cycle that expects to advance owes the full one.** The first pass through this loop runs the full three-axis sweep above. A story re-entered from a `reloop` verdict may instead run the affected set — the changed package(s) *and their dependents*, computed against the story's last recorded commit (`{workflow.implementation_artifacts}/.commit-<story_id>`, the previous cycle's end marker): e.g. turbo's `--filter=...[<that sha>]`, still cache-defeated, still with raw output printed. Two obligations keep the scoped form honest. **Print the resolved package list** — the runner computes it; copy its own output into the transcript and the marker's `packages=` line, because a wrong baseline ref narrows coverage *silently*, and the printed list is the only place a narrowing shows. And **write the marker with `scope=scoped`**, so the record says which form ran — a scoped sweep reported as a full one is the same class of false claim reviews keep finding elsewhere. When the re-loop believes its findings are closed and the next gate should advance, run the full sweep and write `scope=full`: the gate refuses to advance a story off a `scope=scoped` marker (`references/gate.md`, the sweep-scope AND), so a scoped cycle that unexpectedly goes fully green costs one extra full-sweep cycle rather than producing an advance nothing re-proved. When in doubt, run it full — `scope=full` is never wrong, only slower. (Measured, on a seven-cycle story: the whole-repo cache-defeated sweep re-proved untouched packages seven times, roughly six of every eight sweep minutes; this split is that cost's fix, at no loss of gate authority. A repo whose runner cannot compute an affected set simply keeps running the full sweep — the scoped form is an optimisation, never an obligation.)
|
|
59
|
+
|
|
60
|
+
**A wide sweep is also a loaded machine.** Running every language's suite plus the declared gate set, cache-defeating, means suites share a host with concurrent native builds — and a case bounded by a wall-clock timeout can fail from contention alone (measured: a 180-second-bounded case took 197s beside a concurrent `cargo test` + clippy + type-check, and 93s alone). A timeout in a wide sweep is therefore not yet a red: re-run that package in isolation before treating it as one, and where the two can be sequenced, do not schedule a long native build beside a wall-clock-bounded suite.
|
|
45
61
|
|
|
46
62
|
**Capture, then slice — never pipe a long command through a filter.** `cmd 2>&1 | tail -50` buffers everything until the pipeline ends, so a cold build that is working and a genuine hang emit the same thing: nothing. Redirect to a file (`cmd > <log> 2>&1`) and read the summary out of it as a second call. The file also survives compaction, so the evidence outlives the turn, and the pipeline's exit status is the *filter's* rather than the command's. A 45-minute build has been killed on the suspicion it had hung; it had not.
|
|
47
63
|
|
|
48
64
|
**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.
|
|
49
65
|
|
|
50
66
|
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.
|
|
51
|
-
4. **Commit at green** (one commit per green story). 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), 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. The guard **evaluates Bash command strings only**, 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 (its Cross-Session Recall invariant gates an MCP call, which a `Bash`-only matcher never reaches): the hook IS invoked for a `Write`, it simply has nothing to evaluate and returns no decision. 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. **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
|
|
52
|
-
5. **Re-verify on the committed HEAD.** Re-run the authoritative
|
|
67
|
+
4. **Commit at green** (one commit per green story). 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. The guard **evaluates Bash command strings only**, 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 (its Cross-Session Recall invariant gates an MCP call, which a `Bash`-only matcher never reaches): the hook IS invoked for a `Write`, it simply has nothing to evaluate and returns no decision. 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. **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, 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.
|
|
68
|
+
5. **Re-verify on the committed HEAD.** Re-run the authoritative suite (tests + lint + build, the same scope step 2 ran this cycle — all three axes including the declared gate set when full; the same resolved package set when this re-loop cycle legitimately ran scoped, per step 2's re-loop rule) on the just-committed, clean tree and **PRINT** the result before advancing. **Run it cache-defeating.** Committing changes a file's git *tracking state* and not one of its bytes, so a content-addressed cache key is unchanged and this re-run replays the pre-commit answer verbatim, observing nothing: eight of eight tasks reported cached, returning in 719ms immediately after a commit, is the whole failure. Pass `--force` (or invoke the package's runner directly), because the one thing this step must actually execute is the tracked-file gates against the newly tracked fileset. Step 2's pre-commit run cannot see a **conformance gate scoped to *tracked* files** — a `git ls-files`-based ref/ownership/architecture-boundary check: a story's **new** files are still untracked at step 2, so the gate skips them and reports green, then reds the instant the commit tracks them (generated or `.gitignore`d files hide the same way). This committed tree is the exact fileset CI and the Stage-5 gate will see, so a story that is green pre-commit but red here is a **false green** the pre-commit run and the `/goal` transcript evaluator both miss. A red means the story is **not** done: remediate, write a fresh `.tests-ran-<story_id>` marker, and re-commit (amend or a follow-up within the story boundary) until the committed HEAD is green — only then advance. **That fresh marker carries the same `baseline=<sha>` line as step 2's**: the verbatim, whitespace-stripped content of `{workflow.implementation_artifacts}/.baseline-<story_id>` — **copied, never re-derived from `git rev-parse HEAD`**. The story's baseline has not moved; HEAD has, because step 4 just committed. Re-deriving it here would re-anchor the story to that commit and quietly retire the freshness net for the rest of it, which is the very replayed-marker hole the line exists to close — and without the line the guard denies the re-commit outright, so a story that legitimately needs remediation could never close. The fresh marker also re-states `scope=` (and `packages=` when scoped) to match what THIS re-verify actually ran, because the `scope=` line the gate will read through `--tests-ran` is the one written here, not step 2's. **Rewrite `{workflow.implementation_artifacts}/.commit-<story_id>` from `git rev-parse HEAD` once this step's HEAD is green**, in step 4's format — every time, including when nothing was remediated, because an amend replaces the SHA step 4 recorded and a follow-up commit moves it. This marker is the one step-0 artifact whose rule is *refresh*, not *keep*: the baseline names where the story started and must never move, this one names where it ended and must never be stale. That re-commit carries the SAME staging rule as step 4: stage in a prior, SEPARATE tool call (`git add <this story's paths>`), then run the commit (or `git commit --amend`) as a second, distinct call. `git commit -a` and a chained `git add … && git commit` are unsupported here too — the staged index is still empty when the guard pre-evaluates the command string, so the re-commit is denied.
|
|
53
69
|
|
|
54
70
|
**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.
|
|
55
71
|
|
|
56
72
|
### The per-invocation work bound (`--max-stories N`)
|
|
57
73
|
|
|
58
|
-
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.
|
|
74
|
+
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.
|
|
59
75
|
|
|
60
76
|
**It bounds work, not scope.** In-scope is still every not-`done` story of the Epic (Stage 1 rule 3; headless never narrows it), so the remaining stories are not skipped, not deferred, and not logged as `skipped-already-done` — they are simply *not driven this time*. The next invocation's resume routing re-enters at the first story whose last logged gate verdict is not advance, which is precisely where this one stopped, so nothing about resume needs to know the bound existed. Log the bound and the carried-over story ids in `.decision-log.md` so the stop is reconstructable after compaction; an unexplained early exit and a crash look identical in a log.
|
|
61
77
|
|
|
@@ -67,10 +83,10 @@ When the operator passed `--max-stories N`, count the stories this **invocation*
|
|
|
67
83
|
|
|
68
84
|
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.
|
|
69
85
|
|
|
70
|
-
**This bound belongs to the sequential spine**, and it deliberately claims nothing about `--parallel`: that path hands the whole in-scope list to the fan-out workflow up front, so a bound there would have to trim the list itself, which is the scope narrowing this flag exists not to be. Under `--parallel`, ignore `--max-stories` and log the one-line note that it was ignored rather than silently honoring it as a shorter `stories` array.
|
|
71
|
-
|
|
72
86
|
`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.
|
|
73
87
|
|
|
88
|
+
**A spawn that dies in flight is its own condition, and once the driver's own retries are spent, re-spawning is not the route.** A spawned `claude -p` can abort mid-stream (a streaming error, a killed process) leaving no terminal envelope. Nothing is wrong with the story, so this is not an escalation and no decision is pending; no gate ran, so it is not a gate failure — neither documented route fits, and the driver already survives it and reports the tree the dead spawn left. `scripts/drive_epic.py` retries that `no-terminal` stop up to `--max-abort-retries` times (default 2; `0` disables it), and **only** over a tree its post-stop triage read as clean with HEAD unmoved, so a retry can never re-spawn over work in progress. Once those are exhausted the driver stops, and re-spawning by hand from there is the intuitive response that replays the same conditions that killed the first attempt (observed failing twice in a row on one story before succeeding in-session). The recovery that works then is to **drive the story directly** — in the current session, or attended. The dead spawn's on-disk residue needs no cleanup first — its markers and any commits are exactly what the resume routing at the top of this file classifies, so the direct drive enters through that routing like any resume.
|
|
89
|
+
|
|
74
90
|
### Authoring the `/goal` condition
|
|
75
91
|
|
|
76
92
|
Wrap the loop in a single `/goal` whose condition is **under 4000 characters** and encodes the per-story Definition-of-Done as the success criterion, with an explicit escape clause. The condition must:
|
|
@@ -83,7 +99,7 @@ Keep it under the character limit by referencing the story's `atdd-checklist` (o
|
|
|
83
99
|
|
|
84
100
|
After the spine finishes (all stories committed-at-green, or a story hit its turn bound and wrote an escalation marker), proceed to Stage 5 for the deterministic per-story and epic-level gate.
|
|
85
101
|
|
|
86
|
-
**Escalation ping.** Before proceeding, scan `{workflow.implementation_artifacts}` for the escalation markers *this* run produced. A `.escalation-<story_id>.md` is in scope only when it **both** names a story in this run's plan **and** was written after this run's start — both conjuncts, never either one alone. A marker naming an unplanned story belongs to another Epic escalating concurrently; a marker naming a planned story but predating this run's start is residue from an earlier run of the same Epic, and firing on either would tell an absent operator about an escalation nobody is having. On the first in-scope marker, promote it to the typed sidecar `{workflow.implementation_artifacts}/escalation-<story_id>.json` (see "Escalation sidecar" below) before firing anything, so a hook that reads the sidecar finds it already on disk. Then fire, **check-then-write** against `{workflow.implementation_artifacts}/.on-escalation-fired-<run-id>`, where `<run-id>` is the run id minted at Stage 1 and carried forward verbatim — never re-derived here, since re-minting that timestamp would produce a fresh marker on every read and defeat the dedup entirely. If that marker is already present, skip silently: the other fire site already pinged for this run. If it is absent, resolve `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_escalation`; when the resolved value is non-empty, follow it as an instruction (a prompt to run or a shell command), stating alongside it **the escalating story id** and the path to that story's typed `escalation-<story_id>.json` sidecar as the context it carries, and only then write the fired-marker. A resolved-empty value is a silent no-op — nothing fires and no fired-marker is written — so an empty hook can never suppress a later real one.
|
|
102
|
+
**Escalation ping.** Before proceeding, scan `{workflow.implementation_artifacts}` for the escalation markers *this* run produced. A `.escalation-<story_id>.md` is in scope only when it **both** names a story in this run's plan **and** was written after this run's start — both conjuncts, never either one alone. A marker naming an unplanned story belongs to another Epic escalating concurrently; a marker naming a planned story but predating this run's start is residue from an earlier run of the same Epic, and firing on either would tell an absent operator about an escalation nobody is having. On the first in-scope marker, promote it to the typed sidecar `{workflow.implementation_artifacts}/escalation-<story_id>.json` (see "Escalation sidecar" below) before firing anything, so a hook that reads the sidecar finds it already on disk. Then fire, **check-then-write** against `{workflow.implementation_artifacts}/.on-escalation-fired-<run-id>`, where `<run-id>` is the run id minted at Stage 1 and carried forward verbatim — never re-derived here, since re-minting that timestamp would produce a fresh marker on every read and defeat the dedup entirely. If that marker is already present, skip silently: the other fire site already pinged for this run. If it is absent, resolve `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_escalation`; when the resolved value is non-empty, follow it as an instruction (a prompt to run or a shell command), stating alongside it **the escalating story id** and the path to that story's typed `escalation-<story_id>.json` sidecar as the context it carries, and only then write the fired-marker. A resolved-empty value is a silent no-op — nothing fires and no fired-marker is written — so an empty hook can never suppress a later real one.
|
|
87
103
|
|
|
88
104
|
### Escalation sidecar
|
|
89
105
|
|
|
@@ -106,48 +122,15 @@ One object, never an array: the file is already named per story, so a list would
|
|
|
106
122
|
|
|
107
123
|
**Leave the markdown in place — never delete it, never rewrite it.** It is the residual that survives a session which died between the hook's write and this promotion, so consuming it would destroy the only evidence that an escalation happened at all.
|
|
108
124
|
|
|
109
|
-
|
|
125
|
+
## Retired — `--parallel`
|
|
110
126
|
|
|
111
|
-
|
|
127
|
+
The experimental `--parallel` worktree fan-out is retired; the sequential spine above is the only execution path. (`ROADMAP.md` carries why it was retired rather than promoted.)
|
|
112
128
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
```
|
|
116
|
-
args = {
|
|
117
|
-
epic, # Epic id
|
|
118
|
-
stories, # in-scope story ids/keys, sprint order
|
|
119
|
-
profile, # "production" | "light"
|
|
120
|
-
paths: {
|
|
121
|
-
trace_output: {workflow.trace_output_dir},
|
|
122
|
-
deferred_work: {workflow.deferred_work_path},
|
|
123
|
-
implementation_artifacts: {workflow.implementation_artifacts},
|
|
124
|
-
tea_config: {workflow.tea_config_path},
|
|
125
|
-
skill_root: {skill-root} # resolved absolute skill dir; the .js has no
|
|
126
|
-
# {skill-root} resolver, so it must arrive pre-resolved
|
|
127
|
-
},
|
|
128
|
-
max_concurrency: {workflow.parallel_max_concurrency}
|
|
129
|
-
}
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
Pass `paths.skill_root` as the **resolved** `{skill-root}` (the absolute install dir). The workflow runtime executes the `.js` directly and has no `{skill-root}` resolver, so it substitutes this value into the `gate_eval.py` invocations it emits to each subagent; without it the spawned worktree agent receives a literal `{skill-root}` and must guess the script's path.
|
|
133
|
-
|
|
134
|
-
Each story runs isolated in its own worktree: `bmad-dev-story` (un-skip ATDD — production; under `--light` there are none) → run tests/lint/build → (production) `bmad-testarch-test-review` → `bmad-code-review` → commit at green → per-story `gate_eval`. After all stories, an epic-level trace gate. The workflow returns `{ perStory: [{story, verdict, gate_status, committed, branch}], epicGate, deferred: […], unevaluated: […] }`, which feeds Stage 5/6. **`committed` and `unevaluated` are the two honesty fields.** `gate_eval.py` never touches git, so a story can gate `PASS`/`advance` while its commit was denied by the PreToolUse guard; the workflow downgrades such a story to `escalate` rather than reporting an advance whose work is on no branch. `unevaluated` names any story whose agent returned no result at all — a spawn failure or a schema-violating response — because such a story used to be dropped from the run silently, leaving it indistinguishable from one that was never in scope. Both are empty on a healthy run; treat either as non-empty the way you would an escalation.
|
|
135
|
-
|
|
136
|
-
**This path is experimental — be explicit about its limits and do not silently rely on it:**
|
|
137
|
-
|
|
138
|
-
- **No mid-run input.** The fan-out takes no interactive input once launched; every blocker must be resolved at preflight or not at all. This is why launch requires post-remediation budget == 0.
|
|
139
|
-
- **Shared Auto Memory.** Concurrent worktrees write to **one** Auto Memory directory — there is no per-worktree isolation of learned facts; expect interleaving.
|
|
140
|
-
- **Under-documented interplay.** The workflow↔skill handoff (how args bind, how subagents inherit the allowlist and hooks) is not fully specified by the platform docs; treat its behavior as empirically validated, not guaranteed.
|
|
141
|
-
- **No `run-status.json` heartbeat.** Worktree agents cannot reliably write one shared snapshot (each worktree sees its own copy of `{workflow.implementation_artifacts}`), so this path does not write it — progress is watched via the workflow progress view (`/workflows`) and its run log, and the launch briefing says so.
|
|
142
|
-
- **No post-commit re-verify.** Unlike the sequential spine's step 5, the fan-out commits at green and goes straight to per-story `gate_eval` without re-running the suite on the committed tree — so a **tracked-files-scoped conformance gate** (a `git ls-files`-based ref/ownership/boundary check) that only reds once a worktree's new files are committed can slip a per-worktree green through to the merge. Until this path re-verifies on the committed HEAD, treat the epic-level gate over the merged result as the backstop for that class, and prefer the sequential spine for repos that carry such a gate.
|
|
143
|
-
|
|
144
|
-
### Graceful degradation
|
|
145
|
-
|
|
146
|
-
If dynamic workflows are **unavailable** (wrong Claude Code version, workflows feature off, or the saved command does not resolve), **fall back to the sequential `/goal` spine above** and log a one-line note in `.decision-log.md` recording why `--parallel` degraded. The Epic still ships; it just ships sequentially.
|
|
129
|
+
**The flag is still accepted, and it does exactly what its old degradation branch did**: a run invoked with `--parallel` logs one line in `.decision-log.md` recording that the flag was accepted and ignored, then runs the sequential `/goal` spine. It never errors, never warns twice, and changes nothing else — an operator's old invocation keeps working, minus the mode. `{workflow.parallel_max_concurrency}` is likewise deprecated and no-op: still shipped, still resolving, read by nothing (`docs/_internal/STABILITY.md`).
|
|
147
130
|
|
|
148
131
|
## Record
|
|
149
132
|
|
|
150
|
-
Log to `.decision-log.md`: the
|
|
133
|
+
Log to `.decision-log.md`: per-story turn-budget outcomes, the accepted-and-ignored note when a retired `--parallel` flag was passed, every commit-at-green, every deferral appended to `{workflow.deferred_work_path}`, and any escalation marker. The printed test/lint/build evidence stays in the transcript; the decision log carries the durable account across compaction.
|
|
151
134
|
|
|
152
135
|
## Run-status heartbeat
|
|
153
136
|
|
|
@@ -179,6 +162,10 @@ When the prior snapshot's `budget_used.turns` and the current `.budget-<story>.j
|
|
|
179
162
|
|
|
180
163
|
Before the Stop hook has fired for a story, no `.budget-<story>.json` exists yet. That is a normal early-story state, not an error: render `budget_used` as `{"turns": 0, "max_turns": <the resolved ceiling>}` and write the snapshot anyway — an absent hook file is never a reason to skip the write, defer it, or leave the heartbeat partially written.
|
|
181
164
|
|
|
165
|
+
**A resume writes its first heartbeat at re-entry, before step 0 of the story it is about to drive** — `story` naming that story, its `stories` entry at `phase` `"resuming"`, `verdict` null. Until that write the file still holds the prior invocation's terminal snapshot, and everything a resume does before the loop — branch and hook re-assertion, the latch, recall, a grounding read — is real work during which a poller would otherwise be watching a stale terminal. `budget_used.turns` legitimately reads `0` through all of it, because the hook counts from `.current-story` on: zero turns beside a fresh `updated` is a conductor re-asserting the environment, not a stalled run. The poller's liveness signal is `updated` and `phase`, never `turns` alone.
|
|
166
|
+
|
|
182
167
|
This is the file the Stage 2 launch briefing points the operator at ("where to watch"); Stage 6 (finalize) records the terminal state into it when the run closes, carrying every key above forward rather than overwriting the file with a narrower object.
|
|
183
168
|
|
|
169
|
+
**The per-step heartbeat sidecar, and the stall marker its gaps earn.** `run-status.json` says where the spine IS; it cannot say how long nothing has happened, because it is overwritten on story/verdict cadence and a five-hour hole between two writes renders exactly like five busy minutes. So, additionally, append one line — the step name and a UTC timestamp — to `{workflow.implementation_artifacts}/.heartbeat-<story_id>` at every numbered story-loop boundary (step 0 through step 5, plus gate start and gate end). One command, no substitution, guard-inert: `date -u "+step-2 %FT%TZ" >> {workflow.implementation_artifacts}/.heartbeat-<story_id>` (the step label rides the format string). Append-only, observability only: the file is never gate evidence, is read by no guard, and is purged at fresh-run arming exactly as `.budget-*` is (`references/preflight.md`), so a prior run's gaps can never fire this run's stall rule. Everywhere else in this file, "the heartbeat" with no qualifier still means `run-status.json` — the attended ticker above rides ITS story/verdict cadence, never this sidecar's per-step one. Its consumer is the RESUME: on re-entry, when the story's heartbeat exists and the gap between its last line and now exceeds 30 minutes, append one line to `{workflow.implementation_artifacts}/.stall-<story_id>` recording the gap, the last step reached, and the best-known cause — a rate-limit message if one is in context, an operator pause if told, `unknown` otherwise — before driving anything. A measured story carried a five-hour zero-write hole between two gate cycles that no artifact explained, and the investigation had to reconstruct it from file mtimes; `unknown, 5h00m, after gate` would have made it a record instead. Leave both sidecars in place at story end — finalize does not remove them, and the run report may state active versus idle time from them honestly.
|
|
170
|
+
|
|
184
171
|
**Attended runs also get a ticker.** Each time you write the heartbeat, print one line into the transcript — `epic-7 ▸ story 3/6 — last verdict: advance` — so the watching human sees motion without opening a JSON file. Skip the ticker in headless (`-H`): the file is the interface there, and transcript prose has no reader.
|
|
@@ -17,20 +17,21 @@ Interactive runs **offer** the retrospective at Epic close (skip it by default i
|
|
|
17
17
|
|
|
18
18
|
## Decision-log audit
|
|
19
19
|
|
|
20
|
-
Walk every entry
|
|
20
|
+
Walk every entry **this invocation wrote** (scope, preflight verdict, each gate verdict, each deferral, every assumption). On a fresh run that is the whole `.decision-log.md`; on a mature Epic it is not, and must not be — execute.md step 4 forbids Reading the log once it is too large to Read affordably, so the auditable unit there is this session's own `dlog-slice-*.md` files plus what is still in context. Entries from prior invocations were audited by the invocations that wrote them; say that in the accounting below rather than silently narrowing the walk, so a reader can tell a scoped audit from a skipped one. Each entry must resolve to one of three: **captured in the run report** (a primary decision or outcome the user takes away), **captured in the addendum** (a parked alternative or rejected option that needs a home but not the report), or **explicitly marked process noise** (set aside, not silently dropped). End with a shared accounting of how the run's reasoning was handled — not a one-sided polish.
|
|
21
21
|
|
|
22
22
|
## Run report
|
|
23
23
|
|
|
24
|
-
Produce a report (write it as a peer of `.decision-log.md` in the run folder, e.g. `run-report.md`) covering
|
|
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
|
-
- Epic and profile (production / `--light`), branch off `{workflow.epic_branch_prefix}
|
|
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
28
|
- Per-story outcome: gate_status and verdict (advance / defer / reloop / escalate), and any re-loops spent against budget.
|
|
28
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.
|
|
29
|
-
- The Epic-level gate result.
|
|
30
|
+
- The Epic-level gate result — and when this run authored none (the work bound, a handoff, a `partial-complete`), say that in words: `no Epic-level gate — the Epic is not finished`. Never leave the line blank or omit it; a missing gate line reads as a pass.
|
|
30
31
|
- Turns consumed vs `{workflow.max_turns_per_story}`.
|
|
31
32
|
- Learnings captured and where they went (memory vs CLAUDE.md).
|
|
32
33
|
- A pointer to the deferred-work ledger and its open-item count.
|
|
33
|
-
- Cross-Session Recall: consulted / wrote / skipped, plus the outbox tombstone count when the drain ran.
|
|
34
|
+
- Cross-Session Recall: consulted / wrote / skipped, plus the outbox tombstone count when the drain ran — and, when a headless run's probe was denied by the permission layer, the **required** operator-remedy line ingest-and-scope.md's denial rule specifies (grant the permission once, or set `cross_session_recall = "off"`). A run short of turns may drop prose; it may not drop that line.
|
|
34
35
|
|
|
35
36
|
## Gate trail
|
|
36
37
|
|
|
@@ -40,7 +41,7 @@ Write the per-story evidence trail as **`gate-trail.md`, a peer of `run-report.m
|
|
|
40
41
|
uv run {skill-root}/scripts/gate_trail.py --run-dir <this run's folder> --profile <light|production> --impl-artifacts {workflow.implementation_artifacts} --trace-output <the trace artifacts dir> --story <id>… --repo {project-root}
|
|
41
42
|
```
|
|
42
43
|
|
|
43
|
-
**The run's in-scope story ids are required, not optional.** Pass `--story` once per in-scope story **in sprint order** — the order is what turns the recorded baselines into commit ranges (each story's range ends at the next story's baseline, and at `HEAD` for the last one). The script prints the path it wrote; name that path in the run report.
|
|
44
|
+
**The run's in-scope story ids are required, not optional.** Pass `--story` once per in-scope story **in sprint order** (a repeated flag — `--story 4-1 --story 4-2` — never one space-separated list); the order is what turns the recorded baselines into commit ranges (each story's range ends at the next story's baseline, and at `HEAD` for the last one). The script prints the path it wrote; name that path in the run report. **Which set, when a decomposition rewrote `sprint-status.yaml` mid-run:** the trail covers the in-scope set **as resolved at Stage 1** — the ids this run actually acted on, the replaced parent among them. Child rows the decomposition created were resolved by no Stage 1 and driven by nothing here; they belong to the next invocation's trail (`references/execute.md` says the same at the decomposition terminal). Their cells would render `n/a` either way — the difference is whether the delivered evidence names rows that did not exist when the run began.
|
|
44
45
|
|
|
45
46
|
Naming no story (or a blank id) is refused: the script exits `2` with a usage line and writes nothing, rather than rendering a well-formed trail of zero sections that traces nothing and then gets named in the run report as delivered evidence. This does not contradict the fail-soft property below — `--story` is an **argument, not one of the sources**: an absent source is evidence the trail reports as `n/a`, while an absent story list is a malformed invocation, and there is nothing to render fail-soft *about*. That refusal is an **invocation error, not a gate verdict** — the same lane a missing `--run-dir` or `--profile` already occupies. It is never an escalation and never a reason to block a run that reached this stage: re-issue the command with the ids (you already hold them, in sprint order), **and either way continue through the remaining finalize steps** — the terminal `run-status.json` write, the headless emit and the health check must still run.
|
|
46
47
|
|
|
@@ -86,7 +87,7 @@ Resolve the mode exactly as the hooks below resolve theirs:
|
|
|
86
87
|
|
|
87
88
|
Two values, and no others. `off` is the shipped default and a complete no-op — no probe, no delegation, no decision-log line, no output; there is nothing to read further in this section. `refresh` refreshes the project's knowledge graph on the way out, so the next session starts from a current one instead of a stale one.
|
|
88
89
|
|
|
89
|
-
**Probe first, and degrade to silence.** Two preconditions, both required: graphify resolves on PATH (`command -v graphify`), and a prior `graphify-out/graph.json` exists under `{project-root}` to update. If either is missing there is nothing to refresh — do nothing, print nothing, and write no `.decision-log.md` entry, so the run stays byte-identical to an `off` run. A "skipped it" log line is exactly the difference that would break that, so do not add one. Absence is silent; failure is logged. They are different events.
|
|
90
|
+
**Probe first, and degrade to silence.** Two preconditions, both required: graphify resolves on PATH (`command -v graphify`), and a prior `graphify-out/graph.json` exists under `{project-root}` to update. If either is missing there is nothing to refresh — do nothing, print nothing, and write no `.decision-log.md` entry, so the run stays byte-identical to an `off` run. A "skipped it" log line is exactly the difference that would break that, so do not add one. Absence is silent; failure is logged. They are different events. **A probe the permission layer refuses to run is a THIRD state**, distinct from both — the ordinary unattended one, and the same shape ingest-and-scope.md names for the Cross-Session Recall probe: neither precondition was *evaluated*, so "missing → silent" misfiles a refusal as a resolved absence, and the `WARN graphify-refresh-failed` below asserts a refresh that never started. Log one line — `NOTE graphify-probe-unavailable` — and skip the rest of the section, so the next reader can tell a stale graph from an intentionally ungraphed project.
|
|
90
91
|
|
|
91
92
|
The graph precondition is not defensive padding. Refresh means refresh: with no graph there is nothing to update, and building one from nothing walks the whole corpus, which is the opposite of what a bounded step on the way out may do. A first-ever run in this mode therefore refreshes nothing and says nothing.
|
|
92
93
|
|
|
@@ -102,13 +103,13 @@ Deleting code shrinks the graph, and that is the correct outcome, not a failure:
|
|
|
102
103
|
|
|
103
104
|
Pass no other flags. Unlike `graphify extract`, this subcommand rejects an unknown option with a usage error instead of ignoring it, so a flag that stops being real fails loudly here rather than silently doing nothing.
|
|
104
105
|
|
|
105
|
-
The delegation is hard time-boxed by the `timeout 300` prefix above and is **not retried**.
|
|
106
|
+
The delegation is hard time-boxed by the `timeout 300` prefix above and is **not retried**. **Anything other than a clean exit 0 is the same event** — a non-zero exit, a timeout, or a refusal to execute at all (a permission or sandbox denial, which is the ordinary outcome on an unattended host that has not pre-approved the command). Log one `WARN graphify-refresh-failed` line to `.decision-log.md` and move on; never retry, and never stop to ask for approval. A denial is **not** the silent-absence branch above — both preconditions were met, so there is something to refresh — and it is **not a standing fact about the host**: probe and attempt once on every run rather than skipping the step because an earlier run was denied. An operator who wants this step to actually execute unattended should add the binary to their own `{workflow.allowlist_commands}`; the module does not ship it there, because this integration is off by default.
|
|
106
107
|
|
|
107
108
|
**This never gates.** It is advisory-only in the same sense Cross-Session Recall is — it can add an artifact to the developer's machine, and it can change nothing else. A graphify failure, timeout or absence **never changes the gate verdict** and **never changes the terminal envelope**: the run's outcome (complete, blocked or partial-complete), the recorded run-status and the emitted JSON are unchanged whether this step ran, failed, or never fired at all. This section is the only site that calls graphify — no preflight step, no per-story step and no gate step does.
|
|
108
109
|
|
|
109
110
|
## Record the terminal run-status
|
|
110
111
|
|
|
111
|
-
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
|
|
112
|
+
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).
|
|
112
113
|
|
|
113
114
|
## Surface the deferred-work ledger
|
|
114
115
|
|
|
@@ -130,7 +131,7 @@ Execute may already have pinged when it first observed the escalation marker, so
|
|
|
130
131
|
|
|
131
132
|
When the resolved `{workflow.on_escalation}` is non-empty, follow it as an instruction (a prompt to run or a shell command), stating alongside it **the escalating story id** and the path to that story's typed `escalation-<story_id>.json` sidecar as the context it carries, and only then write the fired-marker. A resolved-empty value is a silent no-op — nothing fires and no fired-marker is written — so an empty hook can never suppress a later real one.
|
|
132
133
|
|
|
133
|
-
This is a side effect on the way out, never a gate on the exit: a hook that errors, hangs or is missing must not change the emitted JSON, the status, or the run-status already recorded.
|
|
134
|
+
This is a side effect on the way out, never a gate on the exit: a hook that errors, hangs or is missing must not change the emitted JSON, the status, or the run-status already recorded.
|
|
134
135
|
|
|
135
136
|
## Headless output
|
|
136
137
|
|
|
@@ -145,11 +146,10 @@ build_headless_envelope(<blocker list>, <path to this run's .decision-log.md>, r
|
|
|
145
146
|
|
|
146
147
|
**Both emits are also written to `{workflow.implementation_artifacts}/run-result.json` by `scripts/headless_envelope.py` itself, which is the writer of that file** — so an automator reads a file at a pinned path instead of scraping the transcript for the terminal verdict. The adapter serializes once and hands the same string to both sinks, so the file is byte-identical to what you emit on stdout: print exactly what it produced, do not re-serialize the dict yourself. The write is best-effort and never a gate on the exit — if it fails, the adapter logs `WARN run-result-write-failed` to `.decision-log.md` and the run still emits.
|
|
147
148
|
|
|
148
|
-
|
|
149
|
+
Two constraints on that file:
|
|
149
150
|
|
|
150
151
|
- **Headless only.** An attended run writes no `run-result.json`. An operator who found a stale one from an attended run would read it as a headless terminal, so do not "helpfully" write it in both modes.
|
|
151
152
|
- **Path-pinned and overwrite-in-place**, exactly like `run-status.json`: a second run against the same `{workflow.implementation_artifacts}` overwrites the first run's result.
|
|
152
|
-
- **No `--parallel` trust claim.** The fan-out's worktree agents each see their own `{workflow.implementation_artifacts}`, so there is no single `run-result.json` an automator can read for a fan-out run — the same scope note that binds `.baseline-<story>`, `run-status.json` and the escalation sidecars.
|
|
153
153
|
|
|
154
154
|
The emitted object is the **same five-canonical-key shape every headless exit point honors** (Stage 1 first-touch / already-done blocks, Stage 2 preflight block, and this Stage 6 final emit): the five keys `status`/`skill`/`decision_log`/`report`/`deferred_work` are **always present** (`report` and `deferred_work` `null` when not produced), so a caller parsing them never raises a KeyError. A **complete** emit is those five; a **blocked** exit appends a sixth, `reason` (the one-line cause):
|
|
155
155
|
|