bmad-module-ultracode-goal 5.0.0 → 7.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": "5.0.0",
22
+ "version": "7.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 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."
3
+ description: "The 7.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:** 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.
6
+ > **Status:** 7.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 `5.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 `7.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
 
@@ -27,7 +27,7 @@ These are the module's non-negotiables. Each exists because the documented mecha
27
27
 
28
28
  A set of invariants must hold before the runtime lets a tool call through, and none of them can live in memory, which is context the model may or may not weigh:
29
29
 
30
- - **`scripts/hooks/guard_pretooluse.py`** (PreToolUse): inspects each `git commit`/`git push` and enforces seven invariants. It denies the command on a protected branch; denies a `git commit` when no tests-ran marker (`<impl-artifacts>/.tests-ran-<story_id>`) exists for the current story; denies it when that marker's `baseline=<sha>` does not match the SHA the story recorded at start; denies it when the staged index is empty or unreadable; and denies it, when armed with `ULTRACODE_TEST_ARTIFACTS`, while the staged content of a checklist-enumerated acceptance test still contains `test.skip(`. The last two are not about git at all: they run for every tool call while a Cross-Session Recall latch is present. The sixth denies every claude-mem MCP call and any reach into `.claude-mem`, whatever the latch records. The seventh denies tool calls that name the recall store or would change the latch itself, except the skill's own two recall scripts; reading the latch stays allowed. It returns a `deny` decision in the hook JSON and also exits 2 with the reason on stderr so older clients that ignore the JSON still block. The marker, freshness, staged-index, and recall-latch checks fail **closed**, denying on an input they cannot read. Two do not: the protected-branch check fails **open** when `git rev-parse` cannot report a branch, and the un-skip proof is out of scope entirely when `ULTRACODE_TEST_ARTIFACTS` is unset. The protected-branch check is also scoped to the **session's** working directory rather than the repository the command names, so it denies a `git commit`/`git push` aimed at another checkout whenever the session's own repo is on a protected branch.
30
+ - **`scripts/hooks/guard_pretooluse.py`** (PreToolUse): inspects each `git commit`/`git push` and enforces seven invariants. It denies the command on a protected branch; denies a `git commit` when no tests-ran marker (`<impl-artifacts>/.tests-ran-<story_id>`) exists for the current story; denies it when that marker's `baseline=<sha>` does not match the SHA the story recorded at start; denies it when the staged index is empty or unreadable, or while it holds an intent-to-add entry (`git add -N`, which Execute makes for a story's new files before its sweep), naming each one, since the commit would leave that file out, or, for a mark over a path HEAD holds, delete HEAD's file; and denies it, when armed with `ULTRACODE_TEST_ARTIFACTS`, while the staged content of a checklist-enumerated acceptance test still contains `test.skip(`. The last two are not about git at all: they run for every tool call while a Cross-Session Recall latch is present. The sixth denies every claude-mem MCP call and any reach into `.claude-mem`, whatever the latch records. The seventh denies tool calls that name the recall store or would change the latch itself, except the skill's own two recall scripts; reading the latch stays allowed. It returns a `deny` decision in the hook JSON and also exits 2 with the reason on stderr so older clients that ignore the JSON still block. The marker, freshness, staged-index, intent-to-add, and recall-latch checks fail **closed**, denying on an input they cannot read. Two do not: the protected-branch check fails **open** when `git rev-parse` cannot report a branch, and the un-skip proof is out of scope entirely when `ULTRACODE_TEST_ARTIFACTS` is unset. The protected-branch check is also scoped to the **session's** working directory rather than the repository the command names, so it denies a `git commit`/`git push` aimed at another checkout whenever the session's own repo is on a protected branch.
31
31
  - **`scripts/hooks/budget_stop.py`** (Stop): counts turns for the current story against `max_turns_per_story`. On overrun it writes an escalation marker and surfaces a message, then **lets the stop proceed**. Its documented limitation: a Stop hook fires only when Claude is already trying to stop, so it cannot interrupt a `/goal` condition mid-turn. Its count advances once per Stop, so it cannot see re-loops spent inside a single response. The conductor reads it before a story starts and before each re-loop, where the gate's re-loop budget turns a re-loop that would exceed the ceiling into `escalate`. The in-condition "stop after N turns" clause binds only an operator's own `/goal`, since the conductor cannot start one. This hook itself is the recorder. The conductor promotes its marker to a `budget-overrun` escalation only when the story's gate escalates it on that count; a story that advances gets a sizing note instead.
32
32
 
33
33
  Both hooks read their config from env first (so the conductor injects per-run values) and fall back to hardcoded defaults (`main`/`master`, `25`, `ultracode/epic-`). Because of that fallback, a `customize.toml` override **silently no-ops at the enforcement layer** unless the conductor passes it through the hook env, so preflight injects `ULTRACODE_PROTECTED_BRANCHES`, `ULTRACODE_IMPL_ARTIFACTS`, `ULTRACODE_MAX_TURNS`, `ULTRACODE_EPIC_BRANCH_PREFIX`, and `ULTRACODE_TEST_ARTIFACTS`.
