bmad-module-ultracode-goal 2.2.0 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/README.md +12 -4
  3. package/docs/_internal/RELEASING.md +3 -2
  4. package/docs/architecture.md +6 -6
  5. package/docs/comparison.md +25 -25
  6. package/docs/gate-model.md +1 -1
  7. package/docs/getting-started.md +9 -5
  8. package/docs/how-it-works.md +5 -5
  9. package/docs/index.md +1 -1
  10. package/docs/operating-tips.md +1 -1
  11. package/docs/troubleshooting.md +6 -3
  12. package/docs/why-ultracode-goal.md +3 -3
  13. package/package.json +6 -2
  14. package/skills/ucg-formalize/SKILL.md +11 -4
  15. package/skills/ucg-resolve/SKILL.md +4 -4
  16. package/skills/ucg-status/SKILL.md +21 -8
  17. package/skills/ultracode-goal/SKILL.md +4 -4
  18. package/skills/ultracode-goal/assets/module.yaml +1 -1
  19. package/skills/ultracode-goal/references/define-done.md +3 -1
  20. package/skills/ultracode-goal/references/execute.md +16 -16
  21. package/skills/ultracode-goal/references/finalize.md +6 -5
  22. package/skills/ultracode-goal/references/gate.md +18 -12
  23. package/skills/ultracode-goal/references/preflight.md +20 -12
  24. package/skills/ultracode-goal/scripts/drive_epic.py +11 -6
  25. package/skills/ultracode-goal/scripts/gate_trail.py +107 -18
  26. package/skills/ultracode-goal/scripts/headless_envelope.py +20 -6
  27. package/skills/ultracode-goal/scripts/hooks/budget_stop.py +41 -22
  28. package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +26 -6
  29. package/skills/ultracode-goal/scripts/preflight_check.py +237 -12
  30. package/skills/ultracode-goal/scripts/status_render.py +96 -19
  31. package/tools/cli/lib/platform-codes.yaml +1 -1
  32. package/tools/cli/lib/ui.js +1 -1
  33. package/tools/validate-docs-links.js +302 -29
