bmad-module-ultracode-goal 3.1.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.
Files changed (30) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/README.md +16 -16
  3. package/docs/_internal/STABILITY.md +3 -3
  4. package/docs/architecture.md +4 -2
  5. package/docs/cross-session-recall.md +3 -3
  6. package/docs/gate-model.md +2 -2
  7. package/docs/getting-started.md +2 -2
  8. package/docs/how-it-works.md +3 -3
  9. package/docs/index.md +1 -1
  10. package/docs/operating-tips.md +5 -2
  11. package/docs/troubleshooting.md +28 -4
  12. package/docs/why-ultracode-goal.md +1 -1
  13. package/package.json +1 -1
  14. package/skills/ucg-resolve/SKILL.md +26 -1
  15. package/skills/ucg-status/SKILL.md +37 -3
  16. package/skills/ultracode-goal/SKILL.md +2 -2
  17. package/skills/ultracode-goal/references/execute.md +19 -9
  18. package/skills/ultracode-goal/references/finalize.md +6 -4
  19. package/skills/ultracode-goal/references/gate.md +72 -13
  20. package/skills/ultracode-goal/references/ingest-and-scope.md +1 -1
  21. package/skills/ultracode-goal/references/preflight.md +20 -11
  22. package/skills/ultracode-goal/scripts/drive_epic.py +49 -0
  23. package/skills/ultracode-goal/scripts/gate_trail.py +235 -39
  24. package/skills/ultracode-goal/scripts/hooks/budget_stop.py +5 -3
  25. package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +1008 -96
  26. package/skills/ultracode-goal/scripts/mutate_check.py +445 -35
  27. package/skills/ultracode-goal/scripts/preflight_check.py +160 -28
  28. package/skills/ultracode-goal/scripts/probe_servers.py +201 -0
  29. package/skills/ultracode-goal/scripts/status_render.py +69 -1
  30. package/skills/ultracode-goal/scripts/story_sizing.py +14 -9
@@ -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.1.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
 
@@ -102,7 +102,7 @@ A skeptical reader is probably already running one of these. Here is the honest
102
102
  | Completion authority | `gate_eval.py` reads TEA's `gate-decision.json` | you, story by story | the model's self-assessment | CI, but only after the agent stops |
103
103
  | Preflight autonomy gate | hard-gate to remediated green (intervention budget 0)| ad hoc, per story | none | none: CI runs post-hoc |
104
104
  | Invariants enforcement | `PreToolUse` hooks in `settings.local.json` | your attention | prompt text (context, not a gate)| CI checks, after the fact |
105
- | Rollback | git: epic branch, code + evidence commit per story | manual | `/rewind` (misses Bash changes) | revert after merge |
105
+ | Rollback | git: epic branch, code + gate commits per story | manual | `/rewind` (misses Bash changes) | revert after merge |
106
106
  | Knowledge capture | Auto Memory + CLAUDE.md split at Finalize | none structured | none structured | none |
107
107
 
108
108
  The alternatives aren't bad; they solve different problems. **UCG solves exactly one: advancing an epic only when a deterministic script confirms the gate passed, and giving you the verdict JSON to check it yourself.**
@@ -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
 
