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.
- package/.claude-plugin/marketplace.json +1 -1
- package/README.md +15 -15
- package/docs/_internal/STABILITY.md +3 -3
- package/docs/architecture.md +3 -1
- package/docs/cross-session-recall.md +3 -3
- package/docs/getting-started.md +3 -3
- package/docs/operating-tips.md +2 -0
- package/docs/troubleshooting.md +39 -5
- package/package.json +1 -1
- package/skills/ucg-resolve/SKILL.md +56 -5
- package/skills/ucg-status/SKILL.md +34 -1
- package/skills/ultracode-goal/references/execute.md +11 -7
- package/skills/ultracode-goal/references/finalize.md +3 -3
- package/skills/ultracode-goal/references/gate.md +10 -7
- package/skills/ultracode-goal/references/preflight.md +22 -13
- package/skills/ultracode-goal/scripts/gate_trail.py +270 -36
- package/skills/ultracode-goal/scripts/hooks/budget_stop.py +297 -36
- package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +546 -86
- package/skills/ultracode-goal/scripts/mutate_check.py +661 -70
- package/skills/ultracode-goal/scripts/preflight_check.py +949 -46
- package/skills/ultracode-goal/scripts/probe_servers.py +784 -0
- package/skills/ultracode-goal/scripts/status_render.py +69 -1
- package/skills/ultracode-goal/scripts/story_sizing.py +14 -9
|
@@ -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": "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.
|
|
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](
|
|
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](
|
|
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](
|
|
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](
|
|
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](
|
|
141
|
-
- **[How It Works](
|
|
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](
|
|
146
|
-
- **[Gate Model](
|
|
147
|
-
- **[Health Check](
|
|
148
|
-
- **[Cross-Session Recall](
|
|
149
|
-
- **[Knowledge-Graph Refresh](
|
|
150
|
-
- **[Operating Tips](
|
|
151
|
-
- **[Troubleshooting](
|
|
152
|
-
- **[UCG vs bmad-loop](
|
|
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
|
+
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:**
|
|
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 `
|
|
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
|
|
package/docs/architecture.md
CHANGED
|
@@ -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.
|
|
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.
|
|
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,
|
|
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.
|
package/docs/getting-started.md
CHANGED
|
@@ -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.
|
|
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
|
|
94
|
+
**Take a new Epic through preflight attended.** The same write adds allow rules built from `allowlist_commands`, and Claude Code treats `.claude/settings.local.json` as a protected file. A headless session may be refused that write, and then nobody is there to approve it: under Auto Mode, which the run requires, the permission classifier may refuse it (or the calls after it) as self-modification, and under `drive_epic.py`'s default `acceptEdits` mode the write needs an approval nobody is there to give. Only `bypassPermissions` lets it land unreviewed. A refused write stops the run at arming. So run the first invocation of a new Epic attended, in Auto Mode, through the launch briefing and on to at least one story's gate verdict; if a settings write is refused, approve it under `/permissions` (on its Recently denied tab) or apply it yourself, as the decision log describes. From then on, a session that resumes the Epic routes into Execute and only re-checks the hooks, so `-H` and `drive_epic.py` can take over. A resume that finds the hooks need re-arming (the first after an update to 4.x does, unless it first escalates a reason that is yours to fix, such as a Claude Code older than 2.1.295; then the resume after your fix does) writes the file again: make that resume attended too, or see [Troubleshooting](./troubleshooting.md#preflight-cant-reach-budget-zero) if a headless one met a refused write.
|
package/docs/operating-tips.md
CHANGED
|
@@ -175,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.
|
package/docs/troubleshooting.md
CHANGED
|
@@ -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"|
|
|
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"|
|
|
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,
|
|
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": "
|
|
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
|
|
150
|
+
it, carrying its answer forward (section 3). Suppressing a deferred item would deadlock
|
|
151
|
+
the run outright: `defer` clears nothing,
|
|
151
152
|
so the next preflight still blocks on that RED (`{ucg-root}/references/preflight.md`,
|
|
152
153
|
step 3, drops only the ids whose `action` is `close`), while this surface, the only one that
|
|
153
154
|
can answer it, would never ask again. The scan blocks forever on a question the operator is
|
|
154
155
|
no longer offered.
|
|
155
156
|
|
|
157
|
+
An entry with no `action`, or with an `action` that is neither `close` nor `defer`, is
|
|
158
|
+
pending as well. An earlier version of this surface wrote some entries that way, and
|
|
159
|
+
preflight drops none of their ids, so their questions still block. Present it again, as
|
|
160
|
+
you present a deferred one.
|
|
161
|
+
|
|
162
|
+
When an item you present already has an entry, show its `answer`, and each earlier answer
|
|
163
|
+
its `history` holds (section 3), beside the decision needed. Such an answer can hold the
|
|
164
|
+
operator's whole ruling: they decide on the record as it stands, and may find it already
|
|
165
|
+
answers the question.
|
|
166
|
+
|
|
156
167
|
## 3. Record the answer, then apply its disposition
|
|
157
168
|
|
|
158
169
|
Every answer lands in `{workflow.implementation_artifacts}/.decisions.json`:
|
|
@@ -160,18 +171,33 @@ Every answer lands in `{workflow.implementation_artifacts}/.decisions.json`:
|
|
|
160
171
|
```json
|
|
161
172
|
{"decisions": [{"id": "<the pending item's stable id>",
|
|
162
173
|
"answer": "<what the operator decided, one line>",
|
|
163
|
-
"action": "close|defer"
|
|
174
|
+
"action": "close|defer",
|
|
175
|
+
"history": [{"answer": "<an answer this entry replaced, verbatim>",
|
|
176
|
+
"action": "<that answer's action, when it had one>"}]}]}
|
|
164
177
|
```
|
|
165
178
|
|
|
166
179
|
**Write the file read-modify-write, keyed by `id`.** Read any existing `.decisions.json`
|
|
167
|
-
first, merge this pass's answers into its `decisions[]`
|
|
168
|
-
present replaces that entry
|
|
180
|
+
first, merge this pass's answers into its `decisions[]` (a new answer for an `id` already
|
|
181
|
+
present replaces that entry and carries its answer forward, as the next paragraph says;
|
|
182
|
+
every other entry is preserved untouched), and write the whole
|
|
169
183
|
array back. The fence above is the shape of the *document*, not a licence to emit only this
|
|
170
184
|
pass's answers: a plain overwrite would discard every answer recorded by an earlier pass,
|
|
171
185
|
including the `close` entries preflight reads to keep resolved REDs suppressed. Those
|
|
172
186
|
decisions would silently return as pending and re-block a run the operator already
|
|
173
187
|
unblocked.
|
|
174
188
|
|
|
189
|
+
**A replacement never drops an earlier answer.** When a new answer replaces the entry for
|
|
190
|
+
its `id`, the new entry carries that entry forward in `history`: copy the replaced entry's
|
|
191
|
+
`history` list as it stands, then append the replaced entry itself, with every field but
|
|
192
|
+
`id` and `history` copied verbatim (its `answer`, and its `action` when it had one). When
|
|
193
|
+
the file holds more than one entry for that `id`, carry each forward, in file order, and
|
|
194
|
+
write one entry in their place. Leave `history` off an entry that replaced nothing. A pass
|
|
195
|
+
that only parks an item records one line, while the entry it replaces can hold the
|
|
196
|
+
operator's whole ruling: a plain replacement would erase that ruling, and nothing in the
|
|
197
|
+
pass would report the loss. Every reader of the file keys on `id` and `action` alone
|
|
198
|
+
(`{ucg-root}/scripts/red_ids.py`, which preflight and the resume read it through), so
|
|
199
|
+
`history` changes no suppression.
|
|
200
|
+
|
|
175
201
|
**If an existing `.decisions.json` is unreadable, unparseable, or parsed but missing a
|
|
176
202
|
list-valued `decisions`, stop — do not overwrite it.** Say which file failed and why. This
|
|
177
203
|
is the fail-closed twin of the rule preflight already applies to the same file (an
|
|
@@ -242,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.
|
|
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
|