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
package/docs/operating-tips.md
CHANGED
|
@@ -73,7 +73,7 @@ The dangerous part is what it leaves behind. In the observed case the dead sessi
|
|
|
73
73
|
|
|
74
74
|
**On any resume, believe the artifacts and the sprint-status row, never the story file's prose.** Check for the gate *file* before treating a story as gated.
|
|
75
75
|
|
|
76
|
-
The correct recovery is to re-drive the story. The skill re-enters at Execute, re-measures the committed tree, produces the trace evidence (TEA's `bmad-testarch-trace`, or hand-authored to `gate_eval.py`'s shape
|
|
76
|
+
The correct recovery is to re-drive the story. The skill re-enters at Execute, re-measures the committed tree, produces the trace evidence (TEA's `bmad-testarch-trace`, which on TEA 1.27.2 runs on any stack, or hand-authored to `gate_eval.py`'s shape where trace cannot run), and runs `gate_eval.py` for real. Because the dead session already committed, make sure the re-drive re-reads the story's existing baseline marker rather than regenerating it: a rebuilt baseline re-anchors the evidence range to a mid-story HEAD, and the trace then measures only the tail of the work.
|
|
77
77
|
|
|
78
78
|
Do not hand-mark the story `done` on the strength of your own verification, however thorough: that substitutes your judgment for the gate and produces exactly the artifact-free "PASS" the tool exists to prevent.
|
|
79
79
|
|
|
@@ -150,7 +150,9 @@ The gate is a real verdict and worth trusting. The prose around it is not eviden
|
|
|
150
150
|
|
|
151
151
|
**Prefer executed mutation over a modeled mutant.** A hand-written mutant that differs from the real pre-fix code proves nothing about the real branch. Where a story claims a mutation-proof, re-run one yourself against the shipped code.
|
|
152
152
|
|
|
153
|
-
**
|
|
153
|
+
**Use the shipped runner rather than hand-rolling the harness.** `uv run <skill-root>/scripts/mutate_check.py --table <rows.json>` builds the properties every hand-rolled harness eventually lost in as refusals: a green-baseline precheck, per-row anchor uniqueness (a missing anchor is reported as STALE, the formatter-reflow signature, never silently skipped), an attributable red, a byte-identical restore, and a generated `mutation-ledger-<story_id>.md` that leads with GREEN survivors. The two tips below are what the runner automates; they remain worth knowing for reading its output and for the rare harness it cannot drive.
|
|
154
|
+
|
|
155
|
+
**Make any hand-rolled harness hard-error on a missing anchor.** Observed: a harness silently skipped its mutation twice when a refactor moved the anchor, and reported the suite's ordinary green as a passing twin.
|
|
154
156
|
|
|
155
157
|
**Back files up with `cp` and restore from the backup.** Never `git checkout -- <path>` or `git restore <path>` to undo a mutation: both restore from the *index*, and an intent-to-add entry (`git add -N`) holds the empty blob, so they truncate the file to zero bytes and exit 0 (measured on git 2.47). For a file that has a committed version, `git checkout HEAD -- <path>` is safe. For a file the story just created, nothing git offers is: `git checkout HEAD --` refuses, and `git restore --source=HEAD --` deletes the file with exit 0. The `cp` backup is the only restore that always works.
|
|
156
158
|
|
package/docs/troubleshooting.md
CHANGED
|
@@ -32,13 +32,16 @@ flowchart TD
|
|
|
32
32
|
|
|
33
33
|
**Symptom.** The run stops at Stage 2 (or, headless, emits `{"status":"blocked", ...}` with a one-line `reason`) and never launches.
|
|
34
34
|
|
|
35
|
-
**What happened.** Preflight is a hard gate: the run launches only when the post-remediation mechanical `budget == 0` **and** the semantic scan found no RED. The auto-remediation pass clears the *fixable* mechanical blockers: it scaffolds the test framework, generates missing acceptance criteria, pre-creates the TEA output dirs, ensures
|
|
35
|
+
**What happened.** Preflight is a hard gate: the run launches only when the post-remediation mechanical `budget == 0` **and** the semantic scan found no RED. The auto-remediation pass clears the *fixable* mechanical blockers: it scaffolds the test framework, generates missing acceptance criteria, pre-creates the TEA output dirs, ensures `sprint-status.yaml`, and prompts once (interactively) for secrets, then re-runs the check. The `project-context.md` count is advisory: preflight de-duplicates more than one, logs a missing one, and never blocks on it.
|
|
36
36
|
|
|
37
37
|
**What stays red.** Some things the remediation pass cannot fix, by design:
|
|
38
38
|
|
|
39
39
|
- **Undecided product or architecture decisions.** An open question, a "TBD"/"TODO: decide" on a load-bearing requirement, a PRD↔ADR contradiction, or a story whose "done" is undefinable. The fix is a human decision; an unattended run guessing it produces confidently wrong work. Resolve the decision in the artifacts, then re-run.
|
|
40
40
|
- **Missing secrets in headless.** Headless never prompts, so a secret that cannot be resolved becomes a RED blocker rather than a question. Provide the secret (out of git) before the headless run, or run attended so preflight can prompt once.
|
|
41
41
|
- **Claude Code below the minimum versions.** The primitive-version blocker is marked non-remediable: the script can't upgrade the host. Update Claude Code.
|
|
42
|
+
- **A repository with nothing committed.** On a fresh `git init` (or an orphan branch) the `git_unborn` blocker is non-remediable: the run never makes the commit its Epic branch would start from, because that commit would sit outside its only rollback, the Epic branch. Commit a baseline yourself (the BMAD install, the planning artifacts and the project skeleton) on your base branch, a protected branch such as `main` and never an Epic branch, then re-run. If HEAD already names an Epic branch, the blocker's detail gives the command that points it at the base first.
|
|
43
|
+
- **A refused settings write.** Preflight writes its hooks and allow rules into `.claude/settings.local.json`, which Claude Code treats as protected. Under Auto Mode the permission classifier may refuse that write, or let it land and refuse the next calls, as self-modification. The run then stops rather than work around the refusal, and the decision log names the write. Attended, approve it under `/permissions` (on its Recently denied tab) or apply it yourself; the run re-checks the hooks and continues. Headless, there is nobody to approve it, and `/ucg-resolve` is not the way back: take the Epic through preflight attended (see [hook security](./getting-started.md#hook-security)).
|
|
44
|
+
- **BMAD story skills not installed.** The run delegates story creation to `bmad-create-story` and implementation to `bmad-dev-story`, and on BMAD Method 6.12 or later both are deprecated shims: a fresh install leaves them out unless asked for (`--shims`, or Yes at the installer's shim prompt), and an update removes them when told not to keep them. The `bmad_skills` blocker is non-remediable: the run neither installs them nor works around them. Its detail names the fix; for a 6.12 install made without shims, that is `npx bmad-method@<version> install --directory . --shims --yes` from the project root. With `--yes` the installer also takes newer minor and patch releases of external modules such as TEA; add `--pin <module>=<version>` to hold one (see [Prerequisites](./getting-started.md#prerequisites)). The same check runs on every resume, so a BMAD update that removes them mid-Epic stops the next spawn instead of letting it improvise.
|
|
42
45
|
|
|
43
46
|
The decision log carries the full blocker list with what each needs to clear. Read it, clear the items, re-run.
|
|
44
47
|
|
|
@@ -53,6 +56,10 @@ The decision log carries the full blocker list with what each needs to clear. Re
|
|
|
53
56
|
|
|
54
57
|
Note this is fail-closed on purpose: a missing or unreadable gate artifact escalates rather than being assumed green. The slim file's *absence alone* is not the problem: the script falls back to the summary, and that fallback is explicitly not a failure. See the [gate model](./gate-model.md) for how the artifact resolves into a `gate_status` and the full verdict mapping.
|
|
55
58
|
|
|
59
|
+
## Gate re-loops on a sweep-scope or delta cap
|
|
60
|
+
|
|
61
|
+
A per-story gate can return `reloop` with a `PASS` gate status when a cap fired rather than a finding: the `reasons` name either the sweep-scope cap (the `.tests-ran` marker says `scope=scoped`, or the marker/`scope=` line is missing) or the delta-profile cap (`--cycle-profile delta` was declared). Neither is an error; both mean "not yet, and here is why": a story only advances off a full-scope sweep judged by the full gate instrument. The remedy is the cap-only re-loop, which skips the generalize ceremony entirely: re-run the full three-axis sweep, refresh the marker with `scope=full`, and re-run the gate without `--cycle-profile`. See the cap sections in the [gate model](./gate-model.md).
|
|
62
|
+
|
|
56
63
|
## Hooks not firing
|
|
57
64
|
|
|
58
65
|
**Symptom.** A commit lands on a protected branch, or a commit lands before a story's tests ran: the invariants the PreToolUse hook should enforce did not block.
|
|
@@ -67,9 +74,9 @@ Note this is fail-closed on purpose: a missing or unreadable gate artifact escal
|
|
|
67
74
|
|
|
68
75
|
**Symptom.** A story stops re-looping; an escalation marker (`<impl-artifacts>/.escalation-<story>.md`) appears; the run surfaces a budget message.
|
|
69
76
|
|
|
70
|
-
**What happened.**
|
|
77
|
+
**What happened.** Three layers can bound a runaway story. The literal "…or stop after N turns" clause inside a `/goal` condition binds only when you started a `/goal` whose own condition carries it, and then it bounds the session: the conductor cannot start one itself. Otherwise the bound is the gate's re-loop budget: before each re-loop the conductor reads the hook's recorded turn count, and a `reloop` that would exceed `max_turns_per_story` becomes an `escalate` instead. That count advances once per response, so re-loops spent inside one response do not move it, and for `drive_epic.py` spawns the `--session-timeout` wall clock is the backstop. The **Stop** hook (`budget_stop.py`) is the defensive third layer: it counts turns and, on overrun, writes the escalation marker and lets the stop proceed. The marker records the count and does not stop the drive, so the story goes on toward its gate. It becomes an escalation only when the gate escalates the story on that count. A story that passes its gate gets a sizing note in the decision log and the run report instead: no escalation, no ping, and nothing left open.
|
|
71
78
|
|
|
72
|
-
**Its documented limitation.** A Stop hook fires only when Claude is *already* trying to stop: it **cannot interrupt a `/goal` condition mid-turn**. So at this layer the ceiling is advisory; the
|
|
79
|
+
**Its documented limitation.** A Stop hook fires only when Claude is *already* trying to stop: it **cannot interrupt a `/goal` condition mid-turn**. So at this layer the ceiling is advisory; what can stop the story is the conductor's re-loop budget checked against this count, plus the in-condition turn clause when you started a `/goal`. In a single attended or `-H` session with no `/goal` of yours, nothing bounds re-loops spent inside one response; only `drive_epic.py` spawns have a hard backstop, their `--session-timeout` (unless set to `0`). If a story keeps consuming budget, that is the signal to re-scope, split, or hand it off, not to raise the budget and hope.
|
|
73
80
|
|
|
74
81
|
## Resume after an interruption
|
|
75
82
|
|
|
@@ -11,19 +11,19 @@ Three intuitive shortcuts all push an unattended Epic toward false completion, a
|
|
|
11
11
|
|
|
12
12
|
**The evaluator only sees the transcript.** Claude Code's `/goal` mode drives a loop until a success condition is met, then asks an evaluator to confirm. But that evaluator reads the transcript; it cannot open a file on disk. It cannot read TEA's `gate-decision.json`. So if you let the `/goal` condition be the final word on "is this story done," you have asked the model to grade its own homework from its own notes. The model cannot be the judge of its own completion: the thing that decides "done" has to be something it cannot author.
|
|
13
13
|
|
|
14
|
-
**`/rewind` checkpoints miss Bash changes.** The obvious undo for a runaway agent is `/rewind`. But its checkpoints do not capture changes made through Bash, and an autonomous Epic run is mostly Bash: test commands, lint, build, and the git commits themselves. Rolling back to a checkpoint leaves the working tree's Bash-driven mutations in place. The real undo for this kind of run is git: an Epic branch off a protected branch, one commit per green story. See the [gate model](./gate-model.md) and [architecture](./architecture.md) for how this is wired.
|
|
14
|
+
**`/rewind` checkpoints miss Bash changes.** The obvious undo for a runaway agent is `/rewind`. But its checkpoints do not capture changes made through Bash, and an autonomous Epic run is mostly Bash: test commands, lint, build, and the git commits themselves. Rolling back to a checkpoint leaves the working tree's Bash-driven mutations in place. The real undo for this kind of run is git: an Epic branch off a protected branch, one implementation commit per green story plus its gate's evidence commit. See the [gate model](./gate-model.md) and [architecture](./architecture.md) for how this is wired.
|
|
15
15
|
|
|
16
16
|
**Memory is context, not enforcement.** It is tempting to encode the run's invariants ("never commit on `main`", "never commit before tests pass") into Auto Memory or a CLAUDE.md rule and trust the model to honor them. But memory is context the model may or may not weigh; it does not *block* a `git commit`. An invariant that lives only in memory is a suggestion. An invariant that must hold has to live somewhere the model cannot talk its way past.
|
|
17
17
|
|
|
18
18
|
## The thesis: three enforcement layers
|
|
19
19
|
|
|
20
|
-
UltraCode Goal answers each shortcut with a layer the model cannot override.
|
|
20
|
+
UltraCode Goal answers each shortcut with a layer the model cannot override, except where a layer says otherwise.
|
|
21
21
|
|
|
22
22
|
**1. Deterministic gate truth.** Completion is decided by `scripts/gate_eval.py`, which reads TEA's `gate-decision.json` and maps its gate status to a routing verdict: `PASS`/`WAIVED` advance, `CONCERNS` defers, `FAIL` re-loops, `NOT_EVALUATED` escalates. The script never re-derives TEA's thresholds and never consults the transcript; it reads the artifact as given. The model produces evidence; the script reads the verdict. They are different things on purpose. See the [gate model](./gate-model.md).
|
|
23
23
|
|
|
24
24
|
**2. Hooks as invariants.** The invariants that must hold (no commit on a protected branch, no commit before a story's tests have actually run green, and four more covering marker freshness, an empty staged index, un-skipped acceptance tests, and Cross-Session Recall) live in a **PreToolUse** hook, not in memory. The hook inspects each `git commit`/`git push` and denies it when any of them is violated. It is merged into `.claude/settings.local.json` at preflight and asserted active before the run goes unattended. A denied commit is enforcement; a remembered rule is not. See [architecture](./architecture.md).
|
|
25
25
|
|
|
26
|
-
**3. Budget enforcement.**
|
|
26
|
+
**3. Budget enforcement.** This is the one layer that rests on the conductor following a rule. A **Stop** hook tracks turns against `max_turns_per_story` and writes an escalation marker when it is breached, but it never blocks, and it counts once per response, so re-loops inside one response do not move it. The conductor reads that count before each story and each re-loop, and the gate's re-loop budget turns a `reloop` that would exceed it into an `escalate`. A story that passes its gate after an overrun is not escalated: the gate decides completion, and the overrun is logged as a sizing note. A `/goal` condition's literal "…or stop after N turns" clause binds only when an operator starts a `/goal` (the conductor cannot start one itself), and for `drive_epic.py` spawns a `--session-timeout` wall clock is the backstop. See [how it works](./how-it-works.md).
|
|
27
27
|
|
|
28
28
|
These three are the module's non-negotiables. They exist because the documented mechanics make the intuitive shortcut wrong, so the skill does not optimize them away.
|
|
29
29
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://json.schemastore.org/package.json",
|
|
3
3
|
"name": "bmad-module-ultracode-goal",
|
|
4
|
-
"version": "2.
|
|
4
|
+
"version": "2.3.0",
|
|
5
5
|
"description": "BMAD module — Run a BMAD Epic autonomously to a machine-checked, TEA-gated Definition-of-Done.",
|
|
6
6
|
"keywords": [
|
|
7
7
|
"bmad",
|
|
@@ -39,15 +39,19 @@
|
|
|
39
39
|
"format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,yaml}\"",
|
|
40
40
|
"lint": "eslint . --ext .js,.cjs,.mjs,.yaml --max-warnings=0",
|
|
41
41
|
"lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
|
|
42
|
+
"lint:instructions": "uvx lintlang@0.8.1 scan skills --exclude \"**/scripts/tests/fixtures/**\" --fail-on fail",
|
|
42
43
|
"lint:md": "markdownlint-cli2 \"**/*.md\"",
|
|
43
44
|
"prepare": "husky || exit 0",
|
|
44
|
-
"
|
|
45
|
+
"postprepare": "node tools/link-reference-skills.js --quiet || exit 0",
|
|
46
|
+
"quality": "run-p --print-label --aggregate-output format:check lint lint:md lint:instructions test:install test:cli test:python test:rehype test:docs-links-tool test:skill-links validate:skills validate:refs validate:fixtures validate:docs-links",
|
|
47
|
+
"skills:link": "node tools/link-reference-skills.js",
|
|
45
48
|
"test": "npm run quality",
|
|
46
49
|
"test:cli": "node test/test-cli-integration.js",
|
|
47
50
|
"test:docs-links-tool": "node test/test-validate-docs-links.js",
|
|
48
51
|
"test:install": "node test/test-installation-components.js",
|
|
49
52
|
"test:python": "uv run --with pytest==9.1.1 --with pytest-xdist==3.8.0 pytest skills/ultracode-goal/scripts/tests/ -n auto",
|
|
50
53
|
"test:rehype": "node test/test-rehype-markdown-links.js",
|
|
54
|
+
"test:skill-links": "node test/test-link-reference-skills.js",
|
|
51
55
|
"ucg:install": "node tools/cli/ucg-cli.js install",
|
|
52
56
|
"ucg:status": "node tools/cli/ucg-cli.js status",
|
|
53
57
|
"ucg:uninstall": "node tools/cli/ucg-cli.js uninstall",
|
|
@@ -134,10 +134,17 @@ own unreadable content).
|
|
|
134
134
|
reflects the fixes — the remediate-then-re-run loop. The verdict mapping in step 4
|
|
135
135
|
reads the post-remediation kernel verdict.
|
|
136
136
|
|
|
137
|
-
**Remediation halt catch-all.** If a remediation sub-skill itself fails
|
|
138
|
-
|
|
139
|
-
sub-skill and the exact input it needed,
|
|
140
|
-
|
|
137
|
+
**Remediation halt catch-all.** If a remediation sub-skill itself fails, is not installed
|
|
138
|
+
(the Skill tool does not know its name), or blocks on interactive input, do not re-invoke
|
|
139
|
+
it blind: record a non-remediable gap naming the sub-skill and the exact input it needed,
|
|
140
|
+
and let the verdict mapping route the run to `status=blocked`. A `bmad-create-story` that
|
|
141
|
+
is not installed is the likely case (BMAD Method 6.12 or later ships it as a deprecated
|
|
142
|
+
shim a fresh install leaves out unless asked for): name the operator's fix, run from the
|
|
143
|
+
project root and pinned to the installed version (`installation.version` in
|
|
144
|
+
`_bmad/_config/manifest.yaml`) so it does not also upgrade BMAD:
|
|
145
|
+
`npx bmad-method@<version> install --directory . --shims --yes`. Never substitute another
|
|
146
|
+
skill (`bmad-build`, `bmad-build-auto`) or write the story file or its acceptance criteria
|
|
147
|
+
by hand. Likewise cap the loop at one pass per gap: if a kernel re-run still
|
|
141
148
|
reports a gap whose `kind`+`source` a prior pass already remediated, the fix did not take —
|
|
142
149
|
record it as a non-remediable blocker and route to `status=blocked` rather than re-entering
|
|
143
150
|
step 2, so the remediate-then-re-run loop always converges instead of spinning silently.
|
|
@@ -197,11 +197,11 @@ The two dispositions are genuinely different things, not two names for one:
|
|
|
197
197
|
**Closing a `budget-overrun` escalation also resets that story's turn counter** — delete
|
|
198
198
|
`{workflow.implementation_artifacts}/.budget-<story_id>.json`, or set its `turns` to `0`.
|
|
199
199
|
The Stop hook's counter is persistent and monotonic
|
|
200
|
-
(`{ucg-root}/scripts/hooks/budget_stop.py` increments it every Stop event and
|
|
201
|
-
once it reaches the ceiling), and no ordinary resume clears it — the Stage 2 arming purge
|
|
200
|
+
(`{ucg-root}/scripts/hooks/budget_stop.py` increments it every Stop event and marks
|
|
201
|
+
the story once it reaches the ceiling), and no ordinary resume clears it — the Stage 2 arming purge
|
|
202
202
|
(`{ucg-root}/references/preflight.md`, step 5) deliberately skips it on re-entry so a story cannot evade its ceiling by stopping and
|
|
203
|
-
resuming. Leave it standing here and the resumed story escalates again
|
|
204
|
-
|
|
203
|
+
resuming. Leave it standing here and the resumed story escalates again at the resume's
|
|
204
|
+
step-0 ceiling check, before it has done a single turn of the work the operator just authorized, and
|
|
205
205
|
the close would apply in name only. Answering a budget overrun by re-scoping, splitting,
|
|
206
206
|
or handing off the story *is* the operator granting it a fresh budget, so the counter that
|
|
207
207
|
recorded the exhausted one has no claim on the resumed run.
|
|
@@ -146,26 +146,39 @@ Three things are worth saying out loud alongside it:
|
|
|
146
146
|
**Escalations render from the typed sidecar where one exists.** Where no readable one does,
|
|
147
147
|
the block carries one of two lines, and they mean different things:
|
|
148
148
|
|
|
149
|
-
- `escalation (unpromoted:
|
|
150
|
-
hook's raw marker is on disk
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
149
|
+
- `escalation (unpromoted: no gate verdict yet, or the session ended before Execute
|
|
150
|
+
promoted it)`: only the Stop hook's raw marker is on disk, for a story that has not
|
|
151
|
+
advanced. Execute promotes that marker only when the story's gate escalates it on its
|
|
152
|
+
turn count, so while the gate has not ruled this is the expected state; otherwise it
|
|
153
|
+
is the residual of a session that died before Execute promoted it, and the only
|
|
154
|
+
evidence that the escalation happened at all. Report it as an escalation that may be
|
|
155
|
+
pending (the gate may not have ruled yet) whose typed record is not written yet, and
|
|
156
|
+
leave the marker alone.
|
|
154
157
|
- `escalation (typed record present but unreadable)` - the `escalation-<story>.json` named
|
|
155
158
|
on the `- source:` line was written and then would not parse, which is the half-written
|
|
156
159
|
file a session killed mid-write leaves. "Never promoted" would be the opposite of what
|
|
157
160
|
happened: report it as a typed record that needs repair, because `/ucg-resolve` reads
|
|
158
161
|
that same file to reconstruct the pending decision and cannot parse it either.
|
|
159
162
|
|
|
163
|
+
A raw marker for a story the gate advanced is not an escalation at all: the gate decided
|
|
164
|
+
completion and the overrun is a sizing note in the decision log. A story counts as
|
|
165
|
+
advanced when its heartbeat entry's verdict is `advance` or `defer`, or when its
|
|
166
|
+
`sprint-status.yaml` row reads `done` (a later invocation's heartbeat no longer lists
|
|
167
|
+
it). It renders under stories as `turn ceiling reached; the story advanced at its gate,
|
|
168
|
+
so this is a sizing note and nothing is pending`, on that story's row, or on a line of
|
|
169
|
+
its own when the heartbeat no longer lists it, and not under escalations.
|
|
170
|
+
|
|
160
171
|
A marker and an unreadable sidecar can both be on disk for one story, and the marker wins
|
|
161
172
|
the render, so an `unpromoted` block is worth one directory check before you report the
|
|
162
173
|
typed record as never written.
|
|
163
174
|
|
|
164
175
|
## Optional diff-viewer affordance
|
|
165
176
|
|
|
166
|
-
When `hunk` is on PATH, each story that recorded a baseline commit gains
|
|
167
|
-
|
|
168
|
-
|
|
177
|
+
When `hunk` is on PATH, each story that recorded a baseline commit gains copy-paste
|
|
178
|
+
`hunk show <commit>` lines, so a reader can go straight from a story row to its diff:
|
|
179
|
+
one line per commit in the story's range (its implementation commit and the gate's
|
|
180
|
+
evidence commit) when the repository is readable, else one line for the story's
|
|
181
|
+
recorded end commit, or for its baseline when no end commit was recorded. When it is not on PATH, nothing about it is rendered and the render is otherwise
|
|
169
182
|
unchanged.
|
|
170
183
|
|
|
171
184
|
It is an affordance, never a dependency, and it is confined to stdout. The probe's result
|
|
@@ -9,7 +9,7 @@ description: Runs a BMAD Epic autonomously to a machine-checked Definition-of-Do
|
|
|
9
9
|
|
|
10
10
|
This skill autonomously delivers a BMAD Epic to a **machine-checked** Definition-of-Done. Act as an autonomous delivery conductor — a staff engineer who also owns the release gate. It preflights the Epic to a hard, *remediated* green light, turns acceptance criteria into executable tests with the Test Architect (TEA), drives the stories to completion, and advances only when TEA's deterministic quality gate reads PASS — capturing what it learns to Auto Memory so the next run is sharper. Your output is a delivered, gate-passed Epic, a run report, and a deferred-work ledger of anything safely parked for later.
|
|
11
11
|
|
|
12
|
-
Module `bmad-module-ultracode-goal`. It orchestrates the installed BMAD epic toolbox (`bmad-sprint-planning`, `bmad-create-story`, `bmad-dev-story`, `bmad-code-review`, `bmad-correct-course`, `bmad-retrospective`) and the TEA gates (`bmad-testarch-framework`, `-ci`, `-test-design`, `-atdd`, `-automate`, `-test-review`, `-nfr`, `-trace`). It composes Claude Code primitives
|
|
12
|
+
Module `bmad-module-ultracode-goal`. It orchestrates the installed BMAD epic toolbox (`bmad-sprint-planning`, `bmad-create-story`, `bmad-dev-story`, `bmad-code-review`, `bmad-correct-course`, `bmad-retrospective`) and the TEA gates (`bmad-testarch-framework`, `-ci`, `-test-design`, `-atdd`, `-automate`, `-test-review`, `-nfr`, `-trace`). It composes Claude Code primitives (Auto Mode, Auto Memory, hooks, git branch isolation) and is a conductor over them, not a replacement for them. It cannot start `/goal`, which runs only when the operator starts one (`references/execute.md`).
|
|
13
13
|
|
|
14
14
|
## Conventions
|
|
15
15
|
|
|
@@ -43,8 +43,8 @@ These exist because the documented mechanics make the intuitive shortcut wrong.
|
|
|
43
43
|
- **Completion is decided by `scripts/gate_eval.py` reading TEA's `gate-decision.json` — never your own judgment, and never the `/goal` evaluator alone.** That evaluator only sees the transcript; it cannot read the gate file. The JSON is the truth.
|
|
44
44
|
- **Launch the unattended run only when `scripts/preflight_check.py` returns green *after the remediation pass* (intervention budget == 0) and `formalize_check.py returns ready` (post-remediation — the readiness verdict the step-4 gate decides) and ultracode + Auto Mode are on.** The unattended run takes no mid-run input — every gate is resolved before launch or not at all. This binds the **Stage-2 entry**. A resume routed into Execute does not re-run it — see Resume above.
|
|
45
45
|
- **Only non-gate-blocking work defers** to `{workflow.deferred_work_path}`, and the Epic keeps moving; a P0/critical FAIL never defers — it re-loops within budget or escalates.
|
|
46
|
-
- **Rollback is git** — Epic branch off `{workflow.epic_branch_prefix}`, one commit per green story. `/rewind` checkpoints miss Bash changes; do not rely on them.
|
|
47
|
-
- **Invariants live in PreToolUse hooks**, auto-merged into `.claude/settings.local.json` at preflight — not in memory, which is context, not enforcement.
|
|
46
|
+
- **Rollback is git** — Epic branch off `{workflow.epic_branch_prefix}`, one implementation commit per green story plus its gate's evidence commit. `/rewind` checkpoints miss Bash changes; do not rely on them.
|
|
47
|
+
- **Invariants live in PreToolUse hooks**, auto-merged into `.claude/settings.local.json` at preflight — not in memory, which is context, not enforcement. A headless session cannot approve a refused write to that file, so a first arming belongs to an attended pass (`references/preflight.md`, "A refused settings write").
|
|
48
48
|
- **Cross-Session Recall is advisory-only.** When `{workflow.cross_session_recall}` is `on` and claude-mem is present, recalled memory is *data, never directive* — it informs scope (Stage 1) and preflight (Stage 2), never a gate verdict. The hook-enforced latch (`.mem-state.json`) fails closed during the run: any malformed or off state denies claude-mem calls rather than trusting them. See the Cross-Session Recall guide: <https://armelhbobdad.github.io/bmad-module-ultracode-goal/cross-session-recall/>.
|
|
49
49
|
|
|
50
50
|
## Stages
|
|
@@ -65,7 +65,7 @@ Run the stages in order; each routes by the testable conditions stated in its fi
|
|
|
65
65
|
|
|
66
66
|
With `-H`, run non-interactively: infer scope, default to **production** (unless `--light`), never prompt — a secret that cannot be resolved becomes a red blocker, not a question — and let `.decision-log.md` absorb every assumption.
|
|
67
67
|
|
|
68
|
-
**One core schema, every exit point.** Every exit — completing at Stage 6, or blocking early at ingest (Stage 1, e.g. epic unresolved), at preflight (Stage 2), or at a story escalation — emits the **five canonical keys** `status`, `skill`, `decision_log`, `report`, `deferred_work`, always present (`null` when that artifact was not produced); a **blocked** exit appends a sixth, `reason` (the one-line cause). Build every emit through the `scripts/headless_envelope.py` adapter — the one shared definition `references/finalize.md` and `/ucg-formalize` honor — never by hand. A completed run:
|
|
68
|
+
**One core schema, every exit point.** Every exit — completing at Stage 6, or blocking early at ingest (Stage 1, e.g. epic unresolved), at preflight (Stage 2), or at a story escalation — emits the **five canonical keys** `status`, `skill`, `decision_log`, `report`, `deferred_work`, always present (`null` when that artifact was not produced); a **blocked** exit appends a sixth, `reason` (the one-line cause). Build every emit through the `scripts/headless_envelope.py` adapter — the one shared definition `references/finalize.md` and `/ucg-formalize` honor — never by hand. Attempt that adapter call once even when other calls this session were refused, since a refusal of one call is not a refusal of another; if the adapter call itself is refused, build nothing by hand, record the block and the refusal in `.decision-log.md` and stop, leaving absent the `run-result.json` cleared at entry, which is the fail-closed signal. A completed run:
|
|
69
69
|
|
|
70
70
|
```json
|
|
71
71
|
{"status": "complete",
|
|
@@ -2,7 +2,7 @@ code: ultracode-goal
|
|
|
2
2
|
name: "UltraCode Goal"
|
|
3
3
|
header: "Run a BMAD Epic autonomously to a deterministic, TEA-gated Definition-of-Done"
|
|
4
4
|
subheader: "Preflight to a remediated green light, define done as executable tests, advance only on a machine-checked gate verdict"
|
|
5
|
-
description: "Orchestrates the BMAD epic toolbox + TEA quality gates + Claude Code primitives (
|
|
5
|
+
description: "Orchestrates the BMAD epic toolbox + TEA quality gates + Claude Code primitives (Auto Mode, Auto Memory, hooks, git branch isolation) to deliver an Epic unattended. Completion is decided by a deterministic gate_eval.py reading TEA's gate-decision.json — never the model's own judgment."
|
|
6
6
|
default_selected: false
|
|
7
7
|
|
|
8
8
|
# LLM-readable module documentation. The installer registers this as the
|
|
@@ -36,7 +36,7 @@ parallel_max_concurrency = 8
|
|
|
36
36
|
# per-story baseline SHA with `git rev-parse HEAD` before any implementation, and the evidence
|
|
37
37
|
# trail bounds a story's commit range from it. Omitting them makes an unattended run stop for a
|
|
38
38
|
# permission prompt exactly where walk-away autonomy is claimed.
|
|
39
|
-
allowlist_commands = ["git status", "git add", "git commit", "git rev-parse", "git diff", "npm test", "npm run lint", "npm run build", "pytest", "uv run"]
|
|
39
|
+
allowlist_commands = ["git status", "git add", "git commit", "git rev-parse", "git diff", "npm test", "npm run lint", "npm run build", "pytest", "uv run", "date"]
|
|
40
40
|
|
|
41
41
|
# --- Hook fired at epic completion (prompt or shell command); empty = none ---
|
|
42
42
|
on_epic_complete = ""
|
|
@@ -14,7 +14,7 @@ Run `bmad-testarch-test-design` in **Epic-Level Mode** for the Epic. This is the
|
|
|
14
14
|
|
|
15
15
|
Epic-Level Mode is selected by the presence of `sprint-status.yaml` (preflight reports `sprint_status_present`); if test-design prompts for system-vs-epic, choose **epic**. Force **Create** mode if it offers Resume/Validate/Edit — those are interactive and stall an unattended run.
|
|
16
16
|
|
|
17
|
-
**Test-design runs on any stack — do not skip it on a non-web module.** The framework fitness caveat in `references/preflight.md` is scoped to TEA's *browser generators*: ATDD in this stage,
|
|
17
|
+
**Test-design runs on any stack — do not skip it on a non-web module.** The framework fitness caveat in `references/preflight.md` is scoped to TEA's *browser generators*: ATDD in this stage, which on TEA 1.27.2 emits only Playwright/TypeScript scaffolds. Test-design is not one of them — it is risk-and-priority analysis over the planning corpus, and its output is a document, not a browser harness — and neither is trace, which runs on any stack too. So a `pytest` or `npm-test` module gets the same risk matrix and priorities a web module does. Reading the caveat as "the whole TEA chain is web-only" is what produces an empty test-design directory and leaves the ACs with no risk backbone to sharpen against; when ATDD's generator genuinely cannot serve the stack, the substitution is the hand-established red phase in gate.md's non-web section, and hand-authored trace artifacts only where trace itself cannot run; never a skipped test-design.
|
|
18
18
|
|
|
19
19
|
A `CONCERNS`-grade gap in the test plan (e.g. an `UNKNOWN` NFR threshold that does not block any P0 story) appends to `{workflow.deferred_work_path}` and the Epic keeps moving. A genuine red gap — no risk coverage for a P0 flow — is not deferrable; resolve it before proceeding to per-story work.
|
|
20
20
|
|
|
@@ -34,6 +34,8 @@ For every **in-scope** story, in sprint order:
|
|
|
34
34
|
|
|
35
35
|
**In `--light`:** run step 1 (`bmad-create-story`) but **skip step 2 (`bmad-testarch-atdd`)** — `--light` produces no executable red-phase acceptance tests. The story file and its acceptance criteria become the Definition-of-Done and the oracle `bmad-testarch-trace` resolves the Stage 5 gate against, mirroring gate.md's `--light` branch (which runs only `bmad-testarch-trace`). The per-Epic test-design above still runs in `--light`: `bmad-testarch-trace` consumes its risk scores and P0–P3 priorities when they are available, and they are the backbone you sharpen the ACs against in either profile. Sharpen the ACs here exactly as you would for production — under `--light` they are the *only* machine-checkable DoD a story gets, so vague ACs leave the trace gate nothing to resolve against.
|
|
36
36
|
|
|
37
|
+
**A delegated skill that is not installed.** If a skill this stage delegates to is not installed (the Skill tool does not know its name; for example `bmad-create-story`, a deprecated shim on BMAD Method 6.12 or later, which a fresh install leaves out unless asked for with `--shims` or Yes at the installer's shim prompt, and an update removes when told not to keep it), do not substitute another skill (`bmad-build`, `bmad-build-auto`) and do not write the story file or its tests by hand: Stage 4 and the gate read the artifacts these skills produce, and a stand-in reaches them looking like the real thing. Escalate as Execute's sub-skill halt catch-all does (`references/execute.md`: write the typed escalation sidecar, then stop), for the story concerned or, when the per-Epic test-design is the missing skill, for the Epic's first in-scope story. Name the cause in `decision_needed`: Stage 2's `bmad_skills` blocker refuses a launch without `bmad-create-story`, so a missing `bmad-create-story` here means the install changed after preflight ran, while preflight does not probe the `bmad-testarch-*` skills, so a missing TEA skill means TEA is not installed for this project.
|
|
38
|
+
|
|
37
39
|
## Exit condition (testable)
|
|
38
40
|
|
|
39
41
|
Stage 3 is complete, and Stage 4 may begin, when **all three** hold:
|