bmad-module-ultracode-goal 1.0.1 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/README.md +5 -4
  3. package/docs/404.md +1 -1
  4. package/docs/_internal/STABILITY.md +29 -12
  5. package/docs/architecture.md +15 -11
  6. package/docs/comparison.md +19 -11
  7. package/docs/cross-session-recall.md +8 -0
  8. package/docs/gate-model.md +12 -5
  9. package/docs/getting-started.md +8 -2
  10. package/docs/how-it-works.md +2 -2
  11. package/docs/index.md +1 -1
  12. package/docs/operating-tips.md +183 -0
  13. package/docs/troubleshooting.md +9 -5
  14. package/docs/why-ultracode-goal.md +1 -1
  15. package/package.json +5 -4
  16. package/skills/ucg-formalize/SKILL.md +310 -0
  17. package/skills/{ultracode-goal/skills/ucg-resolve → ucg-resolve}/SKILL.md +103 -71
  18. package/skills/ucg-status/SKILL.md +173 -0
  19. package/skills/ultracode-goal/SKILL.md +10 -16
  20. package/skills/ultracode-goal/assets/module-help.csv +1 -1
  21. package/skills/ultracode-goal/assets/module.yaml +8 -3
  22. package/skills/ultracode-goal/assets/ucg-awareness/bmad-testarch-test-design.toml +8 -0
  23. package/skills/ultracode-goal/customize.toml +11 -6
  24. package/skills/ultracode-goal/references/define-done.md +3 -3
  25. package/skills/ultracode-goal/references/execute.md +65 -48
  26. package/skills/ultracode-goal/references/finalize.md +25 -16
  27. package/skills/ultracode-goal/references/gate.md +32 -7
  28. package/skills/ultracode-goal/references/health-check.md +7 -4
  29. package/skills/ultracode-goal/references/ingest-and-scope.md +13 -5
  30. package/skills/ultracode-goal/references/preflight.md +16 -11
  31. package/skills/ultracode-goal/scripts/drive_epic.py +461 -58
  32. package/skills/ultracode-goal/scripts/formalize_check.py +42 -2
  33. package/skills/ultracode-goal/scripts/gate_eval.py +706 -44
  34. package/skills/ultracode-goal/scripts/gate_trail.py +330 -42
  35. package/skills/ultracode-goal/scripts/headless_envelope.py +45 -6
  36. package/skills/ultracode-goal/scripts/health_check_fp.py +98 -3
  37. package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +134 -18
  38. package/skills/ultracode-goal/scripts/mem_observation.py +48 -10
  39. package/skills/ultracode-goal/scripts/preflight_check.py +424 -4
  40. package/skills/ultracode-goal/scripts/status_render.py +20 -2
  41. package/skills/ultracode-goal/scripts/story_sizing.py +193 -0
  42. package/tools/build-docs.js +25 -1
  43. package/tools/cli/lib/ide-skills.js +11 -2
  44. package/tools/validate-docs-links.js +169 -8
  45. package/website/astro.config.mjs +1 -1
  46. package/docs/parallel-mode.md +0 -68
  47. package/skills/ultracode-goal/assets/execute-epic.workflow.js +0 -208
  48. package/skills/ultracode-goal/skills/ucg-formalize/SKILL.md +0 -210
  49. package/skills/ultracode-goal/skills/ucg-status/SKILL.md +0 -136
@@ -19,7 +19,7 @@
19
19
  "name": "bmad-module-ultracode-goal",
20
20
  "source": "./",
21
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": "1.0.1",
22
+ "version": "2.1.0",
23
23
  "author": {
24
24
  "name": "Armel"
25
25
  },
package/README.md CHANGED
@@ -76,7 +76,7 @@ You'll be prompted for a project name and whether to install the learning materi
76
76
  Invoke the skill in natural language: "run this epic autonomously," "execute this epic," or `ultracode goal`. The conductor ingests the epic, preflights, defines done with TEA, executes, gates, and finalizes. Flags shape the run:
77
77
 
78
78
  - `--light`: run the **trace gate only** (the production default runs the full TEA gate set).
79
- - `--parallel`: opt into the **experimental** worktree fan-out instead of the sequential `/goal` spine.
79
+ - `--parallel`: retired. Still accepted so an old invocation does not error: the run logs one note that the flag was accepted and ignored, then executes the sequential `/goal` spine.
80
80
  - `--yes`: skip Stage 1's open-floor invite and the launch confirm. It **never** skips the hard preflight gate.
81
81
  - `-H`: headless: run non-interactively and emit the five-key status JSON at every exit point.
82
82
  - `--retro`: run the close-out retrospective (interactive runs offer it anyway; headless runs it only when this flag is passed).
@@ -107,7 +107,7 @@ You don't have to take the gate's word for it. The deterministic pieces ship wit
107
107
  Run the Python suite (600+ tests across the preflight, gate, hook, readiness, memory, and customization scripts):
108
108
 
109
109
  ```bash
110
- uv run --with pytest pytest skills/ultracode-goal/scripts/tests/ -v
110
+ uv run --with pytest==9.1.1 --with pytest-xdist==3.8.0 pytest skills/ultracode-goal/scripts/tests/ -n auto
111
111
  ```
