bmad-module-ultracode-goal 2.2.0 → 3.0.0-rc.1

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 (87) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/README.md +14 -6
  3. package/docs/_internal/STABILITY.md +17 -8
  4. package/docs/architecture.md +19 -13
  5. package/docs/comparison.md +32 -32
  6. package/docs/cross-session-recall.md +136 -54
  7. package/docs/gate-model.md +1 -1
  8. package/docs/getting-started.md +30 -16
  9. package/docs/how-it-works.md +6 -6
  10. package/docs/index.md +2 -2
  11. package/docs/knowledge-graph-refresh.md +31 -13
  12. package/docs/operating-tips.md +5 -13
  13. package/docs/troubleshooting.md +7 -3
  14. package/docs/why-ultracode-goal.md +5 -5
  15. package/package.json +22 -7
  16. package/skills/ucg-create-story/LICENSE.md +47 -0
  17. package/skills/ucg-create-story/SKILL.md +438 -0
  18. package/skills/ucg-create-story/checklist.md +357 -0
  19. package/skills/ucg-create-story/customize.toml +40 -0
  20. package/skills/ucg-create-story/discover-inputs.md +88 -0
  21. package/skills/ucg-create-story/template.md +49 -0
  22. package/skills/ucg-dev-story/LICENSE.md +49 -0
  23. package/skills/ucg-dev-story/SKILL.md +561 -0
  24. package/skills/ucg-dev-story/checklist.md +82 -0
  25. package/skills/ucg-dev-story/customize.toml +40 -0
  26. package/skills/ucg-formalize/SKILL.md +122 -43
  27. package/skills/ucg-resolve/SKILL.md +8 -6
  28. package/skills/ucg-status/SKILL.md +22 -9
  29. package/skills/ultracode-goal/SKILL.md +10 -8
  30. package/skills/ultracode-goal/assets/module.yaml +1 -1
  31. package/skills/ultracode-goal/assets/ucg-awareness/bmad-testarch-test-design.toml +1 -1
  32. package/skills/ultracode-goal/assets/ucg-awareness/{bmad-create-story.toml → ucg-create-story.toml} +10 -9
  33. package/skills/ultracode-goal/customize.toml +20 -6
  34. package/skills/ultracode-goal/references/define-done.md +17 -7
  35. package/skills/ultracode-goal/references/execute.md +37 -20
  36. package/skills/ultracode-goal/references/finalize.md +37 -29
  37. package/skills/ultracode-goal/references/gate.md +21 -13
  38. package/skills/ultracode-goal/references/health-check.md +4 -2
  39. package/skills/ultracode-goal/references/ingest-and-scope.md +29 -26
  40. package/skills/ultracode-goal/references/preflight.md +90 -34
  41. package/skills/ultracode-goal/scripts/claim_check.py +364 -0
  42. package/skills/ultracode-goal/scripts/drive_epic.py +12 -7
  43. package/skills/ultracode-goal/scripts/formalize_check.py +409 -72
  44. package/skills/ultracode-goal/scripts/gate_eval.py +203 -6
  45. package/skills/ultracode-goal/scripts/gate_trail.py +107 -18
  46. package/skills/ultracode-goal/scripts/headless_envelope.py +49 -19
  47. package/skills/ultracode-goal/scripts/hooks/budget_stop.py +41 -22
  48. package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +1424 -106
  49. package/skills/ultracode-goal/scripts/lib/mem_common.py +1226 -19
  50. package/skills/ultracode-goal/scripts/link_worktree_deps.py +162 -0
  51. package/skills/ultracode-goal/scripts/mem_observation.py +500 -147
  52. package/skills/ultracode-goal/scripts/mem_recall.py +307 -372
  53. package/skills/ultracode-goal/scripts/merge_customization.py +54 -27
  54. package/skills/ultracode-goal/scripts/mutate_check.py +200 -26
  55. package/skills/ultracode-goal/scripts/preflight_check.py +391 -18
  56. package/skills/ultracode-goal/scripts/red_ids.py +11 -1
  57. package/skills/ultracode-goal/scripts/status_render.py +96 -19
  58. package/skills/ultracode-goal/scripts/story_sizing.py +107 -1
  59. package/tools/cli/commands/status.js +92 -47
  60. package/tools/cli/lib/ide-skills.js +5 -1
  61. package/tools/cli/lib/installer.js +12 -8
  62. package/tools/cli/lib/platform-codes.yaml +1 -1
  63. package/tools/cli/lib/ui.js +1 -1
  64. package/.gitattributes +0 -16
  65. package/.nvmrc +0 -1
  66. package/docs/_internal/RELEASING.md +0 -133
  67. package/tools/build-docs.js +0 -350
  68. package/tools/validate-docs-links.js +0 -663
  69. package/tools/validate-fixtures.js +0 -161
  70. package/website/README.md +0 -92
  71. package/website/astro.config.mjs +0 -150
  72. package/website/package-lock.json +0 -8454
  73. package/website/package.json +0 -26
  74. package/website/public/favicon.svg +0 -13
  75. package/website/public/img/ucg-logo.svg +0 -73
  76. package/website/public/js/mermaid-lightbox.js +0 -67
  77. package/website/public/robots.txt +0 -36
  78. package/website/src/components/Banner.astro +0 -82
  79. package/website/src/components/Header.astro +0 -146
  80. package/website/src/components/MobileMenuFooter.astro +0 -69
  81. package/website/src/content/config.ts +0 -6
  82. package/website/src/lib/site-url.js +0 -28
  83. package/website/src/pages/404.astro +0 -11
  84. package/website/src/rehype-base-paths.js +0 -83
  85. package/website/src/rehype-markdown-links.js +0 -189
  86. package/website/src/styles/custom.css +0 -674
  87. package/website/tsconfig.json +0 -9