@@ -130,4 +130,4 @@ flowchart LR
130
130
 
131
131
  ## Why the hooks live in settings.local.json
132
132
 
133
- The PreToolUse and Stop hooks are auto-merged into `{project-root}/.claude/settings.local.json` (machine-local, gitignored, honored after the workspace trust dialog), not into a committed settings file or memory. The reasoning: these hooks are **enforcement, not context**. A committed hook would impose this module's commit guard on every contributor and every unrelated session in the repo; a hook in memory would not block a commit at all. The machine-local file scopes enforcement to the machine actually running the unattended Epic, and the gitignore keeps it out of shared history. The skill re-merges them every run (idempotently) and asserts they are active before the run goes unattended; it does not assume a prior run left them in place. The guard's entry carries `"onFailure": "block"` (Claude Code 2.1.295 and later), so a guard that cannot start, crashes or times out refuses the tool call instead of letting it through: an enforcement layer that fails open when it breaks is no enforcement layer, and the price is that a broken guard stops the session until someone fixes it. Because the file is machine-local and executes on your machine, review what is merged; see [SECURITY.md](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/SECURITY.md).
133
+ The PreToolUse and Stop hooks are auto-merged into `{project-root}/.claude/settings.local.json` (machine-local, gitignored, honored after the workspace trust dialog), not into a committed settings file or memory. The reasoning: these hooks are **enforcement, not context**. A committed hook would impose this module's commit guard on every contributor and every unrelated session in the repo; a hook in memory would not block a commit at all. The machine-local file scopes enforcement to the machine actually running the unattended Epic, and the gitignore keeps it out of shared history. The skill re-merges them every run (idempotently), checks the file, and then proves that the running session runs the guard before the run goes unattended, since Claude Code's file watcher can miss an edit made while a session runs; it does not assume a prior run left them in place. The guard's entry carries `"onFailure": "block"` (Claude Code 2.1.295 and later), so a guard that cannot start, crashes or times out refuses the tool call instead of letting it through: an enforcement layer that fails open when it breaks is no enforcement layer, and the price is that a broken guard stops the session until someone fixes it. Because the file is machine-local and executes on your machine, review what is merged; see [SECURITY.md](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/SECURITY.md).
@@ -91,7 +91,7 @@ flowchart TD
91
91
 
