bmad-module-ultracode-goal 3.2.0 → 4.1.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": "3.2.0",
22
+ "version": "4.1.0",
23
23
  "author": {
24
24
  "name": "Armel"
25
25
  },
package/README.md CHANGED
@@ -62,7 +62,7 @@ The `gate_status` comes straight from TEA's artifact: `gate_eval.py` never re-de
62
62
 
63
63
  ## Install
64
64
 
65
- Requires [Claude Code](https://claude.com/product/claude-code) >= 2.1.154 (the runtime UCG conducts), [Node.js](https://nodejs.org/) >= 22, [Python](https://www.python.org/) >= 3.11, [uv](https://docs.astral.sh/uv/), plus `git` and `gh` on PATH. The project needs BMAD Method 6 with TEA 1.27.x: TEA 2.0 and later, and BMAD 7, are not supported yet.
65
+ Requires [Claude Code](https://claude.com/product/claude-code) >= 2.1.295 (the runtime UCG conducts), [Node.js](https://nodejs.org/) >= 22, [Python](https://www.python.org/) >= 3.11, [uv](https://docs.astral.sh/uv/), plus `git` and `gh` on PATH. The project needs BMAD Method 6 with TEA 1.27.x: TEA 2.0 and later, and BMAD 7, are not supported yet.
66
66
 
67
67
  **Tested with:** on 2026-10-16 a two-story Epic reached its Definition-of-Done with the versions below, under the `--light` profile (TEA test-design and the trace gate; the production gate set was not exercised). They are the versions that run used, not minimums.
68
68
 
@@ -76,9 +76,9 @@ Requires [Claude Code](https://claude.com/product/claude-code) >= 2.1.154 (the r
76
76
  npx bmad-module-ultracode-goal install
77
77
  ```
78
78
 
79
- You'll be prompted for a project name and whether to install the learning material; the skill installs for Claude Code. UCG is also available through the Claude plugin marketplace. See [Getting Started](./docs/getting-started.md) for that path.
79
+ You'll be prompted for a project name and whether to install the learning material; the skill installs for Claude Code. UCG is also available through the Claude plugin marketplace. See [Getting Started](https://armelhbobdad.github.io/bmad-module-ultracode-goal/getting-started/#install) for that path.
80
80
 
81
- > **Hook security:** UCG installs `PreToolUse`/`Stop` hooks into your machine-local, gitignored `.claude/settings.local.json` at preflight, never into a committed file. They run zero-dependency Python scripts shipped in the skill. Claude Code treats that file as protected, so take a new Epic through preflight in an attended session (see [Getting Started](./docs/getting-started.md#hook-security)). See [SECURITY.md](SECURITY.md) for exactly what they execute and how to remove them.
81
+ > **Hook security:** UCG installs `PreToolUse`/`Stop` hooks into your machine-local, gitignored `.claude/settings.local.json` at preflight, never into a committed file. They run zero-dependency Python scripts shipped in the skill. Claude Code treats that file as protected, so take a new Epic through preflight in an attended session (see [Getting Started](https://armelhbobdad.github.io/bmad-module-ultracode-goal/getting-started/#hook-security)). See [SECURITY.md](SECURITY.md) for exactly what they execute and how to remove them.
82
82
 
83
83
  ## Quick Start
84
84
 
@@ -91,7 +91,7 @@ Invoke the skill in natural language: "run this epic autonomously," "execute thi
91
91
  - `--retro`: run the close-out retrospective (interactive runs offer it anyway; headless runs it only when this flag is passed).
92
92
  - `--max-stories N`: drive at most **N** stories in this invocation, then finish normally through the report and the terminal JSON. It bounds the work, not the scope: the Epic's in-scope set is untouched, so the next invocation resumes where this one stopped. `scripts/drive_epic.py` uses it to run one story per process, so a long Epic's context dies with each story.
93
93
 
94
- See [How It Works](./docs/how-it-works.md) for the full six-stage walkthrough, routing conditions, and the headless contract.
94
+ See [How It Works](https://armelhbobdad.github.io/bmad-module-ultracode-goal/how-it-works/) for the full six-stage walkthrough, routing conditions, and the headless contract.
95
95
 
96
96
  ## How UCG Compares
97
97
 
@@ -133,23 +133,23 @@ The JSON it prints is the same object UCG routes on: `verdict`, `gate_status`, a
133
133
 
134
134
  The docs are organized into three buckets: **Why** (start here), **Try** (do stuff), and **Reference** (look things up):
135
135
 
136
- **Why**: **[Why UltraCode Goal](./docs/why-ultracode-goal.md)**: the problem, the three enforcement layers, and when not to use it.
136
+ **Why**: **[Why UltraCode Goal](https://armelhbobdad.github.io/bmad-module-ultracode-goal/why-ultracode-goal/)**: the problem, the three enforcement layers, and when not to use it.
137
137
 
138
138
  **Try**
139
139
 
140
- - **[Getting Started](./docs/getting-started.md)**: install, prerequisites, the flags, and your first autonomous run.
141
- - **[How It Works](./docs/how-it-works.md)**: the six stages, their routing conditions, and the headless five-key emit.
140
+ - **[Getting Started](https://armelhbobdad.github.io/bmad-module-ultracode-goal/getting-started/)**: install, prerequisites, the flags, and your first autonomous run.
141
+ - **[How It Works](https://armelhbobdad.github.io/bmad-module-ultracode-goal/how-it-works/)**: the six stages, their routing conditions, and the headless five-key emit.
142
142
 
143
143
  **Reference**
144
144
 
145
- - **[Architecture](./docs/architecture.md)**: the conductor model, enforcement layers in depth, and `customize.toml` resolution.
146
- - **[Gate Model](./docs/gate-model.md)**: how `gate_eval.py` maps `gate_status` to a verdict, and the production AND-signals.
147
- - **[Health Check](./docs/health-check.md)**: the terminal self-improvement loop: what it sends, privacy, and how to disable it.
148
- - **[Cross-Session Recall](./docs/cross-session-recall.md)**: the optional run history in a local store UCG owns: what a run reads and writes, the trust model, and how to enable it.
149
- - **[Knowledge-Graph Refresh](./docs/knowledge-graph-refresh.md)**: the optional graphify integration: preconditions, what it sends where, and what it never touches.
150
- - **[Operating Tips](./docs/operating-tips.md)**: field notes from real drives: the driver's stop reasons, sequencing by row order, and the verification traps.
151
- - **[Troubleshooting](./docs/troubleshooting.md)**: real failure modes and their remediations.
152
- - **[UCG vs bmad-loop](./docs/comparison.md)**: a side-by-side comparison with bmad-code-org's bmad-loop orchestrator.
145
+ - **[Architecture](https://armelhbobdad.github.io/bmad-module-ultracode-goal/architecture/)**: the conductor model, enforcement layers in depth, and `customize.toml` resolution.
146
+ - **[Gate Model](https://armelhbobdad.github.io/bmad-module-ultracode-goal/gate-model/)**: how `gate_eval.py` maps `gate_status` to a verdict, and the production AND-signals.
147
+ - **[Health Check](https://armelhbobdad.github.io/bmad-module-ultracode-goal/health-check/)**: the terminal self-improvement loop: what it sends, privacy, and how to disable it.
148
+ - **[Cross-Session Recall](https://armelhbobdad.github.io/bmad-module-ultracode-goal/cross-session-recall/)**: the optional run history in a local store UCG owns: what a run reads and writes, the trust model, and how to enable it.
149
+ - **[Knowledge-Graph Refresh](https://armelhbobdad.github.io/bmad-module-ultracode-goal/knowledge-graph-refresh/)**: the optional graphify integration: preconditions, what it sends where, and what it never touches.
150
+ - **[Operating Tips](https://armelhbobdad.github.io/bmad-module-ultracode-goal/operating-tips/)**: field notes from real drives: the driver's stop reasons, sequencing by row order, and the verification traps.
151
+ - **[Troubleshooting](https://armelhbobdad.github.io/bmad-module-ultracode-goal/troubleshooting/)**: real failure modes and their remediations.
152
+ - **[UCG vs bmad-loop](https://armelhbobdad.github.io/bmad-module-ultracode-goal/comparison/)**: a side-by-side comparison with bmad-code-org's bmad-loop orchestrator.
153
153
 
154
154
  Every run that reaches Finalize ends with a self-improvement check that can file a deduplicated GitHub issue with your approval, so **please let runs finish through Finalize**, or [open an issue](https://github.com/armelhbobdad/bmad-module-ultracode-goal/issues/new/choose) directly. If UCG shipped an epic while you slept, a ⭐ helps others find it.
155
155
 
@@ -1,11 +1,11 @@
1
1
  ---
2
2
  title: Stability and Public Contract
3
- description: "The 3.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 4.x stability posture: which CLI, config, JSON, and gate surfaces are the supported public contract, what a major costs, and everything that is @internal and free to change."
4
4
  ---
5
5
 
6
- > **Status:** 3.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:** 4.x. The surfaces below are the public contract. Per [Semantic Versioning 2.0.0](https://semver.org/), a breaking change to any of them requires a MAJOR bump; everything marked `@internal` may change in any release. This document is what a consumer pins against.
7
7
 
8
- This is the stability posture for `bmad-module-ultracode-goal` at `3.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 `4.x`. It enumerates the surfaces a downstream consumer or automator may reasonably depend on, versus everything else, which is `@internal`.
9
9
 
10
10
  ## Public contract
11
11
 
@@ -58,6 +58,8 @@ skills/ultracode-goal/
58
58
  │ ├── gate_eval.py # gate status -> verdict (the completion authority)
59
59
  │ ├── operator_owed.py # is a gate FAIL owed only operator-evidence ACs' records? (fail-closed)
60
60
  │ ├── mutate_check.py # mutation harness: attributable-red proof for the story's guards
61
+ │ ├── probe_servers.py # which URLs a test runner may reuse already answer, from which folder; stops a server the run left up
62
+ │ ├── link_worktree_deps.py # links the main tree's dependency folders into the gate worktree
61
63
  │ ├── gate_trail.py # per-story evidence trail (gate-trail.md) at finalize
62
64
  │ ├── formalize_check.py # readiness kernel behind the /ucg-formalize gate
63
65
  │ ├── status_render.py # read-side render behind /ucg-status
@@ -128,4 +130,4 @@ flowchart LR
128
130
 
129
131
  ## Why the hooks live in settings.local.json
130
132
 
131
- 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. 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) 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).
@@ -22,10 +22,10 @@ The store is a folder you name with the `cross_session_recall_store` key.
22
22
  - **No default.** The key ships as `""`. An empty or blank value, an unresolved `{...}` token, a literal `$VAR` or `%VAR%` and a relative path all count as unset.
23
23
  - **Accepted values.** A `~` path, expanded like `health_check_seen_cache`, such as `~/.ultracode-goal/recall`. An absolute path or a `{project-root}` path works too.
24
24
  - **Layout.** Each run gets one file, `<store>/<fingerprint-dir>/runs/<run_id>.jsonl`, holding one JSON line. The file is created once and never rewritten. `<fingerprint-dir>` comes from this repo's fingerprint (its origin and root commit), in a form that is legal on Windows; a repo with no remote gets `local-<hex>`.
25
- - **Per machine.** Another developer or a CI runner never sees this machine's records. Worktrees and clones of one repo on this machine share the same fingerprint, so they read each other's records. A shared store is a follow-up, tracked in [#154](https://github.com/armelhbobdad/bmad-module-ultracode-goal/issues/154).
25
+ - **Per machine.** Another developer or a CI runner never sees this machine's records. Worktrees and clones of one repo on this machine share the same fingerprint, so they read each other's records. History stays on the machine that wrote it: a store shared through the repository is not planned for now, and [#154](https://github.com/armelhbobdad/bmad-module-ultracode-goal/issues/154) records what one would have to get right.
26
26
  - **It ignores itself.** When the scripts create the store folder, they write a `.gitignore` holding `*` inside it, so a store inside your workspace leaves `git status` clean. A folder that already existed gets no `.gitignore`.
27
27
  - **Give it a folder of its own.** While a run is active, the guard denies every tool call that names the store. A store set to your workspace, to a folder above it, or to a folder that holds the implementation artifacts makes nearly every command there name the store, so they are denied. [SECURITY.md](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/SECURITY.md) has the detail.
28
- - **Growth.** The store has no pruning yet. Each run, so each `drive_epic` spawn, adds one small file, and Ingest reads them all. The filter's 120-day horizon hides stale records at read time, except records holding a root cause that two or more runs recorded. Pruning is a follow-up, most naturally with #154.
28
+ - **Growth.** The store has no pruning yet. Each run, so each `drive_epic` spawn, adds one small file, and Ingest reads them all. The filter's 120-day horizon hides stale records at read time, except records holding a root cause that two or more runs recorded.
29
29
 
30
30
  ## Turning it on
31
31
 
@@ -183,7 +183,7 @@ A claude-mem call, a call that names the store, or a call that would change the
183
183
  Recall is deliberately bounded. Treat these as the residuals you are signing up for:
184
184
 
185
185
  - **A factual advisory still informs reasoning.** Sanitized advisories carry no instruction-shaped, stale, or foreign content and never reach the gate, but a well-formed factual advisory can still inform the model's reasoning. That is the feature, bounded; it is not a side channel into the verdict.
186
- - **The store is per machine.** Recall across Epics holds on one machine only, until [#154](https://github.com/armelhbobdad/bmad-module-ultracode-goal/issues/154).
186
+ - **The store is per machine.** Recall across Epics holds on one machine only. A shared store is not planned for now, so another machine, such as a teammate's or a CI runner, never sees this machine's runs.
187
187
  - **The store folder follows the fingerprint.** If a repo with no remote gains one, or you work from a shallow clone, new records go to another folder and the earlier ones stop being read.
188
188
  - **A record file is plain JSON.** Anyone who can write the store folder can edit one. The reader treats every record as untrusted data and defangs it, but it cannot tell an edited record from a real one.
189
189
  - **Redaction is high-precision, not complete.** Secret redaction is pattern matching tuned for precision; it is not a complete data-loss-prevention layer.
@@ -14,7 +14,7 @@ UltraCode Goal conducts BMAD and TEA skills and runs deterministic Python under
14
14
 
15
15
  | Tool | Used for | Minimum | Tested on | Install |
16
16
  | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | -------------- | --------------------------------------------------------------------------- |
17
- | Claude Code | **The runtime: non-negotiable.** UCG composes Auto Mode, Auto Memory, and runtime hooks, which only exist in Claude Code, and writes each story's Definition-of-Done as a `/goal`-style condition; the autonomous run cannot execute anywhere else. Preflight refuses to launch below the minimum | 2.1.154 | 2.1.301 | <https://claude.com/product/claude-code> |
17
+ | Claude Code | **The runtime: non-negotiable.** UCG composes Auto Mode, Auto Memory, and runtime hooks, which only exist in Claude Code, and writes each story's Definition-of-Done as a `/goal`-style condition; the autonomous run cannot execute anywhere else. Preflight refuses to launch below the minimum | 2.1.295 | 2.1.301 | <https://claude.com/product/claude-code> |
18
18
  | Node.js | Installation, `npx` commands | 22 | 22, 24 | <https://nodejs.org> |
19
19
  | Python | The deterministic gate, preflight, and hook scripts (run via `uv`) | 3.11 | 3.11, 3.12 | <https://www.python.org> |
20
20
  | `uv` (Python package runner) | Running the module's Python scripts with automatic dependency management | none | 0.13.1 | <https://docs.astral.sh/uv/getting-started/installation/> |
@@ -89,6 +89,6 @@ Useful flags: `--limit N` caps how many sessions it spawns, retries included, `-
89
89
 
90
90
  ## Hook security
91
91
 
92
- At preflight the skill auto-merges its **PreToolUse** guard and **Stop** budget hook into `.claude/settings.local.json`, a machine-local, gitignored file, honored after the workspace trust dialog. These hooks are the enforcement layer that blocks a commit on a protected branch and records each story's turn count; they are not shared into the repo. Because they execute on your machine, review what gets merged: see [SECURITY.md](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/SECURITY.md) for the hook-security model and what to check before granting trust.
92
+ At preflight the skill auto-merges its **PreToolUse** guard and **Stop** budget hook into `.claude/settings.local.json`, a machine-local, gitignored file, honored after the workspace trust dialog. These hooks are the enforcement layer that blocks a commit on a protected branch and records each story's turn count; they are not shared into the repo. The guard's entry carries `"onFailure": "block"`, so a guard that cannot run (no `uv` on `PATH`, say) makes Claude Code refuse the tool call instead of letting it through unchecked; if every call is then refused, see [Troubleshooting](./troubleshooting.md#every-tool-call-is-refused). Because they execute on your machine, review what gets merged: see [SECURITY.md](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/SECURITY.md) for the hook-security model and what to check before granting trust.
93
93
 
94
- **Take a new Epic through preflight attended.** The same write adds allow rules built from `allowlist_commands`, and Claude Code treats `.claude/settings.local.json` as a protected file. A headless session cannot approve that write: under Auto Mode, which the run requires, the permission classifier may refuse it (or the calls after it) as self-modification, and under `drive_epic.py`'s default `acceptEdits` mode the write prompts with nobody there to answer. Either way the run stops at arming. So run the first invocation of a new Epic attended, in Auto Mode, through the launch briefing and on to at least one story's gate verdict; if a settings write is refused, approve it under `/permissions` (on its Recently denied tab) or apply it yourself, as the decision log describes. From then on, a session that resumes the Epic routes into Execute and only re-checks the hooks, so `-H` and `drive_epic.py` can take over.
94
+ **Take a new Epic through preflight attended.** The same write adds allow rules built from `allowlist_commands`, and Claude Code treats `.claude/settings.local.json` as a protected file. A headless session may be refused that write, and then nobody is there to approve it: under Auto Mode, which the run requires, the permission classifier may refuse it (or the calls after it) as self-modification, and under `drive_epic.py`'s default `acceptEdits` mode the write needs an approval nobody is there to give. Only `bypassPermissions` lets it land unreviewed. A refused write stops the run at arming. So run the first invocation of a new Epic attended, in Auto Mode, through the launch briefing and on to at least one story's gate verdict; if a settings write is refused, approve it under `/permissions` (on its Recently denied tab) or apply it yourself, as the decision log describes. From then on, a session that resumes the Epic routes into Execute and only re-checks the hooks, so `-H` and `drive_epic.py` can take over. A resume that finds the hooks need re-arming (the first after an update to 4.x does, unless it first escalates a reason that is yours to fix, such as a Claude Code older than 2.1.295; then the resume after your fix does) writes the file again: make that resume attended too, or see [Troubleshooting](./troubleshooting.md#preflight-cant-reach-budget-zero) if a headless one met a refused write.
@@ -175,4 +175,6 @@ Each of these was hit while verifying real work, and each one first looked like
175
175
 
176
176
  **The spawned session's sandbox may refuse network egress when the parent's does not.** A story escalated reporting that two data files "cannot be fetched" and a dependency was "absent". From the parent session both were trivially available: the dependency was already in the local package cache and a plain `curl` reached the upstream host. **When a spawn reports a dependency it cannot fetch, check the local package caches and try the fetch yourself before accepting the block.**
177
177
 
178
+ **Stop a dev server before an unattended drive.** A test runner that reuses a server already answering at its URL, as Playwright does with `reuseExistingServer` (which TEA's framework scaffold turns on outside CI), attaches the gate's runs in its measurement worktree to the dev server you left running from your own checkout. Those browser runs then exercise your checkout's source, not the commit under assessment, and a mutation the gate writes into the worktree never reaches them. The gate checks the URLs a runner config may reuse and never stops a server unless it reads as one the run itself left up (below): it gives the worktree's runs their own server on a free port when a scratch runner config can, whether or not one answers, and otherwise tells every assessor the limit, so a risk that only a browser run could measure goes unmeasured. Observed: a gate's worktree runs attached to a vite dev server listening on `[::1]:3001` that had been started from the main tree, and automate left the source mutation behind one acceptance criterion unrun, since no run from the worktree could reach it. With the dev server stopped, the runner starts its own from the worktree, but a server it starts through a launcher such as turbo, which runs it in a process group of its own, outlives the run that started it, and with reuse on the runs after it reuse it, serving the files as they were when it started: the gate turns reuse off through its scratch config where it can, and otherwise reads a mutation row run through such a server as one that cannot run. A start command in your runner config that runs the server itself (the package's own dev script rather than turbo's) keeps it from outliving the run. On Linux the gate stops a server the run itself left up, such as one the sweep right before the gate started through turbo, at each of its checks and once more when the story's gate ends, so those servers do not pile up over an Epic, and the decision log names each one it stopped. It stops one only when every process of it is yours, has no controlling terminal and started after the current story's baseline marker was written, the process that started its session has exited, nothing else that still runs in that session started before the marker or is the parent of one of its processes (a watcher or supervisor that can start it again), and it runs from your project or the gate's worktree. A server of yours can meet all of that: one inside the project and on a port the gate checks, started in the background by a command that has since exited (a script's, or another agent session's) or from a terminal you then close (a `nohup ... &`), with nothing that began before the story still running in its session, reads as the run's and is stopped. So does one that a watcher of yours starts again after the story began, when the watcher too began after the story and runs in the server's process group, or starts the server through a command that then exits and either began after the story or had that command give the server a session of its own. That marker is written when the story starts, and the resume of a stopped or blocked run keeps it, so such a server you start between a run and its resume is stopped too. So stop it before you start or resume a drive, as this tip says, or start it outside the project, on another port or from a terminal you keep open.
179
+
178
180
  **Pin the parallelism of the verification suite if it is timing-sensitive.** Observed: a full-concurrency test run was flaky two green in five, because one unrelated gate crept past a 10-second default timeout under contention while taking 1.7 seconds alone. Pinning the runner to one worker (`ava --concurrency=1`; your runner's own name for it will differ) was green every time. A flaky verification tier makes every story's evidence unreliable, which is worse than a slow one.
@@ -17,15 +17,19 @@ flowchart TD
17
17
  G -->|"yes"| GATE["See: gate_eval reports blocked / escalate"]
18
18
  G -->|"no"| H{"A commit slipped past a guard"}
19
19
  H -->|"yes"| HOOK["See: Hooks not firing"]
20
- H -->|"no"| B{"A story stopped re-looping, escalation marker appeared"}
20
+ H -->|"no"| X{"Every tool call is refused, Read included"}
21
+ X -->|"yes"| REF["See: Every tool call is refused"]
22
+ X -->|"no"| B{"A story stopped re-looping, escalation marker appeared"}
21
23
  B -->|"yes"| BUD["See: Budget exhausted mid-story"]
22
24
  B -->|"no"| R{"Run was interrupted, want to continue"}
23
25
  R -->|"yes"| RES["See: Resume after an interruption"]
24
26
  R -->|"no"| D{"A drive stopped and you cannot tell why"}
25
27
  D -->|"yes"| OPS["See: operating tips, the driver's stop reasons"]
26
- D -->|"no"| LOG["Read the tail of .decision-log.md"]
28
+ D -->|"no"| V{"A dev server of yours is gone after a drive"}
29
+ V -->|"yes"| SRV["See: The gate stopped a server, or left one up"]
30
+ V -->|"no"| LOG["Read the tail of .decision-log.md"]
27
31
  classDef accent fill:#6366F1,stroke:#4F46E5,color:#fff
28
- class PRE,GATE,HOOK,BUD,RES,OPS,LOG accent
32
+ class PRE,GATE,HOOK,REF,BUD,RES,OPS,SRV,LOG accent
29
33
  ```
30
34
 
31
35
  ## Preflight can't reach budget-zero
@@ -38,9 +42,9 @@ flowchart TD
38
42
 
39
43
  - **Undecided product or architecture decisions.** An open question, a "TBD"/"TODO: decide" on a load-bearing requirement, a PRD↔ADR contradiction, or a story whose "done" is undefinable. The fix is a human decision; an unattended run guessing it produces confidently wrong work. Resolve the decision in the artifacts, then re-run.
40
44
  - **Missing secrets in headless.** Headless never prompts, so a secret that cannot be resolved becomes a RED blocker rather than a question. Provide the secret (out of git) before the headless run, or run attended so preflight can prompt once.
41
- - **Claude Code below the minimum versions.** The primitive-version blocker is marked non-remediable: the script can't upgrade the host. Update Claude Code.
45
+ - **Claude Code below the minimum versions.** The primitive-version blocker (`cc_version`) is marked non-remediable: the script can't upgrade the host. It names each primitive the version lacks. 2.1.295 is the floor, the release that added the hook setting `"onFailure": "block"` the guard is armed with. Update Claude Code (`claude update`). A run already in flight meets the same floor when it resumes: the resume runs `claude --version`, and below 2.1.295 it escalates the story it was about to drive instead of driving it. Update Claude Code, then resume in a new session, since an update takes effect only when Claude Code next starts: the resume shows that escalation and offers `/ucg-resolve` to close it (headless, run `/ucg-resolve` first). On a run UCG 3.x armed, that resume is also the one that re-arms the hooks, a write to `.claude/settings.local.json`: make it attended, since a headless one may be refused the write (see "A refused settings write" below). Both checks run the `claude` first on `PATH`, not the binary the session runs on. With two installs (an npm one beside the native installer's, say), or a `drive_epic.py --claude-bin` that names another binary, update the one first on `PATH` too, or the check reads its older version.
42
46
  - **A repository with nothing committed.** On a fresh `git init` (or an orphan branch) the `git_unborn` blocker is non-remediable: the run never makes the commit its Epic branch would start from, because that commit would sit outside its only rollback, the Epic branch. Commit a baseline yourself (the BMAD install, the planning artifacts and the project skeleton) on your base branch, a protected branch such as `main` and never an Epic branch, then re-run. If HEAD already names an Epic branch, the blocker's detail gives the command that points it at the base first.
43
- - **A refused settings write.** Preflight writes its hooks and allow rules into `.claude/settings.local.json`, which Claude Code treats as protected. Under Auto Mode the permission classifier may refuse that write, or let it land and refuse the next calls, as self-modification. The run then stops rather than work around the refusal, and the decision log names the write. Attended, approve it under `/permissions` (on its Recently denied tab) or apply it yourself; the run re-checks the hooks and continues. Headless, there is nobody to approve it, and `/ucg-resolve` is not the way back: take the Epic through preflight attended (see [hook security](./getting-started.md#hook-security)).
47
+ - **A refused settings write.** Preflight writes its hooks and allow rules into `.claude/settings.local.json`, which Claude Code treats as protected. Under Auto Mode the permission classifier may refuse that write, or let it land and refuse the next calls, as self-modification. The run then stops rather than work around the refusal, and the decision log names the write. Attended, approve it under `/permissions` (on its Recently denied tab) or apply it yourself; the run re-checks the hooks and continues. Headless, nobody is there to approve a refused write. At preflight the run then stops, and `/ucg-resolve` is not the way back: take the Epic through preflight attended (see [hook security](./getting-started.md#hook-security)). A resume rewrites the file too when the hooks need re-arming (the first resume after an update to 4.x does, unless it first escalates a reason that is yours to fix, such as a Claude Code older than 2.1.295), and a headless resume whose write is refused escalates the story it was about to drive instead. Resume attended: make or approve the write it asks for, and close that escalation with `/ucg-resolve`, which the resume offers before it drives the story. Whether a headless session is refused the write depends on its permission mode: under `bypassPermissions` the write lands, under Auto Mode the classifier decides, and under `default`, `acceptEdits` (the mode `drive_epic.py` spawns in unless you pass another) or `dontAsk` it is refused, since a write to a protected file needs an approval nobody is there to give.
44
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.
45
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.
46
50
 
@@ -61,6 +65,14 @@ Note this is fail-closed on purpose: a missing or unreadable gate artifact escal
61
65
 
62
66
  A per-story gate can return `reloop` with a `PASS` gate status when a cap fired rather than a finding: the `reasons` name either the sweep-scope cap (the `.tests-ran` marker says `scope=scoped`, or the marker/`scope=` line is missing) or the delta-profile cap (`--cycle-profile delta` was declared). Neither is an error; both mean "not yet, and here is why": a story only advances off a full-scope sweep judged by the full gate instrument. The remedy is the cap-only re-loop, which skips the generalize ceremony entirely: re-run the full three-axis sweep, refresh the marker with `scope=full`, and re-run the gate without `--cycle-profile`. See the cap sections in the [gate model](./gate-model.md).
63
67
 
68
+ ## The gate stopped a server, or left one up
69
+
70
+ **Symptom.** A dev server you had running is gone after a drive, or the decision log's worktree line names a server the gate stopped, or one it left up.
71
+
72
+ **What happened.** A test runner such as Playwright starts a server through a launcher such as turbo, which runs it in a process group of its own, so the server outlives the run. Execute's sweep right before the gate leaves one up in the main tree that way, and so does a gate run. On Linux the gate stops such a server with `scripts/probe_servers.py` at each of its checks, and once more when the story's gate ends, so the gate's runs in its worktree do not reuse it and those servers do not pile up over an Epic. It stops a server only when every process of it is yours, has no controlling terminal and started after the story's `.baseline-<story_id>` marker was written, the process that started its session has exited, nothing else that still runs in that session started before the marker or is the parent of one of its processes (a watcher or supervisor that can start it again), and it runs from the project or the gate's worktree. It leaves every other server up, and its `left` list gives the reason; on macOS and Windows it stops nothing. The gate never stops a server any other way.
73
+
74
+ **What you do.** If it stopped a server of yours, that server met every condition: it started inside the project, on a port the gate checks and after the story's marker was written, it had no terminal and had outlived the command that started its session, as a server does that a script or another agent session starts in the background, or one you start with `nohup ... &` from a terminal you then close, and nothing that began before the marker still ran in its session. A watcher or supervisor of yours that starts the server again after the marker (on a file change the run makes, say) keeps it up only while it runs in the server's session and either began before the marker or is the parent of one of the server's processes from a process group of its own; the server reads as the run's when the watcher began after the marker and either runs in the server's process group or starts it through a command that then exits and is not its parent afterwards (a subreaper adopts it back), or, whenever the watcher began, when that command gave the server a session of its own. That marker is written when the story starts, and the resume of a stopped or blocked run keeps it, so it can be days old: a server you start between a run and its resume counts too. Start it again, and stop such a server before you start or resume a drive, or start it outside the project, on another port or from a terminal you keep open. A server it left up keeps its port, so the gate gives the worktree's runs a server of their own through a scratch runner config where it can, and otherwise tells each assessor what that server leaves unmeasured. When the run left that server up, stop it yourself once the drive is done: a runner killed before it could end its start command leaves one whose session's first process still runs, and a watcher the run's own start command runs (a launcher task that runs watchexec, cargo-watch or air, say) keeps up the server it runs in a process group of its own, as a watcher of yours does, so stop that watcher too. A drive that stops before a story's gate logs its verdict can leave one up as well: that story's next gate stops it when you resume the run, so stop it yourself only if you do not resume.
75
+
64
76
  ## Hooks not firing
65
77
 
66
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.
@@ -71,6 +83,28 @@ A per-story gate can return `reloop` with a `PASS` gate status when a cap fired
71
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.
72
84
  - **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.
73
85
 
86
+ ## Every tool call is refused
87
+
88
+ **Symptom.** Every tool call the session makes is refused, Read, Edit and Bash alike, and each refusal names the guard's command, `guard_pretooluse.py`. Most read like `PreToolUse:Bash hook error: [<command>]: failed; blocking because onFailure is "block"` (or `timed out; blocking because onFailure is "block"`). When `uv` itself refuses to start the script (the skill was moved or removed, or no Python it can use), the refusal shows `uv`'s own error instead, such as `error: Failed to spawn`, since `uv` then exits 2, which Claude Code reads as a refusal in any case. A headless run stops on the first call.
89
+
90
+ **What happened.** Preflight arms the PreToolUse guard with `"onFailure": "block"`, so when the guard cannot run, Claude Code refuses the call rather than letting it through unchecked. The guard's matcher covers every tool, so a guard that cannot run refuses every call, including the ones the session would need to repair it. The usual causes:
91
+
92
+ - **`uv` is not on the `PATH` Claude Code runs hooks with.** The guard runs as `uv run …`, and a shell that cannot find `uv` exits 127. A session started from a shell or launcher with a narrower `PATH` than the one preflight ran in hits this.
93
+ - **The skill was moved or removed.** The guard's command names the script by the path the skill was installed at; an uninstall, or a reinstall to another folder, leaves the command pointing at nothing. When the project, or a folder above it, holds a `pyproject.toml`, `uv run` syncs that project on every call before it finds the script missing: it creates the project's `.venv` and `uv.lock` on the first call and builds the project again whenever it changes, and the refusal can show that project's build error instead of `Failed to spawn`. The budget hook's command points at nothing too. `uv` exits 2 when it cannot find the script, which on a `Stop` hook Claude Code reads as a block: each time the session tries to stop, it is sent back with uv's error instead, up to eight times in a row, after which Claude Code lets the stop through (the count starts again whenever Claude calls a tool). When that project fails to build, or its requirements cannot be satisfied, `uv` stops there and exits 1, which Claude Code reads on a `Stop` hook as a non-blocking error: the session stops, and the turn goes uncounted. A network failure in that sync exits 2 instead, and each stop is sent back as above. Reinstalling the skill ends it; then delete a `.venv` or `uv.lock` those calls left in a project that had none.
94
+ - **A path with a space, left unquoted in the command.** Claude Code runs the guard's command through a shell, which splits it at every unquoted space. Preflight writes each injected value and the script path in single quotes, so a project or skill folder whose path holds a space (`~/My Projects/app`, say) stays one word. A command written without them hands the rest of that path to the shell as the command to run, and the message names it: `/bin/sh: 1: Projects/app/_bmad-output/implementation-artifacts: not found` on Linux, or the same path followed by `No such file or directory` on macOS.
95
+ - **No Python `uv` can use.** `uv` cannot start a Python the script's header allows.
96
+ - **The guard ran past its timeout.** Claude Code's default for a command hook is 600 seconds; the message then says `timed out`.
97
+
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.
99
+
100
+ **What you do.** Fix it from outside the session, since the session cannot run a tool:
101
+
102
+ 1. Run the guard's command from `.claude/settings.local.json` yourself, in a terminal, to see why it fails (`echo '{}' | <the command>` should exit 0 and print nothing).
103
+ 2. Fix what it shows: put `uv` on `PATH`, reinstall the skill (`npx bmad-module-ultracode-goal update`), install a Python the script allows, or put each injected value and the script path in single quotes (`KEY='value' uv run '<path>'`), in the Stop budget hook's command too. From the project root, `uv run '<the skill folder>/scripts/preflight_check.py' --assert-armed --project-root . --impl-artifacts _bmad-output/implementation-artifacts` names every UCG hook command the shell would split (pass your own artifacts folder if you moved it).
104
+ 3. Then resume the run. The resume re-checks the hooks and re-arms them if they need it, unless it also finds a reason that is yours to fix, a missing story skill or a Claude Code older than 2.1.295: it then escalates the story it was about to drive first, and re-arms the hooks on the resume after you fix that.
105
+
106
+ If you need the session working before you can fix the cause, remove the guard's item from `.claude/settings.local.json` by hand, as [SECURITY.md](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/SECURITY.md) describes under "How to remove them". The session then runs with no guard at all, and a resume or the next preflight puts the item back, so fix the cause before either.
107
+
74
108
  ## Budget exhausted mid-story
75
109
 
76
110
  **Symptom.** A story stops re-looping; an escalation marker (`<impl-artifacts>/.escalation-<story>.md`) appears; the run surfaces a budget message.
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": "3.2.0",
4
+ "version": "4.1.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",
@@ -147,12 +147,23 @@ exists to remove.
147
147
 
148
148
  An entry recorded with `action` `defer` is the opposite case: it is a parked question, not
149
149
  an answered one. Present it again, and replace its entry in place when the operator decides
150
- it. Suppressing a deferred item would deadlock the run outright — `defer` clears nothing,
150
+ it, carrying its answer forward (section 3). Suppressing a deferred item would deadlock
151
+ the run outright: `defer` clears nothing,
151
152
  so the next preflight still blocks on that RED (`{ucg-root}/references/preflight.md`,
152
153
  step 3, drops only the ids whose `action` is `close`), while this surface, the only one that
153
154
  can answer it, would never ask again. The scan blocks forever on a question the operator is
154
155
  no longer offered.
155
156
 
157
+ An entry with no `action`, or with an `action` that is neither `close` nor `defer`, is
158
+ pending as well. An earlier version of this surface wrote some entries that way, and
159
+ preflight drops none of their ids, so their questions still block. Present it again, as
160
+ you present a deferred one.
161
+
162
+ When an item you present already has an entry, show its `answer`, and each earlier answer
163
+ its `history` holds (section 3), beside the decision needed. Such an answer can hold the
164
+ operator's whole ruling: they decide on the record as it stands, and may find it already
165
+ answers the question.
166
+
156
167
  ## 3. Record the answer, then apply its disposition
157
168
 
158
169
  Every answer lands in `{workflow.implementation_artifacts}/.decisions.json`:
@@ -160,18 +171,33 @@ Every answer lands in `{workflow.implementation_artifacts}/.decisions.json`:
160
171
  ```json
161
172
  {"decisions": [{"id": "<the pending item's stable id>",
162
173
  "answer": "<what the operator decided, one line>",
163
- "action": "close|defer"}]}
174
+ "action": "close|defer",
175
+ "history": [{"answer": "<an answer this entry replaced, verbatim>",
176
+ "action": "<that answer's action, when it had one>"}]}]}
164
177
  ```
165
178
 
166
179
  **Write the file read-modify-write, keyed by `id`.** Read any existing `.decisions.json`
167
- first, merge this pass's answers into its `decisions[]` — a new answer for an `id` already
168
- present replaces that entry, every other entry is preserved untouched — and write the whole
180
+ first, merge this pass's answers into its `decisions[]` (a new answer for an `id` already
181
+ present replaces that entry and carries its answer forward, as the next paragraph says;
182
+ every other entry is preserved untouched), and write the whole
169
183
  array back. The fence above is the shape of the *document*, not a licence to emit only this
170
184
  pass's answers: a plain overwrite would discard every answer recorded by an earlier pass,
171
185
  including the `close` entries preflight reads to keep resolved REDs suppressed. Those
172
186
  decisions would silently return as pending and re-block a run the operator already
173
187
  unblocked.
174
188
 
189
+ **A replacement never drops an earlier answer.** When a new answer replaces the entry for
190
+ its `id`, the new entry carries that entry forward in `history`: copy the replaced entry's
191
+ `history` list as it stands, then append the replaced entry itself, with every field but
192
+ `id` and `history` copied verbatim (its `answer`, and its `action` when it had one). When
193
+ the file holds more than one entry for that `id`, carry each forward, in file order, and
194
+ write one entry in their place. Leave `history` off an entry that replaced nothing. A pass
195
+ that only parks an item records one line, while the entry it replaces can hold the
196
+ operator's whole ruling: a plain replacement would erase that ruling, and nothing in the
197
+ pass would report the loss. Every reader of the file keys on `id` and `action` alone
198
+ (`{ucg-root}/scripts/red_ids.py`, which preflight and the resume read it through), so
199
+ `history` changes no suppression.
200
+
175
201
  **If an existing `.decisions.json` is unreadable, unparseable, or parsed but missing a
176
202
  list-valued `decisions`, stop — do not overwrite it.** Say which file failed and why. This
177
203
  is the fail-closed twin of the rule preflight already applies to the same file (an
@@ -242,6 +268,29 @@ The two dispositions are genuinely different things, not two names for one:
242
268
  and removes the marker (`{ucg-root}/references/gate.md`, "Commit the gate's evidence
243
269
  before the next story starts"), on the Epic's last story too, where every row already
244
270
  reads `done` and the resume re-enters only for that commit before Finalize.
271
+ **Closing a `coupled-stories` escalation records a proposed move, and the resumed run
272
+ makes it; a re-plan is the operator's own edit.**
273
+ The sidecar proposes moving clauses the earlier story owes to the later story it
274
+ names, which narrows the earlier story's AC, or it proposes only a re-plan, where no
275
+ move fits: the later story is outside the run's scope, the two stories are a pair no
276
+ move applies to (a decomposed child beside a story that has a file, or children of two
277
+ parents), or an AC between two decomposed children holds a clause no run measured
278
+ (`{ucg-root}/references/execute.md`, "Two stories green only together"). When the
279
+ operator approves a proposed move, as proposed or
280
+ reworded, write the sidecar's `decision_needed` verbatim into this answer's
281
+ `.decision-log.md` entry, under both story keys it names, beside the operator's answer
282
+ and the id you closed, before you delete the sidecar: once the sidecar is gone, that
283
+ entry is the only copy of the move the resumed run writes into both story files, or for
284
+ two decomposed children into every record of their split (the split record, both child
285
+ rows in `sprint-status.yaml` and both ATDD checklists). This
286
+ surface edits neither story file and moves no test case: the ruling is the operator's,
287
+ and the resumed run applies it before the earlier story's next commit. An answer that
288
+ re-plans the rows instead (one story in place of the two, or another order) is the
289
+ operator's own edit of `sprint-status.yaml` and the story files: record `defer` until
290
+ they have made it, then `close`. A sidecar that proposes only a re-plan has no move for
291
+ this surface to record or for the resumed run to apply, so whatever the operator rules
292
+ for it is their own edit of those files: record `defer` until they have made it, then
293
+ `close`.
245
294
  - **`defer`** — the decision is not made yet. Record the entry **without clearing
246
295
  anything**. The artifact stays exactly where it is, the item stays pending, and the next
247
296
  preflight still blocks on it.
@@ -251,7 +300,9 @@ Record each answer and its disposition in `.decision-log.md` as you apply it.
251
300
  ## 4. Hand control back to the existing resume
252
301
 
253
302
  `/ucg-resolve` defines no resume of its own. Close the pass by stating what closed, what is
254
- still pending, and that anything still pending re-blocks at the next preflight. **Hand back
303
+ still pending, and that anything still pending re-blocks at the next preflight. Name every
304
+ entry this pass replaced, by `id`, with the earlier answer it carried into `history`, so
305
+ the operator sees what the record held before this pass. **Hand back
255
306
  only when the pass closed at least one item, or when the operator asks for the resume**: a
256
307
  pass that deferred everything hands into a run blocked on the identical items, and an empty
257
308
  enumeration means the run stopped for a non-decision reason — say so, point at the read-only
@@ -137,7 +137,7 @@ Three things are worth saying out loud alongside it:
137
137
  | re-loops this run | how many times this run re-entered a story, from the heartbeat |
138
138
  | profile | the profile the run is on, from the heartbeat |
139
139
  | updated | when the heartbeat was last written: this with `phase` is how a reader judges liveness |
140
- | stories | one row per in-scope story: phase, verdict, attempts, re-loops |
140
+ | stories | one row per in-scope story: phase, verdict, attempts, re-loops; a story that still owes its gate evidence commit or a re-gate says so (see below) |
141
141
  | escalations | one block per escalation on disk (see below) |
142
142
  | deferred work | every row of the ledger, across every run it has accumulated |
143
143
  | decision log tail | the run's own account of itself, last lines - only when `--run-dir` was passed (§1) |
@@ -172,6 +172,39 @@ A marker and an unreadable sidecar can both be on disk for one story, and the ma
172
172
  the render, so an `unpromoted` block is worth one directory check before you report the
173
173
  typed record as never written.
174
174
 
175
+ **A story that still owes its gate evidence commit says so on its row.** When a repo commit
176
+ hook rejects the gate's evidence commit in a way the gate may not answer, the gate
177
+ escalates the story as `evidence-commit-rejected` and writes `.evidence-owed-<story_id>`
178
+ beside the sidecar, listing the paths it left staged. `/ucg-resolve` deletes the sidecar
179
+ when it closes that escalation and leaves the marker, which a resume removes once it has
180
+ made the commit, or once it finds the listed paths committed already, by the operator or
181
+ by a run that stopped between its commit and that removal. The story renders under
182
+ stories as `gate evidence commit owed when its marker was written, after a commit hook
183
+ rejected it: a resume makes the commit, or removes the marker when it finds the paths
184
+ committed already`, with the marker's name and its paths, on that story's row, or on a
185
+ line of its own when the heartbeat no longer lists it. Report the story as advanced at its
186
+ gate with its evidence commit owed when the marker was written: while its
187
+ `evidence-commit-rejected` block still renders under escalations, `/ucg-resolve` closes it
188
+ first, and once the block is gone one resume of the run makes the commit, or finds it made
189
+ and removes the marker without one. The render does not read git, so it does not say
190
+ whether the paths are still staged. While this line renders the Epic is not finished, even
191
+ when every story reads `done` and escalations read `n/a`: it is the state in which
192
+ `drive_epic.py` stops `evidence-owed` rather than `all-done`.
193
+
194
+ **A story that owes a re-gate says so on its row too.** When `/ucg-resolve` closes an
195
+ `operator-evidence-owed` escalation, it deletes the sidecar and writes
196
+ `.regate-<story_id>`, holding `sha=` the assessed commit and `decision=` the closed id, and
197
+ the gate deletes that marker once the story's next verdict is logged. Until then nothing
198
+ renders under escalations for the story, and a row the heartbeat still lists keeps the
199
+ verdict that escalated it, so the story renders under stories as `re-gate owed: its
200
+ operator-evidence-owed escalation was closed, and no gate verdict was logged since`, with
201
+ the marker's name, its `sha=` and its `decision=`, on that story's row, or on a line of its
202
+ own when the heartbeat no longer lists it. Report the story as waiting on a gate the next
203
+ resume of the run runs: while the `sha=` commit is still `HEAD`, the resume re-gates that
204
+ commit against the operator's records, and once a later commit has moved `HEAD` past it
205
+ those records are stale and the resume routes the story as if the marker were absent. The
206
+ render does not read `HEAD`, so it does not say which of the two holds.
207
+
175
208
  ## Optional diff-viewer affordance
176
209
 
177
210
  When `hunk` is on PATH, each story that recorded a baseline commit gains copy-paste