bmad-module-ultracode-goal 4.0.0 → 4.1.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.
@@ -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": "4.0.0",
22
+ "version": "4.1.0",
23
23
  "author": {
24
24
  "name": "Armel"
25
25
  },
@@ -58,7 +58,7 @@ skills/ultracode-goal/
58
58
  │ ├── gate_eval.py # gate status -> verdict (the completion authority)
59
59
  │ ├── operator_owed.py # is a gate FAIL owed only operator-evidence ACs' records? (fail-closed)
60
60
  │ ├── mutate_check.py # mutation harness: attributable-red proof for the story's guards
61
- │ ├── probe_servers.py # which URLs a test runner may reuse already answer, and from which folder
61
+ │ ├── probe_servers.py # which URLs a test runner may reuse already answer, from which folder; stops a server the run left up
62
62
  │ ├── link_worktree_deps.py # links the main tree's dependency folders into the gate worktree
63
63
  │ ├── gate_trail.py # per-story evidence trail (gate-trail.md) at finalize
64
64
  │ ├── formalize_check.py # readiness kernel behind the /ucg-formalize gate
@@ -91,4 +91,4 @@ Useful flags: `--limit N` caps how many sessions it spawns, retries included, `-
91
91
 
92
92
  At preflight the skill auto-merges its **PreToolUse** guard and **Stop** budget hook into `.claude/settings.local.json`, a machine-local, gitignored file, honored after the workspace trust dialog. These hooks are the enforcement layer that blocks a commit on a protected branch and records each story's turn count; they are not shared into the repo. The guard's entry carries `"onFailure": "block"`, so a guard that cannot run (no `uv` on `PATH`, say) makes Claude Code refuse the tool call instead of letting it through unchecked; if every call is then refused, see [Troubleshooting](./troubleshooting.md#every-tool-call-is-refused). Because they execute on your machine, review what gets merged: see [SECURITY.md](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/SECURITY.md) for the hook-security model and what to check before granting trust.
93
93
 
94
- **Take a new Epic through preflight attended.** The same write adds allow rules built from `allowlist_commands`, and Claude Code treats `.claude/settings.local.json` as a protected file. A headless session cannot approve that write: under Auto Mode, which the run requires, the permission classifier may refuse it (or the calls after it) as self-modification, and under `drive_epic.py`'s default `acceptEdits` mode the write prompts with nobody there to answer. Either way the run stops at arming. So run the first invocation of a new Epic attended, in Auto Mode, through the launch briefing and on to at least one story's gate verdict; if a settings write is refused, approve it under `/permissions` (on its Recently denied tab) or apply it yourself, as the decision log describes. From then on, a session that resumes the Epic routes into Execute and only re-checks the hooks, so `-H` and `drive_epic.py` can take over.
94
+ **Take a new Epic through preflight attended.** The same write adds allow rules built from `allowlist_commands`, and Claude Code treats `.claude/settings.local.json` as a protected file. A headless session may be refused that write, and then nobody is there to approve it: under Auto Mode, which the run requires, the permission classifier may refuse it (or the calls after it) as self-modification, and under `drive_epic.py`'s default `acceptEdits` mode the write needs an approval nobody is there to give. Only `bypassPermissions` lets it land unreviewed. A refused write stops the run at arming. So run the first invocation of a new Epic attended, in Auto Mode, through the launch briefing and on to at least one story's gate verdict; if a settings write is refused, approve it under `/permissions` (on its Recently denied tab) or apply it yourself, as the decision log describes. From then on, a session that resumes the Epic routes into Execute and only re-checks the hooks, so `-H` and `drive_epic.py` can take over. A resume that finds the hooks need re-arming (the first after an update to 4.x does, unless it first escalates a reason that is yours to fix, such as a Claude Code older than 2.1.295; then the resume after your fix does) writes the file again: make that resume attended too, or see [Troubleshooting](./troubleshooting.md#preflight-cant-reach-budget-zero) if a headless one met a refused write.
@@ -175,6 +175,6 @@ Each of these was hit while verifying real work, and each one first looked like
175
175
 
176
176
  **The spawned session's sandbox may refuse network egress when the parent's does not.** A story escalated reporting that two data files "cannot be fetched" and a dependency was "absent". From the parent session both were trivially available: the dependency was already in the local package cache and a plain `curl` reached the upstream host. **When a spawn reports a dependency it cannot fetch, check the local package caches and try the fetch yourself before accepting the block.**
177
177
 
178
- **Stop a dev server before an unattended drive.** A test runner that reuses a server already answering at its URL, as Playwright does with `reuseExistingServer` (which TEA's framework scaffold turns on outside CI), attaches the gate's runs in its measurement worktree to the dev server you left running from your own checkout. Those browser runs then exercise your checkout's source, not the commit under assessment, and a mutation the gate writes into the worktree never reaches them. The gate checks the URLs a runner config may reuse and never stops a server it did not start: it gives the worktree's runs their own server on a free port when a scratch runner config can, whether or not one answers, and otherwise tells every assessor the limit, so a risk that only a browser run could measure goes unmeasured. Observed: a gate's worktree runs attached to a vite dev server listening on `[::1]:3001` that had been started from the main tree, and automate left the source mutation behind one acceptance criterion unrun, since no run from the worktree could reach it. With the dev server stopped, the runner starts its own from the worktree, but a server it starts through a launcher such as turbo, which runs it in a process group of its own, outlives the run that started it, and with reuse on the runs after it reuse it, serving the files as they were when it started: the gate turns reuse off through its scratch config where it can, and otherwise reads a mutation row run through such a server as one that cannot run. A start command in your runner config that runs the server itself (the package's own dev script rather than turbo's) keeps it from outliving the run.
178
+ **Stop a dev server before an unattended drive.** A test runner that reuses a server already answering at its URL, as Playwright does with `reuseExistingServer` (which TEA's framework scaffold turns on outside CI), attaches the gate's runs in its measurement worktree to the dev server you left running from your own checkout. Those browser runs then exercise your checkout's source, not the commit under assessment, and a mutation the gate writes into the worktree never reaches them. The gate checks the URLs a runner config may reuse and never stops a server unless it reads as one the run itself left up (below): it gives the worktree's runs their own server on a free port when a scratch runner config can, whether or not one answers, and otherwise tells every assessor the limit, so a risk that only a browser run could measure goes unmeasured. Observed: a gate's worktree runs attached to a vite dev server listening on `[::1]:3001` that had been started from the main tree, and automate left the source mutation behind one acceptance criterion unrun, since no run from the worktree could reach it. With the dev server stopped, the runner starts its own from the worktree, but a server it starts through a launcher such as turbo, which runs it in a process group of its own, outlives the run that started it, and with reuse on the runs after it reuse it, serving the files as they were when it started: the gate turns reuse off through its scratch config where it can, and otherwise reads a mutation row run through such a server as one that cannot run. A start command in your runner config that runs the server itself (the package's own dev script rather than turbo's) keeps it from outliving the run. On Linux the gate stops a server the run itself left up, such as one the sweep right before the gate started through turbo, at each of its checks and once more when the story's gate ends, so those servers do not pile up over an Epic, and the decision log names each one it stopped. It stops one only when every process of it is yours, has no controlling terminal and started after the current story's baseline marker was written, the process that started its session has exited, nothing else that still runs in that session started before the marker or is the parent of one of its processes (a watcher or supervisor that can start it again), and it runs from your project or the gate's worktree. A server of yours can meet all of that: one inside the project and on a port the gate checks, started in the background by a command that has since exited (a script's, or another agent session's) or from a terminal you then close (a `nohup ... &`), with nothing that began before the story still running in its session, reads as the run's and is stopped. So does one that a watcher of yours starts again after the story began, when the watcher too began after the story and runs in the server's process group, or starts the server through a command that then exits and either began after the story or had that command give the server a session of its own. That marker is written when the story starts, and the resume of a stopped or blocked run keeps it, so such a server you start between a run and its resume is stopped too. So stop it before you start or resume a drive, as this tip says, or start it outside the project, on another port or from a terminal you keep open.
179
179
 
180
180
  **Pin the parallelism of the verification suite if it is timing-sensitive.** Observed: a full-concurrency test run was flaky two green in five, because one unrelated gate crept past a 10-second default timeout under contention while taking 1.7 seconds alone. Pinning the runner to one worker (`ava --concurrency=1`; your runner's own name for it will differ) was green every time. A flaky verification tier makes every story's evidence unreliable, which is worse than a slow one.
@@ -25,9 +25,11 @@ flowchart TD
25
25
  R -->|"yes"| RES["See: Resume after an interruption"]
26
26
  R -->|"no"| D{"A drive stopped and you cannot tell why"}
27
27
  D -->|"yes"| OPS["See: operating tips, the driver's stop reasons"]
28
- D -->|"no"| LOG["Read the tail of .decision-log.md"]
28
+ D -->|"no"| V{"A dev server of yours is gone after a drive"}
29
+ V -->|"yes"| SRV["See: The gate stopped a server, or left one up"]
30
+ V -->|"no"| LOG["Read the tail of .decision-log.md"]
29
31
  classDef accent fill:#6366F1,stroke:#4F46E5,color:#fff
30
- class PRE,GATE,HOOK,REF,BUD,RES,OPS,LOG accent
32
+ class PRE,GATE,HOOK,REF,BUD,RES,OPS,SRV,LOG accent
31
33
  ```
32
34
 
33
35
  ## Preflight can't reach budget-zero
@@ -40,9 +42,9 @@ flowchart TD
40
42
 
41
43
  - **Undecided product or architecture decisions.** An open question, a "TBD"/"TODO: decide" on a load-bearing requirement, a PRD↔ADR contradiction, or a story whose "done" is undefinable. The fix is a human decision; an unattended run guessing it produces confidently wrong work. Resolve the decision in the artifacts, then re-run.
42
44
  - **Missing secrets in headless.** Headless never prompts, so a secret that cannot be resolved becomes a RED blocker rather than a question. Provide the secret (out of git) before the headless run, or run attended so preflight can prompt once.
43
- - **Claude Code below the minimum versions.** The primitive-version blocker (`cc_version`) is marked non-remediable: the script can't upgrade the host. It names each primitive the version lacks. 2.1.295 is the floor, the release that added the hook setting `"onFailure": "block"` the guard is armed with. Update Claude Code (`claude update`).
45
+ - **Claude Code below the minimum versions.** The primitive-version blocker (`cc_version`) is marked non-remediable: the script can't upgrade the host. It names each primitive the version lacks. 2.1.295 is the floor, the release that added the hook setting `"onFailure": "block"` the guard is armed with. Update Claude Code (`claude update`). A run already in flight meets the same floor when it resumes: the resume runs `claude --version`, and below 2.1.295 it escalates the story it was about to drive instead of driving it. Update Claude Code, then resume in a new session, since an update takes effect only when Claude Code next starts: the resume shows that escalation and offers `/ucg-resolve` to close it (headless, run `/ucg-resolve` first). On a run UCG 3.x armed, that resume is also the one that re-arms the hooks, a write to `.claude/settings.local.json`: make it attended, since a headless one may be refused the write (see "A refused settings write" below). Both checks run the `claude` first on `PATH`, not the binary the session runs on. With two installs (an npm one beside the native installer's, say), or a `drive_epic.py --claude-bin` that names another binary, update the one first on `PATH` too, or the check reads its older version.
44
46
  - **A repository with nothing committed.** On a fresh `git init` (or an orphan branch) the `git_unborn` blocker is non-remediable: the run never makes the commit its Epic branch would start from, because that commit would sit outside its only rollback, the Epic branch. Commit a baseline yourself (the BMAD install, the planning artifacts and the project skeleton) on your base branch, a protected branch such as `main` and never an Epic branch, then re-run. If HEAD already names an Epic branch, the blocker's detail gives the command that points it at the base first.