92
92
  Each recall call is attempted once and never retried. A run whose recall turned off along the way says so in its report, with the tokens under [troubleshooting](#troubleshooting).
93
93
 
94
- **What a record holds.** The Epic, the run id, the repo fingerprint, the gate status and verdict, the root-cause signatures (each with a class from a fixed taxonomy and an artifact path), the count of deferred items, the advisories the run consumed with whether they recurred, the time, and the project's folder name for display. Free text is redacted before it is written. A run that blocked with no gate status (it escalated or handed off before a gate ran, or its gate could not be read) writes a record with gate status `NOT_EVALUATED` and verdict `blocked`, so the next run sees that it blocked; a `WAIVED` outcome is written too. A resume that stops because the story's escalation is still open names no root cause in its record: the run that raised the escalation recorded it, so stopping again on one unanswered decision does not count as recurring. `NOT_EVALUATED` with any other verdict writes no record.
94
+ **What a record holds.** The Epic, the run id, the repo fingerprint, the gate status and verdict, the root-cause signatures (each with a class from a fixed taxonomy and an artifact path), the count of deferred items, the advisories the run consumed, each named by the run id of the record it read, with whether that record's root cause recurred (`yes` when a root cause outside the `other` class is in both records, `no` when that record names one and this run shares none, `unknown` otherwise), the time, and the project's folder name for display. Free text is redacted before it is written. A run that blocked with no gate status (it escalated or handed off before a gate ran, or its gate could not be read) writes a record with gate status `NOT_EVALUATED` and verdict `blocked`, so the next run sees that it blocked; a `WAIVED` outcome is written too. A resume that stops because the story's escalation is still open names no root cause in its record: the run that raised the escalation recorded it, so stopping again on one unanswered decision does not count as recurring. `NOT_EVALUATED` with any other verdict writes no record.
95
95
 
96
96
  **When the store cannot take a record.** The record waits in `mem-outbox.<run_id>.jsonl` in the implementation artifacts folder, and the run logs `WARN mem-write-deferred`. The next run that reaches Finalize with a green latch drains it, keeping its original time. A deferred record older than 14 days is dropped, and one whose drain fails three times moves to `mem-outbox.dead.jsonl`, with `WARN mem-write-dead-lettered`. No drain replays that file.
97
97
 
@@ -83,7 +83,7 @@ The driver is read-only on your tree with exactly one exception: it deletes the
83
83
 
84
84
  **One of those is retried rather than fatal.** A `claude -p` can be terminated in flight by the API layer, leaving no terminal, and that is not a story problem: the same row lands on the next attempt against identical state. The driver retries a no-terminal stop up to `--max-abort-retries` times (default 2, `0` disables), but **only** when its post-stop triage finds the tree clean and HEAD unmoved, so a retry can never re-spawn over work in progress.
85
85
 
86
- **Every post-spawn stop now prints a triage block** describing the tree the session left: clean with HEAD advanced (the work committed and only close-out is missing, so verify and mark it done rather than re-driving), clean and unmoved (nothing landed), or dirty (which may hold a suite that is already green). It reports and never decides. It also names any intent-to-add path, because `git checkout -- <path>` truncates those to zero bytes and exits `0`.
86
+ **Every post-spawn stop now prints a triage block** describing the tree the session left: clean with HEAD advanced (the work committed and only close-out is missing, so verify and mark it done rather than re-driving), clean and unmoved (nothing landed), or dirty (which may hold a suite that is already green). It reports and never decides. It also names any intent-to-add path (Execute marks a story's new files that way before each sweep), because `git checkout -- <path>` and `git restore <path>` truncate those to zero bytes and exit `0`, and `git reset --hard` deletes a new one and reverts one git already tracked to its last commit, discarding its edits.
87
87
 
88
88
  Useful flags: `--limit N` caps how many sessions it spawns, retries included, `--permission-mode` defaults to `acceptEdits` and refuses `bypassPermissions` unless you also pass `--allow-full-autonomy`, and `--skill-command` overrides the invocation string for a plugin-marketplace install (`/bmad-module-ultracode-goal:ultracode-goal`).
89
89
 
@@ -70,7 +70,7 @@ This is the load-bearing gate, because after it the run goes unattended. The pos
70
70
  2. **Auto-remediation pass**: clear each remediable blocker, then re-run the check so `budget` reflects the fixes: create the Epic branch when the run started on a protected branch (it is a remediable, budget-counted blocker, so it has to clear here rather than at arming), scaffold the test framework (`bmad-testarch-framework`), scaffold the CI quality pipeline (`bmad-testarch-ci`, production only, strictly *after* the framework), generate missing acceptance criteria (`ucg-create-story`), pre-create the TEA output dirs, de-duplicate `project-context.md` when there is more than one (a missing one is logged, never generated), ensure `sprint-status.yaml` is present, force TEA **Create** mode, and prompt once (interactively) for any secrets.
71
71
  3. **Semantic intervention scan**: the part the script cannot do: read the PRD and ADR for undecided product/architecture decisions, contradictions, acceptance criteria that presuppose an unmade decision, or a story whose "done" is undefinable. Any such item is **RED** and cannot be auto-remediated, because the fix is a human decision.
72
72
 
73
- The run launches **only** when all hold: post-remediation `budget == 0`, the semantic scan found no RED, and ultracode session effort plus Auto Mode are on. Then the skill arms the environment: asserts the Epic branch off `epic_branch_prefix` (already created during remediation when the run started on a protected branch), merges the PreToolUse and Stop hooks into `.claude/settings.local.json` (asserting they are active, and injecting the resolved config into their env), and pre-populates the allowlist. On an attended run it prints the launch briefing and takes one soft confirm. See [`references/preflight.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/preflight.md).
73
+ The run launches **only** when all hold: post-remediation `budget == 0`, the semantic scan found no RED, and ultracode session effort plus Auto Mode are on. Then the skill arms the environment: asserts the Epic branch off `epic_branch_prefix` (already created during remediation when the run started on a protected branch), merges the PreToolUse and Stop hooks into `.claude/settings.local.json` (checking the file, and injecting the resolved config into their env), pre-populates the allowlist, and then proves the session runs the hooks: one `git commit --dry-run`, which creates no commit, must be refused by the guard, or preflight stops. On an attended run it prints the launch briefing and takes one soft confirm. See [`references/preflight.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/preflight.md).
74
74
 
75
75
  ### Stage 3: Define Done
76
76
 
@@ -78,7 +78,7 @@ Turn the Epic's acceptance criteria into **executable, red-phase acceptance test
78
78
 
79
79
  ### Stage 4: Execute
80
80
 
81
- Drive each in-scope story from its red-phase tests to a green, committed state. Execution is the **sequential `/goal` spine**; per story, in sprint order: set the current story (so the PreToolUse hook can find its marker) → `ucg-dev-story` implements the feature and un-skips the story's ATDD tests → run tests/lint/build and **print the raw output** as evidence → (production) `bmad-testarch-test-review` then `bmad-code-review` → check the commit message against the staged diff (`claim_check.py` lists each path it names that the commit does not touch) and soften any claim the diff's own new lines make that no evidence shows → commit at green (one implementation commit per green story; the gate's commits follow it: a test backfill when automate makes one, then the evidence) → **re-run the suite at this cycle's scope on the committed HEAD (a story only advances off a full-scope sweep)** and print it, because a story's new files are untracked until the commit, so a tracked-files conformance gate can only red once they land; a red here means the story is not done and must be remediated and re-committed before it advances. The conductor writes a per-story `/goal`-style condition that encodes the Definition-of-Done and carries the literal "…or stop after N turns" escape clause, and records it in the decision log. A live `/goal` runs only when you start one, on your own condition, because the conductor cannot start `/goal` itself. The Stop hook records a turn count, once per response, which the conductor reads before each story and each re-loop. The printed evidence keeps the run judgeable mid-flight, but **passing the `/goal` condition is not completion**; the authoritative verdict is Stage 5. As the spine advances it overwrites a `run-status.json` heartbeat for pollers. See [`references/execute.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/execute.md).
81
+ Drive each in-scope story from its red-phase tests to a green, committed state. Execution is the **sequential `/goal` spine**; per story, in sprint order: set the current story (so the PreToolUse hook can find its marker) → `ucg-dev-story` implements the feature and un-skips the story's ATDD tests → mark the story's new files intent-to-add (`git add -N`), so a conformance gate scoped to git's tracked files sees them, then run tests/lint/build and **print the raw output** as evidence → (production) `bmad-testarch-test-review` then `bmad-code-review` → check the commit message against the staged diff (`claim_check.py` lists each path it names that the commit does not touch) and soften any claim the diff's own new lines make that no evidence shows → commit at green (one implementation commit per green story; the gate's commits follow it: a test backfill when automate makes one, then the evidence) → **re-run the suite at this cycle's scope on the committed HEAD (a story only advances off a full-scope sweep)** and print it, because a new file no mark reaches (a generated or ignored one, or one made after the last mark) is untracked until the commit, so a tracked-files conformance gate can only red on it once it lands; a red here means the story is not done and must be remediated and re-committed before it advances, except that a red in a case outside the story's changes, whose cause shows inside that test, and that a second sweep at the same commit does not repeat, is logged as flaky and parked on the ledger, with nothing committed. The conductor writes a per-story `/goal`-style condition that encodes the Definition-of-Done and carries the literal "…or stop after N turns" escape clause, and records it in the decision log. A live `/goal` runs only when you start one, on your own condition, because the conductor cannot start `/goal` itself. The Stop hook records a turn count, once per response, which the conductor reads before each story and each re-loop. The printed evidence keeps the run judgeable mid-flight, but **passing the `/goal` condition is not completion**; the authoritative verdict is Stage 5. As the spine advances it overwrites a `run-status.json` heartbeat for pollers. See [`references/execute.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/execute.md).
82
82
 
83
83
  ### Stage 5: Gate
84
84
 
@@ -48,6 +48,8 @@ flowchart TD
48
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.
49
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.
50
50
 
51
+ - **This session does not run the hooks.** Preflight's last arming step proves that the session runs the hooks it wrote, and stops before the launch when it does not. See [Hooks not firing](#hooks-not-firing).
52
+
51
53
  The decision log carries the full blocker list with what each needs to clear. Read it, clear the items, re-run.
52
54
 
53
55
  ## gate_eval reports blocked / escalate on a missing gate-decision.json
@@ -75,12 +77,17 @@ A per-story gate can return `reloop` with a `PASS` gate status when a cap fired
75
77
 
76
78
  ## Hooks not firing
77
79
 
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
+ **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. Or preflight stops before the launch, saying the hooks are in `.claude/settings.local.json` and this session does not run them.
79
81
 
80
82
  **What to check.**
81
83
 
82
84
  - **Older Claude Code.** The hook returns a `deny` decision in the hook JSON and *also* exits 2 with the reason on stderr precisely so older clients that ignore the JSON still block. If neither path fired, the client may not be honoring PreToolUse hooks at all. Update Claude Code.
83
- - **`settings.local.json` not merged.** The hooks are merged into `{project-root}/.claude/settings.local.json` at preflight, and the skill asserts they are active before going unattended. If the file wasn't merged (or the workspace trust dialog wasn't accepted), the hooks aren't loaded. Re-run preflight; verify the two hook entries are present in the resolved settings.
85
+ - **`settings.local.json` not merged.** The hooks are merged into `{project-root}/.claude/settings.local.json` at preflight. Before going unattended, preflight checks the file, then proves this session runs them with one `git commit --dry-run` that the guard must refuse. If the file wasn't merged (or the workspace trust dialog wasn't accepted), the hooks aren't loaded. Re-run preflight; verify the two hook entries are present in the resolved settings.
86
+ - **Hooks written while the session ran, and not loaded.** Preflight writes the hooks while Claude Code runs, and Claude Code's file watcher normally picks that edit up but can miss it. Preflight's probe catches this: its `git commit --dry-run` creates no commit, a guard the session runs refuses it with `Tests-ran guard: refusing` and `current story (unknown)`, and when it is not refused twice, preflight stops. Attended, it asks you to quit Claude Code and resume the conversation with ultracode effort and Auto Mode on, as you launched it, since a resumed session takes the effort and the mode its launch sets, and then to say continue: `claude --continue --effort ultracode --permission-mode auto` in the project resumes the most recent conversation, `claude --resume` with the same two flags lets you pick this one when another in the project is more recent, or reopen it in the desktop app. The resumed session reads the file as it starts. When either setting is off there, preflight names it and asks you to turn it on and say continue. A headless run stops with a RED blocker: invoke it again, since a new session reads the file as it starts. In the session, `/hooks` lists the hooks it loaded.
87
+ - **A setting that keeps the file's hooks from running.** When a resumed or a new session still does not refuse the probe, something other than the file watcher keeps the hooks from running: `disableAllHooks` set in another settings layer or in a `--settings` file, `allowManagedHooksOnly` in managed settings, a `--setting-sources` that leaves out `local`, or `--bare`, which skips hooks. Clear it, check that `/hooks` lists the guard, then invoke the run again.
88
+ - **A story set in Claude Code's environment.** A guard that runs can also let the probe through: with `ULTRACODE_STORY_ID` in the environment Claude Code runs hooks with, naming a story whose tests-ran marker is fresh, and something staged, the guard allows the call, and preflight reads that as a session that does not run the hooks. Unset the variable where you start Claude Code, start it again, then invoke the run again.
89
+ - **The probe refused for another reason.** Any guard reason other than `Tests-ran guard: refusing` with `current story (unknown)` means a guard runs but reads a story or a branch this run did not set: an `ULTRACODE_STORY_ID` in the environment Claude Code runs hooks with, or a guard from an earlier arming still loaded with another implementation-artifacts folder. For the variable, unset it where you start Claude Code, then start Claude Code again; for an earlier arming, quit and start Claude Code again so it loads the file this run wrote. Then invoke the run again.
90
+ - **A refusal from another hook.** A probe result that names another hook's command in brackets and holds no guard reason, such as `PreToolUse:Bash hook error: [<its command>]: <its stderr>`, is that hook's refusal, so the guard did not refuse the call. Check `/hooks` for the guard, as the bullets above say.
84
91
  - **A `customize.toml` override that silently no-ops.** Both hooks read config from env first and fall back to hardcoded defaults (`main`/`master`, `25`, `ultracode/epic-`). A `protected_branches` or turn-budget override in `customize.toml` only reaches the hook if preflight injected it into the hook env (`ULTRACODE_PROTECTED_BRANCHES`, etc.). If your custom protected branch isn't being guarded, the override didn't reach the enforcement layer. Confirm preflight passed it through.
85
92
 
86
93
  ## Every tool call is refused
@@ -95,7 +102,7 @@ A per-story gate can return `reloop` with a `PASS` gate status when a cap fired
95
102
  - **No Python `uv` can use.** `uv` cannot start a Python the script's header allows.
96
103
  - **The guard ran past its timeout.** Claude Code's default for a command hook is 600 seconds; the message then says `timed out`.
97
104
 
98
- A refusal the guard makes itself reads differently: it starts with the guard's own reason (`Commit/push guard: …`, `Protected-branch guard: …`, `UltraCode-Goal guard: …`) and names what to fix. That is the guard deciding, not failing.
105
+ A refusal the guard makes itself reads differently: in place of `[<command>]: failed; blocking`, it carries the guard's own reason (`Commit/push guard: …`, `Protected-branch guard: …`, `UltraCode-Goal guard: …`) and names what to fix. That is the guard deciding, not failing.
99
106
 
100
107
  **What you do.** Fix it from outside the session, since the session cannot run a tool:
101
108
 
@@ -21,7 +21,7 @@ UltraCode Goal answers each shortcut with a layer the model cannot override, exc
21
21
 
22
22
  **1. Deterministic gate truth.** Completion is decided by `scripts/gate_eval.py`, which reads TEA's `gate-decision.json` and maps its gate status to a routing verdict: `PASS`/`WAIVED` advance, `CONCERNS` defers, `FAIL` re-loops, `NOT_EVALUATED` escalates. The script never re-derives TEA's thresholds and never consults the transcript; it reads the artifact as given. The model produces evidence; the script reads the verdict. They are different things on purpose. See the [gate model](./gate-model.md).
23
23
 
24
- **2. Hooks as invariants.** The invariants that must hold (no commit on a protected branch, no commit before a story's tests have actually run green, and five more covering marker freshness, an empty staged index, un-skipped acceptance tests, and two for Cross-Session Recall) live in a **PreToolUse** hook, not in memory. The hook inspects each `git commit`/`git push`, and every other tool call while a run latch is present, and denies the call when any of them is violated. It is merged into `.claude/settings.local.json` at preflight and asserted active before the run goes unattended. A denied commit is enforcement; a remembered rule is not. See [architecture](./architecture.md).
24
+ **2. Hooks as invariants.** The invariants that must hold (no commit on a protected branch, no commit before a story's tests have actually run green, and five more covering marker freshness, an empty staged index, un-skipped acceptance tests, and two for Cross-Session Recall) live in a **PreToolUse** hook, not in memory. The hook inspects each `git commit`/`git push`, and every other tool call while a run latch is present, and denies the call when any of them is violated. It is merged into `.claude/settings.local.json` at preflight, and preflight proves that the running session runs it before the run goes unattended. A denied commit is enforcement; a remembered rule is not. See [architecture](./architecture.md).
25
25
 
26
26
  **3. Budget enforcement.** This is the one layer that rests on the conductor following a rule. A **Stop** hook tracks turns against `max_turns_per_story` and writes an escalation marker when it is breached, but it never blocks, and it counts once per response, so re-loops inside one response do not move it. The conductor reads that count before each story and each re-loop, and the gate's re-loop budget turns a `reloop` that would exceed it into an `escalate`. A story that passes its gate after an overrun is not escalated: the gate decides completion, and the overrun is logged as a sizing note. A `/goal` condition's literal "…or stop after N turns" clause binds only when an operator starts a `/goal` (the conductor cannot start one itself), and for `drive_epic.py` spawns a `--session-timeout` wall clock is the backstop. See [how it works](./how-it-works.md).
27
27
 
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": "5.0.0",
4
+ "version": "7.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",
@@ -47,7 +47,19 @@ recomputes the readiness verdict. Each verdict and remediation lands in
47
47
  for this Epic when one exists (appending a session entry), otherwise create
48
48
  `epic-<id>-<UTC yyyymmddThhmmssZ>` for this standalone check. That resolved path is
49
49
  what the Headless `decision_log` key carries, so two invocations over the same Epic
50
- cannot scatter their verdicts across two files.
50
+ cannot scatter their verdicts across two files. Append to the log with Write/Edit,
51
+ never a Bash heredoc: a heredoc puts the log's prose into a Bash command string, and the
52
+ PreToolUse guard's git gates read that string as commands
53
+ (`{ucg-root}/references/execute.md`, step 4, gives the reason). Once the log is too large
54
+ to Read affordably, do not Read it, since both file tools refuse a file this session has
55
+ not Read. Write the entry instead to a new file beside the log,
56
+ `<run folder>/dlog-slice-formalize-<n>.md`, where `<run folder>` is the resolved folder
57
+ above in full and `<n>` is one past the highest number a `dlog-slice-formalize-*.md` in
58
+ it already carries (`1` when there is none), so the name is new for every append. Then
59
+ append it in one Bash call, with both paths in full:
60
+ `cat "<run folder>/dlog-slice-formalize-<n>.md" >> "<run folder>/.decision-log.md"`. Keep
61
+ the slice rather than deleting it: it is the only copy of the entry if the append is
62
+ interrupted.
51
63
 
52
64
  ## On Activation
53
65
 
@@ -165,7 +177,8 @@ its `detail`: record it as a non-remediable blocker naming the kind and route to
165
177
  kind blocks loudly instead of being guessed at, and the halt catch-all below then covers
166
178
  the never-remediated case as well as the remediated-but-unfixed one.
167
179
 
168
- Log each remediation to `.decision-log.md` as you apply it. Never
180
+ Log each remediation to `.decision-log.md` as you apply it, appended the way Conventions
181
+ says. Never
169
182
  auto-remediate a `judgment_candidate`, and never auto-remediate a
170
183
  `remediable: false` mechanical gap (an unreadable artifact cannot be fixed from its
171
184
  own unreadable content).
@@ -226,7 +239,7 @@ one-line evidence fields:
226
239
  "candidate": "<only when this answers a seeded judgment candidate: its id, copied as given>"}],
227
240
  "concerns": [{"source": "<artifact path:line>", "note": "<cosmetic / non-blocking gap, one line>",
228
241
  "candidate": "<only when this answers a seeded judgment candidate: its id, copied as given>"}],
229
- "advisories_checked": [{"sig": "<advisory id>", "status": "recurred|not-observed|unknown"}]}
242
+ "advisories_checked": [{"sig": "<the recalled record's id, copied as given>", "status": "recurred|not-observed|unknown"}]}
230
243
  ```
231
244
 
232
245
  **Mint ids before mapping, and apply the operator's closes.** Hand the returned scan
@@ -38,7 +38,9 @@ more than a note-taker.
38
38
  `{project-root}/_bmad-output/ultracode-goal/<run folder>/.decision-log.md` — the module's
39
39
  default runs root, which no `customize.toml` scalar carries. Write to the folder whose
40
40
  Epic the enumerated artifacts belong to; ask the operator when more than one could be it,
41
- and when none exists append nothing rather than create a stray log.
41
+ and when none exists append nothing rather than create a stray log. Append to it with
42
+ Write/Edit, never a Bash heredoc, as section 3 says, which also covers a log too large to
43
+ Read.
42
44
 
43
45
  ## On Activation
44
46
 
@@ -78,8 +80,9 @@ and anything not written down is not a pending decision this surface can honor.
78
80
  genuinely still pending: the arming step deliberately does not purge `escalation-*.json`,
79
81
  so a decision an operator chose to leave open survives to this pass.
80
82
  2. **The preflight RED sidecar** — `{workflow.implementation_artifacts}/.preflight-reds.json`,
81
- shape `{"reds": [...]}`. **One** file holds every still-pending preflight RED. There is
82
- no second RED sidecar and no per-story one: a per-story or per-run RED file would carry
83
+ shape `{"reds": [...]}`. **One** file holds the REDs the last preflight left pending, from
84
+ whichever Epic ran it (section 2 says what that means for an entry no RED carries). There
85
+ is no second RED sidecar and no per-story one: a per-story or per-run RED file would carry
83
86
  an id that changed between scans, and an id that changes cannot carry an answer forward.
84
87
  3. **The deferred-work ledger** — `{workflow.deferred_work_path}`, restricted to its
85
88
  `decision:` rows. Those are the rows whose `source` column reads `decision` (as opposed
@@ -114,7 +117,8 @@ For a sidecar the three arguments are its own `kind`, `source` and `decision_nee
114
117
  fields, each passed verbatim: `<artifact path>` is the sidecar's `source` field, its