@@ -18,8 +18,8 @@
18
18
  {
19
19
  "name": "bmad-module-ultracode-goal",
20
20
  "source": "./",
21
- "description": "Supercharges BMAD with Claude Code Goal Mode, Auto Mode, and Auto Memory: autonomous Epic execution to a machine-checked, TEA-gated Definition-of-Done. Execute Epics. Accumulate Knowledge. Deliver Outcomes.",
22
- "version": "2.2.0",
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": "2.3.0",
23
23
  "author": {
24
24
  "name": "Armel"
25
25
  },
package/README.md CHANGED
@@ -16,7 +16,7 @@
16
16
  [![Docs](https://img.shields.io/badge/docs-online-green)](https://armelhbobdad.github.io/bmad-module-ultracode-goal/)
17
17
  [![GitHub stars](https://img.shields.io/github/stars/armelhbobdad/bmad-module-ultracode-goal?style=social)](https://github.com/armelhbobdad/bmad-module-ultracode-goal/stargazers)
18
18
 
19
- **Built for [Claude Code](https://claude.com/product/claude-code), and only Claude Code.** UCG composes `/goal`, Auto Mode, Auto Memory, and runtime hooks; the autonomous run itself requires Claude Code.
19
+ **Built for [Claude Code](https://claude.com/product/claude-code), and only Claude Code.** UCG composes Auto Mode, Auto Memory, runtime hooks, and git branches, and writes each story's Definition-of-Done as a `/goal`-style condition; the autonomous run itself requires Claude Code.
20
20
 
21
21
  _UCG is a standalone [BMAD](https://github.com/bmad-code-org/BMAD-METHOD) module that delivers a BMAD Epic end to end without a babysitter. It preflights to a remediated green light, turns acceptance criteria into executable tests with the Test Architect (TEA), and advances a story only when a deterministic script reads `PASS` from TEA's gate artifact, not when the model decides it feels done._
22
22
 
@@ -64,13 +64,21 @@ The `gate_status` comes straight from TEA's artifact: `gate_eval.py` never re-de
64
64
 
65
65
  Requires [Claude Code](https://claude.com/product/claude-code) (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.
66
66
 
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
+
69
+ | Component | Version | Note |
70
+ | --- | --- | --- |
71
+ | Claude Code | 2.1.301 | Attended, Auto Mode; the run resumed a preflight first started on 2.1.291 |
72
+ | BMAD Method | 6.12.0 | Installed with `--shims`, so `bmad-create-story` and `bmad-dev-story` are present |
73
+ | TEA (Test Architect) | 1.27.2 | Epic test-design, then a per-story trace gate read by `gate_eval.py` |
74
+
67
75
  ```bash
68
76
  npx bmad-module-ultracode-goal install
69
77
  ```
70
78
 
71
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.
72
80
 
73
- > **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. 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](./docs/getting-started.md#hook-security)). See [SECURITY.md](SECURITY.md) for exactly what they execute and how to remove them.
74
82
 
75
83
  ## Quick Start
76
84
 
@@ -94,7 +102,7 @@ A skeptical reader is probably already running one of these. Here is the honest
94
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 |
95
103
  | Preflight autonomy gate | hard-gate to remediated green (intervention budget 0)| ad hoc, per story | none | none: CI runs post-hoc |
96
104
  | Invariants enforcement | `PreToolUse` hooks in `settings.local.json` | your attention | prompt text (context, not a gate)| CI checks, after the fact |
97
- | Rollback | git: epic branch, one commit per green story | manual | `/rewind` (misses Bash changes) | revert after merge |
105
+ | Rollback | git: epic branch, code + evidence commit per story | manual | `/rewind` (misses Bash changes) | revert after merge |
98
106
  | Knowledge capture | Auto Memory + CLAUDE.md split at Finalize | none structured | none structured | none |
99
107
 
100
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.**
@@ -153,7 +161,7 @@ UCG is a conductor over primitives it does not replace. It builds on:
153
161
  | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
154
162
  | [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD) | The epic toolbox UCG orchestrates (sprint planning, story creation, dev, review) |
155
163
  | [TEA Test Architect](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) | Machine-checked quality gates: test-design, ATDD, NFR, trace; the gate artifact |
156
- | [Claude Code](https://claude.com/product/claude-code) | `/goal`, Auto Mode, Auto Memory, hooks, and git branches, the primitives UCG composes |
164
+ | [Claude Code](https://claude.com/product/claude-code) | Auto Mode, Auto Memory, hooks, and git branches, the primitives UCG composes; `/goal` if you start one yourself |
157
165
 
158
166
  ## Contributing
159
167
 
@@ -51,12 +51,13 @@ These must exist before the first `main`-dispatch release. Order matters.
51
51
 
52
52
  ### 1. Required-check contexts must exist
53
53
 
54
- Branch-protection rulesets can only require status checks that have reported at least once. Open any PR (or dispatch `quality.yaml` manually) so these eight contexts exist:
54
+ Branch-protection rulesets can only require status checks that have reported at least once. Open any PR (or dispatch `quality.yaml` manually) so these nine contexts exist:
55
55
 
56
56
  ```text
57
57
  prettier
58
58
  eslint
59
59
  markdownlint
60
+ lintlang
60
61
  validate (ubuntu-latest)
61
62
  validate (windows-latest)
62
63
  python (ubuntu-latest)
@@ -68,7 +69,7 @@ This list is the setup seed, not the source of truth: the ruleset is. Whenever `
68
69
 
69
70
  ### 2. Main-branch ruleset
70
71
 
71
- Create a ruleset on `main` requiring the seven contexts above, with `bypass_actors` = Admin RepositoryRole, `bypass_mode: pull_request`. Then record its id in the repo variable the workflow reads:
72
+ Create a ruleset on `main` requiring the contexts above, with `bypass_actors` = Admin RepositoryRole, `bypass_mode: pull_request`. Then record its id in the repo variable the workflow reads:
72
73
 
73
74
  ```bash
74
75
  gh api /repos/armelhbobdad/bmad-module-ultracode-goal/rulesets --jq '.[] | {id, name}'
@@ -3,15 +3,15 @@ title: Architecture
3
3
  description: "How UltraCode Goal works as a conductor over BMAD, TEA, and Claude Code primitives: the three enforcement layers, file layout, and customization resolution."
4
4
  ---
5
5
 
6
- UltraCode Goal is a conductor. It orchestrates the installed BMAD epic toolbox and the TEA gates, composing Claude Code primitives (`/goal`, Auto Mode, Auto Memory, hooks, git branch isolation) and replaces none of them. This page covers the conductor model, the three enforcement layers in depth, the file layout, customization resolution, and why the hooks live where they do.
6
+ UltraCode Goal is a conductor. It orchestrates the installed BMAD epic toolbox and the TEA gates, composing Claude Code primitives (Auto Mode, Auto Memory, hooks, git branch isolation) and replaces none of them. This page covers the conductor model, the three enforcement layers in depth, the file layout, customization resolution, and why the hooks live where they do.
7
7
 
8
8
  ## The conductor model
9
9
 
10
10
  The skill owns no implementation logic of its own for building features or running tests. What it owns is the *order*, the *gates*, and the *enforcement*. It delegates:
11
11
 
12
- - **Epic toolbox**: `bmad-sprint-planning`, `bmad-create-story`, `bmad-dev-story`, `bmad-code-review`, `bmad-correct-course`, `bmad-retrospective`.
12
+ - **Epic toolbox**: `bmad-sprint-planning`, `bmad-create-story`, `bmad-dev-story`, `bmad-code-review`, `bmad-correct-course`, `bmad-retrospective`. On BMAD Method 6.12 or later, `bmad-create-story` and `bmad-dev-story` are deprecated shims that a fresh install leaves out unless asked for (`--shims`); preflight refuses to launch without them.
13
13
  - **TEA gates**: `bmad-testarch-framework`, `-ci`, `-test-design`, `-atdd`, `-automate`, `-test-review`, `-nfr`, `-trace`.
14
- - **Claude Code primitives**: the `/goal` loop drives execution; Auto Mode and ultracode session effort make the unattended run possible; Auto Memory carries learnings forward; hooks enforce invariants; git branches provide isolation and rollback.
14
+ - **Claude Code primitives**: each story is driven against a written `/goal`-style condition (only an operator can start a live `/goal`); Auto Mode and ultracode session effort make the unattended run possible; Auto Memory carries learnings forward; hooks enforce invariants; git branches provide isolation and rollback.
15
15
 
16
16
  Because it is a conductor, the truth of "is this done" lives in the artifacts its delegates produce, not in the conductor's own reasoning. That is the whole design: the model arranges the work, but a script reads the verdict.
17
17
 
@@ -21,20 +21,20 @@ These are the module's non-negotiables. Each exists because the documented mecha
21
21
 
22
22
  ### 1. Deterministic gate truth
23
23
 
24
- `scripts/gate_eval.py` reads TEA's `gate-decision.json` and maps its gate status to a routing verdict (`PASS`/`WAIVED` → advance, `CONCERNS` → defer, `FAIL` → reloop, `NOT_EVALUATED` → escalate). It never re-derives TEA's thresholds and never reads the transcript. The `/goal` evaluator that drives execution can only see what the run surfaces, it cannot open the gate file, so it is structurally incapable of being the completion authority. The script is. In production, two extra signals can only downgrade an `advance`, never lift a lower verdict; in both profiles a `scope=scoped` tests-ran marker caps a story-moving verdict at `reloop`, so a scoped re-loop sweep can never advance a story. See the [gate model](./gate-model.md) for the full mapping diagram, thresholds, and the fail-closed contract.
24
+ `scripts/gate_eval.py` reads TEA's `gate-decision.json` and maps its gate status to a routing verdict (`PASS`/`WAIVED` → advance, `CONCERNS` → defer, `FAIL` → reloop, `NOT_EVALUATED` → escalate). It never re-derives TEA's thresholds and never reads the transcript. A `/goal` evaluator, when an operator runs one, can only see what the run surfaces, it cannot open the gate file, so it is structurally incapable of being the completion authority. The script is. In production, two extra signals can only downgrade an `advance`, never lift a lower verdict; in both profiles a `scope=scoped` tests-ran marker caps a story-moving verdict at `reloop`, so a scoped re-loop sweep can never advance a story. See the [gate model](./gate-model.md) for the full mapping diagram, thresholds, and the fail-closed contract.
25
25
 
26
26
  ### 2. Hooks as invariants
27
27
 
28
28
  A set of invariants must hold before the runtime lets a tool call through, and none of them can live in memory, which is context the model may or may not weigh:
29
29
 
30
30
  - **`scripts/hooks/guard_pretooluse.py`** (PreToolUse): inspects each `git commit`/`git push` and enforces six invariants. It denies the command on a protected branch; denies a `git commit` when no tests-ran marker (`<impl-artifacts>/.tests-ran-<story_id>`) exists for the current story; denies it when that marker's `baseline=<sha>` does not match the SHA the story recorded at start; denies it when the staged index is empty or unreadable; and denies it, when armed with `ULTRACODE_TEST_ARTIFACTS`, while the staged content of a checklist-enumerated acceptance test still contains `test.skip(`. A sixth invariant is not about git at all: it runs for every tool call, and while a run is active it denies claude-mem MCP calls and filesystem reach into `.claude-mem` unless the Cross-Session Recall latch is green. It returns a `deny` decision in the hook JSON and also exits 2 with the reason on stderr so older clients that ignore the JSON still block. The marker, freshness, staged-index, and recall-latch checks fail **closed**, denying on an input they cannot read. Two do not: the protected-branch check fails **open** when `git rev-parse` cannot report a branch, and the un-skip proof is out of scope entirely when `ULTRACODE_TEST_ARTIFACTS` is unset. The protected-branch check is also scoped to the **session's** working directory rather than the repository the command names, so it denies a `git commit`/`git push` aimed at another checkout whenever the session's own repo is on a protected branch.
31
- - **`scripts/hooks/budget_stop.py`** (Stop): counts turns for the current story against `max_turns_per_story`. On overrun it writes an escalation marker and surfaces a message, then **lets the stop proceed**. Its documented limitation: a Stop hook fires only when Claude is already trying to stop, so it cannot interrupt a `/goal` condition mid-turn. The in-condition "stop after N turns" clause and the gate's re-loop budget are the real bounds; this hook is the third, defensive layer.
31
+ - **`scripts/hooks/budget_stop.py`** (Stop): counts turns for the current story against `max_turns_per_story`. On overrun it writes an escalation marker and surfaces a message, then **lets the stop proceed**. Its documented limitation: a Stop hook fires only when Claude is already trying to stop, so it cannot interrupt a `/goal` condition mid-turn. Its count advances once per Stop, so it cannot see re-loops spent inside a single response. The conductor reads it before a story starts and before each re-loop, where the gate's re-loop budget turns a re-loop that would exceed the ceiling into `escalate`. The in-condition "stop after N turns" clause binds only an operator's own `/goal`, since the conductor cannot start one. This hook itself is the recorder. The conductor promotes its marker to a `budget-overrun` escalation only when the story's gate escalates it on that count; a story that advances gets a sizing note instead.
32
32
 
33
33
  Both hooks read their config from env first (so the conductor injects per-run values) and fall back to hardcoded defaults (`main`/`master`, `25`, `ultracode/epic-`). Because of that fallback, a `customize.toml` override **silently no-ops at the enforcement layer** unless the conductor passes it through the hook env, so preflight injects `ULTRACODE_PROTECTED_BRANCHES`, `ULTRACODE_IMPL_ARTIFACTS`, `ULTRACODE_MAX_TURNS`, `ULTRACODE_EPIC_BRANCH_PREFIX`, and `ULTRACODE_TEST_ARTIFACTS`.
34
34
 
35
35
  ### 3. Budget enforcement
36
36
 
37
- A runaway story is bounded by three layers in order of authority: the **in-condition** "…or stop after N turns" clause inside the `/goal` condition (the real in-loop bound), the **gate re-loop budget** (a `reloop` that would exceed `max_turns_per_story` becomes `escalate`), and the **Stop hook** as the defensive backstop described above. Rollback is git, not `/rewind` (an Epic branch off a protected branch, one commit per green story) 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 evidence commit) because `/rewind` checkpoints miss the Bash-driven changes that make up the run.
38
38
 
39
39
  ## File layout
40
40
 
@@ -3,13 +3,13 @@ title: UCG vs bmad-loop
3
3
  description: An honest, side-by-side comparison of UltraCode Goal and bmad-code-org's bmad-loop orchestrator (formerly bmad-auto), including where bmad-loop is the better choice and which to reach for when.
4
4
  ---
5
5
 
6
- Both UltraCode Goal (UCG) and [bmad-loop](https://github.com/bmad-code-org/bmad-loop) (formerly bmad-auto; renamed at v0.8.0) automate the BMAD implementation phase without a babysitter. They are siblings, not clones: they make opposite bets on where the control loop lives and how completion is judged. This page compares them honestly, including the places where bmad-loop is the better tool.
6
+ Both UltraCode Goal (UCG) and [bmad-loop](https://github.com/bmad-code-org/bmad-loop) (formerly bmad-auto; renamed at v0.8.0, with the rename shims removed at v0.10.0: a project still on bmad-auto migrates via v0.9.1, the last release carrying them) automate the BMAD implementation phase without a babysitter. They are siblings, not clones: they make opposite bets on where the control loop lives and how completion is judged. This page compares them honestly, including the places where bmad-loop is the better tool.
7
7
 
8
- Snapshot: UCG v2.0.0 and bmad-loop v0.9.1, both released on 2026-08-02. Both projects are young and moving fast.
8
+ Snapshot: UCG v2.2.0 (released 2026-08-15) and bmad-loop v0.10.0 (released 2026-08-14). Both projects are young and moving fast.
9
9
 
10
- bmad-loop's v0.9.1 is a compatibility hotfix rather than new capability: BMAD-METHOD renamed its dev primitive from `bmad-dev-auto` to `bmad-build-auto`, and bmad-loop now resolves the primitive on disk so a project on either era validates and runs. Notably it *refuses* the forwarding shim upstream left behind, because that shim's migration prompt is interactive and would halt an unattended session with nothing written to disk, and it added checks for a worktree that could not be given its upstream skills. UCG is not affected by that rename: it orchestrates `bmad-dev-story`, not the auto primitive. The substantive capability release remains v0.9.0 (2026-07-21), which added a `stories.yaml` planning mode with per-story checkpoints, patch-restore escalation recovery, a pluggable multiplexer-backend registry, verify-gate integrity fixes, a graceful stop that finishes the in-flight item, an active-agent indicator, an OpenCode adapter driven over HTTP rather than a multiplexer, and schema-versioned `--json` documents for eight commands.
10
+ bmad-loop's v0.10.0 is a substantive release cut from main, which its own notes say has not been released since v0.9.0 and does not descend from v0.9.1; the 0.9.x hotfix line (the `bmad-build-auto` primitive resolution and the `skills.base-shim` refusal of upstream's interactive forwarding shim) is brought forward onto main alongside new capability. The headlines: a story owing human-only external actions (a DNS record, an API key) can commit what an agent can do, park at `awaiting-operator`, and be completed later by a new `bmad-loop confirm` command, with the park record traveling in the story's own commit so confirm works from any clone; a deferred-work entry's `gate:` line now hard-blocks the stories it names in both `validate` and `run`, and a story can close ledger entries at its commit via `closes_deferred:`; hook events (the run's control plane) and resume's config baseline move out of the agent-writable project tree into XDG state, part of an agent-tamper defense family the notes candidly call incomplete against a deliberate bypass; coding-CLI adapter classes can ship out-of-tree against a registry, listed by a new `adapters` command; the per-story token budget is re-checked at every session boundary (still advisory); and `confirm` joins the schema-versioned `--json` family. UCG is not affected by the BMAD-METHOD primitive rename: it orchestrates `bmad-dev-story`, not the auto primitive (though BMAD-METHOD 6.12 makes `bmad-dev-story` itself an opt-in shim; see [Prerequisites](./getting-started.md#prerequisites)).
11
11
 
12
- UCG reached v2.0.0 on 2026-08-02. Its headline is unglamorous and worth stating plainly: a quality scan paired the usual prose review with critics reading the Python directly, and nine high-severity defects survived independent reproduction. Six were fail-opens, cases where the module could report work passed that it never actually checked, including a commit guard bypassable by any shell compound form, an NFR audit reading `NOT_ASSESSED` that passed the production gate, and a readiness kernel scoring `ready` on an unparseable sprint board. A seventh was reachability: the three companion skills below shipped nested one directory too deep for the skill loader, so `/ucg-formalize`, `/ucg-resolve` and `/ucg-status` returned `Unknown skill` for their entire existence. All are fixed, each with a test that fails against the previous implementation.
12
+ UCG reached v2.2.0 on 2026-08-15. The release is re-loop economics, distilled from a measured story that took seven gate cycles: the re-loop route now generalizes each finding to its defect class against a per-Epic ledger before fixing (five of that story's six reviews had re-found one class, one seam over each time); mid-loop sweeps may scope to the affected set while the gate refuses to advance any story whose marker does not prove a full-scope sweep; Stage-5 assessors measure a git worktree of the commit under assessment instead of the shared tree, with outputs pinned to the main tree; a delta cycle profile re-runs only the previously failed assessor dimension and is capped so it can never advance; a tracked mutation runner (`mutate_check.py`) proves every new guard red-able before the gate, its ledger leading with survivors; and heartbeat/stall sidecars timestamp every loop boundary so dead air becomes a record. The new gate flags are additive: their JSON keys appear only when the flags are passed, so pre-flag invocations print the shape they always did. (v2.1.0 and v2.0.0, the computed epic roll-up and the nine-defect fail-open closure, are in the [changelog](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/CHANGELOG.md).)
13
13
 
14
14
  Treat every line below as a point-in-time reading of two *released* versions, and verify the current state for yourself (links at the bottom); both projects' main branches run well ahead of their tags.
15
15
 
@@ -17,7 +17,7 @@ Treat every line below as a point-in-time reading of two *released* versions, an
17
17
 
18
18
  bmad-loop puts the control loop in **plain Python, outside the agent**. A deterministic orchestrator picks the next story, spawns a fresh, disposable coding-agent session (over tmux by default) for each step, watches structured hook events the session writes, and decides retries, gates, and completion in code. No LLM sits in the control loop.
19
19
 
20
- UCG puts the control loop **inside Claude Code**. The run is a Claude Code skill that composes `/goal`, Auto Mode, Auto Memory, and runtime hooks. The per-story loop is paced by Claude Code's `/goal` evaluator (an LLM), while the binding completion verdict is a deterministic script (`gate_eval.py`) that reads the Test Architect's (TEA) gate artifact.
20
+ UCG puts the control loop **inside Claude Code**. The run is a Claude Code skill that composes Auto Mode, Auto Memory, and runtime hooks, and writes each story's Definition-of-Done as a `/goal`-style condition. The per-story loop is paced by the conductor, an LLM (a `/goal` evaluator paces it too when the operator starts one), while the binding completion verdict is a deterministic script (`gate_eval.py`) that reads the Test Architect's (TEA) gate artifact.
21
21
 
22
22
  The consequence cascades: bmad-loop is a tool you run beside any supported agent; UCG is a capability that lives within one specific agent.
23
23
 
@@ -25,36 +25,36 @@ The consequence cascades: bmad-loop is a tool you run beside any supported agent
25
25
 
26
26
  | Dimension | bmad-loop | UltraCode Goal (UCG) |
27
27
  |---|---|---|
28
- | Runtime | External Python process plus a terminal multiplexer, tmux being the bundled default (the OpenCode profile runs over HTTP with no multiplexer window); Linux, macOS, or WSL (native Windows is planned) | A skill inside Claude Code; no daemon, no multiplexer, no session to attach to. Runs wherever Claude Code does, given Python 3.11+, `uv`, and `git`, and a Claude Code new enough for `/goal`, dynamic workflows, and Auto Memory, the three versions preflight pins and refuses to launch below. One optional exception: a ~900-line driver script that runs one session per story on long Epics |
29
- | Control loop | Deterministic Python, no LLM in the loop | LLM-paced `/goal` spine with a deterministic completion gate |
28
+ | Runtime | External Python process plus a terminal multiplexer, tmux being the bundled default (the OpenCode profile runs over HTTP with no multiplexer window); Linux, macOS, or WSL; native Windows in progress (a psmux backend ships in-tree behind a real-Windows live gate, not yet claimed as shipped) | A skill inside Claude Code; no daemon, no multiplexer, no session to attach to. Runs wherever Claude Code does, given Python 3.11+, `uv`, and `git`, and a Claude Code new enough for `/goal`, dynamic workflows, and Auto Memory, the three versions preflight pins and refuses to launch below. One optional exception: a ~900-line driver script that runs one session per story on long Epics |
29
+ | Control loop | Deterministic Python, no LLM in the loop | LLM-paced spine with a deterministic completion gate |
30
30
  | Agent / CLI | claude, codex, gemini, copilot, antigravity, opencode (mix per stage) | Claude Code only |
31
31
  | Scope | Implementation phase: `backlog` and `ready-for-dev` stories from `sprint-status.yaml`, or opt-in from a typed `stories.yaml`, through dev, review, verify, commit | Whole Epic, six stages: ingest and scope, planning-readiness preflight, ATDD (acceptance-test-driven development) test generation, execute, TEA gate, finalize, whose terminal step is a workflow health check that the skill's own table numbers as a seventh stage |
32
- | Completion authority | Checks on the spec and result artifacts, a proof-of-work diff, and your test and lint commands; opt-in TEA gate steps via a bundled plugin (advisory by default) | TEA quality gate: `gate-decision.json` (P0/P1/overall), combined in the default profile with NFR and test-review artifacts, read fail-closed by `gate_eval.py` |
33
- | Test strategy | Your `[verify].commands` plus adversarial review hunters; opt-in TEA test-design and ATDD workflows via the bundled plugin | ATDD: acceptance criteria become executable red-phase tests driven to green; TEA traceability |
34
- | Pre-launch gate | `validate`, a registry of named checks across BMAD config, policy, sprint-status, git, multiplexer and process host, CLI binary and profile, hook registration, base skills, and stories-mode manifest and dispatch; v0.9.1 added `skills.base-shim`, which refuses the forwarding shim BMAD-METHOD's rename left behind | A mechanical preflight script plus a readiness check and a semantic scan that refuse to launch on an undecided product or architecture decision |
35
- | Observability | A live terminal dashboard (built with Textual): runs table, attach to live sessions, journal, cost-weighted token totals, an active-agent indicator naming what is driving the current stage, plus schema-versioned `--json` documents for scripted readers | Files plus a read-only renderer: `.decision-log.md`, a `run-status.json` heartbeat, a transcript ticker that prints each gate verdict, a `gate-trail.md` evidence trail at finalize, and `/ucg-status` to assemble all of it on demand |
36
- | Deferred work | A triage-and-execute **sweep** engine plus a decisions workflow | A ledger the gate only appends to, surfaced at finalize and readable mid-run through `/ucg-status`, with `/ucg-resolve` able to mark an answered decision row resolved; no execute engine |
37
- | Escalation | Typed (CRITICAL / PREFERENCE) plus an interactive resolve agent that re-arms the spec and re-applies the saved patch, so review resumes on the restored diff | An `escalate` verdict, a typed `escalation-<story-id>.json` sidecar (`source`, `kind`, `decision_needed`, `evidence`), an `on_escalation` hook, a path-pinned `run-result.json` for every headless terminal exit that got far enough to resolve its artifacts path, not only blocked ones, and `/ucg-resolve` to answer what is pending; resume from the decision log |
38
- | Isolation | In place by default; opt-in git worktree per story or bundle, merged back locally | None (stories run sequentially in one session; the experimental `--parallel` worktree mode was retired) |
32
+ | Completion authority | Checks on the spec and result artifacts, a proof-of-work diff, and your test and lint commands; opt-in TEA gate steps via a bundled plugin (advisory by default) | TEA quality gate: `gate-decision.json` (P0/P1/overall), combined in the default profile with NFR and test-review artifacts, read fail-closed by `gate_eval.py`; since v2.2.0 the verdict is also capped by evidence scope, so a story only advances off a full-scope sweep (`--tests-ran`) and a delta-profile mid-loop gate can never advance (`--cycle-profile`) |
33
+ | Test strategy | Your `[verify].commands` plus adversarial review hunters; opt-in TEA test-design and ATDD workflows via the bundled plugin | ATDD: acceptance criteria become executable red-phase tests driven to green; TEA traceability; a tracked mutation runner (`mutate_check.py`) proves every guard a story adds red-able before the gate, with a generated ledger that leads with the mutations that survived |
34
+ | Pre-launch gate | `validate`, a registry of named checks whose id families at v0.10.0 span BMAD config, adapter (binary, profile, kind, out-of-tree), deferred work (including an unreadable ledger now failing rather than warning), git, hooks, host, multiplexer, notifications, operator park records, policy, queue (sprint-status and stories manifest), and skills, where `skills.base-shim` still refuses the forwarding shim BMAD-METHOD's rename left behind | A mechanical preflight script plus a readiness check and a semantic scan that refuse to launch on an undecided product or architecture decision |
35
+ | Observability | A live terminal dashboard (built with Textual): runs table, attach to live sessions, journal, cost-weighted token totals, an active-agent indicator naming what is driving the current stage, plus schema-versioned `--json` documents for scripted readers | Files plus a read-only renderer: `.decision-log.md`, a `run-status.json` heartbeat, per-step `.heartbeat`/`.stall` sidecars that timestamp every story-loop boundary and turn an unexplained gap into a record at resume, a transcript ticker that prints each gate verdict, a `gate-trail.md` evidence trail at finalize, and `/ucg-status` to assemble all of it on demand |
36
+ | Deferred work | A triage-and-execute **sweep** engine plus a decisions workflow; since v0.10.0 a ledger entry's `gate:` line hard-blocks the stories it names in both `validate` and `run`, and a story can close entries at its commit via `closes_deferred:` | A ledger the gate only appends to, surfaced at finalize and readable mid-run through `/ucg-status`, with `/ucg-resolve` able to mark an answered decision row resolved; no execute engine |
37
+ | Escalation | Typed (CRITICAL / PREFERENCE) plus an interactive resolve agent that re-arms the spec and re-applies the saved patch, so review resumes on the restored diff; v0.10.0 adds a third outcome with no UCG equivalent, where a story owing human-only external actions commits what an agent can do, parks at `awaiting-operator`, and `bmad-loop confirm` completes it later from any clone | An `escalate` verdict, a typed `escalation-<story-id>.json` sidecar (`source`, `kind`, `decision_needed`, `evidence`), an `on_escalation` hook, a path-pinned `run-result.json` for every headless terminal exit that got far enough to resolve its artifacts path, not only blocked ones, and `/ucg-resolve` to answer what is pending; resume from the decision log |
38
+ | Isolation | In place by default; opt-in git worktree per story or bundle, merged back locally | At the gate: since v2.2.0, Stage-5 assessors measure a git worktree of the commit under assessment, with assessor outputs pinned to the main tree. Story execution itself stays sequential in one tree (the experimental `--parallel` worktree mode was retired) |
39
39
  | Extensibility | A plugin system (observe, veto, mutate) with bundled TEA and Unity plugins | `customize.toml` knobs, planning-shaping fragments, and two optional third-party integrations configured there, both off by default and neither able to touch a gate verdict: [claude-mem recall](./cross-session-recall.md) and a [graphify knowledge-graph refresh](./knowledge-graph-refresh.md) |
40
40
  | Self-improvement | Not shipped | A health check that files deduplicated GitHub issues about its own friction |
41
- | Maturity | First-party (bmad-code-org); v0.9.1, a compatibility hotfix over v0.9.0, whose headline was stable schema-versioned `--json` contracts that evolve additively; rich docs; CI + test suite | Community module; v2.0.0, which closes nine high-severity defects (six of them fail-opens in the completion path) and carries four breaking changes with migrations, over the v1.0.0 SemVer contract; docs site; CI + test suite |
41
+ | Maturity | First-party (bmad-code-org); v0.10.0, a substantive release bringing the 0.9.x hotfix line onto main plus operator parking, enforced deferred-work gates, and agent-tamper defenses; rich docs; CI + test suite | Community module; v2.2.0, re-loop economics from a measured seven-cycle post-mortem (defect-class generalization, scope-capped sweeps, worktree-isolated gating, a tracked mutation runner), additive over the v1.0.0 SemVer contract; docs site; CI + test suite |
42
42
  | License | MIT | MIT |
43
43
 
44
44
  ## Where bmad-loop is stronger
45
45
 
46
46
  This is a genuinely strong tool; pretending otherwise would make this page useless.
47
47
 
48
- 1. **A deterministic control loop.** Story selection, retry budgets, gates, and completion checks are ordinary Python, so they are debuggable, reproducible, and cost no tokens. UCG's `/goal` pacing is LLM-driven; its deterministic pieces (the per-story and epic-level gate reads, the preflight scripts, the commit-guard and budget hooks) bound the loop rather than run it. If you want zero LLM judgment in the orchestration itself, bmad-loop is the cleaner model.
48
+ 1. **A deterministic control loop.** Story selection, retry budgets, gates, and completion checks are ordinary Python, so they are debuggable, reproducible, and cost no tokens. UCG's pacing is LLM-driven; its deterministic pieces (the per-story and epic-level gate reads, the preflight scripts, the commit guard, and a budget hook that records turns but never blocks) bound the loop rather than run it, and only as far as those turn counts can see. If you want zero LLM judgment in the orchestration itself, bmad-loop is the cleaner model.
49
49
  2. **Agent portability.** It drives claude, codex, gemini, GitHub Copilot CLI, antigravity, or OpenCode, and can run dev on one model and review on another via per-stage profiles. UCG is deliberately Claude Code only.
50
50
  3. **Observability and control.** A live terminal UI (built with Textual) gives you a runs dashboard, a sprint tree, the deferred-work ledger, per-story token totals, attach-to-session, and a policy editor. UCG's window is files, the transcript, and a read-only `/ucg-status` render assembled from those same files: there is still no live view and no session to attach to.
51
51
  4. **A deferred-work engine, not just a ledger.** `bmad-loop sweep` triages the ledger against the real code, bundles cohesive work, executes it, and has a decisions workflow for the human calls. UCG appends to a ledger, surfaces it at the end, and can render it mid-run through `/ucg-status`; acting on it is still manual, and there is no execute engine.
52
52
  5. **Extensibility and reach.** It has a real plugin system (observe, veto, mutate the cycle) with bundled plugins: a TEA plugin that can add Test Architect workflows to its pipeline, and a Unity game-engine integration. UCG exposes configuration knobs, not a plugin API.
53
- 6. **Operational maturity.** It ships disk reclamation (clean and archive, retention windows, worktree teardown), cost-weighted token budgets that discount cache reads, and an adapter-authoring path for new CLIs, and it carries the backing of the bmad-code-org org.
53
+ 6. **Operational maturity.** It ships disk reclamation (clean and archive, retention windows, worktree teardown), cost-weighted token budgets that discount cache reads, and an adapter-authoring path for new CLIs (out-of-tree adapter classes against a registry since v0.10.0), and it carries the backing of the bmad-code-org org.
54
54
 
55
55
  ## Where UCG is stronger
56
56
 
57
- 1. **The TEA gate is the default, binding completion authority, not an opt-in layer.** UCG's completion authority is the Test Architect's gate: a traceability matrix that holds acceptance criteria to hard thresholds (P0 coverage at 100%, P1 at 90% or above, overall at 80% or above). UCG's default profile combines that verdict with an NFR (non-functional requirements) assessment and a test-review score, and `gate_eval.py` reads the result fail-closed: a missing or unreadable signal downgrades the verdict, never upgrades it. Since v0.5.0 the default sequential path also re-runs the full test, lint, and build suite on each story's committed HEAD before advancing, so a story that is green pre-commit but red once its new files are tracked cannot slip through to the gate.
57
+ 1. **The TEA gate is the default, binding completion authority, not an opt-in layer.** UCG's completion authority is the Test Architect's gate: a traceability matrix that holds acceptance criteria to hard thresholds (P0 coverage at 100%, P1 at 90% or above, overall at 80% or above). UCG's default profile combines that verdict with an NFR (non-functional requirements) assessment and a test-review score, and `gate_eval.py` reads the result fail-closed: a missing or unreadable signal downgrades the verdict, never upgrades it. Since v0.5.0 the default sequential path also re-runs the test, lint, and build suite on each story's committed HEAD before advancing, so a story that is green pre-commit but red once its new files are tracked cannot slip through to the gate; since v2.2.0 that re-verify runs at the cycle's declared scope, with the gate refusing to advance any story whose `.tests-ran` marker does not prove a full-scope sweep.
58
58
 
59
59
  bmad-loop can reach similar territory, but differently. Its default gate is checks on the spec and result artifacts, a proof-of-work diff (the commit must contain real changes since the story's baseline), and your test and lint commands; its bundled TEA plugin can add trace, NFR, and test-review steps before every commit. That plugin is opt-in, its gate steps ship advisory (non-blocking), and they fail open when an artifact is missing or unparseable. That gap narrowed in v0.9.0: at v0.8.1 bmad-loop's independent baseline-commit cross-check could not actually fire, because it read a spec key the dev skill does not write, so a spec claiming a stale or foreign baseline sailed through; v0.9.0 fixed it to accept either key and re-cut the test fixture that had been fabricating the missing one. The advisory-by-default and fail-open-on-missing-artifact properties of the TEA plugin's gate steps are unchanged. If you want acceptance-criterion-to-test traceability enforced by default, fail-closed, with nothing to configure, that is UCG's defining bet.
60
60
  2. **ATDD-first.** UCG turns each story's acceptance criteria into executable acceptance tests (scaffolded as red-phase `test.skip` placeholders) before any code is written, then un-skips them and drives them to green. The acceptance tests are a first-class generated artifact, not a by-product. One scope note, about what the generator *emits* rather than what it accepts: the TEA release installed here does detect a backend stack, but its scaffolds are Playwright and TypeScript, and the browser-recording path loads only for a frontend or fullstack project, so a stack with no JS or TS harness still gets nothing runnable. UCG's preflight therefore steers those runs to `--light`, where the story's acceptance criteria (not generated tests) are the trace oracle, or you author the acceptance tests in the stack's own harness. bmad-loop's default pipeline relies on whatever tests the dev skill writes while implementing, plus the test commands you supply; TEA test generation exists there only as an opt-in plugin step that runs after dev, not as the default path.
@@ -64,12 +64,12 @@ This is a genuinely strong tool; pretending otherwise would make this page usele
64
64
 
65
65
  ## What they share
66
66
 
67
- - A deterministic completion authority the model cannot talk its way past: bmad-loop's artifact, diff, and command checks; UCG's TEA gate read. One caveat on the UCG side, narrowed but not removed in v2.0.0: on a non-web stack, under either profile, the trace artifacts are agent-authored under strict honesty rules, so on that path the model writes the file the gate then reads and the guarantee is procedural rather than mechanical. What changed is that the substitution is no longer invisible: the gate now records `gate-provenance: tea` or `hand-authored` per story and the run report carries it, so a reader can tell which verdicts rested on artifacts the run produced for itself. Before that, an Epic could complete entirely on hand-authored gate files and read identically to one gated on TEA output.
68
- - Proof that the commit is real work, not a claim about work. bmad-loop cross-checks the diff against the story's baseline commit; UCG enforces the equivalent one layer down, in a `PreToolUse` hook that denies the `git commit` outright unless a tests-ran marker exists whose recorded baseline SHA matches the story's character for character, and unless the staged index is non-empty. That hook is only as good as its command parsing, which is worth stating because until v2.0.0 it was not: a commit wrapped in any shell compound form (`if`, a loop body, a subshell, a brace group) or placed after a background `&` classified as carrying no git write at all, skipping the protected-branch, marker, freshness and empty-index gates in one go. On a production run it also refuses a commit whose staged acceptance tests are still skipped, though that check reads `test.skip(` and so does nothing on the non-web stacks the ATDD note above steers to `--light`.
67
+ - A deterministic completion authority the model cannot talk its way past: bmad-loop's artifact, diff, and command checks; UCG's TEA gate read. One caveat on the UCG side, narrowed but not removed in v2.0.0: where TEA's trace cannot run, under either profile, the trace artifacts are agent-authored under strict honesty rules (on TEA 1.27.2 trace runs on any stack, a pytest project included, so this is now the fallback for older TEA builds), so on that path the model writes the file the gate then reads and the guarantee is procedural rather than mechanical. What changed is that the substitution is no longer invisible: the gate now records `gate-provenance: tea` or `hand-authored` per story and the run report carries it, so a reader can tell which verdicts rested on artifacts the run produced for itself. Before that, an Epic could complete entirely on hand-authored gate files and read identically to one gated on TEA output.
68
+ - Proof that the commit is real work, not a claim about work. bmad-loop cross-checks the diff against the story's baseline commit; UCG enforces the equivalent one layer down, in a `PreToolUse` hook that denies the `git commit` outright unless a tests-ran marker exists whose recorded baseline SHA matches the story's character for character, and unless the staged index is non-empty. That hook is only as good as its command parsing, which is worth stating because until v2.0.0 it was not: a commit wrapped in any shell compound form (`if`, a loop body, a subshell, a brace group) or placed after a background `&` classified as carrying no git write at all, skipping the protected-branch, marker, freshness and empty-index gates in one go. On a production run it also refuses a commit whose staged acceptance tests are still skipped, though that check reads `test.skip(` and so does nothing on the non-web stacks the ATDD note above steers to `--light`. Both projects are also hardening the same flank from opposite sides: v0.10.0 moved bmad-loop's hook events and resume baselines out of the agent-writable tree, a tamper-defense family its notes call incomplete against a deliberate bypass, and UCG's guard carries its own bypass history (the v2.0.0 compound-form fix).
69
69
  - Fresh-context review separated from implementation, to kill self-review anchoring bias, on both defaults with a caveat each: bmad-loop's separate session is gated by `review.trigger`, which defaults to `recommended` (set it to `always` for every story), and UCG runs a code-review pass on its production profile but none under `--light`.
70
- - Adversarial review passes, bounded so they cannot oscillate forever: bmad-loop by `max_review_cycles` (default 3), UCG by `max_turns_per_story`, where a re-loop that would exceed the budget escalates instead.
71
- - Optional git worktree isolation.
72
- - Resumable runs with a per-story budget: bmad-loop's is a cost-weighted token ceiling that discounts cache reads; UCG's is a turn cap, encoded in the `/goal` condition and enforced at the gate. UCG adds a second axis, `--max-stories N`, a per-invocation work bound whose exhaustion still ends the run `complete` with stories remaining, so that status means "this invocation finished", not "the Epic is done". Note the asymmetry: UCG has no token or cost bound at all, and `story_token_budget` is now a deprecated no-op.
70
+ - Adversarial review passes, bounded so they cannot oscillate forever: bmad-loop by `max_review_cycles` (default 3), UCG by `max_turns_per_story`, where a re-loop that would exceed the budget escalates instead (the count is the Stop hook's, once per response, so it cannot see re-loops inside one response).
71
+ - Git worktree use, aimed differently: bmad-loop's opt-in isolation runs each story or sweep bundle in its own worktree and merges back locally; UCG's Stage-5 gate measures a worktree of the commit under assessment while story execution stays in the main tree.
72
+ - Resumable runs with a per-story budget: bmad-loop's is a cost-weighted per-story budget that discounts cache reads (advisory, re-checked at every session boundary since v0.10.0) beside a per-session cap that can terminate; UCG's is a turn ceiling the Stop hook counts and the gate's re-loop budget checks before each re-loop (a count of Stops, once per response, so it cannot see re-loops inside one response). UCG adds a second axis, `--max-stories N`, a per-invocation work bound whose exhaustion still ends the run `complete` with stories remaining, so that status means "this invocation finished", not "the Epic is done". Note the asymmetry: UCG has no token or cost bound at all, and `story_token_budget` is now a deprecated no-op.
73
73
  - `sprint-status.yaml` as the shared planning ledger, and both build on BMAD-METHOD. Neither leaves it write-only to the BMAD skills any more: UCG's gate writes the story's `done` row at the `advance` route, and bmad-loop's orchestrator syncs the board itself.
74
74
 
75
75
  ## Which to reach for
@@ -87,6 +87,6 @@ Both tools change weekly, so re-check before you rely on anything above:
87
87
  - bmad-loop: its [README](https://github.com/bmad-code-org/bmad-loop), [docs/FEATURES.md](https://github.com/bmad-code-org/bmad-loop/blob/main/docs/FEATURES.md), and [docs/ROADMAP.md](https://github.com/bmad-code-org/bmad-loop/blob/main/docs/ROADMAP.md).
88
88
  - UCG: [How It Works](./how-it-works.md) and the [Gate Model](./gate-model.md).
89
89
 
90
- This snapshot was re-cut on 2026-08-02 against bmad-loop v0.9.1 and UCG v2.0.0, both released that day. Earlier cuts: 2026-07-28 (bmad-loop v0.9.0, UCG v1.0.0), 2026-07-12 (bmad-loop v0.8.1, UCG v0.5.1), and 2026-06-28 (bmad-auto v0.7.4, UCG v0.4.0), which predates the bmad-auto rename.
90
+ This snapshot was re-cut on 2026-08-15 against bmad-loop v0.10.0 (released 2026-08-14) and UCG v2.2.0 (released 2026-08-15). Earlier cuts: 2026-08-02 (bmad-loop v0.9.1, UCG v2.0.0, both released that day), 2026-07-28 (bmad-loop v0.9.0, UCG v1.0.0), 2026-07-12 (bmad-loop v0.8.1, UCG v0.5.1), and 2026-06-28 (bmad-auto v0.7.4, UCG v0.4.0), which predates the bmad-auto rename.
91
91
 
92
- One deliberate omission in this cut. Previous versions of this page stated a count of bmad-loop's registered `validate` checks. That number could not be reproduced from the v0.9.1 source without running their tool, so it has been replaced by the list of check families, which can be. A number nobody re-derives is a number that quietly goes stale, and this page has no business asserting a precise figure about someone else's project that its own author cannot check.
92
+ One deliberate omission in this cut. Previous versions of this page stated a count of bmad-loop's registered `validate` checks. That number could not be reproduced from the pinned source without running their tool, so it has been replaced by the list of check families, which can be (this cut re-derived that list from the check ids in the v0.10.0 source). A number nobody re-derives is a number that quietly goes stale, and this page has no business asserting a precise figure about someone else's project that its own author cannot check.
@@ -181,4 +181,4 @@ The same `PASS` gate, but with a test review scoring 74, downgrades to `reloop`;
181
181
 
182
182
  ## Why the `/goal` evaluator alone is insufficient
183
183
 
184
- The `/goal` loop that drives Execute ends with an evaluator confirming the success condition, but that evaluator only sees the transcript. It cannot open `gate-decision.json`. So it can confirm "the tests I was shown printed green" but not "TEA's deterministic gate read PASS against the traceability matrix and the NFR thresholds." Letting it be the completion authority would let the run grade itself from its own notes. `gate_eval.py` reads the file the model cannot author, which is exactly why it, and not the transcript evaluator, decides. See [why](./why-ultracode-goal.md) and the routing detail in [`references/gate.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/gate.md).
184
+ A `/goal` loop, when an operator runs one over Execute, ends with an evaluator confirming the success condition, but that evaluator only sees the transcript. It cannot open `gate-decision.json`. So it can confirm "the tests I was shown printed green" but not "TEA's deterministic gate read PASS against the traceability matrix and the NFR thresholds." Letting it be the completion authority would let the run grade itself from its own notes. `gate_eval.py` reads the file the model cannot author, which is exactly why it, and not the transcript evaluator, decides. See [why](./why-ultracode-goal.md) and the routing detail in [`references/gate.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/gate.md).
@@ -11,7 +11,7 @@ UltraCode Goal conducts BMAD and TEA skills and runs deterministic Python under
11
11
 
12
12
  | Tool | Required for | Install |
13
13
  |------|--------------|---------|
14
- | Claude Code | **The runtime: non-negotiable.** UCG composes `/goal`, Auto Mode, Auto Memory, and runtime hooks, which only exist in Claude Code; the autonomous run cannot execute anywhere else | <https://claude.com/product/claude-code> |
14
+ | 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 | <https://claude.com/product/claude-code> |
15
15
  | Node.js >= 22 | Installation, `npx` commands | <https://nodejs.org> |
16
16
  | Python >= 3.11 | The deterministic gate, preflight, and hook scripts (run via `uv`) | <https://www.python.org> |
17
17
  | `uv` | Running the module's Python scripts with automatic dependency management | <https://docs.astral.sh/uv/> |
@@ -20,7 +20,9 @@ UltraCode Goal conducts BMAD and TEA skills and runs deterministic Python under
20
20
  | A BMAD project with an Epic | The unit of delivery: a `_bmad/` install, a `sprint-status.yaml`, and at least one Epic with stories | see [docs.bmad-method.org](https://docs.bmad-method.org) |
21
21
  | TEA (Test Architect) | **The gate: non-negotiable.** UCG invokes the `bmad-testarch-*` skills to produce the `gate-decision.json` that `gate_eval.py` reads. Required in both profiles: `--light` still runs test-design and trace | <https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise> |
22
22
 
23
- The run also depends on recent Claude Code primitives: `/goal`, dynamic workflows, and Auto Memory. The preflight script version-gates these and reports a mechanical blocker if the installed Claude Code is below the minimum any of them needs (see [troubleshooting](./troubleshooting.md)).
23
+ The run also depends on recent Claude Code primitives: dynamic workflows and Auto Memory, plus `/goal` if you start one yourself. The preflight script version-gates these and reports a mechanical blocker if the installed Claude Code is below the minimum any of them needs (see [troubleshooting](./troubleshooting.md)).
24
+
25
+ **On BMAD Method 6.12 or later, install BMAD with `--shims`.** UltraCode Goal delegates story creation to `bmad-create-story` and implementation to `bmad-dev-story`. From 6.12, BMAD ships both as deprecated shims: a fresh install leaves them out unless asked for (`--shims`, or Yes at the installer's shim prompt), and an update removes them when told not to keep them (its prompt recommends No). While either is missing from `.claude/skills/`, preflight reports a non-remediable blocker and the run does not launch. To add them to an existing install, run `npx bmad-method@<version> install --directory . --shims --yes` from the project root, where `<version>` is the installed one (`installation.version` in `_bmad/_config/manifest.yaml`), so the fix does not also upgrade BMAD Method itself; the blocker's detail prints this command with the version filled in. Keep `--directory .`: without it the installer still asks for the directory despite `--yes`. With `--yes` the installer also takes newer minor and patch releases of the external modules it manages, TEA included; to hold one where it is, add `--pin <module>=<version>` with the `version` of that module's entry under `modules:` in the same manifest. BMAD Method 6.2 through 6.11 install both skills by default; earlier releases named them differently and need an upgrade.
24
26
 
25
27
  ## Install
26
28
 
@@ -36,7 +38,7 @@ Invoke the skill with one of its trigger phrases ("run an epic autonomously", "e
36
38
 
37
39
  1. **Name the Epic.** Stage 1 opens the floor: name the Epic, or drop any context (a story id, a branch, a paste of the Epic body). The skill fills the gaps from the BMAD artifacts. If `_bmad/` config, `sprint-status.yaml`, and any Epic are *all* absent, this is not a BMAD project; the skill says so and stops, pointing you at `bmad-bmb-setup` and `bmad-sprint-planning`.
38
40
  2. **Preflight runs.** Stage 2 is the autonomy gate. It runs a mechanical check (`preflight_check.py`), auto-remediates the fixable ambers (scaffolding the test framework, generating missing acceptance criteria, pre-creating TEA output dirs, and so on), then adds a semantic scan for undecided product or architecture decisions the script cannot see. The run launches **only** when the post-remediation intervention budget is zero and the semantic scan found no red blocker. A single undecided architecture decision stops the run here rather than letting an unattended run guess it.
39
- 3. **The launch briefing.** On an attended run, before the first unattended action the skill prints a one-screen briefing: what is about to run, the worst-case turn envelope, the autonomy line ("from here I will not ask you anything"), the kill switch (Ctrl-C, or delete the Epic branch; `/rewind` will not help), and where to watch (the run's `.decision-log.md` and `run-status.json`). One soft confirm crosses the line.
41
+ 3. **The launch briefing.** On an attended run, before the first unattended action the skill prints a one-screen briefing: what is about to run, the per-story turn ceiling (it sizes stories; it does not cap time or cost), the autonomy line ("from here I will not ask you anything"), the kill switch (Ctrl-C, or delete the Epic branch; `/rewind` will not help), and where to watch (the run's `.decision-log.md` and `run-status.json`). One soft confirm crosses the line.
40
42
 
41
43
  From there the run is autonomous: it defines done with TEA, executes each story to a green commit, gates each one deterministically, and finalizes with a run report and the deferred-work ledger. See [how it works](./how-it-works.md) for the full stage-by-stage narration and the routing diagram.
42
44
 
@@ -47,7 +49,7 @@ From there the run is autonomous: it defines done with TEA, executes each story
47
49
  | `--light` | Trace-only gate. Downscopes from the full TEA chain to `bmad-testarch-trace` plus `gate_eval.py --profile light`: no NFR/test-review AND. |
48
50
  | `--parallel` | Retired. The flag is still accepted so an old invocation does not error: the run logs one note that it was accepted and ignored, then executes the sequential `/goal` spine. |
49
51
  | `--yes` | Skips Stage 1's open-floor invite and the launch confirm. The launch briefing still prints. **Never** skips the hard preflight gate. |
50
- | `-H` | Headless. Runs non-interactively, never prompts (an unresolvable secret becomes a red blocker, not a question), and emits one JSON object at every exit point. |
52
+ | `-H` | Headless. Runs non-interactively, never prompts (an unresolvable secret becomes a red blocker, not a question), and emits one JSON object at every exit point the permission layer lets it reach (see [hook security](#hook-security)). |
51
53
  | `--retro` | Runs the close-out retrospective (`bmad-retrospective`). Interactive runs offer it at Epic close anyway; headless runs it only when `--retro` is passed. |
52
54
  | `--max-stories N` | Bounds this **invocation** to N stories, then finalizes normally (report, ledger, terminal JSON). It is a work bound, not a scope narrowing: in-scope stays every not-`done` story, so the next invocation resumes at the story this one stopped before. No Epic-level gate is authored while stories remain. See [one story per process](#one-story-per-process). |
53
55
 
@@ -77,4 +79,6 @@ Useful flags: `--limit N` caps how many sessions it spawns, retries included, `-
77
79
 
78
80
  ## Hook security
79
81
 
80
- 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 bounds a runaway story; 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.
82
+ 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.
83
+
84
+ **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.
@@ -12,7 +12,7 @@ UltraCode Goal runs an Epic through six stages, in order. Each stage routes to t
12
12
  | 1 | Ingest & Scope | one resolved Epic id, or stop |
13
13
  | 2 | Preflight | post-remediation budget == 0 and no red, or stop |
14
14
  | 3 | Define Done | every in-scope story has a red-phase atdd-checklist |
15
- | 4 | Execute | every story committed at green, or a turn-bound escalation |
15
+ | 4 | Execute | every story committed at green, or a resume already at the turn ceiling escalates |
16
16
  | 5 | Gate | the `gate_eval.py` verdict: advance / defer / reloop / escalate |
17
17
  | 6 | Finalize | terminal: report, ledger, memory capture |
18
18
 
@@ -40,7 +40,7 @@ flowchart TD
40
40
  S3 -->|"ATDD hard-halt on vague ACs"| S3
41
41
  S3 -->|"every story has red-phase atdd-checklist"| S4
42
42
  S4 -->|"every story committed at green"| S5
43
- S4 -->|"turn-bound escalation"| S5
43
+ S4 -->|"resume already at the turn ceiling: escalate"| S6
44
44
  S5 -->|"advance or defer"| S6
45
45
  S5 -->|"reloop: gate FAIL within budget"| Correct
46
46
  Correct --> S4
@@ -66,8 +66,8 @@ The one absence that hard-stops here: if `_bmad/` config **and** `sprint-status.
66
66
 
67
67
  This is the load-bearing gate, because after it the run goes unattended. The posture is **hard gate with auto-remediation**:
68
68
 
69
- 1. **Mechanical check**: `preflight_check.py` parses tool versions, git state, and file existence and returns a `budget` count of mechanical blockers (test framework absent, dirty tree, on a protected branch, Claude Code below the minimum versions). It does **not** decide semantic intervention.
70
- 2. **Auto-remediation pass**: clear each remediable blocker, then re-run the check so `budget` reflects the fixes: create the Epic branch when the run started on a protected branch (it is a remediable, budget-counted blocker, so it has to clear here rather than at arming), scaffold the test framework (`bmad-testarch-framework`), scaffold the CI quality pipeline (`bmad-testarch-ci`, production only, strictly *after* the framework), generate missing acceptance criteria (`bmad-create-story`), pre-create the TEA output dirs, ensure exactly one `project-context.md`, ensure `sprint-status.yaml` is present, force TEA **Create** mode, and prompt once (interactively) for any secrets.
69
+ 1. **Mechanical check**: `preflight_check.py` parses tool versions, git state, and file existence and returns a `budget` count of mechanical blockers (test framework absent, dirty tree, on a protected branch, a repository with nothing committed yet, Claude Code below the minimum versions, the BMAD story skills `bmad-create-story` and `bmad-dev-story` not installed). It does **not** decide semantic intervention.
70
+ 2. **Auto-remediation pass**: clear each remediable blocker, then re-run the check so `budget` reflects the fixes: create the Epic branch when the run started on a protected branch (it is a remediable, budget-counted blocker, so it has to clear here rather than at arming), scaffold the test framework (`bmad-testarch-framework`), scaffold the CI quality pipeline (`bmad-testarch-ci`, production only, strictly *after* the framework), generate missing acceptance criteria (`bmad-create-story`), pre-create the TEA output dirs, de-duplicate `project-context.md` when there is more than one (a missing one is logged, never generated), ensure `sprint-status.yaml` is present, force TEA **Create** mode, and prompt once (interactively) for any secrets.
71
71
  3. **Semantic intervention scan**: the part the script cannot do: read the PRD and ADR for undecided product/architecture decisions, contradictions, acceptance criteria that presuppose an unmade decision, or a story whose "done" is undefinable. Any such item is **RED** and cannot be auto-remediated, because the fix is a human decision.
72
72
 
73
73
  The run launches **only** when all hold: post-remediation `budget == 0`, the semantic scan found no RED, and ultracode session effort plus Auto Mode are on. Then the skill arms the environment: asserts the Epic branch off `epic_branch_prefix` (already created during remediation when the run started on a protected branch), merges the PreToolUse and Stop hooks into `.claude/settings.local.json` (asserting they are active, and injecting the resolved config into their env), and pre-populates the allowlist. On an attended run it prints the launch briefing and takes one soft confirm. See [`references/preflight.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/preflight.md).
@@ -78,7 +78,7 @@ 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) → `bmad-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` → commit at green (one commit per green story) → **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 loop is wrapped in a single `/goal` whose condition encodes the per-story Definition-of-Done and carries the literal "…or stop after N turns" escape clause. 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) → `bmad-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` → 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).
82
82
 
83
83
  ### Stage 5: Gate
84
84
 
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 is one git 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 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.
45
45
 
46
46
  ## Read the rest
47
47
 
@@ -73,7 +73,7 @@ The dangerous part is what it leaves behind. In the observed case the dead sessi
73
73
 
74
74
  **On any resume, believe the artifacts and the sprint-status row, never the story file's prose.** Check for the gate *file* before treating a story as gated.
75
75
 
76
- The correct recovery is to re-drive the story. The skill re-enters at Execute, re-measures the committed tree, produces the trace evidence (TEA's `bmad-testarch-trace`, or hand-authored to `gate_eval.py`'s shape on a stack where TEA's browser chain cannot run), and runs `gate_eval.py` for real. Because the dead session already committed, make sure the re-drive re-reads the story's existing baseline marker rather than regenerating it: a rebuilt baseline re-anchors the evidence range to a mid-story HEAD, and the trace then measures only the tail of the work.
76
+ The correct recovery is to re-drive the story. The skill re-enters at Execute, re-measures the committed tree, produces the trace evidence (TEA's `bmad-testarch-trace`, which on TEA 1.27.2 runs on any stack, or hand-authored to `gate_eval.py`'s shape where trace cannot run), and runs `gate_eval.py` for real. Because the dead session already committed, make sure the re-drive re-reads the story's existing baseline marker rather than regenerating it: a rebuilt baseline re-anchors the evidence range to a mid-story HEAD, and the trace then measures only the tail of the work.
77
77
 
78
78
  Do not hand-mark the story `done` on the strength of your own verification, however thorough: that substitutes your judgment for the gate and produces exactly the artifact-free "PASS" the tool exists to prevent.
79
79
 
@@ -32,13 +32,16 @@ flowchart TD
32
32
 
33
33
  **Symptom.** The run stops at Stage 2 (or, headless, emits `{"status":"blocked", ...}` with a one-line `reason`) and never launches.
34
34
 
35
- **What happened.** Preflight is a hard gate: the run launches only when the post-remediation mechanical `budget == 0` **and** the semantic scan found no RED. The auto-remediation pass clears the *fixable* mechanical blockers: it scaffolds the test framework, generates missing acceptance criteria, pre-creates the TEA output dirs, ensures one `project-context.md`, ensures `sprint-status.yaml`, and prompts once (interactively) for secrets, then re-runs the check.
35
+ **What happened.** Preflight is a hard gate: the run launches only when the post-remediation mechanical `budget == 0` **and** the semantic scan found no RED. The auto-remediation pass clears the *fixable* mechanical blockers: it scaffolds the test framework, generates missing acceptance criteria, pre-creates the TEA output dirs, ensures `sprint-status.yaml`, and prompts once (interactively) for secrets, then re-runs the check. The `project-context.md` count is advisory: preflight de-duplicates more than one, logs a missing one, and never blocks on it.
36
36
 
37
37
  **What stays red.** Some things the remediation pass cannot fix, by design:
38
38
 
39
39
  - **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
40
  - **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
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.
42
+ - **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
+ - **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
+ - **BMAD story skills not installed.** The run delegates story creation to `bmad-create-story` and implementation to `bmad-dev-story`, and on BMAD Method 6.12 or later both are deprecated shims: a fresh install leaves them out unless asked for (`--shims`, or Yes at the installer's shim prompt), and an update removes them when told not to keep them. The `bmad_skills` blocker is non-remediable: the run neither installs them nor works around them. Its detail names the fix; for a 6.12 install made without shims, that is `npx bmad-method@<version> install --directory . --shims --yes` from the project root. With `--yes` the installer also takes newer minor and patch releases of external modules such as TEA; add `--pin <module>=<version>` to hold one (see [Prerequisites](./getting-started.md#prerequisites)). The same check runs on every resume, so a BMAD update that removes them mid-Epic stops the next spawn instead of letting it improvise.
42
45
 
43
46
  The decision log carries the full blocker list with what each needs to clear. Read it, clear the items, re-run.
44
47
 
@@ -71,9 +74,9 @@ A per-story gate can return `reloop` with a `PASS` gate status when a cap fired
71
74
 
72
75
  **Symptom.** A story stops re-looping; an escalation marker (`<impl-artifacts>/.escalation-<story>.md`) appears; the run surfaces a budget message.
73
76
 
74
- **What happened.** A runaway story is bounded three ways. The real in-loop bound is the literal "…or stop after N turns" clause inside the `/goal` condition. The gate's re-loop budget is deterministic: a `reloop` that would exceed `max_turns_per_story` becomes an `escalate` instead. The **Stop** hook (`budget_stop.py`) is the defensive third layer: it counts turns and, on overrun, writes the escalation marker and lets the stop proceed.
77
+ **What happened.** Three layers can bound a runaway story. The literal "…or stop after N turns" clause inside a `/goal` condition binds only when you started a `/goal` whose own condition carries it, and then it bounds the session: the conductor cannot start one itself. Otherwise the bound is the gate's re-loop budget: before each re-loop the conductor reads the hook's recorded turn count, and a `reloop` that would exceed `max_turns_per_story` becomes an `escalate` instead. That count advances once per response, so re-loops spent inside one response do not move it, and for `drive_epic.py` spawns the `--session-timeout` wall clock is the backstop. The **Stop** hook (`budget_stop.py`) is the defensive third layer: it counts turns and, on overrun, writes the escalation marker and lets the stop proceed. The marker records the count and does not stop the drive, so the story goes on toward its gate. It becomes an escalation only when the gate escalates the story on that count. A story that passes its gate gets a sizing note in the decision log and the run report instead: no escalation, no ping, and nothing left open.
75
78
 
76
- **Its documented limitation.** A Stop hook fires only when Claude is *already* trying to stop: it **cannot interrupt a `/goal` condition mid-turn**. So at this layer the ceiling is advisory; the hard bounds are the in-condition turn clause and the gate re-loop budget. If a story keeps consuming budget, that is the signal to re-scope, split, or hand it off, not to raise the budget and hope.
79
+ **Its documented limitation.** A Stop hook fires only when Claude is *already* trying to stop: it **cannot interrupt a `/goal` condition mid-turn**. So at this layer the ceiling is advisory; what can stop the story is the conductor's re-loop budget checked against this count, plus the in-condition turn clause when you started a `/goal`. In a single attended or `-H` session with no `/goal` of yours, nothing bounds re-loops spent inside one response; only `drive_epic.py` spawns have a hard backstop, their `--session-timeout` (unless set to `0`). If a story keeps consuming budget, that is the signal to re-scope, split, or hand it off, not to raise the budget and hope.
77
80
 
78
81
  ## Resume after an interruption
79
82
 
@@ -11,19 +11,19 @@ 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 commit per green story. 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 evidence commit. 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
 
18
18
  ## The thesis: three enforcement layers
19
19
 
20
- UltraCode Goal answers each shortcut with a layer the model cannot override.
20
+ UltraCode Goal answers each shortcut with a layer the model cannot override, except where a layer says otherwise.
21
21
 
22
22
  **1. Deterministic gate truth.** Completion is decided by `scripts/gate_eval.py`, which reads TEA's `gate-decision.json` and maps its gate status to a routing verdict: `PASS`/`WAIVED` advance, `CONCERNS` defers, `FAIL` re-loops, `NOT_EVALUATED` escalates. The script never re-derives TEA's thresholds and never consults the transcript; it reads the artifact as given. The model produces evidence; the script reads the verdict. They are different things on purpose. See the [gate model](./gate-model.md).
23
23
 
24
24
  **2. Hooks as invariants.** The invariants that must hold (no commit on a protected branch, no commit before a story's tests have actually run green, and four more covering marker freshness, an empty staged index, un-skipped acceptance tests, and Cross-Session Recall) live in a **PreToolUse** hook, not in memory. The hook inspects each `git commit`/`git push` and denies it when any of them is violated. It is merged into `.claude/settings.local.json` at preflight and asserted active before the run goes unattended. A denied commit is enforcement; a remembered rule is not. See [architecture](./architecture.md).
25
25
 
26
- **3. Budget enforcement.** A runaway story is bounded three ways. The `/goal` condition carries a literal "…or stop after N turns" escape clause (the real in-loop bound, because a Stop hook cannot interrupt a `/goal` condition mid-turn); a **Stop** hook tracks turns against `max_turns_per_story`, writing an escalation marker when it is breached; and the gate's re-loop budget is the third, deterministic bound: a `reloop` that would exceed the turn budget becomes an `escalate` instead. See [how it works](./how-it-works.md).
26
+ **3. Budget enforcement.** This is the one layer that rests on the conductor following a rule. A **Stop** hook tracks turns against `max_turns_per_story` and writes an escalation marker when it is breached, but it never blocks, and it counts once per response, so re-loops inside one response do not move it. The conductor reads that count before each story and each re-loop, and the gate's re-loop budget turns a `reloop` that would exceed it into an `escalate`. A story that passes its gate after an overrun is not escalated: the gate decides completion, and the overrun is logged as a sizing note. A `/goal` condition's literal "…or stop after N turns" clause binds only when an operator starts a `/goal` (the conductor cannot start one itself), and for `drive_epic.py` spawns a `--session-timeout` wall clock is the backstop. See [how it works](./how-it-works.md).
27
27
 
28
28
  These three are the module's non-negotiables. They exist because the documented mechanics make the intuitive shortcut wrong, so the skill does not optimize them away.
29
29
 
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": "2.2.0",
4
+ "version": "2.3.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",
@@ -39,15 +39,19 @@
39
39
  "format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,yaml}\"",
40
40
  "lint": "eslint . --ext .js,.cjs,.mjs,.yaml --max-warnings=0",
41
41
  "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
42
+ "lint:instructions": "uvx lintlang@0.8.1 scan skills --exclude \"**/scripts/tests/fixtures/**\" --fail-on fail",
42
43
  "lint:md": "markdownlint-cli2 \"**/*.md\"",
43
44
  "prepare": "husky || exit 0",
44
- "quality": "run-p --print-label --aggregate-output format:check lint lint:md test:install test:cli test:python test:rehype test:docs-links-tool validate:skills validate:refs validate:fixtures validate:docs-links",
45
+ "postprepare": "node tools/link-reference-skills.js --quiet || exit 0",
46
+ "quality": "run-p --print-label --aggregate-output format:check lint lint:md lint:instructions test:install test:cli test:python test:rehype test:docs-links-tool test:skill-links validate:skills validate:refs validate:fixtures validate:docs-links",
47
+ "skills:link": "node tools/link-reference-skills.js",
45
48
  "test": "npm run quality",
46
49
  "test:cli": "node test/test-cli-integration.js",
47
50
  "test:docs-links-tool": "node test/test-validate-docs-links.js",
48
51
  "test:install": "node test/test-installation-components.js",
49
52
  "test:python": "uv run --with pytest==9.1.1 --with pytest-xdist==3.8.0 pytest skills/ultracode-goal/scripts/tests/ -n auto",
50
53
  "test:rehype": "node test/test-rehype-markdown-links.js",
54
+ "test:skill-links": "node test/test-link-reference-skills.js",
51
55
  "ucg:install": "node tools/cli/ucg-cli.js install",
52
56
  "ucg:status": "node tools/cli/ucg-cli.js status",
53
57
  "ucg:uninstall": "node tools/cli/ucg-cli.js uninstall",