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