bmad-module-ultracode-goal 3.0.0 → 3.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/docs/architecture.md +1 -0
- package/docs/cross-session-recall.md +1 -1
- package/docs/gate-model.md +4 -0
- package/docs/how-it-works.md +3 -3
- package/docs/troubleshooting.md +2 -2
- package/package.json +1 -1
- package/skills/ucg-resolve/SKILL.md +29 -0
- package/skills/ultracode-goal/SKILL.md +1 -1
- package/skills/ultracode-goal/references/define-done.md +5 -1
- package/skills/ultracode-goal/references/execute.md +20 -5
- package/skills/ultracode-goal/references/finalize.md +2 -2
- package/skills/ultracode-goal/references/gate.md +16 -6
- package/skills/ultracode-goal/references/ingest-and-scope.md +2 -0
- package/skills/ultracode-goal/references/preflight.md +5 -3
- package/skills/ultracode-goal/scripts/drive_epic.py +10 -4
- package/skills/ultracode-goal/scripts/formalize_check.py +94 -10
- package/skills/ultracode-goal/scripts/hooks/budget_stop.py +9 -0
- package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +142 -6
- package/skills/ultracode-goal/scripts/mem_observation.py +13 -6
- package/skills/ultracode-goal/scripts/operator_owed.py +338 -0
- package/skills/ultracode-goal/scripts/preflight_check.py +203 -5
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"name": "bmad-module-ultracode-goal",
|
|
20
20
|
"source": "./",
|
|
21
21
|
"description": "Supercharges BMAD with Claude Code's Auto Mode, Auto Memory, and hooks: autonomous Epic execution to a machine-checked, TEA-gated Definition-of-Done. Execute Epics. Accumulate Knowledge. Deliver Outcomes.",
|
|
22
|
-
"version": "3.
|
|
22
|
+
"version": "3.1.0",
|
|
23
23
|
"author": {
|
|
24
24
|
"name": "Armel"
|
|
25
25
|
},
|
package/docs/architecture.md
CHANGED
|
@@ -56,6 +56,7 @@ skills/ultracode-goal/
|
|
|
56
56
|
├── scripts/ # Deterministic truth (run via `uv`)
|
|
57
57
|
│ ├── preflight_check.py # mechanical preflight facts + blocker budget
|
|
58
58
|
│ ├── gate_eval.py # gate status -> verdict (the completion authority)
|
|
59
|
+
│ ├── operator_owed.py # is a gate FAIL owed only operator-evidence ACs' records? (fail-closed)
|
|
59
60
|
│ ├── mutate_check.py # mutation harness: attributable-red proof for the story's guards
|
|
60
61
|
│ ├── gate_trail.py # per-story evidence trail (gate-trail.md) at finalize
|
|
61
62
|
│ ├── formalize_check.py # readiness kernel behind the /ucg-formalize gate
|
|
@@ -91,7 +91,7 @@ flowchart TD
|
|
|
91
91
|
|
|
92
92
|
Each recall call is attempted once and never retried. A run whose recall turned off along the way says so in its report, with the tokens under [troubleshooting](#troubleshooting).
|
|
93
93
|
|
|
94
|
-
**What a record holds.** The Epic, the run id, the repo fingerprint, the gate status and verdict, the root-cause signatures (each with a class from a fixed taxonomy and an artifact path), the count of deferred items, the advisories the run consumed with whether they recurred, the time, and the project's folder name for display. Free text is redacted before it is written. A run
|
|
94
|
+
**What a record holds.** The Epic, the run id, the repo fingerprint, the gate status and verdict, the root-cause signatures (each with a class from a fixed taxonomy and an artifact path), the count of deferred items, the advisories the run consumed with whether they recurred, the time, and the project's folder name for display. Free text is redacted before it is written. A run that blocked with no gate status (it escalated or handed off before a gate ran, or its gate could not be read) writes a record with gate status `NOT_EVALUATED` and verdict `blocked`, so the next run sees that it blocked; a `WAIVED` outcome is written too. A resume that stops because the story's escalation is still open names no root cause in its record: the run that raised the escalation recorded it, so stopping again on one unanswered decision does not count as recurring. `NOT_EVALUATED` with any other verdict writes no record.
|
|
95
95
|
|
|
96
96
|
**When the store cannot take a record.** The record waits in `mem-outbox.<run_id>.jsonl` in the implementation artifacts folder, and the run logs `WARN mem-write-deferred`. The next run that reaches Finalize with a green latch drains it, keeping its original time. A deferred record older than 14 days is dropped, and one whose drain fails three times moves to `mem-outbox.dead.jsonl`, with `WARN mem-write-dead-lettered`. No drain replays that file.
|
|
97
97
|
|
package/docs/gate-model.md
CHANGED
|
@@ -52,6 +52,10 @@ 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.
|
|
56
|
+
|
|
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.
|
|
58
|
+
|
|
55
59
|
## The production AND
|
|
56
60
|
|
|
57
61
|
Under `--profile production`, an otherwise-`advance` verdict is additionally ANDed against two TEA signals, and any failure downgrades it to `reloop`. The downgrade floor is `reloop`. A `defer`/`reloop`/`escalate` is unchanged; only an `advance` moves:
|
package/docs/how-it-works.md
CHANGED
|
@@ -44,7 +44,7 @@ flowchart TD
|
|
|
44
44
|
S5 -->|"advance or defer"| S6
|
|
45
45
|
S5 -->|"reloop: gate FAIL within budget"| Correct
|
|
46
46
|
Correct --> S4
|
|
47
|
-
S5 -->|"escalate: NOT_EVALUATED or
|
|
47
|
+
S5 -->|"escalate: NOT_EVALUATED, budget exhausted, or operator evidence owed"| S6
|
|
48
48
|
|
|
49
49
|
classDef accent fill:#6366F1,stroke:#4F46E5,color:#fff
|
|
50
50
|
classDef verdict fill:#4F46E5,stroke:#3730A3,color:#fff
|
|
@@ -54,7 +54,7 @@ flowchart TD
|
|
|
54
54
|
class NotBmad,Blocked stop
|
|
55
55
|
```
|
|
56
56
|
|
|
57
|
-
A `defer` verdict appends non-blocking items to the ledger and advances anyway; an `escalate` ends the run as `blocked` at Stage 6 rather than `complete`. The reloop edge re-runs the story only while turn budget remains (`max_turns_per_story`); once exhausted, a FAIL becomes an escalate.
|
|
57
|
+
A `defer` verdict appends non-blocking items to the ledger and advances anyway; an `escalate` ends the run as `blocked` at Stage 6 rather than `complete`. The reloop edge re-runs the story only while turn budget remains (`max_turns_per_story`); once exhausted, a FAIL becomes an escalate. A FAIL that only evidence a person records can change (an acceptance criterion tagged `**Gate-ability:** operator-evidence` with no recorded live result, or one that covers only part of it) escalates at once with kind `operator-evidence-owed`, since no re-loop can produce that evidence.
|
|
58
58
|
|
|
59
59
|
### Stage 1: Ingest & Scope
|
|
60
60
|
|
|
@@ -117,7 +117,7 @@ The **production** profile wires the full TEA chain as gates: test-design, atdd,
|
|
|
117
117
|
|
|
118
118
|
## The decision log
|
|
119
119
|
|
|
120
|
-
The run's `.decision-log.md`, held in the skill's run folder, is canonical memory. Compaction can drop everything else; the log recovers full state. It records scope, the preflight verdict, every gate outcome, every deferral, and (in headless) every assumption. **Resume** reads it: on a resumed run, Execute re-enters at the first story whose last logged gate verdict is not `advance`; advanced stories are not re-run, and the Epic branch, hooks, and allowlist are re-asserted (not rebuilt) before continuing.
|
|
120
|
+
The run's `.decision-log.md`, held in the skill's run folder, is canonical memory. Compaction can drop everything else; the log recovers full state. It records scope, the preflight verdict, every gate outcome, every deferral, and (in headless) every assumption. **Resume** reads it: on a resumed run, Execute re-enters at the first story whose last logged gate verdict is not `advance`; advanced stories are not re-run, and the Epic branch, hooks, and allowlist are re-asserted (not rebuilt) before continuing. A re-entry story that still carries an open escalation is not re-entered: the run stops and points at `/ucg-resolve`.
|
|
121
121
|
|
|
122
122
|
## The run report, the gate trail, and the deferred-work ledger
|
|
123
123
|
|
package/docs/troubleshooting.md
CHANGED
|
@@ -75,7 +75,7 @@ A per-story gate can return `reloop` with a `PASS` gate status when a cap fired
|
|
|
75
75
|
|
|
76
76
|
**Symptom.** A story stops re-looping; an escalation marker (`<impl-artifacts>/.escalation-<story>.md`) appears; the run surfaces a budget message.
|
|
77
77
|
|
|
78
|
-
**What happened.** Three layers can bound a runaway story. The literal "…or stop after N turns" clause inside a `/goal` condition binds only when you started a `/goal` whose own condition carries it, and then it bounds the session: the conductor cannot start one itself. Otherwise the bound is the gate's re-loop budget: before each re-loop the conductor reads the hook's recorded turn count, and a `reloop` that would exceed `max_turns_per_story` becomes an `escalate` instead. That count advances once per response, so re-loops spent inside one response do not move it, and for `drive_epic.py` spawns the `--session-timeout` wall clock is the backstop. The **Stop** hook (`budget_stop.py`) is the defensive third layer: it counts turns and, on overrun, writes the escalation marker and lets the stop proceed. The marker records the count and does not stop the drive, so the story goes on toward its gate. It becomes an escalation only when the gate escalates the story on that count. A story that passes its gate gets a sizing note in the decision log and the run report instead: no escalation, no ping, and nothing left open.
|
|
78
|
+
**What happened.** Three layers can bound a runaway story. The literal "…or stop after N turns" clause inside a `/goal` condition binds only when you started a `/goal` whose own condition carries it, and then it bounds the session: the conductor cannot start one itself. Otherwise the bound is the gate's re-loop budget: before each re-loop the conductor reads the hook's recorded turn count, and a `reloop` that would exceed `max_turns_per_story` becomes an `escalate` instead. That count advances once per response, so re-loops spent inside one response do not move it, and for `drive_epic.py` spawns the `--session-timeout` wall clock is the backstop. It counts responses, not work: a background task's notification that lands while the session is idle starts a response of its own, which counts the same as one that edits code, so a story whose sweeps, reviews and gate assessors run in the background can reach the ceiling on waiting. Execute keeps that small by making each wait report once, and by starting no other story's work while a story is current. The **Stop** hook (`budget_stop.py`) is the defensive third layer: it counts turns and, on overrun, writes the escalation marker and lets the stop proceed. The marker records the count and does not stop the drive, so the story goes on toward its gate. It becomes an escalation only when the gate escalates the story on that count. A story that passes its gate gets a sizing note in the decision log and the run report instead: no escalation, no ping, and nothing left open.
|
|
79
79
|
|
|
80
80
|
**Its documented limitation.** A Stop hook fires only when Claude is *already* trying to stop: it **cannot interrupt a `/goal` condition mid-turn**. So at this layer the ceiling is advisory; what can stop the story is the conductor's re-loop budget checked against this count, plus the in-condition turn clause when you started a `/goal`. In a single attended or `-H` session with no `/goal` of yours, nothing bounds re-loops spent inside one response; only `drive_epic.py` spawns have a hard backstop, their `--session-timeout` (unless set to `0`). If a story keeps consuming budget, that is the signal to re-scope, split, or hand it off, not to raise the budget and hope.
|
|
81
81
|
|
|
@@ -83,7 +83,7 @@ A per-story gate can return `reloop` with a `PASS` gate status when a cap fired
|
|
|
83
83
|
|
|
84
84
|
**Symptom.** A run was interrupted (Ctrl-C, a crash, a compaction) and you want to continue rather than restart.
|
|
85
85
|
|
|
86
|
-
**What happens.** The run's `.decision-log.md` is canonical memory and recovers full state regardless of compaction. On resume the skill surfaces the existing log with its last session date and offers to resume. Execute re-enters at the **first story whose last logged gate verdict is not `advance`**; already-advanced stories are not re-run. The Epic branch, hooks, and allowlist are **re-asserted, not rebuilt**, before continuing. You do not need to reconstruct state by hand. Point the skill at the same Epic and accept the resume offer.
|
|
86
|
+
**What happens.** The run's `.decision-log.md` is canonical memory and recovers full state regardless of compaction. On resume the skill surfaces the existing log with its last session date and offers to resume. Execute re-enters at the **first story whose last logged gate verdict is not `advance`**; already-advanced stories are not re-run. The Epic branch, hooks, and allowlist are **re-asserted, not rebuilt**, before continuing. You do not need to reconstruct state by hand. Point the skill at the same Epic and accept the resume offer. One case stops instead: when the story it would re-enter still has an open escalation (its `escalation-<story_id>.json` on disk, not closed by `/ucg-resolve`), the run drives nothing and points you at `/ucg-resolve`; a headless run ends `blocked` with a `reason` naming the sidecar. Answer it there, then resume. When the answered escalation was `operator-evidence-owed`, the resume then re-gates the commit your records were made at instead of re-driving the story, as long as nothing was committed after it.
|
|
87
87
|
|
|
88
88
|
## The retired `--parallel` flag
|
|
89
89
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://json.schemastore.org/package.json",
|
|
3
3
|
"name": "bmad-module-ultracode-goal",
|
|
4
|
-
"version": "3.
|
|
4
|
+
"version": "3.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",
|
|
@@ -110,6 +110,12 @@ at four fields and cannot carry one, so its id is derived rather than read:
|
|
|
110
110
|
uv run {ucg-root}/scripts/red_ids.py --mint-one <kind> <artifact path> <decision_needed>
|
|
111
111
|
```
|
|
112
112
|
|
|
113
|
+
For a sidecar the three arguments are its own `kind`, `source` and `decision_needed`
|
|
114
|
+
fields, each passed verbatim: `<artifact path>` is the sidecar's `source` field, its
|
|
115
|
+
`:line` suffix and all (the id layer strips it), never the path of the sidecar file
|
|
116
|
+
itself. The resume also reads a close keyed by the sidecar file's own path as closed,
|
|
117
|
+
since earlier passes keyed some that way, but never mint a new id from that path.
|
|
118
|
+
|
|
113
119
|
It prints the id and touches nothing. **A ledger `decision:` row is keyed by the same
|
|
114
120
|
call** — kind `decision`, the ledger path, and the row's reason — because the row's own
|
|
115
121
|
`id` column is unique only within its Epic heading, so `d1` under one Epic and `d1` under
|
|
@@ -205,6 +211,29 @@ The two dispositions are genuinely different things, not two names for one:
|
|
|
205
211
|
the close would apply in name only. Answering a budget overrun by re-scoping, splitting,
|
|
206
212
|
or handing off the story *is* the operator granting it a fresh budget, so the counter that
|
|
207
213
|
recorded the exhausted one has no claim on the resumed run.
|
|
214
|
+
**Closing an `operator-evidence-owed` escalation needs the evidence on disk.** Read the
|
|
215
|
+
live results file its `decision_needed` names and confirm a `status` `pass` record for
|
|
216
|
+
every AC it lists, made at the commit it names. Those are the story's
|
|
217
|
+
`**Gate-ability:** operator-evidence` ACs; a plain `operator` tag is work the dev agent
|
|
218
|
+
builds, never evidence this close waits on. If one is missing, say which and record
|
|
219
|
+
`defer`. An AC the escalation names as partly recorded, with the ids of the records TEA
|
|
220
|
+
already counted for it, closes only on a `pass` record at that commit whose `id` is not
|
|
221
|
+
among the ones the escalation names, or on the operator's written narrowing or move of
|
|
222
|
+
the AC: the records already counted are not enough, since re-gating them changes
|
|
223
|
+
nothing. This surface never writes a record itself: the operator is its producer
|
|
224
|
+
(`{ucg-root}/references/gate.md`, "Operator evidence is a recorded live result"). A
|
|
225
|
+
ruling that narrows or moves the AC is the operator's story edit: record it, then close.
|
|
226
|
+
**That close also writes the story's re-gate marker and resets its turn counter.** Write
|
|
227
|
+
`{workflow.implementation_artifacts}/.regate-<story_id>` as two lines, `sha=` the
|
|
228
|
+
assessed commit the sidecar names (in full, as `git rev-parse` prints it) and
|
|
229
|
+
`decision=` the id you closed, then delete the sidecar as for any close, and delete
|
|
230
|
+
`{workflow.implementation_artifacts}/.budget-<story_id>.json`: waiting for operator
|
|
231
|
+
evidence is not the story's work. The marker is the re-gate entry. While its `sha=`
|
|
232
|
+
names `HEAD`, the resume's `--assert-armed` call routes the story `gate-owed`, so it
|
|
233
|
+
re-enters at Stage 5 to re-gate that commit, and is never re-driven from step 0, where
|
|
234
|
+
the turn-ceiling read could escalate it and a commit past the assessed one would make
|
|
235
|
+
the records stale (`{ucg-root}/references/execute.md`, the resume rule). The gate
|
|
236
|
+
deletes the marker once the re-gate's verdict is logged.
|
|
208
237
|
- **`defer`** — the decision is not made yet. Record the entry **without clearing
|
|
209
238
|
anything**. The artifact stays exactly where it is, the item stays pending, and the next
|
|
210
239
|
preflight still blocks on it.
|
|
@@ -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`. 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). 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. **A resume routed into Execute does NOT re-run the Stage-2 formalize gate.** That verdict is Stage 2's and it
|
|
39
|
+
**Resume.** The workspace is this skill's run folder holding `.decision-log.md`. 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. **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
|
|
|
@@ -24,6 +24,8 @@ For every **in-scope** story, in sprint order (leave out a parent that preflight
|
|
|
24
24
|
|
|
25
25
|
1. **`ucg-create-story`**: produce the dedicated story file with full implementation context and *clear, testable* acceptance criteria. Pass it `implementation_artifacts` set to `{workflow.implementation_artifacts}`, so the file lands where this run reads it. If preflight already generated this story, treat the change request as a refinement, not a re-create. Vague ACs are the single most common cause of the next step halting, so sharpen them here.
|
|
26
26
|
|
|
27
|
+
**A criterion with an operator half is split here.** UCG's shaping asks every acceptance criterion for a CI-versus-operator split. When an AC's split names a part no script or test can decide (a measurement on a build or machine CI cannot run, a judgment only a person can make), have `ucg-create-story` split it. The machine-decidable part stays one AC tagged `**Gate-ability:** ci-machine`. The operator part becomes its own numbered AC, numbered after the story's last AC so no existing number moves, with its own `**Gate-ability:** operator-evidence` line. An AC whose split names only such a part, with nothing a script or test can decide, is not split. Retag it in place, keeping its number, with `**Gate-ability:** operator-evidence`, whatever tag it carried, only when it asks the dev agent to build or change nothing: its whole content is a measurement, run or observation a person makes and records. The test is whether the AC asks for anything to be built or changed, not who can check it: an AC that asks for a change (code, a comment, a doc, a ledger edit) keeps its tag even when only a person's read can check it. The `operator-evidence` tag is this class's alone: a plain `**Gate-ability:** operator` tag keeps its meaning, work the dev agent builds that a person or a script verifies, and nothing reads it as owed evidence. Its **Verification** is a recorded live result (`references/gate.md`, "Operator evidence is a recorded live result"), and its anti-vacuous twin is that a `fail` record, or a record made at another commit, leaves it uncovered. Never leave the operator part inside a ci-machine AC as prose such as "recorded rather than gated": trace classifies a criterion by everything it states, so the unrecorded half holds the whole AC at PARTIAL. The split drops and relaxes nothing. Log each split in `.decision-log.md`.
|
|
28
|
+
|
|
27
29
|
**A decomposed child gets no story file.** Skip this step for a key the readiness check listed in `checks.decomposed_children` when the split is recorded (its split record (`.split-<parent key>.json` beside `sprint-status.yaml`, which `scripts/story_sizing.py --record` writes) names the child, the child's row cites the parent ACs it claims, or `.decision-log.md` names the parent and the ACs each child claims): the child has no story file and must never get one, and its criteria are the parent ACs it claims, in the parent's file (`references/execute.md`, step 1). A listed key with none of these records is a story of its own that reads like a child (above a `done` parent's row, or under a parent whose row was removed): create its file here, and log in `.decision-log.md` that the readiness check never read its criteria. One such key already has its file: a key whose title starts with a single letter or a roman numeral (`2-4-a-new-login-page`) reads one level below its story number, so its own story file named by that number alone (`2-4.md`) or by another title is listed as the parent of a removed row. When the listed parent file is that story's own (`parent_row` is `null`, no other key in the list names the same file, and the file's title and criteria are this key's), rename that file to `<key>.md` instead, in one `mv <that file> <its folder>/<key>.md` call (a filesystem command `acceptEdits` runs without asking on a path inside the project, unlike a git move, which no allow rule covers), then run this step on it as a refinement, and log the rename: the readiness check did read its criteria. A file two listed keys name is a parent's, so rename it for neither.
|
|
28
30
|
|
|
29
31
|
On a project whose artifact tree git does not track (preflight's `impl_artifacts_tracked: false`), no acceptance criterion may have a test read a file under that tree at run time: it does not exist in CI. Preflight step 2 states the rule ("A gitignored artifact tree").
|
|
@@ -36,6 +38,8 @@ For every **in-scope** story, in sprint order (leave out a parent that preflight
|
|
|
36
38
|
|
|
37
39
|
**For a decomposed child, run it under the child's own key** (on a stack ATDD cannot run on, the hand-established red phase above stands in, as for any story, scoped to the parent ACs the child claims). Give it the parent's story file for the text of the parent ACs the child claims, and have it write `atdd-checklist-<child key>.md` with the child's key as its story key and the parent's key and those AC numbers in its frontmatter. ATDD otherwise takes the story key from the file it reads, so it would write the parent's checklist, and each sibling's into the same file, while Execute and its commit guard read the child's. Build its criterion registry from the parent's whole AC list, so each id keeps the parent's number, and scaffold the claimed ids only. Treat the parent's file as one ATDD cannot update safely, so it skips the link back into it: the parent's story file is never edited. ATDD's closing checks that every declared criterion has a scaffold and that the link back was written do not apply to a child, and are not gaps to fix. A halt on vague criteria is no loop back here: never run `ucg-create-story` for the child and never edit the parent's file. Record the halt in `.decision-log.md` and escalate as Execute's sub-skill halt catch-all does (`references/execute.md`: write the typed escalation sidecar, then stop), naming the parent ACs that need sharpening.
|
|
38
40
|
|
|
41
|
+
**An operator-evidence AC gets no red-phase scaffold**, and on a stack ATDD cannot run on, no hand-established red-phase case either: no test can decide it, and its proof is the recorded live result. Build ATDD's criterion registry from the whole AC list and scaffold every AC except the ones tagged `**Gate-ability:** operator-evidence`, as for a decomposed child's claimed subset. ATDD's closing check that every declared criterion has a scaffold does not apply to an operator-evidence AC, and is not a gap to fix.
|
|
42
|
+
|
|
39
43
|
Force **Create** mode (not Resume/Validate/Edit) for the same unattended reason.
|
|
40
44
|
|
|
41
45
|
**In `--light`:** run step 1 (`ucg-create-story`) but **skip step 2 (`bmad-testarch-atdd`)**: `--light` produces no executable red-phase acceptance tests. The story file and its acceptance criteria become the Definition-of-Done and the oracle `bmad-testarch-trace` resolves the Stage 5 gate against, mirroring gate.md's `--light` branch (which runs only `bmad-testarch-trace`). The per-Epic test-design above still runs in `--light`: `bmad-testarch-trace` consumes its risk scores and P0–P3 priorities when they are available, and they are the backbone you sharpen the ACs against in either profile. Sharpen the ACs here exactly as you would for production: under `--light` they are the *only* machine-checkable DoD a story gets, so vague ACs leave the trace gate nothing to resolve against.
|
|
@@ -50,6 +54,6 @@ Stage 3 is complete, and Stage 4 may begin, when **all three** hold:
|
|
|
50
54
|
|
|
51
55
|
- The Epic has a `bmad-testarch-test-design` plan with a populated risk matrix, P0–P3 priorities assigned, and every in-scope NFR threshold either resolved or explicitly marked `UNKNOWN`/deferred.
|
|
52
56
|
- **Every in-scope story** has a story file with clear acceptance criteria. A recorded decomposed child, which has none of its own, meets this through its parent's story file, which holds the parent ACs it claims.
|
|
53
|
-
- **Every in-scope story** has a generated `atdd-checklist-{story_key}.md` and red-phase (`test.skip`) acceptance tests on disk
|
|
57
|
+
- **Every in-scope story** has a generated `atdd-checklist-{story_key}.md` and red-phase (`test.skip`) acceptance tests on disk (**production only**, on a stack ATDD can run on). An operator-evidence AC needs no scaffold (step 2). Under `--light` this is skipped by design; the story file's acceptance criteria stand as the trace oracle instead, and this bullet is satisfied by the clear-ACs bullet above. On a **non-web stack** (ATDD's generator cannot run), this bullet is satisfied by the recorded hand-establishment commitment per story (the substitution in step 2 above), never by a checklist nobody could generate.
|
|
54
58
|
|
|
55
59
|
In production, if any in-scope story is missing its atdd-checklist, this stage is not done — Execute has nothing executable to drive that story to. (Under `--light` an absent atdd-checklist is expected, not a gap; on a non-web stack the hand-established red phase per `references/gate.md`'s non-web section stands in for it, and the decision log says so per story.) Record in `.decision-log.md`: the test-design verdict, each story's AC + checklist status (or the `--light` skip), and any deferral appended to `{workflow.deferred_work_path}`.
|
|
@@ -14,10 +14,14 @@ Preconditions (asserted, not assumed): you are on the Epic branch (`{workflow.ep
|
|
|
14
14
|
|
|
15
15
|
**A resume owes the stall check first.** Before the re-assertions below, apply the per-step heartbeat's gap rule (the "Run-status heartbeat" section): when the in-flight story's `.heartbeat-<story_id>` exists and its last line is older than 30 minutes, write the `.stall-<story_id>` line before driving anything — the resume is the only reader positioned to see the gap while its cause is still nearby.
|
|
16
16
|
|
|
17
|
-
**The re-assertion sweep is one script call, not a tool action per fact.** Run `uv run {skill-root}/scripts/preflight_check.py --assert-armed --project-root {project-root} --impl-artifacts {workflow.implementation_artifacts} --epic-branch-prefix {workflow.epic_branch_prefix} --story <the story about to be driven> --run-id <this run's id> --trace-output {workflow.trace_output_dir}` (plus one `--protected-branch <name>` per protected branch, as Stage 2's step 1 passes them: the prefix and the protected list are resolved scalars, and omitting either would assert the branch against a default the operator may have overridden). Exit 0 asserts the branch, both hooks with the all-tools matcher, the five injected hook env vars, and that `ucg-create-story` and `ucg-dev-story` are still installed (a manual deletion, or a UCG install or update interrupted between removing the UCG skills and copying them back, between spawns, can leave a run without them) in one read, and the `story` block returns the artifact-derived route this paragraph defines: `story-boundary`, `mid-story`, or `gate-owed` (the committed-green-un-gated third case below; the script only ever returns it when `--trace-output` named the run's real, readable trace dir and the artifact evidence held in full, while an unverifiable location reads `unknown` and routes to the ordinary loop, so lack of evidence never skips steps 1 through 4). Three things the manifest deliberately does **not** cover: the latch is **reported, never certified** (whatever the JSON shows, re-latch from this run's own measurement exactly as above); a boundary story's fresh baseline is still written by step 0; and the **allowlist** is neither asserted nor reported (it lives in permission settings the script does not read), so re-assert it exactly as the list at the top of this paragraph requires. A non-zero exit is the resume's RED: fix what the `reasons` name before continuing, and never narrate around it. A fix that writes `.claude/settings.local.json` (a hook, its env, the allowlist) follows `references/preflight.md`'s "A refused settings write" rule if the write, or a call after it, is refused: stop, never work around it, and in headless take the escalation route below for the story about to be driven, naming the refused write. The one reason a resume never fixes is a skills failure (`checks.skills.ok: false`): installing UCG's story skills is the operator's call, so do not run the installer command that reason names, do not substitute another skill (`bmad-build`, `bmad-build-auto`, or BMAD's deprecated `bmad-create-story` and `bmad-dev-story`), and do not hand-author the story or the code. Take the sub-skill halt catch-all's route (below) for the story about to be driven: write `escalation-<story_id>.json` with `decision_needed` quoting that reason, then stop.
|
|
17
|
+
**The re-assertion sweep is one script call, not a tool action per fact.** Run `uv run {skill-root}/scripts/preflight_check.py --assert-armed --project-root {project-root} --impl-artifacts {workflow.implementation_artifacts} --epic-branch-prefix {workflow.epic_branch_prefix} --story <the story about to be driven> --run-id <this run's id> --trace-output {workflow.trace_output_dir}` (plus one `--protected-branch <name>` per protected branch, as Stage 2's step 1 passes them: the prefix and the protected list are resolved scalars, and omitting either would assert the branch against a default the operator may have overridden). Exit 0 asserts the branch, both hooks with the all-tools matcher, the five injected hook env vars, and that `ucg-create-story` and `ucg-dev-story` are still installed (a manual deletion, or a UCG install or update interrupted between removing the UCG skills and copying them back, between spawns, can leave a run without them) in one read, and the `story` block returns the artifact-derived route this paragraph defines: `decision-pending` (the next paragraph), `story-boundary`, `mid-story`, or `gate-owed` (the committed-green-un-gated third case below, or the re-gate a closed `operator-evidence-owed` escalation owes, the fourth case after it; for the third case the script only ever returns it when `--trace-output` named the run's real, readable trace dir and the artifact evidence held in full, while an unverifiable location reads `unknown` and routes to the ordinary loop, so lack of evidence never skips steps 1 through 4). Three things the manifest deliberately does **not** cover: the latch is **reported, never certified** (whatever the JSON shows, re-latch from this run's own measurement exactly as above); a boundary story's fresh baseline is still written by step 0; and the **allowlist** is neither asserted nor reported (it lives in permission settings the script does not read), so re-assert it exactly as the list at the top of this paragraph requires. A non-zero exit is the resume's RED: fix what the `reasons` name before continuing, and never narrate around it. A fix that writes `.claude/settings.local.json` (a hook, its env, the allowlist) follows `references/preflight.md`'s "A refused settings write" rule if the write, or a call after it, is refused: stop, never work around it, and in headless take the escalation route below for the story about to be driven, naming the refused write. The one reason a resume never fixes is a skills failure (`checks.skills.ok: false`): installing UCG's story skills is the operator's call, so do not run the installer command that reason names, do not substitute another skill (`bmad-build`, `bmad-build-auto`, or BMAD's deprecated `bmad-create-story` and `bmad-dev-story`), and do not hand-author the story or the code. Take the sub-skill halt catch-all's route (below) for the story about to be driven: write `escalation-<story_id>.json` with `decision_needed` quoting that reason, then stop.
|
|
18
|
+
|
|
19
|
+
**A re-entry story with an open escalation is not re-entered.** The `story` block also reports `escalation`: `null` when no `escalation-<story_id>.json` exists, and otherwise its `state`. It reads `open` when the sidecar is on disk and the id `/ucg-resolve` keys its answer by (`red_ids.py`'s, minted from the sidecar's own `kind`, `source` and `decision_needed`; a close keyed by the sidecar file's own path, as earlier passes keyed some, counts too) is not closed in `.decisions.json`, or when the sidecar cannot be read or no id can be minted from its fields, and the route is then `decision-pending`, ahead of the other three. `/ucg-resolve` deletes the sidecar when it closes the decision and leaves it in place on a `defer`, so a sidecar still on disk is a decision nobody closed: an answer written anywhere else (the story file, a ruling, the ledger) has not closed it. On `decision-pending`, do not drive or gate the story and write no sidecar: the open one is the record, and the skills, refused-write and turn-ceiling routes in this file each write `escalation-<story_id>.json` and would overwrite it. Attended, show the sidecar's `kind` and `decision_needed`, offer `/ucg-resolve`, and continue only once a fresh `--assert-armed` call no longer reads `decision-pending`. Headless, or when the operator leaves it open, end the invocation `blocked` as `references/gate.md`'s `escalate` does, handing the block's `escalation.blocker` to the headless adapter as the one blocker, so the envelope's `reason` names the sidecar. Two states never set the route: `handoff`, a `story-decomposed` or `defined-not-driven` sidecar, which hands this invocation work to pick up rather than a decision (an `operator-evidence-owed` sidecar is not one of them: `scripts/drive_epic.py` reports it as a handoff, but re-driving the story cannot record the evidence an operator owes, so it routes `decision-pending` until `/ucg-resolve` closes it); and `closed`, a sidecar whose id `/ucg-resolve` already closed, the residue of an answered decision that `/ucg-resolve` would not offer again.
|
|
18
20
|
|
|
19
21
|
**A third case: a story already committed, green and un-gated.** The routing above sorts stories into two classes — re-drive, and do not re-run — and a session that died between its commit and its gate belongs to neither. Recognise it by artifacts, never by prose: the row carries commits past its baseline marker **and** a `.tests-ran-<story_id>` marker whose `baseline=` line still matches that marker, **and** neither `trace-<story_id>.md` nor `gate-decision-<story_id>.json` exists under `{workflow.trace_output_dir}`. That story owes **evidence and a gate, not implementation**. Re-set the `.current-story` pointer (the pointer half of step 0 only — the baseline marker is still re-read, never rewritten), skip steps 1 through 4, and enter at **step 5**, re-measuring the committed HEAD rather than reading the tests-ran marker's numbers back — at FULL scope, since no step 2 ran this session to inherit from — and once green, rewrite the tests-ran marker fresh (same `baseline=` line, `scope=full`) **even on a green first try**: the inherited marker may predate the scope contract or carry a mid-loop `scope=scoped`, and the gate reads the marker THIS session leaves behind, not the dead one's; then continue into Stage 5 as normal. Trust the artifacts and the `sprint-status.yaml` row, never the story file's own prose: such a file routinely carries a close-out asserting a gate `PASS` that no artifact backs, which is precisely the claim this stage does not get to make. **The discriminator must hold in full.** A tests-ran marker with no commits, or commits with no marker, is a story that died before or during the sweep, and it takes the ordinary loop from step 0.
|
|
20
22
|
|
|
23
|
+
**A fourth case: a closed `operator-evidence-owed` story owes a re-gate, not a re-drive.** Its FAIL gate left `trace-<story_id>.md` and `gate-decision-<story_id>.json` on disk, so the third case never fires for it. When `/ucg-resolve` closes that escalation, it deletes the sidecar, resets the story's turn counter (waiting for operator evidence is not the story's work) and writes `{workflow.implementation_artifacts}/.regate-<story_id>`, holding `sha=` the assessed commit and `decision=` the closed id. The `story` block reports that marker as `regate`: `null` when there is none, otherwise its `state`. While it reads `fresh` (its `sha=` resolves to `HEAD`) and the baseline marker exists, the route is `gate-owed`: enter exactly as the third case does, re-setting the pointer, skipping step 0's turn-ceiling read and steps 1 through 4, re-measuring `HEAD` at step 5, then re-gating it in Stage 5, whose trace counts the operator's records. Commit nothing before that gate while step 5's re-measure is green, since a commit past the assessed commit makes the records stale. On a red, take step 5's red route (remediate, write a fresh `.tests-ran-<story_id>` marker, re-commit): that commit moves `HEAD` past the assessed commit, so the records no longer count and the `.regate-<story_id>` marker is stale, and the re-gate at the new `HEAD` escalates `operator-evidence-owed` again at the new commit. A `stale` marker (one naming another commit, or no commit id) routes as if it were absent, normally `mid-story`: a later commit already made the records stale. On either route the gate deletes the marker once this story's verdict is logged (`references/gate.md`, "A logged verdict settles an owed re-gate").
|
|
24
|
+
|
|
21
25
|
## Default — Sequential `/goal` spine
|
|
22
26
|
|
|
23
27
|
### Sizing: a story too large to drive
|
|
@@ -51,9 +55,13 @@ Then terminate as the work-bound section below describes for an invocation that
|
|
|
51
55
|
For each in-scope story, in sprint order, run this loop (leave out a decomposed parent: one preflight step 2 set `done` as a container, or a `done` row whose split is recorded, as the resume cursor above passes over):
|
|
52
56
|
|
|
53
57
|
0. **Set the current story and record its baseline commit** — both **before any implementation**, before step 1 touches a single file. (First read the story's recorded turn count, per "Authoring the `/goal` condition" below: a resumed story already at or over the ceiling escalates instead.) First, so the PreToolUse hook can locate this story's marker: write the story id to `{workflow.implementation_artifacts}/.current-story`. Both hooks read the story id from `ULTRACODE_STORY_ID` when their own environment carries it, falling back to that `.current-story` file, and an `export` inside a Bash call never reaches their processes, so the file is the route that works. Skip the write and both hooks keep reading whatever the file last named: no story at all after preflight's purge, so the guard denies every commit and the Stop hook counts nothing, or the previous story, whose markers and counter then stand in for this one's. Then anchor the story: **if `{workflow.implementation_artifacts}/.baseline-<story_id>` is absent, write it now** with the output of `git rev-parse HEAD` — **exactly one newline-terminated line carrying the full 40-hex SHA**. This format is a contract, not a style choice: later stages bound this story's commit range from it and compare it as a verbatim whitespace-stripped string, so a `git rev-parse --short` abbreviation or a write with no trailing newline is a silent breakage, not a cosmetic one. **If the marker is already present, this story is a resume: read it and keep it — never overwrite it.** No later step refreshes it; a multi-commit story must keep the SHA it started from even after HEAD moves. **Scratch build space, if the story needs any.** A story that must build and run a throwaway program to produce a committed artifact puts it in `{workflow.implementation_artifacts}/.scratch-<story_id>/` and nowhere else. Not an improvised repo-root directory — that is one careless `git add` away from being committed, and only step 4's explicit per-path staging would catch it. Not `/tmp` either: it survives no audit, belongs to no run, and buys nothing the run folder does not. What this location buys is containment: the dot prefix and the run folder keep it out of every default source glob and out of the commit. What it does **not** buy is runnability — a headless permission layer gates on command **shape**, not path, so a compound `bash <scratch>/script.sh 2>&1 | tee …`, a `for` loop over gate names, or a `$(…)` substitution can each be refused wherever the file sits. Keep scratch work invocable as one simple command per call, and expect to run its steps as separate calls rather than through one orchestrating script. The directory outlives the step-4 commit **deliberately**: step 5 re-runs the same declared-gate sweep on the committed tree, so a runner or harness built here is still needed there, and one deleted at step 4 gets re-authored verbatim at step 5 — a real, measured cost. **Remove the directory after step 5's re-verify goes green, before the story advances** — never earlier, and never later: the next story's step 0 must not find it.
|
|
54
|
-
1. `ucg-create-story` (if not already current) → `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. **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 under `{workflow.implementation_artifacts}`. `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.)
|
|
58
|
+
1. `ucg-create-story` (if not already current) → `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 under `{workflow.implementation_artifacts}`. `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.)
|
|
55
59
|
**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.
|
|
56
60
|
|
|
61
|
+
**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.
|
|
62
|
+
|
|
63
|
+
**Get an AC narrowed in writing before committing a case that pins behaviour it forbids.** A stated bound (a case asserting an outcome an AC rules out, because the story keeps that behaviour on purpose) leaves the AC PARTIAL in trace, which reads the AC as written, and no re-loop changes the AC. Narrowing it is the operator's decision, so escalate for it as the sub-skill halt catch-all below does, naming the AC, the behaviour and the narrowing you propose, and commit the case only once the story file states the narrowed AC.
|
|
64
|
+
|
|
57
65
|
2. Run the tests, lint, and build, and **PRINT the raw output** (pass/fail counts, lint result, build result) into the transcript. **In a monorepo, scope that test run wide enough to catch cross-package regressions** — run the full suite, or the changed package(s) plus everything downstream of them (e.g. an `--affected` set *and its dependents*), not just this story's own package. A story's change can regress a *sibling* package's conformance gate (a cross-package RBAC, ownership, or architecture-boundary check), and a run scoped to only this story's package reports green while that sibling gate is red — deferring the red (and its fix) to a later story or the Epic gate instead of catching it at the story that caused it. This printed evidence is what keeps the run judgeable mid-flight, and what a `/goal` evaluator reads when the operator started one — but it is *evidence*, not the gate. **Once all three go green, write the tests-ran marker** `{workflow.implementation_artifacts}/.tests-ran-<story_id>` — the PreToolUse guard denies the step-4 commit unless this marker exists for the current story, so write it only after a real green run. **That marker must carry a `baseline=<sha>` line** whose value is the verbatim, whitespace-stripped content of `{workflow.implementation_artifacts}/.baseline-<story_id>` written at step 0 — **copied, never re-derived from `git rev-parse HEAD`** at marker-write time. The guard compares the two strings character for character and denies the commit when they differ or when the line is missing, which is what stops a marker written against an older code state from being replayed to satisfy a later commit. Re-deriving the value here instead of copying it is the trap: on a story that commits more than once, HEAD has already moved past the baseline, so a re-derived line denies the story's own second commit. **Write that marker with the Write tool**, after Reading the baseline file and pasting its line unchanged — for the same reason step 4 writes the decision log with Write/Edit. The obvious Bash form, `printf 'baseline=%s\n' "$(cat …/.baseline-<story_id>)" > …/.tests-ran-<story_id>`, is a command substitution that a harness which statically analyses Bash strings refuses outright (the PreToolUse guard permits it; the refusal comes from above). Hand-retyping the forty hex characters instead is precisely the transcription error the freshness clause exists to catch, and its denial says only that the SHAs differ, never that one was mistyped. **The marker carries the sweep's scope beside its baseline** — two more lines, same file: `scope=<full|scoped>` naming which sweep form this green run was (the re-loop rule below is the only thing that ever writes `scoped`; a first pass writes `scope=full`), and — scoped only — `packages=<the resolved package list>` copied from the runner's own printout, never hand-typed. The gate reads the `scope=` line through `gate_eval.py --tests-ran` and caps a scoped cycle's verdict at `reloop` (`references/gate.md`, the sweep-scope AND), which is what stops a scoped sweep from impersonating a full one at the only place the distinction pays.
|
|
58
66
|
|
|
59
67
|
**Scope the sweep on three axes, not one.** Package breadth above is the first; the other two are how a green sweep is most often blind:
|
|
@@ -86,6 +94,13 @@ The second `--message` is there because the record names files the message may o
|
|
|
86
94
|
|
|
87
95
|
**Sub-skill halt catch-all.** If any orchestrated sub-skill blocks on interactive input mid-run, treat it as escalate for that story: write the typed escalation sidecar `{workflow.implementation_artifacts}/escalation-<story_id>.json` (shape below, under "Escalation sidecar") and stop; do not answer its prompt blind. A sub-skill that is not installed at all (the Skill tool does not know its name) takes the same route: escalate, and never substitute another skill (`bmad-build`, `bmad-build-auto`, or BMAD's deprecated `bmad-create-story` and `bmad-dev-story` for UCG's story skills) or hand-author the work it would have produced.
|
|
88
96
|
|
|
97
|
+
**Waiting spends turns.** The Stop hook counts one turn per response, whatever the response did. A background task's notification (a background command exiting, a background subagent or workflow reporting back, a watch's event) that lands while the session is idle starts a response of its own, so each such wake-up costs a turn even when all it does is say a sweep is still running. A notification that lands while a response is still working can be taken into that response at no cost. A full sweep can outlast a foreground command's time limit, and an attended session often cannot wait for a subagent in the foreground, so the waits in this loop (the step 2 sweep, the step 3 reviews, the step 5 re-verify, Stage 5's assessors) are real. What the run controls is how many wake-ups they cost:
|
|
98
|
+
|
|
99
|
+
- **Make each wait report once.** Start what the next step needs in one response and have it come back as one notification: concurrent commands as one subagent the session waits for, which runs each as its own simple command and reports every exit status in its one reply, and concurrent subagents as one workflow, or as calls the session waits for where it can (a `-p` run can). One compound shell command that starts them together and collects their exit statuses (`&`, `wait`, `$!`, `$?`) is not an option: under `scripts/drive_epic.py`'s default spawn mode, `acceptEdits`, with the default allowlist, Claude Code refuses it before it runs, as step 0 says of compound commands. Separate background tasks each wake the session when they end.
|
|
100
|
+
- **Watch for completion, not progress.** A watch that emits an event per log line or per stage wakes the session on every event. Add no background wait command beside a task that already reports when it ends, and schedule no wake-up only to check progress.
|
|
101
|
+
- **Spend a wake-up on work.** A wake-up while the next step still needs a running task is a turn spent whatever it does, so do in it the work that does not depend on that task (record the finished result, prepare the next command).
|
|
102
|
+
- **Keep another story's work off this story's count.** The hook books every Stop to the story `.current-story` names, so a background task for another story (refining the next one, say) started while this one is current spends this story's turns. Start such work in that story's own loop, once its step 0 has made it current.
|
|
103
|
+
|
|
89
104
|
### The per-invocation work bound (`--max-stories N`)
|
|
90
105
|
|
|
91
106
|
When the operator passed `--max-stories N`, count the stories this **invocation** has taken all the way to a Stage-5 verdict, and once that count reaches N with in-scope stories still remaining, leave the spine and go to Stage 6. **Not "as if the Epic had run out of stories" — it has not.** The Epic-level trace gate is triggered by `references/gate.md`'s own condition (*every* story of the Epic is `done`), which a bounded stop leaves false, so that gate does not fire and Stage 6 must not author one: an Epic-level PASS over an Epic that still owes stories is precisely the misrepresentation `gate.md`'s partial-by-design exception exists to prevent. That sentence has one boundary case it must not swallow: **when the bounded lap drives the Epic's last in-scope story, the bound never fires** — its trigger is "N reached *with in-scope stories still remaining*", and none remain — so that invocation is an ordinary Epic completion: every story is `done`, `gate.md`'s own condition holds, and the Epic-level gate runs normally. Under `--max-stories 1` driving this is how every Epic ends, so reading this paragraph as "a bounded invocation never runs the epic gate" skips the roll-up on the one invocation that earned it.
|
|
@@ -98,7 +113,7 @@ When the operator passed `--max-stories N`, count the stories this **invocation*
|
|
|
98
113
|
|
|
99
114
|
**An invocation can also finish having done durable work and advanced no row** — it decomposed an oversized story (above), or spent its budget authoring a story definition a resume will drive next. Neither is `complete`: no story reached a Stage-5 verdict, and `complete` with zero rows advanced is indistinguishable in the envelope from a run that drove its story successfully. Neither is a failure either.
|
|
100
115
|
|
|
101
|
-
Emit **`blocked`**, and carry the distinction in the typed escalation sidecar rather than in a new status value: `kind` is `"story-decomposed"` for a split or `"defined-not-driven"` for an authored-but-undriven story, `decision_needed` names what the next invocation should pick up, and `evidence` names the artifacts written. `kind` is open vocabulary by design (see "Escalation sidecar"), so this invents nothing. `scripts/drive_epic.py` reads those two kinds and reports the stop as a **handoff** rather than a bare halt
|
|
116
|
+
Emit **`blocked`**, and carry the distinction in the typed escalation sidecar rather than in a new status value: `kind` is `"story-decomposed"` for a split or `"defined-not-driven"` for an authored-but-undriven story, `decision_needed` names what the next invocation should pick up, and `evidence` names the artifacts written. `kind` is open vocabulary by design (see "Escalation sidecar"), so this invents nothing. `scripts/drive_epic.py` reads those two kinds, and `operator-evidence-owed` (`references/gate.md`), and reports the stop as a **handoff** rather than a bare halt. It still stops, and still exits non-zero, because a human does need to look at a decomposition, or record the evidence, before the drive continues.
|
|
102
117
|
|
|
103
118
|
`scripts/drive_epic.py` is the intended caller: it spawns one `claude -p` per story under `--max-stories 1`, deleting the pinned `run-result.json` before each spawn so the file's presence means *that* spawn reached a terminal, and it stops the drive if a session reports `complete` without its story having advanced to `done`. That last check is only sound because Stage 5's `advance` route **writes** the `done` row itself (`references/gate.md`) — the sub-skills leave a passing story at `review` or `in-progress`. If that sync is ever dropped, the driver's progress check goes with it: an unattended loop would read a healthy advance as no progress and halt.
|
|
104
119
|
|
|
@@ -109,7 +124,7 @@ Emit **`blocked`**, and carry the distinction in the typed escalation sidecar ra
|
|
|
109
124
|
**The conductor cannot start `/goal` itself.** It is a built-in slash command with no tool surface, so in an attended session, a `-H` session or a `drive_epic.py` spawn alike, a `/goal` is active only when the operator started one (typing `/goal <condition>`, or launching `claude -p "/goal …"`). Write the condition below either way, and record it in `.decision-log.md` at step 0 as the story's contract. When an operator did start a `/goal`, at launch or mid-session, that loop runs on the operator's own condition, not this one, and a turn clause in it bounds the session rather than the story. Keep it **under 4000 characters**, encoding the per-story Definition-of-Done as the success criterion with an explicit escape clause. The condition must:
|
|
110
125
|
|
|
111
126
|
- State the DoD in checkable terms: ATDD acceptance tests for the story un-skipped and **passing** (production) — or, under `--light`, the story's acceptance criteria demonstrably satisfied — plus lint clean, build green, and (production) test-review + code-review passed — mirroring the printed evidence so the transcript-only evaluator can corroborate it.
|
|
112
|
-
- Include the literal escape: **"…or stop after {workflow.max_turns_per_story} turns."** It belongs in the story's written contract, but it bounds nothing on its own, since no `/goal` runs on this condition. The only turn count every session keeps is the one the `budget_stop.py` Stop hook records in `{workflow.implementation_artifacts}/.budget-<story_id>.json` (`run-status.json` copies it into `budget_used.turns`, and when the two disagree the hook file wins). It advances once per Stop, that is once per response the session ends, so it cannot see re-loops spent inside a single response. Read it, never a count of your own, at two points. **Before a story's step 0** on the `story-boundary` and `mid-story` resume routes: a resume can inherit a counter already at or over `{workflow.max_turns_per_story}`, and then you escalate instead of driving that story (write `escalation-<story_id>.json` with `kind` `budget-overrun`, the kind `/ucg-resolve` resets the counter for, and end the invocation `blocked`, as `references/gate.md`'s `escalate` does). A `gate-owed` story is exempt and goes straight to step 5 and the gate, because its work is already committed. **Before each re-loop**, where `references/gate.md` turns a re-loop that would exceed the ceiling into `escalate` (a cap-only re-gate, which re-measures without re-driving, excepted). The hook itself only records and warns (a Stop hook **cannot force `/goal` to halt mid-condition**, and it never blocks), and the marker it writes on an overrun becomes an escalation only as described below: a story that then advances at its gate gets a sizing note instead. In a single attended or `-H` session with no operator `/goal`, nothing bounds re-loops spent inside one response; for `drive_epic.py` spawns, the `--session-timeout` wall clock is the backstop that holds whatever the count says (unless it is set to `0`). State the clause anyway.
|
|
127
|
+
- Include the literal escape: **"…or stop after {workflow.max_turns_per_story} turns."** It belongs in the story's written contract, but it bounds nothing on its own, since no `/goal` runs on this condition. The only turn count every session keeps is the one the `budget_stop.py` Stop hook records in `{workflow.implementation_artifacts}/.budget-<story_id>.json` (`run-status.json` copies it into `budget_used.turns`, and when the two disagree the hook file wins). It advances once per Stop, that is once per response the session ends, so it cannot see re-loops spent inside a single response. It counts responses, not work: a response that only acknowledges a background task's notification counts the same as one that edits code, so a story's waits spend its ceiling too ("Waiting spends turns" in the story loop above says how to keep that small). Read it, never a count of your own, at two points. **Before a story's step 0** on the `story-boundary` and `mid-story` resume routes: a resume can inherit a counter already at or over `{workflow.max_turns_per_story}`, and then you escalate instead of driving that story (write `escalation-<story_id>.json` with `kind` `budget-overrun`, the kind `/ucg-resolve` resets the counter for, and end the invocation `blocked`, as `references/gate.md`'s `escalate` does). A `gate-owed` story is exempt and goes straight to step 5 and the gate, because its work is already committed. **Before each re-loop**, where `references/gate.md` turns a re-loop that would exceed the ceiling into `escalate` (a cap-only re-gate, which re-measures without re-driving, excepted). The hook itself only records and warns (a Stop hook **cannot force `/goal` to halt mid-condition**, and it never blocks), and the marker it writes on an overrun becomes an escalation only as described below: a story that then advances at its gate gets a sizing note instead. In a single attended or `-H` session with no operator `/goal`, nothing bounds re-loops spent inside one response; for `drive_epic.py` spawns, the `--session-timeout` wall clock is the backstop that holds whatever the count says (unless it is set to `0`). State the clause anyway.
|
|
113
128
|
- Make explicit that **passing the condition is not completion** — the authoritative verdict is Stage 5's `gate_eval.py`. The `/goal` condition gets a story to a *plausibly* done, evidence-printed state; the gate decides.
|
|
114
129
|
|
|
115
130
|
Keep it under the character limit by referencing the story's `atdd-checklist` (or, under `--light`, its acceptance criteria) and printed test output rather than restating ACs verbatim.
|
|
@@ -133,7 +148,7 @@ It is a single JSON object, exactly these four string fields and no fifth:
|
|
|
133
148
|
|
|
134
149
|
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.
|
|
135
150
|
|
|
136
|
-
`kind` is **open vocabulary**. A reader renders whatever string it finds and never validates it against a fixed list
|
|
151
|
+
`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`).
|
|
137
152
|
|
|
138
153
|
**Promoting the turn-budget marker.** The `budget_stop.py` Stop hook writes only its own markdown, `{workflow.implementation_artifacts}/.escalation-<story_id>.md`. It stays a recorder: it emits no JSON and starts no process, and its marker records a count without stopping the drive, so the story still goes on to its gate. **Execute is the sole promoter of that markdown, and the story's gate decides whether it promotes.** A marker counts only while the story's recorded count (`turns` in `{workflow.implementation_artifacts}/.budget-<story_id>.json`) is at or past `{workflow.max_turns_per_story}`: after `/ucg-resolve` closes a `budget-overrun` escalation and resets that counter, the marker left on disk is the answered escalation's residue, and nothing below applies to it. **When the gate advances the story (`advance`, or `defer`, whose route advances anyway), do not promote the marker.** The gate decides completion, and none of the decisions the marker asks for has anything left to act on once the story is done: in a real project, every overrun escalation written for a story that then passed its gate was left open and never answered. Log a sizing note in `.decision-log.md` instead, naming the story and the hook's count against `{workflow.max_turns_per_story}`, and saying that a story of this shape should be split smaller next time; Finalize's run report carries it. **When the gate escalates the story on the turn count** (a re-loop that would exceed the ceiling, which `references/gate.md` turns into `escalate`), promote the marker as that escalation's sidecar: read the `.escalation-<story_id>.md` the hook left behind and write the typed sidecar from it, mapping `source` to that markdown's path, `kind` to `budget-overrun`, `decision_needed` to the human decision the marker asks for (re-scope, split, or hand off), and `evidence` to one line quoted from the marker. The gate can escalate on the count before the hook has written a marker (a re-loop expected to take several responses, from a count still under the ceiling); write the same `budget-overrun` sidecar then from `{workflow.implementation_artifacts}/.budget-<story_id>.json`, with `source` that file's path and `evidence` its count, so `/ucg-resolve` still resets the counter when it closes it. A cap-only `reloop` (a sweep-scope or delta cap) is not that verdict: the full re-gate it leads to decides. A story that escalates for its own reason (a gate file that cannot be read, a sub-skill halt) keeps that reason's sidecar, and the marker's count goes into the decision log beside it. A resume that finds the count already at or past the ceiling escalates before step 0 with the same `kind`, as "Authoring the `/goal` condition" above says. Keeping promotion here means one code path produces the typed JSON whatever the escalation's origin, instead of two writers racing on a file three readers depend on.
|
|
139
154
|
|
|
@@ -24,7 +24,7 @@ Walk every entry **this invocation wrote** (scope, preflight verdict, each gate
|
|
|
24
24
|
Produce a report (write it as a peer of `.decision-log.md` in the run folder, e.g. `run-report.md`) covering the list below. **A prior invocation's report already sitting at that path is the NORMAL state, not a surprise**: under `--max-stories N` the run folder persists across invocations, the Write tool refuses a file that has not been Read this session, and on a mature Epic the prior report cannot be Read cheaply either. Do not Read it and do not improvise a name — archive it first with one Bash move to the next free `run-report-<n>.md` (`<n>` increments per archive; list the folder to find the free slot), then write this invocation's report at `run-report.md`. The latest account is always `run-report.md`; the archives are prior invocations' accounts, ordered by `<n>` — one scheme, stated here, instead of one invented per session.
|
|
25
25
|
|
|
26
26
|
- Epic and profile (production / `--light`), branch off `{workflow.epic_branch_prefix}`.
|
|
27
|
-
- **The terminal route this run took
|
|
27
|
+
- **The terminal route this run took**: Epic complete, work-bounded, `partial-complete`, handoff, or escalated (the five named at the top of this stage). When the Epic still owes stories, give how many and their ids: under `--max-stories N` the conductor already logged the bound and the carried-over ids to `.decision-log.md` (`references/execute.md`), and a handoff names them in its escalation sidecar. The status word cannot carry this (a work-bounded run ends `complete`), so the report is where a returning reader learns whether the Epic is finished. An `operator-evidence-owed` escalation takes the escalated route even though `scripts/drive_epic.py` prints it as a handoff, because its story reached a Stage-5 verdict: say the story is delivered and gated except the evidence its sidecar names.
|
|
28
28
|
- Per-story outcome: gate_status and verdict (advance / defer / reloop / escalate), and any re-loops spent against budget. For a story that advanced with its count at or past the turn ceiling, its sizing note: the Stop hook's count against `{workflow.max_turns_per_story}`, which raised no escalation because the gate advanced the story, taken from `.decision-log.md`, or from `{workflow.implementation_artifacts}/.budget-<story_id>.json` when the session ended before the note was logged.
|
|
29
29
|
- **Gate provenance per story** — `tea` or `hand-authored`, copied from the `gate-provenance:` line Stage 5 logged (`references/gate.md`). Say it per story rather than once for the run: a mixed Epic is the common shape, and a reader who is told only "production profile" cannot tell which stories the model itself supplied the gate file for. If every story reads `hand-authored`, say that in one sentence — an Epic gated entirely on artifacts the run wrote for itself is the single most important caveat on its own report.
|
|
30
30
|
- The `epic-<id>` row's value in `sprint-status.yaml` at close: `done` only when the Epic-level gate advanced, on an `advance` or on a `defer`, whose route advances anyway (`references/gate.md`). BMAD Method 6.12 has no other writer of that `done`, so never tell the operator `bmad-retrospective` will close the row; it writes only the retrospective row.
|
|
@@ -70,7 +70,7 @@ Whichever case applies, repeat in the run report a `NOTE recall-latch-visible` l
|
|
|
70
70
|
uv run {skill-root}/scripts/mem_observation.py drain --impl-artifacts {workflow.implementation_artifacts} --store '{workflow.cross_session_recall_store}' --project-root {project-root}
|
|
71
71
|
```
|
|
72
72
|
|
|
73
|
-
2. **Write this run's record**: epic, run-id (this invocation's own, minted at Stage 1 or at a resume's re-entry and reused verbatim: the record file is named after it), gate-status, verdict, the deferred-work path, any root causes by taxonomy class, and the mechanical `recurred` yes/no for each Stage 1 advisory consumed. Pass no project name: the script takes it from the main worktree's directory, and the store tells repos apart by fingerprint alone.
|
|
73
|
+
2. **Write this run's record**: epic, run-id (this invocation's own, minted at Stage 1 or at a resume's re-entry and reused verbatim: the record file is named after it), gate-status, verdict, the deferred-work path, any root causes by taxonomy class, and the mechanical `recurred` yes/no for each Stage 1 advisory consumed. Pass no project name: the script takes it from the main worktree's directory, and the store tells repos apart by fingerprint alone. When the run stopped on a story that has no gate status (it escalated or handed off before that story's gate ran, or the gate came back `NOT_EVALUATED`), pass `--gate-status NOT_EVALUATED --verdict blocked`: the script writes that record like any other, so the next run's recall sees that this one blocked. Name a root cause for an escalation as for any blocked run, and none for a handoff. Name none either for a run that stopped on `decision-pending` (a resume that found the re-entry story's escalation still open, per `references/execute.md`): the run that raised that escalation recorded its root cause, and naming it again would make recall count one failure as recurring.
|
|
74
74
|
|
|
75
75
|
```
|
|
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=<s>,recurred=<yes|no|unknown>]…
|
|
@@ -13,6 +13,8 @@ The gate reads artifacts TEA produces. In **production**, before running the gat
|
|
|
13
13
|
|
|
14
14
|
`bmad-testarch-nfr` (produces `nfr-assessment.md`) and `bmad-testarch-test-review` are independent — of each other *and* of the automate→trace chain — so run them in any order, or concurrently with it; `gate_eval.py` consumes all three artifacts without caring how they were produced. (`bmad-testarch-test-review` normally runs in Execute per story — run it here only if you lack a current `test-review.md` for the story.) In **`--light`**, skip all of the above and run only `bmad-testarch-trace`, then the gate with `--profile light` (trace gate only — no NFR/review AND).
|
|
15
15
|
|
|
16
|
+
**Operator evidence is a recorded live result, in either profile.** An AC tagged `**Gate-ability:** operator-evidence` (`references/define-done.md`, step 1) is proven only through TEA's live verification results, which trace reads as `live_results_input` and which TEA lets a person write. For a story with such an AC the file is `{workflow.trace_output_dir}/live-verification-results-<story_id>.json`; name it (absolute, main tree) when you delegate trace. Each record carries `id` `<story_id>-LIVE-<NNN>`, `requirement_id` `AC-<n>`, `status`, `evidence` and `source_sha`, under `schema_version` `0.1.0`. A `pass` counts only at the commit trace measures. Write no record the operator did not give you, and name the operator as `producer`. TEA caps a requirement covered only this way at CONCERNS, so the story defers. That is the honest outcome, never a gap to close with a test that restates the record.
|
|
17
|
+
|
|
16
18
|
## Measure the commit, not the working tree
|
|
17
19
|
|
|
18
20
|
Stage 5's subject is a COMMIT, but an assessor that runs or times anything by default measures the WORKING TREE — which is where the next remediation, or a sibling assessor's mutation window, happens. A measured run recorded the consequence three times in one story even under a strict no-concurrent-work rule: one assessor's mutation window contaminated a sibling's timing run (discarded and re-run), and two assessors invented their own ad hoc isolation mid-gate because they could not trust the shared tree. Make the isolation structural instead of a discipline each assessor re-derives: create a worktree of the commit under assessment — `git worktree add <tmp-path> <commit>`, with `<tmp-path>` under `{workflow.implementation_artifacts}/.gate-worktree-<story_id>` (the same containment Execute's scratch rule buys; never an improvised repo-root directory) — and point every assessor's reads, runs and measurements THERE. Their OUTPUTS go home: every artifact an assessor writes — trace report, gate decision, NFR assessment, test review, `bmad-testarch-automate`'s backfilled coverage — lands in the MAIN tree's resolved dirs (`{workflow.trace_output_dir}`, `{workflow.implementation_artifacts}`, resolved to absolute paths against `{project-root}` BEFORE any assessor is pointed at the worktree), never under the worktree. The worktree is the measurement surface, the main tree is the record — an artifact written into the worktree is destroyed with it, after which the gate re-reads the PREVIOUS cycle's same-named artifact as current (resolution is by name, with no freshness check), which is a stale PASS advancing a story whose fresh assessment was never read. Once the story's verdict is recorded, remove the worktree with `git worktree remove --force <tmp-path>` — the copied-in untracked inputs below make the unforced form refuse, and a measurement surface holds nothing to preserve — then `git worktree prune`; a resume that finds a dead session's stale `.gate-worktree-<story_id>` removes it the same way before creating its own. A step that only authors an artifact from already-recorded evidence has nothing to measure and needs no worktree; the rule binds every assessor that runs or times anything. Three caveats the setup owes, each a measured failure when skipped:
|
|
@@ -81,7 +83,7 @@ The score **must** carry the `/100` denominator: a bare `score: 89` matches noth
|
|
|
81
83
|
|
|
82
84
|
## Run the gate
|
|
83
85
|
|
|
84
|
-
**Name the per-story paths trace writes, in either profile.** TEA 1.27.2's `bmad-testarch-trace` writes fixed, flat paths at the TEA `test_artifacts` root (`traceability-matrix.md`, `e2e-trace-summary.json`, `gate-decision.json`) and does not read `trace_output`. Left alone, its output neither lands in `{workflow.trace_output_dir}` nor names a story, so the gate below resolves nothing there, and each story's trace overwrites the last one's. When you delegate trace for a story, name the paths it must write in `{workflow.trace_output_dir}`: `trace-<story_id>.md` (frontmatter `workflowType: testarch-trace` and `gateDecisionFile: gate-decision-<story_id>.json`), `gate-decision-<story_id>.json` and `e2e-trace-summary-<story_id>.json`, with `<story_id>` the sprint-status key copied verbatim. If it writes the flat files anyway, move them to those names before anything else reads or overwrites them. Ask for nothing beyond those names
|
|
86
|
+
**Name the per-story paths trace writes, in either profile.** TEA 1.27.2's `bmad-testarch-trace` writes fixed, flat paths at the TEA `test_artifacts` root (`traceability-matrix.md`, `e2e-trace-summary.json`, `gate-decision.json`) and does not read `trace_output`. Left alone, its output neither lands in `{workflow.trace_output_dir}` nor names a story, so the gate below resolves nothing there, and each story's trace overwrites the last one's. When you delegate trace for a story, name the paths it must write in `{workflow.trace_output_dir}`: `trace-<story_id>.md` (frontmatter `workflowType: testarch-trace` and `gateDecisionFile: gate-decision-<story_id>.json`), `gate-decision-<story_id>.json` and `e2e-trace-summary-<story_id>.json`, with `<story_id>` the sprint-status key copied verbatim. If it writes the flat files anyway, move them to those names before anything else reads or overwrites them. Ask for nothing beyond those names, those frontmatter keys and, for a story with an operator-evidence AC, the live results file trace reads ("Operator evidence is a recorded live result" above): the provenance stays `tea` only while TEA's own steps computed the content.
|
|
85
87
|
|
|
86
88
|
Production:
|
|
87
89
|
|
|
@@ -118,9 +120,11 @@ Do not recompute TEA thresholds or re-judge `gate_status` — read it as given.
|
|
|
118
120
|
|
|
119
121
|
## Route on the verdict
|
|
120
122
|
|
|
121
|
-
|
|
123
|
+
**A logged verdict settles an owed re-gate.** Once this story's verdict is recorded in `.decision-log.md` ("Run the gate" above), and before you take any route below, delete `{workflow.implementation_artifacts}/.regate-<story_id>` if it exists. `/ucg-resolve` wrote it on closing the story's `operator-evidence-owed` escalation, to route a resume to this re-gate (`references/execute.md`'s resume rule), and a logged verdict leaves no re-gate owed.
|
|
124
|
+
|
|
125
|
+
- **`advance`** (gate_status PASS or WAIVED) → the story passes (an operator-evidence AC still owed its evidence is parked on the ledger first, as `defer` below says). **Sync the story's row in `sprint-status.yaml` to `done` before moving on**: set `development_status[<story_id>]` to `done`, preserving the file's comments and key order, and log the transition in `.decision-log.md`. This write is the run's own, not a sub-skill's: `ucg-dev-story` leaves the row at `review`, and `bmad-code-review` (production only; it does not run under `--light` at all) writes `done` **only** when nothing was left as an action item, so a story that legitimately `defer`s a non-critical finding is left at `in-progress`. Every downstream reader keys on `done`: Stage 1's in-scope rule (`references/ingest-and-scope.md` rule 3), the Epic-level trigger in this very sentence, and `scripts/drive_epic.py`'s progress check. So an advanced story whose row still says `review` is an advanced story the next reader re-drives, and an Epic whose last story advanced without this write never satisfies the Epic-level condition below. Sync it here, at the one place the authoritative verdict is known. In the same write, move the Epic's own `epic-<id>` row from `backlog` to `in-progress` when it still reads `backlog` (never backward, and only when the key exists): `bmad-build` makes that move when a story starts, but the story skills this run delegates to skip it when handed an explicit story key, so without it a finished Epic still reads `backlog`. If the Stop hook left a turn-budget marker for this story (`{workflow.implementation_artifacts}/.escalation-<story_id>.md`) and its count is still at or past the ceiling, do **not** promote it: log the sizing note `references/execute.md` describes under "Promoting the turn-budget marker", and leave the marker in place.
|
|
122
126
|
|
|
123
|
-
**Commit the gate's evidence before the next story starts.** The `done` sync, this story's trace and gate files (`trace-<id>.md`, `gate-decision-<id>.json`, `e2e-trace-summary-<id>.json`, and in production its per-story NFR assessment and test review), this gate's ledger rows and the decision log (with the first story, also Stage 3's test-design output) are tracked state written after Execute's commit-at-green. While `.current-story` still names this story, stage those of these paths that exist and are not ignored, by explicit path, in one call, and commit them in a second, before the next story's step 0. For the story whose advance makes every story `done`, make this commit after the Epic-level gate below instead, so it also carries that gate's writes. The commit carries no source or test path, so the story's existing tests-ran marker covers it: reuse that marker as it stands and never rewrite it for this commit. If it must carry an executable path (in production, tests automate backfilled), re-run the sweep and write a fresh marker per `references/execute.md` step 5 first. Then refresh `.commit-<story_id>` from `HEAD`, so this story's range in the gate trail includes the evidence commit. A path the project ignores is logged and left out, never forced in with `git add -f`; if nothing is staged, make no commit and leave `.commit-<story_id>` as it is. A resume that finds an advanced story's evidence still uncommitted makes this commit for it before the next story's step 0: point `.current-story` back at that story (its tests-ran marker still passes the guard), commit, and refresh its `.commit-<story_id>`. Then move to the next story.
|
|
127
|
+
**Commit the gate's evidence before the next story starts.** The `done` sync, this story's trace and gate files (`trace-<id>.md`, `gate-decision-<id>.json`, `e2e-trace-summary-<id>.json`, and in production its per-story NFR assessment and test review), its live results file when it has an operator-evidence AC, this gate's ledger rows and the decision log (with the first story, also Stage 3's test-design output) are tracked state written after Execute's commit-at-green. While `.current-story` still names this story, stage those of these paths that exist and are not ignored, by explicit path, in one call, and commit them in a second, before the next story's step 0. For the story whose advance makes every story `done`, make this commit after the Epic-level gate below instead, so it also carries that gate's writes. The commit carries no source or test path, so the story's existing tests-ran marker covers it: reuse that marker as it stands and never rewrite it for this commit. If it must carry an executable path (in production, tests automate backfilled), re-run the sweep and write a fresh marker per `references/execute.md` step 5 first. Then refresh `.commit-<story_id>` from `HEAD`, so this story's range in the gate trail includes the evidence commit. A path the project ignores is logged and left out, never forced in with `git add -f`; if nothing is staged, make no commit and leave `.commit-<story_id>` as it is. A resume that finds an advanced story's evidence still uncommitted makes this commit for it before the next story's step 0: point `.current-story` back at that story (its tests-ran marker still passes the guard), commit, and refresh its `.commit-<story_id>`. Then move to the next story.
|
|
124
128
|
|
|
125
129
|
When **every story of the Epic is `done`**, run the Epic-level gate: pass the epic's own id via `--story`, **add `--epic-level`**, and read its `gate_status` **only**. TEA produces NFR and test-review **per story, not per epic**, so there is no epic-level aggregate to AND, and every story's own production gate already ANDed its signals before reaching `done`. With `--rollup` the epic id is the sprint-status grouping key and the verdict is a computation over the per-story record; only in the omit-`--rollup` fallback is `--story` resolved against an epic-named artifact (scoped per the `--story` note above) and the roll-up a pure trace read. When the Epic-level gate returns `advance`, or `defer` (whose route advances anyway), set the `epic-<id>` row to `done` (when the key exists), preserving comments and key order, log it, and carry it in the last story's evidence commit. BMAD Method 6.12 has no other writer of an epic row's `done`, and `bmad-retrospective` writes only the `epic-<id>-retrospective` row. Never write it on any other route: the work bound, `partial-complete`, a handoff, a block or an escalation.
|
|
126
130
|
|
|
@@ -134,11 +138,17 @@ uv run {skill-root}/scripts/gate_eval.py --trace-output {workflow.trace_output_d
|
|
|
134
138
|
|
|
135
139
|
**Declare the omission; do not imply it.** `--epic-level` is what makes the skipped ANDs correct rather than the signal-dropping the per-story gate forbids in "Run the gate". The two used to be the same input — leaving the flags off — so a forgotten flag on a story gate was indistinguishable from a legitimate epic roll-up, and the story gate silently advanced on a signal nobody read. Without the flag, `--profile production` now treats an absent `--nfr`/`--test-review` as failing. Passing an epic-level `--test-review`/`--nfr` path that no aggregate writes is the mirror mistake, and the script now refuses the combination outright rather than evaluating it: it is an **invocation error, not a gate verdict** — argparse prints a usage line naming `--epic-level` and exits `2`, computing no verdict at all (the same lane a missing `--story` occupies in `references/finalize.md`). So there is no `reloop` to route on and no gate artifact to re-read: fix it by re-issuing the command without the paths. Under `--profile light` the flag is a no-op, since that profile runs no ANDs at all. Then proceed to Stage 6 (`references/finalize.md`). **Partial-by-design exception:** if this run delivered only a deliberate *strict subset* of the Epic's stories (in-scope ⊊ Epic — e.g. a conditional / evidence-gated Epic where the operator scoped a subset; this is distinct from ingest-and-scope.md's already-`done`-skipping, which still ends with every story `done`) — do **not** author an Epic-level gate: a PASS would misrepresent an incomplete Epic as complete. Record the per-story advance(s) and proceed to Stage 6 with the Epic left in its partial / conditional state (the `partial-complete` terminal outcome — see `references/finalize.md`).
|
|
136
140
|
|
|
137
|
-
- **`defer`** (gate_status CONCERNS, or non-critical code-review / NFR findings that did not flip the gate) → append the open items to the ledger at `{workflow.deferred_work_path}` using the schema below, then **advance** anyway. The Epic keeps moving; the parked work is visible.
|
|
141
|
+
- **`defer`** (gate_status CONCERNS, or non-critical code-review / NFR findings that did not flip the gate) → append the open items to the ledger at `{workflow.deferred_work_path}` using the schema below, then **advance** anyway. The Epic keeps moving; the parked work is visible. **On `advance` or `defer`, an operator-evidence AC still owed its evidence is parked too**: an uncovered P2 or P3 criterion may leave the gate at PASS or CONCERNS, so the story can move without it. It still counts toward TEA's overall coverage, so it can also FAIL the gate, and a FAIL goes to `operator_owed.py` (the next bullet), never to this ledger. It is owed while its live results file holds no `pass` record for it at the commit the gate measured, or while TEA holds it below FULL with only the records it counted there; append a row with `source` `gate` naming the AC, the evidence it owes (for a partly recorded AC, the ids of the records TEA counted and the part still owed) and that file.
|
|
142
|
+
|
|
143
|
+
- **A FAIL only operator evidence can change is not a re-loop.** On every gate_status FAIL, first run the command below (for a decomposed child, `--story-file` is its parent's story file). Under `--light`, pass `--profile light` and no `--nfr` or `--test-review`; in either profile, pass `--cycle-profile` exactly as the gate took it. On `owed: true`, take `escalate` with `kind` `operator-evidence-owed`: `source` is the trace report's path, `decision_needed` names the ACs in `operator`, what each owes, `assessed_commit`, the live results file to record into, and that `/ucg-resolve` closes it once the records are there or once the operator narrows or moves the AC in writing, and `evidence` is TEA's gap line for the first of those ACs. Write no `class:` line, run no `bmad-correct-course`, spend no re-loop, and commit nothing after the assessed commit, since a later commit makes the record stale. Attended, the operator may record it now; then re-gate the same commit in-session. Otherwise `/ucg-resolve` closes it with the records on disk and writes `.regate-<story_id>`, and the resume re-gates that commit rather than re-driving the story (`references/execute.md`'s resume rule). An open operator-evidence AC that already holds a `pass` record TEA counted at the assessed commit is still owed: TEA held it below FULL because the record covers only part of the criterion, and no re-loop can record the rest or narrow the AC, so the script lists it in `operator` and in `partial`, which maps it to the ids of the records TEA counted. For each AC in `partial`, `decision_needed` names the record ids TEA already counted, says they cover only part of the criterion, and asks the operator to record the rest or to narrow or move the AC in writing. On `owed: false`, the `reloop` route below stands; log the script's `reasons`.
|
|
144
|
+
|
|
145
|
+
```
|
|
146
|
+
uv run {skill-root}/scripts/operator_owed.py --trace-output {workflow.trace_output_dir} --story <story_id> --story-file <story file> --profile production --nfr {nfr-assessment.md} --test-review {test-review.md} --tests-ran {workflow.implementation_artifacts}/.tests-ran-<story_id>
|
|
147
|
+
```
|
|
138
148
|
|
|
139
149
|
- **`reloop`** (gate_status FAIL, or a production signal downgraded an advance, or a cap — sweep-scope or delta-profile) → **generalize before fixing.** Before `bmad-correct-course` writes any fix, take the verdict's `reasons` and the review's findings and, for each finding: (1) name, in ONE line, the defect CLASS the finding is an instance of; (2) state whether any earlier review of this story or this Epic already found that class — the previous gate artifacts and `{workflow.implementation_artifacts}/.class-ledger-<epic_id>.md` are the evidence, and they are already on disk, so this is a read, not a judgment call; (3) where the class is a repeat, the fix must close the CLASS — every sibling instance the same seam admits, not the one instance the reviewer demonstrated — and the log records why the class-level fix was not taken when the class was first named. A measured run spent five of six reviews re-finding one class ("an assertion that cannot go red") one seam over each time, with the class-killing move available from day one; the generalize step is what makes cycle N read cycle N-1 instead of re-buying it. Record one `class:` line per finding in this re-loop's `.decision-log.md` entry, and append any class not already present to `.class-ledger-<epic_id>.md` (create on first use; named for the Epic, so a later Epic starts a fresh ledger while this Epic's survives across its own invocations for exactly the resume case; one line per class, `- <class, one line> — first named <story_id>, cycle <n>`; **append-only** — Execute step 1 reads it before every story and re-loop, so a class named once is warned about everywhere after, including across stories, which no per-story artifact can do). **A score that does not move indicts the FIX STRATEGY, not the code:** when two consecutive gate evaluations of this story have moved `review_score` by less than 3 (production — under `--light` no review score exists, so the trigger there is two consecutive re-loops whose findings name any class already in the ledger), the generalize answers above are mandatory *in writing* before any further fix — a re-loop whose findings all name the same class as the previous re-loop's is a re-loop about to be spent badly. **A cap-only re-loop skips the ceremony.** When a cap alone produced the verdict — the `reasons` show only the sweep-scope cap, the delta-profile cap, or both, with no gate FAIL and no failed production signal — there is no finding to generalize and nothing to diagnose: re-run the full three-axis sweep where the sweep cap fired and refresh the marker with `scope=full`, then re-run the gate as the FULL instrument — **dropping `--cycle-profile`**, because the delta cap is lifted by the flag's absence and a re-gate that keeps it caps again forever — writing no `class:` lines, appending nothing to the ledger, and skipping `bmad-correct-course` entirely; such evaluations do not count toward the flat-score tripwire, and a capped CONCERNS keeps its findings for the next gate's own `defer` route — parking them is that gate's job, not this re-loop's. A cap-only re-gate re-measures without re-driving the story, so the turn-ceiling rule below never turns it into `escalate`. Otherwise, run `bmad-correct-course` to diagnose and adjust, then re-run the story (back through Execute, `references/execute.md`) — **within the remaining turn budget**. Re-run the gate after. If the re-loop would exceed `{workflow.max_turns_per_story}`, treat it as `escalate` instead; the count is the `turns` value the Stop hook records in `{workflow.implementation_artifacts}/.budget-<story_id>.json`. When the hook left a turn-budget marker for this story, that escalation's sidecar is the marker's promotion (`references/execute.md`, "Promoting the turn-budget marker").
|
|
140
150
|
|
|
141
|
-
- **`escalate`** (gate_status NOT_EVALUATED
|
|
151
|
+
- **`escalate`** (gate_status NOT_EVALUATED, meaning the gate could not be read; budget exhausted on a FAIL; or a FAIL only operator evidence can change, above) → **stop.** Do not advance, do not defer the failing item. Record the reason and the verdict JSON in `.decision-log.md`, and write the typed escalation sidecar `{workflow.implementation_artifacts}/escalation-<story_id>.json` (shape in `references/execute.md`, under "Escalation sidecar") so the pending decision is readable without the transcript. In an attended run, surface the blocker to the user. In headless, this is a `blocked` outcome: emit the JSON in Stage 6 (`references/finalize.md`).
|
|
142
152
|
|
|
143
153
|
**INVARIANT — a P0/critical FAIL never defers.** A failing gate (or a P0/P1/overall threshold miss) is `reloop` or `escalate`, never `defer`. Only non-gate-blocking work (CONCERNS, non-critical findings, parked decisions) is allowed onto the ledger. If you find yourself about to write a FAIL or a critical finding to the ledger, you are violating the gate — re-loop within budget or escalate instead.
|
|
144
154
|
|
|
@@ -156,7 +166,7 @@ Append to `{workflow.deferred_work_path}` (create on first use). One heading per
|
|
|
156
166
|
| d1 | gate | low | <story-id> | <why parked> | <what to do later> | open |
|
|
157
167
|
```
|
|
158
168
|
|
|
159
|
-
- `source` ∈ `gate` (CONCERNS), `code-review` (non-critical finding), `nfr` (non-FAIL finding), `decision` (parked decision).
|
|
169
|
+
- `source` ∈ `gate` (CONCERNS, or an operator-evidence AC's evidence still owed), `code-review` (non-critical finding), `nfr` (non-FAIL finding), `decision` (parked decision).
|
|
160
170
|
- `severity` ∈ `low`, `med`, `high`. A `high` that maps to a gate FAIL or a P0/critical finding does **not** belong here — re-loop or escalate it.
|
|
161
171
|
- `id` is unique within the Epic heading (append `d2`, `d3`, … ). Note that the id is unique only WITHIN its heading, so `d1` under two Epics is two different decisions; a project-wide reader must key them by more than the raw column (`/ucg-resolve` mints an id for exactly this reason).
|
|
162
172
|
- `status` ∈ `open`, `resolved`. **This gate only ever appends rows, and never rewrites one** — but the column is not frozen forever: `/ucg-resolve` flips `open` to `resolved` when an operator closes a parked decision, and that single transition is the one sanctioned edit to an existing row. Everything else about a row is immutable once written: never restate its `id`, `source`, `severity`, `story`, `reason` or `suggested_action`, because the ledger is the durable account of what was parked and rewriting it loses the history the Epic close-out reads.
|
|
@@ -32,6 +32,8 @@ Resolution order:
|
|
|
32
32
|
2. Confirm the Epic has a body (acceptance-bearing stories or an Epic file). A title-only Epic with no stories is not blocking here: Stage 2 generates missing stories/ACs via `ucg-create-story`. Note it so Stage 2 expects remediation.
|
|
33
33
|
3. **In-scope = not-yet-`done`.** The run's in-scope stories are the resolved Epic's stories whose rollup status is not `done`. A partially-done Epic — say stories 1–3 hand-finished before this run was ever invoked — carries only its remaining stories into preflight; log the done ones as `skipped-already-done` so Execute never re-drives them (the resume cursor only covers re-invocations that have a prior run folder; this rule covers the fresh invocation that doesn't). **The `done` rows this rule skips are trusted, so audit them cheaply before trusting them**: a row that reached `done` without its gate artifacts — a crash between the sync and the artifacts, an older defect, a hand-edit — is otherwise invisible forever, because resume routing keys on the log and the row, never on artifacts, and the gate trail fails soft over the hole. One directory listing suffices: list `{workflow.trace_output_dir}` once and name in `.decision-log.md` any `done` story of this Epic with no `trace-<id>.md` / `gate-decision-<id>.json` pair, as `done-without-gate-artifacts`. **Judge "no pair" the way `gate_eval.py` resolves, not by stem equality**, or the listing invents holes the gate will not see: id components are tolerated (`11-6` == `11.6` == `11_6`), a gate decision named by the trace report's `gateDecisionFile` frontmatter hint counts as resolved, and so does an `e2e-trace-summary-<id>.json` carrying the gate fields (the fallback `gate.md` calls "**not** a failure"). This is **never a launch blocker and never a re-drive trigger on its own** — but it is not merely operator context either: every row named here **will refuse the Epic-level `--rollup` at Stage 5** (`gate.md`: any `done` story with no resolvable gate artifact of its own → `NOT_EVALUATED` → `escalate`), so a partially hand-finished Epic drives each remaining story to `advance` and then blocks at the one gate that certifies the Epic. Log it with the two ways out: author the missing per-story `trace-<id>.md` / `gate-decision-<id>.json` before launch, or accept that the Epic gate will escalate while the per-story advances stand. **Operator-scoped subset:** if the operator deliberately names a *strict subset* of the not-`done` stories (a conditional or evidence-gated Epic where only some stories are in play this run), honor it — in-scope ⊊ Epic. Such a run ends in the **`partial-complete`** terminal state with no Epic-level gate authored (gate.md / finalize.md), distinct from the already-done skip above, which still ends with every story `done`. Headless never narrows this way: its in-scope is every not-`done` story, so a successful headless run finishes the Epic **unless the operator bounded the invocation's work with `--max-stories N`** — that flag drives fewer of the in-scope stories without narrowing the set (`references/execute.md`), so the Epic is finished by the *next* invocation's resume rather than by this one. In-scope is the same either way; only how much of it one invocation takes on differs.
|
|
34
34
|
|
|
35
|
+
**An operator-scoped subset is recorded by key.** Name each story in it in `.decision-log.md` by its key, as its `sprint-status.yaml` row spells it: Stage 2 passes each to the readiness check as `--story <key>` (`references/preflight.md` step 1b), so the verdict reads those stories and no others.
|
|
36
|
+
|
|
35
37
|
**A decomposed parent owes no pair.** Leave out of `done-without-gate-artifacts` a `done` row the Epic-level `--rollup` reads through its children (`references/gate.md`, "A decomposed parent is read through its children, on its split record"): its split record, `.split-<its key>.json` beside `sprint-status.yaml`, names it as the parent and names children each of which is another story row of this Epic, no chain of records leads from it back to it, and `--story <its key>` would find no trace report, gate decision or trace summary of its own. It never refuses the Epic gate. A decomposed parent with no record is listed like any other `done` row with no pair, and its way out is the record: one `scripts/story_sizing.py` run for its split with `--parent` and `--record` (`references/execute.md`).
|
|
36
38
|
4. **Already-done short-circuit.** If *every* story for the resolved Epic is already `done`, do not carry a no-op Epic into preflight: surface "this Epic is already complete — re-run anyway?" and proceed only on a yes (an explicit yes re-scopes all stories deliberately). Headless: emit the same five-key blocked JSON (`report`/`deferred_work` `null`) with `reason` "epic already complete", built by the `scripts/headless_envelope.py` `build_headless_envelope` adapter with `impl_artifacts={workflow.implementation_artifacts}` — the config resolved by this point, so the adapter also writes the envelope to `{workflow.implementation_artifacts}/run-result.json` (same bytes as stdout) for an automator to read.
|
|
37
39
|
5. If `sprint-status.yaml` is absent (the rollup says so and emits no Epics) or `{planning_artifacts}` has no PRD/ADR for this Epic, that is not a hard stop at this stage — record the gap; Stage 2 preflight reports it mechanically and the semantic scan judges whether the missing planning artifact is a true RED (undecided product/architecture) or a benign absence.
|