bmad-module-ultracode-goal 2.0.0 → 2.2.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 +1 -1
- package/README.md +5 -5
- package/docs/404.md +1 -1
- package/docs/_internal/STABILITY.md +13 -9
- package/docs/architecture.md +17 -12
- package/docs/comparison.md +19 -11
- package/docs/gate-model.md +24 -0
- package/docs/getting-started.md +1 -1
- package/docs/how-it-works.md +3 -3
- package/docs/index.md +0 -1
- package/docs/operating-tips.md +4 -2
- package/docs/troubleshooting.md +9 -5
- package/docs/why-ultracode-goal.md +1 -1
- package/package.json +5 -4
- package/skills/ucg-formalize/SKILL.md +136 -39
- package/skills/ucg-resolve/SKILL.md +86 -58
- package/skills/ucg-status/SKILL.md +64 -30
- package/skills/ultracode-goal/SKILL.md +9 -11
- package/skills/ultracode-goal/assets/module-help.csv +1 -1
- package/skills/ultracode-goal/assets/module.yaml +8 -3
- package/skills/ultracode-goal/assets/ucg-awareness/bmad-testarch-test-design.toml +8 -0
- package/skills/ultracode-goal/customize.toml +12 -7
- package/skills/ultracode-goal/references/define-done.md +3 -3
- package/skills/ultracode-goal/references/execute.md +40 -53
- package/skills/ultracode-goal/references/finalize.md +12 -12
- package/skills/ultracode-goal/references/gate.md +42 -11
- package/skills/ultracode-goal/references/health-check.md +7 -4
- package/skills/ultracode-goal/references/ingest-and-scope.md +4 -4
- package/skills/ultracode-goal/references/preflight.md +10 -9
- package/skills/ultracode-goal/scripts/gate_eval.py +684 -39
- package/skills/ultracode-goal/scripts/gate_trail.py +131 -32
- package/skills/ultracode-goal/scripts/health_check_fp.py +98 -3
- package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +56 -14
- package/skills/ultracode-goal/scripts/mem_observation.py +48 -10
- package/skills/ultracode-goal/scripts/mutate_check.py +353 -0
- package/skills/ultracode-goal/scripts/preflight_check.py +397 -3
- package/skills/ultracode-goal/scripts/status_render.py +20 -2
- package/skills/ultracode-goal/scripts/story_sizing.py +193 -0
- package/tools/build-docs.js +24 -1
- package/tools/validate-docs-links.js +169 -8
- package/website/astro.config.mjs +0 -1
- package/docs/parallel-mode.md +0 -68
- package/skills/ultracode-goal/assets/execute-epic.workflow.js +0 -249
|
@@ -31,6 +31,11 @@ one move: run the renderer and show what came back.
|
|
|
31
31
|
- `{workflow.implementation_artifacts}` and `{workflow.deferred_work_path}` resolve from
|
|
32
32
|
the parent module's `customize.toml` workflow block (the same scalars the autonomous
|
|
33
33
|
run reads).
|
|
34
|
+
- Of the `[workflow]` block's three universal defaults, this skill loads
|
|
35
|
+
`{workflow.persistent_facts}` (read-only context, and this skill runs cold) and executes
|
|
36
|
+
**neither** `{workflow.activation_steps_prepend}` nor `{workflow.activation_steps_append}`.
|
|
37
|
+
Those are operator-configured actions, and running one here would break the promise
|
|
38
|
+
below. `ucg-formalize` and `ucg-resolve` state the same split.
|
|
34
39
|
- This skill writes nothing, including no decision-log entry. A status read is not an
|
|
35
40
|
event in the run's history, and recording every glance at a run would bury the
|
|
36
41
|
decisions the log exists to carry.
|
|
@@ -61,11 +66,26 @@ independent in the parent `customize.toml`, and the renderer defaults the ledger
|
|
|
61
66
|
`deferred-work.md` *inside* `--impl-artifacts` when the flag is absent — so omitting it on
|
|
62
67
|
a project that moved the ledger renders `n/a`, or a different checkout's ledger, while
|
|
63
68
|
looking exactly like a clean read. Pass it and the render reads the same ledger the gate writes,
|
|
64
|
-
the same way `references/finalize.md` threads that scalar to `mem_observation.py`.
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
+
the same way `{ucg-root}/references/finalize.md` threads that scalar to `mem_observation.py`.
|
|
70
|
+
|
|
71
|
+
`--run-dir <the run folder>` is what makes the decision-log tail render at all, so the
|
|
72
|
+
invocation above - which omits it - always renders that row `n/a`. Do not ship that as the
|
|
73
|
+
normal answer:
|
|
74
|
+
|
|
75
|
+
- **When the operator named a run**, pass it. The runs index in the render lists the
|
|
76
|
+
folders available to name.
|
|
77
|
+
- **When the operator named none**, resolve it: pass the run folder whose Epic matches the
|
|
78
|
+
heartbeat's `epic` row, so the default read carries the log of the run it is describing.
|
|
79
|
+
If no folder matches, or more than one does, leave the flag off **and say the tail is
|
|
80
|
+
unscoped** - otherwise `n/a` reads as "this run has an empty log" when it means "nobody
|
|
81
|
+
told the renderer which log to read".
|
|
82
|
+
|
|
83
|
+
The two halves can disagree, and the render does not say so. The heartbeat is a single
|
|
84
|
+
project-level file that whichever run ran last overwrote, while run folders are per-Epic
|
|
85
|
+
siblings; naming a run other than the one the heartbeat describes yields a header, stories,
|
|
86
|
+
escalations and ledger belonging to the **latest** run above a decision-log tail belonging
|
|
87
|
+
to the **named** one. When they differ, say which is which above the render, because
|
|
88
|
+
nothing in the render itself distinguishes them.
|
|
69
89
|
|
|
70
90
|
Pass `--runs-root <dir>` when the operator named a different runs root - runs kept under
|
|
71
91
|
a non-default output root, or another checkout's runs read from here. The invocation
|
|
@@ -75,9 +95,13 @@ flag is where an operator whose runs live elsewhere says so. Only the runs index
|
|
|
75
95
|
`--impl-artifacts` is required and the renderer refuses to run without it (exit 2, nothing
|
|
76
96
|
rendered). Every **source** it reads is optional: an absent, empty or unparseable file
|
|
77
97
|
renders `n/a` and the render continues. That split is deliberate and matches the rest of
|
|
78
|
-
the module
|
|
79
|
-
|
|
80
|
-
|
|
98
|
+
the module; `status_render.py` carries the reasoning behind it.
|
|
99
|
+
|
|
100
|
+
Pass `--impl-artifacts <dir>` yourself when the operator names an **isolated-track** run,
|
|
101
|
+
taking the dir that run recorded in its `.decision-log.md`
|
|
102
|
+
(`{ucg-root}/references/ingest-and-scope.md`, the cross-file/colliding-epic rule). The
|
|
103
|
+
configured scalar is the shared track's: rooted there, the render reads the shared track's
|
|
104
|
+
heartbeat, escalations and baselines and presents them as the answer about a different run.
|
|
81
105
|
|
|
82
106
|
## 2. Show what came back
|
|
83
107
|
|
|
@@ -85,16 +109,22 @@ Print the render. Do not re-derive, re-order, or re-judge any row: the renderer
|
|
|
85
109
|
files, and a second opinion formed here would be a second, later reading of artifacts that
|
|
86
110
|
may have moved on since.
|
|
87
111
|
|
|
88
|
-
|
|
112
|
+
Three things are worth saying out loud alongside it:
|
|
89
113
|
|
|
90
114
|
- **The `[machine-derived]` suffix is exclusive.** Only two rendered fields carry it: the
|
|
91
115
|
gate's own reason strings, copied across unedited from the gate result the spine last
|
|
92
|
-
read, and the turn counter the Stop hook maintains. Every other row is
|
|
93
|
-
|
|
94
|
-
|
|
116
|
+
read, and the turn counter the Stop hook maintains. Every other row is copied from an
|
|
117
|
+
artifact a model wrote - except the runs index's `live` / `terminal` word, which the
|
|
118
|
+
renderer derives from the files on disk, not from anything a model maintained.
|
|
95
119
|
- **`no run:` means no heartbeat file, not a broken read.** The runs index still renders
|
|
96
120
|
below it, so a reader who is simply pointed at the wrong artifacts directory can see
|
|
97
121
|
which runs do exist.
|
|
122
|
+
- **`live` means no run report is on disk yet, not that a process is attached.** A run
|
|
123
|
+
whose session died mid-flight renders `live` for good. The one recency signal is the
|
|
124
|
+
heartbeat's `Updated` row, and it belongs to the run that wrote the heartbeat rather
|
|
125
|
+
than to every row of the index - so when the operator asked whether a run is still
|
|
126
|
+
going, quote that timestamp (with `Phase`) alongside the index row instead of reading
|
|
127
|
+
`live` as the answer.
|
|
98
128
|
|
|
99
129
|
## What the render carries
|
|
100
130
|
|
|
@@ -104,18 +134,32 @@ Two things are worth saying out loud alongside it:
|
|
|
104
134
|
| last verdict | the gate's most recent verdict word |
|
|
105
135
|
| last reason(s) | the gate's reason strings, verbatim `[machine-derived]` |
|
|
106
136
|
| budget used | turns spent against the per-story ceiling `[machine-derived]` |
|
|
137
|
+
| re-loops this run | how many times this run re-entered a story, from the heartbeat |
|
|
138
|
+
| profile | the profile the run is on, from the heartbeat |
|
|
139
|
+
| updated | when the heartbeat was last written: this with `phase` is how a reader judges liveness |
|
|
107
140
|
| stories | one row per in-scope story: phase, verdict, attempts, re-loops |
|
|
108
141
|
| escalations | one block per escalation on disk (see below) |
|
|
109
142
|
| deferred work | every row of the ledger, across every run it has accumulated |
|
|
110
|
-
| decision log tail | the run's own account of itself, last lines |
|
|
143
|
+
| decision log tail | the run's own account of itself, last lines - only when `--run-dir` was passed (§1) |
|
|
111
144
|
| runs index | every known run folder, `terminal` once it holds a run report, else `live` |
|
|
112
145
|
|
|
113
|
-
**Escalations render from the typed sidecar where one exists.** Where
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
146
|
+
**Escalations render from the typed sidecar where one exists.** Where no readable one does,
|
|
147
|
+
the block carries one of two lines, and they mean different things:
|
|
148
|
+
|
|
149
|
+
- `escalation (unpromoted: session ended before Execute promoted it)` - only the Stop
|
|
150
|
+
hook's raw marker is on disk. That is not an error state to clean up: it is the residual
|
|
151
|
+
of a session that died between the hook writing the marker and Execute promoting it, and
|
|
152
|
+
it is the only evidence that escalation happened at all. Report it as a pending
|
|
153
|
+
escalation whose typed record was never written, and leave the marker alone.
|
|
154
|
+
- `escalation (typed record present but unreadable)` - the `escalation-<story>.json` named
|
|
155
|
+
on the `- source:` line was written and then would not parse, which is the half-written
|
|
156
|
+
file a session killed mid-write leaves. "Never promoted" would be the opposite of what
|
|
157
|
+
happened: report it as a typed record that needs repair, because `/ucg-resolve` reads
|
|
158
|
+
that same file to reconstruct the pending decision and cannot parse it either.
|
|
159
|
+
|
|
160
|
+
A marker and an unreadable sidecar can both be on disk for one story, and the marker wins
|
|
161
|
+
the render, so an `unpromoted` block is worth one directory check before you report the
|
|
162
|
+
typed record as never written.
|
|
119
163
|
|
|
120
164
|
## Optional diff-viewer affordance
|
|
121
165
|
|
|
@@ -126,14 +170,4 @@ unchanged.
|
|
|
126
170
|
|
|
127
171
|
It is an affordance, never a dependency, and it is confined to stdout. The probe's result
|
|
128
172
|
never reaches an artifact: the run's gate artifacts and its headless envelope are
|
|
129
|
-
byte-identical whether or not the viewer is installed.
|
|
130
|
-
depended on which tools the reader happened to have installed would no longer be
|
|
131
|
-
reproducible from the run itself.
|
|
132
|
-
|
|
133
|
-
## Scope
|
|
134
|
-
|
|
135
|
-
This targets the **sequential spine only**. Under the experimental `--parallel` fan-out
|
|
136
|
-
each worktree agent sees its own copy of the implementation-artifacts directory and writes
|
|
137
|
-
no shared heartbeat, so there is no single snapshot for this to read. The watch surface for
|
|
138
|
-
a fan-out run is the workflow progress view and its run log, as the launch briefing says.
|
|
139
|
-
Do not imply this render covers a fan-out run.
|
|
173
|
+
byte-identical whether or not the viewer is installed.
|
|
@@ -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-
|
|
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 — `/goal`, Auto Mode, Auto Memory, hooks, git branch isolation — it is a conductor over them, not a replacement for them.
|
|
13
13
|
|
|
14
14
|
## Conventions
|
|
15
15
|
|
|
@@ -28,22 +28,22 @@ If it fails, resolve the `workflow` block yourself by reading these three files
|
|
|
28
28
|
|
|
29
29
|
Load config from `{project-root}/_bmad/config.yaml` and `config.user.yaml` (root + `bmm` section for `{planning_artifacts}`); fall back to `{project-root}/_bmad/bmm/config.yaml`. If config is missing — or the user passed `setup`, `configure`, or `register` — offer the module's one-time self-registration (`assets/module-setup.md`), or continue with defaults. Load `{workflow.persistent_facts}` and greet in `{communication_language}`. Run any `{workflow.activation_steps_prepend}` entries in order at the start of activation, and any `{workflow.activation_steps_append}` entries after the greet and before Stage 1 — both default to empty (a stock run is unaffected; a populated override executes in order).
|
|
30
30
|
|
|
31
|
-
**Run modes.** Profile defaults to **production** (full TEA gates); `--light` runs the trace gate only. Execution
|
|
31
|
+
**Run modes.** Profile defaults to **production** (full TEA gates); `--light` runs the trace gate only. Execution is the **sequential** `/goal` spine. (`--parallel` is retired but still accepted: log one `.decision-log.md` line that it was accepted and ignored, and run the spine — `references/execute.md`.) `-H` is headless. `--yes` skips Stage 1's open-floor invite and the launch confirm (the launch briefing still prints) — it **never** skips the hard preflight gate. `--retro` runs the close-out retrospective: interactive runs offer it at Epic close anyway, but headless runs it only when `--retro` was passed. `--max-stories N` bounds how much work this **invocation** takes on (below).
|
|
32
32
|
|
|
33
|
-
**Work bound (`--max-stories N`).** Drive at most N in-scope stories in this **invocation**, then finish normally through Stage 6. It bounds *work*, not scope: the Epic's in-scope set is untouched (headless in-scope is still every not-`done` story, per `references/ingest-and-scope.md` rule 3), so the invocation stops early and the resume routing below picks the rest up next time. It emits the ordinary five-key envelope with `status` `complete` — **there is no third status value** — so read `complete` as "this invocation finished its work without blocking", never as "the Epic is done"; a caller that needs to know whether stories remain re-reads sprint-status. Applied at the story boundary only, never mid-story.
|
|
33
|
+
**Work bound (`--max-stories N`).** Drive at most N in-scope stories in this **invocation**, then finish normally through Stage 6. It bounds *work*, not scope: the Epic's in-scope set is untouched (headless in-scope is still every not-`done` story, per `references/ingest-and-scope.md` rule 3), so the invocation stops early and the resume routing below picks the rest up next time. It emits the ordinary five-key envelope with `status` `complete` — **there is no third status value** — so read `complete` as "this invocation finished its work without blocking", never as "the Epic is done"; a caller that needs to know whether stories remain re-reads sprint-status. Applied at the story boundary only, never mid-story. `references/execute.md` carries the rest — the intended caller (`scripts/drive_epic.py`, one `claude -p` per story), and why a flag that narrowed in-scope instead would make a half-driven Epic indistinguishable from a finished one.
|
|
34
34
|
|
|
35
35
|
**Quick launch** (swap in your Epic id): `ultracode goal epic-7` — attended, production, sequential. `ultracode goal epic-7 --light --yes` — the expert one-liner: trace-only gate, no conversational stops. Add `-H` for headless, `--retro` for the close-out retrospective, `--max-stories 1` to take a single story this invocation.
|
|
36
36
|
|
|
37
|
-
**Resume.** The workspace is this skill's run folder holding `.decision-log.md`. If one exists for the Epic, surface it with its last session date and offer to resume — the log recovers full state regardless of compaction. Otherwise create it at intent and append a session heading. **Route resume by the last stage the log reached** — the run folder is created at intent (Stage 1), so a prior run that blocked *before* Execute also leaves one. If the log carries gate verdicts, re-enter Execute at the first story whose last verdict is not advance (advanced stories are not re-run), re-asserting — not rebuilding — the Epic branch, hooks, allowlist, and the `.mem-state.json` recall latch first
|
|
37
|
+
**Resume.** The workspace is this skill's run folder holding `.decision-log.md`. If one exists for the Epic, surface it with its last session date and offer to resume — the log recovers full state regardless of compaction. Otherwise create it at intent and append a session heading. **Route resume by the last stage the log reached** — the run folder is created at intent (Stage 1), so a prior run that blocked *before* Execute also leaves one. If the log carries gate verdicts, re-enter Execute at the first story whose last verdict is not advance (advanced stories are not re-run), re-asserting — not rebuilding — the Epic branch, hooks, allowlist, and the `.mem-state.json` recall latch first (the latch by re-running Stage 1's latch step; `references/execute.md` says why each, and why the latch especially). If instead it blocked at Stage 1 (epic unresolved) or Stage 2 (preflight RED — the case an operator fixes then re-invokes), re-run from that stage so the hard preflight gate is never skipped. In headless (`-H`) never offer — auto-resume a not-all-done Epic by this same stage routing (a previously-preflight-RED Epic re-runs the gate, it does not enter Execute), delete any existing `{workflow.implementation_artifacts}/run-result.json` as soon as that scalar resolves exactly as a fresh run does (`references/ingest-and-scope.md`), and log the resume as an assumption. **A resume routed into Execute does NOT re-run the Stage-2 formalize gate.** That verdict is Stage 2's and it is epic-scoped by construction (`formalize_check.py` takes no `--story`), so on any Epic with undrafted or later stories it reads `remediable`/`blocked` on gaps belonging to rows this invocation is not driving. Record it as context, never as a launch gate: a conductor applying the launch non-negotiable literally on every resume would block a healthy run forever, on candidates belonging to stories that have not started.
|
|
38
38
|
|
|
39
39
|
## Non-negotiables
|
|
40
40
|
|
|
41
41
|
These exist because the documented mechanics make the intuitive shortcut wrong. Do not optimize them away.
|
|
42
42
|
|
|
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
|
-
- **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.**
|
|
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
|
|
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
47
|
- **Invariants live in PreToolUse hooks**, auto-merged into `.claude/settings.local.json` at preflight — not in memory, which is context, not enforcement.
|
|
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
|
|
|
@@ -54,7 +54,7 @@ These exist because the documented mechanics make the intuitive shortcut wrong.
|
|
|
54
54
|
| 1 | Ingest & Scope | Resolve the Epic + artifacts; confirm profile (production default / `--light`) | `references/ingest-and-scope.md` |
|
|
55
55
|
| 2 | Preflight | Auto-remediate ambers, then hard-gate on red; git branch, hooks, allowlist | `references/preflight.md` |
|
|
56
56
|
| 3 | Define Done | TEA test-design + per-story ATDD → executable acceptance tests | `references/define-done.md` |
|
|
57
|
-
| 4 | Execute | Sequential `/goal` spine
|
|
57
|
+
| 4 | Execute | Sequential `/goal` spine | `references/execute.md` |
|
|
58
58
|
| 5 | Gate | `gate_eval.py` verdict → advance / defer / reloop / escalate | `references/gate.md` |
|
|
59
59
|
| 6 | Finalize | Auto Memory capture, optional retrospective, decision-log audit, report | `references/finalize.md` |
|
|
60
60
|
| 7 | Health Check | Terminal self-improvement audit — Finalize's close-out loads it; capture real workflow friction | `references/health-check.md` |
|
|
@@ -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)
|
|
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:
|
|
69
69
|
|
|
70
70
|
```json
|
|
71
71
|
{"status": "complete",
|
|
@@ -75,7 +75,7 @@ With `-H`, run non-interactively: infer scope, default to **production** (unless
|
|
|
75
75
|
"deferred_work": "<path to {workflow.deferred_work_path}, or null>"}
|
|
76
76
|
```
|
|
77
77
|
|
|
78
|
-
A run that blocked (the same five keys, plus `reason`). `report`/`deferred_work` are `null` below because a block at Stage 1 or Stage 2 produces neither;
|
|
78
|
+
A run that blocked (the same five keys, plus `reason`). `report`/`deferred_work` are `null` below because a block at Stage 1 or Stage 2 produces neither; an **escalated** run reached Stage 6 and carries their paths (`references/finalize.md`):
|
|
79
79
|
|
|
80
80
|
```json
|
|
81
81
|
{"status": "blocked",
|
|
@@ -86,6 +86,4 @@ A run that blocked (the same five keys, plus `reason`). `report`/`deferred_work`
|
|
|
86
86
|
"reason": "<one line, the blocking cause>"}
|
|
87
87
|
```
|
|
88
88
|
|
|
89
|
-
This is byte-identical to the `/ucg-formalize` envelope and the shape `references/finalize.md` and the `scripts/headless_envelope.py` adapter honor (one shared envelope definition).
|
|
90
|
-
|
|
91
89
|
Runs that reach Stage 6 (complete or escalated) also run the terminal workflow health check before emitting — in headless it queues findings locally and never blocks the emit. Runs that block at Stage 1 or Stage 2 do not: there is no executed workflow surface to audit, and inventing findings there would be fabrication.
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
|
|
2
|
-
UltraCode Goal,ultracode-goal,Run Epic Autonomously,UG,"Run a BMAD Epic autonomously to a deterministic, TEA-gated Definition-of-Done: preflight to a remediated green light, define done as executable tests, advance only on a machine-checked gate verdict.",,{<epic>: target epic id}|{--light: trace gate only}|{
|
|
2
|
+
UltraCode Goal,ultracode-goal,Run Epic Autonomously,UG,"Run a BMAD Epic autonomously to a deterministic, TEA-gated Definition-of-Done: preflight to a remediated green light, define done as executable tests, advance only on a machine-checked gate verdict.",,{<epic>: target epic id}|{--light: trace gate only}|{-H: headless}|{--yes: skip open-floor invite + launch confirm}|{--retro: close-out retrospective}|{--max-stories N: bound this invocation to N stories then finalize normally}|{setup: register or re-register the module (configure and register are aliases)},4-implementation,bmad-sprint-planning,bmad-retrospective,false,implementation_artifacts|{project-root}/_bmad-output/ultracode-goal/<run-folder>,run-report.md|deferred-work.md|run-status.json
|
|
3
3
|
UltraCode Goal,ucg-formalize,Formalize Epic Readiness,UF,"Run the standalone formalize readiness gate over an Epic's planning artifacts: auto-remediate machine-derivable gaps, route JUDGMENT candidates to one throwaway subagent, and adapt the ready/remediable/blocked verdict into the canonical five-key headless envelope.",,{-H: headless five-key JSON envelope}|{<epic>: target epic id},anytime,,,false,,five-key readiness envelope
|
|
4
4
|
UltraCode Goal,ucg-status,Read Run Status,US,"Read-only status view over a run, rendered from the files it already wrote: the heartbeat snapshot, the decision-log tail, the deferred-work ledger, the escalation sidecars, and an index of known run folders. Launches nothing, attaches to nothing, writes nothing.",,{--run-dir: a specific run folder}|{--runs-root: the runs root},anytime,,,false,,read-only status render
|
|
5
5
|
UltraCode Goal,ucg-resolve,Resolve Pending Decisions,UR,"Decide-surface for a blocked or escalated run: reconstruct every pending decision from the typed escalation sidecars, the single preflight RED sidecar and the deferred-work ledger, walk them in one guided pass, record each answer, and hand control back to the existing resume.",,,anytime,,,false,implementation_artifacts,.decisions.json
|
|
@@ -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 (/goal, Auto Mode, Auto Memory, hooks,
|
|
5
|
+
description: "Orchestrates the BMAD epic toolbox + TEA quality gates + Claude Code primitives (/goal, 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
|
|
@@ -13,8 +13,13 @@ docs_llms: "https://armelhbobdad.github.io/bmad-module-ultracode-goal/llms.txt"
|
|
|
13
13
|
# Repository that receives workflow health-check findings (fingerprint-deduped).
|
|
14
14
|
# Empty = health check off (the repo doubles as the on/off switch).
|
|
15
15
|
# MIRROR, not source: the canonical default lives in customize.toml
|
|
16
|
-
# [workflow].health_check_repo — that is what the live run reads
|
|
17
|
-
#
|
|
16
|
+
# [workflow].health_check_repo — that is what the live run reads. Nothing in
|
|
17
|
+
# this repo's installer reads the entry below: the assembled help catalog's
|
|
18
|
+
# _meta row is built from `name` + `docs_llms` alone, and merge_config.py
|
|
19
|
+
# copies only name/description/module_version/default_selected into
|
|
20
|
+
# config.yaml. It is declared here so BMad-core consumers of the installed
|
|
21
|
+
# {ucgFolder}/module.yaml see the module's default. If you fork the module,
|
|
22
|
+
# change both — editing this entry alone changes nothing the run reads.
|
|
18
23
|
# Per-project overrides go in _bmad/custom/ultracode-goal.toml as usual.
|
|
19
24
|
health_check_repo:
|
|
20
25
|
prompt: false
|
|
@@ -5,6 +5,14 @@
|
|
|
5
5
|
# is load-bearing; a plain run is unaffected or strictly improved.
|
|
6
6
|
# Idempotent strip-then-reappend is merge_customization.py's concern, matched by the
|
|
7
7
|
# per-directive [ucg:{skill}-NN] id marker each entry carries.
|
|
8
|
+
#
|
|
9
|
+
# WIRING: authored, not auto-enrolled. The installer's Step 6b enrolls only the four
|
|
10
|
+
# planning-workflow fragments (bmad-prd, bmad-architecture, bmad-create-epics-and-stories,
|
|
11
|
+
# bmad-create-story); the TEA fragments are deliberately excluded there, so a stock install
|
|
12
|
+
# never merges this file. It applies only when an operator runs it explicitly:
|
|
13
|
+
# merge_customization.py --target _bmad/custom/bmad-testarch-test-design.toml \
|
|
14
|
+
# --fragment <this file> (--remove to uninstall)
|
|
15
|
+
# Until then this shaping is inert and the gate alone is load-bearing, as above.
|
|
8
16
|
|
|
9
17
|
persistent_facts = [
|
|
10
18
|
"Extract every NFR threshold (latency, size, count, rate, timeout) from the PRD, architecture, ADRs, epics, or stories and cite the source artifact it came from; never guess a number — a genuinely-unknown threshold is marked UNKNOWN and converted into a risk, assumption, or deferral rather than an invented value. [ucg:bmad-testarch-test-design-01]",
|
|
@@ -26,8 +26,9 @@ max_turns_per_story = 25
|
|
|
26
26
|
# resolving without error. Setting it changes nothing.
|
|
27
27
|
story_token_budget = 1500000
|
|
28
28
|
|
|
29
|
-
#
|
|
30
|
-
#
|
|
29
|
+
# DEPRECATED: accepted but no-op. The experimental --parallel fan-out is retired;
|
|
30
|
+
# nothing reads this key any more. Kept so existing overrides keep resolving
|
|
31
|
+
# without error. Setting it changes nothing.
|
|
31
32
|
parallel_max_concurrency = 8
|
|
32
33
|
|
|
33
34
|
# --- Commands pre-populated to the allowlist before an unattended run ---
|
|
@@ -35,7 +36,7 @@ parallel_max_concurrency = 8
|
|
|
35
36
|
# per-story baseline SHA with `git rev-parse HEAD` before any implementation, and the evidence
|
|
36
37
|
# trail bounds a story's commit range from it. Omitting them makes an unattended run stop for a
|
|
37
38
|
# permission prompt exactly where walk-away autonomy is claimed.
|
|
38
|
-
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"]
|
|
39
40
|
|
|
40
41
|
# --- Hook fired at epic completion (prompt or shell command); empty = none ---
|
|
41
42
|
on_epic_complete = ""
|
|
@@ -57,10 +58,14 @@ on_escalation = ""
|
|
|
57
58
|
# separate enabled toggle. (assets/module.yaml mirrors this default for the
|
|
58
59
|
# installer catalog; this file is what the live run reads.)
|
|
59
60
|
health_check_repo = "armelhbobdad/bmad-module-ultracode-goal"
|
|
60
|
-
# Deliberately
|
|
61
|
-
# brace tokens above): the seen-cache is machine-global because
|
|
62
|
-
# span projects — the same defect met in two repos is still one
|
|
63
|
-
|
|
61
|
+
# Deliberately a home-relative `~` path (expanduser semantics, unlike the
|
|
62
|
+
# {project-root} brace tokens above): the seen-cache is machine-global because
|
|
63
|
+
# dedup must span projects — the same defect met in two repos is still one
|
|
64
|
+
# report. Use `~`, not `$HOME`: health_check_fp.py normalises the path with
|
|
65
|
+
# Path.expanduser() only, so a literal `$HOME` survives unexpanded whenever the
|
|
66
|
+
# shell does not expand it first and silently writes a `$HOME/` directory under
|
|
67
|
+
# the current project, making the dedup per-cwd instead of machine-global.
|
|
68
|
+
health_check_seen_cache = "~/.ultracode-goal/health-check-seen.json"
|
|
64
69
|
health_check_queue_path = "{project-root}/_bmad-output/ultracode-goal/improvement-queue"
|
|
65
70
|
# In unattended/headless runs there is no human at the [Y]/[N]/[E] gate.
|
|
66
71
|
# false (default) = queue findings locally, NEVER live-submit without a human.
|
|
@@ -28,7 +28,7 @@ For every **in-scope** story, in sprint order:
|
|
|
28
28
|
- `atdd-checklist-{story_key}.md` under the TEA test-artifacts directory — the per-story checklist mapping each AC to its planned test(s).
|
|
29
29
|
- The acceptance test files themselves, **every test marked `test.skip()`** (TDD red phase). ATDD verifies this and errors if any generated test is not skipped — that is correct and expected; the tests are *supposed* to fail/skip until Stage 4 implements the feature and un-skips them.
|
|
30
30
|
|
|
31
|
-
`bmad-testarch-atdd` **HARD HALTS** if the story lacks clear acceptance criteria or the framework is not configured. Both are preconditions this stage's step 1 and Stage 2 preflight exist to satisfy — if atdd halts anyway, the story's ACs are still too vague: loop back to `bmad-create-story` for that story and re-run atdd. Do not hand a story to Execute with a halted or absent atdd-checklist.
|
|
31
|
+
`bmad-testarch-atdd` **HARD HALTS** if the story lacks clear acceptance criteria or the framework is not configured. Both are preconditions this stage's step 1 and Stage 2 preflight exist to satisfy — if atdd halts anyway, the story's ACs are still too vague: loop back to `bmad-create-story` for that story and re-run atdd. Do not hand a story to Execute with a halted or absent atdd-checklist. **One halt is not a vague-ACs halt and no re-loop fixes it: a stack ATDD's browser generator cannot run on at all** (the framework-fitness caveat above). There the checklist is structurally unproducible, and its production substitution is defined in `references/gate.md`'s non-web section — the red phase is established BY HAND in the stack's own harness, authored, RUN and captured before the story's first implementation edit (`references/execute.md` step 1 restates it at the point of action). *That substitution* is what such a story hands to Execute; record it per story in `.decision-log.md`, and never loop it back through a generator that cannot run.
|
|
32
32
|
|
|
33
33
|
Force **Create** mode (not Resume/Validate/Edit) for the same unattended reason.
|
|
34
34
|
|
|
@@ -40,6 +40,6 @@ Stage 3 is complete, and Stage 4 may begin, when **all three** hold:
|
|
|
40
40
|
|
|
41
41
|
- The Epic has a `bmad-testarch-test-design` plan with a populated risk matrix, P0–P3 priorities assigned, and every in-scope NFR threshold either resolved or explicitly marked `UNKNOWN`/deferred.
|
|
42
42
|
- **Every in-scope story** has a story file with clear acceptance criteria.
|
|
43
|
-
- **Every in-scope story** has a generated `atdd-checklist-{story_key}.md` and red-phase (`test.skip`) acceptance tests on disk — **production only
|
|
43
|
+
- **Every in-scope story** has a generated `atdd-checklist-{story_key}.md` and red-phase (`test.skip`) acceptance tests on disk — **production only**, on a stack ATDD can run on. Under `--light` this is skipped by design; the story file's acceptance criteria stand as the trace oracle instead, and this bullet is satisfied by the clear-ACs bullet above. On a **non-web stack** (ATDD's generator cannot run), this bullet is satisfied by the recorded hand-establishment commitment per story — the substitution in step 2 above — never by a checklist nobody could generate.
|
|
44
44
|
|
|
45
|
-
In production, if any in-scope story is missing its atdd-checklist, this stage is not done — Execute has nothing executable to drive that story to. (Under `--light` an absent atdd-checklist is expected, not a gap.) Record in `.decision-log.md`: the test-design verdict, each story's AC + checklist status (or the `--light` skip), and any deferral appended to `{workflow.deferred_work_path}`.
|
|
45
|
+
In production, if any in-scope story is missing its atdd-checklist, this stage is not done — Execute has nothing executable to drive that story to. (Under `--light` an absent atdd-checklist is expected, not a gap; on a non-web stack the hand-established red phase per `references/gate.md`'s non-web section stands in for it, and the decision log says so per story.) Record in `.decision-log.md`: the test-design verdict, each story's AC + checklist status (or the `--light` skip), and any deferral appended to `{workflow.deferred_work_path}`.
|