bmad-module-ultracode-goal 4.0.0 → 5.0.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/docs/_internal/STABILITY.md +3 -3
- package/docs/architecture.md +1 -1
- package/docs/getting-started.md +1 -1
- package/docs/operating-tips.md +1 -1
- package/docs/troubleshooting.md +16 -6
- package/package.json +1 -1
- package/skills/ucg-formalize/SKILL.md +7 -1
- package/skills/ucg-resolve/SKILL.md +48 -11
- package/skills/ultracode-goal/references/execute.md +17 -14
- package/skills/ultracode-goal/references/finalize.md +2 -2
- package/skills/ultracode-goal/references/gate.md +8 -8
- package/skills/ultracode-goal/references/preflight.md +7 -5
- package/skills/ultracode-goal/scripts/claim_check.py +340 -15
- package/skills/ultracode-goal/scripts/formalize_check.py +228 -131
- package/skills/ultracode-goal/scripts/gate_trail.py +47 -7
- package/skills/ultracode-goal/scripts/hooks/budget_stop.py +296 -37
- package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +336 -15
- package/skills/ultracode-goal/scripts/mutate_check.py +396 -89
- package/skills/ultracode-goal/scripts/preflight_check.py +841 -60
- package/skills/ultracode-goal/scripts/probe_servers.py +633 -50
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"name": "bmad-module-ultracode-goal",
|
|
20
20
|
"source": "./",
|
|
21
21
|
"description": "Supercharges BMAD with Claude Code's Auto Mode, Auto Memory, and hooks: autonomous Epic execution to a machine-checked, TEA-gated Definition-of-Done. Execute Epics. Accumulate Knowledge. Deliver Outcomes.",
|
|
22
|
-
"version": "
|
|
22
|
+
"version": "5.0.0",
|
|
23
23
|
"author": {
|
|
24
24
|
"name": "Armel"
|
|
25
25
|
},
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Stability and Public Contract
|
|
3
|
-
description: "The
|
|
3
|
+
description: "The 5.x stability posture: which CLI, config, JSON, and gate surfaces are the supported public contract, what a major costs, and everything that is @internal and free to change."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
> **Status:**
|
|
6
|
+
> **Status:** 5.x. The surfaces below are the public contract. Per [Semantic Versioning 2.0.0](https://semver.org/), a breaking change to any of them requires a MAJOR bump; everything marked `@internal` may change in any release. This document is what a consumer pins against.
|
|
7
7
|
|
|
8
|
-
This is the stability posture for `bmad-module-ultracode-goal` at `
|
|
8
|
+
This is the stability posture for `bmad-module-ultracode-goal` at `5.x`. It enumerates the surfaces a downstream consumer or automator may reasonably depend on, versus everything else, which is `@internal`.
|
|
9
9
|
|
|
10
10
|
## Public contract
|
|
11
11
|
|
package/docs/architecture.md
CHANGED
|
@@ -58,7 +58,7 @@ skills/ultracode-goal/
|
|
|
58
58
|
│ ├── gate_eval.py # gate status -> verdict (the completion authority)
|
|
59
59
|
│ ├── operator_owed.py # is a gate FAIL owed only operator-evidence ACs' records? (fail-closed)
|
|
60
60
|
│ ├── mutate_check.py # mutation harness: attributable-red proof for the story's guards
|
|
61
|
-
│ ├── probe_servers.py # which URLs a test runner may reuse already answer,
|
|
61
|
+
│ ├── probe_servers.py # which URLs a test runner may reuse already answer, from which folder; stops a server the run left up
|
|
62
62
|
│ ├── link_worktree_deps.py # links the main tree's dependency folders into the gate worktree
|
|
63
63
|
│ ├── gate_trail.py # per-story evidence trail (gate-trail.md) at finalize
|
|
64
64
|
│ ├── formalize_check.py # readiness kernel behind the /ucg-formalize gate
|
package/docs/getting-started.md
CHANGED
|
@@ -91,4 +91,4 @@ Useful flags: `--limit N` caps how many sessions it spawns, retries included, `-
|
|
|
91
91
|
|
|
92
92
|
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. The guard's entry carries `"onFailure": "block"`, so a guard that cannot run (no `uv` on `PATH`, say) makes Claude Code refuse the tool call instead of letting it through unchecked; if every call is then refused, see [Troubleshooting](./troubleshooting.md#every-tool-call-is-refused). 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.
|
|
93
93
|
|
|
94
|
-
**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
|
|
94
|
+
**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 may be refused that write, and then nobody is there to approve it: 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 needs an approval nobody is there to give. Only `bypassPermissions` lets it land unreviewed. A refused write stops the run 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. A resume that finds the hooks need re-arming (the first after an update to 4.x does, unless it first escalates a reason that is yours to fix, such as a Claude Code older than 2.1.295; then the resume after your fix does) writes the file again: make that resume attended too, or see [Troubleshooting](./troubleshooting.md#preflight-cant-reach-budget-zero) if a headless one met a refused write.
|
package/docs/operating-tips.md
CHANGED
|
@@ -175,6 +175,6 @@ Each of these was hit while verifying real work, and each one first looked like
|
|
|
175
175
|
|
|
176
176
|
**The spawned session's sandbox may refuse network egress when the parent's does not.** A story escalated reporting that two data files "cannot be fetched" and a dependency was "absent". From the parent session both were trivially available: the dependency was already in the local package cache and a plain `curl` reached the upstream host. **When a spawn reports a dependency it cannot fetch, check the local package caches and try the fetch yourself before accepting the block.**
|
|
177
177
|
|
|
178
|
-
**Stop a dev server before an unattended drive.** A test runner that reuses a server already answering at its URL, as Playwright does with `reuseExistingServer` (which TEA's framework scaffold turns on outside CI), attaches the gate's runs in its measurement worktree to the dev server you left running from your own checkout. Those browser runs then exercise your checkout's source, not the commit under assessment, and a mutation the gate writes into the worktree never reaches them. The gate checks the URLs a runner config may reuse and never stops a server it
|
|
178
|
+
**Stop a dev server before an unattended drive.** A test runner that reuses a server already answering at its URL, as Playwright does with `reuseExistingServer` (which TEA's framework scaffold turns on outside CI), attaches the gate's runs in its measurement worktree to the dev server you left running from your own checkout. Those browser runs then exercise your checkout's source, not the commit under assessment, and a mutation the gate writes into the worktree never reaches them. The gate checks the URLs a runner config may reuse and never stops a server unless it reads as one the run itself left up (below): it gives the worktree's runs their own server on a free port when a scratch runner config can, whether or not one answers, and otherwise tells every assessor the limit, so a risk that only a browser run could measure goes unmeasured. Observed: a gate's worktree runs attached to a vite dev server listening on `[::1]:3001` that had been started from the main tree, and automate left the source mutation behind one acceptance criterion unrun, since no run from the worktree could reach it. With the dev server stopped, the runner starts its own from the worktree, but a server it starts through a launcher such as turbo, which runs it in a process group of its own, outlives the run that started it, and with reuse on the runs after it reuse it, serving the files as they were when it started: the gate turns reuse off through its scratch config where it can, and otherwise reads a mutation row run through such a server as one that cannot run. A start command in your runner config that runs the server itself (the package's own dev script rather than turbo's) keeps it from outliving the run. On Linux the gate stops a server the run itself left up, such as one the sweep right before the gate started through turbo, at each of its checks and once more when the story's gate ends, so those servers do not pile up over an Epic, and the decision log names each one it stopped. It stops one only when every process of it is yours, has no controlling terminal and started after the current story's baseline marker was written, the process that started its session has exited, nothing else that still runs in that session started before the marker or is the parent of one of its processes (a watcher or supervisor that can start it again), and it runs from your project or the gate's worktree. A server of yours can meet all of that: one inside the project and on a port the gate checks, started in the background by a command that has since exited (a script's, or another agent session's) or from a terminal you then close (a `nohup ... &`), with nothing that began before the story still running in its session, reads as the run's and is stopped. So does one that a watcher of yours starts again after the story began, when the watcher too began after the story and runs in the server's process group, or starts the server through a command that then exits and either began after the story or had that command give the server a session of its own. That marker is written when the story starts, and the resume of a stopped or blocked run keeps it, so such a server you start between a run and its resume is stopped too. So stop it before you start or resume a drive, as this tip says, or start it outside the project, on another port or from a terminal you keep open.
|
|
179
179
|
|
|
180
180
|
**Pin the parallelism of the verification suite if it is timing-sensitive.** Observed: a full-concurrency test run was flaky two green in five, because one unrelated gate crept past a 10-second default timeout under contention while taking 1.7 seconds alone. Pinning the runner to one worker (`ava --concurrency=1`; your runner's own name for it will differ) was green every time. A flaky verification tier makes every story's evidence unreliable, which is worse than a slow one.
|
package/docs/troubleshooting.md
CHANGED
|
@@ -25,9 +25,11 @@ flowchart TD
|
|
|
25
25
|
R -->|"yes"| RES["See: Resume after an interruption"]
|
|
26
26
|
R -->|"no"| D{"A drive stopped and you cannot tell why"}
|
|
27
27
|
D -->|"yes"| OPS["See: operating tips, the driver's stop reasons"]
|
|
28
|
-
D -->|"no"|
|
|
28
|
+
D -->|"no"| V{"A dev server of yours is gone after a drive"}
|
|
29
|
+
V -->|"yes"| SRV["See: The gate stopped a server, or left one up"]
|
|
30
|
+
V -->|"no"| LOG["Read the tail of .decision-log.md"]
|
|
29
31
|
classDef accent fill:#6366F1,stroke:#4F46E5,color:#fff
|
|
30
|
-
class PRE,GATE,HOOK,REF,BUD,RES,OPS,LOG accent
|
|
32
|
+
class PRE,GATE,HOOK,REF,BUD,RES,OPS,SRV,LOG accent
|
|
31
33
|
```
|
|
32
34
|
|
|
33
35
|
## Preflight can't reach budget-zero
|
|
@@ -40,9 +42,9 @@ flowchart TD
|
|
|
40
42
|
|
|
41
43
|
- **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.
|
|
42
44
|
- **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.
|
|
43
|
-
- **Claude Code below the minimum versions.** The primitive-version blocker (`cc_version`) is marked non-remediable: the script can't upgrade the host. It names each primitive the version lacks. 2.1.295 is the floor, the release that added the hook setting `"onFailure": "block"` the guard is armed with. Update Claude Code (`claude update`).
|
|
45
|
+
- **Claude Code below the minimum versions.** The primitive-version blocker (`cc_version`) is marked non-remediable: the script can't upgrade the host. It names each primitive the version lacks. 2.1.295 is the floor, the release that added the hook setting `"onFailure": "block"` the guard is armed with. Update Claude Code (`claude update`). A run already in flight meets the same floor when it resumes: the resume runs `claude --version`, and below 2.1.295 it escalates the story it was about to drive instead of driving it. Update Claude Code, then resume in a new session, since an update takes effect only when Claude Code next starts: the resume shows that escalation and offers `/ucg-resolve` to close it (headless, run `/ucg-resolve` first). On a run UCG 3.x armed, that resume is also the one that re-arms the hooks, a write to `.claude/settings.local.json`: make it attended, since a headless one may be refused the write (see "A refused settings write" below). Both checks run the `claude` first on `PATH`, not the binary the session runs on. With two installs (an npm one beside the native installer's, say), or a `drive_epic.py --claude-bin` that names another binary, update the one first on `PATH` too, or the check reads its older version.
|
|
44
46
|
- **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.
|
|
45
|
-
- **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,
|
|
47
|
+
- **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, nobody is there to approve a refused write. At preflight the run then stops, and `/ucg-resolve` is not the way back: take the Epic through preflight attended (see [hook security](./getting-started.md#hook-security)). A resume rewrites the file too when the hooks need re-arming (the first resume after an update to 4.x does, unless it first escalates a reason that is yours to fix, such as a Claude Code older than 2.1.295), and a headless resume whose write is refused escalates the story it was about to drive instead. Resume attended: make or approve the write it asks for, and close that escalation with `/ucg-resolve`, which the resume offers before it drives the story. Whether a headless session is refused the write depends on its permission mode: under `bypassPermissions` the write lands, under Auto Mode the classifier decides, and under `default`, `acceptEdits` (the mode `drive_epic.py` spawns in unless you pass another) or `dontAsk` it is refused, since a write to a protected file needs an approval nobody is there to give.
|
|
46
48
|
- **Story skills not installed.** The run delegates story creation to `ucg-create-story` and implementation to `ucg-dev-story`, the story skills UCG ships in place of BMAD Method's deprecated `bmad-create-story` and `bmad-dev-story`. UCG's installer copies them beside the `ultracode-goal` skill, so a missing one means a partial or older UCG install, or an install from the plugin marketplace alone, which ships only the `ultracode-goal` skill. The `story_skills` blocker is non-remediable: the run neither installs them nor works around them. Its detail names the fix, `npx bmad-module-ultracode-goal update` from the project root (`install` where UCG was never installed there). BMAD's own shims, installed with `--shims`, do not satisfy it (see [Prerequisites](./getting-started.md#prerequisites)). The same check runs on every resume, so a story skill deleted mid-Epic, by hand or by an install interrupted while it re-copies the UCG skills, stops the next spawn instead of letting it improvise.
|
|
47
49
|
- **TEA skills not installed.** The run delegates test design, acceptance tests, review and the gate to TEA's `bmad-testarch-*` skills. Production needs all eight. `--light` needs three: `bmad-testarch-framework`, `bmad-testarch-test-design` and `bmad-testarch-trace`. The `tea_skills` blocker is non-remediable: the run never installs TEA. UCG supports BMAD 6 with TEA 1.27.x, which BMAD Method 6.12.2 and later install. Add or repair TEA from the project root with `npx bmad-method install`, with the `tea` module selected, then re-run. If the detail says it found `bmad-tea-*` skills instead, the project has TEA 3.0 or later, which renamed the skills UCG calls. UCG does not support it yet: install TEA 1.27.x through BMAD 6 instead (see [Prerequisites](./getting-started.md#prerequisites)). Preflight checks skill names, not the TEA version. TEA 2.x moved to BMAD 7's module format but kept the `bmad-testarch-*` names, so preflight does not catch it, though UCG does not support it either. Preflight checks these skills at launch only. A TEA skill removed mid-Epic escalates the story that calls it.
|
|
48
50
|
|
|
@@ -63,6 +65,14 @@ Note this is fail-closed on purpose: a missing or unreadable gate artifact escal
|
|
|
63
65
|
|
|
64
66
|
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).
|
|
65
67
|
|
|
68
|
+
## The gate stopped a server, or left one up
|
|
69
|
+
|
|
70
|
+
**Symptom.** A dev server you had running is gone after a drive, or the decision log's worktree line names a server the gate stopped, or one it left up.
|
|
71
|
+
|
|
72
|
+
**What happened.** A test runner such as Playwright starts a server through a launcher such as turbo, which runs it in a process group of its own, so the server outlives the run. Execute's sweep right before the gate leaves one up in the main tree that way, and so does a gate run. On Linux the gate stops such a server with `scripts/probe_servers.py` at each of its checks, and once more when the story's gate ends, so the gate's runs in its worktree do not reuse it and those servers do not pile up over an Epic. It stops a server only when every process of it is yours, has no controlling terminal and started after the story's `.baseline-<story_id>` marker was written, the process that started its session has exited, nothing else that still runs in that session started before the marker or is the parent of one of its processes (a watcher or supervisor that can start it again), and it runs from the project or the gate's worktree. It leaves every other server up, and its `left` list gives the reason; on macOS and Windows it stops nothing. The gate never stops a server any other way.
|
|
73
|
+
|
|
74
|
+
**What you do.** If it stopped a server of yours, that server met every condition: it started inside the project, on a port the gate checks and after the story's marker was written, it had no terminal and had outlived the command that started its session, as a server does that a script or another agent session starts in the background, or one you start with `nohup ... &` from a terminal you then close, and nothing that began before the marker still ran in its session. A watcher or supervisor of yours that starts the server again after the marker (on a file change the run makes, say) keeps it up only while it runs in the server's session and either began before the marker or is the parent of one of the server's processes from a process group of its own; the server reads as the run's when the watcher began after the marker and either runs in the server's process group or starts it through a command that then exits and is not its parent afterwards (a subreaper adopts it back), or, whenever the watcher began, when that command gave the server a session of its own. That marker is written when the story starts, and the resume of a stopped or blocked run keeps it, so it can be days old: a server you start between a run and its resume counts too. Start it again, and stop such a server before you start or resume a drive, or start it outside the project, on another port or from a terminal you keep open. A server it left up keeps its port, so the gate gives the worktree's runs a server of their own through a scratch runner config where it can, and otherwise tells each assessor what that server leaves unmeasured. When the run left that server up, stop it yourself once the drive is done: a runner killed before it could end its start command leaves one whose session's first process still runs, and a watcher the run's own start command runs (a launcher task that runs watchexec, cargo-watch or air, say) keeps up the server it runs in a process group of its own, as a watcher of yours does, so stop that watcher too. A drive that stops before a story's gate logs its verdict can leave one up as well: that story's next gate stops it when you resume the run, so stop it yourself only if you do not resume.
|
|
75
|
+
|
|
66
76
|
## Hooks not firing
|
|
67
77
|
|
|
68
78
|
**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.
|
|
@@ -80,7 +90,7 @@ A per-story gate can return `reloop` with a `PASS` gate status when a cap fired
|
|
|
80
90
|
**What happened.** Preflight arms the PreToolUse guard with `"onFailure": "block"`, so when the guard cannot run, Claude Code refuses the call rather than letting it through unchecked. The guard's matcher covers every tool, so a guard that cannot run refuses every call, including the ones the session would need to repair it. The usual causes:
|
|
81
91
|
|
|
82
92
|
- **`uv` is not on the `PATH` Claude Code runs hooks with.** The guard runs as `uv run …`, and a shell that cannot find `uv` exits 127. A session started from a shell or launcher with a narrower `PATH` than the one preflight ran in hits this.
|
|
83
|
-
- **The skill was moved or removed.** The guard's command names the script by the path the skill was installed at; an uninstall, or a reinstall to another folder, leaves the command pointing at nothing.
|
|
93
|
+
- **The skill was moved or removed.** The guard's command names the script by the path the skill was installed at; an uninstall, or a reinstall to another folder, leaves the command pointing at nothing. When the project, or a folder above it, holds a `pyproject.toml`, `uv run` syncs that project on every call before it finds the script missing: it creates the project's `.venv` and `uv.lock` on the first call and builds the project again whenever it changes, and the refusal can show that project's build error instead of `Failed to spawn`. The budget hook's command points at nothing too. `uv` exits 2 when it cannot find the script, which on a `Stop` hook Claude Code reads as a block: each time the session tries to stop, it is sent back with uv's error instead, up to eight times in a row, after which Claude Code lets the stop through (the count starts again whenever Claude calls a tool). When that project fails to build, or its requirements cannot be satisfied, `uv` stops there and exits 1, which Claude Code reads on a `Stop` hook as a non-blocking error: the session stops, and the turn goes uncounted. A network failure in that sync exits 2 instead, and each stop is sent back as above. Reinstalling the skill ends it; then delete a `.venv` or `uv.lock` those calls left in a project that had none.
|
|
84
94
|
- **A path with a space, left unquoted in the command.** Claude Code runs the guard's command through a shell, which splits it at every unquoted space. Preflight writes each injected value and the script path in single quotes, so a project or skill folder whose path holds a space (`~/My Projects/app`, say) stays one word. A command written without them hands the rest of that path to the shell as the command to run, and the message names it: `/bin/sh: 1: Projects/app/_bmad-output/implementation-artifacts: not found` on Linux, or the same path followed by `No such file or directory` on macOS.
|
|
85
95
|
- **No Python `uv` can use.** `uv` cannot start a Python the script's header allows.
|
|
86
96
|
- **The guard ran past its timeout.** Claude Code's default for a command hook is 600 seconds; the message then says `timed out`.
|
|
@@ -91,7 +101,7 @@ A refusal the guard makes itself reads differently: it starts with the guard's o
|
|
|
91
101
|
|
|
92
102
|
1. Run the guard's command from `.claude/settings.local.json` yourself, in a terminal, to see why it fails (`echo '{}' | <the command>` should exit 0 and print nothing).
|
|
93
103
|
2. Fix what it shows: put `uv` on `PATH`, reinstall the skill (`npx bmad-module-ultracode-goal update`), install a Python the script allows, or put each injected value and the script path in single quotes (`KEY='value' uv run '<path>'`), in the Stop budget hook's command too. From the project root, `uv run '<the skill folder>/scripts/preflight_check.py' --assert-armed --project-root . --impl-artifacts _bmad-output/implementation-artifacts` names every UCG hook command the shell would split (pass your own artifacts folder if you moved it).
|
|
94
|
-
3. Then resume the run. The resume re-checks the hooks and re-arms them if they need it.
|
|
104
|
+
3. Then resume the run. The resume re-checks the hooks and re-arms them if they need it, unless it also finds a reason that is yours to fix, a missing story skill or a Claude Code older than 2.1.295: it then escalates the story it was about to drive first, and re-arms the hooks on the resume after you fix that.
|
|
95
105
|
|
|
96
106
|
If you need the session working before you can fix the cause, remove the guard's item from `.claude/settings.local.json` by hand, as [SECURITY.md](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/SECURITY.md) describes under "How to remove them". The session then runs with no guard at all, and a resume or the next preflight puts the item back, so fix the cause before either.
|
|
97
107
|
|
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": "
|
|
4
|
+
"version": "5.0.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",
|
|
@@ -91,7 +91,13 @@ them here. There is one kernel — a second readiness evaluator would let the tw
|
|
|
91
91
|
drift.
|
|
92
92
|
|
|
93
93
|
The kernel is fail-closed: a missing / unreadable / ambiguous artifact is recorded
|
|
94
|
-
as a failing gap, never a neutral pass.
|
|
94
|
+
as a failing gap, never a neutral pass. Of TEA's output it reads only the Epic's own,
|
|
95
|
+
under TEA's test-artifacts root (the TEA config's `test_artifacts`, else
|
|
96
|
+
`_bmad-output/test-artifacts`): every `test-design-epic-<id>.md`, and an
|
|
97
|
+
`nfr-assessment.md` whose `**Story:**` line names a story it reads (one beside the
|
|
98
|
+
Epic's test-design that cannot be read is a failing gap). A test-design or NFR
|
|
99
|
+
assessment the Epic does not have yet is no gap, and another Epic's test-design or
|
|
100
|
+
TEA's system-level files never raise one.
|
|
95
101
|
|
|
96
102
|
## 2. Mechanical auto-remediation pass
|
|
97
103
|
|
|
@@ -147,12 +147,23 @@ exists to remove.
|
|
|
147
147
|
|
|
148
148
|
An entry recorded with `action` `defer` is the opposite case: it is a parked question, not
|
|
149
149
|
an answered one. Present it again, and replace its entry in place when the operator decides
|
|
150
|
-
it. Suppressing a deferred item would deadlock
|
|
150
|
+
it, carrying its answer forward (section 3). Suppressing a deferred item would deadlock
|
|
151
|
+
the run outright: `defer` clears nothing,
|
|
151
152
|
so the next preflight still blocks on that RED (`{ucg-root}/references/preflight.md`,
|
|
152
153
|
step 3, drops only the ids whose `action` is `close`), while this surface, the only one that
|
|
153
154
|
can answer it, would never ask again. The scan blocks forever on a question the operator is
|
|
154
155
|
no longer offered.
|
|
155
156
|
|
|
157
|
+
An entry with no `action`, or with an `action` that is neither `close` nor `defer`, is
|
|
158
|
+
pending as well. An earlier version of this surface wrote some entries that way, and
|
|
159
|
+
preflight drops none of their ids, so their questions still block. Present it again, as
|
|
160
|
+
you present a deferred one.
|
|
161
|
+
|
|
162
|
+
When an item you present already has an entry, show its `answer`, and each earlier answer
|
|
163
|
+
its `history` holds (section 3), beside the decision needed. Such an answer can hold the
|
|
164
|
+
operator's whole ruling: they decide on the record as it stands, and may find it already
|
|
165
|
+
answers the question.
|
|
166
|
+
|
|
156
167
|
## 3. Record the answer, then apply its disposition
|
|
157
168
|
|
|
158
169
|
Every answer lands in `{workflow.implementation_artifacts}/.decisions.json`:
|
|
@@ -160,18 +171,33 @@ Every answer lands in `{workflow.implementation_artifacts}/.decisions.json`:
|
|
|
160
171
|
```json
|
|
161
172
|
{"decisions": [{"id": "<the pending item's stable id>",
|
|
162
173
|
"answer": "<what the operator decided, one line>",
|
|
163
|
-
"action": "close|defer"
|
|
174
|
+
"action": "close|defer",
|
|
175
|
+
"history": [{"answer": "<an answer this entry replaced, verbatim>",
|
|
176
|
+
"action": "<that answer's action, when it had one>"}]}]}
|
|
164
177
|
```
|
|
165
178
|
|
|
166
179
|
**Write the file read-modify-write, keyed by `id`.** Read any existing `.decisions.json`
|
|
167
|
-
first, merge this pass's answers into its `decisions[]`
|
|
168
|
-
present replaces that entry
|
|
180
|
+
first, merge this pass's answers into its `decisions[]` (a new answer for an `id` already
|
|
181
|
+
present replaces that entry and carries its answer forward, as the next paragraph says;
|
|
182
|
+
every other entry is preserved untouched), and write the whole
|
|
169
183
|
array back. The fence above is the shape of the *document*, not a licence to emit only this
|
|
170
184
|
pass's answers: a plain overwrite would discard every answer recorded by an earlier pass,
|
|
171
185
|
including the `close` entries preflight reads to keep resolved REDs suppressed. Those
|
|
172
186
|
decisions would silently return as pending and re-block a run the operator already
|
|
173
187
|
unblocked.
|
|
174
188
|
|
|
189
|
+
**A replacement never drops an earlier answer.** When a new answer replaces the entry for
|
|
190
|
+
its `id`, the new entry carries that entry forward in `history`: copy the replaced entry's
|
|
191
|
+
`history` list as it stands, then append the replaced entry itself, with every field but
|
|
192
|
+
`id` and `history` copied verbatim (its `answer`, and its `action` when it had one). When
|
|
193
|
+
the file holds more than one entry for that `id`, carry each forward, in file order, and
|
|
194
|
+
write one entry in their place. Leave `history` off an entry that replaced nothing. A pass
|
|
195
|
+
that only parks an item records one line, while the entry it replaces can hold the
|
|
196
|
+
operator's whole ruling: a plain replacement would erase that ruling, and nothing in the
|
|
197
|
+
pass would report the loss. Every reader of the file keys on `id` and `action` alone
|
|
198
|
+
(`{ucg-root}/scripts/red_ids.py`, which preflight and the resume read it through), so
|
|
199
|
+
`history` changes no suppression.
|
|
200
|
+
|
|
175
201
|
**If an existing `.decisions.json` is unreadable, unparseable, or parsed but missing a
|
|
176
202
|
list-valued `decisions`, stop — do not overwrite it.** Say which file failed and why. This
|
|
177
203
|
is the fail-closed twin of the rule preflight already applies to the same file (an
|
|
@@ -242,21 +268,30 @@ The two dispositions are genuinely different things, not two names for one:
|
|
|
242
268
|
and removes the marker (`{ucg-root}/references/gate.md`, "Commit the gate's evidence
|
|
243
269
|
before the next story starts"), on the Epic's last story too, where every row already
|
|
244
270
|
reads `done` and the resume re-enters only for that commit before Finalize.
|
|
245
|
-
**Closing a `coupled-stories` escalation records
|
|
246
|
-
it
|
|
247
|
-
|
|
248
|
-
|
|
271
|
+
**Closing a `coupled-stories` escalation records a proposed move, and the resumed run
|
|
272
|
+
makes it; a re-plan is the operator's own edit.**
|
|
273
|
+
The sidecar proposes moving clauses the earlier story owes to the later story it
|
|
274
|
+
names, which narrows the earlier story's AC, or it proposes only a re-plan, where no
|
|
275
|
+
move fits: the later story is outside the run's scope, the two stories are a pair no
|
|
276
|
+
move applies to (a decomposed child beside a story that has a file, or children of two
|
|
277
|
+
parents), or an AC between two decomposed children holds a clause no run measured
|
|
278
|
+
(`{ucg-root}/references/execute.md`, "Two stories green only together"). When the
|
|
279
|
+
operator approves a proposed move, as proposed or
|
|
249
280
|
reworded, write the sidecar's `decision_needed` verbatim into this answer's
|
|
250
281
|
`.decision-log.md` entry, under both story keys it names, beside the operator's answer
|
|
251
282
|
and the id you closed, before you delete the sidecar: once the sidecar is gone, that
|
|
252
283
|
entry is the only copy of the move the resumed run writes into both story files, or for
|
|
253
284
|
two decomposed children into every record of their split (the split record, both child
|
|
254
|
-
rows in `sprint-status.yaml
|
|
285
|
+
rows in `sprint-status.yaml`, the earlier child's ATDD checklist and the later child's
|
|
286
|
+
when it has one). This
|
|
255
287
|
surface edits neither story file and moves no test case: the ruling is the operator's,
|
|
256
288
|
and the resumed run applies it before the earlier story's next commit. An answer that
|
|
257
289
|
re-plans the rows instead (one story in place of the two, or another order) is the
|
|
258
290
|
operator's own edit of `sprint-status.yaml` and the story files: record `defer` until
|
|
259
|
-
they have made it, then `close`.
|
|
291
|
+
they have made it, then `close`. A sidecar that proposes only a re-plan has no move for
|
|
292
|
+
this surface to record or for the resumed run to apply, so whatever the operator rules
|
|
293
|
+
for it is their own edit of those files: record `defer` until they have made it, then
|
|
294
|
+
`close`.
|
|
260
295
|
- **`defer`** — the decision is not made yet. Record the entry **without clearing
|
|
261
296
|
anything**. The artifact stays exactly where it is, the item stays pending, and the next
|
|
262
297
|
preflight still blocks on it.
|
|
@@ -266,7 +301,9 @@ Record each answer and its disposition in `.decision-log.md` as you apply it.
|
|
|
266
301
|
## 4. Hand control back to the existing resume
|
|
267
302
|
|
|
268
303
|
`/ucg-resolve` defines no resume of its own. Close the pass by stating what closed, what is
|
|
269
|
-
still pending, and that anything still pending re-blocks at the next preflight.
|
|
304
|
+
still pending, and that anything still pending re-blocks at the next preflight. Name every
|
|
305
|
+
entry this pass replaced, by `id`, with the earlier answer it carried into `history`, so
|
|
306
|
+
the operator sees what the record held before this pass. **Hand back
|
|
270
307
|
only when the pass closed at least one item, or when the operator asks for the resume**: a
|
|
271
308
|
pass that deferred everything hands into a run blocked on the identical items, and an empty
|
|
272
309
|
enumeration means the run stopped for a non-decision reason — say so, point at the read-only
|