bmad-module-ultracode-goal 3.2.0 → 4.0.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": "3.2.0",
22
+ "version": "4.0.0",
23
23
  "author": {
24
24
  "name": "Armel"
25
25
  },
package/README.md CHANGED
@@ -62,7 +62,7 @@ The `gate_status` comes straight from TEA's artifact: `gate_eval.py` never re-de
62
62
 
63
63
  ## Install
64
64
 
65
- Requires [Claude Code](https://claude.com/product/claude-code) >= 2.1.154 (the runtime UCG conducts), [Node.js](https://nodejs.org/) >= 22, [Python](https://www.python.org/) >= 3.11, [uv](https://docs.astral.sh/uv/), plus `git` and `gh` on PATH. The project needs BMAD Method 6 with TEA 1.27.x: TEA 2.0 and later, and BMAD 7, are not supported yet.
65
+ Requires [Claude Code](https://claude.com/product/claude-code) >= 2.1.295 (the runtime UCG conducts), [Node.js](https://nodejs.org/) >= 22, [Python](https://www.python.org/) >= 3.11, [uv](https://docs.astral.sh/uv/), plus `git` and `gh` on PATH. The project needs BMAD Method 6 with TEA 1.27.x: TEA 2.0 and later, and BMAD 7, are not supported yet.
66
66
 
67
67
  **Tested with:** on 2026-10-16 a two-story Epic reached its Definition-of-Done with the versions below, under the `--light` profile (TEA test-design and the trace gate; the production gate set was not exercised). They are the versions that run used, not minimums.
68
68
 
@@ -76,9 +76,9 @@ Requires [Claude Code](https://claude.com/product/claude-code) >= 2.1.154 (the r
76
76
  npx bmad-module-ultracode-goal install
77
77
  ```
78
78
 
79
- You'll be prompted for a project name and whether to install the learning material; the skill installs for Claude Code. UCG is also available through the Claude plugin marketplace. See [Getting Started](./docs/getting-started.md) for that path.
79
+ You'll be prompted for a project name and whether to install the learning material; the skill installs for Claude Code. UCG is also available through the Claude plugin marketplace. See [Getting Started](https://armelhbobdad.github.io/bmad-module-ultracode-goal/getting-started/#install) for that path.
80
80
 
81
- > **Hook security:** UCG installs `PreToolUse`/`Stop` hooks into your machine-local, gitignored `.claude/settings.local.json` at preflight, never into a committed file. They run zero-dependency Python scripts shipped in the skill. Claude Code treats that file as protected, so take a new Epic through preflight in an attended session (see [Getting Started](./docs/getting-started.md#hook-security)). See [SECURITY.md](SECURITY.md) for exactly what they execute and how to remove them.
81
+ > **Hook security:** UCG installs `PreToolUse`/`Stop` hooks into your machine-local, gitignored `.claude/settings.local.json` at preflight, never into a committed file. They run zero-dependency Python scripts shipped in the skill. Claude Code treats that file as protected, so take a new Epic through preflight in an attended session (see [Getting Started](https://armelhbobdad.github.io/bmad-module-ultracode-goal/getting-started/#hook-security)). See [SECURITY.md](SECURITY.md) for exactly what they execute and how to remove them.
82
82
 
83
83
  ## Quick Start
84
84
 
@@ -91,7 +91,7 @@ Invoke the skill in natural language: "run this epic autonomously," "execute thi
91
91
  - `--retro`: run the close-out retrospective (interactive runs offer it anyway; headless runs it only when this flag is passed).
92
92
  - `--max-stories N`: drive at most **N** stories in this invocation, then finish normally through the report and the terminal JSON. It bounds the work, not the scope: the Epic's in-scope set is untouched, so the next invocation resumes where this one stopped. `scripts/drive_epic.py` uses it to run one story per process, so a long Epic's context dies with each story.
93
93
 
94
- See [How It Works](./docs/how-it-works.md) for the full six-stage walkthrough, routing conditions, and the headless contract.
94
+ See [How It Works](https://armelhbobdad.github.io/bmad-module-ultracode-goal/how-it-works/) for the full six-stage walkthrough, routing conditions, and the headless contract.
95
95
 
96
96
  ## How UCG Compares
97
97
 
@@ -133,23 +133,23 @@ The JSON it prints is the same object UCG routes on: `verdict`, `gate_status`, a
133
133
 
134
134
  The docs are organized into three buckets: **Why** (start here), **Try** (do stuff), and **Reference** (look things up):
135
135
 
136
- **Why**: **[Why UltraCode Goal](./docs/why-ultracode-goal.md)**: the problem, the three enforcement layers, and when not to use it.
136
+ **Why**: **[Why UltraCode Goal](https://armelhbobdad.github.io/bmad-module-ultracode-goal/why-ultracode-goal/)**: the problem, the three enforcement layers, and when not to use it.
137
137
 
138
138
  **Try**
139
139
 
140
- - **[Getting Started](./docs/getting-started.md)**: install, prerequisites, the flags, and your first autonomous run.
141
- - **[How It Works](./docs/how-it-works.md)**: the six stages, their routing conditions, and the headless five-key emit.
140
+ - **[Getting Started](https://armelhbobdad.github.io/bmad-module-ultracode-goal/getting-started/)**: install, prerequisites, the flags, and your first autonomous run.
141
+ - **[How It Works](https://armelhbobdad.github.io/bmad-module-ultracode-goal/how-it-works/)**: the six stages, their routing conditions, and the headless five-key emit.
142
142
 
143
143
  **Reference**
144
144
 
145
- - **[Architecture](./docs/architecture.md)**: the conductor model, enforcement layers in depth, and `customize.toml` resolution.
146
- - **[Gate Model](./docs/gate-model.md)**: how `gate_eval.py` maps `gate_status` to a verdict, and the production AND-signals.
147
- - **[Health Check](./docs/health-check.md)**: the terminal self-improvement loop: what it sends, privacy, and how to disable it.
148
- - **[Cross-Session Recall](./docs/cross-session-recall.md)**: the optional run history in a local store UCG owns: what a run reads and writes, the trust model, and how to enable it.
149
- - **[Knowledge-Graph Refresh](./docs/knowledge-graph-refresh.md)**: the optional graphify integration: preconditions, what it sends where, and what it never touches.
150
- - **[Operating Tips](./docs/operating-tips.md)**: field notes from real drives: the driver's stop reasons, sequencing by row order, and the verification traps.
151
- - **[Troubleshooting](./docs/troubleshooting.md)**: real failure modes and their remediations.
152
- - **[UCG vs bmad-loop](./docs/comparison.md)**: a side-by-side comparison with bmad-code-org's bmad-loop orchestrator.
145
+ - **[Architecture](https://armelhbobdad.github.io/bmad-module-ultracode-goal/architecture/)**: the conductor model, enforcement layers in depth, and `customize.toml` resolution.
146
+ - **[Gate Model](https://armelhbobdad.github.io/bmad-module-ultracode-goal/gate-model/)**: how `gate_eval.py` maps `gate_status` to a verdict, and the production AND-signals.
147
+ - **[Health Check](https://armelhbobdad.github.io/bmad-module-ultracode-goal/health-check/)**: the terminal self-improvement loop: what it sends, privacy, and how to disable it.
148
+ - **[Cross-Session Recall](https://armelhbobdad.github.io/bmad-module-ultracode-goal/cross-session-recall/)**: the optional run history in a local store UCG owns: what a run reads and writes, the trust model, and how to enable it.
149
+ - **[Knowledge-Graph Refresh](https://armelhbobdad.github.io/bmad-module-ultracode-goal/knowledge-graph-refresh/)**: the optional graphify integration: preconditions, what it sends where, and what it never touches.
150
+ - **[Operating Tips](https://armelhbobdad.github.io/bmad-module-ultracode-goal/operating-tips/)**: field notes from real drives: the driver's stop reasons, sequencing by row order, and the verification traps.
151
+ - **[Troubleshooting](https://armelhbobdad.github.io/bmad-module-ultracode-goal/troubleshooting/)**: real failure modes and their remediations.
152
+ - **[UCG vs bmad-loop](https://armelhbobdad.github.io/bmad-module-ultracode-goal/comparison/)**: a side-by-side comparison with bmad-code-org's bmad-loop orchestrator.
153
153
 
154
154
  Every run that reaches Finalize ends with a self-improvement check that can file a deduplicated GitHub issue with your approval, so **please let runs finish through Finalize**, or [open an issue](https://github.com/armelhbobdad/bmad-module-ultracode-goal/issues/new/choose) directly. If UCG shipped an epic while you slept, a ⭐ helps others find it.
155
155
 
@@ -1,11 +1,11 @@
1
1
  ---
2
2
  title: Stability and Public Contract
3
- description: "The 3.x stability posture: which CLI, config, JSON, and gate surfaces are the supported public contract, what a major costs, and everything that is @internal and free to change."
3
+ description: "The 4.x stability posture: which CLI, config, JSON, and gate surfaces are the supported public contract, what a major costs, and everything that is @internal and free to change."
4
4
  ---
5
5
 
6
- > **Status:** 3.x. The surfaces below are the public contract. Per [Semantic Versioning 2.0.0](https://semver.org/), a breaking change to any of them requires a MAJOR bump; everything marked `@internal` may change in any release. This document is what a consumer pins against.
6
+ > **Status:** 4.x. The surfaces below are the public contract. Per [Semantic Versioning 2.0.0](https://semver.org/), a breaking change to any of them requires a MAJOR bump; everything marked `@internal` may change in any release. This document is what a consumer pins against.
7
7
 
8
- This is the stability posture for `bmad-module-ultracode-goal` at `3.x`. It enumerates the surfaces a downstream consumer or automator may reasonably depend on, versus everything else, which is `@internal`.
8
+ This is the stability posture for `bmad-module-ultracode-goal` at `4.x`. It enumerates the surfaces a downstream consumer or automator may reasonably depend on, versus everything else, which is `@internal`.
9
9
 
10
10
  ## Public contract
11
11
 
@@ -58,6 +58,8 @@ 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
62
+ │ ├── link_worktree_deps.py # links the main tree's dependency folders into the gate worktree
61
63
  │ ├── gate_trail.py # per-story evidence trail (gate-trail.md) at finalize
62
64
  │ ├── formalize_check.py # readiness kernel behind the /ucg-formalize gate
63
65
  │ ├── status_render.py # read-side render behind /ucg-status
@@ -128,4 +130,4 @@ flowchart LR
128
130
 
129
131
  ## Why the hooks live in settings.local.json
130
132
 
131
- The PreToolUse and Stop hooks are auto-merged into `{project-root}/.claude/settings.local.json` (machine-local, gitignored, honored after the workspace trust dialog), not into a committed settings file or memory. The reasoning: these hooks are **enforcement, not context**. A committed hook would impose this module's commit guard on every contributor and every unrelated session in the repo; a hook in memory would not block a commit at all. The machine-local file scopes enforcement to the machine actually running the unattended Epic, and the gitignore keeps it out of shared history. The skill re-merges them every run (idempotently) and asserts they are active before the run goes unattended; it does not assume a prior run left them in place. Because the file is machine-local and executes on your machine, review what is merged; see [SECURITY.md](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/SECURITY.md).
133
+ The PreToolUse and Stop hooks are auto-merged into `{project-root}/.claude/settings.local.json` (machine-local, gitignored, honored after the workspace trust dialog), not into a committed settings file or memory. The reasoning: these hooks are **enforcement, not context**. A committed hook would impose this module's commit guard on every contributor and every unrelated session in the repo; a hook in memory would not block a commit at all. The machine-local file scopes enforcement to the machine actually running the unattended Epic, and the gitignore keeps it out of shared history. The skill re-merges them every run (idempotently) and asserts they are active before the run goes unattended; it does not assume a prior run left them in place. The guard's entry carries `"onFailure": "block"` (Claude Code 2.1.295 and later), so a guard that cannot start, crashes or times out refuses the tool call instead of letting it through: an enforcement layer that fails open when it breaks is no enforcement layer, and the price is that a broken guard stops the session until someone fixes it. Because the file is machine-local and executes on your machine, review what is merged; see [SECURITY.md](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/SECURITY.md).
@@ -22,10 +22,10 @@ The store is a folder you name with the `cross_session_recall_store` key.
22
22
  - **No default.** The key ships as `""`. An empty or blank value, an unresolved `{...}` token, a literal `$VAR` or `%VAR%` and a relative path all count as unset.
23
23
  - **Accepted values.** A `~` path, expanded like `health_check_seen_cache`, such as `~/.ultracode-goal/recall`. An absolute path or a `{project-root}` path works too.
24
24
  - **Layout.** Each run gets one file, `<store>/<fingerprint-dir>/runs/<run_id>.jsonl`, holding one JSON line. The file is created once and never rewritten. `<fingerprint-dir>` comes from this repo's fingerprint (its origin and root commit), in a form that is legal on Windows; a repo with no remote gets `local-<hex>`.
25
- - **Per machine.** Another developer or a CI runner never sees this machine's records. Worktrees and clones of one repo on this machine share the same fingerprint, so they read each other's records. A shared store is a follow-up, tracked in [#154](https://github.com/armelhbobdad/bmad-module-ultracode-goal/issues/154).
25
+ - **Per machine.** Another developer or a CI runner never sees this machine's records. Worktrees and clones of one repo on this machine share the same fingerprint, so they read each other's records. History stays on the machine that wrote it: a store shared through the repository is not planned for now, and [#154](https://github.com/armelhbobdad/bmad-module-ultracode-goal/issues/154) records what one would have to get right.
26
26
  - **It ignores itself.** When the scripts create the store folder, they write a `.gitignore` holding `*` inside it, so a store inside your workspace leaves `git status` clean. A folder that already existed gets no `.gitignore`.
27
27
  - **Give it a folder of its own.** While a run is active, the guard denies every tool call that names the store. A store set to your workspace, to a folder above it, or to a folder that holds the implementation artifacts makes nearly every command there name the store, so they are denied. [SECURITY.md](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/SECURITY.md) has the detail.
28
- - **Growth.** The store has no pruning yet. Each run, so each `drive_epic` spawn, adds one small file, and Ingest reads them all. The filter's 120-day horizon hides stale records at read time, except records holding a root cause that two or more runs recorded. Pruning is a follow-up, most naturally with #154.
28
+ - **Growth.** The store has no pruning yet. Each run, so each `drive_epic` spawn, adds one small file, and Ingest reads them all. The filter's 120-day horizon hides stale records at read time, except records holding a root cause that two or more runs recorded.
29
29
 
30
30
  ## Turning it on
31
31
 
@@ -183,7 +183,7 @@ A claude-mem call, a call that names the store, or a call that would change the
183
183
  Recall is deliberately bounded. Treat these as the residuals you are signing up for:
184
184
 
185
185
  - **A factual advisory still informs reasoning.** Sanitized advisories carry no instruction-shaped, stale, or foreign content and never reach the gate, but a well-formed factual advisory can still inform the model's reasoning. That is the feature, bounded; it is not a side channel into the verdict.
186
- - **The store is per machine.** Recall across Epics holds on one machine only, until [#154](https://github.com/armelhbobdad/bmad-module-ultracode-goal/issues/154).
186
+ - **The store is per machine.** Recall across Epics holds on one machine only. A shared store is not planned for now, so another machine, such as a teammate's or a CI runner, never sees this machine's runs.
187
187
  - **The store folder follows the fingerprint.** If a repo with no remote gains one, or you work from a shallow clone, new records go to another folder and the earlier ones stop being read.
188
188
  - **A record file is plain JSON.** Anyone who can write the store folder can edit one. The reader treats every record as untrusted data and defangs it, but it cannot tell an edited record from a real one.
189
189
  - **Redaction is high-precision, not complete.** Secret redaction is pattern matching tuned for precision; it is not a complete data-loss-prevention layer.
@@ -14,7 +14,7 @@ UltraCode Goal conducts BMAD and TEA skills and runs deterministic Python under
14
14
 
15
15
  | Tool | Used for | Minimum | Tested on | Install |
16
16
  | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | -------------- | --------------------------------------------------------------------------- |
17
- | Claude Code | **The runtime: non-negotiable.** UCG composes Auto Mode, Auto Memory, and runtime hooks, which only exist in Claude Code, and writes each story's Definition-of-Done as a `/goal`-style condition; the autonomous run cannot execute anywhere else. Preflight refuses to launch below the minimum | 2.1.154 | 2.1.301 | <https://claude.com/product/claude-code> |
17
+ | Claude Code | **The runtime: non-negotiable.** UCG composes Auto Mode, Auto Memory, and runtime hooks, which only exist in Claude Code, and writes each story's Definition-of-Done as a `/goal`-style condition; the autonomous run cannot execute anywhere else. Preflight refuses to launch below the minimum | 2.1.295 | 2.1.301 | <https://claude.com/product/claude-code> |
18
18
  | Node.js | Installation, `npx` commands | 22 | 22, 24 | <https://nodejs.org> |
19
19
  | Python | The deterministic gate, preflight, and hook scripts (run via `uv`) | 3.11 | 3.11, 3.12 | <https://www.python.org> |
20
20
  | `uv` (Python package runner) | Running the module's Python scripts with automatic dependency management | none | 0.13.1 | <https://docs.astral.sh/uv/getting-started/installation/> |
@@ -89,6 +89,6 @@ Useful flags: `--limit N` caps how many sessions it spawns, retries included, `-
89
89
 
90
90
  ## Hook security
91
91
 
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. 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.
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
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.
@@ -175,4 +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.
179
+
178
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.
@@ -17,7 +17,9 @@ flowchart TD
17
17
  G -->|"yes"| GATE["See: gate_eval reports blocked / escalate"]
18
18
  G -->|"no"| H{"A commit slipped past a guard"}
19
19
  H -->|"yes"| HOOK["See: Hooks not firing"]
20
- H -->|"no"| B{"A story stopped re-looping, escalation marker appeared"}
20
+ H -->|"no"| X{"Every tool call is refused, Read included"}
21
+ X -->|"yes"| REF["See: Every tool call is refused"]
22
+ X -->|"no"| B{"A story stopped re-looping, escalation marker appeared"}
21
23
  B -->|"yes"| BUD["See: Budget exhausted mid-story"]
22
24
  B -->|"no"| R{"Run was interrupted, want to continue"}
23
25
  R -->|"yes"| RES["See: Resume after an interruption"]
@@ -25,7 +27,7 @@ flowchart TD
25
27
  D -->|"yes"| OPS["See: operating tips, the driver's stop reasons"]
26
28
  D -->|"no"| LOG["Read the tail of .decision-log.md"]
27
29
  classDef accent fill:#6366F1,stroke:#4F46E5,color:#fff
28
- class PRE,GATE,HOOK,BUD,RES,OPS,LOG accent
30
+ class PRE,GATE,HOOK,REF,BUD,RES,OPS,LOG accent
29
31
  ```
30
32
 
31
33
  ## Preflight can't reach budget-zero
@@ -38,7 +40,7 @@ flowchart TD
38
40
 
39
41
  - **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.
40
42
  - **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.
41
- - **Claude Code below the minimum versions.** The primitive-version blocker is marked non-remediable: the script can't upgrade the host. Update Claude Code.
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`).
42
44
  - **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.
43
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)).
44
46
  - **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.
