bmad-module-ultracode-goal 3.1.0 → 3.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +1 -1
- package/README.md +1 -1
- package/docs/architecture.md +1 -1
- package/docs/gate-model.md +2 -2
- package/docs/how-it-works.md +3 -3
- package/docs/index.md +1 -1
- package/docs/operating-tips.md +3 -2
- package/docs/troubleshooting.md +1 -1
- package/docs/why-ultracode-goal.md +1 -1
- package/package.json +1 -1
- package/skills/ucg-resolve/SKILL.md +11 -1
- package/skills/ucg-status/SKILL.md +3 -2
- package/skills/ultracode-goal/SKILL.md +2 -2
- package/skills/ultracode-goal/references/execute.md +11 -5
- package/skills/ultracode-goal/references/finalize.md +5 -3
- package/skills/ultracode-goal/references/gate.md +69 -13
- package/skills/ultracode-goal/references/ingest-and-scope.md +1 -1
- package/skills/ultracode-goal/scripts/drive_epic.py +49 -0
- package/skills/ultracode-goal/scripts/gate_trail.py +5 -3
- package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +800 -27
- package/skills/ultracode-goal/scripts/mutate_check.py +158 -32
- package/skills/ultracode-goal/scripts/preflight_check.py +5 -1
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"name": "bmad-module-ultracode-goal",
|
|
20
20
|
"source": "./",
|
|
21
21
|
"description": "Supercharges BMAD with Claude Code's Auto Mode, Auto Memory, and hooks: autonomous Epic execution to a machine-checked, TEA-gated Definition-of-Done. Execute Epics. Accumulate Knowledge. Deliver Outcomes.",
|
|
22
|
-
"version": "3.
|
|
22
|
+
"version": "3.2.0",
|
|
23
23
|
"author": {
|
|
24
24
|
"name": "Armel"
|
|
25
25
|
},
|
package/README.md
CHANGED
|
@@ -102,7 +102,7 @@ A skeptical reader is probably already running one of these. Here is the honest
|
|
|
102
102
|
| Completion authority | `gate_eval.py` reads TEA's `gate-decision.json` | you, story by story | the model's self-assessment | CI, but only after the agent stops |
|
|
103
103
|
| Preflight autonomy gate | hard-gate to remediated green (intervention budget 0)| ad hoc, per story | none | none: CI runs post-hoc |
|
|
104
104
|
| Invariants enforcement | `PreToolUse` hooks in `settings.local.json` | your attention | prompt text (context, not a gate)| CI checks, after the fact |
|
|
105
|
-
| Rollback | git: epic branch, code +
|
|
105
|
+
| Rollback | git: epic branch, code + gate commits per story | manual | `/rewind` (misses Bash changes) | revert after merge |
|
|
106
106
|
| Knowledge capture | Auto Memory + CLAUDE.md split at Finalize | none structured | none structured | none |
|
|
107
107
|
|
|
108
108
|
The alternatives aren't bad; they solve different problems. **UCG solves exactly one: advancing an epic only when a deterministic script confirms the gate passed, and giving you the verdict JSON to check it yourself.**
|
package/docs/architecture.md
CHANGED
|
@@ -34,7 +34,7 @@ Both hooks read their config from env first (so the conductor injects per-run va
|
|
|
34
34
|
|
|
35
35
|
### 3. Budget enforcement
|
|
36
36
|
|
|
37
|
-
Three layers can bound a runaway story, in order of authority: the **in-condition** "…or stop after N turns" clause inside a `/goal` condition (only an operator's own `/goal` condition, which then bounds the session; the conductor cannot start one itself), the **gate re-loop budget** (the conductor reads the hook's turn count before each re-loop, so a `reloop` that would exceed `max_turns_per_story` becomes `escalate`, though that count cannot see re-loops inside one response), and the **Stop hook** as the recorder described above. 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. Rollback is git, not `/rewind` (an Epic branch off a protected branch, one implementation commit per green story plus its gate's evidence
|
|
37
|
+
Three layers can bound a runaway story, in order of authority: the **in-condition** "…or stop after N turns" clause inside a `/goal` condition (only an operator's own `/goal` condition, which then bounds the session; the conductor cannot start one itself), the **gate re-loop budget** (the conductor reads the hook's turn count before each re-loop, so a `reloop` that would exceed `max_turns_per_story` becomes `escalate`, though that count cannot see re-loops inside one response), and the **Stop hook** as the recorder described above. 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. Rollback is git, not `/rewind` (an Epic branch off a protected branch, one implementation commit per green story plus its gate's commits: a test backfill when automate makes one, then the evidence) because `/rewind` checkpoints miss the Bash-driven changes that make up the run.
|
|
38
38
|
|
|
39
39
|
## File layout
|
|
40
40
|
|
package/docs/gate-model.md
CHANGED
|
@@ -103,7 +103,7 @@ The verdict JSON carries the recognised value as `sweep_scope` (or `null`), so a
|
|
|
103
103
|
|
|
104
104
|
## The delta cycle profile
|
|
105
105
|
|
|
106
|
-
A mid-loop re-gate may declare `--cycle-profile delta`: only the assessor dimension(s) whose findings produced the previous reloop re-run in full, while the other assessors re-check their prior artifact against the diff since the commit they assessed. The script caps a delta gate's verdict at `reloop` (defer too, for the sweep-cap reason): a delta gate can say "not yet, and here is why", never move the story. Advancing requires the full instrument, every assessor over a `scope=full` sweep, so the oracle's finality is untouched and a wrong guess costs one extra full gate rather than an unearned advance. The fallback is mechanical: any prior finding without a clean dimension attribution means the full gate runs. `--epic-level` refuses the flag (invocation error, exit 2); omitting it is the full behaviour, and the `cycle_profile` JSON key appears exactly when the flag was supplied.
|
|
106
|
+
A mid-loop re-gate may declare `--cycle-profile delta`: only the assessor dimension(s) whose findings produced the previous reloop re-run in full, while the other assessors re-check their prior artifact against the diff since the commit they assessed. The script caps a delta gate's verdict at `reloop` (defer too, for the sweep-cap reason): a delta gate can say "not yet, and here is why", never move the story. Advancing requires the full instrument, every assessor over a `scope=full` sweep, so the oracle's finality is untouched and a wrong guess costs one extra full gate rather than an unearned advance. The fallback is mechanical: any prior finding without a clean dimension attribution means the full gate runs. `bmad-testarch-automate` sits outside this choice: after a story's first gate cycle, full or delta, it searches only the diff since the previous gate and re-runs the mutation rows behind the gaps that gate backfilled and behind every gap still open, and the full instrument runs it at that scope too. It backfills every gap it finds on a P0 criterion, in any cycle, so trace counts the new test and the script decides; only a gap on another criterion is reported instead, when it lies outside that scope or while operator live results sit at the commit under assessment. A reported gap stays open until a pass at a later commit finds its mutants killed, and it never changes the route a verdict takes. Automate confirms each test it backfills in the same pass, with the test copied into the worktree, and a test that leaves its mutant alive (perhaps an equivalent mutant, which no test can kill) is logged as an `unkilled` gap that no later pass writes another test for while that code stands. `--epic-level` refuses the flag (invocation error, exit 2); omitting it is the full behaviour, and the `cycle_profile` JSON key appears exactly when the flag was supplied.
|
|
107
107
|
|
|
108
108
|
## The thresholds
|
|
109
109
|
|
|
@@ -113,7 +113,7 @@ The P0/P1/overall percentage thresholds (**P0 = 100%, P1 >= 90%, overall >= 80%*
|
|
|
113
113
|
|
|
114
114
|
The production AND is deliberately fail-closed (see the `apply_production_and` docstring in the script): a missing `nfr-assessment.md` or `test-review.md`, or a field the scanners cannot parse, is treated as a **failing** signal, not a neutral or absent one. So if TEA's prose format drifts and the Overall Status or Quality Score cannot be read, an otherwise-`advance` degrades to a conservative `reloop` rather than a silent false-advance. The direction is intentional: the module would rather re-loop a green story than advance a story whose evidence it could not actually read. Likewise, a missing or corrupt gate artifact yields `NOT_EVALUATED` → `escalate`: the gate is never assumed green.
|
|
115
115
|
|
|
116
|
-
This is reinforced by the routing invariant in Stage 5: **a P0/critical FAIL never defers.** Only non-gate-blocking work (CONCERNS, non-critical findings, parked decisions) reaches the deferred-work ledger; a FAIL or a P0/critical finding re-loops within budget or escalates.
|
|
116
|
+
This is reinforced by the routing invariant in Stage 5: **a P0/critical FAIL never defers.** Only non-gate-blocking work (CONCERNS, non-critical findings, parked decisions, and the coverage gaps automate logged as `gate-gap:` lines that are still open) reaches the deferred-work ledger; a FAIL or a P0/critical finding re-loops within budget or escalates. A `gate-gap:` row is neither, whatever its criterion's priority: it reaches the ledger at `med` severity and never re-loops or escalates the story.
|
|
117
117
|
|
|
118
118
|
## Output shape
|
|
119
119
|
|
package/docs/how-it-works.md
CHANGED
|
@@ -78,11 +78,11 @@ Turn the Epic's acceptance criteria into **executable, red-phase acceptance test
|
|
|
78
78
|
|
|
79
79
|
### Stage 4: Execute
|
|
80
80
|
|
|
81
|
-
Drive each in-scope story from its red-phase tests to a green, committed state. Execution is the **sequential `/goal` spine**; per story, in sprint order: set the current story (so the PreToolUse hook can find its marker) → `ucg-dev-story` implements the feature and un-skips the story's ATDD tests → run tests/lint/build and **print the raw output** as evidence → (production) `bmad-testarch-test-review` then `bmad-code-review` → check the commit message against the staged diff (`claim_check.py` lists each path it names that the commit does not touch) and soften any claim the diff's own new lines make that no evidence shows → commit at green (one implementation commit per green story; the gate's
|
|
81
|
+
Drive each in-scope story from its red-phase tests to a green, committed state. Execution is the **sequential `/goal` spine**; per story, in sprint order: set the current story (so the PreToolUse hook can find its marker) → `ucg-dev-story` implements the feature and un-skips the story's ATDD tests → run tests/lint/build and **print the raw output** as evidence → (production) `bmad-testarch-test-review` then `bmad-code-review` → check the commit message against the staged diff (`claim_check.py` lists each path it names that the commit does not touch) and soften any claim the diff's own new lines make that no evidence shows → commit at green (one implementation commit per green story; the gate's commits follow it: a test backfill when automate makes one, then the evidence) → **re-run the suite at this cycle's scope on the committed HEAD (a story only advances off a full-scope sweep)** and print it, because a story's new files are untracked until the commit, so a tracked-files conformance gate can only red once they land; a red here means the story is not done and must be remediated and re-committed before it advances. The conductor writes a per-story `/goal`-style condition that encodes the Definition-of-Done and carries the literal "…or stop after N turns" escape clause, and records it in the decision log. A live `/goal` runs only when you start one, on your own condition, because the conductor cannot start `/goal` itself. The Stop hook records a turn count, once per response, which the conductor reads before each story and each re-loop. The printed evidence keeps the run judgeable mid-flight, but **passing the `/goal` condition is not completion**; the authoritative verdict is Stage 5. As the spine advances it overwrites a `run-status.json` heartbeat for pollers. See [`references/execute.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/execute.md).
|
|
82
82
|
|
|
83
83
|
### Stage 5: Gate
|
|
84
84
|
|
|
85
|
-
Decide whether a story (or, after the last story, the Epic) advances, by a deterministic artifact read. In production, the skill first backfills the evidence
|
|
85
|
+
Decide whether a story (or, after the last story, the Epic) advances, by a deterministic artifact read. In production, the skill first backfills the evidence: `bmad-testarch-automate` runs first and alone, a test it backfills is committed before anything else measures the story, and only then do `bmad-testarch-trace` (which writes the gate decision), `bmad-testarch-nfr` and, when the story lacks a current review, `bmad-testarch-test-review` run. Assessors that run or time anything measure a worktree of the commit under assessment, never the shared working tree. Then it runs `gate_eval.py`; a mid-loop re-gate may declare a delta profile (only the previously failed dimension re-runs in full) whose verdict is capped at reloop, so only the full instrument ever advances a story. The script reads TEA's `gate-decision.json` and returns a verdict the skill executes: `advance` (move to the next story), `defer` (append non-blocking items to the ledger and advance anyway), `reloop` (generalize each finding to its defect class against the Epic's class ledger, then run `bmad-correct-course` and re-run the story within the remaining budget), or `escalate` (stop). The invariant: **a P0/critical FAIL never defers**; it re-loops within budget or escalates. See the [gate model](./gate-model.md) and [`references/gate.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/gate.md).
|
|
86
86
|
|
|
87
87
|
This is how the verdict is read deterministically; the conductor never grades the work itself, it runs the script and routes on what comes back:
|
|
88
88
|
|
|
@@ -123,7 +123,7 @@ The run's `.decision-log.md`, held in the skill's run folder, is canonical memor
|
|
|
123
123
|
|
|
124
124
|
Finalize leaves two durable outputs beside the decision log, in the run folder. The **run report** (`run-report.md`) is the human takeaway. The **gate trail** (`gate-trail.md`, written by `gate_trail.py`) is the evidence trail: one section per story naming the checklist, trace report, gate decision, and baseline behind that story's verdict, so the gate can be audited without the transcript. Sources it cannot read render as `n/a` rather than failing the trail, but the trail refuses to render at all when no story is named, because an evidence trail that traces nothing is the exact failure it exists to prevent.
|
|
125
125
|
|
|
126
|
-
The third output lives elsewhere on purpose. The **deferred-work ledger** (at `deferred_work_path`, outside the run folder because it spans runs) holds one heading per Epic with a row per parked item: only non-gate-blocking work lands here (CONCERNS, non-critical findings, parked decisions); a P0/critical FAIL is never deferred. Finalize surfaces this run's Epic heading so nothing parked is invisible at handoff.
|
|
126
|
+
The third output lives elsewhere on purpose. The **deferred-work ledger** (at `deferred_work_path`, outside the run folder because it spans runs) holds one heading per Epic with a row per parked item: only non-gate-blocking work lands here (CONCERNS, non-critical findings, parked decisions, and the coverage gaps the gate's automate pass logged that are still open, at `med` severity whatever their priority); a P0/critical FAIL is never deferred. Finalize surfaces this run's Epic heading so nothing parked is invisible at handoff.
|
|
127
127
|
|
|
128
128
|
## Headless contract
|
|
129
129
|
|
package/docs/index.md
CHANGED
|
@@ -41,7 +41,7 @@ If the gate file is missing or unparseable, the contract counts it as a *failing
|
|
|
41
41
|
|
|
42
42
|
## What you get
|
|
43
43
|
|
|
44
|
-
Completion stops being a feeling in the transcript and becomes a fact on disk. Every green story lands as an implementation commit, plus its gate's
|
|
44
|
+
Completion stops being a feeling in the transcript and becomes a fact on disk. Every green story lands as an implementation commit, plus its gate's commits (a test backfill when the gate adds coverage, then the evidence), on an isolated epic branch: rollback you can actually trust, not a checkpoint that misses Bash changes. The run ends with a delivered, gate-passed epic, a run report, and a deferred-work ledger of anything safely parked for later.
|
|
45
45
|
|
|
46
46
|
## Read the rest
|
|
47
47
|
|
package/docs/operating-tips.md
CHANGED
|
@@ -42,13 +42,14 @@ Do not write a latch from the parent between drives. The old workaround, `latch
|
|
|
42
42
|
|
|
43
43
|
## Reading the driver's stop reasons
|
|
44
44
|
|
|
45
|
-
The driver names
|
|
45
|
+
The driver names fourteen stop reasons (`drive_epic.py`'s `STOP_*` constants). Three mean the invocation finished its work and exit 0: `all-done`, `limit-reached`, `dry-run`. Every other stop is a fail-closed halt and exits 1, so a wrapper can branch on the exit code before it parses anything.
|
|
46
46
|
|
|
47
|
-
These
|
|
47
|
+
These seven are the ones you will actually meet in a working week, and getting them confused wastes a spawn or, worse, propagates an ungated story. The rest name their own cause and need no table: `dry-run`, the pre-spawn refusals (`no-sprint-status`, `epic-not-found`, `sprint-status-elsewhere`, `stale-result`), a row carrying a status the driver does not recognize (`unknown-status`), and a drive that was killed (`signalled`).
|
|
48
48
|
|
|
49
49
|
| Stop reason | What happened | What to do |
|
|
50
50
|
|---|---|---|
|
|
51
51
|
| `all-done` | Every story of the Epic is `done`. | Nothing. The Epic is finished. |
|
|
52
|
+
| `evidence-owed` | Every story is `done`, but a commit hook rejected the last story's gate evidence commit, which is still staged (`.evidence-owed-<story>`). | Close its escalation with `/ucg-resolve` if it is still open, then resume the run once (`/ultracode-goal <epic> -H`) to make the commit. |
|
|
52
53
|
| `limit-reached` | Normal. `--limit` was reached. | Nothing. Drive again. |
|
|
53
54
|
| `blocked` | The story escalated, and a typed sidecar holds the pending decision. | Run `/ucg-resolve`, which reconstructs every pending decision from the sidecars and walks them. |
|
|
54
55
|
| `no-terminal` | The spawn exited without a readable result envelope. | **The work may be complete.** See below. |
|
package/docs/troubleshooting.md
CHANGED
|
@@ -52,7 +52,7 @@ The decision log carries the full blocker list with what each needs to clear. Re
|
|
|
52
52
|
|
|
53
53
|
**What happened.** `gate_eval.py` reads TEA's gate artifact from the trace output directory. `NOT_EVALUATED` means neither the slim `gate-decision.json` nor the fallback `e2e-trace-summary.json` was found there, or the run carried no gate fields. Almost always this is one of:
|
|
54
54
|
|
|
55
|
-
- **The TEA trace gate did not run.** In production, Stage 5 must backfill evidence first (`bmad-testarch-automate`
|
|
55
|
+
- **The TEA trace gate did not run.** In production, Stage 5 must backfill evidence first (`bmad-testarch-automate` first and alone, then the commit of any test it backfilled, then `bmad-testarch-trace` and `bmad-testarch-nfr`) before the gate; `bmad-testarch-trace` is what writes the gate decision. If it didn't run, there is nothing to read.
|
|
56
56
|
- **Wrong `trace_output_dir`.** The script reads the directory passed as `--trace-output` (resolved from `{workflow.trace_output_dir}`). If TEA wrote elsewhere, or the output dirs were never pre-created at preflight, the artifact is real but in a different place. Confirm `trace_output_dir` matches where TEA actually wrote.
|
|
57
57
|
|
|
58
58
|
Note this is fail-closed on purpose: a missing or unreadable gate artifact escalates rather than being assumed green. The slim file's *absence alone* is not the problem: the script falls back to the summary, and that fallback is explicitly not a failure. See the [gate model](./gate-model.md) for how the artifact resolves into a `gate_status` and the full verdict mapping.
|
|
@@ -11,7 +11,7 @@ Three intuitive shortcuts all push an unattended Epic toward false completion, a
|
|
|
11
11
|
|
|
12
12
|
**The evaluator only sees the transcript.** Claude Code's `/goal` mode drives a loop until a success condition is met, then asks an evaluator to confirm. But that evaluator reads the transcript; it cannot open a file on disk. It cannot read TEA's `gate-decision.json`. So if you let the `/goal` condition be the final word on "is this story done," you have asked the model to grade its own homework from its own notes. The model cannot be the judge of its own completion: the thing that decides "done" has to be something it cannot author.
|
|
13
13
|
|
|
14
|
-
**`/rewind` checkpoints miss Bash changes.** The obvious undo for a runaway agent is `/rewind`. But its checkpoints do not capture changes made through Bash, and an autonomous Epic run is mostly Bash: test commands, lint, build, and the git commits themselves. Rolling back to a checkpoint leaves the working tree's Bash-driven mutations in place. The real undo for this kind of run is git: an Epic branch off a protected branch, one implementation commit per green story plus its gate's evidence
|
|
14
|
+
**`/rewind` checkpoints miss Bash changes.** The obvious undo for a runaway agent is `/rewind`. But its checkpoints do not capture changes made through Bash, and an autonomous Epic run is mostly Bash: test commands, lint, build, and the git commits themselves. Rolling back to a checkpoint leaves the working tree's Bash-driven mutations in place. The real undo for this kind of run is git: an Epic branch off a protected branch, one implementation commit per green story plus its gate's commits (a test backfill when automate makes one, then the evidence). On a project that gitignores its BMAD output, that undo covers the code only: what the run wrote under the ignored tree stays, the story files, the run's decision log and its sprint-status edits among it. See the [gate model](./gate-model.md) and [architecture](./architecture.md) for how this is wired.
|
|
15
15
|
|
|
16
16
|
**Memory is context, not enforcement.** It is tempting to encode the run's invariants ("never commit on `main`", "never commit before tests pass") into Auto Memory or a CLAUDE.md rule and trust the model to honor them. But memory is context the model may or may not weigh; it does not *block* a `git commit`. An invariant that lives only in memory is a suggestion. An invariant that must hold has to live somewhere the model cannot talk its way past.
|
|
17
17
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://json.schemastore.org/package.json",
|
|
3
3
|
"name": "bmad-module-ultracode-goal",
|
|
4
|
-
"version": "3.
|
|
4
|
+
"version": "3.2.0",
|
|
5
5
|
"description": "BMAD module — Run a BMAD Epic autonomously to a machine-checked, TEA-gated Definition-of-Done.",
|
|
6
6
|
"keywords": [
|
|
7
7
|
"bmad",
|
|
@@ -234,6 +234,14 @@ The two dispositions are genuinely different things, not two names for one:
|
|
|
234
234
|
the turn-ceiling read could escalate it and a commit past the assessed one would make
|
|
235
235
|
the records stale (`{ucg-root}/references/execute.md`, the resume rule). The gate
|
|
236
236
|
deletes the marker once the re-gate's verdict is logged.
|
|
237
|
+
**Closing an `evidence-commit-rejected` escalation makes no commit.** Record the
|
|
238
|
+
operator's answer (the hook fixed or reconfigured, or the file it named changed by them),
|
|
239
|
+
then delete only the sidecar. Leave the staged evidence and
|
|
240
|
+
`{workflow.implementation_artifacts}/.evidence-owed-<story_id>` alone, even when the
|
|
241
|
+
answer is to commit as it stands: the resume makes that commit under the gate's hook rule
|
|
242
|
+
and removes the marker (`{ucg-root}/references/gate.md`, "Commit the gate's evidence
|
|
243
|
+
before the next story starts"), on the Epic's last story too, where every row already
|
|
244
|
+
reads `done` and the resume re-enters only for that commit before Finalize.
|
|
237
245
|
- **`defer`** — the decision is not made yet. Record the entry **without clearing
|
|
238
246
|
anything**. The artifact stays exactly where it is, the item stays pending, and the next
|
|
239
247
|
preflight still blocks on it.
|
|
@@ -262,7 +270,9 @@ may skip, because the two arrive from different places:
|
|
|
262
270
|
verdict is not advance; advanced stories are not re-run. Within that branch there is
|
|
263
271
|
no other re-entry point: it is not the first story of the Epic, and not the story the
|
|
264
272
|
answered decision happened to name, either of which would re-run stories that already
|
|
265
|
-
advanced, which is precisely what the shipped resume rule exists to prevent.
|
|
273
|
+
advanced, which is precisely what the shipped resume rule exists to prevent. When every
|
|
274
|
+
story advanced and a story's `.evidence-owed-<story_id>` is on disk, the resume drives no
|
|
275
|
+
story: it makes that story's owed evidence commit and goes to Finalize.
|
|
266
276
|
|
|
267
277
|
Either branch **re-asserts** — never rebuilds — the Epic branch, both hooks, the
|
|
268
278
|
allowlist, the `.mem-state.json` recall latch, and the in-flight story's baseline marker.
|
|
@@ -176,8 +176,9 @@ typed record as never written.
|
|
|
176
176
|
|
|
177
177
|
When `hunk` is on PATH, each story that recorded a baseline commit gains copy-paste
|
|
178
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
|
|
180
|
-
|
|
179
|
+
one line per commit in the story's range (its implementation commit, the gate's test
|
|
180
|
+
backfill commit when automate made one, and the gate's evidence commit) when the
|
|
181
|
+
repository is readable, else one line for the story's
|
|
181
182
|
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
|
|
182
183
|
unchanged.
|
|
183
184
|
|
|
@@ -36,7 +36,7 @@ Load config from `{project-root}/_bmad/config.yaml` and `config.user.yaml` (root
|
|
|
36
36
|
|
|
37
37
|
**Quick launch** (swap in your Epic id): `ultracode goal epic-7` — attended, production, sequential. `ultracode goal epic-7 --light --yes` — the expert one-liner: trace-only gate, no conversational stops. Add `-H` for headless, `--retro` for the close-out retrospective, `--max-stories 1` to take a single story this invocation.
|
|
38
38
|
|
|
39
|
-
**Resume.** The workspace is this skill's run folder holding `.decision-log.md`. If one exists for the Epic, surface it with its last session date and offer to resume: the log recovers full state regardless of compaction. Otherwise create it at intent and append a session heading. **Route resume by the last stage the log reached**: the run folder is created at intent (Stage 1), so a prior run that blocked *before* Execute also leaves one. If the log carries gate verdicts, re-enter Execute at the first story whose last verdict is not advance (advanced stories are not re-run), re-asserting (not rebuilding) the Epic branch, hooks, allowlist, and the `.mem-state.json` recall latch first (the latch by minting this invocation's own run id as Stage 1 does, never reusing one an earlier invocation logged, and re-running Stage 1's `mem_recall.py latch` step with it, which replaces a latch another run left; `references/execute.md` says why each, and why the latch especially). That re-entry stops short when the story still carries an open escalation: the re-assertion sweep's story route then reads `decision-pending`, and the resume drives nothing (attended, offer `/ucg-resolve`; headless, end `blocked` with a `reason` naming its `escalation-<story_id>.json`; `references/execute.md` says what counts as open). If instead it blocked at Stage 1 (epic unresolved) or Stage 2 (preflight RED: the case an operator fixes then re-invokes), re-run from that stage so the hard preflight gate is never skipped. A re-run from Stage 2 first runs Stage 1's Cross-Session Recall section with a fresh run id (the latch and, on a green latch, its one filter call, whose output Stage 2 reads), since the blocked run's preflight STOP removed its latch. In headless (`-H`) never offer: auto-resume a not-all-done Epic by this same stage routing (a previously-preflight-RED Epic re-runs the gate, it does not enter Execute), delete any existing `{workflow.implementation_artifacts}/run-result.json` as soon as that scalar resolves exactly as a fresh run does (`references/ingest-and-scope.md`), and log the resume as an assumption. **A resume routed into Execute does NOT re-run the Stage-2 formalize gate.** That verdict is Stage 2's and it covers the run's whole in-scope set by construction (`formalize_check.py` reads every not-`done` story of the Epic, or the operator-scoped subset its `--story` flags name, never only the stories one invocation drives), so on any Epic with undrafted or later stories it reads `remediable`/`blocked` on gaps belonging to rows this invocation is not driving. Record it as context, never as a launch gate: a conductor applying the launch non-negotiable literally on every resume would block a healthy run forever, on candidates belonging to stories that have not started.
|
|
39
|
+
**Resume.** The workspace is this skill's run folder holding `.decision-log.md`. If one exists for the Epic, surface it with its last session date and offer to resume: the log recovers full state regardless of compaction. Otherwise create it at intent and append a session heading. **Route resume by the last stage the log reached**: the run folder is created at intent (Stage 1), so a prior run that blocked *before* Execute also leaves one. If the log carries gate verdicts, re-enter Execute at the first story whose last verdict is not advance (advanced stories are not re-run), re-asserting (not rebuilding) the Epic branch, hooks, allowlist, and the `.mem-state.json` recall latch first (the latch by minting this invocation's own run id as Stage 1 does, never reusing one an earlier invocation logged, and re-running Stage 1's `mem_recall.py latch` step with it, which replaces a latch another run left; `references/execute.md` says why each, and why the latch especially). That re-entry stops short when the story still carries an open escalation: the re-assertion sweep's story route then reads `decision-pending`, and the resume drives nothing (attended, offer `/ucg-resolve`; headless, end `blocked` with a `reason` naming its `escalation-<story_id>.json`; `references/execute.md` says what counts as open). If instead it blocked at Stage 1 (epic unresolved) or Stage 2 (preflight RED: the case an operator fixes then re-invokes), re-run from that stage so the hard preflight gate is never skipped. A re-run from Stage 2 first runs Stage 1's Cross-Session Recall section with a fresh run id (the latch and, on a green latch, its one filter call, whose output Stage 2 reads), since the blocked run's preflight STOP removed its latch. In headless (`-H`) never offer: auto-resume a not-all-done Epic by this same stage routing (a previously-preflight-RED Epic re-runs the gate, it does not enter Execute), delete any existing `{workflow.implementation_artifacts}/run-result.json` as soon as that scalar resolves exactly as a fresh run does (`references/ingest-and-scope.md`), and log the resume as an assumption. An Epic whose stories all read `done` while a story's `.evidence-owed-<story_id>` is on disk (its evidence commit, escalated as `evidence-commit-rejected`, is still owed, whether or not `/ucg-resolve` has closed that escalation) counts as not-all-done here and in Stage 1's already-done short-circuit: its resume re-enters Execute only for that commit, then goes to Finalize (`references/execute.md`'s resume rule). **A resume routed into Execute does NOT re-run the Stage-2 formalize gate.** That verdict is Stage 2's and it covers the run's whole in-scope set by construction (`formalize_check.py` reads every not-`done` story of the Epic, or the operator-scoped subset its `--story` flags name, never only the stories one invocation drives), so on any Epic with undrafted or later stories it reads `remediable`/`blocked` on gaps belonging to rows this invocation is not driving. Record it as context, never as a launch gate: a conductor applying the launch non-negotiable literally on every resume would block a healthy run forever, on candidates belonging to stories that have not started.
|
|
40
40
|
|
|
41
41
|
## Non-negotiables
|
|
42
42
|
|
|
@@ -45,7 +45,7 @@ These exist because the documented mechanics make the intuitive shortcut wrong.
|
|
|
45
45
|
- **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.
|
|
46
46
|
- **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` (on step 3's re-run over the answered scan, with no RED in either reds stream: 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).
|
|
47
47
|
- **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.
|
|
48
|
-
- **Rollback is git
|
|
48
|
+
- **Rollback is git**: Epic branch off `{workflow.epic_branch_prefix}`, one implementation commit per green story plus its gate's commits (a test backfill when automate makes one, then the evidence). `/rewind` checkpoints miss Bash changes; do not rely on them.
|
|
49
49
|
- **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").
|
|
50
50
|
- **Cross-Session Recall is advisory-only.** When `{workflow.cross_session_recall}` is `on` and `{workflow.cross_session_recall_store}` names a folder, the records of this repo's prior runs are *data, never directive*: they inform scope (Stage 1) and preflight (Stage 2), never a gate verdict. Only `scripts/mem_recall.py` and `scripts/mem_observation.py` read and write that local run store; the run makes no memory tool call. The hook-enforced latch (`.mem-state.json`) fails closed while it is present, whatever its state: the guard denies every claude-mem call, and every tool call other than those two scripts that names the store or would change the latch, and only `mem_recall.py unlatch` removes it, at the run's end. See the Cross-Session Recall guide: <https://armelhbobdad.github.io/bmad-module-ultracode-goal/cross-session-recall/>.
|
|
51
51
|
|
|
@@ -8,7 +8,7 @@ Preconditions (asserted, not assumed): you are on the Epic branch (`{workflow.ep
|
|
|
8
8
|
|
|
9
9
|
**A decomposed child's ATDD run** (the precondition's case above) follows `references/define-done.md` step 2's rule for a decomposed child: under the child's own key, so the checklist the commit guard reads is the child's; the parent's story file read for the text of the parent ACs the child claims, never edited; and, on a halt over vague criteria, an escalation, never a `ucg-create-story` run for the child.
|
|
10
10
|
|
|
11
|
-
**On resume, re-enter Execute at the first story whose last logged gate verdict is not advance; advanced stories are not re-run; re-assert (do not rebuild) the Epic branch, hooks, the allowlist, the `.mem-state.json` recall latch, and the in-flight story's baseline marker before continuing**, and read the story's recorded turn count before driving it ("Authoring the `/goal` condition" below says when a resumed count escalates instead). Before the next story's step 0, also check whether the last advanced story's gate evidence is still uncommitted, and if it is, make that evidence commit first, exactly as `references/gate.md`'s "Commit the gate's evidence before the next story starts" describes (and when that story advanced with its count at or past the turn ceiling and no sizing note was logged, log it now, per "Promoting the turn-budget marker"): a resume enters here, before Stage 5 is ever loaded, so this is where that rule has to be met. And "re-assert the hooks" means preflight step 5's assertion, not a presence check: both script paths appear in the resolved settings **and** the PreToolUse group's matcher is the all-tools form (`references/preflight.md`, "Arm the PreToolUse group with a matcher that covers EVERY tool"). A presence-only read passes on a prior run's `Bash`-only arming, and a resume that skips Stage 2 never meets the bullet where that requirement lives, so this is the one place it binds a resumed run, and without it the Cross-Session Recall invariant enforces nothing outside Bash for the whole session while every log line says the hooks are armed. The latch is *re-written* by re-running Stage 1's latch step (`references/ingest-and-scope.md`, its `mem_recall.py latch` command) with this invocation's own run id, minted first by Stage 1's convention and logged. A resume never reuses an id an earlier invocation logged: the run's record file is named after it and never rewritten, so a reused id turns this run's Finalize write into `skipped-existing` and loses its record. It is re-written because every terminal removes it with `mem_recall.py unlatch` (Stage 6 at every close-out), and the PreToolUse hook reads an absent latch as "no run active" and stops gating recall entirely. A latch already on disk whose `run_id` is not this run's is **another run's (or a spawning wrapper's) artifact, never evidence**: re-latch from this run's own measurement, which replaces it, and never inherit its `store_ok` colour, because an inherited green latch certifies a store this run never checked. Never delete that latch to make room for this run's: the guard refuses it while a latch is present, and the latch command is what replaces it. The baseline marker is the opposite of the latch, split by which case the resume is, and the test is simply whether `.baseline-<story_id>` exists. **Mid-story (it exists):** *re-read* and never regenerate: the story may already carry commits, and a rebuilt baseline silently re-anchors its evidence range to a mid-story HEAD. **Story boundary (it does not exist**, the NORMAL case under `--max-stories N`, where every invocation after the first resumes at a fresh story): there is nothing to re-read; write it fresh at `HEAD` exactly as step 0 does for a first-run story, because the PreToolUse marker-freshness gate fail-closes without it.
|
|
11
|
+
**On resume, re-enter Execute at the first story whose last logged gate verdict is not advance; advanced stories are not re-run; re-assert (do not rebuild) the Epic branch, hooks, the allowlist, the `.mem-state.json` recall latch, and the in-flight story's baseline marker before continuing**, and read the story's recorded turn count before driving it ("Authoring the `/goal` condition" below says when a resumed count escalates instead). Before the next story's step 0, also check whether the last advanced story's gate evidence is still uncommitted, and if it is, make that evidence commit first, exactly as `references/gate.md`'s "Commit the gate's evidence before the next story starts" describes (and when that story advanced with its count at or past the turn ceiling and no sizing note was logged, log it now, per "Promoting the turn-budget marker"): a resume enters here, before Stage 5 is ever loaded, so this is where that rule has to be met. That story carries an `evidence-commit-rejected` escalation when a repo commit hook rejected that commit in a way the gate may not answer, so run the `--assert-armed` call below with `--story` naming that story first: while its `escalation` reads `open`, make no commit and take the `decision-pending` route below for that story, and once `/ucg-resolve` has closed it (its sidecar is gone, and `.evidence-owed-<story_id>` is still on disk), make the commit and remove that marker. Check every `.evidence-owed-<story_id>` of this Epic's stories this way, not only the last advanced story's: a marker whose evidence was committed some other way is removed as `references/gate.md` says, with no commit. When that story is the Epic's last, so every story reads `done`, no story is left to drive: after the commit go to Stage 6 (`references/finalize.md`) with the Epic-level verdict the log holds, and run neither a story nor the Epic-level gate again. Stage 1 resolved no in-scope story for that resume, so Finalize passes that story as its one `--story` to `scripts/gate_trail.py`, whose range then ends at the commit this resume made, and the run report names the route as the owed evidence commit made and the Epic complete. And "re-assert the hooks" means preflight step 5's assertion, not a presence check: both script paths appear in the resolved settings **and** the PreToolUse group's matcher is the all-tools form (`references/preflight.md`, "Arm the PreToolUse group with a matcher that covers EVERY tool"). A presence-only read passes on a prior run's `Bash`-only arming, and a resume that skips Stage 2 never meets the bullet where that requirement lives, so this is the one place it binds a resumed run, and without it the Cross-Session Recall invariant enforces nothing outside Bash for the whole session while every log line says the hooks are armed. The latch is *re-written* by re-running Stage 1's latch step (`references/ingest-and-scope.md`, its `mem_recall.py latch` command) with this invocation's own run id, minted first by Stage 1's convention and logged. A resume never reuses an id an earlier invocation logged: the run's record file is named after it and never rewritten, so a reused id turns this run's Finalize write into `skipped-existing` and loses its record. It is re-written because every terminal removes it with `mem_recall.py unlatch` (Stage 6 at every close-out), and the PreToolUse hook reads an absent latch as "no run active" and stops gating recall entirely. A latch already on disk whose `run_id` is not this run's is **another run's (or a spawning wrapper's) artifact, never evidence**: re-latch from this run's own measurement, which replaces it, and never inherit its `store_ok` colour, because an inherited green latch certifies a store this run never checked. Never delete that latch to make room for this run's: the guard refuses it while a latch is present, and the latch command is what replaces it. The baseline marker is the opposite of the latch, split by which case the resume is, and the test is simply whether `.baseline-<story_id>` exists. **Mid-story (it exists):** *re-read* and never regenerate: the story may already carry commits, and a rebuilt baseline silently re-anchors its evidence range to a mid-story HEAD. **Story boundary (it does not exist**, the NORMAL case under `--max-stories N`, where every invocation after the first resumes at a fresh story): there is nothing to re-read; write it fresh at `HEAD` exactly as step 0 does for a first-run story, because the PreToolUse marker-freshness gate fail-closes without it.
|
|
12
12
|
|
|
13
13
|
**The cursor passes over a decomposed parent.** A story whose row is `done` and whose split is recorded (its split record (`.split-<key>.json` beside `sprint-status.yaml`) names it, a child row cites the parent ACs it claims, or `.decision-log.md` names it and the ACs each child claims) never gets a gate verdict of its own: its children carry its contract, and on its split record the Epic-level roll-up reads their gates in its place (`references/gate.md`). So it is never "a story whose last logged gate verdict is not advance" in the sense above: pass over it and re-enter at the next story, and never drive it. This is the shape a sizing decomposition leaves (below): the invocation that split the row ends without a verdict, the next one re-enters at the first child, since the child rows sit above the parent's, and once every child has advanced the cursor reaches the parent's row and passes over it. A `done` row with no recorded split is not passed over on this rule; Stage 1 rule 3's `skipped-already-done` log is what keeps a fresh run from re-driving one.
|
|
14
14
|
|
|
@@ -22,6 +22,12 @@ Preconditions (asserted, not assumed): you are on the Epic branch (`{workflow.ep
|
|
|
22
22
|
|
|
23
23
|
**A fourth case: a closed `operator-evidence-owed` story owes a re-gate, not a re-drive.** Its FAIL gate left `trace-<story_id>.md` and `gate-decision-<story_id>.json` on disk, so the third case never fires for it. When `/ucg-resolve` closes that escalation, it deletes the sidecar, resets the story's turn counter (waiting for operator evidence is not the story's work) and writes `{workflow.implementation_artifacts}/.regate-<story_id>`, holding `sha=` the assessed commit and `decision=` the closed id. The `story` block reports that marker as `regate`: `null` when there is none, otherwise its `state`. While it reads `fresh` (its `sha=` resolves to `HEAD`) and the baseline marker exists, the route is `gate-owed`: enter exactly as the third case does, re-setting the pointer, skipping step 0's turn-ceiling read and steps 1 through 4, re-measuring `HEAD` at step 5, then re-gating it in Stage 5, whose trace counts the operator's records. Commit nothing before that gate while step 5's re-measure is green, since a commit past the assessed commit makes the records stale. On a red, take step 5's red route (remediate, write a fresh `.tests-ran-<story_id>` marker, re-commit): that commit moves `HEAD` past the assessed commit, so the records no longer count and the `.regate-<story_id>` marker is stale, and the re-gate at the new `HEAD` escalates `operator-evidence-owed` again at the new commit. A `stale` marker (one naming another commit, or no commit id) routes as if it were absent, normally `mid-story`: a later commit already made the records stale. On either route the gate deletes the marker once this story's verdict is logged (`references/gate.md`, "A logged verdict settles an owed re-gate").
|
|
24
24
|
|
|
25
|
+
**A fifth case: a gate stopped between automate and trace.** `preflight_check.py` reads no log, so its `story` block cannot see this case and reads such a story as `gate-owed` or `mid-story`; take this case instead of either, but never instead of `decision-pending`. It takes three forms, each read from the story's `.decision-log.md`:
|
|
26
|
+
|
|
27
|
+
- **A backfill with no verdict after it.** `references/gate.md`'s "When automate backfills" logs `gate-backfill-base:` once automate has finished with a backfill, and `gate-backfill:` once that backfill is committed. When the log holds either line with no verdict logged after it (when it holds both, the later one decides), the story owes the rest of that gate cycle: not a re-drive, and not a second automate pass. Re-set the `.current-story` pointer (the pointer half of step 0 only), skip step 0's turn-ceiling read and steps 1 through 5, and enter Stage 5 at gate.md's "A resume after a backfill does not run automate again", which says at which `HEAD` the case holds and sends a story at any other `HEAD` back to the route the script reports.
|
|
28
|
+
- **A re-loop that ended its cycle before trace.** gate.md's "A red backfill sweep ends the cycle at a re-loop" logs a `reloop` verdict whose JSON holds no `gate_status`, since no trace ran, beside an `assessed-commit:` line. When that is the story's last logged verdict and `HEAD` is still the commit its `assessed-commit:` line names, the re-loop has committed nothing yet, and the story owes that re-loop, not a gate: re-set the `.current-story` pointer (the pointer half of step 0 only), then resume gate.md's `reloop` route where the log stopped, its turn-ceiling check included (the generalize step when this re-loop's `class:` lines are not logged yet, then `bmad-correct-course`, then the story's re-run through the story loop below).
|
|
29
|
+
- **An automate pass with no verdict after it.** gate.md's "A summary already at that name is this cycle's own" logs `gate-automate: <sha>` right before it delegates automate, naming the commit automate measures. When the log holds a `gate-automate:` line with no verdict and no `gate-backfill-base:` or `gate-backfill:` line logged after it (a backfill line after it means the first form applies instead), and that line names the commit `git rev-parse HEAD` prints, the session ended while automate ran, or after it finished but before anything was committed, and the story owes the rest of that gate cycle, not a re-drive. Re-set the `.current-story` pointer (the pointer half of step 0 only), skip step 0's turn-ceiling read and steps 1 through 5, and enter Stage 5 at gate.md's "Backfill the gate evidence", whose paragraph "A summary already at that name is this cycle's own", read before automate is delegated, reuses the pass's summary when it is complete and runs automate again only when the summary is unfinished or absent. When that line names any other commit, the story is not in this form: take the route the script reports.
|
|
30
|
+
|
|
25
31
|
## Default — Sequential `/goal` spine
|
|
26
32
|
|
|
27
33
|
### Sizing: a story too large to drive
|
|
@@ -80,7 +86,7 @@ For each in-scope story, in sprint order, run this loop (leave out a decomposed
|
|
|
80
86
|
**A repo with commit hooks carries gates this sweep structurally cannot see.** `lefthook` / `husky` / `.git/hooks/pre-commit` jobs — typos, formatters, staged-file linters, clippy — run against the staged index and are reachable from no script you can invoke here. So the step-4 commit attempt is itself part of verification rather than the end of it: a rejection there is expected traffic, not a failure of this sweep. What that rejection does to the tests-ran marker is step 4's problem, and it is not the obvious answer.
|
|
81
87
|
|
|
82
88
|
3. **Production profile only:** `bmad-testarch-test-review`, then `bmad-code-review`. A `CONCERNS`-grade or non-critical finding appends to `{workflow.deferred_work_path}` and the story proceeds. A **P0 / critical FAIL never defers** — re-loop within the turn budget or escalate.
|
|
83
|
-
4. **Commit at green** (one implementation commit per green story; the gate's evidence commit follows inside the same story boundary, per `references/gate.md`'s advance route). The PreToolUse hook blocks a commit on a protected branch, blocks a commit when no "tests-ran" marker exists for the current story, and (its marker-freshness clause) blocks a commit when that marker's `baseline=` line does not match the story's recorded baseline, so step 0 must have set the current story and step 2 must have actually run and written `{workflow.implementation_artifacts}/.tests-ran-<story_id>`, in the format step 2 pins, **in a prior, SEPARATE command**. The guard pre-evaluates the command *string* before it runs, so a marker written by a `printf`/`echo` in the SAME compound command as the commit (e.g. `printf … > .tests-ran-<id> && git commit …`) does not yet exist at hook-eval time and the commit is denied. Write the marker, then commit: two distinct tool calls. **A commit can also be rejected by something that is NOT the guard, and the marker rule inverts there.** A repo-side `pre-commit` hook (lefthook, husky, a plain `.git/hooks/pre-commit`) running clippy, rustfmt, typos or a staged-file linter rejects the commit without moving anything: HEAD is where it was, so the tests-ran marker's `baseline=` line still matches character for character and the guard will wave the retry straight through, carrying evidence collected *before* the fix. The freshness clause keys on the BASELINE, not on the code state, so it cannot see this case by construction. Treat a hook rejection exactly as step 5 treats a post-commit red: remediate, re-run the story's tests/lint/build to green, write a **fresh** `.tests-ran-<story_id>` (same `baseline=` line, still copied and never re-derived; `scope=`/`packages=` re-stated for what the re-run actually was), and only then retry the commit. **Append `.decision-log.md` with Write/Edit, never a Bash heredoc.** Stages 4 and 6 require a log of what happened during the run, and what happened *is* commit behaviour, so the log quotes the verbs. The guard evaluates Bash command strings, and a heredoc carrying that prose is a Bash command string: a line leading with the verb is a verb-leading segment, and backticked identifiers or an apostrophe send the whole segment down the fail-closed matches-anywhere path. Its git gates read **Bash command strings alone**, so writing the log with the file tools removes the collision instead of phrasing around it, and keeps Bash for commands you actually mean to run. Said that way rather than "the guard never sees Write/Edit", because preflight arms the hook for EVERY tool: the hook IS invoked for a `Write`, and it does decide on file tools, but only through its Cross-Session Recall rules, which deny a file-tool call that names the recall store or would change the run latch (`references/preflight.md`). A decision-log append is neither, so the conclusion is unchanged, but a reader who believes the guard cannot see a `Write` and then meets the all-tools matcher will try to resolve the contradiction by narrowing the matcher back, and that leaves the recall rules enforcing nothing. **Once the log is too large to Read affordably, do not Read it.** It grows monotonically, one session's prose per invocation, and both file tools refuse a file that has not been Read in this session, so on a long-running Epic (288 KB by its eleventh invocation) the two sanctioned paths are both closed at once. Compose this session's entry with Write into a NEW sibling file in the run folder, `{workflow.implementation_artifacts}/dlog-slice-<story_id>-<n>.md`, where `<n>` increments per append: the name has to be unique per append, not per story, or a story's SECOND entry finds the slice already on disk and walks straight back into the Read it was escaping; then append it in one Bash call, `cat <slice> >> .decision-log.md`. That command's leading token is `cat`, it carries no backtick, no `$(`, and no verb-leading segment, so the guard makes no decision on it and the prose never enters a Bash command string at all. Keep the slice beside the log rather than deleting it: it is the only per-session copy if the append is ever interrupted. **Stage only the current story's paths.** In production, Stage 3 generated *every* in-scope story's red-phase tests up front, so a sibling story's still-skipped tests can co-reside in the same shared dirs as this story's (one `test/` package may hold two stories' acceptance specs before either commits). A blanket `git add -A` here sweeps those uncommitted sibling tests into this story's commit and pollutes the per-story boundary: stage this story's source + test paths explicitly (`git add <this story's paths>`) instead. The allowlist ships plain `git add` (a prefix covering both `-A` and a scoped `git add <paths>`) so the targeted add needs no extra approval. **Staging is itself a prior, SEPARATE tool call**: `git add <this story's paths>` as one call, then `git commit` as a second: the same two-distinct-tool-calls rule the marker follows, and for the same reason. The guard also denies a commit whose staged index is empty, and a chained `git add … && git commit` has staged nothing at the moment it pre-evaluates that command string, so the chained form is denied even though the add would have worked. `git commit -a` and commit-time pathspecs (`git commit <paths>`) are unsupported inside the story loop for exactly that reason. (Under `--light` no ATDD tests are generated, so the collision cannot arise.) **Once the commit lands, record the story's END sha.** Write `{workflow.implementation_artifacts}/.commit-<story_id>` with the output of `git rev-parse HEAD`, in exactly the format step 0 pins for the baseline: one newline-terminated line carrying the full 40-hex SHA. Unlike the baseline, **this marker is refreshed, not preserved**: step 5 rewrites it after any remediation re-commit or amend, and the gate's advance route rewrites it after its evidence commit, so it always names the story's last commit rather than its first. It exists to close the story's commit range explicitly: without it the evidence trail has to *infer* a range end from the NEXT story's baseline marker, and a later story anchored at this story's own SHA collapses that range to `X..X`, so a story that did commit renders as having committed nothing.
|
|
89
|
+
4. **Commit at green** (one implementation commit per green story; the gate's evidence commit follows inside the same story boundary, per `references/gate.md`'s advance route, and when the gate's `bmad-testarch-automate` backfills a test, a commit of that backfill comes before it, per gate.md's "When automate backfills"). The PreToolUse hook blocks a commit on a protected branch, blocks a commit when no "tests-ran" marker exists for the current story, and (its marker-freshness clause) blocks a commit when that marker's `baseline=` line does not match the story's recorded baseline, so step 0 must have set the current story and step 2 must have actually run and written `{workflow.implementation_artifacts}/.tests-ran-<story_id>`, in the format step 2 pins, **in a prior, SEPARATE command**. The guard pre-evaluates the command *string* before it runs, so a marker written by a `printf`/`echo` in the SAME compound command as the commit (e.g. `printf … > .tests-ran-<id> && git commit …`) does not yet exist at hook-eval time and the commit is denied. Write the marker, then commit: two distinct tool calls. **A commit can also be rejected by something that is NOT the guard, and the marker rule inverts there.** A repo-side `pre-commit` hook (lefthook, husky, a plain `.git/hooks/pre-commit`) running clippy, rustfmt, typos or a staged-file linter rejects the commit without moving anything: HEAD is where it was, so the tests-ran marker's `baseline=` line still matches character for character and the guard will wave the retry straight through, carrying evidence collected *before* the fix. The freshness clause keys on the BASELINE, not on the code state, so it cannot see this case by construction. Treat a hook rejection exactly as step 5 treats a post-commit red: remediate, re-run the story's tests/lint/build to green, write a **fresh** `.tests-ran-<story_id>` (same `baseline=` line, still copied and never re-derived; `scope=`/`packages=` re-stated for what the re-run actually was), and only then retry the commit. This rule binds the story's own commits: this step's, and any re-commit or amend step 5 makes. The gate's two commits keep their own rules in `references/gate.md`: "When automate backfills" reads a hook rejection of its commit of a test `bmad-testarch-automate` backfilled as its backfill sweep's red, which it fixes only in the backfilled test files and otherwise ends the cycle at a re-loop, and the advance route says how to answer a hook rejection of its evidence commit. **Append `.decision-log.md` with Write/Edit, never a Bash heredoc.** Stages 4 and 6 require a log of what happened during the run, and what happened *is* commit behaviour, so the log quotes the verbs. The guard evaluates Bash command strings, and a heredoc carrying that prose is a Bash command string: a line leading with the verb is a verb-leading segment, and backticked identifiers or an apostrophe send the whole segment down the fail-closed matches-anywhere path. Its git gates read **Bash command strings alone**, so writing the log with the file tools removes the collision instead of phrasing around it, and keeps Bash for commands you actually mean to run. Said that way rather than "the guard never sees Write/Edit", because preflight arms the hook for EVERY tool: the hook IS invoked for a `Write`, and it does decide on file tools, but only through its Cross-Session Recall rules, which deny a file-tool call that names the recall store or would change the run latch (`references/preflight.md`). A decision-log append is neither, so the conclusion is unchanged, but a reader who believes the guard cannot see a `Write` and then meets the all-tools matcher will try to resolve the contradiction by narrowing the matcher back, and that leaves the recall rules enforcing nothing. **Once the log is too large to Read affordably, do not Read it.** It grows monotonically, one session's prose per invocation, and both file tools refuse a file that has not been Read in this session, so on a long-running Epic (288 KB by its eleventh invocation) the two sanctioned paths are both closed at once. Compose this session's entry with Write into a NEW sibling file in the run folder, `{workflow.implementation_artifacts}/dlog-slice-<story_id>-<n>.md`, where `<n>` increments per append: the name has to be unique per append, not per story, or a story's SECOND entry finds the slice already on disk and walks straight back into the Read it was escaping; then append it in one Bash call, `cat <slice> >> .decision-log.md`. That command's leading token is `cat`, it carries no backtick, no `$(`, and no verb-leading segment, so the guard makes no decision on it and the prose never enters a Bash command string at all. Keep the slice beside the log rather than deleting it: it is the only per-session copy if the append is ever interrupted. **Stage only the current story's paths.** In production, Stage 3 generated *every* in-scope story's red-phase tests up front, so a sibling story's still-skipped tests can co-reside in the same shared dirs as this story's (one `test/` package may hold two stories' acceptance specs before either commits). A blanket `git add -A` here sweeps those uncommitted sibling tests into this story's commit and pollutes the per-story boundary: stage this story's source + test paths explicitly (`git add <this story's paths>`) instead. The allowlist ships plain `git add` (a prefix covering both `-A` and a scoped `git add <paths>`) so the targeted add needs no extra approval. **Staging is itself a prior, SEPARATE tool call**: `git add <this story's paths>` as one call, then `git commit` as a second: the same two-distinct-tool-calls rule the marker follows, and for the same reason. The guard also denies a commit whose staged index is empty, and a chained `git add … && git commit` has staged nothing at the moment it pre-evaluates that command string, so the chained form is denied even though the add would have worked. `git commit -a` and commit-time pathspecs (`git commit <paths>`) are unsupported inside the story loop for exactly that reason. (Under `--light` no ATDD tests are generated, so the collision cannot arise.) **Once the commit lands, record the story's END sha.** Write `{workflow.implementation_artifacts}/.commit-<story_id>` with the output of `git rev-parse HEAD`, in exactly the format step 0 pins for the baseline: one newline-terminated line carrying the full 40-hex SHA. Unlike the baseline, **this marker is refreshed, not preserved**: step 5 rewrites it after any remediation re-commit or amend, the gate rewrites it after the commit of a test `bmad-testarch-automate` backfilled (gate.md's "When automate backfills"), and the gate's advance route rewrites it after its evidence commit, so it always names the story's last commit rather than its first. It exists to close the story's commit range explicitly: without it the evidence trail has to *infer* a range end from the NEXT story's baseline marker, and a later story anchored at this story's own SHA collapses that range to `X..X`, so a story that did commit renders as having committed nothing.
|
|
84
90
|
|
|
85
91
|
**Check the record's claims before the commit.** Gate reviews keep finding one shape of defect in the record: a commit message, a code comment or a story sentence that asserts a property the code does not hold, written by the author who just built it. A catch after the commit costs a re-loop, so check between the staging call and the commit call. Write the commit message with Write to `{workflow.implementation_artifacts}/.scratch-<story_id>/message.txt`, and the story-record notes this cycle added (completion notes, a re-loop's notes, File List entries; for a decomposed child, which has no record, the File List and completion notes from `ucg-dev-story`'s step 10 summary; an empty file when the cycle added none) to `record-notes.md` beside it, Reading either first if an earlier session left it, then run:
|
|
86
92
|
|
|
@@ -124,7 +130,7 @@ Emit **`blocked`**, and carry the distinction in the typed escalation sidecar ra
|
|
|
124
130
|
**The conductor cannot start `/goal` itself.** It is a built-in slash command with no tool surface, so in an attended session, a `-H` session or a `drive_epic.py` spawn alike, a `/goal` is active only when the operator started one (typing `/goal <condition>`, or launching `claude -p "/goal …"`). Write the condition below either way, and record it in `.decision-log.md` at step 0 as the story's contract. When an operator did start a `/goal`, at launch or mid-session, that loop runs on the operator's own condition, not this one, and a turn clause in it bounds the session rather than the story. Keep it **under 4000 characters**, encoding the per-story Definition-of-Done as the success criterion with an explicit escape clause. The condition must:
|
|
125
131
|
|
|
126
132
|
- State the DoD in checkable terms: ATDD acceptance tests for the story un-skipped and **passing** (production) — or, under `--light`, the story's acceptance criteria demonstrably satisfied — plus lint clean, build green, and (production) test-review + code-review passed — mirroring the printed evidence so the transcript-only evaluator can corroborate it.
|
|
127
|
-
- Include the literal escape: **"…or stop after {workflow.max_turns_per_story} turns."** It belongs in the story's written contract, but it bounds nothing on its own, since no `/goal` runs on this condition. The only turn count every session keeps is the one the `budget_stop.py` Stop hook records in `{workflow.implementation_artifacts}/.budget-<story_id>.json` (`run-status.json` copies it into `budget_used.turns`, and when the two disagree the hook file wins). It advances once per Stop, that is once per response the session ends, so it cannot see re-loops spent inside a single response. It counts responses, not work: a response that only acknowledges a background task's notification counts the same as one that edits code, so a story's waits spend its ceiling too ("Waiting spends turns" in the story loop above says how to keep that small). Read it, never a count of your own, at two points. **Before a story's step 0** on the `story-boundary` and `mid-story` resume routes: a resume can inherit a counter already at or over `{workflow.max_turns_per_story}`, and then you escalate instead of driving that story (write `escalation-<story_id>.json` with `kind` `budget-overrun`, the kind `/ucg-resolve` resets the counter for, and end the invocation `blocked`, as `references/gate.md`'s `escalate` does). A `gate-owed` story is exempt and goes straight to step 5 and the gate, because its work is already committed. **Before each re-loop**, where `references/gate.md` turns a re-loop that would exceed the ceiling into `escalate` (a cap-only re-gate, which re-measures without re-driving, excepted). The hook itself only records and warns (a Stop hook **cannot force `/goal` to halt mid-condition**, and it never blocks), and the marker it writes on an overrun becomes an escalation only as described below: a story that then advances at its gate gets a sizing note instead. In a single attended or `-H` session with no operator `/goal`, nothing bounds re-loops spent inside one response; for `drive_epic.py` spawns, the `--session-timeout` wall clock is the backstop that holds whatever the count says (unless it is set to `0`). State the clause anyway.
|
|
133
|
+
- Include the literal escape: **"…or stop after {workflow.max_turns_per_story} turns."** It belongs in the story's written contract, but it bounds nothing on its own, since no `/goal` runs on this condition. The only turn count every session keeps is the one the `budget_stop.py` Stop hook records in `{workflow.implementation_artifacts}/.budget-<story_id>.json` (`run-status.json` copies it into `budget_used.turns`, and when the two disagree the hook file wins). It advances once per Stop, that is once per response the session ends, so it cannot see re-loops spent inside a single response. It counts responses, not work: a response that only acknowledges a background task's notification counts the same as one that edits code, so a story's waits spend its ceiling too ("Waiting spends turns" in the story loop above says how to keep that small). Read it, never a count of your own, at two points. **Before a story's step 0** on the `story-boundary` and `mid-story` resume routes: a resume can inherit a counter already at or over `{workflow.max_turns_per_story}`, and then you escalate instead of driving that story (write `escalation-<story_id>.json` with `kind` `budget-overrun`, the kind `/ucg-resolve` resets the counter for, and end the invocation `blocked`, as `references/gate.md`'s `escalate` does). A `gate-owed` story is exempt and goes straight to step 5 and the gate, because its work is already committed, and so is a story the fifth resume case's first or third form (a backfill, or an automate pass, with no verdict after it) sends into Stage 5, whatever route the script reports for it, because its gate cycle is already under way. The fifth case's second form reads the count at its re-loop's turn-ceiling check instead. **Before each re-loop**, where `references/gate.md` turns a re-loop that would exceed the ceiling into `escalate` (a cap-only re-gate, which re-measures without re-driving, excepted). The hook itself only records and warns (a Stop hook **cannot force `/goal` to halt mid-condition**, and it never blocks), and the marker it writes on an overrun becomes an escalation only as described below: a story that then advances at its gate gets a sizing note instead. In a single attended or `-H` session with no operator `/goal`, nothing bounds re-loops spent inside one response; for `drive_epic.py` spawns, the `--session-timeout` wall clock is the backstop that holds whatever the count says (unless it is set to `0`). State the clause anyway.
|
|
128
134
|
- Make explicit that **passing the condition is not completion** — the authoritative verdict is Stage 5's `gate_eval.py`. The `/goal` condition gets a story to a *plausibly* done, evidence-printed state; the gate decides.
|
|
129
135
|
|
|
130
136
|
Keep it under the character limit by referencing the story's `atdd-checklist` (or, under `--light`, its acceptance criteria) and printed test output rather than restating ACs verbatim.
|
|
@@ -148,7 +154,7 @@ It is a single JSON object, exactly these four string fields and no fifth:
|
|
|
148
154
|
|
|
149
155
|
One object, never an array: the file is already named per story, so a list would only re-encode the story id inside a file that carries it in its name.
|
|
150
156
|
|
|
151
|
-
`kind` is **open vocabulary**. A reader renders whatever string it finds and never validates it against a fixed list, in particular never against the red-kind vocabulary the semantic scan returns in `references/preflight.md`, which classifies *planning-artifact* reds and has no term for anything that happens at run time. `budget-overrun` is a live `kind` and sits deliberately outside that vocabulary; a reader that validated against it would silently drop the most common escalation there is. `operator-evidence-owed` is a live `kind` too: the story is delivered and gated except evidence only a person can record (`references/gate.md`).
|
|
157
|
+
`kind` is **open vocabulary**. A reader renders whatever string it finds and never validates it against a fixed list, in particular never against the red-kind vocabulary the semantic scan returns in `references/preflight.md`, which classifies *planning-artifact* reds and has no term for anything that happens at run time. `budget-overrun` is a live `kind` and sits deliberately outside that vocabulary; a reader that validated against it would silently drop the most common escalation there is. `operator-evidence-owed` is a live `kind` too: the story is delivered and gated except evidence only a person can record (`references/gate.md`). So is `evidence-commit-rejected`: the story advanced, and a repo commit hook rejected its evidence commit in a way the gate may not answer, so that evidence waits, uncommitted, for the operator (`references/gate.md`'s advance route).
|
|
152
158
|
|
|
153
159
|
**Promoting the turn-budget marker.** The `budget_stop.py` Stop hook writes only its own markdown, `{workflow.implementation_artifacts}/.escalation-<story_id>.md`. It stays a recorder: it emits no JSON and starts no process, and its marker records a count without stopping the drive, so the story still goes on to its gate. **Execute is the sole promoter of that markdown, and the story's gate decides whether it promotes.** A marker counts only while the story's recorded count (`turns` in `{workflow.implementation_artifacts}/.budget-<story_id>.json`) is at or past `{workflow.max_turns_per_story}`: after `/ucg-resolve` closes a `budget-overrun` escalation and resets that counter, the marker left on disk is the answered escalation's residue, and nothing below applies to it. **When the gate advances the story (`advance`, or `defer`, whose route advances anyway), do not promote the marker.** The gate decides completion, and none of the decisions the marker asks for has anything left to act on once the story is done: in a real project, every overrun escalation written for a story that then passed its gate was left open and never answered. Log a sizing note in `.decision-log.md` instead, naming the story and the hook's count against `{workflow.max_turns_per_story}`, and saying that a story of this shape should be split smaller next time; Finalize's run report carries it. **When the gate escalates the story on the turn count** (a re-loop that would exceed the ceiling, which `references/gate.md` turns into `escalate`), promote the marker as that escalation's sidecar: read the `.escalation-<story_id>.md` the hook left behind and write the typed sidecar from it, mapping `source` to that markdown's path, `kind` to `budget-overrun`, `decision_needed` to the human decision the marker asks for (re-scope, split, or hand off), and `evidence` to one line quoted from the marker. The gate can escalate on the count before the hook has written a marker (a re-loop expected to take several responses, from a count still under the ceiling); write the same `budget-overrun` sidecar then from `{workflow.implementation_artifacts}/.budget-<story_id>.json`, with `source` that file's path and `evidence` its count, so `/ucg-resolve` still resets the counter when it closes it. A cap-only `reloop` (a sweep-scope or delta cap) is not that verdict: the full re-gate it leads to decides. A story that escalates for its own reason (a gate file that cannot be read, a sub-skill halt) keeps that reason's sidecar, and the marker's count goes into the decision log beside it. A resume that finds the count already at or past the ceiling escalates before step 0 with the same `kind`, as "Authoring the `/goal` condition" above says. Keeping promotion here means one code path produces the typed JSON whatever the escalation's origin, instead of two writers racing on a file three readers depend on.
|
|
154
160
|
|
|
@@ -186,7 +192,7 @@ As the spine advances — each time you move to a new story, log a gate verdict,
|
|
|
186
192
|
"updated": "<ISO-8601 timestamp>"}
|
|
187
193
|
```
|
|
188
194
|
|
|
189
|
-
`last_reasons` and `budget_used` are machine-derived, not narrated. `last_reasons` is the `reasons` array from the `gate_eval.py` result the spine just read, copied across unedited, so a poller sees *why* the last verdict landed instead of only the verdict word; `stories` carries one entry per in-scope story on the same cadence, so an entry appears as soon as the spine reaches that story and its `verdict` stays null until the gate runs. The two `reloop_count`s are deliberately the same name at two nesting levels and are not duplicates: the top-level one is **run-scoped** (every re-loop spent this run), the one inside a `stories` entry is **story-scoped** (that story's own re-loops).
|
|
195
|
+
`last_reasons` and `budget_used` are machine-derived, not narrated. `last_reasons` is the `reasons` array from the `gate_eval.py` result the spine just read, copied across unedited, so a poller sees *why* the last verdict landed instead of only the verdict word (after a re-loop `references/gate.md` logs before trace, in "A red backfill sweep ends the cycle at a re-loop", no `gate_eval.py` result exists, and it is the `reasons` array of the verdict object logged there); `stories` carries one entry per in-scope story on the same cadence, so an entry appears as soon as the spine reaches that story and its `verdict` stays null until the gate runs. The two `reloop_count`s are deliberately the same name at two nesting levels and are not duplicates: the top-level one is **run-scoped** (every re-loop spent this run), the one inside a `stories` entry is **story-scoped** (that story's own re-loops).
|
|
190
196
|
|
|
191
197
|
`budget_used` has exactly two sub-keys and no third: `turns`, copied from the `turns` value in `{workflow.implementation_artifacts}/.budget-<story>.json` that the Stop hook maintains, and `max_turns`, the resolved `{workflow.max_turns_per_story}` — the same value preflight already injects into the hook environment, so the ceiling reported here and the ceiling the hook enforces cannot drift apart.
|
|
192
198
|
|
|
@@ -119,13 +119,15 @@ The delegation is hard time-boxed by the `timeout 300` wrapper above and is **no
|
|
|
119
119
|
|
|
120
120
|
Execute maintains the heartbeat `{workflow.implementation_artifacts}/run-status.json` as the spine advances (shape: `{epic, story, index, total, last_verdict, last_reasons, reloop_count, stories, budget_used, profile, updated}`). At close, write its **terminal** state — the final story/index, the `last_verdict` (`advance` when the Epic completed, the escalating story's verdict when blocked, or the last in-scope story's `advance` for a `partial-complete` run — a deliberate strict subset of the Epic delivered with no Epic-level gate), and a fresh `updated` timestamp — so a poller reading the file after the run sees the settled outcome, not a stale mid-run snapshot. **Write the whole shape, not a subset.** This write overwrites the file, so a narrower object silently strips keys a poller was reading mid-run: carry `last_reasons` and `stories` through from the last heartbeat rather than dropping them off the artifact at the moment the run settles — those two have no fresher source than the snapshot. **`budget_used` does have one, so it is re-derived, never carried**: re-read the final story's `{workflow.implementation_artifacts}/.budget-<story>.json` exactly as every heartbeat write does (execute.md's hook-file-wins rule — "never carry the snapshot's own number forward"). The terminal write is the write most likely to land after turns the last heartbeat never saw — this stage's own — and a carried-forward number under-reports precisely there, in the one direction that matters: a run that ran close to its ceiling reports headroom, and that figure feeds the sizing decisions the next Epic makes. **The enumerated keys are the whole shape.** This file is a single live snapshot, not an accumulating record: do not add a key the shape does not name, and do not carry one forward from an earlier run's write. Dropping an unenumerated key is not narrowing — narrowing loses a key this shape defines and a poller was reading, whereas an unenumerated key has no reader (`scripts/status_render.py` renders exactly these keys and ignores anything else) and no consumer may pin against it (`docs/_internal/STABILITY.md` places this file outside the consumable contract).
|
|
121
121
|
|
|
122
|
+
A run that stopped on an `evidence-commit-rejected` escalation keeps that story's `advance` as `last_verdict`, since the story advanced, so its terminal `last_reasons` carries one reason naming that story's `escalation-<story_id>.json` and saying its gate evidence is not committed: without it, the last story's stop would read exactly like a completed Epic. The resume that later makes that commit replaces those reasons with one naming the commit it made, rather than carrying the blocked run's forward.
|
|
123
|
+
|
|
122
124
|
## Surface the deferred-work ledger
|
|
123
125
|
|
|
124
126
|
Show the user **this run's Epic heading** from the ledger at `{workflow.deferred_work_path}` — the open items under that one heading, their severity and suggested actions — so nothing parked during the run is invisible at handoff. The ledger holds one heading per Epic across runs; do not surface other Epics' parked work. If the file (or this Epic's heading) does not exist, say so plainly: nothing was deferred this run.
|
|
125
127
|
|
|
126
128
|
## Epic-complete hook
|
|
127
129
|
|
|
128
|
-
This hook fires **only when the Epic-level gate verdict was `advance`** (a `complete` run). On a `blocked` run
|
|
130
|
+
This hook fires **only when the Epic-level gate verdict was `advance`** (a `complete` run) and its evidence is committed. On a `blocked` run (a story escalated, so the Epic never advanced or the evidence commit of its last story waits on the operator), skip this step entirely; a "notify success" command must not fire on a blocked Epic.
|
|
129
131
|
|
|
130
132
|
When the Epic advanced, run: `uv run --no-project {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_epic_complete`
|
|
131
133
|
|
|
@@ -133,7 +135,7 @@ If the resolved `{workflow.on_epic_complete}` is non-empty, follow it as the fin
|
|
|
133
135
|
|
|
134
136
|
## Escalation hook
|
|
135
137
|
|
|
136
|
-
The mirror of the epic-complete hook at the opposite terminal. This hook fires **only on a `blocked` run**
|
|
138
|
+
The mirror of the epic-complete hook at the opposite terminal. This hook fires **only on a `blocked` run** (a story escalated, so the Epic never advanced or the evidence commit of its last story waits on the operator) and never on a clean advance, so an operator who walked away learns that the run stopped being able to make progress on its own.
|
|
137
139
|
|
|
138
140
|
Execute may already have pinged when the gate escalated a story on its turn count, so this site is deduped against that same run-scoped marker, `{workflow.implementation_artifacts}/.on-escalation-fired-<run-id>`, **check-then-write**, at that byte-identical path, where `<run-id>` is this invocation's run id, minted at Stage 1 or at a resume's re-entry and carried forward verbatim. If the marker is already present, skip silently: the other fire site already pinged for this run. If it is absent, run: `uv run --no-project {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_escalation`
|
|
139
141
|
|
|
@@ -143,7 +145,7 @@ This is a side effect on the way out, never a gate on the exit: a hook that erro
|
|
|
143
145
|
|
|
144
146
|
## Headless output
|
|
145
147
|
|
|
146
|
-
In headless (`-H`), build the final JSON **through the `scripts/headless_envelope.py` adapter**
|
|
148
|
+
In headless (`-H`), build the final JSON **through the `scripts/headless_envelope.py` adapter** (never hand-composed here), run the Workflow health check (below) in its unattended queue-only mode, then emit the JSON and stop. `status` is `complete` when the Epic-level gate advanced and its evidence is committed, or `blocked` when a story escalated, the last story's `evidence-commit-rejected` included, though the Epic-level gate advanced before it (`references/gate.md`), and the adapter has one entry point per shape:
|
|
147
149
|
|
|
148
150
|
```
|
|
149
151
|
build_complete_envelope(<path to this run's .decision-log.md>, report=<run-report.md path or None>, deferred_work=<{workflow.deferred_work_path} or None>, impl_artifacts={workflow.implementation_artifacts})
|