@@ -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": "3.0.0-rc.1",
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
 
@@ -62,7 +62,15 @@ 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) (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.
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.
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`: that run predates UCG's own story skills, which need no BMAD shim |
73
+ | TEA (Test Architect) | 1.27.2 | Epic test-design, then a per-story trace gate read by `gate_eval.py` |
66
74
 
67
75
  ```bash
68
76
  npx bmad-module-ultracode-goal install
@@ -70,7 +78,7 @@ npx bmad-module-ultracode-goal install
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.**
@@ -137,7 +145,7 @@ The docs are organized into three buckets: **Why** (start here), **Try** (do stu
137
145
  - **[Architecture](./docs/architecture.md)**: the conductor model, enforcement layers in depth, and `customize.toml` resolution.
138
146
  - **[Gate Model](./docs/gate-model.md)**: how `gate_eval.py` maps `gate_status` to a verdict, and the production AND-signals.
139
147
  - **[Health Check](./docs/health-check.md)**: the terminal self-improvement loop: what it sends, privacy, and how to disable it.
140
- - **[Cross-Session Recall](./docs/cross-session-recall.md)**: the optional claude-mem integration: touchpoints, trust model, and how to enable 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.
141
149
  - **[Knowledge-Graph Refresh](./docs/knowledge-graph-refresh.md)**: the optional graphify integration: preconditions, what it sends where, and what it never touches.
142
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.
143
151
  - **[Troubleshooting](./docs/troubleshooting.md)**: real failure modes and their remediations.
@@ -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
 
@@ -1,11 +1,11 @@
1
1
  ---
2
2
  title: Stability and Public Contract
3
- description: "The 2.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 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."
4
4
  ---
5
5
 
6
- > **Status:** 2.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:** 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.
7
7
 
8
- This is the stability posture for `bmad-module-ultracode-goal` at `2.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 `3.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
 
@@ -20,7 +20,7 @@ The installer CLI is invoked via `npx bmad-module-ultracode-goal <subcommand>`.
20
20
 
21
21
  ### The `[workflow]` customize.toml keys
22
22
 
23
- The keys in the shipped `[workflow]` block of `customize.toml` (including `persistent_facts`, `tea_config_path`, `trace_output_dir`, `implementation_artifacts`, `deferred_work_path`, `epic_branch_prefix`, `protected_branches`, `max_turns_per_story`, `story_token_budget` (**deprecated, no-op**), `parallel_max_concurrency` (**deprecated, no-op**), `allowlist_commands`, `on_epic_complete`, `on_escalation`, `cross_session_recall`, and `graphify_integration`) are the supported override surface. Teams and users override them in `_bmad/custom/ultracode-goal.toml` (and `.user.toml`) with base → team → user resolution (scalars override, tables deep-merge, arrays append). Renaming or removing a key, or changing how it resolves, is a contract change. See [architecture](../architecture.md).
23
+ The keys in the shipped `[workflow]` block of `customize.toml` (including `persistent_facts`, `tea_config_path`, `trace_output_dir`, `implementation_artifacts`, `deferred_work_path`, `epic_branch_prefix`, `protected_branches`, `max_turns_per_story`, `story_token_budget` (**deprecated, no-op**), `parallel_max_concurrency` (**deprecated, no-op**), `allowlist_commands`, `on_epic_complete`, `on_escalation`, `cross_session_recall`, `cross_session_recall_store`, and `graphify_integration`) are the supported override surface. Teams and users override them in `_bmad/custom/ultracode-goal.toml` (and `.user.toml`) with base → team → user resolution (scalars override, tables deep-merge, arrays append). Renaming or removing a key, or changing how it resolves, is a contract change. See [architecture](../architecture.md).
24
24
 
25
25
  `story_token_budget` is **deprecated** as of the deprecation note in `CHANGELOG.md`: it is still shipped, still accepted, and still resolves, so existing overrides keep working and nothing errors. It is a no-op; no layer reads it any more. The runaway bound is turns only, via `max_turns_per_story`. The key stays enumerated here (and stays in `customize.toml`) precisely because removing it would be the contract break this section forbids.
26
26
 
@@ -50,7 +50,7 @@ A headless run writes that same object to `{workflow.implementation_artifacts}/r
50
50
 
51
51
  - **The guarantee**: once a headless run resolves `{workflow.implementation_artifacts}` it clears any prior `run-result.json`, before any stage work. From that point on the file's presence means **this** run reached a terminal. The guarantee is scoped to that moment, so a consumer should still prefer a parseable stdout envelope when the file is absent.
52
52
 
53
- Four documented exceptions, none of which is a contract break: a block that fires **before** `{workflow.implementation_artifacts}` resolves (the "not a BMAD project" stop) neither writes nor clears, so it leaves the stdout envelope as its sole output and is the one case where a prior run's file can survive; a terminal whose best-effort write failed leaves no file while still printing its envelope; a headless run that has not yet reached a terminal (still running, crashed, or killed) has no file, because startup cleared any prior one; and an **attended** run writes no file at all and clears none. The file is overwrite-in-place, so it carries no cross-run history.
53
+ Five documented exceptions, none of which is a contract break: a block that fires **before** `{workflow.implementation_artifacts}` resolves (the "not a BMAD project" stop) neither writes nor clears, so it leaves the stdout envelope as its sole output and is the one case where a prior run's file can survive; a terminal whose best-effort write failed leaves no file while still printing its envelope; a headless run whose call to the envelope adapter is itself refused by the permission layer builds nothing by hand, so it leaves no file and prints no envelope, recording the block and the refusal in its `.decision-log.md` instead (since 2.3.0); a headless run that has not yet reached a terminal (still running, crashed, or killed) has no file, because startup cleared any prior one; and an **attended** run writes no file at all and clears none. The file is overwrite-in-place, so it carries no cross-run history.
54
54
 
55
55
  ### The skill name and invocation phrases
56
56
 
@@ -61,6 +61,7 @@ The skill name `ultracode-goal` and its documented invocation phrases ("run an e
61
61
  `scripts/gate_eval.py` is the deterministic completion authority. Covered:
62
62
 
63
63
  - **CLI flags**: `--trace-output` (required), `--profile` (`light` | `production`, required), `--story`, `--nfr`, `--test-review` (production only), `--tests-ran` (per-story only), `--cycle-profile` (per-story only), `--epic-level`, `--rollup` and `--sprint-status` (roll-up only: `--rollup` requires `--epic-level`, `--story <epic id>` and `--sprint-status`, and `--sprint-status` is rejected without `--rollup`; every roll-up refusal resolves to `gate_status: NOT_EVALUATED` -> `escalate`, never to a silent narrower answer).
64
+ - **The roll-up's story set** (`--rollup`): every story row of the epic in `sprint-status.yaml`, except a decomposed parent on its split record: a `done` row with no resolvable gate artifact, for which `.split-<its key>.json` beside `--sprint-status`, as `scripts/story_sizing.py --parent <key> --record <dir>` writes it, holds a JSON object whose `parent` is that key and whose `children` are each another story row of the epic, when no chain of such records leads from it back to it and `--story <key>` would find no trace report, gate decision or trace summary of its own. Its children's gates count in its place, and a `reasons` line names it. The record's other fields are internal.
64
65
  - **The production signals are required, not optional, on a per-story gate.** Under `--profile production` an omitted `--nfr` or `--test-review` is a *failing* signal, exactly as a supplied-but-missing path already was. `--epic-level` is the one sanctioned omission: it declares the epic roll-up, where TEA writes no aggregate to AND, and it cannot be combined with either path (doing so is an invocation error, exit 2). Under `--profile light` the flag is a no-op.
65
66
  - **The sweep-scope cap** (`--tests-ran`): optional PATH to the story's `.tests-ran-<story_id>` marker, read in both profiles. The marker's `scope=` line is read fail-closed: `scope=full` passes the verdict through; `scope=scoped`, a missing marker, a missing `scope=` line, or an unrecognised value caps `advance`/`defer` at `reloop` (defer moves too, because its route advances the story). It cannot be combined with `--epic-level` (an invocation error, exit 2). **Omitting the flag skips the check**: invocations that predate the flag keep their verdicts, per the breaking-change rule below. The verdict JSON's `sweep_scope` key carries the recognised value or `null`, and is present exactly when the flag was supplied, so the printed shape of pre-flag invocations is unchanged.
66
67
  - **The delta cycle profile** (`--cycle-profile`, `full` | `delta`): `delta` declares a mid-loop gate that re-ran only the previously failed assessor dimension(s); its verdict is capped at `reloop` (`advance` and `defer` both move to `reloop`). An unrecognised value is an argparse error (exit 2), and the flag cannot be combined with `--epic-level` (exit 2). Omission is the full behaviour. The `cycle_profile` JSON key is present exactly when the flag was supplied.
@@ -82,6 +83,12 @@ flowchart LR
82
83
 
83
84
  The printed JSON object's key set (`verdict`, `gate_status`, `p0_status`, `p1_status`, `overall_status`, `nfr_status`, `review_score`, `epic_level`, `reasons`) is the consumable shape; the human-readable `reasons` strings are not contractual wording. Two keys are conditional by design: `sweep_scope` appears exactly when `--tests-ran` was supplied (its value the recognised `scope=` reading, or `null`) and `cycle_profile` exactly when `--cycle-profile` was; each is absent otherwise, so an invocation that predates the flags prints the same shape it always did. `epic_level` is how a consumer tells an `advance` that ANDed both production signals from one that skipped them by declaration: `nfr_status: null` alone cannot say which, and the distinction is not readable from `reasons` precisely because that wording is not contractual.
84
85
 
86
+ ### Supported tool versions
87
+
88
+ The minimum versions UCG supports, listed in `tools/tool-requirements.yaml` and shown in the [prerequisites table](../getting-started.md#prerequisites): Claude Code (the version preflight refuses to launch below), Node.js (`engines.node`), Python (the `requires-python` header of every script) and BMAD Method. Raising a minimum, or giving a tool its first one, turns away a setup the release before accepted, so it is a contract change. Lowering or removing a minimum is additive. The tested versions in the same list record what UCG's own runs used and are not part of the contract.
89
+
90
+ This bucket was added in 3.0.0. Adding it widens what the contract covers and removes nothing from it, so it is an additive change to this contract.
91
+
85
92
  ## @internal: not covered
86
93
 
87
94
  Everything not enumerated above is `@internal` and may change in any release, major or minor, without a deprecation note. Do not pin against:
@@ -89,7 +96,7 @@ Everything not enumerated above is `@internal` and may change in any release, ma
89
96
  - **Installer library internals**: the implementation behind the CLI subcommands; what is covered is the observable subcommand surface, not how the files get placed.
90
97
  - **Reference file structure**: the `references/*.md` stage files' internal structure, step ordering, prose, and section headings. The stage *names* are referenced by the health-check fingerprint (see below) but the file contents are an authoring surface.
91
98
  - **Script internals**: the internal functions, regexes, and intermediate behavior of `preflight_check.py`, `gate_eval.py`, `health_check_fp.py`, and the hook scripts. The covered surface is `gate_eval.py`'s CLI and verdict vocabulary above; everything else (the `preflight_check.py` JSON shape, the fingerprint tuple format, the hook env-var names) is internal and may change.
92
- - **The retired `--parallel` workflow**: the experimental fan-out (`assets/execute-epic.workflow.js`, its `/ultracode-goal-execute` registration, args binding and return shape) was explicitly excluded from this contract while it shipped, and has been removed. The `--parallel` flag is still accepted and ignored, and `parallel_max_concurrency` is deprecated, still resolving, no-op — the `story_token_budget` treatment (see [Public contract](#public-contract)).
99
+ - **The retired `--parallel` workflow**: the experimental fan-out (`assets/execute-epic.workflow.js`, its `/ultracode-goal-execute` registration, args binding and return shape) was explicitly excluded from this contract while it shipped, and has been removed. The `--parallel` flag is still accepted and ignored, and `parallel_max_concurrency` is deprecated, still resolving, no-op: the `story_token_budget` treatment (see [Public contract](#public-contract)).
93
100
  - **`_bmad-output/` artifact layout**, with one exception: run folders, the decision log, `run-report.md`, `run-status.json`, the deferred-work ledger, and the improvement queue are run outputs, not a downstream-consumable schema. **`run-result.json` is the exception and is covered** (see [the headless result file](#the-headless-result-file)); it is the one artifact in that tree an automator may pin against. The headless emit shape (covered above) is the supported way to locate the rest of these paths programmatically.
94
101
 
95
102
  ## SemVer note
@@ -99,7 +106,7 @@ Everything not enumerated above is `@internal` and may change in any release, ma
99
106
  What counts as breaking, stated so it is not re-litigated per release:
100
107
 
101
108
  - Removing or renaming an enumerated CLI flag, subcommand, config key, or JSON key.
102
- - **Changing the verdict an unchanged, previously-documented invocation returns.** This is the one that bites, and it bit at 2.0.0: `gate_eval.py --profile production` with neither signal flag was the documented epic-level invocation and returned `advance`; it now returns `reloop` unless `--epic-level` is passed. That the old answer was unearned did not make the change non-breaking — a consumer's pipeline still changed behaviour on an upgrade they did not ask for.
109
+ - **Changing the verdict an unchanged, previously-documented invocation returns.** This is the one that bites, and it bit at 2.0.0: `gate_eval.py --profile production` with neither signal flag was the documented epic-level invocation and returned `advance`; it now returns `reloop` unless `--epic-level` is passed. That the old answer was unearned did not make the change non-breaking: a consumer's pipeline still changed behaviour on an upgrade they did not ask for.
103
110
  - Adding a key to the JSON an UNCHANGED invocation prints (the verdict object or the headless envelope), for a consumer validating the shape strictly. A key that appears only when a newly introduced flag is supplied is additive, not breaking: `sweep_scope` and `cycle_profile` are the worked example, present exactly when `--tests-ran` / `--cycle-profile` are passed and absent from every pre-flag invocation's output.
104
111
 
105
112
  What does not:
@@ -108,4 +115,6 @@ What does not:
108
115
  - Anything behind `@internal`, including which file a resolver picks and how it decides a name carries a story id.
109
116
  - Prose in `references/*.md`, which is an authoring surface.
110
117
 
111
- **Deprecation.** The two surfaces an automator is most likely to encode against — the **headless five-key JSON emit shape** and the **`[workflow]` customize.toml keys** — get a deprecation note in `CHANGELOG.md` at least one minor before changing, and the key stays shipped and accepted meanwhile. `story_token_budget` is the worked example: deprecated, still resolving, no-op.
118
+ **How a release checks this.** Every pull request that changes something a user can notice adds a change fragment to `changes/` ([`changes/README.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/changes/README.md)), and the release notes and the minimum version bump come from those fragments. `tools/covered-surfaces.js` reads the surfaces above (the CLI subcommands and options, the `[workflow]` keys, the headless emit keys and result file, the skill name and invocation phrases, the `gate_eval.py` flags, choices, statuses, verdicts and printed keys, and the tool minimums) at the last stable tag and now. The release gate (`node tools/changes.js gate`) refuses a release that removes one of them without a major bump and a `breaking` fragment that names it, or that adds one without at least a minor bump. Three kinds of change go the other way: adding or removing a key of the headless emit shape, or renaming the result file, is a major change, since the shape is exactly those keys; raising a tool minimum, or giving a tool its first one, is a major change, and lowering or removing one a minor one; and a `gate_status` that maps to another verdict is a major change. A key added to the printed `gate_eval.py` result is listed for a person to judge, since the text cannot tell a key every invocation prints from one only a new flag prints. A changed verdict for an unchanged invocation is not something the diff can see: its fragment says so, as a `breaking` one. The gate also refuses a major release while the **Status** line above names another major, so the copy of this document in each package names the major it describes.
119
+
120
+ **Deprecation.** The two surfaces an automator is most likely to encode against, the **headless five-key JSON emit shape** and the **`[workflow]` customize.toml keys**, get a deprecation note in the release notes (a change fragment, rendered into `CHANGELOG.md`) at least one minor before changing, and the key stays shipped and accepted meanwhile. `story_token_budget` is the worked example: deprecated, still resolving, no-op.
@@ -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-code-review`, `bmad-correct-course`, `bmad-retrospective`, and UCG's own story skills, `ucg-create-story` and `ucg-dev-story`. Those two are adapted from BMAD Method's `bmad-create-story` and `bmad-dev-story`, which 6.12 made opt-in shims and v7 removes, so a run needs no BMAD shim; 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
- - **`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.
30
+ - **`scripts/hooks/guard_pretooluse.py`** (PreToolUse): inspects each `git commit`/`git push` and enforces seven 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(`. The last two are not about git at all: they run for every tool call while a Cross-Session Recall latch is present. The sixth denies every claude-mem MCP call and any reach into `.claude-mem`, whatever the latch records. The seventh denies tool calls that name the recall store or would change the latch itself, except the skill's own two recall scripts; reading the latch stays allowed. 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. 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
 
@@ -61,16 +61,17 @@ skills/ultracode-goal/
61
61
  │ ├── formalize_check.py # readiness kernel behind the /ucg-formalize gate
62
62
  │ ├── status_render.py # read-side render behind /ucg-status
63
63
  │ ├── red_ids.py # preflight-RED identity (the resolve join key)
64
- │ ├── story_sizing.py # decomposition sizing + parent-AC claim reconciliation
64
+ │ ├── story_sizing.py # decomposition sizing + parent-AC claim reconciliation + split record
65
+ │ ├── claim_check.py # pre-commit: paths a message names that the staged diff skips
65
66
  │ ├── drive_epic.py # one `claude -p` per story (--max-stories work bound)
66
67
  │ ├── headless_envelope.py # the one five-key headless-envelope adapter
67
68
  │ ├── health_check_fp.py # health-check fingerprint + seen-cache plumbing
68
- │ ├── mem_observation.py # Cross-Session Recall write path (build/spill/drain)
69
- │ ├── mem_recall.py # Cross-Session Recall read path (latch + filter)
69
+ │ ├── mem_observation.py # Cross-Session Recall write path (write/drain)
70
+ │ ├── mem_recall.py # Cross-Session Recall latch and read path (latch/filter/unlatch)
70
71
  │ ├── merge_config.py # install-time config merge into shared _bmad
71
72
  │ ├── merge_customization.py # install-time UCG-awareness fragment merge
72
73
  │ ├── merge_help_csv.py # install-time help-CSV merge
73
- │ ├── lib/mem_common.py # shared Cross-Session Recall primitives
74
+ │ ├── lib/mem_common.py # shared Cross-Session Recall primitives and the run store
74
75
  │ └── hooks/
75
76
  │ ├── guard_pretooluse.py # commit invariants (PreToolUse)
76
77
  │ └── budget_stop.py # turn budget (Stop)
@@ -85,9 +86,14 @@ skills/ucg-status/ # Read-only status view over a run
85
86
  # the IDE's skill loader enumerates one level, so a
86
87
  # nested command never resolves. Each stays thin and
87
88
  # reaches back into the parent via `{ucg-root}`.
89
+ skills/ucg-create-story/ # Story creation the run delegates to (adapted from BMAD)
90
+ skills/ucg-dev-story/ # Story implementation the run delegates to (adapted from BMAD)
91
+ # Self-contained, each with its own customize.toml and
92
+ # LICENSE.md; no help-catalog row, since the run, not
93
+ # the operator, invokes them.
88
94
  ```
89
95
 
90
- `SKILL.md` carries the routing and the contract; the `references/*.md` files carry each stage's procedure and testable routing conditions; the `scripts/*.py` files carry the deterministic facts the model cannot fudge (the gate, preflight, readiness kernel, hooks, and the install-time/recall plumbing); the top-level sibling skills `skills/ucg-*` are the operator-facing surfaces (`ucg-formalize` the standalone readiness gate, `ucg-resolve` the decide-surface for a stopped run, `ucg-status` the read-only run view); and the `assets/` hold install metadata and the planning-customization fragments. See [how it works](./how-it-works.md) for the stages.
96
+ `SKILL.md` carries the routing and the contract; the `references/*.md` files carry each stage's procedure and testable routing conditions; the `scripts/*.py` files carry the deterministic facts the model cannot fudge (the gate, preflight, readiness kernel, hooks, and the install-time/recall plumbing); three of the top-level sibling skills are the operator-facing surfaces (`ucg-formalize` the standalone readiness gate, `ucg-resolve` the decide-surface for a stopped run, `ucg-status` the read-only run view), and the other two, `ucg-create-story` and `ucg-dev-story`, are the story skills the run delegates to; and the `assets/` hold install metadata and the planning-customization fragments. See [how it works](./how-it-works.md) for the stages.
91
97
 
92
98
  ## Customization resolution
93
99
 
@@ -99,7 +105,7 @@ Configuration resolves in three layers, base → team → user, via `resolve_cus
99
105
 
100
106
  Neither override file is created by any installer, and a missing one is not an error: the resolver loads it non-required and treats absence as an empty table, so a fresh project resolves the base layer alone. You create them when you first need to override something. Do not mistake them for the `config.toml` and `config.user.toml` already sitting in that directory: those are BMAD's own configuration, and a UCG knob written there resolves to nothing.
101
107
 
102
- Merge semantics: **scalars override**, **tables deep-merge**, **arrays append**. At activation the skill runs `resolve_customization.py --skill {skill-root} --key workflow`; if that fails, it resolves the three files itself in the same order. The shipped base layer defines the run's knobs: the TEA/artifact paths (`tea_config_path`, `trace_output_dir`, `implementation_artifacts`, `deferred_work_path`), the git guardrails (`epic_branch_prefix`, `protected_branches`), the turn budget (`max_turns_per_story`; `story_token_budget` remains as a deprecated no-op key), `parallel_max_concurrency` (deprecated no-op since the `--parallel` retirement), the `allowlist_commands`, the two lifecycle hooks (`on_epic_complete`, `on_escalation`), the [health check](./health-check.md) family (`health_check_repo`, `health_check_seen_cache`, `health_check_queue_path`, `health_check_autosubmit`), and the two optional third-party integrations, both off by default: [`cross_session_recall`](./cross-session-recall.md) and [`graphify_integration`](./knowledge-graph-refresh.md). Teams and users override without editing the shipped file. Remember that a budget or branch override only reaches the *enforcement* layer because preflight threads it into the hook env (see layer 2 above).
108
+ Merge semantics: **scalars override**, **tables deep-merge**, **arrays append**. At activation the skill runs `resolve_customization.py --skill {skill-root} --key workflow`; if that fails, it resolves the three files itself in the same order. The shipped base layer defines the run's knobs: the TEA/artifact paths (`tea_config_path`, `trace_output_dir`, `implementation_artifacts`, `deferred_work_path`), the git guardrails (`epic_branch_prefix`, `protected_branches`), the turn budget (`max_turns_per_story`; `story_token_budget` remains as a deprecated no-op key), `parallel_max_concurrency` (deprecated no-op since the `--parallel` retirement), the `allowlist_commands`, the two lifecycle hooks (`on_epic_complete`, `on_escalation`), the [health check](./health-check.md) family (`health_check_repo`, `health_check_seen_cache`, `health_check_queue_path`, `health_check_autosubmit`), and the two optional integrations, both off by default: [`cross_session_recall`](./cross-session-recall.md) with its store folder `cross_session_recall_store`, and the third-party [`graphify_integration`](./knowledge-graph-refresh.md). Teams and users override without editing the shipped file. Remember that a budget or branch override only reaches the *enforcement* layer because preflight threads it into the hook env (see layer 2 above).
103
109
 
104
110
  The three TOML layers merge once, but a branch or budget value then travels two ways: the conductor reads it directly, while the hooks only see it if preflight re-injects it as env:
105
111
 
@@ -3,21 +3,21 @@ 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.3.0 (released 2026-10-16) and bmad-loop v0.13.2 (released 2026-10-10). 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 has shipped six releases since v0.10.0: v0.11.0 (2026-08-19), v0.11.1 (2026-08-24), v0.12.0 (2026-09-20), v0.13.0 (2026-09-28), v0.13.1 (2026-10-01) and v0.13.2 (2026-10-10). Most of their volume is hardening, itemized candidly: atomic writes so a failed write can no longer truncate the sprint board, a story spec or the policy file, writers that will not follow a planted link, merge-back failures classified from the measured tree state, and a long pass over the deferred-work ledger and sweep migrations (v0.12.0's notes outgrew GitHub's release-body limit and end by pointing to the changelog). The capability headlines, release by release: v0.11.0 hands plugins structured per-command verify results from the dev and fix legs (`post_dev_verify`) and has `validate` warn on a CLI binary that is on `PATH` but will not run; v0.11.1 makes git 2.34 an enforced floor and lands a hard `stop` on every platform and multiplexer backend; v0.12.0 lets a sweep target exact ids or a severity floor (`--only`, `--min-severity`) and archive closed entries (`--archive`); v0.13.0 adds an opt-in `[gates] retrospective = "auto"` that runs a headless `/bmad-retrospective` at each epic boundary on its own `retro` adapter role, has a fresh sweep file a retrospective's open action items as ledger entries, pauses a session parked on a permission, idle or quota prompt instead of nudging it (the claude profile maps those prompts), publishes review-leg verify results to plugins (`post_review_verify`), and adds `resolve --adopt-branch` to finish an escalated worktree story from its kept branch with no new session (review and verify are not re-run); v0.13.1 drops hook events from a nested coding-CLI session as foreign, with the claude profile pinning the launched session's id; and v0.13.2 adds `[environment]` health probes, run before verify and before each session launch, where a failing probe pauses the run without charging the story an attempt, plus `resolve --reverify`, which re-runs verify on a deferred or environment-faulted story's kept work and then reviews and commits it with no new dev session. UCG is not affected by the BMAD-METHOD primitive rename: it orchestrates `bmad-dev-story`, not the auto primitive (BMAD-METHOD 6.12 makes `bmad-dev-story` itself an opt-in shim, and from the release after v2.3.0 UCG orchestrates its own `ucg-dev-story`, adapted from it, so the shim no longer reaches it; 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.3.0 on 2026-10-16. The release fits the module to the toolchain a full Epic was last run on under `--light`, which the README now records in a "Tested with" table (Claude Code 2.1.301, BMAD Method 6.12.0 installed with `--shims`, TEA 1.27.2: the versions that run used, not minimums). Preflight now refuses to launch when `bmad-create-story` or `bmad-dev-story` is missing, since BMAD Method 6.12 ships both as deprecated shims a fresh install leaves out, and checks again on every resume; it also stops on a repository with nothing committed yet, and treats a settings write the Auto Mode classifier refuses as a stop rather than something to work around. A story whose gate passes after its turn count reached the ceiling now gets a sizing note in the decision log and run report, not a `budget-overrun` escalation: the count escalates only when the gate escalates the story on it or a resume finds it already at the ceiling, and `max_turns_per_story` stays 25. The docs no longer list `/goal` among the primitives a run composes, since no run starts one: what bounds a story's turns is the Stop hook's count, read before a resumed story's step 0 and before each re-loop. Each story now lands an implementation commit plus its gate's evidence commit, the Epic's own sprint-status row moves to `in-progress` and then `done`, and on TEA 1.27.2 trace runs on any stack, with the run naming the per-story trace files the gate reads. (v2.2.0's re-loop economics, v2.1.0's computed epic roll-up and v2.0.0's nine-defect fail-open closure are in the [changelog](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/CHANGELOG.md).)
13
13
 
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.
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 move ahead of their tags between releases.
15
15
 
16
16
  ## The one difference everything else follows from
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, with git 2.34 or newer enforced since v0.11.1 (`run`, `sweep` and `resume` refuse below it); 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
- | 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) |
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
- | 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 |
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; since v0.13.0 an opt-in `[gates] retrospective = "auto"` also runs a headless `/bmad-retrospective` at each epic boundary | 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`; 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.13.2 span BMAD config, adapter (binary, including one on `PATH` that will not run, profile, kind, out-of-tree), deferred work (including an unreadable ledger now failing rather than warning, and a ledger the orchestrator's own commits would sweep in or lose), environment (health probes, run only under `--probes`), git (including the 2.34 floor), hooks, host, multiplexer, notifications, operator park records, plugin manifests, 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; since v2.3.0 the script also refuses a project whose story skills are not installed (UCG's own `ucg-create-story` and `ucg-dev-story` from the release after v2.3.0, with no BMAD shim needed) or whose repository has nothing committed yet |
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` (a `sweep --migrate` rewrite that would drop one is refused since v0.11.0), and a story can close entries at its commit via `closes_deferred:`; v0.12.0 adds sweep selectors (`--only`, `--min-severity`) and `--archive` for closed entries, and v0.13.0 has a fresh sweep file a retrospective's open action items as ledger entries | 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; v0.13.0 and v0.13.2 add ways to finish a stopped story from its kept work with no new dev session: `resolve --adopt-branch` for an escalated worktree story (review and verify are not re-run) and `resolve --reverify` for a deferred or environment-faulted one (verify and review run first) | 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
+ | Extensibility | A plugin system (observe, veto, mutate) with bundled TEA and Unity plugins | `customize.toml` knobs, planning-shaping fragments, and two optional integrations configured there, both off by default and neither able to touch a gate verdict: [cross-session recall](./cross-session-recall.md) over a local run store and a third-party [graphify knowledge-graph refresh](./knowledge-graph-refresh.md) |
40
+ | Self-improvement | Not shipped as issues against the tool itself; since v0.13.0 an opt-in automated epic retrospective files its action items into the deferred-work ledger, which a sweep then executes | A health check that files deduplicated GitHub issues about its own friction |
41
+ | Maturity | First-party (bmad-code-org); v0.13.2, six releases past v0.10.0 that add opt-in automated epic retrospectives, environment probes and kept-work recovery verbs atop long hardening passes on writes, merges and the deferred-work ledger; rich docs; CI + test suite | Community module; v2.3.0, fixes surfaced mostly by real runs on BMAD Method 6.12 and TEA 1.27.2 (preflight refusals for missing BMAD story skills and an unborn repository, a passing gate overriding the turn-count escalation, a per-story evidence commit), a minor release under the 2.x 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
- 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
- 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.
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. Since v0.12.0 a sweep can be aimed at exact ids or a severity floor and can archive closed entries, and since v0.13.0 a fresh sweep files a retrospective's open action items as new entries. 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
+ 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. Plugins also receive structured per-command verify results, from the dev and fix legs since v0.11.0 and from review since v0.13.0. 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 (out-of-tree adapter classes against a registry since v0.10.0), and it carries the backing of the bmad-code-org org. Its recovery tooling has grown too: `[environment]` health probes pause a run on a broken environment without charging the story an attempt (v0.13.2), a session parked on a permission, idle or quota prompt pauses instead of being nudged (v0.13.0, on the claude profile), and `resolve --adopt-branch` (v0.13.0) and `resolve --reverify` (v0.13.2) finish a stopped story from its kept work with no new dev session.
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,13 +64,13 @@ 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, since extended by writers that will not follow a planted link (v0.11.0, v0.12.0) and by run and worktree roots pinned to their recorded identity (v0.13.0), 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.
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.
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); since v2.3.0 a story whose gate passes after its count reached the ceiling advances with a sizing note rather than an escalation. 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
+ - `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, since v2.3.0, moves the Epic's own row to `in-progress` and then `done`), and bmad-loop's orchestrator syncs the board itself.
74
74
 
75
75
  ## Which to reach for
76
76
 
@@ -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-10-16 against bmad-loop v0.13.2 (released 2026-10-10) and UCG v2.3.0 (released 2026-10-16). Earlier cuts: 2026-08-15 (bmad-loop v0.10.0, UCG v2.2.0), 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.13.2 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.