@@ -71,6 +73,28 @@ A per-story gate can return `reloop` with a `PASS` gate status when a cap fired
71
73
  - **`settings.local.json` not merged.** The hooks are merged into `{project-root}/.claude/settings.local.json` at preflight, and the skill asserts they are active before going unattended. If the file wasn't merged (or the workspace trust dialog wasn't accepted), the hooks aren't loaded. Re-run preflight; verify the two hook entries are present in the resolved settings.
72
74
  - **A `customize.toml` override that silently no-ops.** Both hooks read config from env first and fall back to hardcoded defaults (`main`/`master`, `25`, `ultracode/epic-`). A `protected_branches` or turn-budget override in `customize.toml` only reaches the hook if preflight injected it into the hook env (`ULTRACODE_PROTECTED_BRANCHES`, etc.). If your custom protected branch isn't being guarded, the override didn't reach the enforcement layer. Confirm preflight passed it through.
73
75
 
76
+ ## Every tool call is refused
77
+
78
+ **Symptom.** Every tool call the session makes is refused, Read, Edit and Bash alike, and each refusal names the guard's command, `guard_pretooluse.py`. Most read like `PreToolUse:Bash hook error: [<command>]: failed; blocking because onFailure is "block"` (or `timed out; blocking because onFailure is "block"`). When `uv` itself refuses to start the script (the skill was moved or removed, or no Python it can use), the refusal shows `uv`'s own error instead, such as `error: Failed to spawn`, since `uv` then exits 2, which Claude Code reads as a refusal in any case. A headless run stops on the first call.
79
+
80
+ **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
+
82
+ - **`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.
84
+ - **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
+ - **No Python `uv` can use.** `uv` cannot start a Python the script's header allows.
86
+ - **The guard ran past its timeout.** Claude Code's default for a command hook is 600 seconds; the message then says `timed out`.
87
+
88
+ A refusal the guard makes itself reads differently: it starts with the guard's own reason (`Commit/push guard: …`, `Protected-branch guard: …`, `UltraCode-Goal guard: …`) and names what to fix. That is the guard deciding, not failing.
89
+
90
+ **What you do.** Fix it from outside the session, since the session cannot run a tool:
91
+
92
+ 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
+ 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.
95
+
96
+ 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
+
74
98
  ## Budget exhausted mid-story
75
99
 
76
100
  **Symptom.** A story stops re-looping; an escalation marker (`<impl-artifacts>/.escalation-<story>.md`) appears; the run surfaces a budget message.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://json.schemastore.org/package.json",
3
3
  "name": "bmad-module-ultracode-goal",
4
- "version": "3.2.0",
4
+ "version": "4.0.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",
@@ -242,6 +242,21 @@ The two dispositions are genuinely different things, not two names for one:
242
242
  and removes the marker (`{ucg-root}/references/gate.md`, "Commit the gate's evidence
243
243
  before the next story starts"), on the Epic's last story too, where every row already
244
244
  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
249
+ reworded, write the sidecar's `decision_needed` verbatim into this answer's
250
+ `.decision-log.md` entry, under both story keys it names, beside the operator's answer
251
+ and the id you closed, before you delete the sidecar: once the sidecar is gone, that
252
+ entry is the only copy of the move the resumed run writes into both story files, or for
253
+ two decomposed children into every record of their split (the split record, both child
254
+ rows in `sprint-status.yaml` and both ATDD checklists). This
255
+ surface edits neither story file and moves no test case: the ruling is the operator's,
256
+ and the resumed run applies it before the earlier story's next commit. An answer that
257
+ re-plans the rows instead (one story in place of the two, or another order) is the
258
+ operator's own edit of `sprint-status.yaml` and the story files: record `defer` until
259
+ they have made it, then `close`.
245
260
  - **`defer`** — the decision is not made yet. Record the entry **without clearing
246
261
  anything**. The artifact stays exactly where it is, the item stays pending, and the next
247
262
  preflight still blocks on it.
@@ -137,7 +137,7 @@ Three things are worth saying out loud alongside it:
137
137
  | re-loops this run | how many times this run re-entered a story, from the heartbeat |
138
138
  | profile | the profile the run is on, from the heartbeat |
139
139
  | updated | when the heartbeat was last written: this with `phase` is how a reader judges liveness |
140
- | stories | one row per in-scope story: phase, verdict, attempts, re-loops |
140
+ | stories | one row per in-scope story: phase, verdict, attempts, re-loops; a story that still owes its gate evidence commit or a re-gate says so (see below) |
141
141
  | escalations | one block per escalation on disk (see below) |
142
142
  | deferred work | every row of the ledger, across every run it has accumulated |
143
143
  | decision log tail | the run's own account of itself, last lines - only when `--run-dir` was passed (§1) |
@@ -172,6 +172,39 @@ A marker and an unreadable sidecar can both be on disk for one story, and the ma
172
172
  the render, so an `unpromoted` block is worth one directory check before you report the
173
173
  typed record as never written.
174
174
 
175
+ **A story that still owes its gate evidence commit says so on its row.** When a repo commit
176
+ hook rejects the gate's evidence commit in a way the gate may not answer, the gate
177
+ escalates the story as `evidence-commit-rejected` and writes `.evidence-owed-<story_id>`
178
+ beside the sidecar, listing the paths it left staged. `/ucg-resolve` deletes the sidecar
179
+ when it closes that escalation and leaves the marker, which a resume removes once it has
180
+ made the commit, or once it finds the listed paths committed already, by the operator or
181
+ by a run that stopped between its commit and that removal. The story renders under
182
+ stories as `gate evidence commit owed when its marker was written, after a commit hook
183
+ rejected it: a resume makes the commit, or removes the marker when it finds the paths
184
+ committed already`, with the marker's name and its paths, on that story's row, or on a
185
+ line of its own when the heartbeat no longer lists it. Report the story as advanced at its
186
+ gate with its evidence commit owed when the marker was written: while its
187
+ `evidence-commit-rejected` block still renders under escalations, `/ucg-resolve` closes it
188
+ first, and once the block is gone one resume of the run makes the commit, or finds it made
189
+ and removes the marker without one. The render does not read git, so it does not say
190
+ whether the paths are still staged. While this line renders the Epic is not finished, even
191
+ when every story reads `done` and escalations read `n/a`: it is the state in which
192
+ `drive_epic.py` stops `evidence-owed` rather than `all-done`.
193
+
194
+ **A story that owes a re-gate says so on its row too.** When `/ucg-resolve` closes an
195
+ `operator-evidence-owed` escalation, it deletes the sidecar and writes
196
+ `.regate-<story_id>`, holding `sha=` the assessed commit and `decision=` the closed id, and
197
+ the gate deletes that marker once the story's next verdict is logged. Until then nothing
198
+ renders under escalations for the story, and a row the heartbeat still lists keeps the
199
+ verdict that escalated it, so the story renders under stories as `re-gate owed: its
200
+ operator-evidence-owed escalation was closed, and no gate verdict was logged since`, with
201
+ the marker's name, its `sha=` and its `decision=`, on that story's row, or on a line of its
202
+ own when the heartbeat no longer lists it. Report the story as waiting on a gate the next
203
+ resume of the run runs: while the `sha=` commit is still `HEAD`, the resume re-gates that
204
+ commit against the operator's records, and once a later commit has moved `HEAD` past it
205
+ those records are stale and the resume routes the story as if the marker were absent. The
206
+ render does not read `HEAD`, so it does not say which of the two holds.
207
+
175
208
  ## Optional diff-viewer affordance
176
209
 
177
210
  When `hunk` is on PATH, each story that recorded a baseline commit gains copy-paste
@@ -4,7 +4,7 @@ Drive each in-scope story from its red-phase acceptance tests (generated in Stag
4
4
 
5
5
  One path: the **sequential `/goal` spine**, named for the `/goal`-style condition each story's drive is written against; the conductor cannot start a live `/goal` (see "Authoring the `/goal` condition"). (The experimental `--parallel` worktree fan-out is retired; the flag is still accepted so an old invocation does not error — see "Retired — `--parallel`" below.)
6
6
 
7
- Preconditions (asserted, not assumed): you are on the Epic branch (`{workflow.epic_branch_prefix}…`, off a `{workflow.protected_branches}` branch), PreToolUse + Stop hooks are active in `.claude/settings.local.json`, the allowlist is pre-populated, and — **in production** — every in-scope story has an `atdd-checklist-{story_key}.md` with `test.skip` acceptance tests. (Under `--light` there is no atdd-checklist by design; the story file's clear acceptance criteria are the Stage-5 trace oracle instead — see define-done.md's `--light` note. The clear-ACs precondition still holds. **On a stack whose ATDD generator cannot run** — the non-web case `references/gate.md`'s hand-authoring section carves out — there is no atdd-checklist either, and that is not a failed precondition: the checklist is replaced by a red phase established BY HAND, authored, RUN and captured before the story's first implementation edit, per gate.md's non-web section and step 1 below. Routing such a run back to an earlier stage cannot produce the artifact and never terminates.) If any is false, return to the stage that produces the missing piece: branch, hooks or allowlist to Stage 2; a genuinely missing atdd-checklist to **Stage 3** (define-done — the only stage that generates it; Stage 2 cannot). Two legitimate ways a story reaches this stage checklist-less, neither of which is a bounce: a **decomposed child row** (created after Stage 3 ran — run `bmad-testarch-atdd` scoped to that story before its step 0, or hand-establish the red phase where ATDD cannot run) and the **non-web stack** above. Record which case it was, and what replaced the checklist, in `.decision-log.md`.
7
+ Preconditions (asserted, not assumed): you are on the Epic branch (`{workflow.epic_branch_prefix}…`, off a `{workflow.protected_branches}` branch), PreToolUse + Stop hooks are active in `.claude/settings.local.json`, the allowlist is pre-populated, and (**in production**) every in-scope story has an `atdd-checklist-{story_key}.md` with `test.skip` acceptance tests. (Under `--light` there is no atdd-checklist by design; the story file's clear acceptance criteria are the Stage-5 trace oracle instead: see define-done.md's `--light` note. The clear-ACs precondition still holds. **On a stack whose ATDD generator cannot run** (the non-web case `references/gate.md`'s hand-authoring section carves out), there is no atdd-checklist either, and that is not a failed precondition: the checklist is replaced by a red phase established BY HAND, authored, RUN and captured before the story's first implementation edit, per gate.md's non-web section and step 1 below. Routing such a run back to an earlier stage cannot produce the artifact and never terminates.) If any is false, return to the stage that produces the missing piece: branch, hooks or allowlist to Stage 2 (on a resume, the hooks by re-merging them through Stage 2's step 5 **Hooks** bullet alone, as "A hooks reason is fixed in place" below says); a genuinely missing atdd-checklist to **Stage 3** (define-done, the only stage that generates it; Stage 2 cannot). Two legitimate ways a story reaches this stage checklist-less, neither of which is a bounce: a **decomposed child row** (created after Stage 3 ran: run `bmad-testarch-atdd` scoped to that story before its step 0, or hand-establish the red phase where ATDD cannot run) and the **non-web stack** above. Record which case it was, and what replaced the checklist, in `.decision-log.md`.
8
8
 
9
9
  **A decomposed child's ATDD run** (the precondition's case above) follows `references/define-done.md` step 2's rule for a decomposed child: under the child's own key, so the checklist the commit guard reads is the child's; the parent's story file read for the text of the parent ACs the child claims, never edited; and, on a halt over vague criteria, an escalation, never a `ucg-create-story` run for the child.
10
10
 
@@ -14,7 +14,9 @@ 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, 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) in one read, and the `story` block returns the artifact-derived route this paragraph defines: `decision-pending` (the next paragraph), `story-boundary`, `mid-story`, or `gate-owed` (the committed-green-un-gated third case below, or the re-gate a closed `operator-evidence-owed` escalation owes, the fourth case after it; for the third case the script only ever returns it when `--trace-output` named the run's real, readable trace dir and the artifact evidence held in full, while an unverifiable location reads `unknown` and routes to the ordinary loop, so lack of evidence never skips steps 1 through 4). Three things the manifest deliberately does **not** cover: the latch is **reported, never certified** (whatever the JSON shows, re-latch from this run's own measurement exactly as above); a boundary story's fresh baseline is still written by step 0; and the **allowlist** is neither asserted nor reported (it lives in permission settings the script does not read), so re-assert it exactly as the list at the top of this paragraph requires. A non-zero exit is the resume's RED: fix what the `reasons` name before continuing, and never narrate around it. A fix that writes `.claude/settings.local.json` (a hook, its env, the allowlist) follows `references/preflight.md`'s "A refused settings write" rule if the write, or a call after it, is refused: stop, never work around it, and in headless take the escalation route below for the story about to be driven, naming the refused write. The one reason a resume never fixes is a skills failure (`checks.skills.ok: false`): installing UCG's story skills is the operator's call, so do not run the installer command that reason names, do not substitute another skill (`bmad-build`, `bmad-build-auto`, or BMAD's deprecated `bmad-create-story` and `bmad-dev-story`), and do not hand-author the story or the code. Take the sub-skill halt catch-all's route (below) for the story about to be driven: write `escalation-<story_id>.json` with `decision_needed` quoting that reason, then stop.
18
+
19
+ **A 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.
18
20
 
19
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.
20
22
 
@@ -32,7 +34,7 @@ Preconditions (asserted, not assumed): you are on the Epic branch (`{workflow.ep
32
34
 
33
35
  ### Sizing: a story too large to drive
34
36
 
35
- **Before step 0 writes any marker, size the row.** Count its acceptance criteria and tasks. **Take that set from the ROW, not from a neighbour's prose.** The `sprint-status.yaml` row is the authority on *which* acceptance criteria a story owes; the story file it cites (its own, or the parent it was split from) is only where those criteria's text lives. A decomposed child has no story file of its own by the convention below, so its contract exists solely as the criteria its row cites. A sibling's ledger entry, or a decision-log entry, names what that sibling **handed off** — a different set, with no reason to be complete — and a scope read from one undersizes the row here and under-delivers it at step 1. Nothing downstream catches that: the trace, the gate-decision file and the gate verdict are all written from this same reading, so they come out green over a missing criterion by construction. When the count is implausible against `{workflow.max_turns_per_story}`, **do not start the story** — decompose it into child rows and terminate the invocation. "Implausible" has a first-pass test, not just a judgment: a driven story spends a turn or more per acceptance criterion once implementation, verification and the gate artifacts are counted, so **when the row's AC count plus task count reaches roughly half of `{workflow.max_turns_per_story}`, treat the row as implausible**, and tie-break against this Epic's own record — the AC/task counts of rows already driven cleanly versus rows already split; a row matching an already-split parent's shape is answered by that precedent. The judgment word stays as the override in both directions (a count under the threshold can still be implausible when each AC owes an executed artifact; over it can be plausible when the ACs are one-line checklist items), but an override is a recorded reason in `.decision-log.md`, never the whole method — two conductors meeting the same row must be able to reach the same verdict.
37
+ **Before step 0 writes any marker, size the row.** Count its acceptance criteria and tasks. **Take that set from the ROW, not from a neighbour's prose.** The `sprint-status.yaml` row is the authority on *which* acceptance criteria a story owes; the story file it cites (its own, or the parent it was split from) is only where those criteria's text lives. A decomposed child has no story file of its own by the convention below, so its contract exists solely as the criteria its row cites. A sibling's ledger entry, or a decision-log entry, names what that sibling **handed off** (a different set, with no reason to be complete), and a scope read from one undersizes the row here and under-delivers it at step 1. Nothing downstream catches that: the trace, the gate-decision file and the gate verdict are all written from this same reading, so they come out green over a missing criterion by construction. When the count is implausible against `{workflow.max_turns_per_story}`, **do not start the story**: decompose it into child rows and terminate the invocation. "Implausible" has a first-pass test, not just a judgment: **when the row's acceptance-criteria count reaches roughly half of `{workflow.max_turns_per_story}`, treat the row as implausible** (13 criteria at the default 25). Count the tasks too, as evidence for the tie-break and the override, but keep them out of the threshold: a task list is how its author sliced the work, and it also holds steps every row pays (reading the skills, running the gates, a step the operator owns). Criteria plus tasks flagged 25 of one real Epic's 30 rows and 4 of another's 5, and nearly every flagged row was then driven whole. The threshold sizes what the story owes; it is not a forecast of turns. The Stop hook counts one turn per response ("Waiting spends turns" below), so the turns a story spends follow how its drive waits, not how many criteria it closes: drives that ran each stage as one delegated workflow took rows of 9 and 13 criteria to their gates in 6 and 7 turns, a 3-criterion row whose sweeps and suite runs each cost turns passed the ceiling twice over, and a `scripts/drive_epic.py` spawn is usually one long response per story. Tie-break against this Epic's own record: the criteria counts of rows already driven cleanly versus rows already split; a row matching an already-split parent's shape is answered by that precedent. The tie-break reads no turn counts. The turns a row spends follow how its drive waits, as above, and no record holds the turns a driven row used: `/ucg-resolve` resets or deletes its `.budget-<story_id>.json` when it closes a `budget-overrun` or `operator-evidence-owed` escalation, and the Stop hook adds each response of a later session to the story `.current-story` still names, so that file, and a count logged from it beside a gate verdict, can hold fewer turns than the row used or more. The judgment word stays as the override in both directions (a count under the threshold can still be implausible when each AC owes an executed artifact; over it can be plausible when the ACs are one-line checklist items), but an override is a recorded reason in `.decision-log.md`, never the whole method: two conductors meeting the same row must be able to reach the same verdict.
36
38
 
37
39
  Nothing else in this stage covers that case, and the two routes it seems to offer are both wrong. Driving it reaches the turn bound with a baseline marker and a tests-ran marker on disk and no commit, which is exactly the abandoned-mid-story outcome the work bound below exists to avoid. Escalating reaches the same conclusion having first spent the whole budget proving what an AC count showed in five minutes. **A decomposition writes no baseline and no tests-ran marker at all**, so the abandoned-story shape cannot arise from it.
38
40
 
@@ -50,7 +52,7 @@ Record the split in `.decision-log.md`: the parent, the children in order, and w
50
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}
51
53
  ```
52
54
 
53
- It exits 0 when the map reconciles and 1 when it does not, printing `unclaimed`, `double_claimed` and `unknown_claims` (an AC no parent row owns) either way — **a non-zero exit means the split is wrong and must be fixed before the child rows are written**, not a warning to log past. Called without `--child` before the split it does the sizing half only, returning `load`, `ratio` and `implausible` against the same threshold this section states, and it says `reconciled: false` rather than reporting a clean claim map it never checked. The judgment stays here: `implausible` is an override in both directions with a recorded reason, and which child owns which AC is an authoring decision the script never makes.
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.
54
56
 
55
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.
56
58
 
@@ -68,6 +70,8 @@ For each in-scope story, in sprint order, run this loop (leave out a decomposed
68
70
 
69
71
  **Get an AC narrowed in writing before committing a case that pins behaviour it forbids.** A stated bound (a case asserting an outcome an AC rules out, because the story keeps that behaviour on purpose) leaves the AC PARTIAL in trace, which reads the AC as written, and no re-loop changes the AC. Narrowing it is the operator's decision, so escalate for it as the sub-skill halt catch-all below does, naming the AC, the behaviour and the narrowing you propose, and commit the case only once the story file states the narrowed AC.
70
72
 
73
+ **Two stories green only together: move the clauses in writing, never share a commit.** A plan can couple two in-scope stories so that the earlier story's commit cannot be green alone: the earlier story owes a clause only the later story's build can satisfy, and the later story often turns the earlier story's cases red without them, so no order helps. Step 5 advances a story only on its own green commit. Do not commit them together, leave the earlier story uncommitted, or gate both at one commit: the tests-ran marker, the range from `.baseline-<story_id>` to `.commit-<story_id>`, and the trace and gate decision are each one story's, and two stories gated at one commit share one range, so neither shows its own work (step 4's END sha). Driving the two rows as one unit is not a route this run takes either: only the operator re-plans rows, outside the run (one story in place of the two, or another order). The route is to move each such clause forward, to the later story, which must be an in-scope, not-`done` story of this Epic. That narrows the earlier story's AC, so it is the operator's decision, as the narrowing above is: never move a clause on your own ruling. As soon as the plan, a story file's notes, a red at step 2 or step 5, or a re-loop's findings show the coupling, and before the earlier story's next commit, capture for each clause a run on the earlier story's tree, to a file under `{workflow.implementation_artifacts}`, showing that the code it needs exists only in the later story's build. Only a clause so measured moves. The operator's ruling takes one of two forms. An **Operator notes** entry given before launch (`references/ingest-and-scope.md`, "Operator notes") that names both stories and authorizes moving clauses from the earlier story to the later one is that ruling for each measured clause it covers, so where a move fits that clause (below), apply the move without escalating and cite that note. A note that does not name both stories is not that ruling, and neither is a general or standing delegation (to rule on AC wording, say), wherever it is written. Otherwise escalate for the earlier story as the sub-skill halt catch-all below does, with `kind` `coupled-stories`, `source` the measurement file, and `decision_needed` naming both story keys, each clause, its measurement and the wording you propose for both story files (for two decomposed children, the changed claim map); when the later story is outside this run's scope, propose only a re-plan. Once `/ucg-resolve` has closed it, take the ruling from the entry it logs in `.decision-log.md`, which holds your proposal beside the operator's answer; a re-plan leaves you nothing to apply. What the move writes depends on the pair, and all of it lands before the earlier story's next commit. When both stories have a story file, write the ruling into both story files, each citing it: the earlier story's AC states what its own build measures and names the later story's AC that now owns each moved clause, and the later story gains each clause as an AC of its own, with its verification and anti-vacuous twin. Between two decomposed children of one parent, which have no story file, only a whole claimed AC moves, and only when each of its clauses is so measured, while the parent's story file stays unedited: a new reconciling run records the split with the changed claim map ("The reconciling run records the split", above), and the same pass rewrites the AC citation in both child rows' comments in `sprint-status.yaml`, which step 1 takes `claimed_acs` from and the trace is written from, and the AC numbers in both children's `atdd-checklist-<child key>.md` frontmatter (`references/define-done.md`), so no record of the split still gives the earlier child the AC it handed on. An AC the earlier child claims that also holds a clause no run so measured has no move to apply: that clause may not move, and the AC cannot move without it. Any other pair (a decomposed child beside a story that has a file, or children of two parents) has no move to apply either: a child owns only whole ACs of its own parent's story file, and nothing on the other side can claim one. No note can authorize a move where none fits. Escalate for the earlier story as above, proposing only a re-plan, as for a later story outside this run's scope. Move each clause's scaffolded cases with it, out of every file the earlier story's checklist lists in `generatedTestFiles` and into one the later story's checklist lists, since the commit guard reads a skipped case in a listed file as unfinished work. Log the move under both stories in `.decision-log.md`, with the changed claim map for two children. Each gate then reads its own story's ACs as written: the earlier story's gate counts no moved clause as a gap, and the later story's gate measures each one, its automate pass included.
74
+
71
75
  2. Run the tests, lint, and build, and **PRINT the raw output** (pass/fail counts, lint result, build result) into the transcript. **In a monorepo, scope that test run wide enough to catch cross-package regressions** — run the full suite, or the changed package(s) plus everything downstream of them (e.g. an `--affected` set *and its dependents*), not just this story's own package. A story's change can regress a *sibling* package's conformance gate (a cross-package RBAC, ownership, or architecture-boundary check), and a run scoped to only this story's package reports green while that sibling gate is red — deferring the red (and its fix) to a later story or the Epic gate instead of catching it at the story that caused it. This printed evidence is what keeps the run judgeable mid-flight, and what a `/goal` evaluator reads when the operator started one — but it is *evidence*, not the gate. **Once all three go green, write the tests-ran marker** `{workflow.implementation_artifacts}/.tests-ran-<story_id>` — the PreToolUse guard denies the step-4 commit unless this marker exists for the current story, so write it only after a real green run. **That marker must carry a `baseline=<sha>` line** whose value is the verbatim, whitespace-stripped content of `{workflow.implementation_artifacts}/.baseline-<story_id>` written at step 0 — **copied, never re-derived from `git rev-parse HEAD`** at marker-write time. The guard compares the two strings character for character and denies the commit when they differ or when the line is missing, which is what stops a marker written against an older code state from being replayed to satisfy a later commit. Re-deriving the value here instead of copying it is the trap: on a story that commits more than once, HEAD has already moved past the baseline, so a re-derived line denies the story's own second commit. **Write that marker with the Write tool**, after Reading the baseline file and pasting its line unchanged — for the same reason step 4 writes the decision log with Write/Edit. The obvious Bash form, `printf 'baseline=%s\n' "$(cat …/.baseline-<story_id>)" > …/.tests-ran-<story_id>`, is a command substitution that a harness which statically analyses Bash strings refuses outright (the PreToolUse guard permits it; the refusal comes from above). Hand-retyping the forty hex characters instead is precisely the transcription error the freshness clause exists to catch, and its denial says only that the SHAs differ, never that one was mistyped. **The marker carries the sweep's scope beside its baseline** — two more lines, same file: `scope=<full|scoped>` naming which sweep form this green run was (the re-loop rule below is the only thing that ever writes `scoped`; a first pass writes `scope=full`), and — scoped only — `packages=<the resolved package list>` copied from the runner's own printout, never hand-typed. The gate reads the `scope=` line through `gate_eval.py --tests-ran` and caps a scoped cycle's verdict at `reloop` (`references/gate.md`, the sweep-scope AND), which is what stops a scoped sweep from impersonating a full one at the only place the distinction pays.
72
76
 
73
77
  **Scope the sweep on three axes, not one.** Package breadth above is the first; the other two are how a green sweep is most often blind:
@@ -154,7 +158,7 @@ It is a single JSON object, exactly these four string fields and no fifth:
154
158
 
155
159
  One object, never an array: the file is already named per story, so a list would only re-encode the story id inside a file that carries it in its name.
156
160
 
157
- `kind` is **open vocabulary**. A reader renders whatever string it finds and never validates it against a fixed list, in particular never against the red-kind vocabulary the semantic scan returns in `references/preflight.md`, which classifies *planning-artifact* reds and has no term for anything that happens at run time. `budget-overrun` is a live `kind` and sits deliberately outside that vocabulary; a reader that validated against it would silently drop the most common escalation there is. `operator-evidence-owed` is a live `kind` too: the story is delivered and gated except evidence only a person can record (`references/gate.md`). So is `evidence-commit-rejected`: the story advanced, and a repo commit hook rejected its evidence commit in a way the gate may not answer, so that evidence waits, uncommitted, for the operator (`references/gate.md`'s advance route).
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").
158
162
 
159
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.
160
164
 
@@ -48,7 +48,7 @@ Naming no story (or a blank id) is refused: the script exits `2` with a usage li
48
48
 
49
49
  Two properties are load-bearing, so do not "improve" them:
50
50
 
51
- - **It renders verdicts, it never forms one.** The verdict cell is the verdict the run already recorded, or the gate artifact's `gate_status` mapped through the gate's own table. The production AND ran once, when the gate decided; re-running it here would be a second, later judgment on the same story. A story whose verdict was not `advance` is shown as it was decided — never quietly green.
51
+ - **It renders verdicts, it never forms one.** The verdict cell is the verdict the run already recorded, or the gate artifact's `gate_status` mapped through the gate's own table. A story whose escalation is still open (`escalation-<story_id>.json` on disk, neither closed nor a handoff, beside a `sprint-status.yaml` row that is not `done`) reads `escalate` instead, gate artifact or not, because the `escalate` route stops after logging the verdict it escalated from, the `reloop` of a story owed operator evidence or stopped at its turn ceiling; an `evidence-commit-rejected` escalation `/ucg-resolve` has not closed keeps the verdict the story advanced on (`advance`, or `defer`), whatever its row reads, and is named on its verdict-source line. The production AND ran once, when the gate decided; re-running it here would be a second, later judgment on the same story. A story whose verdict was not `advance` is shown as it was decided, never quietly green.
52
52
  - **It fails soft.** Every source is optional: a missing or unreadable checklist, trace report, gate file or baseline renders `n/a` in its cell and the trail continues. This is the opposite of the gate, which fails closed, and deliberately so — the trail has no authority, and failing closed here would turn a reporting bug into a blocked run. Under `--light` there is no acceptance checklist by design, so those sections synthesize from the trace report (TEA-authored, or hand-authored where trace cannot run) and gate decision instead.
53
53
 
54
54
  **Optional diff viewer — detect, then degrade to silence.** The trail's commit column names a sha per story and the run report names the Epic branch, but neither opens a diff. When `hunk` is detected on PATH (`which hunk`), the run report may point at what it already names: `hunk show <commit>` for one story's commit, `hunk diff <epic-branch>` for the run as a whole, so a reader auditing the evidence can open a diff without reconstructing the range by hand. Absent `hunk`, print nothing — no suggestion and no warning that it is missing, and both surfaces read exactly as they did before. It is a render affordance and nothing else: do not add it to `{workflow.allowlist_commands}`, do not add a preflight check for it, and never let it reach a machine surface — not the gate verdict JSON, not the headless envelope, not the terminal `run-status.json`. Those are parsed by callers that will not have it installed.