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.
@@ -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": "4.0.0",
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 4.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."
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:** 4.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.
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 `4.x`. It enumerates the surfaces a downstream consumer or automator may reasonably depend on, versus everything else, which is `@internal`.
8
+ This is the stability posture for `bmad-module-ultracode-goal` at `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
 
@@ -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, and from which folder
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
@@ -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 cannot approve that write: under Auto Mode, which the run requires, the permission classifier may refuse it (or the calls after it) as self-modification, and under `drive_epic.py`'s default `acceptEdits` mode the write prompts with nobody there to answer. Either way the run stops at arming. So run the first invocation of a new Epic attended, in Auto Mode, through the launch briefing and on to at least one story's gate verdict; if a settings write is refused, approve it under `/permissions` (on its Recently denied tab) or apply it yourself, as the decision log describes. From then on, a session that resumes the Epic routes into Execute and only re-checks the hooks, so `-H` and `drive_epic.py` can take over.
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.
@@ -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 did not start: 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.
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.
@@ -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"| LOG["Read the tail of .decision-log.md"]
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, 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)).
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.0.0",
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 the run outright — `defer` clears nothing,
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[]` — a new answer for an `id` already
168
- present replaces that entry, every other entry is preserved untouched — and write the whole
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 the move, and the resumed run makes
246
- it.** The sidecar proposes moving clauses the earlier story owes to the later story it
247
- names, which narrows the earlier story's AC (`{ucg-root}/references/execute.md`, "Two
248
- stories green only together"). When the operator approves the move, as proposed or
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` and both ATDD checklists). This
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. **Hand back
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