bmad-module-ultracode-goal 7.3.0 → 8.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +1 -1
- package/docs/_internal/STABILITY.md +3 -3
- package/docs/architecture.md +1 -1
- package/docs/gate-model.md +1 -1
- package/docs/health-check.md +6 -4
- package/docs/operating-tips.md +1 -1
- package/package.json +3 -2
- package/skills/ucg-formalize/SKILL.md +1 -1
- package/skills/ucg-resolve/SKILL.md +8 -1
- package/skills/ultracode-goal/SKILL.md +1 -1
- package/skills/ultracode-goal/customize.toml +9 -3
- package/skills/ultracode-goal/references/execute.md +6 -6
- package/skills/ultracode-goal/references/finalize.md +1 -1
- package/skills/ultracode-goal/references/gate.md +8 -8
- package/skills/ultracode-goal/references/health-check.md +17 -7
- package/skills/ultracode-goal/references/ingest-and-scope.md +3 -3
- package/skills/ultracode-goal/references/preflight.md +1 -1
- package/skills/ultracode-goal/scripts/drive_epic.py +5 -3
- package/skills/ultracode-goal/scripts/formalize_check.py +96 -17
- package/skills/ultracode-goal/scripts/gate_eval.py +13 -13
- package/skills/ultracode-goal/scripts/gate_trail.py +19 -19
- package/skills/ultracode-goal/scripts/health_check_fp.py +110 -5
- package/skills/ultracode-goal/scripts/link_worktree_deps.py +480 -11
- package/skills/ultracode-goal/scripts/moved_ac_check.py +2 -2
- package/skills/ultracode-goal/scripts/operator_owed.py +45 -14
|
@@ -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": "8.0.0",
|
|
23
23
|
"author": {
|
|
24
24
|
"name": "Armel"
|
|
25
25
|
},
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Stability and Public Contract
|
|
3
|
-
description: "The
|
|
3
|
+
description: "The 8.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:** 8.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 `8.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
|
@@ -70,7 +70,7 @@ skills/ultracode-goal/
|
|
|
70
70
|
│ ├── claim_check.py # pre-commit: paths a message names that the staged diff skips
|
|
71
71
|
│ ├── drive_epic.py # one `claude -p` per story (--max-stories work bound)
|
|
72
72
|
│ ├── headless_envelope.py # the one five-key headless-envelope adapter
|
|
73
|
-
│ ├── health_check_fp.py # health-check fingerprint, seen-cache and queue plumbing
|
|
73
|
+
│ ├── health_check_fp.py # health-check fingerprint, seen-cache, repository split and queue plumbing
|
|
74
74
|
│ ├── mem_observation.py # Cross-Session Recall write path (write/drain)
|
|
75
75
|
│ ├── mem_recall.py # Cross-Session Recall latch and read path (latch/filter/unlatch)
|
|
76
76
|
│ ├── merge_config.py # install-time config merge into shared _bmad
|
package/docs/gate-model.md
CHANGED
|
@@ -52,7 +52,7 @@ The gate status maps to a verdict (`GATE_VERDICT` in the script):
|
|
|
52
52
|
|
|
53
53
|
Any unrecognized status escalates (the script's `GATE_VERDICT.get(gate_status, "escalate")` default), with a `reasons` entry noting it.
|
|
54
54
|
|
|
55
|
-
One `FAIL` takes a different route. When the only criteria TEA's coverage matrix holds open are acceptance criteria tagged `**Gate-ability:** operator-evidence`, whose proof is a live result a person records, no re-loop can change the gate. A plain `**Gate-ability:** operator` tag is not read this way: it marks work the dev agent builds, so an open criterion carrying it keeps the re-loop. The skill checks that with `scripts/operator_owed.py`, which fails closed, and escalates with kind `operator-evidence-owed` instead of re-looping. `gate_eval.py` still prints `reloop`: the route changes, not the verdict.
|
|
55
|
+
One `FAIL` takes a different route. When the only criteria TEA's coverage matrix holds open are acceptance criteria tagged `**Gate-ability:** operator-evidence`, whose proof is a live result a person records, no re-loop can change the gate. A plain `**Gate-ability:** operator` tag is not read this way: it marks work the dev agent builds, so an open criterion carrying it keeps the re-loop. The skill checks that with `scripts/operator_owed.py`, which fails closed, and escalates with kind `operator-evidence-owed` instead of re-looping. When the story tags such a criterion but the script cannot read TEA's coverage matrix (there is no trace report, or it lost its absolute `tempCoverageMatrixPath`, the file is gone, or the matrix or the summary is not this gate's), it answers `evaluated: false` rather than a plain `owed: false`, and the story escalates the same way, with a `decision_needed` that opens "The operator-evidence check could not read trace's coverage matrix", since what kept the check from the matrix is the files trace left, which no build work changes. The gate moves that cycle's trace files aside first, so `/ucg-resolve` closes the first such escalation at a commit at once and its re-gate runs trace again, and closes a later one at that commit only on the operator's written word that trace can leave a matrix the check can read there. A hand-authored trace, which holds no matrix by design, keeps the re-loop, and so does a decomposed child none of whose claimed criteria carries the tag. `gate_eval.py` still prints `reloop`: the route changes, not the verdict.
|
|
56
56
|
|
|
57
57
|
Once `/ucg-resolve` closes that escalation, with the person's records on disk at the commit the gate measured, the resume re-gates that same commit instead of re-driving the story. An `operator-evidence` criterion that already has a counted `pass` record, and that TEA still holds below `FULL`, is still owed: the record covers only part of the criterion, so the escalation names the records already counted and asks the operator to record the rest or to narrow or move the criterion in writing. Re-gating the records already counted changes nothing, so `/ucg-resolve` closes it only on a new `pass` record or on that written change. A criterion the operator moves out of the story leaves the story's numbered list for a section of its own that names its owner and the ruling, its number retired and never reused, and `/ucg-resolve` closes on the move only once the story file carries it, recording each moved criterion in a per-story `.moved-<story_id>` file. A decomposed child's criterion is not moved this way, since its parent's story file is never edited. TEA's trace has no status for a moved criterion and can still score it from the epic, the PRD or the test design, so every gate cycle of a story with that record names the main-tree story file, and every recorded oracle source, to trace, and before `gate_eval.py` runs, `scripts/moved_ac_check.py --commit` reads TEA's coverage matrix for the commit under assessment: while a row still holds a moved criterion, or the trace files cannot be read or measured another commit, the story escalates `operator-evidence-owed` again, with a `decision_needed` that opens "The moved-AC check refused" and its exit code, instead of re-looping with nothing left to build.
|
|
58
58
|
|
package/docs/health-check.md
CHANGED
|
@@ -92,14 +92,14 @@ health_check_repo = ""
|
|
|
92
92
|
|
|
93
93
|
The `[workflow]` table header matters: the resolver extracts the `workflow` block from the merged files, so a bare top-level line is silently discarded and the knob keeps its default.
|
|
94
94
|
|
|
95
|
-
**To send findings to another repository**, set `health_check_repo` to it under the same header (`OWNER/REPO`, or `HOST/OWNER/REPO` on a host other than github.com), and set that repository up as the default one is: create the labels `health-check`, `workflow-improvement`, `bug`, `friction`, `gap`, `duplicate` and `possible-duplicate` there, and copy two files into it unchanged, the issue template [`.github/ISSUE_TEMPLATE/workflow-health-check.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/.github/ISSUE_TEMPLATE/workflow-health-check.md) and the dedup Action [`.github/workflows/health-check-dedup.yaml`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/.github/workflows/health-check-dedup.yaml), which reads its repository from the run. Without the labels the first create fails and the retry files the issue unlabeled; without the Action nothing labels it or closes a duplicate. Set the project's own `health_check_seen_cache` too: the cache keys each record by fingerprint alone, so two projects that share it and file to different repositories would block or overwrite each other's records.
|
|
95
|
+
**To send findings to another repository**, set `health_check_repo` to it under the same header (`OWNER/REPO`, or `HOST/OWNER/REPO` on a host other than github.com, such as a GitHub Enterprise Server host: log in to that host first, with `gh auth login --hostname HOST`, writing HOST in lower case and without a leading `www.`, as `gh` reads the host of a repository), and set that repository up as the default one is: create the labels `health-check`, `workflow-improvement`, `bug`, `friction`, `gap`, `duplicate` and `possible-duplicate` there, and copy two files into it unchanged, the issue template [`.github/ISSUE_TEMPLATE/workflow-health-check.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/.github/ISSUE_TEMPLATE/workflow-health-check.md) and the dedup Action [`.github/workflows/health-check-dedup.yaml`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/.github/workflows/health-check-dedup.yaml), which reads its repository from the run. Without the labels the first create fails and the retry files the issue unlabeled; without the Action nothing labels it or closes a duplicate. On a host other than github.com, the Action runs only once GitHub Actions is on there, its `runs-on` names one of the host's runners, the host can reach `actions/github-script` at the commit the Action pins, and those runners can run the Node version that commit's `action.yml` names in `runs.using`. Set the project's own `health_check_seen_cache` too: the cache keys each record by fingerprint alone, so two projects that share it and file to different repositories would block or overwrite each other's records.
|
|
96
96
|
|
|
97
97
|
**To let autosubmit post unattended**, allow the four `gh` commands a submission runs. Without an allow rule, each is left to Claude Code's permission check: under Auto Mode the classifier decides whether it runs, and in a mode that asks first, such as `drive_epic.py`'s default `acceptEdits`, nobody is there to answer, so the call is refused and the finding is queued with a reason that says a `gh` call was refused. Add them to `allowlist_commands` under the same `[workflow]` header, not a second one: TOML refuses a table declared twice, and the resolver then rejects the whole file. Arrays append to the shipped list, and preflight writes each entry as an allow rule in `.claude/settings.local.json`. The whole file then reads:
|
|
98
98
|
|
|
99
99
|
```toml
|
|
100
100
|
[workflow]
|
|
101
101
|
health_check_autosubmit = true
|
|
102
|
-
allowlist_commands = ["gh auth status", "gh
|
|
102
|
+
allowlist_commands = ["gh auth status", "gh issue list", "gh label create", "gh issue create"]
|
|
103
103
|
```
|
|
104
104
|
|
|
105
105
|
These rules outlast the run: they stay in `.claude/settings.local.json` and apply to every later session in the project, so any agent working there can then create issues and labels on any repository without asking. To keep the three that take a repository to the health-check repository, scope them with it. Every `gh` command the health check runs puts `--repo` right after its subcommand, so the narrower rules still match:
|
|
@@ -107,9 +107,11 @@ These rules outlast the run: they stay in `.claude/settings.local.json` and appl
|
|
|
107
107
|
```toml
|
|
108
108
|
[workflow]
|
|
109
109
|
health_check_autosubmit = true
|
|
110
|
-
allowlist_commands = ["gh auth status", "gh
|
|
110
|
+
allowlist_commands = ["gh auth status", "gh issue list --repo <health_check_repo>", "gh label create --repo <health_check_repo>", "gh issue create --repo <health_check_repo>"]
|
|
111
111
|
```
|
|
112
112
|
|
|
113
|
+
An override written for 7.3.0 or earlier allows `gh search issues`, which the health check no longer runs: it searches with `gh issue list`, whose `--repo` also takes a host. In the `[workflow]` override, replace `"gh search issues"` with `"gh issue list"` (or `"gh search issues --repo <health_check_repo>"` with `"gh issue list --repo <health_check_repo>"`), and delete the rule preflight wrote for the old entry, `Bash(gh search issues:*)` or `Bash(gh search issues --repo <health_check_repo>:*)`, from `.claude/settings.local.json`.
|
|
114
|
+
|
|
113
115
|
When you turn autosubmit off, remove the entries, then delete the rules preflight wrote for them, such as `Bash(gh issue create:*)`, from `.claude/settings.local.json` yourself: preflight only adds rules.
|
|
114
116
|
|
|
115
117
|
The local queue lives at the configured `health_check_queue_path` (by default `{project-root}/_bmad-output/ultracode-goal/improvement-queue/`), which is created when it is missing. `health_check_fp.py queue` writes each finding there as one file, named `hc-ultracode-goal-{stage}-{YYYYMMDD-HHmmss}.md` from the UTC time, and holding the finding's issue body exactly as it was drafted, with no frontmatter. When two findings of one stage are written in the same second, the later names get `-2`, `-3` and so on before `.md`, so no file is overwritten. Whatever the reason a finding stays local (the `[Q]` choice, a headless run, a friction or gap finding, a finding about the health check itself, no GitHub CLI, a refused `gh` call, a skipped or failed submission), the health check lists each file it wrote with one sentence giving the reason and the commands that submit it, which `health_check_fp.py queue` prints with every argument quoted: on screen in an attended run, in the log in a headless one.
|
|
@@ -184,4 +186,4 @@ When the body opens with "Regression of", add `--regression`: the new issue trac
|
|
|
184
186
|
|
|
185
187
|
Then retire the queue file: delete it, or move it into a `resolved/` subfolder of the queue directory.
|
|
186
188
|
|
|
187
|
-
You can also open one through the issue chooser of `<health-check-repo>`, `https
|
|
189
|
+
You can also open one through the issue chooser of `<health-check-repo>`, `https://<host>/<owner>/<repo>/issues/new/choose`, `<host>` being the host you logged in to for a `HOST/OWNER/REPO` value, and `github.com` for `OWNER/REPO` (on the default, <https://github.com/armelhbobdad/bmad-module-ultracode-goal/issues/new/choose>). An issue filed that way keeps the template's `health-check` and `workflow-improvement` labels and lacks only the `fp-*` and severity ones, so replace its sections from Workflow through Defect Key with the `body_header` that the `health_check_fp.py fingerprint` command in the template's comments prints: the dedup Action adds those two labels from its Fingerprint and Severity, and leaves an issue whose Fingerprint still holds the `fp-XXXXXXX` placeholder as it is.
|
package/docs/operating-tips.md
CHANGED
|
@@ -175,7 +175,7 @@ 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]:
|
|
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]:5173` that had been started from the main tree, and automate left the source mutation behind one acceptance criterion unrun, since no run from the worktree could reach it. With the dev server stopped, the runner starts its own from the worktree, but a server it starts through a launcher such as turbo, which runs it in a process group of its own, outlives the run that started it, and with reuse on the runs after it reuse it, serving the files as they were when it started: the gate turns reuse off through its scratch config where it can, and otherwise reads a mutation row run through such a server as one that cannot run. A start command in your runner config that runs the server itself (the package's own dev script rather than turbo's) keeps it from outliving the run. On Linux the gate stops a server the run itself left up, such as one the sweep right before the gate started through turbo, at each of its checks and once more when the story's gate ends, so those servers do not pile up over an Epic, and the decision log names each one it stopped. It stops one only when every process of it is yours, has no controlling terminal and started after the current story's baseline marker was written, the process that started its session has exited, nothing else that still runs in that session started before the marker or is the parent of one of its processes (a watcher or supervisor that can start it again), and it runs from your project or the gate's worktree. A server of yours can meet all of that: one inside the project and on a port the gate checks, started in the background by a command that has since exited (a script's, or another agent session's) or from a terminal you then close (a `nohup ... &`), with nothing that began before the story still running in its session, reads as the run's and is stopped. So does one that a watcher of yours starts again after the story began, when the watcher too began after the story and runs in the server's process group, or starts the server through a command that then exits and either began after the story or had that command give the server a session of its own. That marker is written when the story starts, and the resume of a stopped or blocked run keeps it, so such a server you start between a run and its resume is stopped too. So stop it before you start or resume a drive, as this tip says, or start it outside the project, on another port or from a terminal you keep open.
|
|
179
179
|
|
|
180
180
|
**Expect one cold Cargo build per gated story, not two.** The production gate replaces its measurement worktree once automate has finished, and `git worktree remove --force` deletes every ignored folder with it. The gate carries the worktree's Cargo build folders (`target`, `src-tauri/target`) out before that removal and back after the new worktree is added, and does the same across a `reloop`, so only the story's first gate setup builds from nothing. After an `escalate`, `advance` or `defer` verdict it carries nothing, and an escalation deletes what it had carried, so a re-gate after an escalation builds cold again. The decision log's honesty line names each folder it carried, skipped or could not move.
|
|
181
181
|
|
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": "8.0.0",
|
|
5
5
|
"description": "BMAD module — Run a BMAD Epic autonomously to a machine-checked, TEA-gated Definition-of-Done.",
|
|
6
6
|
"keywords": [
|
|
7
7
|
"bmad",
|
|
@@ -45,7 +45,7 @@
|
|
|
45
45
|
"lint:md": "markdownlint-cli2 \"**/*.md\" && node tools/changes.js lint",
|
|
46
46
|
"prepare": "husky || exit 0",
|
|
47
47
|
"postprepare": "node tools/link-reference-skills.js --quiet || exit 0",
|
|
48
|
-
"quality": "run-p --print-label --aggregate-output format:check lint lint:md lint:instructions test:install test:cli test:pack test:python test:rehype test:docs-links-tool test:skill-links test:em-dash-tool test:tool-requirements-tool test:context-index-tool test:changes-tool validate:skills validate:refs validate:fixtures validate:docs-links validate:em-dash validate:tool-requirements validate:context-index validate:changes",
|
|
48
|
+
"quality": "run-p --print-label --aggregate-output format:check lint lint:md lint:instructions test:install test:cli test:pack test:python test:rehype test:docs-links-tool test:skill-links test:em-dash-tool test:tool-requirements-tool test:context-index-tool test:changes-tool test:private-tokens-tool validate:skills validate:refs validate:fixtures validate:docs-links validate:em-dash validate:tool-requirements validate:context-index validate:changes",
|
|
49
49
|
"skills:link": "node tools/link-reference-skills.js",
|
|
50
50
|
"test": "npm run quality",
|
|
51
51
|
"test:changes-tool": "node test/test-changes.js && node test/test-covered-surfaces.js && node test/test-release-state.js",
|
|
@@ -55,6 +55,7 @@
|
|
|
55
55
|
"test:em-dash-tool": "node test/test-validate-no-em-dash.js",
|
|
56
56
|
"test:install": "node test/test-installation-components.js",
|
|
57
57
|
"test:pack": "node test/test-pack-contents.js",
|
|
58
|
+
"test:private-tokens-tool": "node test/test-check-private-tokens.js",
|
|
58
59
|
"test:python": "uv run --with pytest==9.1.1 --with pytest-xdist==3.8.0 --with pyyaml==6.0.3 pytest skills/ultracode-goal/scripts/tests/ test/ -o \"python_files=test-*.py test_*.py *_test.py\" -n auto",
|
|
59
60
|
"test:rehype": "node test/test-rehype-markdown-links.js",
|
|
60
61
|
"test:skill-links": "node test/test-link-reference-skills.js",
|
|
@@ -136,7 +136,7 @@ each entry where `remediable: true`. The remediation per kind:
|
|
|
136
136
|
decomposed child is never scaffolded: it has no story file by design, and the kernel
|
|
137
137
|
already counts it covered by its parent's file when its row sits above the parent's
|
|
138
138
|
row and the parent row is `done`, or when the split removed the parent's row. So a
|
|
139
|
-
listed key whose id extends a parent's (`
|
|
139
|
+
listed key whose id extends a parent's (`55-0-a-i` of `55-0-a`) is a story of its own,
|
|
140
140
|
or a child the kernel found under a parent row that is not `done` or below a `done`
|
|
141
141
|
parent's row (the `detail` names each key below a `done` parent's row, with that row;
|
|
142
142
|
for a parent row that is not `done`, find the parent from the key's id). The split
|
|
@@ -308,7 +308,14 @@ The two dispositions are genuinely different things, not two names for one:
|
|
|
308
308
|
opens with "The moved-AC check refused (exit 2)" closes at once when it is the story's
|
|
309
309
|
first exit-2 refusal at that commit; when it says one came before at that commit, it
|
|
310
310
|
closes only once the operator confirms in writing that trace can write its files there,
|
|
311
|
-
and until then record `defer`.
|
|
311
|
+
and until then record `defer`. One that opens with "The operator-evidence check could not
|
|
312
|
+
read trace's coverage matrix" lists no AC and waits on no record: it closes at once when
|
|
313
|
+
it is the story's first such escalation at that commit, and the re-gate it owes runs
|
|
314
|
+
trace again, since the gate moved that cycle's trace files aside; when it says one came
|
|
315
|
+
before at that commit, it closes only once the operator confirms in writing that trace
|
|
316
|
+
can leave a coverage matrix the check can read there, with what its `evidence` names
|
|
317
|
+
fixed, and until then record `defer`.
|
|
318
|
+
An AC the escalation names as partly recorded, with the
|
|
312
319
|
ids of the records TEA
|
|
313
320
|
already counted for it, closes only on a `pass` record at that commit whose `id` is not
|
|
314
321
|
among the ones the escalation names, or on the operator's written narrowing or move of
|
|
@@ -36,7 +36,7 @@ Load config from `{project-root}/_bmad/config.yaml` and `config.user.yaml` (root
|
|
|
36
36
|
|
|
37
37
|
**Quick launch** (swap in your Epic id): `ultracode goal epic-7` — attended, production, sequential. `ultracode goal epic-7 --light --yes` — the expert one-liner: trace-only gate, no conversational stops. Add `-H` for headless, `--retro` for the close-out retrospective, `--max-stories 1` to take a single story this invocation.
|
|
38
38
|
|
|
39
|
-
**Resume.** The workspace is this skill's run folder holding `.decision-log.md`. An operator's request to run the health check for a run skips the resume offer and creates nothing: the operator names the Epic or its run folder (ask in an attended run when they name neither, and refuse in a headless one), refuse a folder that holds no `.decision-log.md`, and otherwise load `references/health-check.md` against that folder's log (Stages row 7). If one exists for the Epic, surface it with its last session date and offer to resume: the log recovers full state regardless of compaction. Otherwise create it at intent and append a session heading. **Route resume by the last stage the log reached**: the run folder is created at intent (Stage 1), so a prior run that blocked *before* Execute also leaves one. If the log carries gate verdicts, re-enter Execute at the first story whose last verdict is not advance (advanced stories are not re-run), re-asserting (not rebuilding) the Epic branch, hooks, allowlist, and the `.mem-state.json` recall latch first (the latch by minting this invocation's own run id as Stage 1 does, never reusing one an earlier invocation logged, and re-running Stage 1's `mem_recall.py latch` step with it, which replaces a latch another run left; `references/execute.md` says why each, and why the latch especially). That re-entry stops short when the story still carries an open escalation: the re-assertion sweep's story route then reads `decision-pending`, and the resume drives nothing (attended, offer `/ucg-resolve`; headless, end `blocked` with a `reason` naming its `escalation-<story_id>.json`; `references/execute.md` says what counts as open). If instead it blocked at Stage 1 (epic unresolved) or Stage 2 (preflight RED: the case an operator fixes then re-invokes), re-run from that stage so the hard preflight gate is never skipped. A re-run from Stage 2 first runs Stage 1's Cross-Session Recall section with a fresh run id (the latch and, on a green latch, its one filter call, whose output Stage 2 reads), since the blocked run's preflight STOP removed its latch. In headless (`-H`) never offer: auto-resume a not-all-done Epic by this same stage routing (a previously-preflight-RED Epic re-runs the gate, it does not enter Execute), delete any existing `{workflow.implementation_artifacts}/run-result.json` as soon as that scalar resolves exactly as a fresh run does (`references/ingest-and-scope.md`), and log the resume as an assumption. An Epic whose stories all read `done` while a story's `.evidence-owed-<story_id>` is on disk (its evidence commit, escalated as `evidence-commit-rejected`, is still owed, whether or not `/ucg-resolve` has closed that escalation) counts as not-all-done here and in Stage 1's already-done short-circuit: its resume re-enters Execute only for that commit, then goes to Finalize (`references/execute.md`'s resume rule). **A resume routed into Execute does NOT re-run the Stage-2 formalize gate.** That verdict is Stage 2's and it covers the run's whole in-scope set by construction (`formalize_check.py` reads every not-`done` story of the Epic, or the operator-scoped subset its `--story` flags name, never only the stories one invocation drives), so on any Epic with undrafted or later stories it reads `remediable`/`blocked` on gaps belonging to rows this invocation is not driving. Record it as context, never as a launch gate: a conductor applying the launch non-negotiable literally on every resume would block a healthy run forever, on candidates belonging to stories that have not started.
|
|
39
|
+
**Resume.** The workspace is this skill's run folder holding `.decision-log.md`. An operator's request to run the health check for a run skips the resume offer and creates nothing: the operator names the Epic or its run folder (ask in an attended run when they name neither, and refuse in a headless one), refuse a folder that holds no `.decision-log.md`, and otherwise load `references/health-check.md` against that folder's log (Stages row 7). If one exists for the Epic, surface it with its last session date and offer to resume: the log recovers full state regardless of compaction. Otherwise create it at intent and append a session heading. **Route resume by the last stage the log reached**: the run folder is created at intent (Stage 1), so a prior run that blocked *before* Execute also leaves one. If the log carries gate verdicts, re-enter Execute at the first story whose last verdict is not advance (advanced stories are not re-run), re-asserting (not rebuilding) the Epic branch, hooks, allowlist, and the `.mem-state.json` recall latch first (the latch by minting this invocation's own run id as Stage 1 does, never reusing one an earlier invocation logged, and re-running Stage 1's `mem_recall.py latch` step with it (that step alone, never Stage 1's filter call), which replaces a latch another run left; `references/execute.md` says why each, and why the latch especially). That re-entry stops short when the story still carries an open escalation: the re-assertion sweep's story route then reads `decision-pending`, and the resume drives nothing (attended, offer `/ucg-resolve`; headless, end `blocked` with a `reason` naming its `escalation-<story_id>.json`; `references/execute.md` says what counts as open). If instead it blocked at Stage 1 (epic unresolved) or Stage 2 (preflight RED: the case an operator fixes then re-invokes), re-run from that stage so the hard preflight gate is never skipped. A re-run from Stage 2 first runs Stage 1's Cross-Session Recall section with a fresh run id (the latch and, on a green latch, its one filter call, whose output Stage 2 reads), since the blocked run's preflight STOP removed its latch. In headless (`-H`) never offer: auto-resume a not-all-done Epic by this same stage routing (a previously-preflight-RED Epic re-runs the gate, it does not enter Execute), delete any existing `{workflow.implementation_artifacts}/run-result.json` as soon as that scalar resolves exactly as a fresh run does (`references/ingest-and-scope.md`), and log the resume as an assumption. An Epic whose stories all read `done` while a story's `.evidence-owed-<story_id>` is on disk (its evidence commit, escalated as `evidence-commit-rejected`, is still owed, whether or not `/ucg-resolve` has closed that escalation) counts as not-all-done here and in Stage 1's already-done short-circuit: its resume re-enters Execute only for that commit, then goes to Finalize (`references/execute.md`'s resume rule). **A resume routed into Execute does NOT re-run the Stage-2 formalize gate.** That verdict is Stage 2's and it covers the run's whole in-scope set by construction (`formalize_check.py` reads every not-`done` story of the Epic, or the operator-scoped subset its `--story` flags name, never only the stories one invocation drives), so on any Epic with undrafted or later stories it reads `remediable`/`blocked` on gaps belonging to rows this invocation is not driving. Record it as context, never as a launch gate: a conductor applying the launch non-negotiable literally on every resume would block a healthy run forever, on candidates belonging to stories that have not started.
|
|
40
40
|
|
|
41
41
|
## Non-negotiables
|
|
42
42
|
|
|
@@ -79,7 +79,9 @@ on_escalation = ""
|
|
|
79
79
|
# separate enabled toggle. (assets/module.yaml carries a test-pinned mirror of
|
|
80
80
|
# this default for BMad-core readers of module.yaml; this file is what the live
|
|
81
81
|
# run reads.)
|
|
82
|
-
# A repository on a host other than github.com is given as HOST/OWNER/REPO
|
|
82
|
+
# A repository on a host other than github.com is given as HOST/OWNER/REPO:
|
|
83
|
+
# log gh in to that host first, with gh auth login --hostname HOST, HOST in
|
|
84
|
+
# lower case and without a leading www.
|
|
83
85
|
# To send findings to another repository, create these labels there:
|
|
84
86
|
# health-check, workflow-improvement, bug, friction, gap, duplicate and
|
|
85
87
|
# possible-duplicate, and copy two files into it unchanged: the issue template,
|
|
@@ -88,6 +90,10 @@ on_escalation = ""
|
|
|
88
90
|
# https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/.github/workflows/health-check-dedup.yaml
|
|
89
91
|
# Without the labels the first create fails and the retry files the issue
|
|
90
92
|
# unlabeled; without the Action nothing labels it or closes a duplicate.
|
|
93
|
+
# On a host other than github.com the Action runs only once GitHub Actions is
|
|
94
|
+
# on there, its runs-on names one of the host's runners, the host can reach
|
|
95
|
+
# actions/github-script at the commit the Action pins, and those runners can
|
|
96
|
+
# run the Node version that commit's action.yml names in runs.using.
|
|
91
97
|
# Such a project must also set its own health_check_seen_cache: the cache keys
|
|
92
98
|
# each record by fingerprint alone, so two projects filing to different
|
|
93
99
|
# repositories would block or overwrite each other's records. The check only
|
|
@@ -112,13 +118,13 @@ health_check_queue_path = "{project-root}/_bmad-output/ultracode-goal/improvemen
|
|
|
112
118
|
# an unattended run has nobody to approve them, so each is refused
|
|
113
119
|
# and the finding queued. Allow them under [workflow] in
|
|
114
120
|
# {project-root}/_bmad/custom/ultracode-goal.toml (or .user.toml):
|
|
115
|
-
# allowlist_commands = ["gh auth status", "gh
|
|
121
|
+
# allowlist_commands = ["gh auth status", "gh issue list", "gh label create", "gh issue create"]
|
|
116
122
|
# Arrays append: the list above keeps every command it holds.
|
|
117
123
|
# Preflight writes each entry as an allow rule in
|
|
118
124
|
# .claude/settings.local.json, where it stays for every later session
|
|
119
125
|
# in the project: any agent there can then create issues and labels on
|
|
120
126
|
# any repository without asking. To keep them to the health-check
|
|
121
|
-
# repository, write "gh
|
|
127
|
+
# repository, write "gh issue list --repo <repo>",
|
|
122
128
|
# "gh label create --repo <repo>" and "gh issue create --repo <repo>",
|
|
123
129
|
# <repo> being health_check_repo. When you turn autosubmit off, drop the
|
|
124
130
|
# entries and delete their Bash(gh ...) rules from
|
|
@@ -8,7 +8,7 @@ Preconditions (asserted, not assumed): you are on the Epic branch (`{workflow.ep
|
|
|
8
8
|
|
|
9
9
|
**A decomposed child's ATDD run** (the precondition's case above) follows `references/define-done.md` step 2's rule for a decomposed child: under the child's own key, so the checklist the commit guard reads is the child's; the parent's story file read for the text of the parent ACs the child claims, never edited; and, on a halt over vague criteria, an escalation, never a `ucg-create-story` run for the child. The run is the child's own work: it comes after the child's step 0 (story loop, below) has written both the `.current-story` pointer and the child's baseline marker, and before step 1, so the Stop hook books its turns to the child. Step 0 is never split around it, pointer first and baseline after: the run commits nothing and leaves `HEAD` where it was, so the baseline step 0 records is the one the child starts from either way. Sizing still comes first ("Sizing: a story too large to drive" sizes the row ahead of step 0), so a child that is split again gets no run. In production, on a stack ATDD can run on, a resume that finds the child's `.baseline-<story_id>` still owes the run, before step 1, when `atdd-checklist-<child key>.md` is absent or a `generatedTestFiles` path it lists does not exist: an interrupted run can leave either.
|
|
10
10
|
|
|
11
|
-
**On resume, re-enter Execute at the first story whose last logged gate verdict is not advance; advanced stories are not re-run; re-assert (do not rebuild) the Epic branch, hooks, the allowlist, the `.mem-state.json` recall latch, and the in-flight story's baseline marker before continuing**, and read the story's recorded turn count before driving it ("Authoring the `/goal` condition" below says when a resumed count escalates instead). Before the next story's step 0, also check whether the last advanced story's gate evidence is still uncommitted, and if it is, make that evidence commit first, exactly as `references/gate.md`'s "Commit the gate's evidence before the next story starts" describes (and when that story advanced with its count at or past the turn ceiling and no sizing note was logged, log it now, per "Promoting the turn-budget marker"): a resume enters here, before Stage 5 is ever loaded, so this is where that rule has to be met. That story carries an `evidence-commit-rejected` escalation when a repo commit hook rejected that commit in a way the gate may not answer, so run the `--assert-armed` call below with `--story` naming that story first: while its `escalation` reads `open`, make no commit and take the `decision-pending` route below for that story, and once `/ucg-resolve` has closed it (its sidecar is gone, and `.evidence-owed-<story_id>` is still on disk), make the commit and remove that marker. Check every `.evidence-owed-<story_id>` of this Epic's stories this way, not only the last advanced story's: a marker whose evidence was committed some other way is removed as `references/gate.md` says, with no commit. When that story is the Epic's last, so every story reads `done`, no story is left to drive: after the commit go to Stage 6 (`references/finalize.md`) with the Epic-level verdict the log holds, and run neither a story nor the Epic-level gate again. Stage 1 resolved no in-scope story for that resume, so Finalize passes that story as its one `--story` to `scripts/gate_trail.py`, whose range then ends at the commit this resume made, and the run report names the route as the owed evidence commit made and the Epic complete. Before the next story's step 0, or before Stage 6 on that route, remove `.scratch-<story_id>/` of each story of this Epic whose row is already `done` (`references/gate.md`, "Commit the gate's evidence before the next story starts"): a run that stopped after that story's evidence commit, or with nothing staged for it, left the folder there. And "re-assert the hooks" means preflight step 5's assertion, not a presence check: both script paths appear in the resolved settings **and** the PreToolUse group's matcher is the all-tools form (`references/preflight.md`, "Arm the PreToolUse group with a matcher that covers EVERY tool"). A presence-only read passes on a prior run's `Bash`-only arming, and a resume that skips Stage 2 never meets the bullet where that requirement lives, so this is the one place it binds a resumed run, and without it the Cross-Session Recall invariant enforces nothing outside Bash for the whole session while every log line says the hooks are armed. The latch is *re-written* by re-running Stage 1's latch step (`references/ingest-and-scope.md`, its `mem_recall.py latch` command) with this invocation's own run id, minted first by Stage 1's convention and logged. A resume never reuses an id an earlier invocation logged: the run's record file is named after it and never rewritten, so a reused id turns this run's Finalize write into `skipped-existing` and loses its record. It is re-written because every terminal removes it with `mem_recall.py unlatch` (Stage 6 at every close-out), and the PreToolUse hook reads an absent latch as "no run active" and stops gating recall entirely. A latch already on disk whose `run_id` is not this run's is **another run's (or a spawning wrapper's) artifact, never evidence**: re-latch from this run's own measurement, which replaces it, and never inherit its `store_ok` colour, because an inherited green latch certifies a store this run never checked. Never delete that latch to make room for this run's: the guard refuses it while a latch is present, and the latch command is what replaces it. The baseline marker is the opposite of the latch, split by which case the resume is, and the test is simply whether `.baseline-<story_id>` exists. **Mid-story (it exists):** *re-read* and never regenerate: the story may already carry commits, and a rebuilt baseline silently re-anchors its evidence range to a mid-story HEAD. **Story boundary (it does not exist**, the NORMAL case under `--max-stories N`, where every invocation after the first resumes at a fresh story): there is nothing to re-read; write it fresh at `HEAD` exactly as step 0 does for a first-run story, because the PreToolUse marker-freshness gate fail-closes without it.
|
|
11
|
+
**On resume, re-enter Execute at the first story whose last logged gate verdict is not advance; advanced stories are not re-run; re-assert (do not rebuild) the Epic branch, hooks, the allowlist, the `.mem-state.json` recall latch, and the in-flight story's baseline marker before continuing**, and read the story's recorded turn count before driving it ("Authoring the `/goal` condition" below says when a resumed count escalates instead). Before the next story's step 0, also check whether the last advanced story's gate evidence is still uncommitted, and if it is, make that evidence commit first, exactly as `references/gate.md`'s "Commit the gate's evidence before the next story starts" describes (and when that story advanced with its count at or past the turn ceiling and no sizing note was logged, log it now, per "Promoting the turn-budget marker"): a resume enters here, before Stage 5 is ever loaded, so this is where that rule has to be met. That story carries an `evidence-commit-rejected` escalation when a repo commit hook rejected that commit in a way the gate may not answer, so run the `--assert-armed` call below with `--story` naming that story first: while its `escalation` reads `open`, make no commit and take the `decision-pending` route below for that story, and once `/ucg-resolve` has closed it (its sidecar is gone, and `.evidence-owed-<story_id>` is still on disk), make the commit and remove that marker. Check every `.evidence-owed-<story_id>` of this Epic's stories this way, not only the last advanced story's: a marker whose evidence was committed some other way is removed as `references/gate.md` says, with no commit. When that story is the Epic's last, so every story reads `done`, no story is left to drive: after the commit go to Stage 6 (`references/finalize.md`) with the Epic-level verdict the log holds, and run neither a story nor the Epic-level gate again. Stage 1 resolved no in-scope story for that resume, so Finalize passes that story as its one `--story` to `scripts/gate_trail.py`, whose range then ends at the commit this resume made, and the run report names the route as the owed evidence commit made and the Epic complete. Before the next story's step 0, or before Stage 6 on that route, remove `.scratch-<story_id>/` of each story of this Epic whose row is already `done` (`references/gate.md`, "Commit the gate's evidence before the next story starts"): a run that stopped after that story's evidence commit, or with nothing staged for it, left the folder there. And "re-assert the hooks" means preflight step 5's assertion, not a presence check: both script paths appear in the resolved settings **and** the PreToolUse group's matcher is the all-tools form (`references/preflight.md`, "Arm the PreToolUse group with a matcher that covers EVERY tool"). A presence-only read passes on a prior run's `Bash`-only arming, and a resume that skips Stage 2 never meets the bullet where that requirement lives, so this is the one place it binds a resumed run, and without it the Cross-Session Recall invariant enforces nothing outside Bash for the whole session while every log line says the hooks are armed. The latch is *re-written* by re-running Stage 1's latch step (`references/ingest-and-scope.md`, its `mem_recall.py latch` command) with this invocation's own run id, minted first by Stage 1's convention and logged. The resume re-runs that latch step alone, never Stage 1's filter call: it reads no prior run, so this invocation consumes no record and Finalize passes no `--advisory` for it (`references/finalize.md`, "Cross-Session Recall write"). A resume never reuses an id an earlier invocation logged: the run's record file is named after it and never rewritten, so a reused id turns this run's Finalize write into `skipped-existing` and loses its record. It is re-written because every terminal removes it with `mem_recall.py unlatch` (Stage 6 at every close-out), and the PreToolUse hook reads an absent latch as "no run active" and stops gating recall entirely. A latch already on disk whose `run_id` is not this run's is **another run's (or a spawning wrapper's) artifact, never evidence**: re-latch from this run's own measurement, which replaces it, and never inherit its `store_ok` colour, because an inherited green latch certifies a store this run never checked. Never delete that latch to make room for this run's: the guard refuses it while a latch is present, and the latch command is what replaces it. The baseline marker is the opposite of the latch, split by which case the resume is, and the test is simply whether `.baseline-<story_id>` exists. **Mid-story (it exists):** *re-read* and never regenerate: the story may already carry commits, and a rebuilt baseline silently re-anchors its evidence range to a mid-story HEAD. **Story boundary (it does not exist**, the NORMAL case under `--max-stories N`, where every invocation after the first resumes at a fresh story): there is nothing to re-read; write it fresh at `HEAD` exactly as step 0 does for a first-run story, because the PreToolUse marker-freshness gate fail-closes without it.
|
|
12
12
|
|
|
13
13
|
**The cursor passes over a decomposed parent.** A story whose row is `done` and whose split is recorded (its split record (`.split-<key>.json` beside `sprint-status.yaml`) names it, a child row cites the parent ACs it claims, or `.decision-log.md` names it and the ACs each child claims) never gets a gate verdict of its own: its children carry its contract, and on its split record the Epic-level roll-up reads their gates in its place (`references/gate.md`). So it is never "a story whose last logged gate verdict is not advance" in the sense above: pass over it and re-enter at the next story, and never drive it. This is the shape a sizing decomposition leaves (below): the invocation that split the row ends without a verdict, the next one re-enters at the first child, since the child rows sit above the parent's, and once every child has advanced the cursor reaches the parent's row and passes over it. A `done` row with no recorded split is not passed over on this rule; Stage 1 rule 3's `skipped-already-done` log is what keeps a fresh run from re-driving one.
|
|
14
14
|
|
|
@@ -34,7 +34,7 @@ Preconditions (asserted, not assumed): you are on the Epic branch (`{workflow.ep
|
|
|
34
34
|
|
|
35
35
|
### Sizing: a story too large to drive
|
|
36
36
|
|
|
37
|
-
**Before step 0 writes any marker, size the row.** Count its acceptance criteria and tasks. **Take that set from the ROW, not from a neighbour's prose.** The `sprint-status.yaml` row is the authority on *which* acceptance criteria a story owes; the story file it cites (its own, or the parent it was split from) is only where those criteria's text lives. A decomposed child has no story file of its own by the convention below, so its contract exists solely as the criteria its row cites. A sibling's ledger entry, or a decision-log entry, names what that sibling **handed off** (a different set, with no reason to be complete), and a scope read from one undersizes the row here and under-delivers it at step 1. Nothing downstream catches that: the trace, the gate-decision file and the gate verdict are all written from this same reading, so they come out green over a missing criterion by construction. When the count is implausible against `{workflow.max_turns_per_story}`, **do not start the story**: decompose it into child rows and terminate the invocation. "Implausible" has a first-pass test, not just a judgment: **when the row's acceptance-criteria count reaches roughly half of `{workflow.max_turns_per_story}`, treat the row as implausible** (13 criteria at the default 25). Count the tasks too, as evidence for the tie-break and the override, but keep them out of the threshold: a task list is how its author sliced the work, and it also holds steps every row pays (reading the skills, running the gates, a step the operator owns). Criteria plus tasks flagged 25 of one real Epic's 30 rows and 4 of another's 5, and nearly every flagged row was then driven whole. The threshold sizes what the story owes; it is not a forecast of turns. The Stop hook counts one turn per response ("Waiting spends turns" below), so the turns a story spends follow how its drive waits, not how many criteria it closes: drives that ran each stage as one delegated workflow took rows of 9 and 13 criteria to their gates in 6 and 7 turns, a 3-criterion row whose sweeps and suite runs each cost turns passed the ceiling twice over, and a `scripts/drive_epic.py` spawn is usually one long response per story. Tie-break against this Epic's own record: the criteria counts of rows already driven cleanly versus rows already split; a row matching an already-split parent's shape is answered by that precedent. The tie-break reads no turn counts. The turns a row spends follow how its drive waits, as above, and no record holds the turns a driven row used: `/ucg-resolve` resets or deletes its `.budget-<story_id>.json` when it closes a `budget-overrun` or `operator-evidence-owed` escalation, and the Stop hook adds each response of a later session to the story `.current-story` still names, so that file, and a count logged from it beside a gate verdict, can hold fewer turns than the row used or more. The judgment word stays as the override in both directions (a count under the threshold can still be implausible when each AC owes an executed artifact; over it can be plausible when the ACs are one-line checklist items), but an override is a recorded reason in `.decision-log.md`, never the whole method: two conductors meeting the same row must be able to reach the same verdict.
|
|
37
|
+
**Before step 0 writes any marker, size the row.** Count its acceptance criteria and tasks. **Take that set from the ROW, not from a neighbour's prose.** The `sprint-status.yaml` row is the authority on *which* acceptance criteria a story owes; the story file it cites (its own, or the parent it was split from) is only where those criteria's text lives. A decomposed child has no story file of its own by the convention below, so its contract exists solely as the criteria its row cites. Any other row with no story file has not been drafted, so it has no criteria to count yet: it fails Stage 3's exit condition, which binds every profile (`references/define-done.md`: every in-scope story has a story file with clear acceptance criteria), and a resume that enters this stage from the log never re-checks it. Send that row alone back to Stage 3, never every in-scope story: Stage 3's `ucg-create-story` drafts its story file (and, in production on a stack ATDD can run on, `bmad-testarch-atdd` scaffolds its red phase) before step 0 writes any marker, and the draft's criteria are then the set this section counts. A sibling's ledger entry, or a decision-log entry, names what that sibling **handed off** (a different set, with no reason to be complete), and a scope read from one undersizes the row here and under-delivers it at step 1. Nothing downstream catches that: the trace, the gate-decision file and the gate verdict are all written from this same reading, so they come out green over a missing criterion by construction. When the count is implausible against `{workflow.max_turns_per_story}`, **do not start the story**: decompose it into child rows and terminate the invocation. "Implausible" has a first-pass test, not just a judgment: **when the row's acceptance-criteria count reaches roughly half of `{workflow.max_turns_per_story}`, treat the row as implausible** (13 criteria at the default 25). Count the tasks too, as evidence for the tie-break and the override, but keep them out of the threshold: a task list is how its author sliced the work, and it also holds steps every row pays (reading the skills, running the gates, a step the operator owns). Criteria plus tasks flagged 25 of one real Epic's 30 rows and 4 of another's 5, and nearly every flagged row was then driven whole. The threshold sizes what the story owes; it is not a forecast of turns. The Stop hook counts one turn per response ("Waiting spends turns" below), so the turns a story spends follow how its drive waits, not how many criteria it closes: drives that ran each stage as one delegated workflow took rows of 9 and 13 criteria to their gates in 6 and 7 turns, a 3-criterion row whose sweeps and suite runs each cost turns passed the ceiling twice over, and a `scripts/drive_epic.py` spawn is usually one long response per story. Tie-break against this Epic's own record: the criteria counts of rows already driven cleanly versus rows already split; a row matching an already-split parent's shape is answered by that precedent. The tie-break reads no turn counts. The turns a row spends follow how its drive waits, as above, and no record holds the turns a driven row used: `/ucg-resolve` resets or deletes its `.budget-<story_id>.json` when it closes a `budget-overrun` or `operator-evidence-owed` escalation, and the Stop hook adds each response of a later session to the story `.current-story` still names, so that file, and a count logged from it beside a gate verdict, can hold fewer turns than the row used or more. The judgment word stays as the override in both directions (a count under the threshold can still be implausible when each AC owes an executed artifact; over it can be plausible when the ACs are one-line checklist items), but an override is a recorded reason in `.decision-log.md`, never the whole method: two conductors meeting the same row must be able to reach the same verdict.
|
|
38
38
|
|
|
39
39
|
Nothing else in this stage covers that case, and the two routes it seems to offer are both wrong. Driving it reaches the turn bound with a baseline marker and a tests-ran marker on disk and no commit, which is exactly the abandoned-mid-story outcome the work bound below exists to avoid. Escalating reaches the same conclusion having first spent the whole budget proving what an AC count showed in five minutes. **A decomposition writes no baseline and no tests-ran marker at all**, so the abandoned-story shape cannot arise from it.
|
|
40
40
|
|
|
@@ -66,7 +66,7 @@ For each in-scope story, in sprint order, run this loop (leave out a decomposed
|
|
|
66
66
|
|
|
67
67
|
**Evidence never goes in scratch.** The scratch directory is removed when the story advances, while the story record and the gate trail (`references/finalize.md`) cite their evidence after that, so the story's evidence has a folder of its own, `{workflow.implementation_artifacts}/evidence-<story_id>/`, which no step removes. The red-phase capture (step 1's, on a stack where Stage 3 could not generate the ATDD scaffold), a sweep log the record or the gate cites, a coupled-stories measurement and a planted-defect run (a case shown red against a defect planted for it) go there; a runner or harness built only to produce them stays in scratch. It holds captured output and the notes recorded on it (the red count `references/gate.md`'s non-web item 4 records beside a red-phase capture), nothing runnable: it has no dot prefix, so on a tracked tree a repo-wide tool can reach it. The mutation ledger keeps its own name-pinned path (step 2). Name each capture by the step that wrote it and the commit `HEAD` named when it ran (`sweep-step2-<short sha>.log`, `sweep-step5-<short sha>.log`, `sweep-backfill-<short sha>.log`), and give a name already taken the next free number (`-2`), so no capture overwrites another: step 2's sweep can run at the `HEAD` the cycle before it measured at step 5 (when that cycle's gate committed no backfill), and the backfill's sweep runs at the `HEAD` step 5 measured. A file already in the folder when step 0 writes a fresh baseline is an earlier run's, never cited as this run's. On a tracked artifact tree the folder stays untracked, as the mutation ledger does: the gate's evidence commit stages its own list of paths, and this folder is not on it.
|
|
68
68
|
|
|
69
|
-
1. `ucg-create-story`
|
|
69
|
+
1. `ucg-create-story` as a refinement of the story file Stage 3 drafted, when that file is not already current (never to draft a missing one: sizing, above, sends a row with no story file back to Stage 3 before step 0) → `ucg-dev-story` implementing the feature and **un-skipping** the story's ATDD acceptance tests (remove `test.skip()`; **production only**): under `--light` there are no ATDD tests to un-skip, so the DoD is the story's acceptance criteria satisfied with lint and build green. The commit guard reads the story's acceptance-test files from the checklist's `generatedTestFiles` frontmatter, so a test file the story adds to hold acceptance cases (a scaffolded file split in two, say) goes into that list as a repo-relative path. **For a decomposed child row, skip `ucg-create-story` entirely**: the child has no story file and must never get one (running the sub-skill would duplicate the contract, which the sizing conventions above forbid); its owed criteria are its sprint-status row comment plus the parent story file it cites by AC number, and the parent file is read for the AC text only, with its Dev Notes as guidance. Pass both story skills `implementation_artifacts` set to `{workflow.implementation_artifacts}` on every call, so the story file and the sprint-status row they touch are the ones this run reads. Hand `ucg-dev-story` the child's input in place of a story path: `story_key` the child's row key, `parent_story_path` the parent's story file, and `claimed_acs` the parent AC ids the child's row claims, taken from the row as the sizing section above requires. On a re-loop, also hand it `review_findings`: the `reasons` of the gate verdict that sent the child back and the findings of that cycle's reviews, which no review can write into a story file the child does not have. Its "Decomposed Child" section keeps it to those ACs, has it write no story file, and has it move only the child's row (to `in-progress`, then `review`), so the parent's row stays `done` and the parent's file unedited. A halt there over a claimed AC takes the sub-skill halt catch-all's route below, naming the parent ACs concerned: never a `ucg-create-story` run for the child, and never an edit to the parent's file. **On a stack where Stage 3 could not generate the ATDD scaffold** (the non-web case), the story still owes a red phase and it is owed **now, before the first implementation edit**: author the acceptance cases with real assertions, RUN them, and capture that run's raw output to a file in `{workflow.implementation_artifacts}/evidence-<story_id>/` ("Evidence never goes in scratch", above). `references/gate.md`'s non-web section is the authority on the shape, but by the time that file is read at Stage 5 the window this rule governs has already closed. Before delegating, check the run's `.decision-log.md` for an **Operator notes** entry naming this story (a pre-launch hint like "watch the auth flow in story 3") and surface that note into the `ucg-dev-story` / review context for this story so the operator's last words actually reach the work. Read `{workflow.implementation_artifacts}/.class-ledger-<epic_id>.md` the same way when it exists (the defect classes this Epic's reviews have already caught, appended by the gate's re-loop route, `references/gate.md`) and surface it into the same context: a class named there is a class the reviewers will look for again, and code written blind to it is a re-loop pre-booked. (A story otherwise inherits nothing from its siblings' reviews: a measured run re-found the previous story's review finding on its very first cycle, so the ledger is the one artifact that crosses that boundary.)
|
|
70
70
|
**On a gitignored artifact tree** (`impl_artifacts_tracked: false`, which preflight step 1 reports and a resumed session reads in its `--assert-armed` manifest's `checks`), no test this story writes or un-skips may read a file under that tree, or any other path `git check-ignore` reports, at run time: it does not exist in CI. Point the test at a tracked fixture instead. Preflight step 2 states the rule ("A gitignored artifact tree"); a session that resumed straight into this stage may not have read it.
|
|
71
71
|
|
|
72
72
|
**An operator-evidence AC is not `ucg-dev-story`'s to satisfy.** When the story carries an AC tagged `**Gate-ability:** operator-evidence` (`references/define-done.md`, step 1), say so when you hand it the story: that AC is proven at the gate by a live result a person records (`references/gate.md`), so it builds nothing for it and does not hold the story's completion on it. An AC tagged plain `**Gate-ability:** operator` is not one: it is work `ucg-dev-story` builds like any other AC, which a person or a script then verifies.
|
|
@@ -88,7 +88,7 @@ For each in-scope story, in sprint order, run this loop (leave out a decomposed
|
|
|
88
88
|
|
|
89
89
|
**A re-loop iteration may scope the sweep; the cycle that expects to advance owes the full one.** The first pass through this loop runs the full three-axis sweep above. A story re-entered from a `reloop` verdict may instead run the affected set — the changed package(s) *and their dependents*, computed against the story's last recorded commit (`{workflow.implementation_artifacts}/.commit-<story_id>`, the previous cycle's end marker): e.g. turbo's `--filter=...[<that sha>]`, still cache-defeated, still with raw output printed. Two obligations keep the scoped form honest. **Print the resolved package list** — the runner computes it; copy its own output into the transcript and the marker's `packages=` line, because a wrong baseline ref narrows coverage *silently*, and the printed list is the only place a narrowing shows. And **write the marker with `scope=scoped`**, so the record says which form ran — a scoped sweep reported as a full one is the same class of false claim reviews keep finding elsewhere. When the re-loop believes its findings are closed and the next gate should advance, run the full sweep and write `scope=full`: the gate refuses to advance a story off a `scope=scoped` marker (`references/gate.md`, the sweep-scope AND), so a scoped cycle that unexpectedly goes fully green costs one extra full-sweep cycle rather than producing an advance nothing re-proved. When in doubt, run it full — `scope=full` is never wrong, only slower. (Measured, on a seven-cycle story: the whole-repo cache-defeated sweep re-proved untouched packages seven times, roughly six of every eight sweep minutes; this split is that cost's fix, at no loss of gate authority. A repo whose runner cannot compute an affected set simply keeps running the full sweep — the scoped form is an optimisation, never an obligation.)
|
|
90
90
|
|
|
91
|
-
**A wide sweep is also a loaded machine.** Running every language's suite plus the declared gate set, cache-defeating, means suites share a host with concurrent native builds
|
|
91
|
+
**A wide sweep is also a loaded machine.** Running every language's suite plus the declared gate set, cache-defeating, means suites share a host with concurrent native builds, and a case bounded by a wall-clock timeout can fail from contention alone (measured: a 180-second-bounded case took 197s beside a concurrent `cargo test` + clippy + type-check, and 93s alone). A timeout in a wide sweep is therefore not yet a red: re-run that package in isolation before treating it as one, and where the two can be sequenced, do not schedule a long native build beside a wall-clock-bounded suite. Run each isolation run once, on its own (one package at a time, with no other suite or build this run started still running), at the same tree, changing nothing between the sweep and it, cache-defeated, with the test command and time bound the sweep gave that package: a raised bound, an edited test, a cached result or a second attempt proves nothing about contention. Keep that sweep's capture in `evidence-<story_id>/`, and capture the isolation run there too as `isolation-<step>-<short sha>.log`, named by the step whose sweep timed out and the `HEAD` that sweep ran at (`isolation-step2-<short sha>.log`, `isolation-step5-<short sha>.log`, `isolation-backfill-<short sha>.log`), a name already taken getting the next free number ("Evidence never goes in scratch", above): its stem is not `sweep-`, so it is never read as the numbered capture of a second sweep. When that package then passes in isolation, the timeout puts no red in that sweep, so a sweep that ran every task it scheduled and whose only reds were such timeouts is its step's green: step 2 writes its marker from that sweep, and a gate step that writes one after its sweep by its own rule (`references/gate.md`: the backfill's step 3 once its sweep is green, a cap-only re-loop's `scope=full` refresh) writes it from that sweep too; at step 5 the marker stands, and step 5 commits nothing for it. For each such pass, log one `timeout:` line in `.decision-log.md` naming the package, the `HEAD` the sweep ran at, the sweep's capture and the isolation run's capture; the timeout owes no `flaky:` line of its own and no row to `{workflow.deferred_work_path}`, since contention on the host is not deferred work. A sweep that left tasks unrun (a runner that stops at its first failure, turbo without `--continue` say) and whose only reds were timeouts is no green yet: before any isolation run, run it once more at the same tree and scope, cache-defeated, with every task run, captured under the next free number, and read that sweep instead; at the gate's backfill that re-run is no fix, so it counts toward neither of its two fixes. When that package fails in isolation too, the timeout is that sweep's red, and takes its step's route.
|
|
92
92
|
|
|
93
93
|
**A red the story's changes do not explain is not yet a red either.** In any wide sweep this file or `references/gate.md` runs (this step's, step 5's, and each sweep the gate runs as step 5 runs it), a failing case that is not a timeout (the paragraph above rules a timeout) is not yet this story's red when all three of these hold: its test file appears in neither `git diff --name-only --no-renames <the sha in .baseline-<story_id>>` (which lists both sides of a rename) nor `git status --porcelain --untracked-files=all`; its captured failure names no path either command lists; and the output shows the failure's cause inside that test, such as a random value the test draws that hit a string it asserts is absent, or a date or clock boundary. A failure that shows state another test left behind (the order the cases ran in, a shared fixture, a leftover file or port) does not qualify, since this story's own tests can leave that state. For a case that qualifies, keep that sweep's capture, change nothing, and run the same sweep once more at the same tree and scope, cache-defeated, captured under the next free number ("Evidence never goes in scratch", above). Running the case alone does not answer it: a case can pass alone and fail in the sweep on state another test leaves behind. When that second sweep shows no red at all, it is the step's green: log a `flaky:` line in `.decision-log.md` naming the case, its file, the `HEAD` both sweeps ran at (at step 2 the story's changes are uncommitted: they sit on that `HEAD`, untouched between the two sweeps), the cause the output shows and both captures; append a row for the case to `{workflow.deferred_work_path}`, worded as a non-critical finding (`references/gate.md`, "Deferred-work ledger schema"), with `source` `sweep`, `severity` `med`, `story` this story's id, a `reason` naming the case, its file and both captures, a `suggested_action` to fix the test outside this Epic's stories, and `status` `open`; and edit, skip or retry-wrap nothing in that file, which is not this story's to change. Step 2 then writes its marker from that second sweep, and a gate step that writes one after its sweep by its own rule (`references/gate.md`: the backfill's step 3 once its sweep is green, a cap-only re-loop's `scope=full` refresh) writes it from that second sweep too. At step 5 nothing has changed, so commit nothing (the guard refuses a commit whose staged index is empty): the marker stands as it does after a green first try. A timeout in the second sweep still takes the paragraph above first, as a timeout in any wide sweep does, before it is read as that sweep's red. When that package then passes in isolation, the timeout puts no red in the second sweep, and the `flaky:` line and the ledger row cite that isolation run's capture beside both sweeps' captures. Any red in the second sweep, in that case or in another, is a red, and takes its step's route.
|
|
94
94
|
|
|
@@ -165,7 +165,7 @@ It is a single JSON object, exactly these four string fields and no fifth:
|
|
|
165
165
|
|
|
166
166
|
One object, never an array: the file is already named per story, so a list would only re-encode the story id inside a file that carries it in its name.
|
|
167
167
|
|
|
168
|
-
`kind` is **open vocabulary**. A reader renders whatever string it finds and never validates it against a fixed list, in particular never against the red-kind vocabulary the semantic scan returns in `references/preflight.md`, which classifies *planning-artifact* reds and has no term for anything that happens at run time. `budget-overrun` is a live `kind` and sits deliberately outside that vocabulary; a reader that validated against it would silently drop the most common escalation there is. `operator-evidence-owed` is a live `kind` too: the story is delivered and gated except evidence only a person can record (`references/gate.md`). So is `evidence-commit-rejected`: the story advanced, and a repo commit hook rejected its evidence commit in a way the gate may not answer, so that evidence waits, uncommitted, for the operator (`references/gate.md`'s advance route). So is `coupled-stories`: the earlier of two stories that are green only together owes clauses only the later story's build satisfies, and moving them narrows its AC, which only the operator may rule on (the story loop's "Two stories green only together").
|
|
168
|
+
`kind` is **open vocabulary**. A reader renders whatever string it finds and never validates it against a fixed list, in particular never against the red-kind vocabulary the semantic scan returns in `references/preflight.md`, which classifies *planning-artifact* reds and has no term for anything that happens at run time. `budget-overrun` is a live `kind` and sits deliberately outside that vocabulary; a reader that validated against it would silently drop the most common escalation there is. `operator-evidence-owed` is a live `kind` too: the story is delivered and gated except evidence only a person can record, or the gate could not check that, because the operator-evidence check could not read trace's coverage matrix or the check after a move refused (`references/gate.md`). So is `evidence-commit-rejected`: the story advanced, and a repo commit hook rejected its evidence commit in a way the gate may not answer, so that evidence waits, uncommitted, for the operator (`references/gate.md`'s advance route). So is `coupled-stories`: the earlier of two stories that are green only together owes clauses only the later story's build satisfies, and moving them narrows its AC, which only the operator may rule on (the story loop's "Two stories green only together").
|
|
169
169
|
|
|
170
170
|
**An escalated story keeps no gate build.** The gate carries its worktree's build folders into `<stash>` only for a story it will gate again (`references/gate.md`, the first caveat under "Measure the commit, not the working tree", which says what `<stash>` is), and an escalation stops the story instead, whatever route it came by. So whenever you are about to write this sidecar and `<stash>` holds a build folder, run `uv run {skill-root}/scripts/carry_build_cache.py drop --stash <stash>` right before you write it, so a session that ends between the two leaves no build behind a story it escalated. It deletes each folder `<stash>` holds, never through a link, and prints what it deleted, skipped and failed to delete; log that in `.decision-log.md` beside the escalation. The story's re-gate, once the operator answers, builds cold.
|
|
171
171
|
|
|
@@ -213,7 +213,7 @@ When the prior snapshot's `budget_used.turns` and the current `.budget-<story>.j
|
|
|
213
213
|
|
|
214
214
|
Before the Stop hook has fired for a story, no `.budget-<story>.json` exists yet. That is a normal early-story state, not an error: render `budget_used` as `{"turns": 0, "max_turns": <the resolved ceiling>}` and write the snapshot anyway — an absent hook file is never a reason to skip the write, defer it, or leave the heartbeat partially written.
|
|
215
215
|
|
|
216
|
-
**A resume writes its first heartbeat at re-entry, before step 0 of the story it is about to drive
|
|
216
|
+
**A resume writes its first heartbeat at re-entry, before step 0 of the story it is about to drive**: `story` naming that story, its `stories` entry at `phase` `"resuming"`, `verdict` null. Until that write the file still holds the prior invocation's terminal snapshot, and everything a resume does before the loop (branch and hook re-assertion, the latch, a grounding read) is real work during which a poller would otherwise be watching a stale terminal. `budget_used.turns` legitimately stays put through all of it (at `0` for a story not yet driven, at the inherited count for a mid-story resume), because the hook counts only Stops booked to the current story: an unmoved count beside a fresh `updated` is a conductor re-asserting the environment, not a stalled run. The poller's liveness signal is `updated` and `phase`, never `turns` alone.
|
|
217
217
|
|
|
218
218
|
This is the file the Stage 2 launch briefing points the operator at ("where to watch"); Stage 6 (finalize) records the terminal state into it when the run closes, carrying every key above forward rather than overwriting the file with a narrower object.
|
|
219
219
|
|
|
@@ -76,7 +76,7 @@ Whichever case applies, repeat in the run report a `NOTE recall-latch-visible` l
|
|
|
76
76
|
uv run {skill-root}/scripts/mem_observation.py write --impl-artifacts {workflow.implementation_artifacts} --store '{workflow.cross_session_recall_store}' --project-root {project-root} --epic <id> --run-id <run-id> --gate-status <status> --verdict <advance|blocked> --deferred {workflow.deferred_work_path} [--root-cause class=<taxonomy>,path=<artifact>]… [--advisory sig=<record-id>]…
|
|
77
77
|
```
|
|
78
78
|
|
|
79
|
-
Each `--advisory` names one record this invocation's own Stage 1 filter call consumed: `sig` is that record's `id`, the `run_id` of the run that wrote it, copied as given from the attributed advisory Stage 1 logged to `.decision-log.md` (the same `id` the record carries in `recall-filter-<run-id>.json`, when Stage 1 wrote that file). It is never a root-cause signature, a story id or this run's own run id. Pass no `recurred`: the script decides it from the store. It stores `yes` when a root cause whose class is not `other` is in both that record and this run (the same class and artifact path), `no` when that record names such a root cause and this run shares none of them, and `unknown` otherwise: the `id` is not a run id, that record cannot be read or is not this repo's, it names no root cause outside `other`, or this run did not advance and names no root cause (a handoff or a `decision-pending` stop). A matching gate status or verdict is not a recurrence, and preflight's `advisories_checked` status does not feed `recurred`. Pass no `--advisory` on a resume routed into Execute, which makes no filter call, nor when this invocation's filter call was skipped, refused or failed, or consumed no record.
|
|
79
|
+
Each `--advisory` names one record this invocation's own Stage 1 filter call consumed: `sig` is that record's `id`, the `run_id` of the run that wrote it, copied as given from the attributed advisory Stage 1 logged to `.decision-log.md` (the same `id` the record carries in `recall-filter-<run-id>.json`, when Stage 1 wrote that file). It is never a root-cause signature, a story id or this run's own run id. Pass no `recurred`: the script decides it from the store. It stores `yes` when a root cause whose class is not `other` is in both that record and this run (the same class and artifact path), `no` when that record names such a root cause and this run shares none of them, and `unknown` otherwise: the `id` is not a run id, that record cannot be read or is not this repo's, it names no root cause outside `other`, or this run did not advance and names no root cause (a handoff or a `decision-pending` stop). A matching gate status or verdict is not a recurrence, and preflight's `advisories_checked` status does not feed `recurred`. Pass no `--advisory` on a resume routed into Execute, which makes no filter call under `references/execute.md`'s resume rule (that resume re-runs Stage 1's latch step alone), nor when this invocation's filter call was skipped, refused or failed, or consumed no record.
|
|
80
80
|
|
|
81
81
|
Each call prints one JSON object. Log every line in its `notes` to `.decision-log.md` and carry it into the run report: the `mem-` tokens belong to the write path (`WARN mem-write-deferred` when the store could not take the record and it waits in the outbox for a later drain, `WARN mem-write-dead-lettered` when a parked record failed its third write and moved to `mem-outbox.dead.jsonl`, which no drain replays, `NOTE mem-target-foreign`, `NOTE mem-run-id-invalid`, `NOTE mem-legacy-unconvertible`), and `NOTE recall-store-unset` means the store key is unset. Log the write's `status` the same way: `written`, or why no record landed (`skipped-existing`, `deferred`, `foreign-target`, `skip`, `no-fingerprint` or `store-unset`), since some of those print no note. Print the drain's `converted`, `legacy_unconvertible`, `dead_lettered` and `tombstones` counts in the run report too. If the permission layer refuses the drain or the write call, log `NOTE recall-write-refused`, do not retry it, and continue: a refused write never reaches the script, so nothing is parked. If the drain or the write call exits non-zero, log what it printed to `.decision-log.md` and the run report, do not retry it, and go on: to the write after a failed drain, and to the close-out below after a failed write. Recall is advisory, so a failed call never stops the run. The run report always lands; the record is best-effort.
|
|
82
82
|
|