bmad-module-ultracode-goal 2.2.0 → 2.3.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 +2 -2
- package/README.md +12 -4
- package/docs/_internal/RELEASING.md +3 -2
- package/docs/architecture.md +6 -6
- package/docs/comparison.md +25 -25
- package/docs/gate-model.md +1 -1
- package/docs/getting-started.md +9 -5
- package/docs/how-it-works.md +5 -5
- package/docs/index.md +1 -1
- package/docs/operating-tips.md +1 -1
- package/docs/troubleshooting.md +6 -3
- package/docs/why-ultracode-goal.md +3 -3
- package/package.json +6 -2
- package/skills/ucg-formalize/SKILL.md +11 -4
- package/skills/ucg-resolve/SKILL.md +4 -4
- package/skills/ucg-status/SKILL.md +21 -8
- package/skills/ultracode-goal/SKILL.md +4 -4
- package/skills/ultracode-goal/assets/module.yaml +1 -1
- package/skills/ultracode-goal/references/define-done.md +3 -1
- package/skills/ultracode-goal/references/execute.md +16 -16
- package/skills/ultracode-goal/references/finalize.md +6 -5
- package/skills/ultracode-goal/references/gate.md +18 -12
- package/skills/ultracode-goal/references/preflight.md +20 -12
- package/skills/ultracode-goal/scripts/drive_epic.py +11 -6
- package/skills/ultracode-goal/scripts/gate_trail.py +107 -18
- package/skills/ultracode-goal/scripts/headless_envelope.py +20 -6
- package/skills/ultracode-goal/scripts/hooks/budget_stop.py +41 -22
- package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +26 -6
- package/skills/ultracode-goal/scripts/preflight_check.py +237 -12
- package/skills/ultracode-goal/scripts/status_render.py +96 -19
- package/tools/cli/lib/platform-codes.yaml +1 -1
- package/tools/cli/lib/ui.js +1 -1
- package/tools/validate-docs-links.js +302 -29
|
@@ -134,10 +134,17 @@ own unreadable content).
|
|
|
134
134
|
reflects the fixes — the remediate-then-re-run loop. The verdict mapping in step 4
|
|
135
135
|
reads the post-remediation kernel verdict.
|
|
136
136
|
|
|
137
|
-
**Remediation halt catch-all.** If a remediation sub-skill itself fails
|
|
138
|
-
|
|
139
|
-
sub-skill and the exact input it needed,
|
|
140
|
-
|
|
137
|
+
**Remediation halt catch-all.** If a remediation sub-skill itself fails, is not installed
|
|
138
|
+
(the Skill tool does not know its name), or blocks on interactive input, do not re-invoke
|
|
139
|
+
it blind: record a non-remediable gap naming the sub-skill and the exact input it needed,
|
|
140
|
+
and let the verdict mapping route the run to `status=blocked`. A `bmad-create-story` that
|
|
141
|
+
is not installed is the likely case (BMAD Method 6.12 or later ships it as a deprecated
|
|
142
|
+
shim a fresh install leaves out unless asked for): name the operator's fix, run from the
|
|
143
|
+
project root and pinned to the installed version (`installation.version` in
|
|
144
|
+
`_bmad/_config/manifest.yaml`) so it does not also upgrade BMAD:
|
|
145
|
+
`npx bmad-method@<version> install --directory . --shims --yes`. Never substitute another
|
|
146
|
+
skill (`bmad-build`, `bmad-build-auto`) or write the story file or its acceptance criteria
|
|
147
|
+
by hand. Likewise cap the loop at one pass per gap: if a kernel re-run still
|
|
141
148
|
reports a gap whose `kind`+`source` a prior pass already remediated, the fix did not take —
|
|
142
149
|
record it as a non-remediable blocker and route to `status=blocked` rather than re-entering
|
|
143
150
|
step 2, so the remediate-then-re-run loop always converges instead of spinning silently.
|
|
@@ -197,11 +197,11 @@ The two dispositions are genuinely different things, not two names for one:
|
|
|
197
197
|
**Closing a `budget-overrun` escalation also resets that story's turn counter** — delete
|
|
198
198
|
`{workflow.implementation_artifacts}/.budget-<story_id>.json`, or set its `turns` to `0`.
|
|
199
199
|
The Stop hook's counter is persistent and monotonic
|
|
200
|
-
(`{ucg-root}/scripts/hooks/budget_stop.py` increments it every Stop event and
|
|
201
|
-
once it reaches the ceiling), and no ordinary resume clears it — the Stage 2 arming purge
|
|
200
|
+
(`{ucg-root}/scripts/hooks/budget_stop.py` increments it every Stop event and marks
|
|
201
|
+
the story once it reaches the ceiling), and no ordinary resume clears it — the Stage 2 arming purge
|
|
202
202
|
(`{ucg-root}/references/preflight.md`, step 5) deliberately skips it on re-entry so a story cannot evade its ceiling by stopping and
|
|
203
|
-
resuming. Leave it standing here and the resumed story escalates again
|
|
204
|
-
|
|
203
|
+
resuming. Leave it standing here and the resumed story escalates again at the resume's
|
|
204
|
+
step-0 ceiling check, before it has done a single turn of the work the operator just authorized, and
|
|
205
205
|
the close would apply in name only. Answering a budget overrun by re-scoping, splitting,
|
|
206
206
|
or handing off the story *is* the operator granting it a fresh budget, so the counter that
|
|
207
207
|
recorded the exhausted one has no claim on the resumed run.
|
|
@@ -146,26 +146,39 @@ Three things are worth saying out loud alongside it:
|
|
|
146
146
|
**Escalations render from the typed sidecar where one exists.** Where no readable one does,
|
|
147
147
|
the block carries one of two lines, and they mean different things:
|
|
148
148
|
|
|
149
|
-
- `escalation (unpromoted:
|
|
150
|
-
hook's raw marker is on disk
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
149
|
+
- `escalation (unpromoted: no gate verdict yet, or the session ended before Execute
|
|
150
|
+
promoted it)`: only the Stop hook's raw marker is on disk, for a story that has not
|
|
151
|
+
advanced. Execute promotes that marker only when the story's gate escalates it on its
|
|
152
|
+
turn count, so while the gate has not ruled this is the expected state; otherwise it
|
|
153
|
+
is the residual of a session that died before Execute promoted it, and the only
|
|
154
|
+
evidence that the escalation happened at all. Report it as an escalation that may be
|
|
155
|
+
pending (the gate may not have ruled yet) whose typed record is not written yet, and
|
|
156
|
+
leave the marker alone.
|
|
154
157
|
- `escalation (typed record present but unreadable)` - the `escalation-<story>.json` named
|
|
155
158
|
on the `- source:` line was written and then would not parse, which is the half-written
|
|
156
159
|
file a session killed mid-write leaves. "Never promoted" would be the opposite of what
|
|
157
160
|
happened: report it as a typed record that needs repair, because `/ucg-resolve` reads
|
|
158
161
|
that same file to reconstruct the pending decision and cannot parse it either.
|
|
159
162
|
|
|
163
|
+
A raw marker for a story the gate advanced is not an escalation at all: the gate decided
|
|
164
|
+
completion and the overrun is a sizing note in the decision log. A story counts as
|
|
165
|
+
advanced when its heartbeat entry's verdict is `advance` or `defer`, or when its
|
|
166
|
+
`sprint-status.yaml` row reads `done` (a later invocation's heartbeat no longer lists
|
|
167
|
+
it). It renders under stories as `turn ceiling reached; the story advanced at its gate,
|
|
168
|
+
so this is a sizing note and nothing is pending`, on that story's row, or on a line of
|
|
169
|
+
its own when the heartbeat no longer lists it, and not under escalations.
|
|
170
|
+
|
|
160
171
|
A marker and an unreadable sidecar can both be on disk for one story, and the marker wins
|
|
161
172
|
the render, so an `unpromoted` block is worth one directory check before you report the
|
|
162
173
|
typed record as never written.
|
|
163
174
|
|
|
164
175
|
## Optional diff-viewer affordance
|
|
165
176
|
|
|
166
|
-
When `hunk` is on PATH, each story that recorded a baseline commit gains
|
|
167
|
-
|
|
168
|
-
|
|
177
|
+
When `hunk` is on PATH, each story that recorded a baseline commit gains copy-paste
|
|
178
|
+
`hunk show <commit>` lines, so a reader can go straight from a story row to its diff:
|
|
179
|
+
one line per commit in the story's range (its implementation commit and the gate's
|
|
180
|
+
evidence commit) when the repository is readable, else one line for the story's
|
|
181
|
+
recorded end commit, or for its baseline when no end commit was recorded. When it is not on PATH, nothing about it is rendered and the render is otherwise
|
|
169
182
|
unchanged.
|
|
170
183
|
|
|
171
184
|
It is an affordance, never a dependency, and it is confined to stdout. The probe's result
|
|
@@ -9,7 +9,7 @@ description: Runs a BMAD Epic autonomously to a machine-checked Definition-of-Do
|
|
|
9
9
|
|
|
10
10
|
This skill autonomously delivers a BMAD Epic to a **machine-checked** Definition-of-Done. Act as an autonomous delivery conductor — a staff engineer who also owns the release gate. It preflights the Epic to a hard, *remediated* green light, turns acceptance criteria into executable tests with the Test Architect (TEA), drives the stories to completion, and advances only when TEA's deterministic quality gate reads PASS — capturing what it learns to Auto Memory so the next run is sharper. Your output is a delivered, gate-passed Epic, a run report, and a deferred-work ledger of anything safely parked for later.
|
|
11
11
|
|
|
12
|
-
Module `bmad-module-ultracode-goal`. It orchestrates the installed BMAD epic toolbox (`bmad-sprint-planning`, `bmad-create-story`, `bmad-dev-story`, `bmad-code-review`, `bmad-correct-course`, `bmad-retrospective`) and the TEA gates (`bmad-testarch-framework`, `-ci`, `-test-design`, `-atdd`, `-automate`, `-test-review`, `-nfr`, `-trace`). It composes Claude Code primitives
|
|
12
|
+
Module `bmad-module-ultracode-goal`. It orchestrates the installed BMAD epic toolbox (`bmad-sprint-planning`, `bmad-create-story`, `bmad-dev-story`, `bmad-code-review`, `bmad-correct-course`, `bmad-retrospective`) and the TEA gates (`bmad-testarch-framework`, `-ci`, `-test-design`, `-atdd`, `-automate`, `-test-review`, `-nfr`, `-trace`). It composes Claude Code primitives (Auto Mode, Auto Memory, hooks, git branch isolation) and is a conductor over them, not a replacement for them. It cannot start `/goal`, which runs only when the operator starts one (`references/execute.md`).
|
|
13
13
|
|
|
14
14
|
## Conventions
|
|
15
15
|
|
|
@@ -43,8 +43,8 @@ These exist because the documented mechanics make the intuitive shortcut wrong.
|
|
|
43
43
|
- **Completion is decided by `scripts/gate_eval.py` reading TEA's `gate-decision.json` — never your own judgment, and never the `/goal` evaluator alone.** That evaluator only sees the transcript; it cannot read the gate file. The JSON is the truth.
|
|
44
44
|
- **Launch the unattended run only when `scripts/preflight_check.py` returns green *after the remediation pass* (intervention budget == 0) and `formalize_check.py returns ready` (post-remediation — the readiness verdict the step-4 gate decides) and ultracode + Auto Mode are on.** The unattended run takes no mid-run input — every gate is resolved before launch or not at all. This binds the **Stage-2 entry**. A resume routed into Execute does not re-run it — see Resume above.
|
|
45
45
|
- **Only non-gate-blocking work defers** to `{workflow.deferred_work_path}`, and the Epic keeps moving; a P0/critical FAIL never defers — it re-loops within budget or escalates.
|
|
46
|
-
- **Rollback is git** — Epic branch off `{workflow.epic_branch_prefix}`, one commit per green story. `/rewind` checkpoints miss Bash changes; do not rely on them.
|
|
47
|
-
- **Invariants live in PreToolUse hooks**, auto-merged into `.claude/settings.local.json` at preflight — not in memory, which is context, not enforcement.
|
|
46
|
+
- **Rollback is git** — Epic branch off `{workflow.epic_branch_prefix}`, one implementation commit per green story plus its gate's evidence commit. `/rewind` checkpoints miss Bash changes; do not rely on them.
|
|
47
|
+
- **Invariants live in PreToolUse hooks**, auto-merged into `.claude/settings.local.json` at preflight — not in memory, which is context, not enforcement. A headless session cannot approve a refused write to that file, so a first arming belongs to an attended pass (`references/preflight.md`, "A refused settings write").
|
|
48
48
|
- **Cross-Session Recall is advisory-only.** When `{workflow.cross_session_recall}` is `on` and claude-mem is present, recalled memory is *data, never directive* — it informs scope (Stage 1) and preflight (Stage 2), never a gate verdict. The hook-enforced latch (`.mem-state.json`) fails closed during the run: any malformed or off state denies claude-mem calls rather than trusting them. See the Cross-Session Recall guide: <https://armelhbobdad.github.io/bmad-module-ultracode-goal/cross-session-recall/>.
|
|
49
49
|
|
|
50
50
|
## Stages
|
|
@@ -65,7 +65,7 @@ Run the stages in order; each routes by the testable conditions stated in its fi
|
|
|
65
65
|
|
|
66
66
|
With `-H`, run non-interactively: infer scope, default to **production** (unless `--light`), never prompt — a secret that cannot be resolved becomes a red blocker, not a question — and let `.decision-log.md` absorb every assumption.
|
|
67
67
|
|
|
68
|
-
**One core schema, every exit point.** Every exit — completing at Stage 6, or blocking early at ingest (Stage 1, e.g. epic unresolved), at preflight (Stage 2), or at a story escalation — emits the **five canonical keys** `status`, `skill`, `decision_log`, `report`, `deferred_work`, always present (`null` when that artifact was not produced); a **blocked** exit appends a sixth, `reason` (the one-line cause). Build every emit through the `scripts/headless_envelope.py` adapter — the one shared definition `references/finalize.md` and `/ucg-formalize` honor — never by hand. A completed run:
|
|
68
|
+
**One core schema, every exit point.** Every exit — completing at Stage 6, or blocking early at ingest (Stage 1, e.g. epic unresolved), at preflight (Stage 2), or at a story escalation — emits the **five canonical keys** `status`, `skill`, `decision_log`, `report`, `deferred_work`, always present (`null` when that artifact was not produced); a **blocked** exit appends a sixth, `reason` (the one-line cause). Build every emit through the `scripts/headless_envelope.py` adapter — the one shared definition `references/finalize.md` and `/ucg-formalize` honor — never by hand. Attempt that adapter call once even when other calls this session were refused, since a refusal of one call is not a refusal of another; if the adapter call itself is refused, build nothing by hand, record the block and the refusal in `.decision-log.md` and stop, leaving absent the `run-result.json` cleared at entry, which is the fail-closed signal. A completed run:
|
|
69
69
|
|
|
70
70
|
```json
|
|
71
71
|
{"status": "complete",
|
|
@@ -2,7 +2,7 @@ code: ultracode-goal
|
|
|
2
2
|
name: "UltraCode Goal"
|
|
3
3
|
header: "Run a BMAD Epic autonomously to a deterministic, TEA-gated Definition-of-Done"
|
|
4
4
|
subheader: "Preflight to a remediated green light, define done as executable tests, advance only on a machine-checked gate verdict"
|
|
5
|
-
description: "Orchestrates the BMAD epic toolbox + TEA quality gates + Claude Code primitives (
|
|
5
|
+
description: "Orchestrates the BMAD epic toolbox + TEA quality gates + Claude Code primitives (Auto Mode, Auto Memory, hooks, git branch isolation) to deliver an Epic unattended. Completion is decided by a deterministic gate_eval.py reading TEA's gate-decision.json — never the model's own judgment."
|
|
6
6
|
default_selected: false
|
|
7
7
|
|
|
8
8
|
# LLM-readable module documentation. The installer registers this as the
|
|
@@ -14,7 +14,7 @@ Run `bmad-testarch-test-design` in **Epic-Level Mode** for the Epic. This is the
|
|
|
14
14
|
|
|
15
15
|
Epic-Level Mode is selected by the presence of `sprint-status.yaml` (preflight reports `sprint_status_present`); if test-design prompts for system-vs-epic, choose **epic**. Force **Create** mode if it offers Resume/Validate/Edit — those are interactive and stall an unattended run.
|
|
16
16
|
|
|
17
|
-
**Test-design runs on any stack — do not skip it on a non-web module.** The framework fitness caveat in `references/preflight.md` is scoped to TEA's *browser generators*: ATDD in this stage,
|
|
17
|
+
**Test-design runs on any stack — do not skip it on a non-web module.** The framework fitness caveat in `references/preflight.md` is scoped to TEA's *browser generators*: ATDD in this stage, which on TEA 1.27.2 emits only Playwright/TypeScript scaffolds. Test-design is not one of them — it is risk-and-priority analysis over the planning corpus, and its output is a document, not a browser harness — and neither is trace, which runs on any stack too. So a `pytest` or `npm-test` module gets the same risk matrix and priorities a web module does. Reading the caveat as "the whole TEA chain is web-only" is what produces an empty test-design directory and leaves the ACs with no risk backbone to sharpen against; when ATDD's generator genuinely cannot serve the stack, the substitution is the hand-established red phase in gate.md's non-web section, and hand-authored trace artifacts only where trace itself cannot run; never a skipped test-design.
|
|
18
18
|
|
|
19
19
|
A `CONCERNS`-grade gap in the test plan (e.g. an `UNKNOWN` NFR threshold that does not block any P0 story) appends to `{workflow.deferred_work_path}` and the Epic keeps moving. A genuine red gap — no risk coverage for a P0 flow — is not deferrable; resolve it before proceeding to per-story work.
|
|
20
20
|
|
|
@@ -34,6 +34,8 @@ For every **in-scope** story, in sprint order:
|
|
|
34
34
|
|
|
35
35
|
**In `--light`:** run step 1 (`bmad-create-story`) but **skip step 2 (`bmad-testarch-atdd`)** — `--light` produces no executable red-phase acceptance tests. The story file and its acceptance criteria become the Definition-of-Done and the oracle `bmad-testarch-trace` resolves the Stage 5 gate against, mirroring gate.md's `--light` branch (which runs only `bmad-testarch-trace`). The per-Epic test-design above still runs in `--light`: `bmad-testarch-trace` consumes its risk scores and P0–P3 priorities when they are available, and they are the backbone you sharpen the ACs against in either profile. Sharpen the ACs here exactly as you would for production — under `--light` they are the *only* machine-checkable DoD a story gets, so vague ACs leave the trace gate nothing to resolve against.
|
|
36
36
|
|
|
37
|
+
**A delegated skill that is not installed.** If a skill this stage delegates to is not installed (the Skill tool does not know its name; for example `bmad-create-story`, a deprecated shim on BMAD Method 6.12 or later, which a fresh install leaves out unless asked for with `--shims` or Yes at the installer's shim prompt, and an update removes when told not to keep it), do not substitute another skill (`bmad-build`, `bmad-build-auto`) and do not write the story file or its tests by hand: Stage 4 and the gate read the artifacts these skills produce, and a stand-in reaches them looking like the real thing. Escalate as Execute's sub-skill halt catch-all does (`references/execute.md`: write the typed escalation sidecar, then stop), for the story concerned or, when the per-Epic test-design is the missing skill, for the Epic's first in-scope story. Name the cause in `decision_needed`: Stage 2's `bmad_skills` blocker refuses a launch without `bmad-create-story`, so a missing `bmad-create-story` here means the install changed after preflight ran, while preflight does not probe the `bmad-testarch-*` skills, so a missing TEA skill means TEA is not installed for this project.
|
|
38
|
+
|
|
37
39
|
## Exit condition (testable)
|
|
38
40
|
|
|
39
41
|
Stage 3 is complete, and Stage 4 may begin, when **all three** hold:
|
|
@@ -2,15 +2,15 @@
|
|
|
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
|
-
One path: the **sequential `/goal` spine
|
|
5
|
+
One path: the **sequential `/goal` spine**, named for the `/goal`-style condition each story's drive is written against; the conductor cannot start a live `/goal` (see "Authoring the `/goal` condition"). (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
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
|
|
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 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 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
10
|
|
|
11
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
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,
|
|
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, the five injected hook env vars, and that `bmad-create-story` and `bmad-dev-story` are still installed (a BMAD update between spawns can remove 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 — 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 BMAD 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`), 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.
|
|
14
14
|
|
|
15
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.
|
|
16
16
|
|
|
@@ -44,9 +44,9 @@ Then terminate as the work-bound section below describes for an invocation that
|
|
|
44
44
|
|
|
45
45
|
For each in-scope story, in sprint order, run this loop:
|
|
46
46
|
|
|
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
|
|
47
|
+
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.
|
|
48
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
|
|
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 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.
|
|
50
50
|
|
|
51
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:
|
|
52
52
|
|
|
@@ -64,10 +64,10 @@ For each in-scope story, in sprint order, run this loop:
|
|
|
64
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.
|
|
65
65
|
|
|
66
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.
|
|
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
|
|
67
|
+
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. 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, 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.
|
|
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 any transcript-only evaluator (a `/goal` an operator started, say) 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.
|
|
69
69
|
|
|
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.
|
|
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. 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 hand-author the work it would have produced.
|
|
71
71
|
|
|
72
72
|
### The per-invocation work bound (`--max-stories N`)
|
|
73
73
|
|
|
@@ -75,7 +75,7 @@ When the operator passed `--max-stories N`, count the stories this **invocation*
|
|
|
75
75
|
|
|
76
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.
|
|
77
77
|
|
|
78
|
-
**Check it at the story boundary and nowhere else.** The tempting place is wherever the count happens to tick over, and that is the trap: the loop above writes a baseline marker at step 0, a tests-ran marker at step 2, and commits at step 4, so a bound applied mid-story abandons a story with markers on disk and no commit. Evaluate it only after the story's Stage-5 verdict has landed, i.e. between laps, never inside one.
|
|
78
|
+
**Check it at the story boundary and nowhere else.** The tempting place is wherever the count happens to tick over, and that is the trap: the loop above writes a baseline marker at step 0, a tests-ran marker at step 2, and commits at step 4, so a bound applied mid-story abandons a story with markers on disk and no commit. Evaluate it only after the story's Stage-5 verdict has landed, and after the advance route's evidence commit when one is owed, i.e. between laps, never inside one.
|
|
79
79
|
|
|
80
80
|
**A bounded stop is a completion, not an abort — Stage 6 still runs in full.** Auto Memory capture, the decision-log audit, the run report, the gate trail over the run's **in-scope** stories (finalize.md requires every in-scope id, so the ones this invocation did not drive render `n/a` under its fail-soft source rule rather than being omitted), and (headless) the terminal health check all happen exactly as they would on a full run, and the emit is the ordinary five-key envelope with `status` `complete`. The one thing that does *not* happen is the Epic-level gate, per the paragraph above, and for the same reason the `on_epic_complete` hook stays unfired: the Epic did not complete. Returning early *past* finalize would produce no report and, worse, no `run-result.json` at the pinned path — and the documented automator tests for that file's presence, so a bounded invocation that skipped the terminal would be indistinguishable from one that was killed. There is deliberately **no third status value**: `complete` here means "this invocation finished its work without blocking", and a caller that needs to know whether the Epic still owes stories re-reads sprint-status, never the status word.
|
|
81
81
|
|
|
@@ -89,21 +89,21 @@ Emit **`blocked`**, and carry the distinction in the typed escalation sidecar ra
|
|
|
89
89
|
|
|
90
90
|
### Authoring the `/goal` condition
|
|
91
91
|
|
|
92
|
-
|
|
92
|
+
**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:
|
|
93
93
|
|
|
94
94
|
- 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.
|
|
95
|
-
- Include the literal escape: **"…or stop after {workflow.max_turns_per_story} turns."**
|
|
95
|
+
- 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.
|
|
96
96
|
- 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.
|
|
97
97
|
|
|
98
98
|
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.
|
|
99
99
|
|
|
100
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.
|
|
101
101
|
|
|
102
|
-
**Escalation ping.**
|
|
102
|
+
**Escalation ping.** When a story's gate escalates it on the turn count (`references/gate.md`), before Stage 6, 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. The story whose gate just escalated it on the count is in scope whatever its marker's age, since its count, not the marker's date, already shows the escalation is this run's. 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. A marker whose story the gate advanced is never promoted or pinged, as "Promoting the turn-budget marker" below says. On the first in-scope marker whose story the gate escalated on the turn count, 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.
|
|
103
103
|
|
|
104
104
|
### Escalation sidecar
|
|
105
105
|
|
|
106
|
-
Every escalation route — the sub-skill halt catch-all above, the gate's `escalate` verdict, and a story
|
|
106
|
+
Every escalation route — the sub-skill halt catch-all above, the gate's `escalate` verdict, and a story escalated on its turn count (at its gate, or at a resume already at the ceiling) — writes **one** typed sidecar at `{workflow.implementation_artifacts}/escalation-<story_id>.json`, on top of whatever it logs in prose. A status read and a resume both have to reconstruct *which* decision is pending, and the run that escalated is exactly the run whose transcript is no longer in front of anyone. Prose alone leaves them re-parsing a log; a typed file does not.
|
|
107
107
|
|
|
108
108
|
It is a single JSON object, exactly these four string fields and no fifth:
|
|
109
109
|
|
|
@@ -118,9 +118,9 @@ One object, never an array: the file is already named per story, so a list would
|
|
|
118
118
|
|
|
119
119
|
`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.
|
|
120
120
|
|
|
121
|
-
**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. **Execute is the sole promoter of that markdown
|
|
121
|
+
**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.
|
|
122
122
|
|
|
123
|
-
**Leave the markdown in place — never delete it, never rewrite it.** It is the
|
|
123
|
+
**Leave the markdown in place — never delete it, never rewrite it.** It is the hook's own record of the count. For a story that advanced it is the sizing note's source, and for a story that escalates it is the residual that survives a session which died before this promotion, so consuming it could destroy the only evidence that an escalation happened at all.
|
|
124
124
|
|
|
125
125
|
## Retired — `--parallel`
|
|
126
126
|
|
|
@@ -162,7 +162,7 @@ When the prior snapshot's `budget_used.turns` and the current `.budget-<story>.j
|
|
|
162
162
|
|
|
163
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.
|
|
164
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
|
|
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 stays put through all of it (at `0` for a story not yet driven, at the inherited count for a mid-story resume), because the hook counts only Stops booked to the current story: an unmoved count 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
166
|
|
|
167
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.
|
|
168
168
|
|
|
@@ -25,10 +25,11 @@ Produce a report (write it as a peer of `.decision-log.md` in the run folder, e.
|
|
|
25
25
|
|
|
26
26
|
- Epic and profile (production / `--light`), branch off `{workflow.epic_branch_prefix}`.
|
|
27
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.
|
|
28
|
-
- Per-story outcome: gate_status and verdict (advance / defer / reloop / escalate), and any re-loops spent against budget.
|
|
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
|
+
- 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.
|
|
30
31
|
- 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.
|
|
31
|
-
- Turns
|
|
32
|
+
- Turns the Stop hook counted per story (`{workflow.implementation_artifacts}/.budget-<story_id>.json`, `0` when the hook never fired for it), against `{workflow.max_turns_per_story}`.
|
|
32
33
|
- Learnings captured and where they went (memory vs CLAUDE.md).
|
|
33
34
|
- A pointer to the deferred-work ledger and its open-item count.
|
|
34
35
|
- 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.
|
|
@@ -41,14 +42,14 @@ Write the per-story evidence trail as **`gate-trail.md`, a peer of `run-report.m
|
|
|
41
42
|
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}
|
|
42
43
|
```
|
|
43
44
|
|
|
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.
|
|
45
|
+
**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 its own `.commit-<story_id>` when that marker names a commit, else 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.
|
|
45
46
|
|
|
46
47
|
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.
|
|
47
48
|
|
|
48
49
|
Two properties are load-bearing, so do not "improve" them:
|
|
49
50
|
|
|
50
51
|
- **It renders verdicts, it never forms one.** The verdict cell is the verdict the run already recorded, or the gate artifact's `gate_status` mapped through the gate's own table. The production AND ran once, when the gate decided; re-running it here would be a second, later judgment on the same story. A story whose verdict was not `advance` is shown as it was decided — never quietly green.
|
|
51
|
-
- **It fails soft.** Every source is optional: a missing or unreadable checklist, trace report, gate file or baseline renders `n/a` in its cell and the trail continues. This is the opposite of the gate, which fails closed, and deliberately so — the trail has no authority, and failing closed here would turn a reporting bug into a blocked run. Under `--light` there is no acceptance checklist by design, so those sections synthesize from the hand-authored trace
|
|
52
|
+
- **It fails soft.** Every source is optional: a missing or unreadable checklist, trace report, gate file or baseline renders `n/a` in its cell and the trail continues. This is the opposite of the gate, which fails closed, and deliberately so — the trail has no authority, and failing closed here would turn a reporting bug into a blocked run. Under `--light` there is no acceptance checklist by design, so those sections synthesize from the trace report (TEA-authored, or hand-authored where trace cannot run) and gate decision instead.
|
|
52
53
|
|
|
53
54
|
**Optional diff viewer — detect, then degrade to silence.** The trail's commit column names a sha per story and the run report names the Epic branch, but neither opens a diff. When `hunk` is detected on PATH (`which hunk`), the run report may point at what it already names: `hunk show <commit>` for one story's commit, `hunk diff <epic-branch>` for the run as a whole, so a reader auditing the evidence can open a diff without reconstructing the range by hand. Absent `hunk`, print nothing — no suggestion and no warning that it is missing, and both surfaces read exactly as they did before. It is a render affordance and nothing else: do not add it to `{workflow.allowlist_commands}`, do not add a preflight check for it, and never let it reach a machine surface — not the gate verdict JSON, not the headless envelope, not the terminal `run-status.json`. Those are parsed by callers that will not have it installed.
|
|
54
55
|
|
|
@@ -127,7 +128,7 @@ If the resolved `{workflow.on_epic_complete}` is non-empty, follow it as the fin
|
|
|
127
128
|
|
|
128
129
|
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.
|
|
129
130
|
|
|
130
|
-
Execute may already have pinged when
|
|
131
|
+
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 — `<run-id>` is the run id minted at Stage 1, 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: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_escalation`
|
|
131
132
|
|
|
132
133
|
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.
|
|
133
134
|
|