115
118
  `:line` suffix and all (the id layer strips it), never the path of the sidecar file
116
119
  itself. The resume also reads a close keyed by the sidecar file's own path as closed,
117
- since earlier passes keyed some that way, but never mint a new id from that path.
120
+ since earlier passes keyed some that way, but never key an answer by an id minted from
121
+ that path: section 2 mints those ids only to recognize an entry already recorded.
118
122
 
119
123
  It prints the id and touches nothing. **A ledger `decision:` row is keyed by the same
120
124
  call** — kind `decision`, the ledger path, and the row's reason — because the row's own
@@ -146,24 +150,56 @@ Re-asking a question the operator already **resolved** is the exact failure this
146
150
  exists to remove.
147
151
 
148
152
  An entry recorded with `action` `defer` is the opposite case: it is a parked question, not
149
- an answered one. Present it again, and replace its entry in place when the operator decides
150
- it, carrying its answer forward (section 3). Suppressing a deferred item would deadlock
151
- the run outright: `defer` clears nothing,
152
- so the next preflight still blocks on that RED (`{ucg-root}/references/preflight.md`,
153
- step 3, drops only the ids whose `action` is `close`), while this surface, the only one that
154
- can answer it, would never ask again. The scan blocks forever on a question the operator is
155
- no longer offered.
153
+ an answered one. Present it again while an item this pass enumerated carries its `id`, and
154
+ replace its entry in place when the operator decides it, carrying its answer forward
155
+ (section 3). Suppressing a deferred item would deadlock the run outright: `defer` clears
156
+ nothing, so the next preflight still blocks on that RED
157
+ (`{ucg-root}/references/preflight.md`, step 3, drops only the ids whose `action` is
158
+ `close`), while this surface, the only one that can answer it, would never ask again. The
159
+ scan blocks forever on a question the operator is no longer offered.
156
160
 
