bmad-module-ultracode-goal 2.3.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 (80) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/README.md +3 -3
  3. package/docs/_internal/STABILITY.md +17 -8
  4. package/docs/architecture.md +14 -8
  5. package/docs/comparison.md +20 -20
  6. package/docs/cross-session-recall.md +136 -54
  7. package/docs/getting-started.md +23 -13
  8. package/docs/how-it-works.md +4 -4
  9. package/docs/index.md +1 -1
  10. package/docs/knowledge-graph-refresh.md +31 -13
  11. package/docs/operating-tips.md +4 -12
  12. package/docs/troubleshooting.md +2 -1
  13. package/docs/why-ultracode-goal.md +3 -3
  14. package/package.json +18 -7
  15. package/skills/ucg-create-story/LICENSE.md +47 -0
  16. package/skills/ucg-create-story/SKILL.md +438 -0
  17. package/skills/ucg-create-story/checklist.md +357 -0
  18. package/skills/ucg-create-story/customize.toml +40 -0
  19. package/skills/ucg-create-story/discover-inputs.md +88 -0
  20. package/skills/ucg-create-story/template.md +49 -0
  21. package/skills/ucg-dev-story/LICENSE.md +49 -0
  22. package/skills/ucg-dev-story/SKILL.md +561 -0
  23. package/skills/ucg-dev-story/checklist.md +82 -0
  24. package/skills/ucg-dev-story/customize.toml +40 -0
  25. package/skills/ucg-formalize/SKILL.md +118 -46
  26. package/skills/ucg-resolve/SKILL.md +4 -2
  27. package/skills/ucg-status/SKILL.md +1 -1
  28. package/skills/ultracode-goal/SKILL.md +7 -5
  29. package/skills/ultracode-goal/assets/ucg-awareness/bmad-testarch-test-design.toml +1 -1
  30. package/skills/ultracode-goal/assets/ucg-awareness/{bmad-create-story.toml → ucg-create-story.toml} +10 -9
  31. package/skills/ultracode-goal/customize.toml +20 -6
  32. package/skills/ultracode-goal/references/define-done.md +15 -7
  33. package/skills/ultracode-goal/references/execute.md +26 -9
  34. package/skills/ultracode-goal/references/finalize.md +32 -25
  35. package/skills/ultracode-goal/references/gate.md +5 -3
  36. package/skills/ultracode-goal/references/health-check.md +4 -2
  37. package/skills/ultracode-goal/references/ingest-and-scope.md +29 -26
  38. package/skills/ultracode-goal/references/preflight.md +78 -30
  39. package/skills/ultracode-goal/scripts/claim_check.py +364 -0
  40. package/skills/ultracode-goal/scripts/drive_epic.py +1 -1
  41. package/skills/ultracode-goal/scripts/formalize_check.py +409 -72
  42. package/skills/ultracode-goal/scripts/gate_eval.py +203 -6
  43. package/skills/ultracode-goal/scripts/headless_envelope.py +30 -14
  44. package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +1398 -100
  45. package/skills/ultracode-goal/scripts/lib/mem_common.py +1226 -19
  46. package/skills/ultracode-goal/scripts/link_worktree_deps.py +162 -0
  47. package/skills/ultracode-goal/scripts/mem_observation.py +500 -147
  48. package/skills/ultracode-goal/scripts/mem_recall.py +307 -372
  49. package/skills/ultracode-goal/scripts/merge_customization.py +54 -27
  50. package/skills/ultracode-goal/scripts/mutate_check.py +200 -26
  51. package/skills/ultracode-goal/scripts/preflight_check.py +251 -103
  52. package/skills/ultracode-goal/scripts/red_ids.py +11 -1
  53. package/skills/ultracode-goal/scripts/story_sizing.py +107 -1
  54. package/tools/cli/commands/status.js +92 -47
  55. package/tools/cli/lib/ide-skills.js +5 -1
  56. package/tools/cli/lib/installer.js +12 -8
  57. package/.gitattributes +0 -16
  58. package/.nvmrc +0 -1
  59. package/docs/_internal/RELEASING.md +0 -134
  60. package/tools/build-docs.js +0 -350
  61. package/tools/validate-docs-links.js +0 -936
  62. package/tools/validate-fixtures.js +0 -161
  63. package/website/README.md +0 -92
  64. package/website/astro.config.mjs +0 -150
  65. package/website/package-lock.json +0 -8454
  66. package/website/package.json +0 -26
  67. package/website/public/favicon.svg +0 -13
  68. package/website/public/img/ucg-logo.svg +0 -73
  69. package/website/public/js/mermaid-lightbox.js +0 -67
  70. package/website/public/robots.txt +0 -36
  71. package/website/src/components/Banner.astro +0 -82
  72. package/website/src/components/Header.astro +0 -146
  73. package/website/src/components/MobileMenuFooter.astro +0 -69
  74. package/website/src/content/config.ts +0 -6
  75. package/website/src/lib/site-url.js +0 -28
  76. package/website/src/pages/404.astro +0 -11
  77. package/website/src/rehype-base-paths.js +0 -83
  78. package/website/src/rehype-markdown-links.js +0 -189
  79. package/website/src/styles/custom.css +0 -674
  80. package/website/tsconfig.json +0 -9