@@ -34,7 +34,7 @@ Both hooks read their config from env first (so the conductor injects per-run va
34
34
 
35
35
  ### 3. Budget enforcement
36
36
 
37
- Three layers can bound a runaway story, in order of authority: the **in-condition** "…or stop after N turns" clause inside a `/goal` condition (only an operator's own `/goal` condition, which then bounds the session; the conductor cannot start one itself), the **gate re-loop budget** (the conductor reads the hook's turn count before each re-loop, so a `reloop` that would exceed `max_turns_per_story` becomes `escalate`, though that count cannot see re-loops inside one response), and the **Stop hook** as the recorder described above. In a single attended or `-H` session with no operator `/goal`, nothing bounds re-loops spent inside one response; for `drive_epic.py` spawns, the `--session-timeout` wall clock is the backstop. Rollback is git, not `/rewind` (an Epic branch off a protected branch, one implementation commit per green story plus its gate's evidence commit) because `/rewind` checkpoints miss the Bash-driven changes that make up the run.
37
+ Three layers can bound a runaway story, in order of authority: the **in-condition** "…or stop after N turns" clause inside a `/goal` condition (only an operator's own `/goal` condition, which then bounds the session; the conductor cannot start one itself), the **gate re-loop budget** (the conductor reads the hook's turn count before each re-loop, so a `reloop` that would exceed `max_turns_per_story` becomes `escalate`, though that count cannot see re-loops inside one response), and the **Stop hook** as the recorder described above. In a single attended or `-H` session with no operator `/goal`, nothing bounds re-loops spent inside one response; for `drive_epic.py` spawns, the `--session-timeout` wall clock is the backstop. Rollback is git, not `/rewind` (an Epic branch off a protected branch, one implementation commit per green story plus its gate's commits: a test backfill when automate makes one, then the evidence) because `/rewind` checkpoints miss the Bash-driven changes that make up the run.
38
38
 
39
39
  ## File layout
40
40
 
@@ -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.
@@ -103,7 +103,7 @@ The verdict JSON carries the recognised value as `sweep_scope` (or `null`), so a
103
103
 
104
104
  ## The delta cycle profile
105
105
 
106
- A mid-loop re-gate may declare `--cycle-profile delta`: only the assessor dimension(s) whose findings produced the previous reloop re-run in full, while the other assessors re-check their prior artifact against the diff since the commit they assessed. The script caps a delta gate's verdict at `reloop` (defer too, for the sweep-cap reason): a delta gate can say "not yet, and here is why", never move the story. Advancing requires the full instrument, every assessor over a `scope=full` sweep, so the oracle's finality is untouched and a wrong guess costs one extra full gate rather than an unearned advance. The fallback is mechanical: any prior finding without a clean dimension attribution means the full gate runs. `--epic-level` refuses the flag (invocation error, exit 2); omitting it is the full behaviour, and the `cycle_profile` JSON key appears exactly when the flag was supplied.
106
+ A mid-loop re-gate may declare `--cycle-profile delta`: only the assessor dimension(s) whose findings produced the previous reloop re-run in full, while the other assessors re-check their prior artifact against the diff since the commit they assessed. The script caps a delta gate's verdict at `reloop` (defer too, for the sweep-cap reason): a delta gate can say "not yet, and here is why", never move the story. Advancing requires the full instrument, every assessor over a `scope=full` sweep, so the oracle's finality is untouched and a wrong guess costs one extra full gate rather than an unearned advance. The fallback is mechanical: any prior finding without a clean dimension attribution means the full gate runs. `bmad-testarch-automate` sits outside this choice: after a story's first gate cycle, full or delta, it searches only the diff since the previous gate and re-runs the mutation rows behind the gaps that gate backfilled and behind every gap still open, and the full instrument runs it at that scope too. It backfills every gap it finds on a P0 criterion, in any cycle, so trace counts the new test and the script decides; only a gap on another criterion is reported instead, when it lies outside that scope or while operator live results sit at the commit under assessment. A reported gap stays open until a pass at a later commit finds its mutants killed, and it never changes the route a verdict takes. Automate confirms each test it backfills in the same pass, with the test copied into the worktree, and a test that leaves its mutant alive (perhaps an equivalent mutant, which no test can kill) is logged as an `unkilled` gap that no later pass writes another test for while that code stands. `--epic-level` refuses the flag (invocation error, exit 2); omitting it is the full behaviour, and the `cycle_profile` JSON key appears exactly when the flag was supplied.
107
107
 
108
108
  ## The thresholds
109
109
 
@@ -113,7 +113,7 @@ The P0/P1/overall percentage thresholds (**P0 = 100%, P1 >= 90%, overall >= 80%*
113
113
 
114
114
  The production AND is deliberately fail-closed (see the `apply_production_and` docstring in the script): a missing `nfr-assessment.md` or `test-review.md`, or a field the scanners cannot parse, is treated as a **failing** signal, not a neutral or absent one. So if TEA's prose format drifts and the Overall Status or Quality Score cannot be read, an otherwise-`advance` degrades to a conservative `reloop` rather than a silent false-advance. The direction is intentional: the module would rather re-loop a green story than advance a story whose evidence it could not actually read. Likewise, a missing or corrupt gate artifact yields `NOT_EVALUATED` → `escalate`: the gate is never assumed green.
115
115
 
116
- This is reinforced by the routing invariant in Stage 5: **a P0/critical FAIL never defers.** Only non-gate-blocking work (CONCERNS, non-critical findings, parked decisions) reaches the deferred-work ledger; a FAIL or a P0/critical finding re-loops within budget or escalates.
116
+ This is reinforced by the routing invariant in Stage 5: **a P0/critical FAIL never defers.** Only non-gate-blocking work (CONCERNS, non-critical findings, parked decisions, and the coverage gaps automate logged as `gate-gap:` lines that are still open) reaches the deferred-work ledger; a FAIL or a P0/critical finding re-loops within budget or escalates. A `gate-gap:` row is neither, whatever its criterion's priority: it reaches the ledger at `med` severity and never re-loops or escalates the story.
117
117
 
118
118
  ## Output shape
119
119
 
@@ -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.
@@ -78,11 +78,11 @@ Turn the Epic's acceptance criteria into **executable, red-phase acceptance test
78
78
 
79
79
  ### Stage 4: Execute
80
80
 
81
- Drive each in-scope story from its red-phase tests to a green, committed state. Execution is the **sequential `/goal` spine**; per story, in sprint order: set the current story (so the PreToolUse hook can find its marker) → `ucg-dev-story` implements the feature and un-skips the story's ATDD tests → run tests/lint/build and **print the raw output** as evidence → (production) `bmad-testarch-test-review` then `bmad-code-review` → check the commit message against the staged diff (`claim_check.py` lists each path it names that the commit does not touch) and soften any claim the diff's own new lines make that no evidence shows → commit at green (one implementation commit per green story; the gate's evidence commit follows it) → **re-run the suite at this cycle's scope on the committed HEAD (a story only advances off a full-scope sweep)** and print it, because a story's new files are untracked until the commit, so a tracked-files conformance gate can only red once they land; a red here means the story is not done and must be remediated and re-committed before it advances. The conductor writes a per-story `/goal`-style condition that encodes the Definition-of-Done and carries the literal "…or stop after N turns" escape clause, and records it in the decision log. A live `/goal` runs only when you start one, on your own condition, because the conductor cannot start `/goal` itself. The Stop hook records a turn count, once per response, which the conductor reads before each story and each re-loop. The printed evidence keeps the run judgeable mid-flight, but **passing the `/goal` condition is not completion**; the authoritative verdict is Stage 5. As the spine advances it overwrites a `run-status.json` heartbeat for pollers. See [`references/execute.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/execute.md).
81
+ Drive each in-scope story from its red-phase tests to a green, committed state. Execution is the **sequential `/goal` spine**; per story, in sprint order: set the current story (so the PreToolUse hook can find its marker) → `ucg-dev-story` implements the feature and un-skips the story's ATDD tests → run tests/lint/build and **print the raw output** as evidence → (production) `bmad-testarch-test-review` then `bmad-code-review` → check the commit message against the staged diff (`claim_check.py` lists each path it names that the commit does not touch) and soften any claim the diff's own new lines make that no evidence shows → commit at green (one implementation commit per green story; the gate's commits follow it: a test backfill when automate makes one, then the evidence) → **re-run the suite at this cycle's scope on the committed HEAD (a story only advances off a full-scope sweep)** and print it, because a story's new files are untracked until the commit, so a tracked-files conformance gate can only red once they land; a red here means the story is not done and must be remediated and re-committed before it advances. The conductor writes a per-story `/goal`-style condition that encodes the Definition-of-Done and carries the literal "…or stop after N turns" escape clause, and records it in the decision log. A live `/goal` runs only when you start one, on your own condition, because the conductor cannot start `/goal` itself. The Stop hook records a turn count, once per response, which the conductor reads before each story and each re-loop. The printed evidence keeps the run judgeable mid-flight, but **passing the `/goal` condition is not completion**; the authoritative verdict is Stage 5. As the spine advances it overwrites a `run-status.json` heartbeat for pollers. See [`references/execute.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/execute.md).
82
82
 
83
83
  ### Stage 5: Gate
84
84
 
85
- Decide whether a story (or, after the last story, the Epic) advances, by a deterministic artifact read. In production, the skill first backfills the evidence in order: `bmad-testarch-automate`, `bmad-testarch-trace` (which writes the gate decision), `bmad-testarch-nfr`. Assessors that run or time anything measure a worktree of the commit under assessment, never the shared working tree. Then it runs `gate_eval.py`; a mid-loop re-gate may declare a delta profile (only the previously failed dimension re-runs in full) whose verdict is capped at reloop, so only the full instrument ever advances a story. The script reads TEA's `gate-decision.json` and returns a verdict the skill executes: `advance` (move to the next story), `defer` (append non-blocking items to the ledger and advance anyway), `reloop` (generalize each finding to its defect class against the Epic's class ledger, then run `bmad-correct-course` and re-run the story within the remaining budget), or `escalate` (stop). The invariant: **a P0/critical FAIL never defers**; it re-loops within budget or escalates. See the [gate model](./gate-model.md) and [`references/gate.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/gate.md).
85
+ Decide whether a story (or, after the last story, the Epic) advances, by a deterministic artifact read. In production, the skill first backfills the evidence: `bmad-testarch-automate` runs first and alone, a test it backfills is committed before anything else measures the story, and only then do `bmad-testarch-trace` (which writes the gate decision), `bmad-testarch-nfr` and, when the story lacks a current review, `bmad-testarch-test-review` run. Assessors that run or time anything measure a worktree of the commit under assessment, never the shared working tree. Then it runs `gate_eval.py`; a mid-loop re-gate may declare a delta profile (only the previously failed dimension re-runs in full) whose verdict is capped at reloop, so only the full instrument ever advances a story. The script reads TEA's `gate-decision.json` and returns a verdict the skill executes: `advance` (move to the next story), `defer` (append non-blocking items to the ledger and advance anyway), `reloop` (generalize each finding to its defect class against the Epic's class ledger, then run `bmad-correct-course` and re-run the story within the remaining budget), or `escalate` (stop). The invariant: **a P0/critical FAIL never defers**; it re-loops within budget or escalates. See the [gate model](./gate-model.md) and [`references/gate.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/gate.md).
86
86
 
87
87
  This is how the verdict is read deterministically; the conductor never grades the work itself, it runs the script and routes on what comes back:
88
88
 
@@ -123,7 +123,7 @@ The run's `.decision-log.md`, held in the skill's run folder, is canonical memor
123
123
 
124
124
  Finalize leaves two durable outputs beside the decision log, in the run folder. The **run report** (`run-report.md`) is the human takeaway. The **gate trail** (`gate-trail.md`, written by `gate_trail.py`) is the evidence trail: one section per story naming the checklist, trace report, gate decision, and baseline behind that story's verdict, so the gate can be audited without the transcript. Sources it cannot read render as `n/a` rather than failing the trail, but the trail refuses to render at all when no story is named, because an evidence trail that traces nothing is the exact failure it exists to prevent.
125
125
 
126
- The third output lives elsewhere on purpose. The **deferred-work ledger** (at `deferred_work_path`, outside the run folder because it spans runs) holds one heading per Epic with a row per parked item: only non-gate-blocking work lands here (CONCERNS, non-critical findings, parked decisions); a P0/critical FAIL is never deferred. Finalize surfaces this run's Epic heading so nothing parked is invisible at handoff.
126
+ The third output lives elsewhere on purpose. The **deferred-work ledger** (at `deferred_work_path`, outside the run folder because it spans runs) holds one heading per Epic with a row per parked item: only non-gate-blocking work lands here (CONCERNS, non-critical findings, parked decisions, and the coverage gaps the gate's automate pass logged that are still open, at `med` severity whatever their priority); a P0/critical FAIL is never deferred. Finalize surfaces this run's Epic heading so nothing parked is invisible at handoff.
127
127
 
128
128
  ## Headless contract
129
129
 
package/docs/index.md CHANGED
@@ -41,7 +41,7 @@ If the gate file is missing or unparseable, the contract counts it as a *failing
41
41
 
42
42
  ## What you get
43
43
 
44
- Completion stops being a feeling in the transcript and becomes a fact on disk. Every green story lands as an implementation commit, plus its gate's evidence commit, on an isolated epic branch: rollback you can actually trust, not a checkpoint that misses Bash changes. The run ends with a delivered, gate-passed epic, a run report, and a deferred-work ledger of anything safely parked for later.
44
+ Completion stops being a feeling in the transcript and becomes a fact on disk. Every green story lands as an implementation commit, plus its gate's commits (a test backfill when the gate adds coverage, then the evidence), on an isolated epic branch: rollback you can actually trust, not a checkpoint that misses Bash changes. The run ends with a delivered, gate-passed epic, a run report, and a deferred-work ledger of anything safely parked for later.
45
45
 
46
46
  ## Read the rest
47
47
 
@@ -42,13 +42,14 @@ Do not write a latch from the parent between drives. The old workaround, `latch
42
42
 
43
43
  ## Reading the driver's stop reasons
44
44
 
45
- The driver names thirteen stop reasons (`drive_epic.py`'s `STOP_*` constants). Three mean the invocation finished its work and exit 0: `all-done`, `limit-reached`, `dry-run`. Every other stop is a fail-closed halt and exits 1, so a wrapper can branch on the exit code before it parses anything.
45
+ The driver names fourteen stop reasons (`drive_epic.py`'s `STOP_*` constants). Three mean the invocation finished its work and exit 0: `all-done`, `limit-reached`, `dry-run`. Every other stop is a fail-closed halt and exits 1, so a wrapper can branch on the exit code before it parses anything.
46
46
 
47
- These six are the ones you will actually meet in a working week, and getting them confused wastes a spawn or, worse, propagates an ungated story. The rest name their own cause and need no table: `dry-run`, the pre-spawn refusals (`no-sprint-status`, `epic-not-found`, `sprint-status-elsewhere`, `stale-result`), a row carrying a status the driver does not recognize (`unknown-status`), and a drive that was killed (`signalled`).
47
+ These seven are the ones you will actually meet in a working week, and getting them confused wastes a spawn or, worse, propagates an ungated story. The rest name their own cause and need no table: `dry-run`, the pre-spawn refusals (`no-sprint-status`, `epic-not-found`, `sprint-status-elsewhere`, `stale-result`), a row carrying a status the driver does not recognize (`unknown-status`), and a drive that was killed (`signalled`).
48
48
 
49
49
  | Stop reason | What happened | What to do |
50
50
  |---|---|---|
51
51
  | `all-done` | Every story of the Epic is `done`. | Nothing. The Epic is finished. |
52
+ | `evidence-owed` | Every story is `done`, but a commit hook rejected the last story's gate evidence commit, which is still staged (`.evidence-owed-<story>`). | Close its escalation with `/ucg-resolve` if it is still open, then resume the run once (`/ultracode-goal <epic> -H`) to make the commit. |
52
53
  | `limit-reached` | Normal. `--limit` was reached. | Nothing. Drive again. |
53
54
  | `blocked` | The story escalated, and a typed sidecar holds the pending decision. | Run `/ucg-resolve`, which reconstructs every pending decision from the sidecars and walks them. |
54
55
  | `no-terminal` | The spawn exited without a readable result envelope. | **The work may be complete.** See below. |
@@ -174,4 +175,6 @@ Each of these was hit while verifying real work, and each one first looked like
174
175
 
175
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.**
176
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
+
177
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.
@@ -52,7 +54,7 @@ The decision log carries the full blocker list with what each needs to clear. Re
52
54
 
53
55
  **What happened.** `gate_eval.py` reads TEA's gate artifact from the trace output directory. `NOT_EVALUATED` means neither the slim `gate-decision.json` nor the fallback `e2e-trace-summary.json` was found there, or the run carried no gate fields. Almost always this is one of:
54
56
 
55
- - **The TEA trace gate did not run.** In production, Stage 5 must backfill evidence first (`bmad-testarch-automate` → `bmad-testarch-trace` → `bmad-testarch-nfr`) before the gate; `bmad-testarch-trace` is what writes the gate decision. If it didn't run, there is nothing to read.
57
+ - **The TEA trace gate did not run.** In production, Stage 5 must backfill evidence first (`bmad-testarch-automate` first and alone, then the commit of any test it backfilled, then `bmad-testarch-trace` and `bmad-testarch-nfr`) before the gate; `bmad-testarch-trace` is what writes the gate decision. If it didn't run, there is nothing to read.
56
58
  - **Wrong `trace_output_dir`.** The script reads the directory passed as `--trace-output` (resolved from `{workflow.trace_output_dir}`). If TEA wrote elsewhere, or the output dirs were never pre-created at preflight, the artifact is real but in a different place. Confirm `trace_output_dir` matches where TEA actually wrote.
57
59
 
58
60
  Note this is fail-closed on purpose: a missing or unreadable gate artifact escalates rather than being assumed green. The slim file's *absence alone* is not the problem: the script falls back to the summary, and that fallback is explicitly not a failure. See the [gate model](./gate-model.md) for how the artifact resolves into a `gate_status` and the full verdict mapping.
@@ -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.
@@ -11,7 +11,7 @@ Three intuitive shortcuts all push an unattended Epic toward false completion, a
11
11
 
12
12
  **The evaluator only sees the transcript.** Claude Code's `/goal` mode drives a loop until a success condition is met, then asks an evaluator to confirm. But that evaluator reads the transcript; it cannot open a file on disk. It cannot read TEA's `gate-decision.json`. So if you let the `/goal` condition be the final word on "is this story done," you have asked the model to grade its own homework from its own notes. The model cannot be the judge of its own completion: the thing that decides "done" has to be something it cannot author.
13
13
 
14
- **`/rewind` checkpoints miss Bash changes.** The obvious undo for a runaway agent is `/rewind`. But its checkpoints do not capture changes made through Bash, and an autonomous Epic run is mostly Bash: test commands, lint, build, and the git commits themselves. Rolling back to a checkpoint leaves the working tree's Bash-driven mutations in place. The real undo for this kind of run is git: an Epic branch off a protected branch, one implementation commit per green story plus its gate's evidence commit. On a project that gitignores its BMAD output, that undo covers the code only: what the run wrote under the ignored tree stays, the story files, the run's decision log and its sprint-status edits among it. See the [gate model](./gate-model.md) and [architecture](./architecture.md) for how this is wired.
14
+ **`/rewind` checkpoints miss Bash changes.** The obvious undo for a runaway agent is `/rewind`. But its checkpoints do not capture changes made through Bash, and an autonomous Epic run is mostly Bash: test commands, lint, build, and the git commits themselves. Rolling back to a checkpoint leaves the working tree's Bash-driven mutations in place. The real undo for this kind of run is git: an Epic branch off a protected branch, one implementation commit per green story plus its gate's commits (a test backfill when automate makes one, then the evidence). On a project that gitignores its BMAD output, that undo covers the code only: what the run wrote under the ignored tree stays, the story files, the run's decision log and its sprint-status edits among it. See the [gate model](./gate-model.md) and [architecture](./architecture.md) for how this is wired.
15
15
 
16
16
  **Memory is context, not enforcement.** It is tempting to encode the run's invariants ("never commit on `main`", "never commit before tests pass") into Auto Memory or a CLAUDE.md rule and trust the model to honor them. But memory is context the model may or may not weigh; it does not *block* a `git commit`. An invariant that lives only in memory is a suggestion. An invariant that must hold has to live somewhere the model cannot talk its way past.
17
17
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://json.schemastore.org/package.json",
3
3
  "name": "bmad-module-ultracode-goal",
4
- "version": "3.1.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",
@@ -234,6 +234,29 @@ The two dispositions are genuinely different things, not two names for one:
234
234
  the turn-ceiling read could escalate it and a commit past the assessed one would make
235
235
  the records stale (`{ucg-root}/references/execute.md`, the resume rule). The gate
236
236
  deletes the marker once the re-gate's verdict is logged.
237
+ **Closing an `evidence-commit-rejected` escalation makes no commit.** Record the
238
+ operator's answer (the hook fixed or reconfigured, or the file it named changed by them),
239
+ then delete only the sidecar. Leave the staged evidence and
240
+ `{workflow.implementation_artifacts}/.evidence-owed-<story_id>` alone, even when the
241
+ answer is to commit as it stands: the resume makes that commit under the gate's hook rule
242
+ and removes the marker (`{ucg-root}/references/gate.md`, "Commit the gate's evidence
243
+ before the next story starts"), on the Epic's last story too, where every row already
244
+ reads `done` and the resume re-enters only for that commit before Finalize.
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`.
237
260
  - **`defer`** — the decision is not made yet. Record the entry **without clearing
238
261
  anything**. The artifact stays exactly where it is, the item stays pending, and the next
239
262
  preflight still blocks on it.
@@ -262,7 +285,9 @@ may skip, because the two arrive from different places:
262
285
  verdict is not advance; advanced stories are not re-run. Within that branch there is
263
286
  no other re-entry point: it is not the first story of the Epic, and not the story the
264
287
  answered decision happened to name, either of which would re-run stories that already
265
- advanced, which is precisely what the shipped resume rule exists to prevent.
288
+ advanced, which is precisely what the shipped resume rule exists to prevent. When every
289
+ story advanced and a story's `.evidence-owed-<story_id>` is on disk, the resume drives no
290
+ story: it makes that story's owed evidence commit and goes to Finalize.
266
291
 
267
292
  Either branch **re-asserts** — never rebuilds — the Epic branch, both hooks, the
268
293
  allowlist, the `.mem-state.json` recall latch, and the in-flight story's baseline marker.
@@ -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,12 +172,46 @@ 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
178
211
  `hunk show <commit>` lines, so a reader can go straight from a story row to its diff:
179
- one line per commit in the story's range (its implementation commit and the gate's
180
- evidence commit) when the repository is readable, else one line for the story's
212
+ one line per commit in the story's range (its implementation commit, the gate's test
213
+ backfill commit when automate made one, and the gate's evidence commit) when the
214
+ repository is readable, else one line for the story's
181
215
  recorded end commit, or for its baseline when no end commit was recorded. When it is not on PATH, nothing about it is rendered and the render is otherwise
182
216
  unchanged.
183
217
 
@@ -36,7 +36,7 @@ Load config from `{project-root}/_bmad/config.yaml` and `config.user.yaml` (root
36
36
 
37
37
  **Quick launch** (swap in your Epic id): `ultracode goal epic-7` — attended, production, sequential. `ultracode goal epic-7 --light --yes` — the expert one-liner: trace-only gate, no conversational stops. Add `-H` for headless, `--retro` for the close-out retrospective, `--max-stories 1` to take a single story this invocation.
38
38
 
39
- **Resume.** The workspace is this skill's run folder holding `.decision-log.md`. If one exists for the Epic, surface it with its last session date and offer to resume: the log recovers full state regardless of compaction. Otherwise create it at intent and append a session heading. **Route resume by the last stage the log reached**: the run folder is created at intent (Stage 1), so a prior run that blocked *before* Execute also leaves one. If the log carries gate verdicts, re-enter Execute at the first story whose last verdict is not advance (advanced stories are not re-run), re-asserting (not rebuilding) the Epic branch, hooks, allowlist, and the `.mem-state.json` recall latch first (the latch by minting this invocation's own run id as Stage 1 does, never reusing one an earlier invocation logged, and re-running Stage 1's `mem_recall.py latch` step with it, which replaces a latch another run left; `references/execute.md` says why each, and why the latch especially). That re-entry stops short when the story still carries an open escalation: the re-assertion sweep's story route then reads `decision-pending`, and the resume drives nothing (attended, offer `/ucg-resolve`; headless, end `blocked` with a `reason` naming its `escalation-<story_id>.json`; `references/execute.md` says what counts as open). If instead it blocked at Stage 1 (epic unresolved) or Stage 2 (preflight RED: the case an operator fixes then re-invokes), re-run from that stage so the hard preflight gate is never skipped. A re-run from Stage 2 first runs Stage 1's Cross-Session Recall section with a fresh run id (the latch and, on a green latch, its one filter call, whose output Stage 2 reads), since the blocked run's preflight STOP removed its latch. In headless (`-H`) never offer: auto-resume a not-all-done Epic by this same stage routing (a previously-preflight-RED Epic re-runs the gate, it does not enter Execute), delete any existing `{workflow.implementation_artifacts}/run-result.json` as soon as that scalar resolves exactly as a fresh run does (`references/ingest-and-scope.md`), and log the resume as an assumption. **A resume routed into Execute does NOT re-run the Stage-2 formalize gate.** That verdict is Stage 2's and it covers the run's whole in-scope set by construction (`formalize_check.py` reads every not-`done` story of the Epic, or the operator-scoped subset its `--story` flags name, never only the stories one invocation drives), so on any Epic with undrafted or later stories it reads `remediable`/`blocked` on gaps belonging to rows this invocation is not driving. Record it as context, never as a launch gate: a conductor applying the launch non-negotiable literally on every resume would block a healthy run forever, on candidates belonging to stories that have not started.
39
+ **Resume.** The workspace is this skill's run folder holding `.decision-log.md`. If one exists for the Epic, surface it with its last session date and offer to resume: the log recovers full state regardless of compaction. Otherwise create it at intent and append a session heading. **Route resume by the last stage the log reached**: the run folder is created at intent (Stage 1), so a prior run that blocked *before* Execute also leaves one. If the log carries gate verdicts, re-enter Execute at the first story whose last verdict is not advance (advanced stories are not re-run), re-asserting (not rebuilding) the Epic branch, hooks, allowlist, and the `.mem-state.json` recall latch first (the latch by minting this invocation's own run id as Stage 1 does, never reusing one an earlier invocation logged, and re-running Stage 1's `mem_recall.py latch` step with it, which replaces a latch another run left; `references/execute.md` says why each, and why the latch especially). That re-entry stops short when the story still carries an open escalation: the re-assertion sweep's story route then reads `decision-pending`, and the resume drives nothing (attended, offer `/ucg-resolve`; headless, end `blocked` with a `reason` naming its `escalation-<story_id>.json`; `references/execute.md` says what counts as open). If instead it blocked at Stage 1 (epic unresolved) or Stage 2 (preflight RED: the case an operator fixes then re-invokes), re-run from that stage so the hard preflight gate is never skipped. A re-run from Stage 2 first runs Stage 1's Cross-Session Recall section with a fresh run id (the latch and, on a green latch, its one filter call, whose output Stage 2 reads), since the blocked run's preflight STOP removed its latch. In headless (`-H`) never offer: auto-resume a not-all-done Epic by this same stage routing (a previously-preflight-RED Epic re-runs the gate, it does not enter Execute), delete any existing `{workflow.implementation_artifacts}/run-result.json` as soon as that scalar resolves exactly as a fresh run does (`references/ingest-and-scope.md`), and log the resume as an assumption. An Epic whose stories all read `done` while a story's `.evidence-owed-<story_id>` is on disk (its evidence commit, escalated as `evidence-commit-rejected`, is still owed, whether or not `/ucg-resolve` has closed that escalation) counts as not-all-done here and in Stage 1's already-done short-circuit: its resume re-enters Execute only for that commit, then goes to Finalize (`references/execute.md`'s resume rule). **A resume routed into Execute does NOT re-run the Stage-2 formalize gate.** That verdict is Stage 2's and it covers the run's whole in-scope set by construction (`formalize_check.py` reads every not-`done` story of the Epic, or the operator-scoped subset its `--story` flags name, never only the stories one invocation drives), so on any Epic with undrafted or later stories it reads `remediable`/`blocked` on gaps belonging to rows this invocation is not driving. Record it as context, never as a launch gate: a conductor applying the launch non-negotiable literally on every resume would block a healthy run forever, on candidates belonging to stories that have not started.
40
40
 
41
41
  ## Non-negotiables
42
42
 
@@ -45,7 +45,7 @@ These exist because the documented mechanics make the intuitive shortcut wrong.
45
45
  - **Completion is decided by `scripts/gate_eval.py` reading TEA's `gate-decision.json` — never your own judgment, and never the `/goal` evaluator alone.** That evaluator only sees the transcript; it cannot read the gate file. The JSON is the truth.
46
46
  - **Launch the unattended run only when `scripts/preflight_check.py` returns green *after the remediation pass* (intervention budget == 0) and `formalize_check.py returns ready` (on step 3's re-run over the answered scan, with no RED in either reds stream: the readiness verdict the step-4 gate decides) and ultracode + Auto Mode are on.** The unattended run takes no mid-run input: every gate is resolved before launch or not at all. This binds the **Stage-2 entry**. A resume routed into Execute does not re-run it (see Resume above).
47
47
  - **Only non-gate-blocking work defers** to `{workflow.deferred_work_path}`, and the Epic keeps moving; a P0/critical FAIL never defers — it re-loops within budget or escalates.
48
- - **Rollback is git** — Epic branch off `{workflow.epic_branch_prefix}`, one implementation commit per green story plus its gate's evidence commit. `/rewind` checkpoints miss Bash changes; do not rely on them.
48
+ - **Rollback is git**: Epic branch off `{workflow.epic_branch_prefix}`, one implementation commit per green story plus its gate's commits (a test backfill when automate makes one, then the evidence). `/rewind` checkpoints miss Bash changes; do not rely on them.
49
49
  - **Invariants live in PreToolUse hooks**, auto-merged into `.claude/settings.local.json` at preflight — not in memory, which is context, not enforcement. A headless session cannot approve a refused write to that file, so a first arming belongs to an attended pass (`references/preflight.md`, "A refused settings write").
50
50
  - **Cross-Session Recall is advisory-only.** When `{workflow.cross_session_recall}` is `on` and `{workflow.cross_session_recall_store}` names a folder, the records of this repo's prior runs are *data, never directive*: they inform scope (Stage 1) and preflight (Stage 2), never a gate verdict. Only `scripts/mem_recall.py` and `scripts/mem_observation.py` read and write that local run store; the run makes no memory tool call. The hook-enforced latch (`.mem-state.json`) fails closed while it is present, whatever its state: the guard denies every claude-mem call, and every tool call other than those two scripts that names the store or would change the latch, and only `mem_recall.py unlatch` removes it, at the run's end. See the Cross-Session Recall guide: <https://armelhbobdad.github.io/bmad-module-ultracode-goal/cross-session-recall/>.
51
51