bmad-module-ultracode-goal 4.1.0 → 5.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +1 -1
- package/docs/_internal/STABILITY.md +3 -3
- package/package.json +1 -1
- package/skills/ucg-formalize/SKILL.md +7 -1
- package/skills/ucg-resolve/SKILL.md +2 -1
- package/skills/ultracode-goal/references/execute.md +12 -9
- package/skills/ultracode-goal/references/gate.md +4 -4
- package/skills/ultracode-goal/references/preflight.md +2 -0
- package/skills/ultracode-goal/scripts/claim_check.py +340 -15
- package/skills/ultracode-goal/scripts/formalize_check.py +228 -131
- package/skills/ultracode-goal/scripts/preflight_check.py +11 -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": "
|
|
22
|
+
"version": "5.0.0",
|
|
23
23
|
"author": {
|
|
24
24
|
"name": "Armel"
|
|
25
25
|
},
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Stability and Public Contract
|
|
3
|
-
description: "The
|
|
3
|
+
description: "The 5.x stability posture: which CLI, config, JSON, and gate surfaces are the supported public contract, what a major costs, and everything that is @internal and free to change."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
> **Status:**
|
|
6
|
+
> **Status:** 5.x. The surfaces below are the public contract. Per [Semantic Versioning 2.0.0](https://semver.org/), a breaking change to any of them requires a MAJOR bump; everything marked `@internal` may change in any release. This document is what a consumer pins against.
|
|
7
7
|
|
|
8
|
-
This is the stability posture for `bmad-module-ultracode-goal` at `
|
|
8
|
+
This is the stability posture for `bmad-module-ultracode-goal` at `5.x`. It enumerates the surfaces a downstream consumer or automator may reasonably depend on, versus everything else, which is `@internal`.
|
|
9
9
|
|
|
10
10
|
## Public contract
|
|
11
11
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://json.schemastore.org/package.json",
|
|
3
3
|
"name": "bmad-module-ultracode-goal",
|
|
4
|
-
"version": "
|
|
4
|
+
"version": "5.0.0",
|
|
5
5
|
"description": "BMAD module — Run a BMAD Epic autonomously to a machine-checked, TEA-gated Definition-of-Done.",
|
|
6
6
|
"keywords": [
|
|
7
7
|
"bmad",
|
|
@@ -91,7 +91,13 @@ them here. There is one kernel — a second readiness evaluator would let the tw
|
|
|
91
91
|
drift.
|
|
92
92
|
|
|
93
93
|
The kernel is fail-closed: a missing / unreadable / ambiguous artifact is recorded
|
|
94
|
-
as a failing gap, never a neutral pass.
|
|
94
|
+
as a failing gap, never a neutral pass. Of TEA's output it reads only the Epic's own,
|
|
95
|
+
under TEA's test-artifacts root (the TEA config's `test_artifacts`, else
|
|
96
|
+
`_bmad-output/test-artifacts`): every `test-design-epic-<id>.md`, and an
|
|
97
|
+
`nfr-assessment.md` whose `**Story:**` line names a story it reads (one beside the
|
|
98
|
+
Epic's test-design that cannot be read is a failing gap). A test-design or NFR
|
|
99
|
+
assessment the Epic does not have yet is no gap, and another Epic's test-design or
|
|
100
|
+
TEA's system-level files never raise one.
|
|
95
101
|
|
|
96
102
|
## 2. Mechanical auto-remediation pass
|
|
97
103
|
|
|
@@ -282,7 +282,8 @@ The two dispositions are genuinely different things, not two names for one:
|
|
|
282
282
|
and the id you closed, before you delete the sidecar: once the sidecar is gone, that
|
|
283
283
|
entry is the only copy of the move the resumed run writes into both story files, or for
|
|
284
284
|
two decomposed children into every record of their split (the split record, both child
|
|
285
|
-
rows in `sprint-status.yaml
|
|
285
|
+
rows in `sprint-status.yaml`, the earlier child's ATDD checklist and the later child's
|
|
286
|
+
when it has one). This
|
|
286
287
|
surface edits neither story file and moves no test case: the ruling is the operator's,
|
|
287
288
|
and the resumed run applies it before the earlier story's next commit. An answer that
|
|
288
289
|
re-plans the rows instead (one story in place of the two, or another order) is the
|
|
@@ -4,9 +4,9 @@ Drive each in-scope story from its red-phase acceptance tests (generated in Stag
|
|
|
4
4
|
|
|
5
5
|
One path: the **sequential `/goal` spine**, named for the `/goal`-style condition each story's drive is written against; the conductor cannot start a live `/goal` (see "Authoring the `/goal` condition"). (The experimental `--parallel` worktree fan-out is retired; the flag is still accepted so an old invocation does not error — see "Retired — `--parallel`" below.)
|
|
6
6
|
|
|
7
|
-
Preconditions (asserted, not assumed): you are on the Epic branch (`{workflow.epic_branch_prefix}…`, off a `{workflow.protected_branches}` branch), PreToolUse + Stop hooks are active in `.claude/settings.local.json`, the allowlist is pre-populated, and (**in production**) every in-scope story has an `atdd-checklist-{story_key}.md` with `test.skip` acceptance tests. (Under `--light` there is no atdd-checklist by design; the story file's clear acceptance criteria are the Stage-5 trace oracle instead: see define-done.md's `--light` note. The clear-ACs precondition still holds. **On a stack whose ATDD generator cannot run** (the non-web case `references/gate.md`'s hand-authoring section carves out), there is no atdd-checklist either, and that is not a failed precondition: the checklist is replaced by a red phase established BY HAND, authored, RUN and captured before the story's first implementation edit, per gate.md's non-web section and step 1 below. Routing such a run back to an earlier stage cannot produce the artifact and never terminates.) If any is false, return to the stage that produces the missing piece: branch, hooks or allowlist to Stage 2 (on a resume, the hooks by re-merging them through Stage 2's step 5 **Hooks** bullet alone, as "A hooks reason is fixed in place" below says); a genuinely missing atdd-checklist to **Stage 3** (define-done, the only stage that generates it; Stage 2 cannot). Two legitimate ways a story reaches this stage checklist-less, neither of which is a bounce: a **decomposed child row** (created after Stage 3 ran: run `bmad-testarch-atdd` scoped to that story
|
|
7
|
+
Preconditions (asserted, not assumed): you are on the Epic branch (`{workflow.epic_branch_prefix}…`, off a `{workflow.protected_branches}` branch), PreToolUse + Stop hooks are active in `.claude/settings.local.json`, the allowlist is pre-populated, and (**in production**) every in-scope story has an `atdd-checklist-{story_key}.md` with `test.skip` acceptance tests. (Under `--light` there is no atdd-checklist by design; the story file's clear acceptance criteria are the Stage-5 trace oracle instead: see define-done.md's `--light` note. The clear-ACs precondition still holds. **On a stack whose ATDD generator cannot run** (the non-web case `references/gate.md`'s hand-authoring section carves out), there is no atdd-checklist either, and that is not a failed precondition: the checklist is replaced by a red phase established BY HAND, authored, RUN and captured before the story's first implementation edit, per gate.md's non-web section and step 1 below. Routing such a run back to an earlier stage cannot produce the artifact and never terminates.) If any is false, return to the stage that produces the missing piece: branch, hooks or allowlist to Stage 2 (on a resume, the hooks by re-merging them through Stage 2's step 5 **Hooks** bullet alone, as "A hooks reason is fixed in place" below says); a genuinely missing atdd-checklist to **Stage 3** (define-done, the only stage that generates it; Stage 2 cannot). Two legitimate ways a story reaches this stage checklist-less, neither of which is a bounce: a **decomposed child row** (created after Stage 3 ran: run `bmad-testarch-atdd` scoped to that story right after its step 0 (next paragraph), or hand-establish its red phase at step 1 where ATDD cannot run) and the **non-web stack** above. Record which case it was, and what replaced the checklist, in `.decision-log.md`.
|
|
8
8
|
|
|
9
|
-
**A decomposed child's ATDD run** (the precondition's case above) follows `references/define-done.md` step 2's rule for a decomposed child: under the child's own key, so the checklist the commit guard reads is the child's; the parent's story file read for the text of the parent ACs the child claims, never edited; and, on a halt over vague criteria, an escalation, never a `ucg-create-story` run for the child.
|
|
9
|
+
**A decomposed child's ATDD run** (the precondition's case above) follows `references/define-done.md` step 2's rule for a decomposed child: under the child's own key, so the checklist the commit guard reads is the child's; the parent's story file read for the text of the parent ACs the child claims, never edited; and, on a halt over vague criteria, an escalation, never a `ucg-create-story` run for the child. The run is the child's own work: it comes after the child's step 0 (story loop, below) has written both the `.current-story` pointer and the child's baseline marker, and before step 1, so the Stop hook books its turns to the child. Step 0 is never split around it, pointer first and baseline after: the run commits nothing and leaves `HEAD` where it was, so the baseline step 0 records is the one the child starts from either way. Sizing still comes first ("Sizing: a story too large to drive" sizes the row ahead of step 0), so a child that is split again gets no run. In production, on a stack ATDD can run on, a resume that finds the child's `.baseline-<story_id>` still owes the run, before step 1, when `atdd-checklist-<child key>.md` is absent or a `generatedTestFiles` path it lists does not exist: an interrupted run can leave either.
|
|
10
10
|
|
|
11
11
|
**On resume, re-enter Execute at the first story whose last logged gate verdict is not advance; advanced stories are not re-run; re-assert (do not rebuild) the Epic branch, hooks, the allowlist, the `.mem-state.json` recall latch, and the in-flight story's baseline marker before continuing**, and read the story's recorded turn count before driving it ("Authoring the `/goal` condition" below says when a resumed count escalates instead). Before the next story's step 0, also check whether the last advanced story's gate evidence is still uncommitted, and if it is, make that evidence commit first, exactly as `references/gate.md`'s "Commit the gate's evidence before the next story starts" describes (and when that story advanced with its count at or past the turn ceiling and no sizing note was logged, log it now, per "Promoting the turn-budget marker"): a resume enters here, before Stage 5 is ever loaded, so this is where that rule has to be met. That story carries an `evidence-commit-rejected` escalation when a repo commit hook rejected that commit in a way the gate may not answer, so run the `--assert-armed` call below with `--story` naming that story first: while its `escalation` reads `open`, make no commit and take the `decision-pending` route below for that story, and once `/ucg-resolve` has closed it (its sidecar is gone, and `.evidence-owed-<story_id>` is still on disk), make the commit and remove that marker. Check every `.evidence-owed-<story_id>` of this Epic's stories this way, not only the last advanced story's: a marker whose evidence was committed some other way is removed as `references/gate.md` says, with no commit. When that story is the Epic's last, so every story reads `done`, no story is left to drive: after the commit go to Stage 6 (`references/finalize.md`) with the Epic-level verdict the log holds, and run neither a story nor the Epic-level gate again. Stage 1 resolved no in-scope story for that resume, so Finalize passes that story as its one `--story` to `scripts/gate_trail.py`, whose range then ends at the commit this resume made, and the run report names the route as the owed evidence commit made and the Epic complete. And "re-assert the hooks" means preflight step 5's assertion, not a presence check: both script paths appear in the resolved settings **and** the PreToolUse group's matcher is the all-tools form (`references/preflight.md`, "Arm the PreToolUse group with a matcher that covers EVERY tool"). A presence-only read passes on a prior run's `Bash`-only arming, and a resume that skips Stage 2 never meets the bullet where that requirement lives, so this is the one place it binds a resumed run, and without it the Cross-Session Recall invariant enforces nothing outside Bash for the whole session while every log line says the hooks are armed. The latch is *re-written* by re-running Stage 1's latch step (`references/ingest-and-scope.md`, its `mem_recall.py latch` command) with this invocation's own run id, minted first by Stage 1's convention and logged. A resume never reuses an id an earlier invocation logged: the run's record file is named after it and never rewritten, so a reused id turns this run's Finalize write into `skipped-existing` and loses its record. It is re-written because every terminal removes it with `mem_recall.py unlatch` (Stage 6 at every close-out), and the PreToolUse hook reads an absent latch as "no run active" and stops gating recall entirely. A latch already on disk whose `run_id` is not this run's is **another run's (or a spawning wrapper's) artifact, never evidence**: re-latch from this run's own measurement, which replaces it, and never inherit its `store_ok` colour, because an inherited green latch certifies a store this run never checked. Never delete that latch to make room for this run's: the guard refuses it while a latch is present, and the latch command is what replaces it. The baseline marker is the opposite of the latch, split by which case the resume is, and the test is simply whether `.baseline-<story_id>` exists. **Mid-story (it exists):** *re-read* and never regenerate: the story may already carry commits, and a rebuilt baseline silently re-anchors its evidence range to a mid-story HEAD. **Story boundary (it does not exist**, the NORMAL case under `--max-stories N`, where every invocation after the first resumes at a fresh story): there is nothing to re-read; write it fresh at `HEAD` exactly as step 0 does for a first-run story, because the PreToolUse marker-freshness gate fail-closes without it.
|
|
12
12
|
|
|
@@ -63,14 +63,17 @@ Then terminate as the work-bound section below describes for an invocation that
|
|
|
63
63
|
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):
|
|
64
64
|
|
|
65
65
|
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.
|
|
66
|
-
|
|
66
|
+
|
|
67
|
+
**Evidence never goes in scratch.** The scratch directory is removed before the story advances, while trace, the gate and the story record cite their evidence after that, so the story's evidence has a folder of its own, `{workflow.implementation_artifacts}/evidence-<story_id>/`, which no step removes. The red-phase capture (step 1's, on a stack where Stage 3 could not generate the ATDD scaffold), a sweep log the record or the gate cites, a coupled-stories measurement and a planted-defect run (a case shown red against a defect planted for it) go there; a runner or harness built only to produce them stays in scratch. It holds captured output and the notes recorded on it (the red count `references/gate.md`'s non-web item 4 records beside a red-phase capture), nothing runnable: it has no dot prefix, so on a tracked tree a repo-wide tool can reach it. The mutation ledger keeps its own name-pinned path (step 2). Name each capture by the step that wrote it and the commit `HEAD` named when it ran (`sweep-step2-<short sha>.log`, `sweep-step5-<short sha>.log`, `sweep-backfill-<short sha>.log`), and give a name already taken the next free number (`-2`), so no capture overwrites another: step 2's sweep can run at the `HEAD` the cycle before it measured at step 5 (when that cycle's gate committed no backfill), and the backfill's sweep runs at the `HEAD` step 5 measured. A file already in the folder when step 0 writes a fresh baseline is an earlier run's, never cited as this run's. On a tracked artifact tree the folder stays untracked, as the mutation ledger does: the gate's evidence commit stages its own list of paths, and this folder is not on it.
|
|
68
|
+
|
|
69
|
+
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 in `{workflow.implementation_artifacts}/evidence-<story_id>/` ("Evidence never goes in scratch", above). `references/gate.md`'s non-web section is the authority on the shape, but by the time that file is read at Stage 5 the window this rule governs has already closed. Before delegating, check the run's `.decision-log.md` for an **Operator notes** entry naming this story (a pre-launch hint like "watch the auth flow in story 3") and surface that note into the `ucg-dev-story` / review context for this story so the operator's last words actually reach the work. Read `{workflow.implementation_artifacts}/.class-ledger-<epic_id>.md` the same way when it exists (the defect classes this Epic's reviews have already caught, appended by the gate's re-loop route, `references/gate.md`) and surface it into the same context: a class named there is a class the reviewers will look for again, and code written blind to it is a re-loop pre-booked. (A story otherwise inherits nothing from its siblings' reviews: a measured run re-found the previous story's review finding on its very first cycle, so the ledger is the one artifact that crosses that boundary.)
|
|
67
70
|
**On a gitignored artifact tree** (`impl_artifacts_tracked: false`, which preflight step 1 reports and a resumed session reads in its `--assert-armed` manifest's `checks`), no test this story writes or un-skips may read a file under that tree, or any other path `git check-ignore` reports, at run time: it does not exist in CI. Point the test at a tracked fixture instead. Preflight step 2 states the rule ("A gitignored artifact tree"); a session that resumed straight into this stage may not have read it.
|
|
68
71
|
|
|
69
72
|
**An operator-evidence AC is not `ucg-dev-story`'s to satisfy.** When the story carries an AC tagged `**Gate-ability:** operator-evidence` (`references/define-done.md`, step 1), say so when you hand it the story: that AC is proven at the gate by a live result a person records (`references/gate.md`), so it builds nothing for it and does not hold the story's completion on it. An AC tagged plain `**Gate-ability:** operator` is not one: it is work `ucg-dev-story` builds like any other AC, which a person or a script then verifies.
|
|
70
73
|
|
|
71
74
|
**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.
|
|
72
75
|
|
|
73
|
-
**Two stories green only together: move the clauses in writing, never share a commit.** A plan can couple two in-scope stories so that the earlier story's commit cannot be green alone: the earlier story owes a clause only the later story's build can satisfy, and the later story often turns the earlier story's cases red without them, so no order helps. Step 5 advances a story only on its own green commit. Do not commit them together, leave the earlier story uncommitted, or gate both at one commit: the tests-ran marker, the range from `.baseline-<story_id>` to `.commit-<story_id>`, and the trace and gate decision are each one story's, and two stories gated at one commit share one range, so neither shows its own work (step 4's END sha). Driving the two rows as one unit is not a route this run takes either: only the operator re-plans rows, outside the run (one story in place of the two, or another order). The route is to move each such clause forward, to the later story, which must be an in-scope, not-`done` story of this Epic. That narrows the earlier story's AC, so it is the operator's decision, as the narrowing above is: never move a clause on your own ruling. As soon as the plan, a story file's notes, a red at step 2 or step 5, or a re-loop's findings show the coupling, and before the earlier story's next commit, capture for each clause a run on the earlier story's tree, to a file
|
|
76
|
+
**Two stories green only together: move the clauses in writing, never share a commit.** A plan can couple two in-scope stories so that the earlier story's commit cannot be green alone: the earlier story owes a clause only the later story's build can satisfy, and the later story often turns the earlier story's cases red without them, so no order helps. Step 5 advances a story only on its own green commit. Do not commit them together, leave the earlier story uncommitted, or gate both at one commit: the tests-ran marker, the range from `.baseline-<story_id>` to `.commit-<story_id>`, and the trace and gate decision are each one story's, and two stories gated at one commit share one range, so neither shows its own work (step 4's END sha). Driving the two rows as one unit is not a route this run takes either: only the operator re-plans rows, outside the run (one story in place of the two, or another order). The route is to move each such clause forward, to the later story, which must be an in-scope, not-`done` story of this Epic. That narrows the earlier story's AC, so it is the operator's decision, as the narrowing above is: never move a clause on your own ruling. As soon as the plan, a story file's notes, a red at step 2 or step 5, or a re-loop's findings show the coupling, and before the earlier story's next commit, capture for each clause a run on the earlier story's tree, to a file in the earlier story's `{workflow.implementation_artifacts}/evidence-<story_id>/` ("Evidence never goes in scratch", above), showing that the code it needs exists only in the later story's build. Only a clause so measured moves. The operator's ruling takes one of two forms. An **Operator notes** entry given before launch (`references/ingest-and-scope.md`, "Operator notes") that names both stories and authorizes moving clauses from the earlier story to the later one is that ruling for each measured clause it covers, so where a move fits that clause (below), apply the move without escalating and cite that note. A note that does not name both stories is not that ruling, and neither is a general or standing delegation (to rule on AC wording, say), wherever it is written. Otherwise escalate for the earlier story as the sub-skill halt catch-all below does, with `kind` `coupled-stories`, `source` the measurement file, and `decision_needed` naming both story keys, each clause, its measurement and the wording you propose for both story files (for two decomposed children, the changed claim map); when the later story is outside this run's scope, propose only a re-plan. Once `/ucg-resolve` has closed it, take the ruling from the entry it logs in `.decision-log.md`, which holds your proposal beside the operator's answer; a re-plan leaves you nothing to apply. What the move writes depends on the pair, and all of it lands before the earlier story's next commit. When both stories have a story file, write the ruling into both story files, each citing it: the earlier story's AC states what its own build measures and names the later story's AC that now owns each moved clause, and the later story gains each clause as an AC of its own, with its verification and anti-vacuous twin. Between two decomposed children of one parent, which have no story file, only a whole claimed AC moves, and only when each of its clauses is so measured, while the parent's story file stays unedited: a new reconciling run records the split with the changed claim map ("The reconciling run records the split", above), and the same pass rewrites the AC citation in both child rows' comments in `sprint-status.yaml`, which step 1 takes `claimed_acs` from and the trace is written from, and the AC numbers in both children's `atdd-checklist-<child key>.md` frontmatter (`references/define-done.md`), so no record of the split still gives the earlier child the AC it handed on. An AC the earlier child claims that also holds a clause no run so measured has no move to apply: that clause may not move, and the AC cannot move without it. Any other pair (a decomposed child beside a story that has a file, or children of two parents) has no move to apply either: a child owns only whole ACs of its own parent's story file, and nothing on the other side can claim one. No note can authorize a move where none fits. Escalate for the earlier story as above, proposing only a re-plan, as for a later story outside this run's scope. Move each clause's scaffolded cases with it, out of every file the earlier story's checklist lists in `generatedTestFiles` and into one the later story's checklist lists, since the commit guard reads a skipped case in a listed file as unfinished work. A later child split off after Stage 3 has no checklist yet, since its own ATDD run comes after its step 0 ("A decomposed child's ATDD run", above), so there is no frontmatter of its own to rewrite and no file it lists to take the cases. For such a child the move writes no checklist: it rewrites the AC numbers in the earlier child's checklist alone, and it removes each moved clause's cases from every file the earlier child's checklist lists, instead of moving them, parking no copy for the later child to take up. A listed file the removal leaves with no case comes off `generatedTestFiles` first and is then deleted, in the same pass: a test file with no case fails Jest and Vitest, and a listed path that does not exist reads to a resume as an interrupted ATDD run (above) and to the commit guard as a listed file it cannot read from the index. When that leaves `generatedTestFiles` naming no test file, the guard reads every test path the checklist's text names in its place, so each deleted file's path is also taken out of the checklist's text. The later child's ATDD run after its step 0 then scaffolds the moved AC from its rewritten row, as it does every AC the row cites; on a stack ATDD cannot run on, the later child's step 1 establishes the moved AC's red phase from its rewritten row instead, as for every AC the row cites. The earlier child's evidence folder keeps what it captured (the measurement, any red-phase capture), never edited or made again, and the move's log entry names each case it took out. Log the move under both stories in `.decision-log.md`, with the changed claim map for two children. Each gate then reads its own story's ACs as written: the earlier story's gate counts no moved clause as a gap, and the later story's gate measures each one, its automate pass included.
|
|
74
77
|
|
|
75
78
|
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.
|
|
76
79
|
|
|
@@ -85,20 +88,20 @@ For each in-scope story, in sprint order, run this loop (leave out a decomposed
|
|
|
85
88
|
|
|
86
89
|
**A wide sweep is also a loaded machine.** Running every language's suite plus the declared gate set, cache-defeating, means suites share a host with concurrent native builds — and a case bounded by a wall-clock timeout can fail from contention alone (measured: a 180-second-bounded case took 197s beside a concurrent `cargo test` + clippy + type-check, and 93s alone). A timeout in a wide sweep is therefore not yet a red: re-run that package in isolation before treating it as one, and where the two can be sequenced, do not schedule a long native build beside a wall-clock-bounded suite.
|
|
87
90
|
|
|
88
|
-
**Capture, then slice
|
|
91
|
+
**Capture, then slice: never pipe a long command through a filter.** `cmd 2>&1 | tail -50` buffers everything until the pipeline ends, so a cold build that is working and a genuine hang emit the same thing: nothing. Redirect to a file (`cmd > <log> 2>&1`) and read the summary out of it as a second call. A log the record or the gate will cite goes in `evidence-<story_id>/` ("Evidence never goes in scratch", above). The file also survives compaction, so the evidence outlives the turn, and the pipeline's exit status is the *filter's* rather than the command's. A 45-minute build has been killed on the suspicion it had hung; it had not.
|
|
89
92
|
|
|
90
93
|
**A repo with commit hooks carries gates this sweep structurally cannot see.** `lefthook` / `husky` / `.git/hooks/pre-commit` jobs — typos, formatters, staged-file linters, clippy — run against the staged index and are reachable from no script you can invoke here. So the step-4 commit attempt is itself part of verification rather than the end of it: a rejection there is expected traffic, not a failure of this sweep. What that rejection does to the tests-ran marker is step 4's problem, and it is not the obvious answer.
|
|
91
94
|
|
|
92
95
|
3. **Production profile only:** `bmad-testarch-test-review`, then `bmad-code-review`. A `CONCERNS`-grade or non-critical finding appends to `{workflow.deferred_work_path}` and the story proceeds. A **P0 / critical FAIL never defers** — re-loop within the turn budget or escalate.
|
|
93
|
-
4. **Commit at green** (one implementation commit per green story; the gate's evidence commit follows inside the same story boundary, per `references/gate.md`'s advance route, and when the gate's `bmad-testarch-automate` backfills a test, a commit of that backfill comes before it, per gate.md's "When automate backfills"). The PreToolUse hook blocks a commit on a protected branch, blocks a commit when no "tests-ran" marker exists for the current story, and (its marker-freshness clause) blocks a commit when that marker's `baseline=` line does not match the story's recorded baseline, so step 0 must have set the current story and step 2 must have actually run and written `{workflow.implementation_artifacts}/.tests-ran-<story_id>`, in the format step 2 pins, **in a prior, SEPARATE command**. The guard pre-evaluates the command *string* before it runs, so a marker written by a `printf`/`echo` in the SAME compound command as the commit (e.g. `printf … > .tests-ran-<id> && git commit …`) does not yet exist at hook-eval time and the commit is denied. Write the marker, then commit: two distinct tool calls. **A commit can also be rejected by something that is NOT the guard, and the marker rule inverts there.** A repo-side `pre-commit` hook (lefthook, husky, a plain `.git/hooks/pre-commit`) running clippy, rustfmt, typos or a staged-file linter rejects the commit without moving anything: HEAD is where it was, so the tests-ran marker's `baseline=` line still matches character for character and the guard will wave the retry straight through, carrying evidence collected *before* the fix. The freshness clause keys on the BASELINE, not on the code state, so it cannot see this case by construction. Treat a hook rejection exactly as step 5 treats a post-commit red: remediate, re-run the story's tests/lint/build to green, write a **fresh** `.tests-ran-<story_id>` (same `baseline=` line, still copied and never re-derived; `scope=`/`packages=` re-stated for what the re-run actually was), and only then retry the commit. This rule binds the story's own commits: this step's, and any re-commit or amend step 5 makes. The gate's two commits keep their own rules in `references/gate.md`: "When automate backfills" reads a hook rejection of its commit of a test `bmad-testarch-automate` backfilled as its backfill sweep's red, which it fixes only in the backfilled test files and otherwise ends the cycle at a re-loop, and the advance route says how to answer a hook rejection of its evidence commit. **Append `.decision-log.md` with Write/Edit, never a Bash heredoc.** Stages 4 and 6 require a log of what happened during the run, and what happened *is* commit behaviour, so the log quotes the verbs. The guard evaluates Bash command strings, and a heredoc carrying that prose is a Bash command string: a line leading with the verb is a verb-leading segment, and backticked identifiers or an apostrophe send the whole segment down the fail-closed matches-anywhere path. Its git gates read **Bash command strings alone**, so writing the log with the file tools removes the collision instead of phrasing around it, and keeps Bash for commands you actually mean to run. Said that way rather than "the guard never sees Write/Edit", because preflight arms the hook for EVERY tool: the hook IS invoked for a `Write`, and it does decide on file tools, but only through its Cross-Session Recall rules, which deny a file-tool call that names the recall store or would change the run latch (`references/preflight.md`). A decision-log append is neither, so the conclusion is unchanged, but a reader who believes the guard cannot see a `Write` and then meets the all-tools matcher will try to resolve the contradiction by narrowing the matcher back, and that leaves the recall rules enforcing nothing. **Once the log is too large to Read affordably, do not Read it.** It grows monotonically, one session's prose per invocation, and both file tools refuse a file that has not been Read in this session, so on a long-running Epic (288 KB by its eleventh invocation) the two sanctioned paths are both closed at once. Compose this session's entry with Write into a NEW sibling file in the run folder, `{workflow.implementation_artifacts}/dlog-slice-<story_id>-<n>.md`, where `<n>` increments per append: the name has to be unique per append, not per story, or a story's SECOND entry finds the slice already on disk and walks straight back into the Read it was escaping; then append it in one Bash call, `cat <slice> >> .decision-log.md`. That command's leading token is `cat`, it carries no backtick, no `$(`, and no verb-leading segment, so the guard makes no decision on it and the prose never enters a Bash command string at all. Keep the slice beside the log rather than deleting it: it is the only per-session copy if the append is ever interrupted. **Stage only the current story's paths.** In production, Stage 3 generated *every* in-scope story's red-phase tests up front, so a sibling story's still-skipped tests can co-reside in the same shared dirs as this story's (one `test/` package may hold two stories' acceptance specs before either commits). A blanket `git add -A` here sweeps those uncommitted sibling tests into this story's commit and pollutes the per-story boundary: stage this story's source + test paths explicitly (`git add <this story's paths>`) instead. The allowlist ships plain `git add` (a prefix covering both `-A` and a scoped `git add <paths>`) so the targeted add needs no extra approval. **Staging is itself a prior, SEPARATE tool call**: `git add <this story's paths>` as one call, then `git commit` as a second: the same two-distinct-tool-calls rule the marker follows, and for the same reason. The guard also denies a commit whose staged index is empty, and a chained `git add … && git commit` has staged nothing at the moment it pre-evaluates that command string, so the chained form is denied even though the add would have worked. `git commit -a` and commit-time pathspecs (`git commit <paths>`) are unsupported inside the story loop for exactly that reason. (Under `--light` no ATDD tests are generated, so the collision cannot arise.) **Once the commit lands, record the story's END sha.** Write `{workflow.implementation_artifacts}/.commit-<story_id>` with the output of `git rev-parse HEAD`, in exactly the format step 0 pins for the baseline: one newline-terminated line carrying the full 40-hex SHA. Unlike the baseline, **this marker is refreshed, not preserved**: step 5 rewrites it after any remediation re-commit or amend, the gate rewrites it after the commit of a test `bmad-testarch-automate` backfilled (gate.md's "When automate backfills"), and the gate's advance route rewrites it after its evidence commit, so it always names the story's last commit rather than its first. It exists to close the story's commit range explicitly: without it the evidence trail has to *infer* a range end from the NEXT story's baseline marker, and a later story anchored at this story's own SHA collapses that range to `X..X`, so a story that did commit renders as having committed nothing.
|
|
96
|
+
4. **Commit at green** (one implementation commit per green story; the gate's evidence commit follows inside the same story boundary, per `references/gate.md`'s advance route, and when the gate's `bmad-testarch-automate` backfills a test, a commit of that backfill comes before it, per gate.md's "When automate backfills"). The PreToolUse hook blocks a commit on a protected branch, blocks a commit when no "tests-ran" marker exists for the current story, and (its marker-freshness clause) blocks a commit when that marker's `baseline=` line does not match the story's recorded baseline, so step 0 must have set the current story and step 2 must have actually run and written `{workflow.implementation_artifacts}/.tests-ran-<story_id>`, in the format step 2 pins, **in a prior, SEPARATE command**. The guard pre-evaluates the command *string* before it runs, so a marker written by a `printf`/`echo` in the SAME compound command as the commit (e.g. `printf … > .tests-ran-<id> && git commit …`) does not yet exist at hook-eval time and the commit is denied. Write the marker, then commit: two distinct tool calls. **A commit can also be rejected by something that is NOT the guard, and the marker rule inverts there.** A repo-side `pre-commit` hook (lefthook, husky, a plain `.git/hooks/pre-commit`) running clippy, rustfmt, typos or a staged-file linter rejects the commit without moving anything: HEAD is where it was, so the tests-ran marker's `baseline=` line still matches character for character and the guard will wave the retry straight through, carrying evidence collected *before* the fix. The freshness clause keys on the BASELINE, not on the code state, so it cannot see this case by construction. Treat a hook rejection exactly as step 5 treats a post-commit red: remediate, re-run the story's tests/lint/build to green, write a **fresh** `.tests-ran-<story_id>` (same `baseline=` line, still copied and never re-derived; `scope=`/`packages=` re-stated for what the re-run actually was), and only then retry the commit. This rule binds the story's own commits: this step's, and any re-commit or amend step 5 makes. The gate's two commits keep their own rules in `references/gate.md`: "When automate backfills" reads a hook rejection of its commit of a test `bmad-testarch-automate` backfilled as its backfill sweep's red, which it fixes only in the backfilled test files and otherwise ends the cycle at a re-loop, and the advance route says how to answer a hook rejection of its evidence commit. **A `commit-msg` hook that rejects the message alone takes a shorter route, on the story's own commits.** Git runs that hook only once every `pre-commit` job has passed, so such a rejection asks for no file change: reword `message.txt` ("Check the record's claims before the commit", below), run the claim check again, and retry the commit from the message file (`-F`) with the marker as it stands, re-running no sweep and writing no fresh marker. A change a `pre-commit` job staged on its way there (a formatter that rewrote and re-staged a file) rides the retry as it would ride an accepted commit, and step 5's re-verify measures it. A path the re-run claim check has you stage or edit is a file change, which takes the rule above. Reword at most twice for one commit: when the hook rejects the second rewording too, the message it wants may hold what the run does not have (a ticket id, say), so commit nothing and escalate for the story as the sub-skill halt catch-all below does, with a `decision_needed` that names the hook and the rule it applies. A rejection whose fix needs a file changed, or whose output does not show that a `commit-msg` hook made it, keeps the rule above. **Append `.decision-log.md` with Write/Edit, never a Bash heredoc.** Stages 4 and 6 require a log of what happened during the run, and what happened *is* commit behaviour, so the log quotes the verbs. The guard evaluates Bash command strings, and a heredoc carrying that prose is a Bash command string: a line leading with the verb is a verb-leading segment, and backticked identifiers or an apostrophe send the whole segment down the fail-closed matches-anywhere path. Its git gates read **Bash command strings alone**, so writing the log with the file tools removes the collision instead of phrasing around it, and keeps Bash for commands you actually mean to run. Said that way rather than "the guard never sees Write/Edit", because preflight arms the hook for EVERY tool: the hook IS invoked for a `Write`, and it does decide on file tools, but only through its Cross-Session Recall rules, which deny a file-tool call that names the recall store or would change the run latch (`references/preflight.md`). A decision-log append is neither, so the conclusion is unchanged, but a reader who believes the guard cannot see a `Write` and then meets the all-tools matcher will try to resolve the contradiction by narrowing the matcher back, and that leaves the recall rules enforcing nothing. **Once the log is too large to Read affordably, do not Read it.** It grows monotonically, one session's prose per invocation, and both file tools refuse a file that has not been Read in this session, so on a long-running Epic (288 KB by its eleventh invocation) the two sanctioned paths are both closed at once. Compose this session's entry with Write into a NEW sibling file in the run folder, `{workflow.implementation_artifacts}/dlog-slice-<story_id>-<n>.md`, where `<n>` increments per append: the name has to be unique per append, not per story, or a story's SECOND entry finds the slice already on disk and walks straight back into the Read it was escaping; then append it in one Bash call, `cat <slice> >> .decision-log.md`. That command's leading token is `cat`, it carries no backtick, no `$(`, and no verb-leading segment, so the guard makes no decision on it and the prose never enters a Bash command string at all. Keep the slice beside the log rather than deleting it: it is the only per-session copy if the append is ever interrupted. **Stage only the current story's paths.** In production, Stage 3 generated *every* in-scope story's red-phase tests up front, so a sibling story's still-skipped tests can co-reside in the same shared dirs as this story's (one `test/` package may hold two stories' acceptance specs before either commits). A blanket `git add -A` here sweeps those uncommitted sibling tests into this story's commit and pollutes the per-story boundary: stage this story's source + test paths explicitly (`git add <this story's paths>`) instead. The allowlist ships plain `git add` (a prefix covering both `-A` and a scoped `git add <paths>`) so the targeted add needs no extra approval. **Staging is itself a prior, SEPARATE tool call**: `git add <this story's paths>` as one call, then `git commit` as a second: the same two-distinct-tool-calls rule the marker follows, and for the same reason. The guard also denies a commit whose staged index is empty, and a chained `git add … && git commit` has staged nothing at the moment it pre-evaluates that command string, so the chained form is denied even though the add would have worked. `git commit -a` and commit-time pathspecs (`git commit <paths>`) are unsupported inside the story loop for exactly that reason. (Under `--light` no ATDD tests are generated, so the collision cannot arise.) **Once the commit lands, record the story's END sha.** Write `{workflow.implementation_artifacts}/.commit-<story_id>` with the output of `git rev-parse HEAD`, in exactly the format step 0 pins for the baseline: one newline-terminated line carrying the full 40-hex SHA. Unlike the baseline, **this marker is refreshed, not preserved**: step 5 rewrites it after any remediation re-commit or amend, the gate rewrites it after the commit of a test `bmad-testarch-automate` backfilled (gate.md's "When automate backfills"), and the gate's advance route rewrites it after its evidence commit, so it always names the story's last commit rather than its first. It exists to close the story's commit range explicitly: without it the evidence trail has to *infer* a range end from the NEXT story's baseline marker, and a later story anchored at this story's own SHA collapses that range to `X..X`, so a story that did commit renders as having committed nothing.
|
|
94
97
|
|
|
95
98
|
**Check the record's claims before the commit.** Gate reviews keep finding one shape of defect in the record: a commit message, a code comment or a story sentence that asserts a property the code does not hold, written by the author who just built it. A catch after the commit costs a re-loop, so check between the staging call and the commit call. Write the commit message with Write to `{workflow.implementation_artifacts}/.scratch-<story_id>/message.txt`, and the story-record notes this cycle added (completion notes, a re-loop's notes, File List entries; for a decomposed child, which has no record, the File List and completion notes from `ucg-dev-story`'s step 10 summary; an empty file when the cycle added none) to `record-notes.md` beside it, Reading either first if an earlier session left it, then run:
|
|
96
99
|
|
|
97
100
|
```
|
|
98
|
-
uv run {skill-root}/scripts/claim_check.py --message {workflow.implementation_artifacts}/.scratch-<story_id>/message.txt --message {workflow.implementation_artifacts}/.scratch-<story_id>/record-notes.md --project-root {project-root}
|
|
101
|
+
uv run {skill-root}/scripts/claim_check.py --message {workflow.implementation_artifacts}/.scratch-<story_id>/message.txt --message {workflow.implementation_artifacts}/.scratch-<story_id>/record-notes.md --project-root {project-root} --artifacts-root {workflow.implementation_artifacts} --artifacts-root {workflow.implementation_artifacts}/.scratch-<story_id> --artifacts-root {workflow.implementation_artifacts}/evidence-<story_id> --tea-config {workflow.tea_config_path}
|
|
99
102
|
```
|
|
100
103
|
|
|
101
|
-
The second `--message` is there because the record names files the message may only describe. Its `not_in_diff` lists the paths it reads as named in either text that the staged diff does not touch, each a claim about the tree that needs no judgment to refute; paths git ignores (the mutation ledger the record cites, a story file under an ignored artifact tree) are listed apart, in `ignored`, since no commit can carry them. For each path in `not_in_diff`: stage it if this commit changed it; if the work tree shows no change there, the edit did not happen, so make it or remove the claim; and reword the message or correct the story record itself (not only its scratch copy) when the text says this commit changed a file it did not. A text may name an unchanged file on purpose, if it says so. Run the check again until every path left in `not_in_diff` is one a text names on purpose and says so. Then make one pass over the claims the diff itself adds (its new comment and header lines, the story's new completion notes) and each line of the message, for a superlative or a property: "exactly", "every", "always", "cannot", "not X but Y", "composed", or a claim that something exists or does not exist yet. Each one either cites evidence this cycle already produced (a test, a mutation row, a printed measurement) or is softened to what that evidence shows; start no new run to back a sentence, since the usual fix is to weaken the sentence, not to strengthen the code. In the same pass, read `git diff --cached` once and find the hunk for each edit the message or the notes say this commit makes ("now says", "narrowed", "landed", "fixed"), path or no path: an edit described by its content has a path too, and an edit whose script failed leaves no hunk. And look for a claim this commit makes false without touching it: a forward reference to what it lands in a comment or doc elsewhere in the tree. Search the project's own files with the Grep tool, case-insensitive, for this story's id, "does not exist yet" and "owed by", and for the name of each file the commit adds, leaving out the installed skill, the run folder and this story's own record and tests; correct a hit only when it refers to what this commit lands, in this commit, staged with this story's paths, unless a sibling story's uncommitted edits share its file, in which case log it to `.decision-log.md` for that story instead. Re-stage every file this pass edited, in its own `git add` call, then commit from the message file (`-F`). Run the same check before any re-commit or amend step 5 makes.
|
|
104
|
+
The second `--message` is there because the record names files the message may only describe. Its `not_in_diff` lists the paths it reads as named in either text that the staged diff does not touch, each a claim about the tree that needs no judgment to refute; paths git ignores (the mutation ledger the record cites, a story file under an ignored artifact tree) are listed apart, in `ignored`, since no commit can carry them. A record names its own artifacts from the folder that holds them (`sweep.sh`, `red-phase/INDEX.md`), so the command names three folders with `--artifacts-root` (the run folder, this story's scratch folder and its evidence folder) and a fourth with `--tea-config`, the TEA test-artifacts root that holds `atdd-checklist-<story_id>.md`, resolved from the TEA config as preflight resolves it (`scripts/preflight_check.py`, `_tea_artifacts_root`), and such a name is read there: one that does not exist from `{project-root}` but exists in one of them lands in `ignored` when each copy that holds it is either ignored by git or outside the work tree, and in `not_in_diff` otherwise; one that exists from `{project-root}`, that a file the tree holds could be, or that is in none of them, is read from `{project-root}` as before. A file this commit claims and never wrote, named bare, under a folder the tree does not hold, or under an empty or ignored-only folder inside an untracked one (git lists only the topmost untracked folder), cannot be told from an artifact of that name, so a copy in one of the folders reads it as the copy: the hunk pass below, which finds the hunk for each edit the message or the notes say this commit makes, is what catches it. For each path in `not_in_diff`: stage it if this commit changed it; if the work tree shows no change there, the edit did not happen, so make it or remove the claim; and reword the message or correct the story record itself (not only its scratch copy) when the text says this commit changed a file it did not. A path under this story's `.scratch-<story_id>/` or `evidence-<story_id>/` is never staged, since both folders stay untracked: the record names it on purpose, as its own evidence, and it may stay listed. A text may name an unchanged file on purpose, if it says so. Run the check again until every path left in `not_in_diff` is one a text names on purpose and says so. Then make one pass over the claims the diff itself adds (its new comment and header lines, the story's new completion notes) and each line of the message, for a superlative or a property: "exactly", "every", "always", "cannot", "not X but Y", "composed", or a claim that something exists or does not exist yet. Each one either cites evidence this cycle already produced (a test, a mutation row, a printed measurement) or is softened to what that evidence shows; start no new run to back a sentence, since the usual fix is to weaken the sentence, not to strengthen the code. In the same pass, read `git diff --cached` once and find the hunk for each edit the message or the notes say this commit makes ("now says", "narrowed", "landed", "fixed"), path or no path: an edit described by its content has a path too, and an edit whose script failed leaves no hunk. And look for a claim this commit makes false without touching it: a forward reference to what it lands in a comment or doc elsewhere in the tree. Search the project's own files with the Grep tool, case-insensitive, for this story's id, "does not exist yet" and "owed by", and for the name of each file the commit adds, leaving out the installed skill, the run folder and this story's own record and tests; correct a hit only when it refers to what this commit lands, in this commit, staged with this story's paths, unless a sibling story's uncommitted edits share its file, in which case log it to `.decision-log.md` for that story instead. Re-stage every file this pass edited, in its own `git add` call, then commit from the message file (`-F`). Run the same check before any re-commit or amend step 5 makes.
|
|
102
105
|
|
|
103
106
|
5. **Re-verify on the committed HEAD.** Re-run the authoritative suite (tests + lint + build, the same scope step 2 ran this cycle — all three axes including the declared gate set when full; the same resolved package set when this re-loop cycle legitimately ran scoped, per step 2's re-loop rule) on the just-committed, clean tree and **PRINT** the result before advancing. **Run it cache-defeating.** Committing changes a file's git *tracking state* and not one of its bytes, so a content-addressed cache key is unchanged and this re-run replays the pre-commit answer verbatim, observing nothing: eight of eight tasks reported cached, returning in 719ms immediately after a commit, is the whole failure. Pass `--force` (or invoke the package's runner directly), because the one thing this step must actually execute is the tracked-file gates against the newly tracked fileset. Step 2's pre-commit run cannot see a **conformance gate scoped to *tracked* files** — a `git ls-files`-based ref/ownership/architecture-boundary check: a story's **new** files are still untracked at step 2, so the gate skips them and reports green, then reds the instant the commit tracks them (generated or `.gitignore`d files hide the same way). This committed tree is the exact fileset CI and the Stage-5 gate will see, so a story that is green pre-commit but red here is a **false green** the pre-commit run and any transcript-only evaluator (a `/goal` an operator started, say) both miss. A red means the story is **not** done: remediate, write a fresh `.tests-ran-<story_id>` marker, and re-commit (amend or a follow-up within the story boundary) until the committed HEAD is green — only then advance. **That fresh marker carries the same `baseline=<sha>` line as step 2's**: the verbatim, whitespace-stripped content of `{workflow.implementation_artifacts}/.baseline-<story_id>` — **copied, never re-derived from `git rev-parse HEAD`**. The story's baseline has not moved; HEAD has, because step 4 just committed. Re-deriving it here would re-anchor the story to that commit and quietly retire the freshness net for the rest of it, which is the very replayed-marker hole the line exists to close — and without the line the guard denies the re-commit outright, so a story that legitimately needs remediation could never close. The fresh marker also re-states `scope=` (and `packages=` when scoped) to match what THIS re-verify actually ran, because the `scope=` line the gate will read through `--tests-ran` is the one written here, not step 2's. **Rewrite `{workflow.implementation_artifacts}/.commit-<story_id>` from `git rev-parse HEAD` once this step's HEAD is green**, in step 4's format — every time, including when nothing was remediated, because an amend replaces the SHA step 4 recorded and a follow-up commit moves it. This marker is the one step-0 artifact whose rule is *refresh*, not *keep*: the baseline names where the story started and must never move, this one names where it ended and must never be stale. That re-commit carries the SAME staging rule as step 4: stage in a prior, SEPARATE tool call (`git add <this story's paths>`), then run the commit (or `git commit --amend`) as a second, distinct call. `git commit -a` and a chained `git add … && git commit` are unsupported here too — the staged index is still empty when the guard pre-evaluates the command string, so the re-commit is denied.
|
|
104
107
|
|
|
@@ -109,7 +112,7 @@ The second `--message` is there because the record names files the message may o
|
|
|
109
112
|
- **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.
|
|
110
113
|
- **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.
|
|
111
114
|
- **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).
|
|
112
|
-
- **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.
|
|
115
|
+
- **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. A decomposed child's ATDD run is such work: it runs after the child's own step 0, never while the story before it is current ("A decomposed child's ATDD run", above).
|
|
113
116
|
|
|
114
117
|
### The per-invocation work bound (`--max-stories N`)
|
|
115
118
|
|
|
@@ -19,8 +19,8 @@ The gate reads artifacts TEA produces. In **production**, before running the gat
|
|
|
19
19
|
1. Stage the test files this pass's summary (`automation-summary-<story_id>-<sha>.md`, with `<sha>` the `gate-backfill-base:` commit; "Automate's summary records its rows" below) names as written or changed, by explicit path, in one call. `git status --porcelain --untracked-files=all` lists them: the plain `git status --porcelain` lists a new directory instead of the files in it, so a test in a new folder would look absent. A path it lists that the summary does not name is not part of the backfill and stays unstaged. A path the summary names that it lists is staged from the main tree, and the worktree's copy of that file, which automate ran the test's confirming rows against ("A backfill is confirmed in the pass that writes it" below), is not a test written into the worktree: the rebuild discards it. A path the summary names that it does not list has no change in the main tree, so look for the file in the worktree: at that path when the summary gives it under `<tmp-path>`, and otherwise at the same repo-relative path under `<tmp-path>`. When the file is there, automate wrote it into the worktree: copy it to its repo-relative path in the main tree before the rebuild destroys it, and list again. When git still lists no change at that path, or neither tree holds the file, the test the summary names was never written: leave the path out, and log a `gate-gap:` line for the gap that test was written for, as "A reported gap stays open until a later pass measures it closed" below describes, in place of any `unkilled` line logged for that gap. When this step stages nothing, there is no backfill: skip steps 2 through 5, and the commit under assessment stays the `gate-backfill-base:` commit.
|
|
20
20
|
2. With them staged, so that a gate reading git's file list sees a new test file, run the full three-axis sweep over the main tree, cache-defeated and printed, as `references/execute.md` step 5 runs it. A red that a change to the backfilled test files alone fixes (a lint or format error in one, a tracked-files gate that names one) is fixed there, staged, and re-run, at most twice in this backfill, a fix step 4 makes for a commit hook included. A red that needs a change to any other path, or that is still red after the second fix, is not the gate's to fix: commit nothing, and take "A red backfill sweep ends the cycle at a re-loop" below. A green sweep goes on to step 3, whatever `gate-gap:` lines this cycle has logged.
|
|
21
21
|
3. Once the sweep is green, write a fresh `.tests-ran-<story_id>` marker as step 5 writes one: its `baseline=` line copied from `.baseline-<story_id>`, never re-derived, and `scope=full`.
|
|
22
|
-
4. Run `references/execute.md` step 4's claim check on the commit message, then commit from the message file, in a call separate from the staging call, as step 4 requires. The guard allows this commit as it allows the evidence commit in "Route on the verdict": the story is still current, its marker was written in a prior call, and the index is not empty. A repo commit hook that rejects this commit is read as step 2's red, and `references/execute.md` step 4's own rule for a hook rejection does not apply to it: when a change to the backfilled test files alone answers the hook, make it there, stage it, and go back to step 2, whose sweep runs again before step 3 writes a fresh marker and this step retries the commit, all within step 2's budget of two fixes; when the hook needs a change to any other path, or rejects the commit again after the second fix, commit nothing, and take "A red backfill sweep ends the cycle at a re-loop" below.
|
|
23
|
-
5. Refresh `.commit-<story_id>` from `HEAD`, log `gate-backfill: <sha>`, naming the new commit, in `.decision-log.md`, and remove `.scratch-<story_id>/` again: the claim check's message files recreated it, and `references/execute.md` step 0 has it removed before the story advances.
|
|
22
|
+
4. Run `references/execute.md` step 4's claim check on the commit message, then commit from the message file, in a call separate from the staging call, as step 4 requires. The guard allows this commit as it allows the evidence commit in "Route on the verdict": the story is still current, its marker was written in a prior call, and the index is not empty. A repo commit hook that rejects this commit is read as step 2's red, and `references/execute.md` step 4's own rule for a hook rejection does not apply to it: when a change to the backfilled test files alone answers the hook, make it there, stage it, and go back to step 2, whose sweep runs again before step 3 writes a fresh marker and this step retries the commit, all within step 2's budget of two fixes; when the hook needs a change to any other path, or rejects the commit again after the second fix, commit nothing, and take "A red backfill sweep ends the cycle at a re-loop" below. A `commit-msg` hook that rejects the message alone asks for no file change: Git runs it only once every `pre-commit` job has passed, so reword the message file, run the claim check again and retry the commit with the marker as it stands, re-running no sweep. That retry counts as one of step 2's two fixes, and a rejection after the second still takes "A red backfill sweep ends the cycle at a re-loop" below. A change a `pre-commit` job staged on its way there rides the retry as it would ride an accepted commit. A path the re-run claim check has you stage or edit is a file change, which takes the rule above. A rejection whose output does not show that a `commit-msg` hook made it is read as step 2's red, as above.
|
|
23
|
+
5. Refresh `.commit-<story_id>` from `HEAD`, log `gate-backfill: <sha>`, naming the new commit, in `.decision-log.md`, and remove `.scratch-<story_id>/` again: the claim check's message files recreated it, and `references/execute.md` step 0 has it removed before the story advances. The story's `evidence-<story_id>/` folder stays: no step removes it (`references/execute.md`, "Evidence never goes in scratch").
|
|
24
24
|
|
|
25
25
|
The new commit is now the commit under assessment: the worktree is rebuilt at it, trace, NFR and test review measure it, and the verdict's `assessed-commit` line names it. The backfill belongs to this gate cycle and is not a re-loop: it writes no `class:` line, spends no re-loop, and never meets the turn-ceiling check that runs before a re-loop, though its sweep spends turns like any wait (`references/execute.md`, "Waiting spends turns").
|
|
26
26
|
|
|
@@ -107,7 +107,7 @@ Write a PASS only when the story is demonstrably done to its profile's Definitio
|
|
|
107
107
|
|
|
108
108
|
1. **The trace decision** — TEA's own wherever trace runs, and the two hand-authored files above only where it cannot.
|
|
109
109
|
2. **The red phase is established BY HAND, and it must still be established.** Where ATDD cannot generate the `test.skip()` scaffold: author the acceptance cases with real assertions and RUN them before the first implementation edit — the window this rule governs closes in Stage 4, which is why `references/execute.md` step 1 states the same obligation where the first-edit decision is actually made. This section otherwise rules the artifacts thoroughly and the acceptance-test BAR ("un-skipped and passing") while saying nothing about how un-skipped is reached from a red start — so a run that skipped the red phase entirely satisfies every other sentence here. **A case nobody ever saw fail is not evidence**, and a hand-authored PASS resting on one is the same dishonesty the hand-authored-PASS rule above forbids.
|
|
110
|
-
3. **Capture that run's raw output to a file**
|
|
110
|
+
3. **Capture that run's raw output to a file** in `{workflow.implementation_artifacts}/evidence-<story_id>/`, which no step removes (`references/execute.md`, "Evidence never goes in scratch"). An independent deliverable, not a detail of item 2: the capture is what makes the red phase auditable after the fact, and it cannot be honestly re-made once the implementation lands. A run that ran the red phase and read the result but captured nothing holds strictly weaker evidence than this item asks for, and a labelled transcription is the most it can honestly write.
|
|
111
111
|
4. **The red count recorded in the trace report, with a one-line justification for every case that was already green.** Where TEA authored the trace report, record them beside the captured output of item 3 and in `.decision-log.md` instead, never in TEA's file: an edit there would make its provenance false. Where a shared acceptance file accumulates already-shipped siblings' cases, those green-by-design cases may be justified as one line naming that class rather than case-by-case — the per-case justification owed is for THIS story's cases that never went red.
|
|
112
112
|
5. **`gate-provenance:`, logged per story** exactly as "Run the gate" below requires: `gate-provenance: hand-authored` where item 1 applied, and `tea` where trace ran. A run that takes the hand-authored branch on every row produces an Epic whose every verdict rests on a file the run wrote for itself, and nothing else in the artifacts would say so.
|
|
113
113
|
|
|
@@ -179,7 +179,7 @@ Do not recompute TEA thresholds or re-judge `gate_status` — read it as given.
|
|
|
179
179
|
|
|
180
180
|
- **`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.
|
|
181
181
|
|
|
182
|
-
**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. A repo commit hook that rejects this commit is not `references/execute.md` step 4's case, whose rule for a hook rejection binds the story's own commits. Make a change the hook asks for only in a file the gate itself writes for this commit, `sprint-status.yaml` (its `done` sync) or `.decision-log.md`, then stage it and retry, with the marker as it stands, at most twice for this commit. When the hook asks for a change to any other path, such as a file TEA wrote (an edit there would make its provenance false) or a ledger row (the ledger schema below never rewrites one), or rejects the commit again after the second fix, commit nothing: log the rejection in `.decision-log.md`, write the typed escalation sidecar `escalation-<story_id>.json` (shape in `references/execute.md`, under "Escalation sidecar") with `kind` `evidence-commit-rejected` and a `decision_needed` that names the hook, its message, the paths left uncommitted and this run's id (so a rejection on a later run is a new decision, never one `/ucg-resolve` has closed already), write `.evidence-owed-<story_id>` beside it, listing those paths one per line, and stop before the next story's step 0, as the `escalate` route below stops. The story keeps the verdict it advanced on (`advance`, or `defer`, whose route advances anyway), and its evidence stays staged for the commit a resume makes. Automate's backfill is not among its paths, because it was committed before trace ran ("When automate backfills", under "Backfill the gate evidence"). If it must carry an executable path all the same (a source or test file left uncommitted when trace ran, which this gate therefore never measured: log why), 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>`. While that story's `evidence-commit-rejected` escalation is still open, the resume commits nothing and stops on it instead (`references/execute.md`'s resume rule says how it reads one); once `/ucg-resolve` has closed it, the resume makes the commit, under the hook rule above. Once the commit is made, remove `.evidence-owed-<story_id>`: `/ucg-resolve` deletes the sidecar when it closes the escalation, so the marker is what tells a resume, and Stage 1's already-done short-circuit, that the commit is still owed. A resume that finds the marker with the sidecar gone and none of the paths it lists staged or different from `HEAD` (`git diff --quiet HEAD -- <paths>` exits 0 for them) finds the evidence committed already, by the operator or by a run that stopped between its commit and this removal: log the commit that holds it and remove the marker, making no commit. On the story whose advance makes every story `done`, this commit follows the Epic-level gate, so the `epic-<id>` row that gate's `advance` wrote stays staged with the rest, and the run ends `blocked` on that escalation all the same, because its evidence is not committed (`references/finalize.md`). While `.evidence-owed-<story_id>` is on disk, Stage 1's already-done short-circuit does not end that Epic's resume (`references/ingest-and-scope.md`, rule 4), nor does `scripts/drive_epic.py` report the Epic `all-done`: the resume waits on the escalation while it is open, makes the commit once it is closed, and then goes to Finalize with the Epic-level verdict the log holds, without running that gate again. Then move to the next story.
|
|
182
|
+
**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. Before the commit call, write its message with Write to `{workflow.implementation_artifacts}/.scratch-<story_id>/message.txt`, recreating the folder Execute removed before the story advanced, or Reading the file first if an earlier session left it there, and commit from that file (`git commit -F`), as the story's own commits do. Never put the message in the Bash command. After a double-quoted `-m`, or in a heredoc whose delimiter is unquoted, bash runs a backticked name or a `$(...)` in it as a command while it builds the arguments, and the commit still exits 0 with the text that is left. A quoted heredoc keeps the text, but the guard reads its lines as commands (a line that opens with `Git runs` is read as a git command it does not know, which it counts as a commit and a push), and the `$(cat <<'EOF' ...)` form is a command substitution, which a harness that statically analyses Bash strings refuses (`references/execute.md` step 2). Once the commit is made, or the escalation below is written, remove `.scratch-<story_id>/` again, since the next story's step 0 must not find it (`references/execute.md` step 0). A resume that finds the folder left by a run that stopped after this commit removes it 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. A repo commit hook that rejects this commit is not `references/execute.md` step 4's case, whose rule for a hook rejection binds the story's own commits. Make a change the hook asks for only in a file the gate itself writes for this commit, `sprint-status.yaml` (its `done` sync) or `.decision-log.md`, then stage it and retry, with the marker as it stands, at most twice for this commit. When the hook asks for a change to any other path, such as a file TEA wrote (an edit there would make its provenance false) or a ledger row (the ledger schema below never rewrites one), or rejects the commit again after the second fix, commit nothing: log the rejection in `.decision-log.md`, write the typed escalation sidecar `escalation-<story_id>.json` (shape in `references/execute.md`, under "Escalation sidecar") with `kind` `evidence-commit-rejected` and a `decision_needed` that names the hook, its message, the paths left uncommitted and this run's id (so a rejection on a later run is a new decision, never one `/ucg-resolve` has closed already), write `.evidence-owed-<story_id>` beside it, listing those paths one per line, and stop before the next story's step 0, as the `escalate` route below stops. The story keeps the verdict it advanced on (`advance`, or `defer`, whose route advances anyway), and its evidence stays staged for the commit a resume makes. A `commit-msg` hook that rejects only this commit's message asks for no file change: the message is the gate's own, as the `done` sync and the decision log are, so reword `message.txt` and retry from it (`-F`), with the marker as it stands, and count that retry as one of this commit's two fixes, after which a rejection still takes the escalation above. Git runs that hook only once every `pre-commit` job has passed, so a change a `pre-commit` job staged on its way there rides the retry as it would ride an accepted commit. A rejection whose output does not show that a `commit-msg` hook made it keeps the rule above. Automate's backfill is not among its paths, because it was committed before trace ran ("When automate backfills", under "Backfill the gate evidence"). If it must carry an executable path all the same (a source or test file left uncommitted when trace ran, which this gate therefore never measured: log why), 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), write the message file and commit from it as above, and refresh its `.commit-<story_id>`. While that story's `evidence-commit-rejected` escalation is still open, the resume commits nothing and stops on it instead (`references/execute.md`'s resume rule says how it reads one); once `/ucg-resolve` has closed it, the resume makes the commit, under the hook rule above. Once the commit is made, remove `.evidence-owed-<story_id>`: `/ucg-resolve` deletes the sidecar when it closes the escalation, so the marker is what tells a resume, and Stage 1's already-done short-circuit, that the commit is still owed. A resume that finds the marker with the sidecar gone and none of the paths it lists staged or different from `HEAD` (`git diff --quiet HEAD -- <paths>` exits 0 for them) finds the evidence committed already, by the operator or by a run that stopped between its commit and this removal: log the commit that holds it and remove the marker, making no commit. On the story whose advance makes every story `done`, this commit follows the Epic-level gate, so the `epic-<id>` row that gate's `advance` wrote stays staged with the rest, and the run ends `blocked` on that escalation all the same, because its evidence is not committed (`references/finalize.md`). While `.evidence-owed-<story_id>` is on disk, Stage 1's already-done short-circuit does not end that Epic's resume (`references/ingest-and-scope.md`, rule 4), nor does `scripts/drive_epic.py` report the Epic `all-done`: the resume waits on the escalation while it is open, makes the commit once it is closed, and then goes to Finalize with the Epic-level verdict the log holds, without running that gate again. Then move to the next story.
|
|
183
183
|
|
|
184
184
|
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.
|
|
185
185
|
|
|
@@ -41,6 +41,8 @@ Qualify the path with `{skill-root}` for the same cwd-safety reason step 1 does
|
|
|
41
41
|
|
|
42
42
|
The verdict is computed from the **resolved artifact set on disk** — the real PRD / architecture / epic / story content the readiness resolver locates — regardless of whether any customization shaping applied; the gate reads the artifact on disk, not the shaping. The kernel is **fail-closed**: an unreadable or absent artifact is a *failing signal*, never neutral (mirroring `gate_eval.py`'s `nfr_status is None → failing`). The run is unconditional on that resolved corpus — it is the verify side that must hold even when shaping legitimately did not land.
|
|
43
43
|
|
|
44
|
+
Of TEA's output the kernel reads only this Epic's, where TEA writes it: under TEA's test-artifacts root, the root step 5 injects as `ULTRACODE_TEST_ARTIFACTS` (the TEA config's `test_artifacts`, else `{project-root}/_bmad-output/test-artifacts`), in that folder or any folder below it. There it reads every `test-design-epic-<id>.md` for the risk matrix and the NFR thresholds, and, beside one, an `nfr-assessment.md` only when its `**Story:**` or `story_id:` line names a story the kernel reads; one it cannot read is a failing gap, as an unreadable test-design is, since its story line cannot be checked. Another Epic's test-design, TEA's system-level `test-design-architecture.md` and `test-design-qa.md`, and TEA's progress, validation and handoff files are never read. A missing test-design or NFR assessment is no gap: Stage 3 writes the Epic's test-design after this stage, and TEA assesses NFRs from implementation evidence, which the Stage 5 production gate requires of each story. A TEA file under that root, or under a `trace_output` folder the TEA config sets, is not a leaked TEA artifact.
|
|
45
|
+
|
|
44
46
|
This step only *produces* the verdict; nothing is folded in here. Step 2 folds in its mechanical gaps and closes on a re-run of this command, which seeds step 3 with the judgment candidates, and step 4 reads the verdict of step 3's own re-run on the answered scan.
|
|
45
47
|
|
|
46
48
|
Per the measurement protocol, log the formalize duration provenance — `wall_clock_ms`, `mechanical_ms`, `artifact_count` — to `.decision-log.md` on every verdict, reusing the existing step-3 scan boundary for the end-to-end split; no number gates the run (the wall-clock budget is measured, never guessed).
|