45
- - **A refused settings write.** Preflight writes its hooks and allow rules into `.claude/settings.local.json`, which Claude Code treats as protected. Under Auto Mode the permission classifier may refuse that write, or let it land and refuse the next calls, as self-modification. The run then stops rather than work around the refusal, and the decision log names the write. Attended, approve it under `/permissions` (on its Recently denied tab) or apply it yourself; the run re-checks the hooks and continues. Headless, there is nobody to approve it, and `/ucg-resolve` is not the way back: take the Epic through preflight attended (see [hook security](./getting-started.md#hook-security)).
47
+ - **A refused settings write.** Preflight writes its hooks and allow rules into `.claude/settings.local.json`, which Claude Code treats as protected. Under Auto Mode the permission classifier may refuse that write, or let it land and refuse the next calls, as self-modification. The run then stops rather than work around the refusal, and the decision log names the write. Attended, approve it under `/permissions` (on its Recently denied tab) or apply it yourself; the run re-checks the hooks and continues. Headless, nobody is there to approve a refused write. At preflight the run then stops, and `/ucg-resolve` is not the way back: take the Epic through preflight attended (see [hook security](./getting-started.md#hook-security)). A resume rewrites the file too when the hooks need re-arming (the first resume after an update to 4.x does, unless it first escalates a reason that is yours to fix, such as a Claude Code older than 2.1.295), and a headless resume whose write is refused escalates the story it was about to drive instead. Resume attended: make or approve the write it asks for, and close that escalation with `/ucg-resolve`, which the resume offers before it drives the story. Whether a headless session is refused the write depends on its permission mode: under `bypassPermissions` the write lands, under Auto Mode the classifier decides, and under `default`, `acceptEdits` (the mode `drive_epic.py` spawns in unless you pass another) or `dontAsk` it is refused, since a write to a protected file needs an approval nobody is there to give.
46
48
  - **Story skills not installed.** The run delegates story creation to `ucg-create-story` and implementation to `ucg-dev-story`, the story skills UCG ships in place of BMAD Method's deprecated `bmad-create-story` and `bmad-dev-story`. UCG's installer copies them beside the `ultracode-goal` skill, so a missing one means a partial or older UCG install, or an install from the plugin marketplace alone, which ships only the `ultracode-goal` skill. The `story_skills` blocker is non-remediable: the run neither installs them nor works around them. Its detail names the fix, `npx bmad-module-ultracode-goal update` from the project root (`install` where UCG was never installed there). BMAD's own shims, installed with `--shims`, do not satisfy it (see [Prerequisites](./getting-started.md#prerequisites)). The same check runs on every resume, so a story skill deleted mid-Epic, by hand or by an install interrupted while it re-copies the UCG skills, stops the next spawn instead of letting it improvise.
47
49
  - **TEA skills not installed.** The run delegates test design, acceptance tests, review and the gate to TEA's `bmad-testarch-*` skills. Production needs all eight. `--light` needs three: `bmad-testarch-framework`, `bmad-testarch-test-design` and `bmad-testarch-trace`. The `tea_skills` blocker is non-remediable: the run never installs TEA. UCG supports BMAD 6 with TEA 1.27.x, which BMAD Method 6.12.2 and later install. Add or repair TEA from the project root with `npx bmad-method install`, with the `tea` module selected, then re-run. If the detail says it found `bmad-tea-*` skills instead, the project has TEA 3.0 or later, which renamed the skills UCG calls. UCG does not support it yet: install TEA 1.27.x through BMAD 6 instead (see [Prerequisites](./getting-started.md#prerequisites)). Preflight checks skill names, not the TEA version. TEA 2.x moved to BMAD 7's module format but kept the `bmad-testarch-*` names, so preflight does not catch it, though UCG does not support it either. Preflight checks these skills at launch only. A TEA skill removed mid-Epic escalates the story that calls it.
48
50
 
@@ -63,6 +65,14 @@ Note this is fail-closed on purpose: a missing or unreadable gate artifact escal
63
65
 
64
66
  A per-story gate can return `reloop` with a `PASS` gate status when a cap fired rather than a finding: the `reasons` name either the sweep-scope cap (the `.tests-ran` marker says `scope=scoped`, or the marker/`scope=` line is missing) or the delta-profile cap (`--cycle-profile delta` was declared). Neither is an error; both mean "not yet, and here is why": a story only advances off a full-scope sweep judged by the full gate instrument. The remedy is the cap-only re-loop, which skips the generalize ceremony entirely: re-run the full three-axis sweep, refresh the marker with `scope=full`, and re-run the gate without `--cycle-profile`. See the cap sections in the [gate model](./gate-model.md).
65
67
 
68
+ ## The gate stopped a server, or left one up
69
+
70
+ **Symptom.** A dev server you had running is gone after a drive, or the decision log's worktree line names a server the gate stopped, or one it left up.
71
+
72
+ **What happened.** A test runner such as Playwright starts a server through a launcher such as turbo, which runs it in a process group of its own, so the server outlives the run. Execute's sweep right before the gate leaves one up in the main tree that way, and so does a gate run. On Linux the gate stops such a server with `scripts/probe_servers.py` at each of its checks, and once more when the story's gate ends, so the gate's runs in its worktree do not reuse it and those servers do not pile up over an Epic. It stops a server only when every process of it is yours, has no controlling terminal and started after the story's `.baseline-<story_id>` marker was written, the process that started its session has exited, nothing else that still runs in that session started before the marker or is the parent of one of its processes (a watcher or supervisor that can start it again), and it runs from the project or the gate's worktree. It leaves every other server up, and its `left` list gives the reason; on macOS and Windows it stops nothing. The gate never stops a server any other way.
73
+
74
+ **What you do.** If it stopped a server of yours, that server met every condition: it started inside the project, on a port the gate checks and after the story's marker was written, it had no terminal and had outlived the command that started its session, as a server does that a script or another agent session starts in the background, or one you start with `nohup ... &` from a terminal you then close, and nothing that began before the marker still ran in its session. A watcher or supervisor of yours that starts the server again after the marker (on a file change the run makes, say) keeps it up only while it runs in the server's session and either began before the marker or is the parent of one of the server's processes from a process group of its own; the server reads as the run's when the watcher began after the marker and either runs in the server's process group or starts it through a command that then exits and is not its parent afterwards (a subreaper adopts it back), or, whenever the watcher began, when that command gave the server a session of its own. That marker is written when the story starts, and the resume of a stopped or blocked run keeps it, so it can be days old: a server you start between a run and its resume counts too. Start it again, and stop such a server before you start or resume a drive, or start it outside the project, on another port or from a terminal you keep open. A server it left up keeps its port, so the gate gives the worktree's runs a server of their own through a scratch runner config where it can, and otherwise tells each assessor what that server leaves unmeasured. When the run left that server up, stop it yourself once the drive is done: a runner killed before it could end its start command leaves one whose session's first process still runs, and a watcher the run's own start command runs (a launcher task that runs watchexec, cargo-watch or air, say) keeps up the server it runs in a process group of its own, as a watcher of yours does, so stop that watcher too. A drive that stops before a story's gate logs its verdict can leave one up as well: that story's next gate stops it when you resume the run, so stop it yourself only if you do not resume.
75
+
66
76
  ## Hooks not firing
67
77
 
68
78
  **Symptom.** A commit lands on a protected branch, or a commit lands before a story's tests ran: the invariants the PreToolUse hook should enforce did not block.
@@ -80,7 +90,7 @@ A per-story gate can return `reloop` with a `PASS` gate status when a cap fired
80
90
  **What happened.** Preflight arms the PreToolUse guard with `"onFailure": "block"`, so when the guard cannot run, Claude Code refuses the call rather than letting it through unchecked. The guard's matcher covers every tool, so a guard that cannot run refuses every call, including the ones the session would need to repair it. The usual causes:
81
91
 
82
92
  - **`uv` is not on the `PATH` Claude Code runs hooks with.** The guard runs as `uv run …`, and a shell that cannot find `uv` exits 127. A session started from a shell or launcher with a narrower `PATH` than the one preflight ran in hits this.
83
- - **The skill was moved or removed.** The guard's command names the script by the path the skill was installed at; an uninstall, or a reinstall to another folder, leaves the command pointing at nothing.
93
+ - **The skill was moved or removed.** The guard's command names the script by the path the skill was installed at; an uninstall, or a reinstall to another folder, leaves the command pointing at nothing. When the project, or a folder above it, holds a `pyproject.toml`, `uv run` syncs that project on every call before it finds the script missing: it creates the project's `.venv` and `uv.lock` on the first call and builds the project again whenever it changes, and the refusal can show that project's build error instead of `Failed to spawn`. The budget hook's command points at nothing too. `uv` exits 2 when it cannot find the script, which on a `Stop` hook Claude Code reads as a block: each time the session tries to stop, it is sent back with uv's error instead, up to eight times in a row, after which Claude Code lets the stop through (the count starts again whenever Claude calls a tool). When that project fails to build, or its requirements cannot be satisfied, `uv` stops there and exits 1, which Claude Code reads on a `Stop` hook as a non-blocking error: the session stops, and the turn goes uncounted. A network failure in that sync exits 2 instead, and each stop is sent back as above. Reinstalling the skill ends it; then delete a `.venv` or `uv.lock` those calls left in a project that had none.
84
94
  - **A path with a space, left unquoted in the command.** Claude Code runs the guard's command through a shell, which splits it at every unquoted space. Preflight writes each injected value and the script path in single quotes, so a project or skill folder whose path holds a space (`~/My Projects/app`, say) stays one word. A command written without them hands the rest of that path to the shell as the command to run, and the message names it: `/bin/sh: 1: Projects/app/_bmad-output/implementation-artifacts: not found` on Linux, or the same path followed by `No such file or directory` on macOS.
85
95
  - **No Python `uv` can use.** `uv` cannot start a Python the script's header allows.
86
96
  - **The guard ran past its timeout.** Claude Code's default for a command hook is 600 seconds; the message then says `timed out`.
@@ -91,7 +101,7 @@ A refusal the guard makes itself reads differently: it starts with the guard's o
91
101
 
92
102
  1. Run the guard's command from `.claude/settings.local.json` yourself, in a terminal, to see why it fails (`echo '{}' | <the command>` should exit 0 and print nothing).
93
103
  2. Fix what it shows: put `uv` on `PATH`, reinstall the skill (`npx bmad-module-ultracode-goal update`), install a Python the script allows, or put each injected value and the script path in single quotes (`KEY='value' uv run '<path>'`), in the Stop budget hook's command too. From the project root, `uv run '<the skill folder>/scripts/preflight_check.py' --assert-armed --project-root . --impl-artifacts _bmad-output/implementation-artifacts` names every UCG hook command the shell would split (pass your own artifacts folder if you moved it).
94
- 3. Then resume the run. The resume re-checks the hooks and re-arms them if they need it.
104
+ 3. Then resume the run. The resume re-checks the hooks and re-arms them if they need it, unless it also finds a reason that is yours to fix, a missing story skill or a Claude Code older than 2.1.295: it then escalates the story it was about to drive first, and re-arms the hooks on the resume after you fix that.
95
105
 
96
106
  If you need the session working before you can fix the cause, remove the guard's item from `.claude/settings.local.json` by hand, as [SECURITY.md](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/SECURITY.md) describes under "How to remove them". The session then runs with no guard at all, and a resume or the next preflight puts the item back, so fix the cause before either.
97
107
 
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": "4.0.0",
4
+ "version": "4.1.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",
@@ -147,12 +147,23 @@ exists to remove.
147
147
 
148
148
  An entry recorded with `action` `defer` is the opposite case: it is a parked question, not
149
149
  an answered one. Present it again, and replace its entry in place when the operator decides
150
- it. Suppressing a deferred item would deadlock the run outright — `defer` clears nothing,
150
+ it, carrying its answer forward (section 3). Suppressing a deferred item would deadlock
151
+ the run outright: `defer` clears nothing,
151
152
  so the next preflight still blocks on that RED (`{ucg-root}/references/preflight.md`,
152
153
  step 3, drops only the ids whose `action` is `close`), while this surface, the only one that
153
154
  can answer it, would never ask again. The scan blocks forever on a question the operator is
154
155
  no longer offered.
155
156
 
157
+ An entry with no `action`, or with an `action` that is neither `close` nor `defer`, is
158
+ pending as well. An earlier version of this surface wrote some entries that way, and
159
+ preflight drops none of their ids, so their questions still block. Present it again, as
160
+ you present a deferred one.
161
+
162
+ When an item you present already has an entry, show its `answer`, and each earlier answer
163
+ its `history` holds (section 3), beside the decision needed. Such an answer can hold the
164
+ operator's whole ruling: they decide on the record as it stands, and may find it already
165
+ answers the question.
166
+
156
167
  ## 3. Record the answer, then apply its disposition
157
168
 
158
169
  Every answer lands in `{workflow.implementation_artifacts}/.decisions.json`:
@@ -160,18 +171,33 @@ Every answer lands in `{workflow.implementation_artifacts}/.decisions.json`:
160
171
  ```json
161
172
  {"decisions": [{"id": "<the pending item's stable id>",
162
173
  "answer": "<what the operator decided, one line>",
163
- "action": "close|defer"}]}
174
+ "action": "close|defer",
175
+ "history": [{"answer": "<an answer this entry replaced, verbatim>",
176
+ "action": "<that answer's action, when it had one>"}]}]}
164
177
  ```
165
178
 
166
179
  **Write the file read-modify-write, keyed by `id`.** Read any existing `.decisions.json`
167
- first, merge this pass's answers into its `decisions[]` — a new answer for an `id` already
168
- present replaces that entry, every other entry is preserved untouched — and write the whole
180
+ first, merge this pass's answers into its `decisions[]` (a new answer for an `id` already
181
+ present replaces that entry and carries its answer forward, as the next paragraph says;
182
+ every other entry is preserved untouched), and write the whole
169
183
  array back. The fence above is the shape of the *document*, not a licence to emit only this
170
184
  pass's answers: a plain overwrite would discard every answer recorded by an earlier pass,
171
185
  including the `close` entries preflight reads to keep resolved REDs suppressed. Those
172
186
  decisions would silently return as pending and re-block a run the operator already
173
187
  unblocked.
174
188
 
189
+ **A replacement never drops an earlier answer.** When a new answer replaces the entry for
190
+ its `id`, the new entry carries that entry forward in `history`: copy the replaced entry's
191
+ `history` list as it stands, then append the replaced entry itself, with every field but
192
+ `id` and `history` copied verbatim (its `answer`, and its `action` when it had one). When
193
+ the file holds more than one entry for that `id`, carry each forward, in file order, and
194
+ write one entry in their place. Leave `history` off an entry that replaced nothing. A pass
195
+ that only parks an item records one line, while the entry it replaces can hold the
196
+ operator's whole ruling: a plain replacement would erase that ruling, and nothing in the
197
+ pass would report the loss. Every reader of the file keys on `id` and `action` alone
198
+ (`{ucg-root}/scripts/red_ids.py`, which preflight and the resume read it through), so
199
+ `history` changes no suppression.
200
+
175
201
  **If an existing `.decisions.json` is unreadable, unparseable, or parsed but missing a
176
202
  list-valued `decisions`, stop — do not overwrite it.** Say which file failed and why. This
177
203
  is the fail-closed twin of the rule preflight already applies to the same file (an
@@ -242,10 +268,15 @@ The two dispositions are genuinely different things, not two names for one:
242
268
  and removes the marker (`{ucg-root}/references/gate.md`, "Commit the gate's evidence
243
269
  before the next story starts"), on the Epic's last story too, where every row already
244
270
  reads `done` and the resume re-enters only for that commit before Finalize.
245
- **Closing a `coupled-stories` escalation records the move, and the resumed run makes
246
- it.** The sidecar proposes moving clauses the earlier story owes to the later story it
247
- names, which narrows the earlier story's AC (`{ucg-root}/references/execute.md`, "Two
248
- stories green only together"). When the operator approves the move, as proposed or
271
+ **Closing a `coupled-stories` escalation records a proposed move, and the resumed run
272
+ makes it; a re-plan is the operator's own edit.**
273
+ The sidecar proposes moving clauses the earlier story owes to the later story it
274
+ names, which narrows the earlier story's AC, or it proposes only a re-plan, where no
275
+ move fits: the later story is outside the run's scope, the two stories are a pair no
276
+ move applies to (a decomposed child beside a story that has a file, or children of two
277
+ parents), or an AC between two decomposed children holds a clause no run measured
278
+ (`{ucg-root}/references/execute.md`, "Two stories green only together"). When the
279
+ operator approves a proposed move, as proposed or
249
280
  reworded, write the sidecar's `decision_needed` verbatim into this answer's
250
281
  `.decision-log.md` entry, under both story keys it names, beside the operator's answer
251
282
  and the id you closed, before you delete the sidecar: once the sidecar is gone, that
@@ -256,7 +287,10 @@ The two dispositions are genuinely different things, not two names for one:
256
287
  and the resumed run applies it before the earlier story's next commit. An answer that
257
288
  re-plans the rows instead (one story in place of the two, or another order) is the
258
289
  operator's own edit of `sprint-status.yaml` and the story files: record `defer` until
259
- they have made it, then `close`.
290
+ they have made it, then `close`. A sidecar that proposes only a re-plan has no move for
291
+ this surface to record or for the resumed run to apply, so whatever the operator rules
292
+ for it is their own edit of those files: record `defer` until they have made it, then
293
+ `close`.
260
294
  - **`defer`** — the decision is not made yet. Record the entry **without clearing
261
295
  anything**. The artifact stays exactly where it is, the item stays pending, and the next
262
296
  preflight still blocks on it.
@@ -266,7 +300,9 @@ Record each answer and its disposition in `.decision-log.md` as you apply it.
266
300
  ## 4. Hand control back to the existing resume
267
301
 
268
302
  `/ucg-resolve` defines no resume of its own. Close the pass by stating what closed, what is
269
- still pending, and that anything still pending re-blocks at the next preflight. **Hand back
303
+ still pending, and that anything still pending re-blocks at the next preflight. Name every
304
+ entry this pass replaced, by `id`, with the earlier answer it carried into `history`, so
305
+ the operator sees what the record held before this pass. **Hand back
270
306
  only when the pass closed at least one item, or when the operator asks for the resume**: a
271
307
  pass that deferred everything hands into a run blocked on the identical items, and an empty
272
308
  enumeration means the run stopped for a non-decision reason — say so, point at the read-only
@@ -14,11 +14,11 @@ Preconditions (asserted, not assumed): you are on the Epic branch (`{workflow.ep
14
14
 
15
15
  **A resume owes the stall check first.** Before the re-assertions below, apply the per-step heartbeat's gap rule (the "Run-status heartbeat" section): when the in-flight story's `.heartbeat-<story_id>` exists and its last line is older than 30 minutes, write the `.stall-<story_id>` line before driving anything — the resume is the only reader positioned to see the gap while its cause is still nearby.
16
16
 
17
- **The re-assertion sweep is one script call, not a tool action per fact.** Run `uv run {skill-root}/scripts/preflight_check.py --assert-armed --project-root {project-root} --impl-artifacts {workflow.implementation_artifacts} --epic-branch-prefix {workflow.epic_branch_prefix} --story <the story about to be driven> --run-id <this run's id> --trace-output {workflow.trace_output_dir}` (plus one `--protected-branch <name>` per protected branch, as Stage 2's step 1 passes them: the prefix and the protected list are resolved scalars, and omitting either would assert the branch against a default the operator may have overridden). Exit 0 asserts the branch, both hooks with the all-tools matcher and the guard item's `"onFailure": "block"`, each UCG hook command split by the shell into its injected values, `uv run` and its script, the five injected hook env vars, and that `ucg-create-story` and `ucg-dev-story` are still installed (a manual deletion, or a UCG install or update interrupted between removing the UCG skills and copying them back, between spawns, can leave a run without them) in one read, and the `story` block returns the artifact-derived route this paragraph defines: `decision-pending` (the next paragraph), `story-boundary`, `mid-story`, or `gate-owed` (the committed-green-un-gated third case below, or the re-gate a closed `operator-evidence-owed` escalation owes, the fourth case after it; for the third case the script only ever returns it when `--trace-output` named the run's real, readable trace dir and the artifact evidence held in full, while an unverifiable location reads `unknown` and routes to the ordinary loop, so lack of evidence never skips steps 1 through 4). Three things the manifest deliberately does **not** cover: the latch is **reported, never certified** (whatever the JSON shows, re-latch from this run's own measurement exactly as above); a boundary story's fresh baseline is still written by step 0; and the **allowlist** is neither asserted nor reported (it lives in permission settings the script does not read), so re-assert it exactly as the list at the top of this paragraph requires. A non-zero exit is the resume's RED: fix what the `reasons` name before continuing, and never narrate around it. A fix that writes `.claude/settings.local.json` (a hook, its env, the allowlist) follows `references/preflight.md`'s "A refused settings write" rule if the write, or a call after it, is refused: stop, never work around it, and in headless take the escalation route below for the story about to be driven, naming the refused write. The one reason a resume never fixes is a skills failure (`checks.skills.ok: false`): installing UCG's story skills is the operator's call, so do not run the installer command that reason names, do not substitute another skill (`bmad-build`, `bmad-build-auto`, or BMAD's deprecated `bmad-create-story` and `bmad-dev-story`), and do not hand-author the story or the code. Take the sub-skill halt catch-all's route (below) for the story about to be driven: write `escalation-<story_id>.json` with `decision_needed` quoting that reason, then stop.
17
+ **The re-assertion sweep is one script call, not a tool action per fact.** Run `uv run {skill-root}/scripts/preflight_check.py --assert-armed --project-root {project-root} --impl-artifacts {workflow.implementation_artifacts} --epic-branch-prefix {workflow.epic_branch_prefix} --story <the story about to be driven> --run-id <this run's id> --trace-output {workflow.trace_output_dir}` (plus one `--protected-branch <name>` per protected branch, as Stage 2's step 1 passes them: the prefix and the protected list are resolved scalars, and omitting either would assert the branch against a default the operator may have overridden). Exit 0 asserts the branch, both hooks with the all-tools matcher and the guard item's `"onFailure": "block"`, each UCG hook command split by the shell into its injected values, `uv run` and its script, the five injected hook env vars, and that `ucg-create-story` and `ucg-dev-story` are still installed (a manual deletion, or a UCG install or update interrupted between removing the UCG skills and copying them back, between spawns, can leave a run without them), and that `claude --version` gives no version below 2.1.295, the release from which Claude Code honors the guard's `onFailure` (a version it cannot read is reported in `checks.cc_version` and fails nothing), in one read, and the `story` block returns the artifact-derived route this paragraph defines: `decision-pending` (the next paragraph), `story-boundary`, `mid-story`, or `gate-owed` (the committed-green-un-gated third case below, or the re-gate a closed `operator-evidence-owed` escalation owes, the fourth case after it; for the third case the script only ever returns it when `--trace-output` named the run's real, readable trace dir and the artifact evidence held in full, while an unverifiable location reads `unknown` and routes to the ordinary loop, so lack of evidence never skips steps 1 through 4). Three things the manifest deliberately does **not** cover: the latch is **reported, never certified** (whatever the JSON shows, re-latch from this run's own measurement exactly as above); a boundary story's fresh baseline is still written by step 0; and the **allowlist** is neither asserted nor reported (it lives in permission settings the script does not read), so re-assert it exactly as the list at the top of this paragraph requires. A non-zero exit is the resume's RED: fix what the `reasons` name before continuing, and never narrate around it. A fix that writes `.claude/settings.local.json` (a hook, its env, the allowlist) follows `references/preflight.md`'s "A refused settings write" rule if the write, or a call after it, is refused: stop, never work around it, and in headless take the escalation route below for the story about to be driven, naming the refused write. Two reasons are the operator's to fix, never a resume's. One is a skills failure (`checks.skills.ok: false`): installing UCG's story skills is the operator's call, so do not run the installer command that reason names, do not substitute another skill (`bmad-build`, `bmad-build-auto`, or BMAD's deprecated `bmad-create-story` and `bmad-dev-story`), and do not hand-author the story or the code. The other is a Claude Code below the minimum (`checks.cc_version.ok: false`): updating it is the operator's call too, and this session keeps the version it started with, so do not run `claude update`. For either, or both, 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 each such reason the `reasons` name, then stop. When one stands beside other reasons, a hooks reason included, take this route first and fix none of the others: the run stops on the operator's reason either way, and a hooks re-merge writes a protected file that a headless session may be refused. The resume after the operator's fix meets the others again and fixes them then.
18
18
 
19
- **A hooks reason is fixed in place, not by a return to Stage 2.** When the `reasons` name the hooks (a hook not armed, a matcher that is not the all-tools form, the guard not armed with `"onFailure": "block"`, a hook command the shell would not split as written, or injected env that is missing), apply `references/preflight.md` step 5's **Hooks** bullet alone, exactly as written there: re-merge both hooks into `.claude/settings.local.json` with this invocation's resolved scalars, first removing every inner item whose `command` names either script (replace, never append), and keep the allowlist entries the file already holds. A guard item without `"onFailure": "block"` is the one every run armed by UCG 3.x or earlier carries, so the first resume after an update meets this reason and re-arms here. Purge nothing: step 5's marker purge and its `.current-story` delete belong to an arming, and the turn counters this resume inherits are ones it must keep. Run none of preflight's checks, remediation or launch gate, and rebuild nothing else: the branch, the latch and the baseline marker keep the rules above. Then run the same `--assert-armed` call again, and drive the story only once it exits 0. A write that is refused takes the route the paragraph above gives (stop; headless, escalate for the story about to be driven, naming the write), so a drive by `scripts/drive_epic.py`, whose spawns run headless, stops at that spawn until an attended resume makes the write.
19
+ **A hooks reason is fixed in place, not by a return to Stage 2.** When the `reasons` name the hooks (a hook not armed, a matcher that is not the all-tools form, the guard not armed with `"onFailure": "block"`, a hook command the shell would not split as written, or injected env that is missing) and no reason that is the operator's to fix stands beside them (the paragraph above escalates that one first), apply `references/preflight.md` step 5's **Hooks** bullet alone, exactly as written there: re-merge both hooks into `.claude/settings.local.json` with this invocation's resolved scalars, first removing every inner item whose `command` names either script (replace, never append), and keep the allowlist entries the file already holds. A guard item without `"onFailure": "block"` is the one every run armed by UCG 3.x or earlier carries, so the first resume after an update meets this reason and re-arms here, unless a reason that is the operator's to fix (a skills failure, or a Claude Code below the minimum) stands beside it: the paragraph above takes the escalation route first, and the resume after the operator's fix re-arms here. Purge nothing: step 5's marker purge and its `.current-story` delete belong to an arming, and the turn counters this resume inherits are ones it must keep. Run none of preflight's checks, remediation or launch gate, and rebuild nothing else: the branch, the latch and the baseline marker keep the rules above. Then run the same `--assert-armed` call again, and drive the story only once it exits 0. A write that is refused takes the route the paragraph above gives (stop; headless, escalate for the story about to be driven, naming the write), so a drive by `scripts/drive_epic.py`, whose spawns run headless, stops at that spawn until an attended resume makes the write and `/ucg-resolve` closes that escalation, which the resume offers before it drives the story (the decision-pending paragraph below).
20
20
 
21
- **A re-entry story with an open escalation is not re-entered.** The `story` block also reports `escalation`: `null` when no `escalation-<story_id>.json` exists, and otherwise its `state`. It reads `open` when the sidecar is on disk and the id `/ucg-resolve` keys its answer by (`red_ids.py`'s, minted from the sidecar's own `kind`, `source` and `decision_needed`; a close keyed by the sidecar file's own path, as earlier passes keyed some, counts too) is not closed in `.decisions.json`, or when the sidecar cannot be read or no id can be minted from its fields, and the route is then `decision-pending`, ahead of the other three. `/ucg-resolve` deletes the sidecar when it closes the decision and leaves it in place on a `defer`, so a sidecar still on disk is a decision nobody closed: an answer written anywhere else (the story file, a ruling, the ledger) has not closed it. On `decision-pending`, do not drive or gate the story and write no sidecar: the open one is the record, and the skills, refused-write and turn-ceiling routes in this file each write `escalation-<story_id>.json` and would overwrite it. Attended, show the sidecar's `kind` and `decision_needed`, offer `/ucg-resolve`, and continue only once a fresh `--assert-armed` call no longer reads `decision-pending`. Headless, or when the operator leaves it open, end the invocation `blocked` as `references/gate.md`'s `escalate` does, handing the block's `escalation.blocker` to the headless adapter as the one blocker, so the envelope's `reason` names the sidecar. Two states never set the route: `handoff`, a `story-decomposed` or `defined-not-driven` sidecar, which hands this invocation work to pick up rather than a decision (an `operator-evidence-owed` sidecar is not one of them: `scripts/drive_epic.py` reports it as a handoff, but re-driving the story cannot record the evidence an operator owes, so it routes `decision-pending` until `/ucg-resolve` closes it); and `closed`, a sidecar whose id `/ucg-resolve` already closed, the residue of an answered decision that `/ucg-resolve` would not offer again.
21
+ **A re-entry story with an open escalation is not re-entered.** The `story` block also reports `escalation`: `null` when no `escalation-<story_id>.json` exists, and otherwise its `state`. It reads `open` when the sidecar is on disk and the id `/ucg-resolve` keys its answer by (`red_ids.py`'s, minted from the sidecar's own `kind`, `source` and `decision_needed`; a close keyed by the sidecar file's own path, as earlier passes keyed some, counts too) is not closed in `.decisions.json`, or when the sidecar cannot be read or no id can be minted from its fields, and the route is then `decision-pending`, ahead of the other three. `/ucg-resolve` deletes the sidecar when it closes the decision and leaves it in place on a `defer`, so a sidecar still on disk is a decision nobody closed: an answer written anywhere else (the story file, a ruling, the ledger) has not closed it. On `decision-pending`, do not drive or gate the story and write no sidecar: the open one is the record, and the skills, Claude Code version, refused-write and turn-ceiling routes in this file each write `escalation-<story_id>.json` and would overwrite it. Attended, show the sidecar's `kind` and `decision_needed`, offer `/ucg-resolve`, and continue only once a fresh `--assert-armed` call no longer reads `decision-pending`. Headless, or when the operator leaves it open, end the invocation `blocked` as `references/gate.md`'s `escalate` does, handing the block's `escalation.blocker` to the headless adapter as the one blocker, so the envelope's `reason` names the sidecar. Two states never set the route: `handoff`, a `story-decomposed` or `defined-not-driven` sidecar, which hands this invocation work to pick up rather than a decision (an `operator-evidence-owed` sidecar is not one of them: `scripts/drive_epic.py` reports it as a handoff, but re-driving the story cannot record the evidence an operator owes, so it routes `decision-pending` until `/ucg-resolve` closes it); and `closed`, a sidecar whose id `/ucg-resolve` already closed, the residue of an answered decision that `/ucg-resolve` would not offer again.
22
22
 
23
23
  **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.
24
24
 
@@ -52,7 +52,7 @@ Record the split in `.decision-log.md`: the parent, the children in order, and w
52
52
  uv run {skill-root}/scripts/story_sizing.py --parent '<the parent row's key>' --record {workflow.implementation_artifacts} --parent-acs '<the parent row's ACs>' --child '<child-row-id>=<ACs it claims>' --child '…' --tasks <n> --turn-ceiling {workflow.max_turns_per_story}
53
53
  ```
54
54
 
55
- It exits 0 when the map reconciles and 1 when it does not, printing `unclaimed`, `double_claimed` and `unknown_claims` (an AC no parent row owns) either way, and **a non-zero exit means the split is wrong and must be fixed before the child rows are written**, not a warning to log past. Called without `--child` before the split it does the sizing half only, returning `ratio` (the criteria count over the ceiling) and `implausible` against the same threshold this section states, and it says `reconciled: false` rather than reporting a clean claim map it never checked. The judgment stays here: `implausible` is an override in both directions with a recorded reason, and which child owns which AC is an authoring decision the script never makes.
55
+ It exits 0 when the map reconciles and 1 when it does not, printing `unclaimed`, `double_claimed` and `unknown_claims` (an AC no parent row owns) either way, and **a non-zero exit means the split is wrong and must be fixed before the child rows are written**, not a warning to log past. Before the split, call it with no `--child`, `--parent` or `--record`: `uv run {skill-root}/scripts/story_sizing.py --parent-acs '<the row's ACs>' --tasks <n> --turn-ceiling {workflow.max_turns_per_story}`. A `--record` with no `--child` is a usage error (exit 2), since a record needs children. That call does the sizing half only, returning `ratio` (the criteria count over the ceiling) and `implausible` against the same threshold this section states, and it says `reconciled: false` rather than reporting a clean claim map it never checked. The judgment stays here: `implausible` is an override in both directions with a recorded reason, and which child owns which AC is an authoring decision the script never makes.
56
56
 
57
57
  **The reconciling run records the split.** With `--parent` and `--record`, a run that exits 0 also writes `.split-<the parent row's key>.json` into the directory `--record` names: the parent, its children in the order given, and the claim map. It is the only evidence of the split the Epic-level `--rollup` reads, which reads the parent through its children's gates on it and refuses the parent without it (`references/gate.md`), so the record goes beside the `sprint-status.yaml` the Epic gate is given: `{workflow.implementation_artifacts}`, or on a flag-only isolated track (`references/ingest-and-scope.md` rule 6) the isolated track's own directory. Pass the sprint-status keys byte for byte, the parent's and each child's, once each, with the children in the order their rows take. A failing run writes no record and leaves an earlier one as it was. Exit 2 is a usage error with no record written: a `--child` row given twice, a record asked for with no `--parent-acs` or a child that claims none, a parent that is also a child, a missing directory, or a record the script cannot write. The sizing call before the split leaves both flags off, since a record needs children. A parent split before the record existed gets one the same way: one reconciling run for that split, with both flags.
58
58
 
@@ -160,7 +160,7 @@ One object, never an array: the file is already named per story, so a list would
160
160
 
161
161
  `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). So is `coupled-stories`: the earlier of two stories that are green only together owes clauses only the later story's build satisfies, and moving them narrows its AC, which only the operator may rule on (the story loop's "Two stories green only together").
162
162
 
163
- **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.
163
+ **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}`; Finalize's run report carries it. The note records the turns the drive spent, and never says a row of this shape should be split: sizing reads a row's criteria, never its turns ("Sizing: a story too large to drive" above), and the turns follow how the drive waited. **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.
164
164
 
165
165
  **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.
166
166
 
@@ -117,9 +117,9 @@ The delegation is hard time-boxed by the `timeout 300` wrapper above and is **no
117
117
 
118
118
  ## Record the terminal run-status
119
119
 
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).
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 it did not have. **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.
122
+ A run that stopped on an `evidence-commit-rejected` escalation keeps the verdict that story advanced on (`advance`, or `defer`) 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
123
 
124
124
  ## Surface the deferred-work ledger
125
125
 
@@ -55,7 +55,7 @@ The new commit is now the commit under assessment: the worktree is rebuilt at it
55
55
 
56
56
  - A row reads killed when it is `KILLED`, `KILLED+others`, or `MISATTRIBUTED` with the detail that its `expect_red` never appears beside a failure token. In each, something the row's command runs failed under the mutant, and a test a re-loop added under a name other than the row's `expect_red` reads `MISATTRIBUTED` that way.
57
57
  - A row that reads `GREEN` is still a gap unless it reads killed when re-run once more with its `command` replaced by the test command of the story's full sweep that covers its `file`, cache-defeated, as step 2 of "When automate backfills" runs it: a row's own command can select only the tests that existed when the row was written, so it misses a killing test a re-loop added in another file. When the second run reads killed, the row reads killed. When it reads `GREEN`, or cannot run (the next bullet), the row is still a gap, read by its first run: a second run that cannot run is no reason to measure the gap afresh. Automate makes that second run in the same pass, for each row it runs that reads `GREEN`, so when you delegate it, tell it to, and to record both results beside the row in its summary.
58
- - A row cannot run when it reads `STALE`, `NOT UNIQUE` or `UNDECODABLE` (its file or its anchor no longer holds, so nothing was mutated), or `MISATTRIBUTED` with the detail that the output's own count says 0 failed (a collection or harness error, not a test: a mutant reads this way when pytest then cannot collect a test module or class or load a conftest.py, or jest, vitest or Node's test runner cannot load a test file, since no test in that file or class runs, or when a Node test file's process exits non-zero after the row's test passes or is skipped, and no other test fails; a Node test file's process that exits or crashes during a test, before Node reports the row's test, still reads as a kill, since the row's `expect_red` then never appears beside a failure token, though it can read 0 failed when a test of the same name passes or is skipped in a file Node lists before it, or when the last thing Node prints for that file is an uncaught error that a child process printed), or `MISATTRIBUTED` with the detail that no test ran (a harness error too: the runner stopped before any test because it could not start its web server, its port taken, by a server an earlier run left up among others, or its start command failing, whether or not the mutant made it fail), or when `mutate_check.py` refuses its table with exit 2 (no row ran). A row whose command runs through a server the gate set reuses, and whose mutated file that server would load, cannot run either, even when the worktree's own processes load that file too, whatever `mutate_check.py` prints, and the two bullets above do not read it ("A server the gate set reuses does not follow the commit", under "Measure the commit, not the working tree"): that server serves the tree it was started from and never the mutant, so whatever the run reads, its `GREEN` is no gap and its red no kill, no test is backfilled for it, no `unkilled` line is logged from it and no line closes on it. It measures nothing, so its line stays open, and the pass measures that gap afresh, once in the pass: when a row it writes for the gap then cannot run either, it measures that gap no further, and logs the gap's line as `unmeasured`, in place of a summary, for the story's next automate pass to measure.
58
+ - A row cannot run when it reads `STALE`, `NOT UNIQUE` or `UNDECODABLE` (its file or its anchor no longer holds, so nothing was mutated), or `MISATTRIBUTED` with the detail that the output's own count says 0 failed (a collection or harness error, not a test: a mutant reads this way when pytest then cannot collect a test module or class or load a conftest.py, or jest, vitest or Node's test runner cannot load a test file, since no test in that file or class runs, or Node's test runner cannot run its global setup, since no test runs at all, or when a Node test file's process exits non-zero after the row's test passes or is skipped, or reports that a test generated asynchronous activity after it ended, whatever test that names, and no other test fails; a Node test file's process that exits or crashes during a test, before Node reports the row's test, still reads as a kill, since the row's `expect_red` then never appears beside a failure token, though it can read 0 failed when a test whose name holds the row's `expect_red` passes or is skipped in that file before the process dies or in a file Node lists before it, when that file reports such asynchronous activity before the process dies, or when the last thing Node prints for that file is an uncaught error that a child process printed; Node prints a test file whose process exits non-zero after all its tests pass as it prints one whose process dies during a test, so such a file whose lines report no pass of a test whose name holds the row's `expect_red` reads as that death, and the row as a kill though no test went red, and when you delegate automate, tell it to write each Node row's `command` to run only the test file that holds the row's test, though a row's second run, through the full sweep, can still read so; a module that calls `process.exit` while a Node test file loads, or that kills its process then by filling the heap or by a signal, stops the file loading, yet Node reports it as it reports a process that exits or crashes during the file's first test, so it reads as that kill does, and when you delegate automate, tell it to write no replacement that makes a module exit, fill the heap or raise a signal while a Node test file loads; and in output that interleaves the lines of several runs with no task-runner prefix to tell them apart, a Node test file that cannot load, or whose process exits non-zero after the row's test passes, can still read as a kill), or `MISATTRIBUTED` with the detail that no test ran (a harness error too: the runner stopped before any test because it could not start its web server, its port taken, by a server an earlier run left up among others, or its start command failing, whether or not the mutant made it fail), or when `mutate_check.py` refuses its table with exit 2 (no row ran). A row whose command runs through a server the gate set reuses, and whose mutated file that server would load, cannot run either, even when the worktree's own processes load that file too, whatever `mutate_check.py` prints, and the two bullets above do not read it ("A server the gate set reuses does not follow the commit", under "Measure the commit, not the working tree"): that server serves the tree it was started from and never the mutant, so whatever the run reads, its `GREEN` is no gap and its red no kill, no test is backfilled for it, no `unkilled` line is logged from it and no line closes on it. It measures nothing, so its line stays open, and the pass measures that gap afresh, once in the pass: when a row it writes for the gap then cannot run either, it measures that gap no further, and logs the gap's line as `unmeasured`, in place of a summary, for the story's next automate pass to measure.
59
59
 
60
60
  A line closes when an automate pass at a later commit than the one the line names finds every row behind it reading killed: the line's own rows, re-run, or for an `unmeasured` line or one whose rows cannot run, the rows that pass writes when it measures the gap afresh, any test it backfills for them included. That pass's cycle leaves the line out. A carried line that pass does not close is logged afresh in place of the copied line, naming this commit and this pass's summary, or `unmeasured` while the risk still is or the gap's rows still cannot run, or `unkilled`, naming its test, while a test backfilled for the gap has not killed its rows. A `gate-gap:` line never changes the route the verdict takes, and each route treats the open lines this way:
61
61
 
@@ -71,12 +71,12 @@ Stage 5's subject is a COMMIT, but an assessor that runs or times anything by de
71
71
 
72
72
  - **Dependency directories do not follow the commit.** A worktree carries tracked files only, so an installed dependency tree (`node_modules` and its kin) is absent there. Link each such directory the repo has (root *and* nested) from the main tree into the worktree with `uv run {skill-root}/scripts/link_worktree_deps.py --project-root {project-root} --worktree <tmp-path>`, which links every `node_modules` folder (`--dir <path>`, repeatable, names a dependency folder of another name instead) and prints what it linked, skipped and failed. Never a bare `ln -s`: it is not a command `acceptEdits` runs without asking, nor on the allowlist, so an unattended gate would have it refused, where the script runs under the allowlisted `uv run`. And prefer the symlink over resolver environment variables: Node's ESM resolver ignores `NODE_PATH` (it is honoured by the CJS resolver only), so a `NODE_PATH` bridge quietly breaks exactly the modern half of a JS gate set. Where a symlink cannot serve, an offline install from the package manager's shared store is the fallback; measure both once per repo before committing to one.
73
73
  - **Untracked inputs the gate set reads.** A scratch browser config, an env file, a generated fixture: enumerate what the declared gate commands actually read that the commit does not carry, and copy those in deliberately — an isolated gate that silently lost its config measures a different harness and reports the result as this one's.
74
- - **A server the gate set reuses does not follow the commit.** A test runner that attaches to a server already answering at its URL, instead of starting one (Playwright's `webServer` entry with `reuseExistingServer` true, or `!process.env.CI` outside CI, the form TEA's framework scaffold writes), runs the worktree's tests against the tree that server was started from, usually the main tree: a browser run from the worktree measures that tree's source, and a mutation written into the worktree never reaches it. Read each runner config the declared gate commands load, list each URL it may reuse (`http://localhost:<port>` for an entry that gives only a port), and check them before the first run in the worktree and again after the rebuild, with `uv run {skill-root}/scripts/probe_servers.py --url <url>` (`--url` repeatable), which prints which of them answer and, where the system lets it read one, the folder the server that answered each runs from. When none answers, the runner starts its own server from the worktree, and that server can stay up: the runner stops only the process group its start command runs in, so a server that a launcher such as turbo runs in a group of its own outlives the run that started it and keeps the port, and with reuse on every later run reuses it, a mutation row's included, while it serves the files as they were when it started. So when you delegate automate, have it check them the same way before and after each `mutate_check.py` table it runs, and name in its summary each URL that answers at one of those checks: that is a server the gate set reuses, whoever started it, one a run in the worktree left up included, and with reuse on each row of a table after which it answers ran through it. A server that answers is not the gate's to stop. When the runner config lets the worktree's runs have their own server without editing a tracked file, give them one, whether or not a server answers: a scratch runner config, copied in like the inputs above, that loads the project's own and moves each reused server, its start command and its URL, to a port the probe reports free, with reuse turned off and the base URL pointed at that port. The runner takes it by its config flag (`--config <file>` for Playwright), never by an environment variable set in front of the command, which the command's allow rule does not match past. Tell every assessor to run the runner with it, a mutation row's `command` included, so that each run starts a server from the worktree. Each run then needs that port free: with reuse off, a run that finds it taken stops before any test runs, and a server an earlier run left up keeps it. So give the scratch config a start command that runs the server in the process group the runner stops, where the project has one (the package's own dev script rather than a task runner's), check its URLs with the same probe before each assessor starts, moving each one that answers to a port the probe reports free, and run no two assessors under it at once. Have automate check its URLs at the same points, before and after each table, and move a port that answers before it runs the next one. A row whose run stopped because the runner could not start its web server reads as one that cannot run, by the detail `mutate_check.py` gives it, that no test ran ("A reported gap stays open until a later pass measures it closed"). No other stop before any test gets that detail: a run Playwright stops because it could not load a spec, a support file or its config reads as a kill, since the row's `expect_red` never appears beside a failure token, so tell automate, too, to write no replacement that stops such a file loading. Otherwise tell every assessor, automate included, in its brief, which URL answers and, when the probe read it, from which folder, that a browser run through it measures the source of the tree that server was started from (the commit's only while that folder is in the main tree, the main tree's `HEAD` is the commit under assessment and no file the server loads differs from it), and that no mutation in the worktree reaches it. Tell automate, too, that it writes no mutation row whose command runs through that server and whose mutated file that server would load, even when the worktree's own processes load that file too (a spec that reads its expected value from it, say): it measures such a risk with a row whose command does not go through that server (a unit or component test that loads the file in its own process), or whose mutated file that server does not load (a spec or a support file the runner loads from the worktree), and a risk on a P0 criterion that no such row can measure is one it leaves unmeasured ("A risk automate names on a P0 criterion is measured in the same pass", under "Backfill the gate evidence"). Any such row it runs, one behind a carried `gate-gap:` line or a previous backfill included, is a row that cannot run, whatever `mutate_check.py` prints ("A reported gap stays open until a later pass measures it closed" says how such a row is read): what it reads measures the server's tree and not the mutant, so its `GREEN` is no gap and its red no kill, no test is backfilled for it and no `unkilled` line is logged from it.
74
+ - **A server the gate set reuses does not follow the commit.** A test runner that attaches to a server already answering at its URL, instead of starting one (Playwright's `webServer` entry with `reuseExistingServer` true, or `!process.env.CI` outside CI, the form TEA's framework scaffold writes), runs the worktree's tests against the tree that server was started from, usually the main tree: a browser run from the worktree measures that tree's source, and a mutation written into the worktree never reaches it. Read each runner config the declared gate commands load, list each URL it may reuse (`http://localhost:<port>` for an entry that gives only a port), and check them before the first run in the worktree and again after the rebuild, with `uv run {skill-root}/scripts/probe_servers.py --url <url>` (`--url` repeatable), which prints which of them answer and, where the system lets it read one, the folder the server that answered each runs from. When none answers, the runner starts its own server from the worktree, and that server can stay up: the runner stops only the process group its start command runs in, so a server that a launcher such as turbo runs in a group of its own outlives the run that started it and keeps the port, and with reuse on every later run reuses it, a mutation row's included, while it serves the files as they were when it started. So when you delegate automate, have it check them the same way before and after each `mutate_check.py` table it runs, and name in its summary each URL that answers at one of those checks: that is a server the gate set reuses, whoever started it, one a run in the worktree left up included, and with reuse on each row of a table after which it answers ran through it. A server the run itself started is the run's to stop, and no other server is. `references/execute.md` step 5 re-runs the full sweep, browser tests included, in the main tree right before the gate, so a server its runner started through a launcher can still answer at the first check, from the main tree, and the worktree's runs would reuse it. So run the probe at every check this caveat names, automate's included, with the stop flags added: `--stop-since {workflow.implementation_artifacts}/.baseline-<story_id> --root {project-root} --root <tmp-path>`. The probe then stops a server that answers only when it reads as one this run left up: every process in the server's process group is this user's, has no controlling terminal and started after the story's baseline marker was written, the process that led its session has exited, as a runner's start command has once the runner ends, no other process that still runs in that session started before that marker or is the parent of a process in the group, as a watcher that can start the server again is, and the server runs from inside one of those folders. Those are signs, not proof: a server the operator started inside the project after that marker, in the background with no terminal or from a terminal since closed, with nothing older than the marker still running in its session, reads the same way, and so does one that a watcher of the operator's restarts after the marker, when the watcher too started after it and runs in the server's process group, or starts the server through a command that then exits and either started after the marker or had that command give the server a session of its own. A resume keeps that marker, so a server an earlier session of the story started counts. The probe lists each server it stopped under `stopped`. Have automate name in its summary each server the probe stopped at one of its checks, before a table or after one, by the `url` and `cwd` of its `stopped` entry, since only its summary can tell you of those stops. At automate's check after a table, a URL whose server the probe stopped still counts as one that answers there, since with reuse on the table's rows ran through that server. It leaves every other server up and lists it under `left` with its reason, and on a system without Linux's `/proc` it stops nothing. A server the probe leaves up is not the gate's to stop: never stop it any other way, since it may be the operator's own. When the runner config lets the worktree's runs have their own server without editing a tracked file, give them one, whether or not a server answers: a scratch runner config, copied in like the inputs above, that loads the project's own and moves each reused server, its start command and its URL, to a port the probe reports free, with reuse turned off and the base URL pointed at that port. The runner takes it by its config flag (`--config <file>` for Playwright), never by an environment variable set in front of the command, which the command's allow rule does not match past. Tell every assessor to run the runner with it, a mutation row's `command` included, so that each run starts a server from the worktree. Each run then needs that port free: with reuse off, a run that finds it taken stops before any test runs, and a server an earlier run left up keeps it. So give the scratch config a start command that runs the server in the process group the runner stops, where the project has one (the package's own dev script rather than a task runner's), check its URLs with the same probe before each assessor starts, moving each one that still answers to a port the probe reports free, and run no two assessors under it at once. Have automate check its URLs at the same points, before and after each table, and move a port that still answers before it runs the next one. Once the cycle's last test run has finished, a backfill sweep's in the main tree included, and before you log the cycle's verdict, run the probe with the stop flags once more over every URL the gate set may reuse and every URL of the scratch config, so that no server this story's runs left up outlives its gate: over an Epic they would pile up, each holding a port. Run it before the verdict, not after: a story whose verdict is not logged is gated again under the same marker, and that gate's checks stop what an ended session left up, but a server still up once the story has advanced started before the next story's marker, so no later check stops it. A row whose run stopped because the runner could not start its web server reads as one that cannot run, by the detail `mutate_check.py` gives it, that no test ran ("A reported gap stays open until a later pass measures it closed"). No other stop before any test gets that detail: a run Playwright stops because it could not load a spec, a support file or its config reads as a kill, since the row's `expect_red` never appears beside a failure token, so tell automate, too, to write no replacement that stops such a file loading. Otherwise tell every assessor, automate included, in its brief, which URL answers and, when the probe read it, from which folder, that a browser run through it measures the source of the tree that server was started from (the commit's only while that folder is in the main tree, the main tree's `HEAD` is the commit under assessment and no file the server loads differs from it), and that no mutation in the worktree reaches it. Tell automate, too, that it writes no mutation row whose command runs through that server and whose mutated file that server would load, even when the worktree's own processes load that file too (a spec that reads its expected value from it, say): it measures such a risk with a row whose command does not go through that server (a unit or component test that loads the file in its own process), or whose mutated file that server does not load (a spec or a support file the runner loads from the worktree), and a risk on a P0 criterion that no such row can measure is one it leaves unmeasured ("A risk automate names on a P0 criterion is measured in the same pass", under "Backfill the gate evidence"). Any such row it runs, one behind a carried `gate-gap:` line or a previous backfill included, is a row that cannot run, whatever `mutate_check.py` prints ("A reported gap stays open until a later pass measures it closed" says how such a row is read): what it reads measures the server's tree and not the mutant, so its `GREEN` is no gap and its red no kill, no test is backfilled for it and no `unkilled` line is logged from it.
75
75
  - **The ordering rule stands.** Isolation removes the contamination, not the sequence: the run still gates story N to a verdict before touching story N+1 (the sequential spine is unchanged), so this section licenses no overlap. What the worktree buys is that no stray tree state, the next remediation's included, can contaminate a gate mid-read. It does not keep the assessors apart, since they all measure the one worktree: that comes from the order "Backfill the gate evidence" sets, where automate, the one assessor that edits source, runs alone and the worktree is rebuilt before any other assessor starts. The assessors after it only read, run and time, so none of them changes the tree another one measures. They still share one machine, so a timing one of them takes beside another's runs carries the load caveat `references/execute.md` gives a wide sweep.
76
76
 
77
77
  **Rebuild the worktree once automate has finished (production).** Automate's mutation runs edit source in the worktree, and it puts there a copy of each test it backfills to confirm the test ("A backfill is confirmed in the pass that writes it" above), so before any other assessor starts, replace the worktree instead of trusting it: remove it with `git worktree remove --force <tmp-path>`, add it again with `git worktree add <tmp-path> <commit>` at the commit under assessment (the backfill's commit when automate made one, per "When automate backfills" above), then link the dependency folders with the same `link_worktree_deps.py` call and copy the same untracked inputs in again, exactly as the first setup did. Then check the URLs the gate set may reuse again ("A server the gate set reuses does not follow the commit" above), and act on what it finds, as that caveat says, before trace, NFR and test review start: a server may have started since the first check, one started from the old worktree among them, which outlives the worktree's removal. A worktree just added from the commit holds that commit's tracked files and nothing a mutation or a copied test left behind (a backfilled test the backfill commit carries is one of those tracked files), and the rebuild needs no status read of the old worktree, which would take `git -C <tmp-path> status`, a command no allowlist entry covers. Rebuild whether or not automate backfilled, and whether this session ran the pass or a resume reused it ("A summary already at that name is this cycle's own" above); skip the rebuild only when no automate pass ran in this cycle (`--light`, or a later cycle that skips it), or when a red backfill sweep ended the cycle before trace, so that no other assessor runs in it.
78
78
 
79
- Record in `.decision-log.md`, once per gated story, whether the gate measured a worktree or the main tree: the same honesty line the sweep's `scope=` carries, since an assessment reported as isolated that actually ran on the shared tree is a false claim about the evidence. In production the line also says whether automate ran alone and the worktree was rebuilt before the other assessors started, and names the commit it was rebuilt at. When a runner reused a server the gate did not start, or one a run in the worktree left up, the line also names its URL, the folder it ran from when the probe could read one, and what it left unmeasured.
79
+ Record in `.decision-log.md`, once per gated story, whether the gate measured a worktree or the main tree: the same honesty line the sweep's `scope=` carries, since an assessment reported as isolated that actually ran on the shared tree is a false claim about the evidence. In production the line also says whether automate ran alone and the worktree was rebuilt before the other assessors started, and names the commit it was rebuilt at. When a runner reused a server the gate did not start, or one a run in the worktree left up, the line also names its URL, the folder it ran from when the probe could read one, and what it left unmeasured. It also names each server the probe stopped, by its URL and the folder it ran from, those automate's summary names included, since a server the operator started can read as one the run left up.
80
80
 
81
81
  ## Non-web stack: the red phase by hand, and the trace artifacts where trace cannot run
82
82
 
@@ -163,7 +163,7 @@ Resolve `{nfr-assessment.md}` and `{test-review.md}` to the paths TEA wrote them
163
163
 
164
164
  Do not recompute TEA thresholds or re-judge `gate_status` — read it as given. The script already ANDs the production signals (an `advance` is downgraded to `reloop` if `nfr-assessment.md` overallStatus is FAIL, or `test-review.md` score < 80 or recommendation is Block). Record the full verdict JSON and its `reasons` in `.decision-log.md` for this story.
165
165
 
166
- **Head each gate cycle's entries with the story's key.** Before a gate cycle logs anything in `.decision-log.md` (in production, before the `gate-automate:` line "Backfill the gate evidence" logs ahead of automate), write the heading `### Story <story_id>: gate` on a line of its own, with `<story_id>` the sprint-status key copied verbatim, as `--story` takes it. Write it again before each later cycle of the story, a re-gate included. Under it, log the cycle's verdict JSON as a fenced JSON object on lines of its own, as a red backfill sweep logs its re-loop. `scripts/gate_trail.py` reads the verdict the run acted on from the first JSON object carrying `verdict` after such a heading, fenced or inline in backticks, and never from one carrying `"epic_level": true`, the Epic-level gate's roll-up, or from one whose `reasons` say it read another story's gate file. The heading's entries run to the next heading the trail reads as a story's: one in this shape, one whose id after `Story` starts with a digit, or one whose id is a key `sprint-status.yaml` lists, so a prose heading such as `### Story order` ends none. A later heading in this shape for the story replaces what an earlier one's entries recorded, even when no verdict object follows it, so the story's last cycle decides: when the trail cannot read that cycle's verdict, it shows the gate artifact's status, mapped, never an earlier cycle's verdict. A later heading of another shape for the story (`### Story <story_id>: re-loop 1`) is no cycle: it replaces that verdict only with a verdict object of its own, so a re-loop's notes never turn a downgraded or capped `reloop` into the gate artifact's mapped `advance`. A heading the trail does not read as a story's leaves its verdict objects in the previous story's entries, so a heading that starts with `Story` and a digit names a story key, never a position such as `Story 2 of 5`.
166
+ **Head each gate cycle's entries with the story's key.** Before a gate cycle logs anything in `.decision-log.md` (in production, before the `gate-automate:` line "Backfill the gate evidence" logs ahead of automate), write the heading `### Story <story_id>: gate` on a line of its own, with `<story_id>` the sprint-status key copied verbatim, as `--story` takes it. Write it again before each later cycle of the story, a re-gate included. Under it, log the cycle's verdict JSON as a fenced JSON object on lines of its own, as a red backfill sweep logs its re-loop. `scripts/gate_trail.py` reads the verdict the run acted on from the first JSON object carrying `verdict` after such a heading, fenced or inline in backticks, and never from one carrying `"epic_level": true`, the Epic-level gate's roll-up, or from one whose `reasons` say it read another story's gate file. The heading's entries run to the next heading the trail reads as a story's: one in this shape, one whose id after `Story` starts with a digit, or one whose id is a key `sprint-status.yaml` lists, so a prose heading such as `### Story order` ends none. A later heading in this shape for the story replaces what an earlier one's entries recorded, even when no verdict object follows it, so the story's last cycle decides: when the trail cannot read that cycle's verdict, it shows the gate artifact's status, mapped, never an earlier cycle's verdict. The trail reads a later heading for the story as a later cycle too when only its level differs (`## Story <story_id>: gate`), or when it says `re-gate` or `regate` for `gate` (`### Story <story_id>: re-gate`). The same holds when `gate` is followed by a cycle number (`2`, `#2` or `cycle 2`) after a blank, a comma, a semicolon, a colon or a dash, which a note in parentheses may follow (`### Story <story_id>: gate - cycle 2`), and when `gate` is followed by a note in parentheses that says `cycle` or `re-gate`, or holds only a number (`### Story <story_id>: gate (cycle 2)`). Any other text after `gate` makes the heading no cycle, a note that names no cycle included (`### Story <story_id>: gate (skipped)`), so write each cycle's heading in this shape. A later heading of another shape for the story (`### Story <story_id>: re-loop 1`) is no cycle: it replaces that verdict only with a verdict object of its own, so a re-loop's notes never turn a downgraded or capped `reloop` into the gate artifact's mapped `advance`. A heading the trail does not read as a story's leaves its verdict objects in the previous story's entries, so a heading that starts with `Story` and a digit names a story key, never a position such as `Story 2 of 5`.
167
167
 
168
168
  **The sweep-scope AND (`--tests-ran`, per-story gates, both profiles).** Pass `--tests-ran {workflow.implementation_artifacts}/.tests-ran-<story_id>` on every per-story gate, exactly as the commands above show. The script reads the marker's `scope=` line (`references/execute.md` steps 2 and 5 write it beside `baseline=`): `scope=full` asserts the green run behind this gate was the full three-axis sweep and passes the verdict through; `scope=scoped` is legitimate mid-loop evidence, so the verdict is **capped at `reloop`** — a story may only advance off a full-scope sweep, and the cap moves `defer` too, because defer's route advances the story. Fail-closed like every other signal: a missing marker, a marker with no `scope=` line, or a value the reader does not recognise all get the same cap, with a reason naming what was wrong. The verdict JSON carries the recognised value as `sweep_scope` so an advance that proved its sweep is distinguishable from one that was never asked. Two boundaries: the epic roll-up gates no sweep of its own, so `--epic-level` refuses the flag outright (an invocation error, exit 2 — the same lane as `--epic-level` with `--nfr`); and *omitting* the flag skips the check rather than failing it, deliberately — making omission failing would change the verdict of documented invocations that predate the flag, the exact 2.0.0 lesson `docs/_internal/STABILITY.md` records — so the always-pass-it rule lives here, in the instruction, and a per-story gate invoked without the flag is a drift to fix, not a laxer mode to use.
169
169
 
@@ -179,7 +179,7 @@ Do not recompute TEA thresholds or re-judge `gate_status` — read it as given.
179
179
 
180
180
  - **`advance`** (gate_status PASS or WAIVED) → the story passes (an operator-evidence AC still owed its evidence is parked on the ledger first, as `defer` below says). **Sync the story's row in `sprint-status.yaml` to `done` before moving on**: set `development_status[<story_id>]` to `done`, preserving the file's comments and key order, and log the transition in `.decision-log.md`. This write is the run's own, not a sub-skill's: `ucg-dev-story` leaves the row at `review`, and `bmad-code-review` (production only; it does not run under `--light` at all) writes `done` **only** when nothing was left as an action item, so a story that legitimately `defer`s a non-critical finding is left at `in-progress`. Every downstream reader keys on `done`: Stage 1's in-scope rule (`references/ingest-and-scope.md` rule 3), the Epic-level trigger in this very sentence, and `scripts/drive_epic.py`'s progress check. So an advanced story whose row still says `review` is an advanced story the next reader re-drives, and an Epic whose last story advanced without this write never satisfies the Epic-level condition below. Sync it here, at the one place the authoritative verdict is known. In the same write, move the Epic's own `epic-<id>` row from `backlog` to `in-progress` when it still reads `backlog` (never backward, and only when the key exists): `bmad-build` makes that move when a story starts, but the story skills this run delegates to skip it when handed an explicit story key, so without it a finished Epic still reads `backlog`. If the Stop hook left a turn-budget marker for this story (`{workflow.implementation_artifacts}/.escalation-<story_id>.md`) and its count is still at or past the ceiling, do **not** promote it: log the sizing note `references/execute.md` describes under "Promoting the turn-budget marker", and leave the marker in place.
181
181
 
182
- **Commit the gate's evidence before the next story starts.** The `done` sync, this story's trace and gate files (`trace-<id>.md`, `gate-decision-<id>.json`, `e2e-trace-summary-<id>.json`, and in production its per-story NFR assessment and test review), its live results file when it has an operator-evidence AC, this gate's ledger rows and the decision log (with the first story, also Stage 3's test-design output) are tracked state written after Execute's commit-at-green. While `.current-story` still names this story, stage those of these paths that exist and are not ignored, by explicit path, in one call, and commit them in a second, before the next story's step 0. For the story whose advance makes every story `done`, make this commit after the Epic-level gate below instead, so it also carries that gate's writes. The commit carries no source or test path, so the story's existing tests-ran marker covers it: reuse that marker as it stands and never rewrite it for this commit. A repo commit hook that rejects this commit is not `references/execute.md` step 4's case, whose rule for a hook rejection binds the story's own commits. Make a change the hook asks for only in a file the gate itself writes for this commit, `sprint-status.yaml` (its `done` sync) or `.decision-log.md`, then stage it and retry, with the marker as it stands, at most twice for this commit. When the hook asks for a change to any other path, such as a file TEA wrote (an edit there would make its provenance false) or a ledger row (the ledger schema below never rewrites one), or rejects the commit again after the second fix, commit nothing: log the rejection in `.decision-log.md`, write the typed escalation sidecar `escalation-<story_id>.json` (shape in `references/execute.md`, under "Escalation sidecar") with `kind` `evidence-commit-rejected` and a `decision_needed` that names the hook, its message, the paths left uncommitted and this run's id (so a rejection on a later run is a new decision, never one `/ucg-resolve` has closed already), write `.evidence-owed-<story_id>` beside it, listing those paths one per line, and stop before the next story's step 0, as the `escalate` route below stops. The story keeps its `advance` verdict, and its evidence stays staged for the commit a resume makes. Automate's backfill is not among its paths, because it was committed before trace ran ("When automate backfills", under "Backfill the gate evidence"). If it must carry an executable path all the same (a source or test file left uncommitted when trace ran, which this gate therefore never measured: log why), re-run the sweep and write a fresh marker per `references/execute.md` step 5 first. Then refresh `.commit-<story_id>` from `HEAD`, so this story's range in the gate trail includes the evidence commit. A path the project ignores is logged and left out, never forced in with `git add -f`; if nothing is staged, make no commit and leave `.commit-<story_id>` as it is. A resume that finds an advanced story's evidence still uncommitted makes this commit for it before the next story's step 0: point `.current-story` back at that story (its tests-ran marker still passes the guard), commit, and refresh its `.commit-<story_id>`. While that story's `evidence-commit-rejected` escalation is still open, the resume commits nothing and stops on it instead (`references/execute.md`'s resume rule says how it reads one); once `/ucg-resolve` has closed it, the resume makes the commit, under the hook rule above. Once the commit is made, remove `.evidence-owed-<story_id>`: `/ucg-resolve` deletes the sidecar when it closes the escalation, so the marker is what tells a resume, and Stage 1's already-done short-circuit, that the commit is still owed. A resume that finds the marker with the sidecar gone and none of the paths it lists staged or different from `HEAD` (`git diff --quiet HEAD -- <paths>` exits 0 for them) finds the evidence committed already, by the operator or by a run that stopped between its commit and this removal: log the commit that holds it and remove the marker, making no commit. On the story whose advance makes every story `done`, this commit follows the Epic-level gate, so the `epic-<id>` row that gate's `advance` wrote stays staged with the rest, and the run ends `blocked` on that escalation all the same, because its evidence is not committed (`references/finalize.md`). While `.evidence-owed-<story_id>` is on disk, Stage 1's already-done short-circuit does not end that Epic's resume (`references/ingest-and-scope.md`, rule 4), nor does `scripts/drive_epic.py` report the Epic `all-done`: the resume waits on the escalation while it is open, makes the commit once it is closed, and then goes to Finalize with the Epic-level verdict the log holds, without running that gate again. Then move to the next story.
182
+ **Commit the gate's evidence before the next story starts.** The `done` sync, this story's trace and gate files (`trace-<id>.md`, `gate-decision-<id>.json`, `e2e-trace-summary-<id>.json`, and in production its per-story NFR assessment and test review), its live results file when it has an operator-evidence AC, this gate's ledger rows and the decision log (with the first story, also Stage 3's test-design output) are tracked state written after Execute's commit-at-green. While `.current-story` still names this story, stage those of these paths that exist and are not ignored, by explicit path, in one call, and commit them in a second, before the next story's step 0. For the story whose advance makes every story `done`, make this commit after the Epic-level gate below instead, so it also carries that gate's writes. The commit carries no source or test path, so the story's existing tests-ran marker covers it: reuse that marker as it stands and never rewrite it for this commit. A repo commit hook that rejects this commit is not `references/execute.md` step 4's case, whose rule for a hook rejection binds the story's own commits. Make a change the hook asks for only in a file the gate itself writes for this commit, `sprint-status.yaml` (its `done` sync) or `.decision-log.md`, then stage it and retry, with the marker as it stands, at most twice for this commit. When the hook asks for a change to any other path, such as a file TEA wrote (an edit there would make its provenance false) or a ledger row (the ledger schema below never rewrites one), or rejects the commit again after the second fix, commit nothing: log the rejection in `.decision-log.md`, write the typed escalation sidecar `escalation-<story_id>.json` (shape in `references/execute.md`, under "Escalation sidecar") with `kind` `evidence-commit-rejected` and a `decision_needed` that names the hook, its message, the paths left uncommitted and this run's id (so a rejection on a later run is a new decision, never one `/ucg-resolve` has closed already), write `.evidence-owed-<story_id>` beside it, listing those paths one per line, and stop before the next story's step 0, as the `escalate` route below stops. The story keeps the verdict it advanced on (`advance`, or `defer`, whose route advances anyway), and its evidence stays staged for the commit a resume makes. Automate's backfill is not among its paths, because it was committed before trace ran ("When automate backfills", under "Backfill the gate evidence"). If it must carry an executable path all the same (a source or test file left uncommitted when trace ran, which this gate therefore never measured: log why), re-run the sweep and write a fresh marker per `references/execute.md` step 5 first. Then refresh `.commit-<story_id>` from `HEAD`, so this story's range in the gate trail includes the evidence commit. A path the project ignores is logged and left out, never forced in with `git add -f`; if nothing is staged, make no commit and leave `.commit-<story_id>` as it is. A resume that finds an advanced story's evidence still uncommitted makes this commit for it before the next story's step 0: point `.current-story` back at that story (its tests-ran marker still passes the guard), commit, and refresh its `.commit-<story_id>`. While that story's `evidence-commit-rejected` escalation is still open, the resume commits nothing and stops on it instead (`references/execute.md`'s resume rule says how it reads one); once `/ucg-resolve` has closed it, the resume makes the commit, under the hook rule above. Once the commit is made, remove `.evidence-owed-<story_id>`: `/ucg-resolve` deletes the sidecar when it closes the escalation, so the marker is what tells a resume, and Stage 1's already-done short-circuit, that the commit is still owed. A resume that finds the marker with the sidecar gone and none of the paths it lists staged or different from `HEAD` (`git diff --quiet HEAD -- <paths>` exits 0 for them) finds the evidence committed already, by the operator or by a run that stopped between its commit and this removal: log the commit that holds it and remove the marker, making no commit. On the story whose advance makes every story `done`, this commit follows the Epic-level gate, so the `epic-<id>` row that gate's `advance` wrote stays staged with the rest, and the run ends `blocked` on that escalation all the same, because its evidence is not committed (`references/finalize.md`). While `.evidence-owed-<story_id>` is on disk, Stage 1's already-done short-circuit does not end that Epic's resume (`references/ingest-and-scope.md`, rule 4), nor does `scripts/drive_epic.py` report the Epic `all-done`: the resume waits on the escalation while it is open, makes the commit once it is closed, and then goes to Finalize with the Epic-level verdict the log holds, without running that gate again. Then move to the next story.
183
183
 
184
184
  When **every story of the Epic is `done`**, run the Epic-level gate: pass the epic's own id via `--story`, **add `--epic-level`**, and read its `gate_status` **only**. TEA produces NFR and test-review **per story, not per epic**, so there is no epic-level aggregate to AND, and every story's own production gate already ANDed its signals before reaching `done`. With `--rollup` the epic id is the sprint-status grouping key and the verdict is a computation over the per-story record; only in the omit-`--rollup` fallback is `--story` resolved against an epic-named artifact (scoped per the `--story` note above) and the roll-up a pure trace read. When the Epic-level gate returns `advance`, or `defer` (whose route advances anyway), set the `epic-<id>` row to `done` (when the key exists), preserving comments and key order, log it, and carry it in the last story's evidence commit. BMAD Method 6.12 has no other writer of an epic row's `done`, and `bmad-retrospective` writes only the `epic-<id>-retrospective` row. Never write it on any other route: the work bound, `partial-complete`, a handoff, a block or an escalation.
185
185
 
@@ -84,8 +84,8 @@ Log each supersession to `.decision-log.md`.
84
84
 
85
85
  **A refused settings write.** The disarm above and step 5's arming both write `{project-root}/.claude/settings.local.json`, which Claude Code treats as a protected path. Under Auto Mode, which the hard gate requires, the permission classifier reviews that write: it may refuse it as self-modification, or let it land and then refuse the calls that follow it. In a headless session nobody can approve either refusal. A refused write of a disarm the pass does not need (the paragraph above) is no stop: skip that disarm, log it, and go on. Treat any other refusal of the write, or of any call after it until the assertion that write serves has passed, as a stop. Do not retry it through another tool, script, encoding or subagent; do not delete or restore the file; do not forge a marker; do not skip the step-5 assertion; and do not progress. Log the refused action verbatim, the file's state (written or not, asserted or not) and the current branch to `.decision-log.md`. Then:
86
86
 
87
- - **Attended:** show the operator the exact content the write was meant to apply, and ask them to approve it (under `/permissions`, on its Recently denied tab) or make the edit themselves. Then re-run the assertion that write served: `preflight_check.py --assert-armed` after arming, or, after a disarm, the check that no hook `command` names either script. A refused **disarm** has one more route. Hand the operator one `!`-prefixed command that stages the named remediation paths and commits them on the current branch, with no push. A `!` command runs outside the PreToolUse hooks, so the commit needs no disarm and the hooks stay armed. Record it as an operator-run deviation, then re-run step 1. Offer this route only after confirming the current branch is `{workflow.epic_branch_prefix}<epic-id>`, and only for a remediation commit made before Execute. If the operator neither approves nor makes the write (nor runs that command, for a disarm), the run stops here: remove this run's recall latch first, with the unlatch command at the end of step 4, as every stop before Finalize does.
88
- - **Headless:** record a **RED** blocker naming the refused write and the operator action that clears it (an attended pass that approves or makes the write), and stop through step 4's blocked exit. The way back is that attended pass, not `/ucg-resolve`.
87
+ - **Attended:** show the operator the exact content the write was meant to apply, and ask them to approve it (under `/permissions`, on its Recently denied tab) or make the edit themselves. Then re-run the assertion that write served: `preflight_check.py --assert-armed` after arming, or, after a disarm, the check that no hook `command` names either script. A refused **disarm** has one more route. Hand the operator one command, to run in a terminal outside this session, that stages the named remediation paths and commits them on the current branch, with no push. A command run there is no tool call, so no PreToolUse hook reads it: the commit needs no disarm and the hooks stay armed. Do not offer it as a `!` command in the session: Claude Code's docs say a `!` command runs without going through Claude, but not whether the PreToolUse hooks see it. Record it as an operator-run deviation, then re-run step 1. Offer this route only after confirming the current branch is `{workflow.epic_branch_prefix}<epic-id>`, and only for a remediation commit made before Execute. If the operator neither approves nor makes the write (nor runs that command, for a disarm), the run stops here: remove this run's recall latch first, with the unlatch command at the end of step 4, as every stop before Finalize does.
88
+ - **Headless:** record a **RED** blocker naming the refused write and the operator action that clears it (an attended pass that approves or makes the write), and stop through step 4's blocked exit. The way back is that attended pass, not `/ucg-resolve`. A resume never reaches this stage: when its hooks need re-arming and the write is refused in a headless session, it escalates the story it was about to drive instead (`references/execute.md`, the re-assertion sweep), and its way back is an attended resume that makes the write, with `/ucg-resolve` closing that escalation.
89
89
 
90
90
  **Ordering.** `git_branch` → the `git_clean` clear (the branch has to exist before a remediation commit lands, per its bullet) and framework → ci (the CI scaffold halts without a framework, as its bullet states) are both load-bearing, as is the stale-hook disarm above, which must precede any remediation commit. While `git_unborn` stands, no remediation that writes to the tree runs at all, the branch and the `git_clean` clear included, as its bullet says. Every *other* remediation above is mutually independent — run them in any order, or concurrently; do not serialize them defensively.
91
91
 
@@ -202,13 +202,13 @@ Do these in order; each must be asserted, not assumed:
202
202
  - guard: `{"type": "command", "command": "<env> uv run '{skill-root}/scripts/hooks/guard_pretooluse.py'", "onFailure": "block"}`
203
203
  - budget: `{"type": "command", "command": "<env> uv run '{skill-root}/scripts/hooks/budget_stop.py'"}`
204
204
 
205
- With the key, Claude Code refuses the tool call when the guard cannot start (`uv` missing from `PATH`, say), crashes, exits with a code other than 0 or 2, or times out. Without it each of those lets the call run unchecked, because Claude Code reads a hook that failed as no objection. Claude Code honors the key from 2.1.295, the minimum step 1's `cc_version` check enforces; an older one ignores it silently. Write the value exactly `"block"`, in lower case: Claude Code drops a whole item whose `onFailure` is any value other than `"continue"` or `"block"`, so a mistyped one leaves no guard at all. The cost comes with the all-tools matcher below. A guard that cannot run refuses every tool call, Read and Edit included, so the session cannot repair it, and the fix is made outside the session: put `uv` back on `PATH`, or mend whatever else broke, or remove the guard item from `.claude/settings.local.json` by hand as SECURITY.md describes, then resume the run. The Stop budget hook carries no `onFailure`: Claude Code ignores the key on `Stop`, and the budget hook never blocks a stop by design, so it has no failure the key could turn into a refusal. A run armed before this key existed (by UCG 3.x or earlier) has a guard item without it: a fresh preflight replaces that item here, and a resume, which never reaches this stage, re-merges through this bullet when its `--assert-armed` names the missing key (`references/execute.md`, the re-assertion sweep).
205
+ With the key, Claude Code refuses the tool call when the guard cannot start (`uv` missing from `PATH`, say), crashes, exits with a code other than 0 or 2, or times out. Without it each of those lets the call run unchecked, because Claude Code reads a hook that failed as no objection. Claude Code honors the key from 2.1.295, the minimum step 1's `cc_version` check enforces, and a resume's `--assert-armed` too; an older one ignores it silently. Write the value exactly `"block"`, in lower case: Claude Code drops a whole item whose `onFailure` is any value other than `"continue"` or `"block"`, so a mistyped one leaves no guard at all. The cost comes with the all-tools matcher below. A guard that cannot run refuses every tool call, Read and Edit included, so the session cannot repair it, and the fix is made outside the session: put `uv` back on `PATH`, or mend whatever else broke, or remove the guard item from `.claude/settings.local.json` by hand as SECURITY.md describes, then resume the run. The Stop budget hook carries no `onFailure`: Claude Code ignores the key on `Stop`, and the budget hook never blocks a stop by design, so it has no failure the key could turn into a refusal. A run armed before this key existed (by UCG 3.x or earlier) has a guard item without it: a fresh preflight replaces that item here, and a resume, which never reaches this stage, re-merges through this bullet when its `--assert-armed` names the missing key (`references/execute.md`, the re-assertion sweep), unless a reason that is the operator's to fix stands beside it (a skills failure, or a Claude Code below the minimum): that resume escalates the story it was about to drive first, and the resume after the operator's fix re-merges.
206
206
 
207
- **Quote each injected value and the script path in single quotes, as the templates do.** Claude Code runs the command through a shell, which splits it at every unquoted space. Left unquoted, a project or skill path that holds a space (a project under `~/My Projects`, say) hands the rest of that path to the shell as the command to run, or to `uv run` as the script, so the hook never starts: Claude Code then refuses every tool call under the guard's key, and skips the budget hook without a word. Single quotes keep each value and the path one word, as the recall store value is kept (`references/ingest-and-scope.md`); write a single quote inside a value as `'\''`. `--assert-armed` reads each UCG hook command the way the shell splits it, and fails one that would not start its script as `<env> uv run <script>`.
207
+ **Quote each injected value and the script path in single quotes, as the templates do.** Claude Code runs the command through a shell, which splits it at every unquoted space. Left unquoted, a project or skill path that holds a space (a project under `~/My Projects`, say) hands the rest of that path to the shell as the command to run, or to `uv run` as the script, so the hook never starts: Claude Code then refuses every tool call under the guard's key, and the budget hook counts no turn (a command the shell cannot run lets each stop through; a script `uv` cannot find sends each stop back with uv's error, up to eight times in a row, unless the project `uv` syncs first fails to build, or its requirements cannot be satisfied, when `uv` exits 1 and each stop goes through too; a network failure in that sync exits 2, and sends each stop back). Single quotes keep each value and the path one word, as the recall store value is kept (`references/ingest-and-scope.md`); write a single quote inside a value as `'\''`. Quote the value alone, never its name with it: the shell runs `'KEY=a b'` as the command. `--assert-armed` reads each UCG hook command the way the shell splits it, and fails one that would not start its script as `<env> uv run <script>`, that holds a shell operator or redirection (`;`, `||`, `&`, `<`, `2>&1`) outside quotes, or that holds what the shell expands before `uv` starts (a `$` or a backtick outside single quotes, such as `$HOME` or `"$(cat)"`, or a `*`, `?`, `[` or `{` outside quotes).
208
208
 
209
209
  **Arm the PreToolUse group with a matcher that covers EVERY tool, not just `Bash`.** Use `"matcher": "*"`, or omit the `matcher` key entirely the way the `Stop` group already does. Five of the guard's seven invariants are Bash/git, so `Bash` is the natural choice and it is the choice both known installs made, but the other two, the Cross-Session Recall latch rules, gate other tools too. While a latch is present the guard denies Read, Grep, Glob, Write, Edit, MultiEdit and NotebookEdit calls that name the recall store, the file-tool calls that would change the latch itself, and every claude-mem MCP call. Claude Code only invokes a PreToolUse group for tools its matcher selects, so under `Bash` the hook is never run for any of those calls: the guard would deny each one correctly if it were asked, and it is never asked. Those two then enforce nothing outside Bash while every log line says the hooks are armed, which is the worst of both: a control that reports itself active and is not.
210
210
 
211
- Then **assert they are active**: re-read the resolved settings and confirm both script paths appear **and** that the PreToolUse group's matcher is the all-tools form **and** that every guard item carries `"onFailure": "block"` **and** that each UCG command quotes its injected values and script path. A presence-only assertion passes on a `Bash`-only arming, which is exactly the state this bullet exists to prevent. The same assertion is scriptable: `preflight_check.py --assert-armed` performs it (branch, both hooks under their own events, matcher form, the guard's `onFailure`, how the shell splits each UCG command, injected env, and the UCG story skills `ucg-create-story` and `ucg-dev-story`) in one read and fail-closes with named reasons. Pass `--epic-branch-prefix {workflow.epic_branch_prefix}` and one `--protected-branch <name>` per entry in `{workflow.protected_branches}`, exactly as step 1 does: omit either and it asserts the branch against its hardcoded defaults (`ultracode/epic-`, `main, master`), silently no-opping those overrides and failing a correctly armed run on a false RED. The resume path leans on it (`references/execute.md`), and it is equally valid here. It reads `.claude/settings.local.json`, the file this bullet's arming writes, so an arming that lives in another settings layer fail-closes, which is the correct answer for a control this stage must be able to disarm and re-merge. Invariants that live only in memory are context, not enforcement, and memory does not block a `git commit`.
211
+ Then **assert they are active**: re-read the resolved settings and confirm both script paths appear **and** that the PreToolUse group's matcher is the all-tools form **and** that every guard item carries `"onFailure": "block"` **and** that each UCG command quotes its injected values and script path. A presence-only assertion passes on a `Bash`-only arming, which is exactly the state this bullet exists to prevent. The same assertion is scriptable: `preflight_check.py --assert-armed` performs it (branch, both hooks under their own events, matcher form, the guard's `onFailure`, how the shell splits each UCG command, injected env, the UCG story skills `ucg-create-story` and `ucg-dev-story`, and the Claude Code version against step 1's minimums) in one read and fail-closes with named reasons. Pass `--epic-branch-prefix {workflow.epic_branch_prefix}` and one `--protected-branch <name>` per entry in `{workflow.protected_branches}`, exactly as step 1 does: omit either and it asserts the branch against its hardcoded defaults (`ultracode/epic-`, `main, master`), silently no-opping those overrides and failing a correctly armed run on a false RED. The resume path leans on it (`references/execute.md`), and it is equally valid here. It reads `.claude/settings.local.json`, the file this bullet's arming writes, so an arming that lives in another settings layer fail-closes, which is the correct answer for a control this stage must be able to disarm and re-merge. Invariants that live only in memory are context, not enforcement, and memory does not block a `git commit`.
212
212
  - **Inject the hook env from the resolved scalars.** Both hooks read config from env first ("env wins so the conductor can inject per run") and fall back to hardcoded defaults (`main/master`, `25`, `ultracode/epic-`) otherwise, so a `customize.toml` override of any of these **silently no-ops at the enforcement layer** unless you pass it through. Set these on the hook commands (in the `settings.local.json` hook `command`, each value in single quotes as the templates above write them: `KEY='value' uv run '…'`) or in the process env the hooks inherit:
213
213
  - `ULTRACODE_PROTECTED_BRANCHES='{workflow.protected_branches}'` (comma-separated)
214
214
  - `ULTRACODE_IMPL_ARTIFACTS='{workflow.implementation_artifacts}'`