157
161
  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.
162
+ pending as well while an item this pass enumerated carries its `id`. An earlier version of
163
+ this surface wrote some entries that way, and preflight drops none of their ids, so that
164
+ item's question stays open. Present it again, as you present a deferred one.
165
+
166
+ **An item carries an entry's `id` only on an exact match, as written.** A RED carries the
167
+ `id` on its `reds` entry, and a ledger `decision:` row the id the id layer printed for it.
168
+ An escalation sidecar carries the id the id layer printed from its own fields, and one
169
+ more for each spelling of the sidecar file's own path the resume reads a close by
170
+ (`_sidecar_ids` in `{ucg-root}/scripts/preflight_check.py`): its path relative to
171
+ `{project-root}`, its absolute path, that absolute path with its folder's symlinks
172
+ resolved, and the resolved path relative to `{project-root}`, each written with forward
173
+ slashes and, on Windows, with backslashes too. Ask the id layer for each of those with the
174
+ sidecar's own `kind` and `decision_needed`. Mint them only to recognize an entry already
175
+ recorded, never to key an answer: an entry keyed by any of them belongs to that sidecar's
176
+ item.
161
177
 
162
178
  When an item you present already has an entry, show its `answer`, and each earlier answer
163
179
  its `history` holds (section 3), beside the decision needed. Such an answer can hold the
