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.
- package/.claude-plugin/marketplace.json +1 -1
- package/docs/_internal/STABILITY.md +3 -3
- package/docs/architecture.md +2 -2
- package/docs/cross-session-recall.md +1 -1
- package/docs/getting-started.md +1 -1
- package/docs/how-it-works.md +2 -2
- package/docs/troubleshooting.md +10 -3
- package/docs/why-ultracode-goal.md +1 -1
- package/package.json +1 -1
- package/skills/ucg-formalize/SKILL.md +16 -3
- package/skills/ucg-resolve/SKILL.md +74 -17
- package/skills/ultracode-goal/SKILL.md +1 -1
- package/skills/ultracode-goal/references/execute.md +13 -9
- package/skills/ultracode-goal/references/finalize.md +5 -3
- package/skills/ultracode-goal/references/gate.md +6 -6
- package/skills/ultracode-goal/references/preflight.md +11 -5
- package/skills/ultracode-goal/scripts/claim_check.py +117 -16
- package/skills/ultracode-goal/scripts/drive_epic.py +33 -10
- package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +104 -15
- package/skills/ultracode-goal/scripts/lib/mem_common.py +30 -0
- package/skills/ultracode-goal/scripts/mem_observation.py +85 -10
- package/skills/ultracode-goal/scripts/mutate_check.py +22 -1
- package/skills/ultracode-goal/scripts/preflight_check.py +4 -1
|
@@ -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": "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
|
|
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:**
|
|
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 `
|
|
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
|
|
package/docs/architecture.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
package/docs/getting-started.md
CHANGED
|
@@ -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>`
|
|
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
|
|
package/docs/how-it-works.md
CHANGED
|
@@ -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` (
|
|
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
|
|
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
|
|
package/docs/troubleshooting.md
CHANGED
|
@@ -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,
|
|
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
|
|
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
|
|
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": "
|
|
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
|
|
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": "<
|
|
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
|
|
82
|
-
|
|
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
|
|
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
|
|
150
|
-
|
|
151
|
-
the run outright: `defer` clears
|
|
152
|
-
so the next preflight still blocks on that RED
|
|
153
|
-
step 3, drops only the ids whose `action` is
|
|
154
|
-
can answer it, would never ask again. The
|
|
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
|
|
159
|
-
preflight drops none of their ids, so
|
|
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.
|
|
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
|
|
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
|
|