@@ -19,7 +19,7 @@
19
19
  "name": "bmad-module-ultracode-goal",
20
20
  "source": "./",
21
21
  "description": "Supercharges BMAD with Claude Code's Auto Mode, Auto Memory, and hooks: autonomous Epic execution to a machine-checked, TEA-gated Definition-of-Done. Execute Epics. Accumulate Knowledge. Deliver Outcomes.",
22
- "version": "2.3.0",
22
+ "version": "3.0.0-rc.1",
23
23
  "author": {
24
24
  "name": "Armel"
25
25
  },
package/README.md CHANGED
@@ -62,14 +62,14 @@ 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
66
 
67
67
  **Tested with:** on 2026-10-16 a two-story Epic reached its Definition-of-Done with the versions below, under the `--light` profile (TEA test-design and the trace gate; the production gate set was not exercised). They are the versions that run used, not minimums.
68
68
 
69
69
  | Component | Version | Note |
70
70
  | --- | --- | --- |
71
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 |
72
+ | BMAD Method | 6.12.0 | Installed with `--shims`: that run predates UCG's own story skills, which need no BMAD shim |
73
73
  | TEA (Test Architect) | 1.27.2 | Epic test-design, then a per-story trace gate read by `gate_eval.py` |
74
74
 
75
75
  ```bash
@@ -145,7 +145,7 @@ The docs are organized into three buckets: **Why** (start here), **Try** (do stu
145
145
  - **[Architecture](./docs/architecture.md)**: the conductor model, enforcement layers in depth, and `customize.toml` resolution.
146
146
  - **[Gate Model](./docs/gate-model.md)**: how `gate_eval.py` maps `gate_status` to a verdict, and the production AND-signals.
147
147
  - **[Health Check](./docs/health-check.md)**: the terminal self-improvement loop: what it sends, privacy, and how to disable it.
148
- - **[Cross-Session Recall](./docs/cross-session-recall.md)**: the optional 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.
149
149
  - **[Knowledge-Graph Refresh](./docs/knowledge-graph-refresh.md)**: the optional graphify integration: preconditions, what it sends where, and what it never touches.
150
150
  - **[Operating Tips](./docs/operating-tips.md)**: field notes from real drives: the driver's stop reasons, sequencing by row order, and the verification traps.
151
151
  - **[Troubleshooting](./docs/troubleshooting.md)**: real failure modes and their remediations.
@@ -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.
@@ -9,7 +9,7 @@ UltraCode Goal is a conductor. It orchestrates the installed BMAD epic toolbox a
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`. 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.
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
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
 
@@ -27,7 +27,7 @@ These are the module's non-negotiables. Each exists because the documented mecha
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.
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
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`.
@@ -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
 
@@ -5,13 +5,13 @@ description: An honest, side-by-side comparison of UltraCode Goal and bmad-code-
5
5
 
6
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.2.0 (released 2026-08-15) and bmad-loop v0.10.0 (released 2026-08-14). 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.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)).
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.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).)
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
 
@@ -25,20 +25,20 @@ 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 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 |
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
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 |
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
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
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 |
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
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 |
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
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 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.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 |
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
@@ -48,9 +48,9 @@ This is a genuinely strong tool; pretending otherwise would make this page usele
48
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 (out-of-tree adapter classes against a registry since v0.10.0), 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
 
@@ -65,12 +65,12 @@ This is a genuinely strong tool; pretending otherwise would make this page usele
65
65
  ## What they share
66
66
 
67
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).
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
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
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
- - `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.
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-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.
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 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.
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.