164
180
  operator's whole ruling: they decide on the record as it stands, and may find it already
165
181
  answers the question.
166
182
 
183
+ **An entry no enumerated item carries is orphaned, not pending.** That is an entry whose
184
+ `action` is anything but `close` and whose `id` no item of this pass carries: none of the
185
+ three sources holds its question at this pass, so there is no item to present it with.
186
+ List the orphaned entries after the pending items, apart from them, each with its `id`,
187
+ its `answer` and each earlier answer its `history` holds, and ask nothing about them; the
188
+ record keeps each one as it stands. Say beside that list that a later preflight can raise
189
+ an orphaned entry again and block on it. `.preflight-reds.json` is one project-wide file
190
+ that each preflight replaces, so it holds only the REDs of the last preflight, from
191
+ whichever Epic ran it: a RED one Epic's preflight raised can be gone from it after another
192
+ Epic's preflight, while that first Epic's next preflight can raise it again. An orphaned
193
+ entry whose `id` a later RED, sidecar or ledger row carries is pending again at that pass,
194
+ which asks it.
195
+
196
+ **When a source could not be read in full, call nothing orphaned.** That is an unreadable
197
+ `.preflight-reds.json`, an escalation sidecar that cannot be read or whose fields no id can
198
+ be minted from, or a ledger on disk that cannot be read, or is malformed or a bullet list,
199
+ so it yields no rows here. In that case present every entry that is not a `close` as
200
+ pending, with its `id`, its `answer` and its `history`, since an id that source would carry
201
+ cannot be ruled out.
202
+
167
203
  ## 3. Record the answer, then apply its disposition