112
112
 
113
113
  Then inspect any `gate-decision.json` TEA wrote and evaluate it directly:
@@ -130,7 +130,6 @@ The docs are organized into three buckets: **Why** (start here), **Try** (do stu
130
130
 
131
131
  - **[Getting Started](./docs/getting-started.md)**: install, prerequisites, the flags, and your first autonomous run.
132
132
  - **[How It Works](./docs/how-it-works.md)**: the six stages, their routing conditions, and the headless five-key emit.
133
- - **[Parallel Mode](./docs/parallel-mode.md)**: the experimental worktree fan-out and its known limits.
134
133
 
135
134
  **Reference**
136
135
 
@@ -139,7 +138,9 @@ The docs are organized into three buckets: **Why** (start here), **Try** (do stu
139
138
  - **[Health Check](./docs/health-check.md)**: the terminal self-improvement loop: what it sends, privacy, and how to disable it.
140
139
  - **[Cross-Session Recall](./docs/cross-session-recall.md)**: the optional claude-mem integration: touchpoints, trust model, and how to enable it.
141
140
  - **[Knowledge-Graph Refresh](./docs/knowledge-graph-refresh.md)**: the optional graphify integration: preconditions, what it sends where, and what it never touches.
141
+ - **[Operating Tips](./docs/operating-tips.md)**: field notes from real drives: the driver's stop reasons, sequencing by row order, and the verification traps.
142
142
  - **[Troubleshooting](./docs/troubleshooting.md)**: real failure modes and their remediations.
143
+ - **[UCG vs bmad-loop](./docs/comparison.md)**: a side-by-side comparison with bmad-code-org's bmad-loop orchestrator.
143
144
 
144
145
  Every run that reaches Finalize ends with a self-improvement check that can file a deduplicated GitHub issue with your approval, so **please let runs finish through Finalize**, or [open an issue](https://github.com/armelhbobdad/bmad-module-ultracode-goal/issues/new/choose) directly. If UCG shipped an epic while you slept, a ⭐ helps others find it.
145
146
 
@@ -151,7 +152,7 @@ UCG is a conductor over primitives it does not replace. It builds on:
151
152
  | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
152
153
  | [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD) | The epic toolbox UCG orchestrates (sprint planning, story creation, dev, review) |
153
154
  | [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 |
154
- | [Claude Code](https://claude.com/product/claude-code) | `/goal`, Auto Mode, Auto Memory, hooks, and git worktrees, the primitives UCG composes |
155
+ | [Claude Code](https://claude.com/product/claude-code) | `/goal`, Auto Mode, Auto Memory, hooks, and git branches, the primitives UCG composes |
155
156
 
156
157
  ## Contributing
157
158
 
package/docs/404.md CHANGED
@@ -12,7 +12,7 @@ Use the **search bar** at the top of the page, or jump to one of these pages tha
12
12
 
13
13
  **Why**: [Why UltraCode Goal](./why-ultracode-goal.md)
14
14
 
15
- **Try**: [Getting Started](./getting-started.md) · [How It Works](./how-it-works.md) · [Parallel Mode](./parallel-mode.md)
15
+ **Try**: [Getting Started](./getting-started.md) · [How It Works](./how-it-works.md) · [Architecture](./architecture.md)
16
16
 
17
17
  **Reference**: [Architecture](./architecture.md) · [Gate Model](./gate-model.md) · [Health Check](./health-check.md) · [Troubleshooting](./troubleshooting.md)
18
18
 
@@ -1,15 +1,15 @@
1
1
  ---
2
2
  title: Stability and Public Contract
3
- description: "The 0.1.0 stability posture: which CLI, config, JSON, and gate surfaces are the supported public contract versus everything that is @internal and free to change."
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."
4
4
  ---
5
5
 
6
- > **Status:** 0.x, pre-1.0. The surfaces below are the intended public contract at `0.1.0`. Per [Semantic Versioning 2.0.0](https://semver.org/), a `0.x` series makes no stability guarantee across minor versions; this document records what we *try* to hold stable and what is explicitly `@internal`, so a consumer knows which surfaces to pin against and which to treat as free to change.
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.
7
7
 
8
- This is the stability posture for `bmad-module-ultracode-goal` at `0.1.0`. 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 `2.x`. It enumerates the surfaces a downstream consumer or automator may reasonably depend on, versus everything else, which is `@internal`.
9
9
 
10
- ## Public contract at 0.1.0
10
+ ## Public contract
11
11
 
12
- The following surfaces are the intended public contract. We aim not to break them within the `0.x` series without a deprecation note; see [SemVer note](#semver-note).
12
+ The following surfaces are the public contract. Breaking one requires a MAJOR bump; see [SemVer note](#semver-note).
13
13
 
14
14
  ### CLI command surface
15
15
 
@@ -20,10 +20,12 @@ 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`, `allowlist_commands`, `on_epic_complete`, and `on_escalation`) 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`, 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
 
27
+ `parallel_max_concurrency` is **deprecated** on the same terms, as of the retirement of the experimental `--parallel` fan-out: still shipped, still accepted, still resolves, read by nothing. The `--parallel` flag itself is likewise still accepted by the skill and ignored (the run logs one note and executes the sequential spine), so an operator's old invocation keeps working.
28
+
27
29
  ### The headless five-key JSON emit shape
28
30
 
29
31
  Every headless (`-H`) exit point emits one object with exactly these five keys, always present, `null` when an artifact was not produced, plus a conditional sixth, `reason`, carrying a one-line cause only when blocked. A **complete** emit omits `reason` entirely; it is not present-and-`null`, so read it only when `status` is `blocked`:
@@ -48,7 +50,7 @@ A headless run writes that same object to `{workflow.implementation_artifacts}/r
48
50
 
49
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.
50
52
 
51
- 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, and under the experimental `--parallel` mode each worktree agent sees its own artifacts path, so no single `run-result.json` describes a fan-out run.
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.
52
54
 
53
55
  ### The skill name and invocation phrases
54
56
 
@@ -58,7 +60,8 @@ The skill name `ultracode-goal` and its documented invocation phrases ("run an e
58
60
 
59
61
  `scripts/gate_eval.py` is the deterministic completion authority. Covered:
60
62
 
61
- - **CLI flags**: `--trace-output` (required), `--profile` (`light` | `production`, required), `--story`, `--nfr`, `--test-review` (production only).
63
+ - **CLI flags**: `--trace-output` (required), `--profile` (`light` | `production`, required), `--story`, `--nfr`, `--test-review` (production 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 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.
62
65
  - **Verdict vocabulary**: the `verdict` values `advance` / `defer` / `reloop` / `escalate`, and the `gate_status` values `PASS` / `CONCERNS` / `FAIL` / `WAIVED` / `NOT_EVALUATED`, plus the mapping between them. See the [gate model](../gate-model.md).
63
66
  - **`--story` fail-closed resolution**: when `--story` matches no artifact in a trace dir whose reports or gate-decision files are named per story, the result is `NOT_EVALUATED` (so, `escalate`), never a fallback to another story's gate. A trace dir whose candidates are all generically named (`trace.md`, `gate-decision.json`) still resolves unscoped. Which file the resolver picks, and how it decides that a name carries a story id, are internal.
64
67
 
@@ -75,18 +78,32 @@ flowchart LR
75
78
  class ADV,DEF,REL,ESC verdict
76
79
  ```
77
80
 
78
- The printed JSON object's key set (`verdict`, `gate_status`, `p0_status`, `p1_status`, `overall_status`, `nfr_status`, `review_score`, `reasons`) is the consumable shape; the human-readable `reasons` strings are not contractual wording.
81
+ 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. `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.
79
82
 
80
83
  ## @internal: not covered
81
84
 
82
- Everything not enumerated above is `@internal` and may change in any `0.x` release without a deprecation note. Do not pin against:
85
+ Everything not enumerated above is `@internal` and may change in any release, major or minor, without a deprecation note. Do not pin against:
83
86
 
84
87
  - **Installer library internals**: the implementation behind the CLI subcommands; what is covered is the observable subcommand surface, not how the files get placed.
85
88
  - **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.
86
89
  - **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.
87
- - **The experimental `--parallel` workflow**: `assets/execute-epic.workflow.js`, the `/ultracode-goal-execute` registration, its args binding, its return shape, and `parallel_max_concurrency`'s runtime behavior are explicitly experimental and excluded from the contract. See [parallel mode](../parallel-mode.md).
90
+ - **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)).
88
91
  - **`_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.
89
92
 
90
93
  ## SemVer note
91
94
 
92
- This is a `0.x` module: **minor versions may break.** We try to hold the surfaces in [Public contract at 0.1.0](#public-contract-at-010) stable, and 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` before changing. `@internal` surfaces change freely. Once the module reaches `1.0.0`, this document is superseded by a full SemVer contract.
95
+ **A breaking change to any surface in [Public contract](#public-contract) requires a MAJOR bump.** That is the whole rule, and it is deliberately stricter than "we try": this module's value is that a machine-checked contract means what it says, so the versioning of the contract has to as well.
96
+
97
+ What counts as breaking, stated so it is not re-litigated per release:
98
+
99
+ - Removing or renaming an enumerated CLI flag, subcommand, config key, or JSON key.
100
+ - **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.
101
+ - Adding a key to the printed verdict JSON or the headless envelope, for a consumer validating the shape strictly.
102
+
103
+ What does not:
104
+
105
+ - Fixing a resolver so it returns the *right* artifact rather than a neighbour's, where the documented invocation and its vocabulary are unchanged.
106
+ - Anything behind `@internal`, including which file a resolver picks and how it decides a name carries a story id.
107
+ - Prose in `references/*.md`, which is an authoring surface.
108
+
109
+ **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.
@@ -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/worktree 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 (`/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.
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-check-implementation-readiness`, `bmad-dev-story`, `bmad-code-review`, `bmad-correct-course`, `bmad-sprint-status`, `bmad-retrospective`.
12
+ - **Epic toolbox**: `bmad-sprint-planning`, `bmad-create-story`, `bmad-dev-story`, `bmad-code-review`, `bmad-correct-course`, `bmad-retrospective`.
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 and worktrees provide isolation and rollback.
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.
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
 
@@ -34,7 +34,7 @@ Both hooks read their config from env first (so the conductor injects per-run va
34
34
 
35
35
  ### 3. Budget enforcement
36
36
 
37
- 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, worktree isolation under `--parallel`) because `/rewind` checkpoints miss the Bash-driven changes that make up the run.
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.
38
38
 
39
39
  ## File layout
40
40
 
@@ -60,6 +60,7 @@ skills/ultracode-goal/
60
60
  │ ├── formalize_check.py # readiness kernel behind the /ucg-formalize gate
61
61
  │ ├── status_render.py # read-side render behind /ucg-status
62
62
  │ ├── red_ids.py # preflight-RED identity (the resolve join key)
63
+ │ ├── story_sizing.py # decomposition sizing + parent-AC claim reconciliation
63
64
  │ ├── drive_epic.py # one `claude -p` per story (--max-stories work bound)
64
65
  │ ├── headless_envelope.py # the one five-key headless-envelope adapter
65
66
  │ ├── health_check_fp.py # health-check fingerprint + seen-cache plumbing
@@ -72,17 +73,20 @@ skills/ultracode-goal/
72
73
  │ └── hooks/
73
74
  │ ├── guard_pretooluse.py # commit invariants (PreToolUse)
74
75
  │ └── budget_stop.py # turn budget (Stop)
75
- ├── skills/
76
- │ ├── ucg-formalize/ # Standalone readiness gate
77
- │ ├── ucg-resolve/ # Decide-surface for a blocked or escalated run
78
- │ └── ucg-status/ # Read-only status view over a run
79
76
  └── assets/
80
- ├── execute-epic.workflow.js # EXPERIMENTAL --parallel worktree fan-out
81
77
  ├── module.yaml · module-setup.md · module-help.csv # install metadata
82
78
  └── ucg-awareness/ # shift-left planning customization fragments
79
+
80
+ skills/ucg-formalize/ # Standalone readiness gate
81
+ skills/ucg-resolve/ # Decide-surface for a blocked or escalated run
82
+ skills/ucg-status/ # Read-only status view over a run
83
+ # Top-level siblings of `ultracode-goal`, not children:
84
+ # the IDE's skill loader enumerates one level, so a
85
+ # nested command never resolves. Each stays thin and
86
+ # reaches back into the parent via `{ucg-root}`.
83
87
  ```
84
88
 
85
- `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 `skills/` subskills 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 the experimental `--parallel` workflow plus install metadata and the planning-customization fragments. See [how it works](./how-it-works.md) for the stages and [parallel mode](./parallel-mode.md) for the workflow asset.
89
+ `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.
86
90
 
87
91
  ## Customization resolution
88
92
 
@@ -94,7 +98,7 @@ Configuration resolves in three layers, base → team → user, via `resolve_cus
94
98
 
95
99
  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.
96
100
 
97
- 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), the experimental `parallel_max_concurrency`, 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).
101
+ 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).
98
102
 
99
103
  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:
100
104
 
@@ -5,13 +5,19 @@ 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) 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 v1.0.0 and bmad-loop v0.9.0, as of 2026-07-28, both released versions. Both projects are young and moving fast. bmad-loop's v0.9.0 (released 2026-07-21) shipped four of the five items the previous snapshot listed as unreleased work on main: a `stories.yaml` planning mode with per-story checkpoints, patch-restore escalation recovery, a pluggable multiplexer-backend registry, and the integrity fixes to its verify gate. The fifth was this page's error rather than a gap in the release: those adversarial review layers are BMAD-METHOD's, declared in `bmad-dev-auto` and run against BMAD-METHOD's own review skills, and what v0.9.0 added was a preflight that refuses to start when they are missing. It also added a graceful stop that finishes the in-flight item before ending a run, an active-agent indicator in the dashboard, an OpenCode adapter driven over HTTP rather than a multiplexer, and stable, schema-versioned `--json` documents for six more commands: `status`, `list`, `validate`, `decisions`, `clean`, and `cleanup`. Eight commands now emit versioned documents, `diagnose` and `probe-adapter` having been converted from a JSON block appended to a text report; most of what is left is action commands with no document to emit. UCG reached v1.0.0 on 2026-07-28. 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.
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.
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.
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.
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.
9
15
 
10
16
  ## The one difference everything else follows from
11
17
 
12
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.
13
19
 
14
- 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 experimental `--parallel` fan-out additionally uses a dynamic workflow, and degrades to the sequential spine when one is unavailable. 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 `/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.
15
21
 
16
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.
17
23
 
@@ -25,14 +31,14 @@ The consequence cascades: bmad-loop is a tool you run beside any supported agent
25
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 |
26
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` |
27
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 |
28
- | Pre-launch gate | `validate`: 26 registered checks at v0.9.0 (BMAD config, policy, sprint-status, git, multiplexer and process host, CLI binary and profile, hook registration, base skills, stories-mode manifest and dispatch) | A mechanical preflight script plus a readiness check and a semantic scan that refuse to launch on an undecided product or architecture decision |
29
- | 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 on the sequential spine (the `--parallel` fan-out uses the `/workflows` view instead and writes no 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 |
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 |
30
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 |
31
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 |
32
- | Isolation | In place by default; opt-in git worktree per story or bundle, merged back locally | None by default (stories run sequentially in one session); an experimental `--parallel` mode fans stories out into git worktrees |
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) |
33
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) |
34
40
  | Self-improvement | Not shipped | A health check that files deduplicated GitHub issues about its own friction |
35
- | Maturity | First-party (bmad-code-org); v0.9.0, whose headline is stable schema-versioned `--json` contracts that evolve additively; rich docs; CI + test suite | Community module; v1.0.0, which binds an already-stated contract (the headless envelope and `gate_eval.py`'s verdict vocabulary were covered at 0.x) under SemVer and adds `run-result.json` to it; docs site; CI + test suite |
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 |
36
42
  | License | MIT | MIT |
37
43
 
38
44
  ## Where bmad-loop is stronger
@@ -52,14 +58,14 @@ This is a genuinely strong tool; pretending otherwise would make this page usele
52
58
 
53
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.
54
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.
55
- 3. **A planning-readiness gate that can refuse to launch.** UCG's preflight hands the PRD, the architecture, and the stories to a throwaway subagent that hunts for undecided product or architecture decisions, contradictions between the PRD and the architecture, and any story whose "done" cannot be pinned down. The scan grades what it finds, and any RED verdict stops the run rather than letting an unattended agent guess; the one way past a RED is an operator recording a `close` for it, since a `defer` does not clear one and an unreadable decisions file clears nothing. That scan is itself LLM judgment, the very thing bmad-loop keeps out of its loop; the difference is that it can only block a launch, never pass one, and the readiness kernel beside it is deterministic (v1.0.0 closed three fail-opens there, where an Epic with no stories, a story with no acceptance criteria, and a partially seeded story set each used to score `ready`). bmad-loop's preflight is mechanical and assumes the sprint's stories are already ready to build.
56
- 4. **Almost no moving parts outside the agent.** The autonomous run is a skill: no daemon, no multiplexer, no session to attach to. For a Claude Code user that is a smaller operational surface, and it is also exactly why UCG cannot run anywhere else. Two qualifiers, added honestly. Three companion skills ship alongside the run and none is required by one: `ucg-formalize` (the standalone readiness gate), `ucg-status` (the read-only run view), and `ucg-resolve` (the decide-surface for a stopped run). And a long Epic accumulates every story's transcript in one session, so UCG ships an optional driver script that spawns one `claude -p` per story; use it and you are running a loop outside the agent after all, which is bmad-loop's model in miniature. The difference is that it is opt-in and about 900 lines, where bmad-loop's orchestrator is the product; skip it and the skill still runs standalone, since `--max-stories` is a flag on the skill rather than something the script provides.
61
+ 3. **A planning-readiness gate that can refuse to launch.** UCG's preflight hands the PRD, the architecture, and the stories to a throwaway subagent that hunts for undecided product or architecture decisions, contradictions between the PRD and the architecture, and any story whose "done" cannot be pinned down. The scan grades what it finds, and any RED verdict stops the run rather than letting an unattended agent guess; the one way past a RED is an operator recording a `close` for it, since a `defer` does not clear one and an unreadable decisions file clears nothing. That scan is itself LLM judgment, the very thing bmad-loop keeps out of its loop; the difference is that it can only block a launch, never pass one, and the readiness kernel beside it is deterministic. That kernel has been the module's most defect-prone surface, and the honest reading is that it took three releases to make it fail closed: v1.0.0 closed three fail-opens where an Epic with no stories, a story with no acceptance criteria, and a partially seeded story set each scored `ready`, and v2.0.0 closed two more, where a present-but-unparseable sprint board emptied the in-scope set (silencing both guards that exist to catch exactly that), and where a citation in a story counted as its own declaration, so a dangling reference could never be reported and the judgment branch was unreachable. bmad-loop's preflight is mechanical and assumes the sprint's stories are already ready to build.
62
+ 4. **Almost no moving parts outside the agent.** The autonomous run is a skill: no daemon, no multiplexer, no session to attach to. For a Claude Code user that is a smaller operational surface, and it is also exactly why UCG cannot run anywhere else. Two qualifiers, added honestly. Three companion skills ship alongside the run and none is required by one: `ucg-formalize` (the standalone readiness gate), `ucg-status` (the read-only run view), and `ucg-resolve` (the decide-surface for a stopped run). Worth recording rather than quietly fixing: until v2.0.0 all three shipped one directory too deep for the skill loader, which enumerates a single level, so every one of them returned `Unknown skill` when invoked. Every check the project had verified they were *present*, and they were; none tested whether they were *reachable*. And a long Epic accumulates every story's transcript in one session, so UCG ships an optional driver script that spawns one `claude -p` per story; use it and you are running a loop outside the agent after all, which is bmad-loop's model in miniature. The difference is that it is opt-in and about 900 lines, where bmad-loop's orchestrator is the product; skip it and the skill still runs standalone, since `--max-stories` is a flag on the skill rather than something the script provides.
57
63
  5. **A self-improvement loop.** UCG's finalize step can file deduplicated GitHub issues about friction in its own workflow, so the tool reports its own rough edges.
58
64
 
59
65
  ## What they share
60
66
 
61
- - A deterministic completion authority the model cannot talk its way past: bmad-loop's artifact, diff, and command checks; UCG's TEA gate read (on a non-web stack, under either profile, the trace artifacts are agent-authored under strict honesty rules, so the guarantee there is procedural rather than mechanical).
62
- - 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. 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: 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`.
63
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`.
64
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.
65
71
  - Optional git worktree isolation.
@@ -81,4 +87,6 @@ Both tools change weekly, so re-check before you rely on anything above:
81
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).
82
88
  - UCG: [How It Works](./how-it-works.md) and the [Gate Model](./gate-model.md).
83
89
 
84
- This snapshot was re-cut on 2026-07-28 against bmad-loop v0.9.0 (released 2026-07-21) and UCG v1.0.0 (released 2026-07-28); the previous cut (2026-07-12) read bmad-loop v0.8.1 and UCG v0.5.1, and the one before it (2026-06-28, bmad-auto v0.7.4 and UCG v0.4.0) predates the rename.
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.
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.
@@ -17,6 +17,14 @@ You need [claude-mem](https://github.com/thedotmack/claude-mem) installed and th
17
17
 
18
18
  > claude-mem is a third-party plugin maintained independently of this module. We don't bundle, endorse, or install it; Cross-Session Recall simply uses it when you already have it.
19
19
 
20
+ **Two headless caveats, both observed rather than theoretical.**
21
+
22
+ *Your harness may gate the MCP call behind a permission prompt.* An unattended run has nobody to answer it, so the tools are listed, their schemas resolve, and the one sanctioned `search` is refused at call time. UCG handles that correctly (it latches red, logs a `WARN`, and proceeds gateless, since recall is advisory and never part of the gate) but it pays one call every run to rediscover it. One project recorded that outcome on 25 consecutive runs. If that is your situation, `on` means **off in practice**: either grant the permission once, or set `cross_session_recall = "off"` and stop paying for the probe.
23
+
24
+ *The latch only enforces anything if your PreToolUse hook is armed for MCP tools.* The guard denies a claude-mem call under a red latch, but Claude Code only invokes a hook group for the tools its `matcher` selects, and a group armed for `Bash` alone is never invoked for an MCP call. Preflight arms it with an all-tools matcher for exactly this reason; if you merge the hook by hand, match every tool or this gate is inert.
25
+
26
+ *And claude-mem may expose reads without a write.* The latch is validated by a read-shaped probe, so `present` certifies that UCG can look, not that there is anywhere to write. On a surface with no write tool, Finalize parks its summary and says so rather than reporting a failed write.
27
+
20
28
  ## The touchpoints
21
29
 
22
30
  Recall touches the run in exactly three places, and a machine latch (`.mem-state.json`) gates every one of them. The latch is written **once** at Ingest and removed at Finalize close-out; while it is present a `PreToolUse` hook allows claude-mem calls only when recall is green, and denies them otherwise: fail closed. The Execute and Gate stages are never touched.
@@ -59,25 +59,32 @@ Under `--profile production`, an otherwise-`advance` verdict is additionally AND
59
59
  - **NFR** (`nfr-assessment.md`): the audit's Overall Status must not be `FAIL`.
60
60
  - **Test review** (`test-review.md`): the Quality Score must be `>= 80` **and** the Recommendation must not be `Block`.
61
61
 
62
- How the AND folds the two signals in, with every unreadable path counting as a failure:
62
+ **Both paths are required, and an omitted flag is a failure too.** A path that is given but missing counts as failing, and so does one you simply leave off: the AND cannot run on a signal nobody named. That matters because the two used to differ. A forgotten flag was skipped in silence, `nfr_status` rendered `null`, and the verdict was computed without it, so forgetting a flag bought a *higher* verdict than supplying a failing artifact would have.
63
+
64
+ The one legitimate omission is the **epic roll-up**, where TEA writes no aggregate to AND, because it produces both artifacts per story. That case declares itself with `--epic-level` rather than being inferred from an absent flag, and the flag cannot be combined with either path (an invocation error, exit 2). The verdict JSON carries `epic_level` so a reader can tell a skipped-AND `advance` from one that ANDed both signals.
65
+
66
+ How the AND folds the two signals in, with every unreadable *or unsupplied* path counting as a failure:
63
67
 
64
68
  ```mermaid
65
69
  flowchart TD
66
70
  V{"Verdict is advance?"} -->|"no, defer/reloop/escalate"| K["Unchanged"]
67
- V -->|"yes"| N{"NFR Overall Status"}
71
+ V -->|"yes"| E{"--epic-level declared?"}
72
+ E -->|"yes, no aggregate to AND"| A["Stay advance"]
73
+ E -->|"no, per-story gate"| N{"NFR Overall Status"}
68
74
  N -->|"FAIL"| F["Signal failed"]
69
75
  N -->|"file missing or unparsable"| F
76
+ N -->|"--nfr not supplied"| F
70
77
  N -->|"parsed and not FAIL"| R{"Test review"}
71
78
  R -->|"score lt 80 or Block"| F
72
79
  R -->|"score unparsable, file missing"| F
73
- R -->|"score gte 80 and not Block"| P["Both signals passed"]
80
+ R -->|"--test-review not supplied"| F
81
+ R -->|"score gte 80 and not Block"| A
74
82
  F --> D["Downgrade advance to reloop"]
75
- P --> A["Stay advance"]
76
83
  classDef verdict fill:#4F46E5,stroke:#3730A3,color:#fff
77
84
  class A,D,K verdict
78
85
  ```
79
86
 
80
- Under `--profile light` none of this applies: the trace gate is the whole decision.
87
+ Under `--profile light` none of this applies: the trace gate is the whole decision, and `--epic-level` is a no-op there.
81
88
 
82
89
  ## The thresholds
83
90
 
@@ -45,7 +45,7 @@ From there the run is autonomous: it defines done with TEA, executes each story
45
45
  | Flag | Effect |
46
46
  |------|--------|
47
47
  | `--light` | Trace-only gate. Downscopes from the full TEA chain to `bmad-testarch-trace` plus `gate_eval.py --profile light`: no NFR/test-review AND. |
48
- | `--parallel` | Experimental worktree fan-out. Each story runs isolated in its own worktree; no mid-run input. The sequential `/goal` spine is the default and recommended path; see [parallel mode](./parallel-mode.md). |
48
+ | `--parallel` | Retired. The flag is still accepted so an old invocation does not error: the run logs one note that it was accepted and ignored, then executes the sequential `/goal` spine. |
49
49
  | `--yes` | Skips Stage 1's open-floor invite and the launch confirm. The launch briefing still prints. **Never** skips the hard preflight gate. |
50
50
  | `-H` | Headless. Runs non-interactively, never prompts (an unresolvable secret becomes a red blocker, not a question), and emits one JSON object at every exit point. |
51
51
  | `--retro` | Runs the close-out retrospective (`bmad-retrospective`). Interactive runs offer it at Epic close anyway; headless runs it only when `--retro` is passed. |
@@ -67,7 +67,13 @@ Run it from your project root. The path above is the Claude Code skill copy the
67
67
 
68
68
  Drop `--dry-run` to actually spawn. Point `--impl-artifacts` at the directory holding your `sprint-status.yaml`; the driver refuses to start if it is not there, since that is the sprint plan it reads. That directory also has to be the one your config resolves `implementation_artifacts` to, because the spawned session writes its terminal `run-result.json` where the config says, not where the driver was pointed. The driver cannot check that half for you: it would have to re-implement the skill's own config resolution to do it.
69
69
 
70
- The driver is read-only on your tree with exactly one exception: it deletes the pinned `run-result.json` before each spawn, so the file's presence means *that* spawn reached a terminal. It stops on anything it cannot verify, and says why: no readable terminal, a `blocked` envelope (with the reason), a status it does not recognize, a `complete` whose story did not reach `done`, or a session that outran `--session-timeout` (2 hours by default; `0` disables it). Useful flags: `--limit N` caps how many sessions it spawns, `--permission-mode` defaults to `acceptEdits` and refuses `bypassPermissions` unless you also pass `--allow-full-autonomy`, and `--skill-command` overrides the invocation string for a plugin-marketplace install (`/bmad-module-ultracode-goal:ultracode-goal`).
70
+ The driver is read-only on your tree with exactly one exception: it deletes the pinned `run-result.json` before each spawn, so the file's presence means *that* spawn reached a terminal. It stops on anything it cannot verify, and says why: no readable terminal, a `blocked` envelope (with the reason), a status it does not recognize, a `complete` whose story did not reach `done`, or a session that outran `--session-timeout` (2 hours by default; `0` disables it).
71
+
72
+ **One of those is retried rather than fatal.** A `claude -p` can be terminated in flight by the API layer, leaving no terminal, and that is not a story problem: the same row lands on the next attempt against identical state. The driver retries a no-terminal stop up to `--max-abort-retries` times (default 2, `0` disables), but **only** when its post-stop triage finds the tree clean and HEAD unmoved, so a retry can never re-spawn over work in progress.
73
+
74
+ **Every post-spawn stop now prints a triage block** describing the tree the session left: clean with HEAD advanced (the work committed and only close-out is missing, so verify and mark it done rather than re-driving), clean and unmoved (nothing landed), or dirty (which may hold a suite that is already green). It reports and never decides. It also names any intent-to-add path, because `git checkout -- <path>` truncates those to zero bytes and exits `0`.
75
+
76
+ Useful flags: `--limit N` caps how many sessions it spawns, retries included, `--permission-mode` defaults to `acceptEdits` and refuses `bypassPermissions` unless you also pass `--allow-full-autonomy`, and `--skill-command` overrides the invocation string for a plugin-marketplace install (`/bmad-module-ultracode-goal:ultracode-goal`).
71
77
 
72
78
  ## Hook security
73
79
 
@@ -78,7 +78,7 @@ Turn the Epic's acceptance criteria into **executable, red-phase acceptance test
78
78
 
79
79
  ### Stage 4: Execute
80
80
 
81
- Drive each in-scope story from its red-phase tests to a green, committed state. The default is the **sequential `/goal` spine**; per story, in sprint order: set the current story (so the PreToolUse hook can find its marker) → `bmad-dev-story` implements the feature and un-skips the story's ATDD tests → run tests/lint/build and **print the raw output** as evidence → (production) `bmad-testarch-test-review` then `bmad-code-review` → commit at green (one commit per green story) → **re-run the full suite on the committed HEAD** and print it, because a story's new files are untracked until the commit, so a tracked-files conformance gate can only red once they land; a red here means the story is not done and must be remediated and re-committed before it advances. The loop is wrapped in a single `/goal` whose condition encodes the per-story Definition-of-Done and carries the literal "…or stop after N turns" escape clause. The printed evidence keeps the run judgeable mid-flight, but **passing the `/goal` condition is not completion**; the authoritative verdict is Stage 5. The experimental `--parallel` path fans the same per-story loop out across worktree-isolated agents; see [parallel mode](./parallel-mode.md). As the spine advances it overwrites a `run-status.json` heartbeat for pollers. See [`references/execute.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/execute.md).
81
+ Drive each in-scope story from its red-phase tests to a green, committed state. Execution is the **sequential `/goal` spine**; per story, in sprint order: set the current story (so the PreToolUse hook can find its marker) → `bmad-dev-story` implements the feature and un-skips the story's ATDD tests → run tests/lint/build and **print the raw output** as evidence → (production) `bmad-testarch-test-review` then `bmad-code-review` → commit at green (one commit per green story) → **re-run the full suite on the committed HEAD** and print it, because a story's new files are untracked until the commit, so a tracked-files conformance gate can only red once they land; a red here means the story is not done and must be remediated and re-committed before it advances. The loop is wrapped in a single `/goal` whose condition encodes the per-story Definition-of-Done and carries the literal "…or stop after N turns" escape clause. The printed evidence keeps the run judgeable mid-flight, but **passing the `/goal` condition is not completion**; the authoritative verdict is Stage 5. As the spine advances it overwrites a `run-status.json` heartbeat for pollers. See [`references/execute.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/execute.md).
82
82
 
83
83
  ### Stage 5: Gate
84
84
 
@@ -170,4 +170,4 @@ case "$status" in
170
170
  esac
171
171
  ```
172
172
 
173
- The file is overwrite-in-place, and a headless run additionally clears any prior copy at startup, so a second run against the same artifacts path never leaves the first run's result readable once it begins. Under experimental `--parallel` each worktree agent sees its own artifacts path: there is no single `run-result.json` for a fan-out run. An attended run writes no file at all, and does not clear one either, since an operator reads the outcome from the conversation and the report and may still be consulting a previous result.
173
+ The file is overwrite-in-place, and a headless run additionally clears any prior copy at startup, so a second run against the same artifacts path never leaves the first run's result readable once it begins. An attended run writes no file at all, and does not clear one either, since an operator reads the outcome from the conversation and the report and may still be consulting a previous result.
package/docs/index.md CHANGED
@@ -55,7 +55,6 @@ The docs split into three buckets: **Why** (start here), **Try** (do stuff), and
55
55
 
56
56
  - [Getting Started](./getting-started.md): prerequisites, install, the flags, and your first autonomous run.
57
57
  - [How It Works](./how-it-works.md): the six stages, their routing conditions, and the headless emit shape.
58
- - [Parallel Mode](./parallel-mode.md): the experimental worktree fan-out and its known limits.
59
58
 
60
59
  **Reference**
61
60
 
@@ -64,5 +63,6 @@ The docs split into three buckets: **Why** (start here), **Try** (do stuff), and
64
63
  - [Health Check](./health-check.md): the terminal self-improvement reflection: what it sends, the privacy model, and how to disable it.
65
64
  - [Cross-Session Recall](./cross-session-recall.md): the optional claude-mem integration and its trust model.
66
65
  - [Knowledge-Graph Refresh](./knowledge-graph-refresh.md): the optional graphify integration, its preconditions, and what it sends where.
66
+ - [Operating Tips](./operating-tips.md): field notes from real drives: the driver's stop reasons, why row order is the only sequencing mechanism, and the verification traps.
67
67
  - [Troubleshooting](./troubleshooting.md): real failure modes and their remediations.
68
68
  - [UCG vs bmad-loop](./comparison.md): a side-by-side comparison with bmad-code-org's bmad-loop orchestrator (formerly bmad-auto).