168
204
 
169
205
  Every answer lands in `{workflow.implementation_artifacts}/.decisions.json`:
@@ -296,18 +332,39 @@ The two dispositions are genuinely different things, not two names for one:
296
332
  anything**. The artifact stays exactly where it is, the item stays pending, and the next
297
333
  preflight still blocks on it.
298
334
 
299
- Record each answer and its disposition in `.decision-log.md` as you apply it.
335
+ Record each answer and its disposition in `.decision-log.md` as you apply it, with
336
+ Write/Edit and never a Bash heredoc. A heredoc puts decision prose (commit and push verbs,
337
+ backticked names, apostrophes) into a Bash command string, and the PreToolUse guard's git
338
+ gates read that string as commands (`{ucg-root}/references/execute.md`, step 4, gives the
339
+ reason). Once the log is too large to Read affordably, do not Read it, since both file
340
+ tools refuse a file this session has not Read. Write the entry instead to a new file beside
341
+ the log, `{project-root}/_bmad-output/ultracode-goal/<run folder>/dlog-slice-resolve-<n>.md`,
342
+ with `<n>` one past the highest number a `dlog-slice-resolve-*.md` in that folder already
343
+ carries (`1` when there is none): the name has to be new for every append, or Write finds
344
+ the file on disk and asks for the Read again. Then append it in one Bash call, with both
345
+ paths in full:
346
+ `cat "{project-root}/_bmad-output/ultracode-goal/<run folder>/dlog-slice-resolve-<n>.md" >> "{project-root}/_bmad-output/ultracode-goal/<run folder>/.decision-log.md"`.
347
+ Keep the slice rather than deleting it: it is the only copy of the entry if the append is
348
+ interrupted. This holds for every entry the pass writes, the coupled-stories entry above
349
+ included.
300
350
 
301
351
  ## 4. Hand control back to the existing resume
302
352
 
303
353
  `/ucg-resolve` defines no resume of its own. Close the pass by stating what closed, what is
304
354
  still pending, and that anything still pending re-blocks at the next preflight. Name every
305
355
  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
356
+ the operator sees what the record held before this pass. List the orphaned entries apart
357
+ from both, by `id`, and say that a later preflight can raise any of them again and block
358
+ on it, and that the pass after that preflight asks it. **Hand back
307
359
  only when the pass closed at least one item, or when the operator asks for the resume**: a
308
360
  pass that deferred everything hands into a run blocked on the identical items, and an empty
309
361
  enumeration means the run stopped for a non-decision reason — say so, point at the read-only
310
- `/ucg-status`, and hand nothing back.
362
+ `/ucg-status`, and hand nothing back. A pass that found only orphaned entries is not an
363
+ empty enumeration, so do not say the run stopped for a non-decision reason: the run can
364
+ have stopped on a RED that another Epic's preflight has since dropped from
365
+ `.preflight-reds.json`, and its next preflight raises that RED again. Such a pass closed
366
+ nothing, so point at the read-only `/ucg-status`, as for an empty enumeration, and hand
367
+ back only when the operator asks for the resume.
311
368
 
312
369
  Otherwise hand back to the resume the module already has, which **routes by the last stage
313
370
  the blocked run reached**, not by story. Which branch applies is not a detail this surface
@@ -61,7 +61,7 @@ These exist because the documented mechanics make the intuitive shortcut wrong.
61
61
  | 6 | Finalize | Auto Memory capture, optional retrospective, decision-log audit, report | `references/finalize.md` |
62
62
  | 7 | Health Check | Terminal self-improvement audit — Finalize's close-out loads it; capture real workflow friction | `references/health-check.md` |
63
63
 
64
- Run the stages in order; each routes by the testable conditions stated in its file. The decision log is canonical memory — record scope, the preflight verdict, every gate outcome, and every deferral as you go.
64
+ Run the stages in order; each routes by the testable conditions stated in its file. The decision log is canonical memory: record scope, the preflight verdict, every gate outcome, and every deferral as you go. **Append it with Write/Edit, never a Bash heredoc**, from Stage 1 on: a heredoc puts the log's prose into a Bash command string, and the guard's git gates read that string as commands (`references/execute.md`, step 4, gives the reason). Once the log is too large to Read affordably, do not Read it: Write the entry to a new file beside the log, in the run folder that holds it, `<log folder>/dlog-slice-<label>-<n>.md`, where `<log folder>` is that folder's full path, `<label>` is the story's id for an entry about a story and `stage<k>` for one a stage writes outside a story (`stage1` for Ingest & Scope), and `<n>` is one past the highest number a `dlog-slice-<label>-*.md` there already carries, so the name is new for every append. Then append it in one Bash call, `cat "<log folder>/dlog-slice-<label>-<n>.md" >> "<log folder>/.decision-log.md"`, and keep the slice.
65
65
 
66
66
  ## Headless
67
67