armelhbobdad/bmad-module-ultracode-goal / skills/ultracode-goal
ultracode-goal
UnverifiedRuns a BMAD Epic autonomously to a machine-checked Definition-of-Done. Use when the user requests to 'run an epic autonomously', 'execute this epic', 'ultracode goal', or 'autonomously deliver the epic'.
references/gate.md
View on GitHub# Stage 5 — Gate
**Goal:** Decide whether a completed story (or, after the last story, the Epic) advances — by a deterministic artifact read, not by judgment. `scripts/gate_eval.py` reads TEA's `gate-decision.json` and returns a routing verdict. You execute the route. Converse in `{communication_language}`; the deferred-work ledger is written in `{document_output_language}`.
This is the completion authority. The `/goal` evaluator only sees the transcript; it cannot read the gate file. Never substitute your own read of "the tests look green" or the evaluator's transcript-only verdict for this script. The JSON is the truth.
## Backfill the gate evidence (production only)
The gate reads artifacts TEA produces. In **production**, before running the gate, make the evidence current, in this order:
1. `bmad-testarch-automate` backfills coverage for code that landed during Execute. **It runs first and alone.** The mutation runs it confirms a gap with (`scripts/mutate_check.py` writes a mutation into a source file, runs a command, then restores the file) edit source in the gate worktree ("Measure the commit, not the working tree" below), and trace reads the coverage it backfills, so no other assessor reads, runs or times anything in the worktree until automate has finished.
2. Once automate has finished, log its `gate-gap:` lines ("A reported gap stays open until a later pass measures it closed" below), commit its backfill if it made one ("When automate backfills" below), then rebuild the gate worktree at the commit under assessment ("Rebuild the worktree once automate has finished" below). A red backfill sweep ends the cycle here instead, before trace ("A red backfill sweep ends the cycle at a re-loop" below), and nothing else automate's pass or its backfill produces does: a `gate-gap:` line never ends a cycle. A sub-skill that blocks on input or is not installed still escalates the story, at this step or any other, as `references/execute.md`'s sub-skill halt catch-all says.
3. `bmad-testarch-trace` (re)builds the traceability matrix and writes the gate decision.
`bmad-testarch-nfr` (produces `nfr-assessment.md`) and `bmad-testarch-test-review` are independent of each other and of trace, so once step 2 is done, run them in any order, or concurrently with trace, except that no two of them run tests at once under a scratch runner config that gives the worktree's runs their own server ("A server the gate set reuses does not follow the commit" below): each such run starts that server on the one port the config names, so a second one would find the port taken and run no test. None of the three may edit a file in the worktree, so none of them runs a mutant: an assessor that would probe one names the mutant it would run as a finding in its own artifact instead, and when you delegate NFR or test review, tell it so. `gate_eval.py` consumes all three artifacts without caring how they were produced. (`bmad-testarch-test-review` normally runs in Execute per story: run it here only if you lack a current `test-review.md` for the story. One written before automate's backfill is not current, since no review has read the tests the backfill added.) In **`--light`**, skip all of the above and run only `bmad-testarch-trace`, then the gate with `--profile light` (trace gate only, with no NFR/review AND).
**When automate backfills, commit the backfill before trace runs.** A test automate writes or changes lands in the main tree, as every assessor's output does ("Their OUTPUTS go home" below), so neither the commit under assessment nor the worktree made from it holds that test, and trace would count a test the commit does not contain. So never run trace, NFR or test review on that commit. While `.current-story` still names this story, log `gate-backfill-base: <sha>` in `.decision-log.md`, naming `HEAD`, the commit automate measured, then commit the backfill the way `references/execute.md` commits a story's paths, in this order:
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. Neither is a test the summary names for a risk or a gap an owned `gate-gap:` line names ("An owned `gate-gap:` line is not this story's to close" below): move it aside, unstaged, into the story's scratch folder, `{workflow.implementation_artifacts}/.scratch-<story_id>/`, at its repo-relative path under that folder, creating the folder when it is gone, which keeps it out of every default source glob (`references/execute.md`, step 0), and log the move in `.decision-log.md`. The gap it was written for is none the cycle backfilled, so the next cycle re-runs no row for it as one ("At most one automate pass finishes per gate cycle" below). 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.
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. When `{workflow.backfill_sweep}` is `scoped` and every condition of "A backfill of test files alone may scope its sweep" below holds, this sweep, and each re-run after a fix, takes that paragraph's scoped form instead; any other value of the key, or a condition that does not hold, keeps it the full sweep. A red `references/execute.md` step 2 reads as not yet a red (a timeout on a loaded machine, or a red the story's changes do not explain) is read that way here first. That step's second sweep for a red the story's changes do not explain is no fix, so it counts toward neither of the two fixes below, and when it shows no red, this sweep is green. 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.
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`. After the scoped form, it also carries a `sweep=` line naming the green capture of the full sweep that form builds on and the green capture of this one, `sweep=<base capture>+<backfill capture>` ("A backfill of test files alone may scope its sweep" below), and still says `scope=full`.
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.
5. Refresh `.commit-<story_id>` from `HEAD`, log `gate-backfill: <sha>`, naming the new commit, in `.decision-log.md`, and leave `.scratch-<story_id>/` in place, the claim check's message files included: `references/execute.md` step 0 keeps it until the story advances, since a cap-only re-loop or a re-gate of this story may still run its sweep. The story's `evidence-<story_id>/` folder stays: no step removes it (`references/execute.md`, "Evidence never goes in scratch"). When the marker carries a `sweep=` line, this step opens, before its refresh, with the check "A backfill of test files alone may scope its sweep" below gives, on a resume that starts here too.
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").
**A backfill of test files alone may scope its sweep.** `{workflow.backfill_sweep}` ships as `full`, `scoped` opts in, and any other value reads as `full`. The scoped form builds on the full sweep `references/execute.md` step 5 ran green at the commit the backfill builds on, and re-runs only the checks the backfill's files can change. Use it only while all of these hold, checked before the sweep and again before each re-run after a fix:
- the story's `.tests-ran-<story_id>` marker reads `scope=full` and holds no `sweep=` line, so a scoped sweep never builds on another;
- `.commit-<story_id>`, `git rev-parse HEAD` and the `gate-backfill-base:` commit are one commit;
- `evidence-<story_id>/` holds the capture of a full sweep that went green at that commit (`sweep-step5-<short sha>.log`, or the numbered capture of its second sweep);
- every path `git diff --cached --name-only --no-renames` lists is a test file: it follows its toolchain's test-file naming (`*.test.*`, `*.spec.*`, `test_*.py`, `*_test.py`, `*_test.go`, or a file in a Rust crate's top-level `tests/` folder), and no file but itself and the run's own records (under `{workflow.implementation_artifacts}` and `{workflow.trace_output_dir}`) mentions its name, the file name without its last extension (`a.test` for `a.test.ts`), which you check with the Grep tool, searching for that name as a literal string, not a pattern, in hidden files too (`.storybook/main.ts`, say), and a mention it finds in a file git does not track counts as well;
- every fix step 2 makes stays inside those files.
When one does not hold, or you are in any doubt, run the full sweep: it is never wrong, only slower. The scoped form runs, cache-defeated and printed, every check of each package that holds a staged path, and every check that reads files across packages or git's file list (a format, lint or type check, a scanner, a tracked-files gate, a per-file line cap, a build-input manifest) unless its own declared inputs exclude every staged path. It leaves out only the checks of a package that holds no staged path, and a repo-wide check whose own declared inputs exclude every staged path, and it prints each check it leaves out and why; when it cannot tell whether a check reads a staged path, it runs that check. Capture it as `sweep-backfill-<short sha>.log`, as the full form is captured, with the staged paths it ran for, as `git diff --cached --name-only --no-renames` listed them, printed in it. A red in it takes step 2's route, and `references/execute.md` step 2 reads a red the story's changes do not explain the same way here, its second sweep run at the same tree and the same scope. Step 3 then writes `scope=full`, since the full sweep at the base and this one together cover the backfill's tree, beside the `sweep=` line that names the green capture on each side; `gate_eval.py --tests-ran` reads only the `scope=` line. The story's next step 5 writes a marker without that line, so log its value in `.decision-log.md` too, on a line of its own that starts `backfill-sweep:`, never inside the `gate-backfill:` line a resume reads. Step 4's commit can take in a path outside the staged set (a `pre-commit` job that stages a file it rewrote), so step 5 opens with a check, which a resume that starts at step 5 runs too: before it refreshes `.commit-<story_id>`, when the marker carries a `sweep=` line and `git diff --name-only --no-renames <base> HEAD`, with `<base>` the `gate-backfill-base:` commit, lists a path the scoped capture's printed staged list does not hold, run the full sweep on `HEAD`. When it is green, write the marker again from it with no `sweep=` line, then go on with step 5. A red in it ends the cycle at a re-loop as "A red backfill sweep ends the cycle at a re-loop" below does, except that its `assessed-commit:` line names the backfill commit, `HEAD`, and the files are already committed; that logged verdict takes a resume out of `references/execute.md`'s fifth resume case. The second run a row that reads `GREEN` gets ("A reported gap stays open until a later pass measures it closed" below) still takes the test command of the story's full sweep: the scoped form changes only this sweep.
**A red backfill sweep ends the cycle at a re-loop.** A red in step 2's sweep, a commit hook's rejection at step 4 included, that needs a change outside the backfilled test files, or is still red after the second fix, means the backfill has found a defect in the story's code. Of what automate's pass and its backfill produce, it is the one thing that ends a cycle before trace, because a failing sweep is a script's result and not a judgment; a `gate-gap:` line never ends a cycle. A fix made here would land after automate's only pass in this cycle and skip the generalize step, so commit nothing and run no trace, NFR or test review in this cycle. Log this cycle's verdict in `.decision-log.md` as a fenced JSON object holding only `verdict` and `reasons`, `{"verdict": "reloop", "reasons": [...]}`, with one reason naming the red, and beside it an `assessed-commit:` line naming the `gate-backfill-base:` commit, the commit automate measured. That object is the shape `scripts/gate_trail.py` reads as a recorded verdict, and since no trace ran it holds no `gate_status`. It stands in for the `gate_eval.py` result this cycle never produced: the run-status heartbeat's `last_reasons` copies its `reasons` (`references/execute.md`, "Run-status heartbeat"), and an attended run prints the one verdict line "Attended runs also print the verdict, once" (under "Run the gate") describes when this verdict is logged, with `n/a` as the `gate_status`. Then take the `reloop` route under "Route on the verdict" with the red and every open `gate-gap:` line of this cycle that is neither `unmeasured`, `unkilled` nor owned as its findings, turn-ceiling check included. The backfilled files stay staged in the main tree, so the re-loop's `references/execute.md` step 4 commits them with its fix, and the next cycle's automate scope, the diff from the `assessed-commit:` commit, holds the fix and those tests. When the turn-ceiling check turns that re-loop into `escalate`, the backfilled files stay staged too, and the escalation sidecar's `decision_needed` names each of them as staged for this story. The cycle after this re-loop runs the full gate, never a delta gate: this cycle wrote no trace, NFR or test review artifact for a delta gate to re-check. A resume that finds this verdict logged and `HEAD` still at its `assessed-commit:` commit takes this re-loop where the log stopped (`references/execute.md`'s fifth resume case).
**A resume after a backfill does not run automate again.** When this story's `.decision-log.md` holds a `gate-backfill-base:` or a `gate-backfill:` line with no verdict logged after it (when it holds both for this cycle, the later one decides which bullet applies), `references/execute.md`'s fifth resume case sends the resume here, and it goes on from where the cycle stopped:
- After `gate-backfill: <sha>` with `HEAD` still `<sha>`, rebuild the worktree at that commit and run trace, NFR and test review on it.
- After `gate-backfill-base: <sha>`, when `git rev-parse HEAD` prints `<sha>`, the backfill is not committed yet: start again at step 1 above. When `git rev-parse HEAD~1` prints `<sha>`, it is committed: start at step 5.
- At any other `HEAD`, the story is not in this case: take the route `preflight_check.py` reports.
**At most one automate pass finishes per gate cycle, and a backfill never restarts the cycle.** After the backfill commit the same cycle goes on, on the new commit, and automate does not run in it again, so every cycle reaches a verdict whatever automate finds: trace's, or the re-loop a red backfill sweep takes. Automate runs a second time in one cycle only when a resume finds the first pass's summary unfinished, or finds none at all ("A summary already at that name is this cycle's own" below). A later cycle of the story exists only because a verdict sent it back to be gated again, and in that cycle, whether the re-gate is full or delta, automate's scope is the diff from the previous gate's `assessed-commit` line to the commit under assessment, plus the mutation rows behind the previous cycle's backfilled gaps and behind every open `gate-gap:` line that is not owned ("An owned `gate-gap:` line is not this story's to close" below):
- It searches for new gaps only in code that diff changes. Code outside the diff was in an earlier cycle's scope already.
- It re-runs, at the commit under assessment, whatever the diff covers, the mutation rows behind each gap the previous cycle backfilled (the `scripts/mutate_check.py` table rows recorded in the summary named for that cycle's `gate-backfill-base:` commit), never a gap whose test step 1 of "When automate backfills" moved aside for an owned line, and behind each open `gate-gap:` line that is not owned (the rows recorded in the summary the line names). For an `unmeasured` line ("A risk automate names on a P0 criterion" below), and for a line whose rows cannot run ("A reported gap stays open until a later pass measures it closed" below says which cannot), it measures the gap afresh instead and writes new rows for it. A row that reads `GREEN` is a gap again, and "Automate backfills every gap it finds on a P0 criterion" below says whether automate backfills it or reports it, except a row behind an open `unkilled` line, which keeps that line open and gets no new test ("A backfill is confirmed in the pass that writes it" below). A re-loop sent to close a reported gap often adds only a test, which leaves the gap's code outside the diff, so without this re-run no gate would measure whether that test closes the gap.
- When that diff is empty, automate still runs, for the open `gate-gap:` lines that are not owned and nothing else, when any of them names a commit other than the commit under assessment. Otherwise skip automate and the rebuild, and carry the open lines unchanged, `unmeasured` and owned ones included. A cap-only re-gate, and the re-gate a closed `operator-evidence-owed` escalation owes, measure the commit the previous gate measured, so automate has nothing left to look at there unless an open line that is not owned names another commit, and the gate is still the full instrument. Each automate pass leaves every open line that is not owned naming the commit that pass measured, so no cycle runs automate at a commit an earlier cycle's pass has measured, and an owned line, which keeps the commit it names, never makes automate run.
- When the previous verdict record has no `assessed-commit` line, automate runs in full, as in a story's first cycle (the same fallback the delta profile takes).
(Measured on one story, where each backfill started a new cycle: two cycles of about an hour each ended at automate with a new backfilled test, and a third reached a verdict only once its automate could not add tests. The second gap sat in code the first automate pass had already searched and named as a risk, outside the diff between the two cycles, which held only the first backfill's tests. A re-run of the previous backfill's mutation table alone would leave a re-loop's own new code, the code automate exists to cover, with no automate pass at all, and the diff alone would leave a gap a re-loop was sent to close unmeasured, so a later cycle takes both.)
**Automate backfills every gap it finds on a P0 criterion.** In any cycle, whatever its scope, and even while the story's live results file holds a record at the commit under assessment, a gap automate finds on a P0 criterion gets a test: the backfill is committed before trace ("When automate backfills" above), so TEA's trace counts the test and `gate_eval.py` decides. A gap on any other criterion it backfills only when the gap's code is in this cycle's search scope (the code that landed during Execute in a story's first cycle, the diff in a later one) and the story's live results file holds no record at the commit under assessment. Otherwise it reports the gap rather than backfills it: it names the gap in its summary, with its mutation evidence, and adds no test. So only a gap on a criterion other than P0 is ever reported rather than backfilled, and a gap on a P0 criterion goes without a backfill on purpose only when an owned line names it, which automate leaves alone ("An owned `gate-gap:` line is not this story's to close" below). A gap behind an open `unkilled` line already has its test, so no pass writes it another while its rows can run ("A backfill is confirmed in the pass that writes it" below). The behaviour under a gap whose rows only a test that reads source text has killed already has that test, so no pass writes it another test that reads source text: only a test that executes the code can measure it ("A test that reads the source measures only its spelling" below). A P0 backfill made while a live record sits at the commit under assessment moves that commit past the record, and that needs no rule of its own: a `pass` counts only at the commit trace measures ("Operator evidence is a recorded live result" below), so the gate at the backfill commit owes the AC again through the routes that already owe one (the `operator-evidence-owed` escalation on a FAIL, a ledger row on `advance` or `defer`), as `references/execute.md`'s fourth resume case already says of the commit a red makes past the assessed commit. For a gap on another criterion that cost is not worth paying, which is why automate reports it instead.
**A risk automate names on a P0 criterion is measured in the same pass.** The pass is the only one its cycle finishes, so a risk it names in its summary and leaves as prose (an assertion that a mutant failing some other way would also satisfy, say) would reach the verdict unmeasured. When you delegate automate, tell it to measure each risk it names on a P0 criterion before it finishes, with a mutation row for each failure arm the criterion names, its own backfilled tests included, and to backfill each gap that measuring confirms, as it backfills every gap on a P0 criterion. A named P0 risk it still leaves unmeasured is logged as a `gate-gap:` line that says `unmeasured` in place of a summary, and carried: the story's next automate pass measures it, and backfills the gap when a row confirms one. An `unmeasured` line is not a finding, since no mutant has run for it yet, and like every `gate-gap:` line it never changes the route the verdict takes. A risk an owned line names is the exception: automate does not measure it, and its line stays as it was logged ("An owned `gate-gap:` line is not this story's to close" below).
**A backfill is confirmed in the pass that writes it.** When you delegate automate, tell it to write each test it backfills to its repo-relative path in the main tree, copy that file unchanged to the same path in the gate worktree, where its mutation rows run, and re-run there, with the test in place, the rows behind the gap the test was written for, making any later edit to the test in the main tree and copying it again. Tell it, too, to give each row it re-runs there a `command` that runs the backfilled test's file, so that the row's own run sees the test: a row written before the test may select only the tests that existed then, and the second run with the full sweep's command (the second bullet below) can be refused in the worktree, where a tracked-files check sees the copy as a file git does not track. Read each row as "A reported gap stays open until a later pass measures it closed" below reads one. When every row reads killed, the test closed the gap. When a row still reads `GREEN` with the test in place, the test ran and did not kill that row's mutant, which may be an equivalent one that no test can tell from the code: log an `unkilled` `gate-gap:` line for the gap, naming the summary that records its rows and the test that did not kill them. The test is still committed with the backfill. No later pass writes another test for an `unkilled` line while its rows can run: each later pass re-runs them, the line closes when they read killed, a row that reads `GREEN` keeps it open, and a row that cannot run (`STALE` once the code it mutates has moved) has the gap measured afresh, as for any line. Like an `unmeasured` line, an `unkilled` line is not a finding, and it never changes the route the verdict takes.
**A test that reads the source measures only its spelling.** Where no test runner can execute the code a gap sits in (a constructor that needs a live host-framework object, say), automate can backfill a test that reads that code's text instead. A test reads source text when it does not execute the code under its gap and reads that code's text, for example by a file read, an `include_str!` or `include_bytes!`, a `?raw` import, Python's `inspect.getsource` or JavaScript's `fn.toString()`, or an AST or a snapshot of the source. A mutant changes the text such a test reads, so the rows behind its gap read killed, yet nothing has executed the behaviour: its kills measure the spelling and nothing else. Automate's summary says beside each test it backfilled whether the test executes the code ("Automate's summary records its rows" below), and before step 1 of "When automate backfills" stages anything, read each test the summary names too: a test whose text names the `file` of its gap's rows beside a read form reads source text, whatever the summary says of it, and so does one that reads the gap's code by its object without naming the file, as Python's `inspect.getsource` or JavaScript's `Function.prototype.toString` (`String(fn)`, `fn.toString()`) does. The read forms include, among others, `open(`, `read_text`, `read_to_string`, `fs::read`, `include_str!`, `include_bytes!`, `readFile` and `readFileSync` (Node's `fs` or `fs.promises`), Go's `os.ReadFile`, a `?raw` import and a parse of the source. Commit such a test with the backfill like any other, and log an `unmeasured` `gate-gap:` line for the behaviour under its gap, naming the test and what could execute the code (a mock of the runtime, a real build). A row in a file such a test reads counts as killed only as the first bullet under "A reported gap stays open until a later pass measures it closed" below says, so no test that reads source text, the backfilled one or a later one, ever closes that line: it closes only when a test that executes the code kills every row behind it, and no later pass writes another test that reads source text for it. `scripts/mutate_check.py` finds a row's `expect_red` anywhere on a failure line, a test's file path or its suite or class title included, so a test that reads source text and fails can make a row read `KILLED` for a test that executes the code whose name sits inside its own name, its file path or its title: when you delegate automate, tell it to name each test that executes such code so that no test that reads source text has a name, a file path or a suite or class title that contains it.
**Automate's summary records its rows.** When you delegate automate, name its summary `{workflow.implementation_artifacts}/automation-summary-<story_id>-<sha>.md`, with `<sha>` the commit it measures as `git rev-parse HEAD` prints it, and tell it to copy into that summary, verbatim, each `scripts/mutate_check.py` table row (`file`, `anchor`, `replacement`, `command`, `expect_red`) behind a gap it backfilled or reported, or behind an open `gate-gap:` line it re-ran and leaves open, so a later cycle can re-run them. Tell it, too, to say beside each test it backfilled, and beside each test a row it ran names as its `expect_red`, whether that test executes the code under its gap or reads that code's source text, and for one that reads it, what could execute the code ("A test that reads the source measures only its spelling" above). TEA's default, `automation-summary.md` at the TEA `test_artifacts` root, is one file every pass updates, for every story, so step 1 of a backfill would read an earlier pass's files as this pass's, and a later cycle would look for its rows in a file another pass has since updated. If automate writes the flat file anyway, move it to that name before anything else reads it. A host can also refuse a delegated agent's write of a report file, so tell automate, too, that when the host refuses its write of the summary, or of a draft of it, it returns the summary's full text, its frontmatter and its rows included, in its result, rather than write it some other way. When it returns that text, write it at that name yourself, unchanged, in place of whatever is there, before anything else reads it and before you log its `gate-gap:` lines, and log in `.decision-log.md` that you wrote it from automate's text. Its rows are then the ones automate copied, and its frontmatter's `lastStep` the one automate's text gives, never one you set, so a resume reads it as "A summary already at that name is this cycle's own" below says. The ledger that `scripts/mutate_check.py --output` writes leaves out each row's anchor, replacement and command, so it is no substitute for the rows.
**A summary already at that name is this cycle's own.** No two cycles run automate at one commit ("When that diff is empty", above), so a summary at that name was written by this cycle's own pass, in a session that ended before this cycle's verdict was logged, and TEA adds each step's output to a summary that already exists rather than starting a new one. So before you delegate automate, look for it, and right before each time you delegate it, log `gate-automate: <sha>` in `.decision-log.md`, with `<sha>` the commit it measures, the one its summary's name carries: a session that ends while automate runs, or after it finishes but before anything is committed, then leaves a record of where its cycle stopped, and `references/execute.md`'s fifth resume case sends a resume that finds that line for `HEAD`, with no verdict and no backfill line after it, back to this paragraph instead of re-driving the story. When none is there, delegate automate. When it is there and complete (its frontmatter's `lastStep` reads `step-04-validate-and-summarize`, the last step of TEA's automate), that pass finished: do not run automate again. Go on to step 2 of the list at the top of this section with that summary as this pass's, logging only the `gate-gap:` lines this cycle's entry does not hold yet, and leave the dead session's worktree in place until the rebuild removes it, so that step 1 of "When automate backfills" can look in it for the tests the summary names. When it is there but not complete, that pass stopped part way: move it aside to `automation-summary-<story_id>-<sha>-stale-<n>.md` in the same folder, with `<n>` the first number from 1 that no file there carries yet, log the move in `.decision-log.md`, and only then delegate automate.
**A reported gap stays open until a later pass measures it closed.** Once automate has finished, log in this cycle's `.decision-log.md` entry one `gate-gap:` line for each gap it reported, for each risk on a P0 criterion it left unmeasured, for each gap it could not measure because its rows could not run even afresh, and for each backfill its confirmation left `unkilled`, beside any line step 1 of "When automate backfills" logs for a test that was never written. Log one, too, for the behaviour under each gap whose rows only a test that reads source text has killed ("A test that reads the source measures only its spelling" above). Each line names the criterion, its priority, the commit automate measured and the summary that recorded its rows, or `unmeasured` in place of the summary for a risk it did not measure or a gap it could not, and an `unkilled` line also says `unkilled` and names the test that did not kill its rows. An owned line ends with its `owned-by` marker ("An owned `gate-gap:` line is not this story's to close" below). A line for that behaviour says `unmeasured` in place of the summary, and also names the test that reads the source and what could execute the code, in place of an `unkilled` line for the same gap. Every later cycle of the story copies the previous cycle's open `gate-gap:` lines into its own entry, whatever route the previous verdict took: once its automate has finished, or before trace when automate does not run. Whether a line is open is read off `scripts/mutate_check.py`'s classification of each row behind it:
- A row reads killed when it is `KILLED`, `KILLED+others`, or `MISATTRIBUTED` with the detail that its `expect_red` never appears beside a failure token. In each, something the row's command runs failed under the mutant, and a test a re-loop added under a name other than the row's `expect_red` reads `MISATTRIBUTED` that way. Where a test that reads source text reads the row's `file` ("A test that reads the source measures only its spelling" above), the row reads killed only when it is `KILLED` or `KILLED+others` and its `expect_red` names a test that executes the code, a name that is no part of the name, the file path or the suite or class title of a test that reads source text: any other row there, a `MISATTRIBUTED` one included, reads as a row that reads `GREEN` does, and automate makes its second run too (the next bullet), so when you delegate it, tell it to.
- A row that reads `GREEN` is still a gap unless it reads killed when re-run once more with its `command` replaced by the test command of the story's full sweep that covers its `file`, cache-defeated, as step 2 of "When automate backfills" runs it: a row's own command can select only the tests that existed when the row was written, so it misses a killing test a re-loop added in another file. When the second run reads killed, the row reads killed. When it reads `GREEN`, or cannot run (the next bullet), the row is still a gap, read by its first run: a second run that cannot run is no reason to measure the gap afresh. Automate makes that second run in the same pass, for each row it runs that reads `GREEN`, so when you delegate it, tell it to, and to record both results beside the row in its summary.
- A row cannot run when it reads `STALE`, `NOT UNIQUE` or `UNDECODABLE` (its file or its anchor no longer holds, so nothing was mutated), or `MISATTRIBUTED` with the detail that the output's own count says 0 failed (a collection or harness error, not a test: a mutant reads this way when pytest then cannot collect a test module or class or load a conftest.py, or jest, vitest or Node's test runner cannot load a test file, since no test in that file or class runs, or Node's test runner cannot run its global setup, since no test runs at all, or when a Node test file's process exits non-zero after the row's test passes or is skipped, or reports that a test generated asynchronous activity after it ended, whatever test that names, and no other test fails; a Node test file's process that exits or crashes during a test, before Node reports the row's test, still reads as a kill, since the row's `expect_red` then never appears beside a failure token, though it can read 0 failed when a test whose name holds the row's `expect_red` passes or is skipped in that file before the process dies or in a file Node lists before it, when that file reports such asynchronous activity before the process dies, or when the last thing Node prints for that file is an uncaught error that a child process printed; Node prints a test file whose process exits non-zero after all its tests pass as it prints one whose process dies during a test, so such a file whose lines report no pass of a test whose name holds the row's `expect_red` reads as that death, and the row as a kill though no test went red, and when you delegate automate, tell it to write each Node row's `command` to run only the test file that holds the row's test, though a row's second run, through the full sweep, can still read so; a module that calls `process.exit` while a Node test file loads, or that kills its process then by filling the heap or by a signal, stops the file loading, yet Node reports it as it reports a process that exits or crashes during the file's first test, so it reads as that kill does, and when you delegate automate, tell it to write no replacement that makes a module exit, fill the heap or raise a signal while a Node test file loads; and in output that interleaves the lines of several runs with no task-runner prefix to tell them apart, a Node test file that cannot load, or whose process exits non-zero after the row's test passes, can still read as a kill), or `MISATTRIBUTED` with the detail that no test ran (a harness error too: the runner stopped before any test because it could not start its web server, its port taken, by a server an earlier run left up among others, or its start command failing, whether or not the mutant made it fail), or when `mutate_check.py` refuses its table with exit 2 (no row ran). A row whose command runs through a server the gate set reuses, and whose mutated file that server would load, cannot run either, even when the worktree's own processes load that file too, whatever `mutate_check.py` prints, and the two bullets above do not read it ("A server the gate set reuses does not follow the commit", under "Measure the commit, not the working tree"): that server serves the tree it was started from and never the mutant, so whatever the run reads, its `GREEN` is no gap and its red no kill, no test is backfilled for it, no `unkilled` line is logged from it and no line closes on it. It measures nothing, so its line stays open, and the pass measures that gap afresh, once in the pass: when a row it writes for the gap then cannot run either, it measures that gap no further, and logs the gap's line as `unmeasured`, in place of a summary, for the story's next automate pass to measure. A row whose mutated file lies in a workspace package that the worktree reads from the main tree, because its offline install could not serve, and whose command reaches that package by its name (another package's tests, or its own that import it by name), reads the same way, for the same reason ("Dependency directories do not follow the commit", under "Measure the commit, not the working tree"): it loads the main tree's copy of that file, never the mutant.
A line closes when an automate pass at a later commit than the one the line names finds every row behind it reading killed: the line's own rows, re-run, or for an `unmeasured` line or one whose rows cannot run, the rows that pass writes when it measures the gap afresh, any test it backfills for them included. That pass's cycle leaves the line out. A carried line that is not owned and that pass does not close is logged afresh in place of the copied line, naming this commit and this pass's summary, or `unmeasured` while the risk still is or the gap's rows still cannot run, or `unkilled`, naming its test, while a test backfilled for the gap has not killed its rows. A line for the behaviour a test that reads source text left unmeasured closes only when a test that executes the code kills every row behind it ("A test that reads the source measures only its spelling" above), and until then each pass logs it afresh, naming this commit, `unmeasured`, that test and what could execute the code, whatever its rows read. A `gate-gap:` line never changes the route the verdict takes, and each route treats the open lines this way:
- On a `reloop` that is not cap-only, each open line that is neither `unmeasured`, `unkilled` nor owned is one of the findings the generalize step reads. A cap-only `reloop` has no finding to generalize and an `escalate` only stops, so neither of them takes one.
- On `advance` or `defer`, each open line becomes a ledger row with `source` `gate` and `severity` `med`, whatever its criterion's priority, except an owned line on a moved AC, which rides that AC's row. An `unmeasured` line's row says the risk or the gap is unmeasured, and an `unkilled` line's row says the backfilled test did not kill the mutant, which may be equivalent. An owned line's row also names its owner and the ruling in `reason`, and its `suggested_action` names the owner. The row of a line for the behaviour a test that reads source text left unmeasured names that test in `reason`, and its `suggested_action` names what could execute the code. No such row is a gate FAIL or a critical finding, whatever its criterion's priority, so it belongs on the ledger and never re-loops or escalates the story, and neither the INVARIANT under "Route on the verdict" nor the ledger schema's `severity` bar sends it anywhere else: a FAIL is the `gate_status` that `gate_eval.py` reads from TEA's trace, which no `gate-gap:` line changes, and a critical finding is one a code review or the NFR assessment rates critical, while a `gate-gap:` line records automate's mutation measurement, an `unmeasured` one a measurement nobody has made yet and an `unkilled` one a test that did not kill its mutant, not a defect anyone found.
- Whatever the route, a line stays open, so the story's next gate cycle, when there is one, copies it.
**An owned `gate-gap:` line is not this story's to close.** A written operator ruling can assign a risk or a gap a `gate-gap:` line names, on a criterion the story keeps, to another story of this Epic or to a row of the deferred-work ledger. Only then, log the line with `owned-by <owner> per <ruling>` at its end, after every field above: `<owner>` is the story key of a story of this Epic not yet `done`, and any other owner, a `done` story or one outside this Epic included, takes the ledger-row form, `"<Epic heading> <ledger id>"` (a ledger id is unique only within its heading), and `<ruling>` cites the ruling as `Operator notes <entry>` or `decision <id>`, with `<id>` the `.decisions.json` id `/ucg-resolve` recorded it under. The ruling names this story, the criterion or the risk, and the owner; one that names less is not this ruling, and neither is a general or standing delegation, wherever it is written, the bar the clause move in `references/execute.md`'s "Two stories green only together" sets. A ruling that assigns a whole criterion elsewhere is a move of the AC, which takes the moved-AC form ("A moved AC leaves the story's list", under "Route on the verdict"), not this marker alone: whoever applies that form, for any written ruling (the `/ucg-resolve` close, you in an attended run, or the re-read at each cycle's start below, which takes the latest ruling for each AC as it does for each line), writes the story's `.moved-<story_id>` record and logs each open line of the criterion the move retired again with the marker, and those lines reach the ledger inside the moved AC's row and not as rows of their own. An Operator notes entry given before launch (`references/ingest-and-scope.md`, "Operator notes") counts from the story's first cycle: when you delegate automate there, name the risk or the gap the entry assigns and tell automate neither to measure nor to backfill it, then log its line `unmeasured`, with the marker. At the start of each gate cycle, before automate's scope and the empty-diff trigger are decided, read the rulings again (the Operator notes entries, and the `answer` and the `history` of each entry of `{workflow.implementation_artifacts}/.decisions.json` whose `action` is `close`, the store `/ucg-resolve` records every answer in), taking only the latest ruling for each line, an entry's `answer` over its `history` and a later entry over an earlier one, since a later return or reassignment replaces an earlier ruling, and log each open line whose marker that ruling changes in this cycle's entry, with the marker it now gives or with none, in place of the copy the carry makes. Keep the line one line of prose: never a heading, with no JSON object and no `|` in it. An owned line is outside automate's scope in every cycle: automate re-runs no row behind it, neither measures nor backfills the risk or the gap it names, and writes no row and no test for it, so when you delegate automate, name each owned line and tell it so. A test its summary names for one anyway is never staged: step 1 of "When automate backfills" above moves it aside and logs the move. An owned line never closes in this story: each cycle copies it unchanged and never logs it afresh, and only a later written ruling takes the marker off, by logging the line again without it, which puts the line back in automate's scope. It is none of a re-loop's findings, so it gets no `class:` line, and it reaches the ledger once, as the row an `advance` or a `defer` gives every open line (the bullets above), except an owned line on a moved AC, which rides that AC's row, with `source` `gate`, `severity` `med` and `story` this story, its `reason` the line's state (`unmeasured`, `unkilled`, or the summary that recorded its rows) with the owner and the ruling, and its `suggested_action` naming the owner. The owner takes the work up from that row, never from this line: no story's gate reads another story's `gate-gap:` lines.
**Operator evidence is a recorded live result, in either profile.** An AC tagged `**Gate-ability:** operator-evidence` (`references/define-done.md`, step 1) is proven only through TEA's live verification results, which trace reads as `live_results_input` and which TEA lets a person write. For a story with such an AC the file is `{workflow.trace_output_dir}/live-verification-results-<story_id>.json`; name it (absolute, main tree) when you delegate trace. Each record carries `id` `<story_id>-LIVE-<NNN>`, `requirement_id` `AC-<n>`, `status`, `evidence` and `source_sha`, under `schema_version` `0.1.0`. A `pass` counts only at the commit trace measures. Write no record the operator did not give you, and name the operator as `producer`. TEA caps a requirement covered only this way at CONCERNS, so the story defers. That is the honest outcome, never a gap to close with a test that restates the record.
## Measure the commit, not the working tree
Stage 5's subject is a COMMIT, but an assessor that runs or times anything by default measures the WORKING TREE, which is where the next remediation, or a sibling assessor's mutation window, happens. A measured run recorded the consequence three times in one story even under a strict no-concurrent-work rule: one assessor's mutation window contaminated a sibling's timing run (discarded and re-run), and two assessors invented their own ad hoc isolation mid-gate because they could not trust the shared tree. Make the isolation structural instead of a discipline each assessor re-derives: create a worktree of the commit under assessment with `git worktree add <tmp-path> <commit>`, with `<tmp-path>` under `{workflow.implementation_artifacts}/.gate-worktree-<story_id>` (the same containment Execute's scratch rule buys; never an improvised repo-root directory), and point every assessor's reads, runs and measurements THERE. Their OUTPUTS go home: every artifact an assessor writes (trace report, gate decision, NFR assessment, test review, `bmad-testarch-automate`'s backfilled coverage) lands in the MAIN tree's resolved dirs (`{workflow.trace_output_dir}`, `{workflow.implementation_artifacts}`, resolved to absolute paths against `{project-root}` BEFORE any assessor is pointed at the worktree), never under the worktree. The copy of a backfilled test that automate puts in the worktree, to run the rows that confirm it there, is an input to that measurement and not where the test lands: automate writes the test to the main tree first, the main tree's file is the one the backfill commit stages, and the rebuild after automate discards the copy ("A backfill is confirmed in the pass that writes it", under "Backfill the gate evidence"). The worktree is the measurement surface, the main tree is the record: an artifact written into the worktree is destroyed with it, after which the gate re-reads the PREVIOUS cycle's same-named artifact as current (resolution is by name, with no freshness check), which is a stale PASS advancing a story whose fresh assessment was never read. Once the story's verdict is recorded, remove the worktree with `git worktree remove --force <tmp-path>` (the copied-in untracked inputs below make the unforced form refuse, and a measurement surface holds nothing to keep but the build folders the first caveat below carries out when the verdict is a `reloop` the turn-ceiling check keeps), then `git worktree prune`; a resume that finds a dead session's stale `.gate-worktree-<story_id>` removes it the same way before creating its own, carrying its build folders out first only when the story's last gate cycle logged no verdict or a `reloop`. A step that only authors an artifact from already-recorded evidence has nothing to measure and needs no worktree; the rule binds every assessor that runs or times anything. Four caveats the setup owes, each a measured failure when skipped:
- **Dependency directories do not follow the commit.** A worktree carries tracked files only, so an installed dependency tree (`node_modules` and its kin) is absent there. Link each such directory the repo has (root *and* nested) from the main tree into the worktree with `uv run {skill-root}/scripts/link_worktree_deps.py --project-root {project-root} --worktree <tmp-path>`, which links every `node_modules` folder (`--dir <path>`, repeatable, names a dependency folder of another name instead) and prints what it linked, skipped and failed. Never a bare `ln -s`: it is not a command `acceptEdits` runs without asking, nor on the allowlist, so an unattended gate would have it refused, where the script runs under the allowlisted `uv run`. And prefer the symlink over resolver environment variables: Node's ESM resolver ignores `NODE_PATH` (it is honoured by the CJS resolver only), so a `NODE_PATH` bridge quietly breaks exactly the modern half of a JS gate set. Where a symlink cannot serve, an offline install from the package manager's shared store is the fallback, and a dependency folder that holds a workspace link is such a case. A workspace package manager writes each of the repo's own packages into those folders as a relative link (`node_modules/@ex/sb-util -> ../../packages/sb-util`), bun and pnpm also write a registry package's peer on one of them inside their store (under `node_modules/.bun/` and `node_modules/.pnpm/`), and through a folder linked whole such a link resolves to the MAIN tree's package: a run in the worktree that crosses a package boundary, a registry package's import of its peer included, loads the main tree's source, uncommitted edits and build output included, and a mutation written into the worktree's copy never reaches it, so a known-killed cross-package row reads `GREEN` there. So the script reads each folder before it links anything, lists under `workspace` each one that holds such a link, with each link, the package folder it resolves to (`to`) and the lockfiles nearest the folder (`lockfiles`), and then links no folder at all, skipping each other one as `install-first`: an install run over a linked folder writes through the link into the main tree (npm's removed a main-tree package through one, and pnpm's wrote a link into a main-tree folder). For the same reason it fails, with exit 1, a folder the worktree already holds as a link: replace the worktree the way the rebuild below does and run the call again. When it lists one, copy in any package-manager config the install reads that the commit does not carry (an untracked `.npmrc` or `bunfig.toml`, under the next caveat), and give the worktree an offline install with the same `link_worktree_deps.py` call and `--install --impl-artifacts {workflow.implementation_artifacts}` added, never with an install command of your own: no allowlist entry covers one, since a rule matches a command by its start and would let the same install run in any folder, the main tree included, where npm's clean install empties and rebuilds `node_modules`. The call runs, once per lockfile and in the worktree's copy of the lockfile's folder, the offline, frozen-lockfile install of the package manager the lockfile names (npm's for `package-lock.json` or `npm-shrinkwrap.json`, bun's for `bun.lock` or `bun.lockb`, pnpm's for `pnpm-lock.yaml`), each measured to resolve every workspace package, through a peer too, to the worktree's own copy, then links whole each folder the install did not make, never one that holds a workspace link, and prints each install's `command`, `exit` and last `error` line under `installs`. It refuses, with exit 3 and its reason under `refused`, any worktree but `<tmp-path>` (one `git worktree list` gives for the project root, not the main tree, at `{workflow.implementation_artifacts}/.gate-worktree-<story_id>`), a lockfile's folder or a dependency folder that resolves outside it, and a folder whose `lockfiles` is not exactly one of those five. The install runs the packages' lifecycle scripts, as the main tree's install did, so a workspace package whose `prepare` script builds its entry point gets it built from the commit's source. `--offline` keeps the package manager off the network, not a lifecycle script: one that downloads (a browser binary, say) uses its own cache or fails, and a failed install takes the path below. A workspace package whose entry point only its build script makes (a gitignored `dist/`) is built in the worktree with the project's own build command before any run reads it, and never copied from the main tree, whose build is of the main tree's source: the untracked inputs the next caveat copies in are the ones no build of the commit's source produces. When the `--install` call exits non-zero (it refused, or an install failed: a cache that lacks a package the lockfile pins, or a lockfile the offline install refuses) or is itself refused (a permission or sandbox denial), never install online: log the reason it printed (its `refused` line, or the failed install's `command` and `error`) in `.decision-log.md`, replace the worktree the way the rebuild below does (carry its build folders out, remove it, add it again, carry them back), since a failed install can leave part-filled folders behind (bun's did), and run the same call with `--link-workspace` added, which links every folder whole, those included. The worktree then reads the main tree's copy of each package a `workspace` link points to (its `to`), so a mutation row whose mutated file lies in one of those packages, under a command that reaches that package by its name (another package's tests, or its own tests that import it by its name rather than by a relative path), cannot run ("A reported gap stays open until a later pass measures it closed" says how such a row is read): tell automate to write no such row, and tell every assessor that a run of its own that reaches a file in one of those packages by the package's name measures the main tree, so it reports that run as unmeasured. For any other folder a symlink may not serve, measure both once per repo before committing to one. A build folder (Cargo's `target`) does not follow the commit either, and is never linked: two trees that build into one folder run each other's output as their own. So carry the worktree's own across each replacement after which the story is gated again: right before the rebuild's `git worktree remove --force <tmp-path>`, the one once a `reloop` verdict is recorded and the turn-ceiling check of the `reloop` route under "Route on the verdict" has kept it a re-loop, and a resume's of a dead session's worktree when the story's last gate cycle logged no verdict or a `reloop`, run `uv run {skill-root}/scripts/carry_build_cache.py out --worktree <tmp-path> --stash <stash>`, and right after every `git worktree add <tmp-path> <commit>`, before the links above, the same call with `back` in place of `out`. Once an `escalate`, `advance` or `defer` verdict is recorded, a `reloop` the turn-ceiling check turns into `escalate` included, carry nothing out: the build folder goes with the worktree, as it always has, so a story that stops holds no build of its own, and its re-gate builds cold. `<stash>` is `{workflow.implementation_artifacts}/.scratch-<story_id>/gate-build`, so the gate's build folders sit in the story's scratch folder (`references/execute.md`, step 0) while they are out of the worktree, and never pass to another story. A story that escalates keeps none of them (`references/execute.md`, "Escalation sidecar"). The script moves every Cargo build folder (`--dir <path>`, repeatable, names another toolchain's build folder instead, and only one whose tool rebuilds from changed source and never replays a test result) to the same path with a rename, never a test-result cache (`.pytest_cache`, a turbo or nx cache), a folder reached through a link or a path outside the worktree and the stash, and before it carries a Cargo folder out it deletes the run results Cargo's tools keep there (`criterion/`, `nextest/`, `tarpaulin/`, `llvm-cov/`, `tmp/`, `*.profraw`, `*.profdata`), which a mutant's run wrote. It prints what it carried, skipped and failed to move. A folder it cannot move stays in the worktree and goes with it, so its next build is cold, never wrong: its exit 1, a folder that failed, never stops the rebuild or the removal. Its exit 2 means the call was wrong: fix the call or carry nothing, and the honesty line says which.
- **Untracked inputs the gate set reads.** A scratch browser config, an env file, a generated fixture: enumerate what the declared gate commands actually read that the commit does not carry, and copy those in deliberately — an isolated gate that silently lost its config measures a different harness and reports the result as this one's.
- **A server the gate set reuses does not follow the commit.** A test runner that attaches to a server already answering at its URL, instead of starting one (Playwright's `webServer` entry with `reuseExistingServer` true, or `!process.env.CI` outside CI, the form TEA's framework scaffold writes), runs the worktree's tests against the tree that server was started from, usually the main tree: a browser run from the worktree measures that tree's source, and a mutation written into the worktree never reaches it. Read each runner config the declared gate commands load, list each URL it may reuse (`http://localhost:<port>` for an entry that gives only a port), and check them before the first run in the worktree and again after the rebuild, with `uv run {skill-root}/scripts/probe_servers.py --url <url>` (`--url` repeatable), which prints which of them answer and, where the system lets it read one, the folder the server that answered each runs from. When none answers, the runner starts its own server from the worktree, and that server can stay up: the runner stops only the process group its start command runs in, so a server that a launcher such as turbo runs in a group of its own outlives the run that started it and keeps the port, and with reuse on every later run reuses it, a mutation row's included, while it serves the files as they were when it started. So when you delegate automate, have it check them the same way before and after each `mutate_check.py` table it runs, and name in its summary each URL that answers at one of those checks: that is a server the gate set reuses, whoever started it, one a run in the worktree left up included, and with reuse on each row of a table after which it answers ran through it. A server the run itself started is the run's to stop, and no other server is. `references/execute.md` step 5 re-runs the full sweep, browser tests included, in the main tree right before the gate, so a server its runner started through a launcher can still answer at the first check, from the main tree, and the worktree's runs would reuse it. So run the probe at every check this caveat names, automate's included, with the stop flags added: `--stop-since {workflow.implementation_artifacts}/.baseline-<story_id> --root {project-root} --root <tmp-path>`. The probe then stops a server that answers only when it reads as one this run left up: every process in the server's process group is this user's, has no controlling terminal and started after the story's baseline marker was written, the process that led its session has exited, as a runner's start command has once the runner ends, no other process that still runs in that session started before that marker or is the parent of a process in the group, as a watcher that can start the server again is, and the server runs from inside one of those folders. Those are signs, not proof: a server the operator started inside the project after that marker, in the background with no terminal or from a terminal since closed, with nothing older than the marker still running in its session, reads the same way, and so does one that a watcher of the operator's restarts after the marker, when the watcher too started after it and runs in the server's process group, or starts the server through a command that then exits and either started after the marker or had that command give the server a session of its own. A resume keeps that marker, so a server an earlier session of the story started counts. The probe lists each server it stopped under `stopped`. Have automate name in its summary each server the probe stopped at one of its checks, before a table or after one, by the `url` and `cwd` of its `stopped` entry, since only its summary can tell you of those stops. At automate's check after a table, a URL whose server the probe stopped still counts as one that answers there, since with reuse on the table's rows ran through that server. It leaves every other server up and lists it under `left` with its reason, and on a system without Linux's `/proc` it stops nothing. A server the probe leaves up is not the gate's to stop: never stop it any other way, since it may be the operator's own. When the runner config lets the worktree's runs have their own server without editing a tracked file, give them one, whether or not a server answers: a scratch runner config, copied in like the inputs above, that loads the project's own and moves each reused server, its start command and its URL, to a port the probe reports free, with reuse turned off and the base URL pointed at that port. The runner takes it by its config flag (`--config <file>` for Playwright), never by an environment variable set in front of the command, which the command's allow rule does not match past. Tell every assessor to run the runner with it, a mutation row's `command` included, so that each run starts a server from the worktree. Each run then needs that port free: with reuse off, a run that finds it taken stops before any test runs, and a server an earlier run left up keeps it. So give the scratch config a start command that runs the server in the process group the runner stops, where the project has one (the package's own dev script rather than a task runner's), check its URLs with the same probe before each assessor starts, moving each one that still answers to a port the probe reports free, and run no two assessors under it at once. Have automate check its URLs at the same points, before and after each table, and move a port that still answers before it runs the next one. Once the cycle's last test run has finished, a backfill sweep's in the main tree included, and before you log the cycle's verdict, run the probe with the stop flags once more over every URL the gate set may reuse and every URL of the scratch config, so that no server this story's runs left up outlives its gate: over an Epic they would pile up, each holding a port. Run it before the verdict, not after: a story whose verdict is not logged is gated again under the same marker, and that gate's checks stop what an ended session left up, but a server still up once the story has advanced started before the next story's marker, so no later check stops it. A row whose run stopped because the runner could not start its web server reads as one that cannot run, by the detail `mutate_check.py` gives it, that no test ran ("A reported gap stays open until a later pass measures it closed"). No other stop before any test gets that detail: a run Playwright stops because it could not load a spec, a support file or its config reads as a kill, since the row's `expect_red` never appears beside a failure token, so tell automate, too, to write no replacement that stops such a file loading. Otherwise tell every assessor, automate included, in its brief, which URL answers and, when the probe read it, from which folder, that a browser run through it measures the source of the tree that server was started from (the commit's only while that folder is in the main tree, the main tree's `HEAD` is the commit under assessment and no file the server loads differs from it), and that no mutation in the worktree reaches it. Tell automate, too, that it writes no mutation row whose command runs through that server and whose mutated file that server would load, even when the worktree's own processes load that file too (a spec that reads its expected value from it, say): it measures such a risk with a row whose command does not go through that server (a unit or component test that loads the file in its own process), or whose mutated file that server does not load (a spec or a support file the runner loads from the worktree), and a risk on a P0 criterion that no such row can measure is one it leaves unmeasured ("A risk automate names on a P0 criterion is measured in the same pass", under "Backfill the gate evidence"). Any such row it runs, one behind a carried `gate-gap:` line or a previous backfill included, is a row that cannot run, whatever `mutate_check.py` prints ("A reported gap stays open until a later pass measures it closed" says how such a row is read): what it reads measures the server's tree and not the mutant, so its `GREEN` is no gap and its red no kill, no test is backfilled for it and no `unkilled` line is logged from it.
- **The ordering rule stands.** Isolation removes the contamination, not the sequence: the run still gates story N to a verdict before touching story N+1 (the sequential spine is unchanged), so this section licenses no overlap. What the worktree buys is that no stray tree state, the next remediation's included, can contaminate a gate mid-read. It does not keep the assessors apart, since they all measure the one worktree: that comes from the order "Backfill the gate evidence" sets, where automate, the one assessor that edits source, runs alone and the worktree is rebuilt before any other assessor starts. The assessors after it only read, run and time, so none of them changes the tree another one measures. They still share one machine, so a timing one of them takes beside another's runs carries the load caveat `references/execute.md` gives a wide sweep.
**Rebuild the worktree once automate has finished (production).** Automate's mutation runs edit source in the worktree, and it puts there a copy of each test it backfills to confirm the test ("A backfill is confirmed in the pass that writes it" above), so before any other assessor starts, replace the worktree instead of trusting it: carry its build folders out with the `carry_build_cache.py` call the first caveat above gives, remove it with `git worktree remove --force <tmp-path>`, add it again with `git worktree add <tmp-path> <commit>` at the commit under assessment (the backfill's commit when automate made one, per "When automate backfills" above), carry them back with the same call's `back` form, then link the dependency folders with the same `link_worktree_deps.py` call and copy the same untracked inputs in again, exactly as the first setup did: the same `--install` call when the call lists a `workspace` folder, or, when the first setup's install could not serve, the `--link-workspace` call with no second try at the install. Then check the URLs the gate set may reuse again ("A server the gate set reuses does not follow the commit" above), and act on what it finds, as that caveat says, before trace, NFR and test review start: a server may have started since the first check, one started from the old worktree among them, which outlives the worktree's removal. A worktree just added from the commit holds that commit's tracked files and nothing a mutation or a copied test left behind (a backfilled test the backfill commit carries is one of those tracked files), and the rebuild needs no status read of the old worktree, which would take `git -C <tmp-path> status`, a command no allowlist entry covers. The build folders carried back are the one exception, and what a mutant's build left in them is an input the build tool checks, never a result it reads: every file the add writes is newer than anything built there before, so Cargo rebuilds each crate of the worktree from the commit's source and reuses only what no file of the worktree feeds, such as the registry's crates. Rebuild whether or not automate backfilled, and whether this session ran the pass or a resume reused it ("A summary already at that name is this cycle's own" above); skip the rebuild only when no automate pass ran in this cycle (`--light`, or a later cycle that skips it), or when a red backfill sweep ended the cycle before trace, so that no other assessor runs in it.
Record in `.decision-log.md`, once per gated story, whether the gate measured a worktree or the main tree: the same honesty line the sweep's `scope=` carries, since an assessment reported as isolated that actually ran on the shared tree is a false claim about the evidence. In production the line also says whether automate ran alone and the worktree was rebuilt before the other assessors started, and names the commit it was rebuilt at. When a runner reused a server the gate did not start, or one a run in the worktree left up, the line also names its URL, the folder it ran from when the probe could read one, and what it left unmeasured. It also names each server the probe stopped, by its URL and the folder it ran from, those automate's summary names included, since a server the operator started can read as one the run left up. It also names each build folder `carry_build_cache.py` carried out or back, and each one it skipped, with the reason it printed, or failed to move. It also names each folder `link_worktree_deps.py` listed under `workspace` and the offline install the worktree got for them, and, when no install could serve, the call's refusal or the install that failed and its last error line, each package the worktree then read from the main tree, and each mutation row and assessor run that left unmeasured.
## Non-web stack: the red phase by hand, and the trace artifacts where trace cannot run
On TEA 1.27.2, `bmad-testarch-trace` runs on any stack (verified on a pytest project, where it authored the gate with `gate-provenance: tea`), so run it first on every stack and read its decision. Two things in this section still apply. The red phase established by hand (items 2 to 4 below) applies on any stack ATDD's generator cannot serve, whether or not trace runs. The two trace files described next are the fallback for when trace halts or cannot run (an older TEA build, say): then nothing else emits the binding gate decision, and you author it. A `bmad-testarch-trace` that is not installed is not this case: preflight's `tea_skills` blocker refused a launch without it, so the install changed mid-Epic. Escalate the story as Execute's sub-skill halt catch-all says (`references/execute.md`). Do **not** reverse-engineer a prior run's leftover artifacts: author the two files to the exact shape `scripts/gate_eval.py` reads; every other field in real TEA output (`target`, `links`/`trace_report_path`, `rationale`, `schema_version`) is decoration the reader never touches. **Name all four for the story**: `trace-<id>.md`, `gate-decision-<id>.json`, and on the production path `nfr-assessment-<id>.md` and `test-review-<id>.md`. The first pair must be per-story because `--story <id>` scoping resolves them by name in a shared `--trace-output` dir. The second pair binds nothing mechanically (the `--nfr` / `--test-review` flags take an explicit path), which is exactly why it needs stating: unnamed, each story's NFR and review overwrite the last one's in that shared directory, and the audit trail keeps only whichever story finished most recently.
**`trace-<id>.md`** — only the frontmatter is read (the body is human prose). The resolver needs exactly two keys:
```yaml
---
workflowType: testarch-trace # must be 'testarch-trace' or 'trace', else the report is skipped
gateDecisionFile: gate-decision-<id>.json # the slim file to read; a bare filename in --trace-output
---
```
**The hint is bounded, and a hint it refuses is not fatal.** `gateDecisionFile` must name a file sitting **directly in `--trace-output`**: a bare filename, never a subdirectory, never a `..` path and never an absolute path (a hint that resolves outside the artifact directory is ignored, because a gate read from outside the directory the run was pointed at is not this run's gate). When the hint carries a story id it must be **this** story's; when it carries none, it is honoured only where no other story's artifact is present. A refused hint does not fail the story on its own: resolution continues to `gate-decision-<story_id>.json` and then to the same fail-closed rule an artifact-less story gets.
**`gate-decision-<id>.json`** — the slim file the hint points at. `gate_eval.py` reads only these four keys; `gate_status` alone drives the `--light` verdict (PASS/WAIVED → advance, CONCERNS → defer, FAIL → reloop, NOT_EVALUATED → escalate), the other three are passed through into the verdict JSON / `.decision-log.md`:
```json
{ "gate_status": "PASS", "p0_status": "MET", "p1_status": "MET", "overall_status": "MET" }
```
Write a PASS only when the story is demonstrably done to its profile's Definition-of-Done (under `--light`: acceptance criteria satisfied with lint and build green; under production the bar is higher — also un-skipped passing acceptance tests plus test-review/code-review, per the profile note below — see `references/define-done.md`); a non-green story is `reloop`/`escalate`, never a hand-authored PASS (see the INVARIANT in "Route on the verdict"). `p0_status`/`p1_status`/`overall_status` are passthrough-only here — they do not drive the `--light` verdict, so write them to reflect reality, never to dress up a non-green story. If you instead write the always-present `e2e-trace-summary.json`, the reader takes its top-level `gate_status` and the nested `gate_criteria.{p0_status,p1_status,overall_status}` — the same fields one level down.
**Which profile's gate you then run.** The hand-authored trace decision above is the same file for either profile; only what you AND onto it differs. Under **`--light`** it *is* the whole gate — run `gate_eval.py --profile light` (below) and stop. Under **production** — the legitimate case when an operator scopes foundational, non-web packages to the full chain — the production ANDs still apply. What a non-web stack cannot use as-is is ATDD's generator in Stage 3, which on TEA 1.27.2 detects a backend stack but still emits only Playwright/TypeScript scaffolds. Trace runs on any stack, and automate lists a backend worker (pytest, JUnit, go-test) that this module has not yet verified. So the story's acceptance tests are authored and driven in the stack's own harness (the Vitest case) and reach the production Definition-of-Done un-skipped and passing; the trace decision is TEA's wherever trace runs, and you hand-author it as above only where it cannot.
**A production story on this path owes five deliverables.** (A `--light` story owes at most two of them, items 1 and 5, and item 1 only where trace cannot run: the trace decision *is* its whole gate, and provenance is logged whichever path it took.) Each is independently checkable and each has been independently dropped by a run that complied with the rest — so they are numbered rather than prosed, and a production story is done with this section only when all five exist:
1. **The trace decision** — TEA's own wherever trace runs, and the two hand-authored files above only where it cannot.
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.
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.
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.
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.
`bmad-testarch-nfr` and `bmad-testarch-test-review` are independent of trace and wait only for automate and the step after it, its backfill commit and the worktree rebuild (see "Backfill the gate evidence" above), so still produce `nfr-assessment.md` and `test-review.md` the normal way and run `gate_eval.py --profile production --story <story_id> --nfr <…/nfr-assessment-<story_id>.md> --test-review <…/test-review-<story_id>.md> --tests-ran {workflow.implementation_artifacts}/.tests-ran-<story_id>`. Pass **both** signal flags (and `--tests-ran`, which every per-story gate carries: the sweep-scope AND binds this path unchanged). `gate_eval.py` fail-closes a `--nfr`/`--test-review` path that is given-but-missing **and one you simply omit**: an omitted flag on a per-story production gate is itself a failing signal, with a reason naming the flag. That is deliberate: a forgotten flag used to be skipped in silence, so the AND never ran, the field rendered `null`, and the verdict was computed without it, which bought a *higher* verdict than supplying a failing artifact would have. If a signal genuinely cannot be produced on the stack, that is a CONCERNS/`defer` or a `reloop`, never a dropped flag. The one legitimate omission is the epic roll-up, which declares itself with `--epic-level` (see "Route on the verdict") rather than by leaving the flags off. A stack that cannot meet the production acceptance-test bar at all belongs under `--light` (see the framework fitness caveat in `references/preflight.md`), not a hand-waved production PASS. The honesty bar is unchanged: a PASS requires full AC coverage by passing tests, never to dodge an AND.
**The epic-level roll-up needs no hand-authoring at all where sprint-status is available: run it with `--rollup`** (see "Route on the verdict"), which computes the aggregate from the per-story artifacts this section already had you author — no `trace-<epic>.md` required. Hand-author the epic pair only where the gate cannot be given sprint-status. **In that fallback the roll-up needs the same hand-authoring, named for the EPIC.** Everything above is written per story, and where trace cannot run nothing ever writes the epic's own `trace-<epic>.md`, while the omit-`--rollup` form of the gate below presumes it exists: `--story <epic_id>` in a per-story-named directory resolves nothing and fail-closes a completed Epic to `escalate`. When every story is `done`, hand-author the same two files named for the epic id — `trace-<epic>.md`, its frontmatter pointing at `gate-decision-<epic>.json` — with a `gate_status` that honestly summarises the per-story record: a PASS only when every story advanced, never a roll-up dressed over a story that did not. It takes no NFR and no test-review; the roll-up declares that omission with `--epic-level`, per "Route on the verdict" below.
**Hand-authored `nfr-assessment.md` and `test-review.md` shapes (production path only).** `gate_eval.py` scans these two files with the *same* parser it uses on real TEA output, so a hand- or agent-authored file must carry the exact fields below — otherwise the scanner reads the signal as *not found* and, under the fail-closed contract, treats it as **failing**, spuriously downgrading an `advance` to `reloop`. (Under `--light` neither file is read, so this whole block is production-only.) Only the named field is parsed; everything else is human prose.
`nfr-assessment.md` — the reader needs one field:
```markdown
**Overall Status:** PASS
```
`PASS` | `CONCERNS` | `FAIL` | `NOT_ASSESSED` (the key may also be written `overallStatus:`). A `FAIL`, a `NOT_ASSESSED`, or a status the scanner cannot find all downgrade `advance`→`reloop`. `NOT_ASSESSED` is listed because TEA emits it and the scanner recognises it: it parses cleanly, so it never reaches the cannot-find branch, and it means the NFRs were never evaluated — strictly weaker evidence than a file the reader cannot parse, which already fails closed. Write it honestly rather than reaching for `CONCERNS` to keep a story moving; `CONCERNS` is a `defer` and claims the NFRs *were* assessed.
`test-review.md` — the reader needs two fields:
```markdown
**Quality Score**: 89/100
**Recommendation**: Approve
```
The score **must** carry the `/100` denominator: a bare `score: 89` matches nothing, is read as *not found*, and fail-closes to `reloop` — always write it as `N/100` (a `Quality Score` label or a bare `score` both parse, but only with `/100`). `Recommendation` ∈ `Approve` | `Approve with Comments` | `Request Changes` | `Block`; a `Block`, or a score `< 80`, downgrades `advance`→`reloop`.
## Run the gate
**Name the per-story paths trace writes, in either profile.** TEA 1.27.2's `bmad-testarch-trace` writes fixed, flat paths at the TEA `test_artifacts` root (`traceability-matrix.md`, `e2e-trace-summary.json`, `gate-decision.json`) and does not read `trace_output`. Left alone, its output neither lands in `{workflow.trace_output_dir}` nor names a story, so the gate below resolves nothing there, and each story's trace overwrites the last one's. When you delegate trace for a story, name the paths it must write in `{workflow.trace_output_dir}`: `trace-<story_id>.md` (frontmatter `workflowType: testarch-trace`, `gateDecisionFile: gate-decision-<story_id>.json` and `tempCoverageMatrixPath`, the absolute path of the coverage matrix TEA's own step 4 records, which the report must still carry after step 5, since `operator_owed.py` reads the matrix through it), `gate-decision-<story_id>.json` and `e2e-trace-summary-<story_id>.json`, with `<story_id>` the sprint-status key copied verbatim. If it writes the flat files anyway, move them to those names before anything else reads or overwrites them. For a decomposed child (`references/execute.md`, step 1), which has no story file, the names also hold its parent's story file, as the file trace reads the child's criteria from, and the parent AC ids the child's sprint-status row claims, as the only criteria trace scores: the siblings' ACs stand in that file too, and none of them is a row of the child's coverage matrix or a part of any of its scores. Ask for nothing beyond those names, those frontmatter keys, the live results file trace reads for a story with an operator-evidence AC ("Operator evidence is a recorded live result" above) and, on every gate cycle of a story with a `.moved-<story_id>` record, the story file trace reads the story's criteria from and every `oracle=` path that record lists, each named absolute in the main tree: the move, and an operator's edit of an oracle source, are edits no commit carries until the story advances ("A moved AC leaves the story's list", under "Route on the verdict"), so the worktree's copies still state the AC. Name the files and nothing of the move, which the files themselves state: the provenance stays `tea` only while TEA's own steps computed the content.
**After a move, check that trace scored no moved AC, in either profile.** On every gate cycle of a story with a `{workflow.implementation_artifacts}/.moved-<story_id>` record ("A moved AC leaves the story's list", under "Route on the verdict"), the re-gate the move owes first, move the story's previous `trace-<story_id>.md`, `gate-decision-<story_id>.json` and `e2e-trace-summary-<story_id>.json` aside, all three in one step, before you delegate trace, into `{workflow.implementation_artifacts}/evidence-<story_id>/`, each under its own name with `-cycle-<n>` before its extension, `<n>` the first number from 1 that no file there carries yet, so nothing there is overwritten, and a trace that writes nothing, or only some of its files, leaves the check nothing of an earlier cycle to read, and it exits 2. A resume that finds some of the three moved aside and some still in place moves the rest aside the same way before trace. A resume that finds them moved aside still routes `gate-owed`: through `references/execute.md`'s fourth resume case while the `.regate-<story_id>` marker is fresh, and otherwise through its third, which finds neither the trace report nor the gate decision. Once trace has written its files and before `gate_eval.py` runs, run the command below, with `--commit` the full sha `git rev-parse <the commit under assessment>` prints and one `--moved AC-<n>` for each line of the record that is not an `oracle=` line, taken from the `AC-<n>` that opens it. Run it whatever `gate_status` trace wrote. Trace scores every criterion it resolves, from the story, the epic, the PRD or the test design, and has no status for a moved one, so an AC that left the story's list can still be a row of its coverage matrix, and a row left at `NONE` fails the gate, or holds it at CONCERNS, over work this story no longer owes. Exit 0 means no row is a moved AC: run `gate_eval.py` as below and take the route its verdict gives, the ordinary routes unchanged, since what it scores is then only criteria the story still owns. Exit 1 means a row is one, and exit 2 that the trace files could not be read, are not this trace's or measured another commit, since the script reads them as `operator_owed.py` does and fails closed. On either, run no `gate_eval.py`. Log the script's JSON and, as this cycle's verdict, a fenced JSON object holding only `verdict` and `reasons`, `{"verdict": "escalate", "reasons": [...]}`, with the script's `reasons`, as a red backfill sweep logs its re-loop, with the provenance and `assessed-commit:` lines "Record who authored the artifacts the verdict rests on" below asks for. Then take `escalate` with `kind` `operator-evidence-owed` again: `source` is the trace report's path, `evidence` is the script's first reason, and `decision_needed` opens with "The moved-AC check refused (exit 1)" or "The moved-AC check refused (exit 2)", then names this run's id, the refusal's number for this story (one past the refusals of this story the decision log already records), `assessed_commit` (the script's, or the commit under assessment when it printed none), each moved AC, and what must change before a re-gate can pass, so each refusal is a decision of its own and never one `/ucg-resolve` has closed already. On exit 1, that is each source in the script's `oracle_sources` that still states a moved AC for this story (when it names none, the story file, the epic, the PRD and the test design), which the operator edits in the main tree so it no longer does, or a written return of the AC to the story. Resolve a relative source against `{project-root}`, and name one outside the work tree `git rev-parse --show-toplevel` prints, or one that names no file, as a source the operator must clear themselves, since only a path inside the work tree is recorded and committed. On exit 2, it is that the trace files are missing, not this trace's or of another commit, so the re-gate runs trace again, and `decision_needed` says whether an exit-2 refusal of this story at this commit came before. `/ucg-resolve` keys its close on that opening phrase. Write no `class:` line and take no `reloop` route, since no re-loop changes what trace reads.
```
uv run {skill-root}/scripts/moved_ac_check.py --trace-output {workflow.trace_output_dir} --story <story_id> --commit <the full sha git rev-parse prints for the commit under assessment> --moved AC-<n>
```
Production:
```
uv run {skill-root}/scripts/gate_eval.py --trace-output {workflow.trace_output_dir} --story <story_id> --profile production --nfr {nfr-assessment.md} --test-review {test-review.md} --tests-ran {workflow.implementation_artifacts}/.tests-ran-<story_id>
```
Light:
```
uv run {skill-root}/scripts/gate_eval.py --trace-output {workflow.trace_output_dir} --story <story_id> --profile light --tests-ran {workflow.implementation_artifacts}/.tests-ran-<story_id>
```
Resolve `{nfr-assessment.md}` and `{test-review.md}` to the paths TEA wrote them to (under `{workflow.trace_output_dir}` or the TEA output root); pass the production-only flags only in production. The script reads `gate-decision.json` (resolving its filename from the trace report frontmatter, falling back to the `e2e-trace-summary.json` gate fields when the slim file is absent — that fallback is **not** a failure).
**`--story` in a shared multi-story trace dir.** When every story in a multi-story Epic writes a per-story-named trace report + gate decision (`trace-<id>.md`, `gate-decision-<id>.json`) into the **one** shared `{workflow.trace_output_dir}`, an unscoped read resolves the first/oldest story's gate, a false verdict for every later story. Pass `--story <story_id>` (the id of the story you are gating) so resolution is scoped to that story's artifacts; matching is on id components (`61-6` == `61.6` == `61_6`) anchored to the trailing components, so epic id `1` resolves `trace-1` and never the child story `1-1`'s report. **`<story_id>` is ONE string, used byte-identically in three places:** the story's `sprint-status.yaml` key, the `<id>` in the artifact filenames above (`trace-<id>.md`, `gate-decision-<id>.json`, and the same `<id>` in the per-story NFR and test-review names the non-web section above pins), and this `--story` argument. Copy the key verbatim, whether it is bare (`4-2`) or carries a kebab title slug (`4-2-<kebab-title>`); do not abbreviate it to its number when invoking, and do not expand it when naming. When TEA wrote the files under other names, rename them to the sprint-status key per "Name the per-story paths trace writes" at the top of this section, rather than passing the stem it wrote. **A mismatch fails in both directions**: `--story 4-2-<kebab-title>` resolves `gate-decision-4-2-<kebab-title>.json` and *not* `gate-decision-4-2.json`, and `--story 4-2` resolves neither. The tolerance is deliberately no wider than this: matching is anchored to the trailing components on purpose, because a prefix match would let epic id `4` resolve `trace-4-2-<kebab-title>.md` and hand the epic roll-up a child story's verdict, which is the fail-open the anchor exists to close. **Recognise the symptom:** a spelling mismatch surfaces as `gate_status: NOT_EVALUATED` -> `escalate`, worded identically to a story that genuinely wrote nothing, so before treating that `escalate` as a real block, list `{workflow.trace_output_dir}` and compare the exact stem. For the **epic-level** gate after the last story, pass the epic's own id the same way (it resolves the epic's `trace-<epic>` report, not any child story). **`--story` fails closed on a genuine no-match: this is a behaviour change.** It used to fall back to the unscoped read whenever nothing matched, which meant a story that wrote *no* artifacts at all silently reported a NEIGHBOURING story's gate as its own: an unevaluated story could read `PASS`/`advance`. Now the fallback depends on how the directory is **named**. If any artifact there is named for a story, a `--story` that matches nothing means that story is genuinely absent, and the read returns `gate_status: NOT_EVALUATED` -> `escalate`, with a reason naming the artifact KIND that made the directory per-story-named (never a neighbour's filename: quoting one in an absent story's verdict is the very fail-open this branch closes). **"Named for a story" is wider than the two gate-bearing files, and the test is not "ends in a number".** Seven prefixes count (`gate-decision`, `e2e-trace-summary`, `nfr-assessment`, `test-review`, `traceability-matrix`, `trace`, `atdd-checklist`), and the rule is that the component **immediately after the prefix starts with a digit**, so `trace-52-0a.md` and `trace-5-8-some-slug.md` both count even though neither ends in a number. Two consequences worth holding: a per-story NFR assessment or test review, alone, flips the directory per-story-named on its own even with no trace or gate file beside it, and those are artifacts the non-web section above orders into this same directory; and an id whose first component is not a digit (`trace-sb-5.md`) does not flip it, which is one more reason the isolated-track rule requires a numeric epic prefix. If instead every candidate is generically named (`trace.md`, `gate-decision.json`), the directory holds one story's artifacts and the documented unscoped fallback still applies, so passing `--story` against a single-story dir resolves exactly as before. `--story` remains optional; omit it only when `{workflow.trace_output_dir}` provably holds a single story's artifacts. If you were relying on the old silent fallback in a per-story-named dir, you will now get an `escalate` instead of a verdict, which is the point: it surfaces a story whose gate was never produced. TEA 1.27.2 does not name its trace artifacts per story on its own: give it the per-story names, or move its flat files to them, in the shared `{workflow.trace_output_dir}` exactly as "Name the per-story paths trace writes" at the top of this section says. Never isolate a story into a fresh directory instead: the `--rollup` Epic gate refuses a multi-story Epic whose trace directory is not per-story-named, and the gate trail reads one trace directory. It returns JSON:
```json
{"verdict": "advance|defer|reloop|escalate",
"gate_status": "PASS|CONCERNS|FAIL|WAIVED|NOT_EVALUATED",
"p0_status": "...", "p1_status": "...", "overall_status": "...",
"nfr_status": "...", "review_score": 0, "reasons": ["..."]}
```
Do not recompute TEA thresholds or re-judge `gate_status` — read it as given. The script already ANDs the production signals (an `advance` is downgraded to `reloop` if `nfr-assessment.md` overallStatus is FAIL, or `test-review.md` score < 80 or recommendation is Block). Record the full verdict JSON and its `reasons` in `.decision-log.md` for this story.
**Head each gate cycle's entries with the story's key.** Before a gate cycle logs anything in `.decision-log.md` (in production, before the `gate-automate:` line "Backfill the gate evidence" logs ahead of automate), write the heading `### Story <story_id>: gate` on a line of its own, with `<story_id>` the sprint-status key copied verbatim, as `--story` takes it. Write it again before each later cycle of the story, a re-gate included. Under it, log the cycle's verdict JSON as a fenced JSON object on lines of its own, as a red backfill sweep logs its re-loop. `scripts/gate_trail.py` reads the verdict the run acted on from the first JSON object carrying `verdict` after such a heading, fenced or inline in backticks, and never from one carrying `"epic_level": true`, the Epic-level gate's roll-up, or from one whose `reasons` say it read another story's gate file. The heading's entries run to the next heading the trail reads as a story's: one in this shape, one whose id after `Story` starts with a digit, or one whose id is a key `sprint-status.yaml` lists, so a prose heading such as `### Story order` ends none. A later heading in this shape for the story replaces what an earlier one's entries recorded, even when no verdict object follows it, so the story's last cycle decides: when the trail cannot read that cycle's verdict, it shows the gate artifact's status, mapped, never an earlier cycle's verdict. The trail reads a later heading for the story as a later cycle too when only its level differs (`## Story <story_id>: gate`), or when it says `re-gate` or `regate` for `gate` (`### Story <story_id>: re-gate`). The same holds when `gate` is followed by a cycle number (`2`, `#2` or `cycle 2`) after a blank, a comma, a semicolon, a colon or a dash, which a note in parentheses may follow (`### Story <story_id>: gate - cycle 2`), and when `gate` is followed by a note in parentheses that says `cycle` or `re-gate`, or holds only a number (`### Story <story_id>: gate (cycle 2)`). Any other text after `gate` makes the heading no cycle, a note that names no cycle included (`### Story <story_id>: gate (skipped)`), so write each cycle's heading in this shape. A later heading of another shape for the story (`### Story <story_id>: re-loop 1`) is no cycle: it replaces that verdict only with a verdict object of its own, so a re-loop's notes never turn a downgraded or capped `reloop` into the gate artifact's mapped `advance`. A heading the trail does not read as a story's leaves its verdict objects in the previous story's entries, so a heading that starts with `Story` and a digit names a story key, never a position such as `Story 2 of 5`.
**The sweep-scope AND (`--tests-ran`, per-story gates, both profiles).** Pass `--tests-ran {workflow.implementation_artifacts}/.tests-ran-<story_id>` on every per-story gate, exactly as the commands above show. The script reads the marker's `scope=` line (`references/execute.md` steps 2 and 5 write it beside `baseline=`): `scope=full` asserts the green run behind this gate was the full three-axis sweep, or, beside a `sweep=` line, the full sweep at the commit a backfill of test files alone built on together with that backfill's scoped sweep ("A backfill of test files alone may scope its sweep", under "Backfill the gate evidence"), and passes the verdict through; `scope=scoped` is legitimate mid-loop evidence, so the verdict is **capped at `reloop`**: a story may only advance off a full-scope sweep, and the cap moves `defer` too, because defer's route advances the story. Fail-closed like every other signal: a missing marker, a marker with no `scope=` line, or a value the reader does not recognise all get the same cap, with a reason naming what was wrong. The verdict JSON carries the recognised value as `sweep_scope` so an advance that proved its sweep is distinguishable from one that was never asked. Two boundaries: the epic roll-up gates no sweep of its own, so `--epic-level` refuses the flag outright (an invocation error, exit 2, the same lane as `--epic-level` with `--nfr`); and *omitting* the flag skips the check rather than failing it, deliberately (making omission failing would change the verdict of documented invocations that predate the flag, the exact 2.0.0 lesson `docs/_internal/STABILITY.md` records), so the always-pass-it rule lives here, in the instruction, and a per-story gate invoked without the flag is a drift to fix, not a laxer mode to use.
**The delta cycle profile (`--cycle-profile`, mid-loop gates, production).** A gate whose previous evaluation of this story was `reloop` with findings cleanly attributed to their assessor dimension may re-run as a **delta gate**: re-run in full only the assessor(s) whose dimension produced the failing findings, while the others verify their own prior artifact against the diff from the previous gate's `assessed-commit` line to the commit under assessment (a concerns-only re-check; a previous verdict record without that line means the fallback below: run the full gate) instead of re-deriving the story from zero. Declare it (pass `--cycle-profile delta`) and the script caps the verdict at `reloop`: a delta gate may say "not yet, and here is why", never `advance` or `defer`. ADVANCE requires the full instrument (every assessor over a `scope=full` sweep, a backfill's scoped sweep with the full one it builds on included, with automate in the scope "At most one automate pass finishes per gate cycle", under "Backfill the gate evidence", gives a later cycle), so the oracle's finality is untouched, and a delta cycle whose findings all close costs one extra full gate, the confirming cycle a multi-cycle story pays anyway. The fallback is mechanical, not judgment: when any prior finding lacks a clean dimension attribution (which assessor artifact it came from), run the full gate. A re-loop that ended its cycle before trace ("A red backfill sweep ends the cycle at a re-loop") left no trace, NFR or test review artifact to re-check, so the gate after it is always the full gate. Automate is not one of the assessors this choice sorts: in every later cycle, full or delta, it takes the scope that paragraph sets, and for a finding automate reported, that scope's re-run of the gap's mutation rows is the re-run in full of its dimension. Pair the profile with the sweep split: mid-loop cycles ride `scope=scoped` sweeps and delta gates; the advance-bound cycle runs the full sweep and the full gate. (A measured seven-cycle story paid a flat ~20 minutes of full three-assessor gating per cycle regardless of fix size: a nine-minute confirming fix gated at the same cost as a 77-minute one.) Under `--light` the gate is already a single trace read, so the profile buys nothing there; omit it.
**Record who authored the artifacts the verdict rests on.** Alongside that JSON, log one line naming the provenance of this story's `trace-<id>.md` / `gate-decision-<id>.json`: **`gate-provenance: tea`** when `bmad-testarch-trace` wrote them, or **`gate-provenance: hand-authored`** when the non-web section above did. This is not bookkeeping. The module's central non-negotiable is that completion is decided by a script reading TEA's artifact rather than by the model's judgment, and on the hand-authored path the model *writes the file the gate then reads* — a defensible substitution the non-web section sanctions, but one that is otherwise **indistinguishable** in the decision log and the run report from a verdict grounded in a TEA-authored gate. An Epic can run to completion entirely on the hand-authored path, story after story, with nothing anywhere recording that it did. Provenance is what keeps "the JSON is the truth" honest about *whose* JSON it was; it changes no verdict and gates nothing. Beside it, log `assessed-commit: <sha>` — the commit the assessors measured — because the delta cycle profile's re-check computes its diff from the PREVIOUS gate's `assessed-commit` line, and a story whose record lacks one falls back to the full gate.
**Attended runs also print the verdict, once.** In an attended run, immediately after `gate_eval.py` returns and alongside the `.decision-log.md` record above, print **exactly one** transcript line for this story — `story 4-2 — gate_status PASS — verdict advance` — carrying the story id, the `gate_status`, and the routing verdict. The line fires at the moment the verdict is formed, not on the heartbeat cadence: **one line per story, per gate evaluation**, so a watching human sees every story's completion decision without opening a file, and a re-looped story prints its own line for its second evaluation rather than restating the first. Skip this print in headless (`-H`): there the artifacts and `run-result.json` are the interface, and transcript prose has no reader. The line is **additive to the `.decision-log.md` record and never a substitute for it** — the recorded JSON is the completion evidence, a transcript line is not, and a reader who treats the line as the record has lost the `reasons`.
## Route on the verdict
**A logged verdict settles an owed re-gate.** Once this story's verdict is recorded in `.decision-log.md` ("Run the gate" above), and before you take any route below, delete `{workflow.implementation_artifacts}/.regate-<story_id>` if it exists. `/ucg-resolve` wrote it on closing the story's `operator-evidence-owed` escalation, to route a resume to this re-gate (`references/execute.md`'s resume rule), and a logged verdict leaves no re-gate owed. A refusal of the check after a move ("After a move, check that trace scored no moved AC", under "Run the gate") is logged as this cycle's verdict too, so it settles the marker the same way, and `/ucg-resolve` writes a fresh one when it closes the escalation that refusal takes.
- **`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.
**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 or moved one out, its story file, its ATDD checklist and every `oracle=` path its `.moved-<story_id>` lists, when it has that record ("A moved AC leaves the story's list" below), 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, and any `sweep` row this story's sweeps appended (`references/execute.md` step 2) is tracked state no commit of the story carries, since those stage only its source and test paths. 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`, Reading the file first when one is there (step 4's claim check leaves one, as a backfill or an earlier session may) and creating the folder when it is gone, 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, the escalation below is written, or nothing is staged, remove `.scratch-<story_id>/`: this is where `references/execute.md` step 0 has it removed, and the next story's step 0 must not find it. A resume that finds `.scratch-<story_id>/` for a story whose row is already `done` 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. Once that commit is made, by this route or by a resume (the resume after a commit hook's escalation included), or nothing is staged for it, or a resume finds the gate's files committed already, remove `{workflow.implementation_artifacts}/.moved-<story_id>`: the story's committed file and its ledger rows now hold each move. 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.
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.
```
uv run {skill-root}/scripts/gate_eval.py --trace-output {workflow.trace_output_dir} --story <epic_id> --profile production --epic-level --rollup --sprint-status {workflow.implementation_artifacts}/sprint-status.yaml
```
**`--rollup` computes the roll-up; it does not read an epic-named artifact.** The story set comes from `sprint-status.yaml` — the authority on what the Epic owes, never a typed list a story could quietly fall off — and the aggregate is the WORST per-story `gate_status`, fail-closed on five refusals, each `NOT_EVALUATED` → `escalate`: an unreadable sprint-status; an epic with no stories in it; any story not `done` (the roll-up's own trigger is every-story-done, so running it early is refused rather than answered); a multi-story epic whose trace dir is not per-story-named (one shared artifact cannot decide N stories); and any `done` story with no resolvable gate artifact of its own — Stage 1's `done-without-gate-artifacts` audit made binding at the one gate that certifies the Epic. The sprint-status key is the resolution identity, byte-identical to the artifact `<id>` exactly as the `--story` rule above pins it — a renamed or slugged mismatch fail-closes, and the remedy is naming, never slug tolerance. Omit `--rollup` and the invocation reads the epic's own `trace-<epic>` artifact exactly as before; prefer `--rollup` wherever sprint-status is available, because the epic summary then rests on a computation over the per-story record instead of on prose nobody re-checks. **The partial-by-design exception below binds `--rollup` unchanged**: a deliberately partial Epic authors no epic-level gate and runs no roll-up — and one run anyway is answered by the not-`done` refusal, never by a PASS over a subset.
**A decomposed parent is read through its children, on its split record.** `references/execute.md`'s decomposition conventions set a split story's row `done` and move its contract into child rows, so nothing ever drives or gates the parent, and refusing it would escalate every Epic that was ever split. The split is recorded mechanically: the `scripts/story_sizing.py` run that reconciles the claim map, given `--parent` and `--record`, writes `.split-<parent key>.json` beside `sprint-status.yaml`, naming the parent and its children by their sprint-status keys. Execute's decomposition step writes it for every split it makes, preflight's remediation pass writes it for every split of a parent with a row that it finds recorded only by a child row's AC citation or the decision log (`references/preflight.md`), and `/ucg-formalize` writes it for each such split its own remediation repairs. The roll-up reads a `done` row with no resolvable gate through its children only on that record: a file named for the row's key, byte for byte, beside `--sprint-status`, that names the row as its parent and names children each of which is another story row of this Epic. It leaves the row out of the aggregate, its children's gates count in its place, and a reason line names it with them. Nothing else is evidence of a split: a reading of the row's id, its place or which story files exist waived a never-gated row's gate under some placement or file name, so none of them is read. A row whose own gate resolves is read on that gate like any story, record or not. A decomposed parent with no record, such as one split before the record existed, still refuses the roll-up; when rows above it extend its id and it has no gate artifact of its own, a reason line says so and points at the way out, one `story_sizing.py` run for that split with `--parent` and `--record`, then the gate again. Four records are not read, each with a reason line, and their parents refuse like any story with no resolvable gate: one that is not a JSON object naming the row as its parent and a list of children; one that names a child that is not another story row of this Epic; one whose chain of children, through other records read the same way, leads back to its own parent, since records that name each other would otherwise leave every row in the cycle out and compute a PASS over no gate; and the record of a parent with a gate artifact of its own, which must then resolve. A gate artifact of its own is one `--story <parent key>` would read, by the naming rule above: a trace report named for its key that declares itself one, its gate decision or its per-story trace summary. Its story file, its ATDD checklist (Define-Done writes both before Execute sizes the row), notes, and a gate filed under another name are not.
**Declare the omission; do not imply it.** `--epic-level` is what makes the skipped ANDs correct rather than the signal-dropping the per-story gate forbids in "Run the gate". The two used to be the same input — leaving the flags off — so a forgotten flag on a story gate was indistinguishable from a legitimate epic roll-up, and the story gate silently advanced on a signal nobody read. Without the flag, `--profile production` now treats an absent `--nfr`/`--test-review` as failing. Passing an epic-level `--test-review`/`--nfr` path that no aggregate writes is the mirror mistake, and the script now refuses the combination outright rather than evaluating it: it is an **invocation error, not a gate verdict** — argparse prints a usage line naming `--epic-level` and exits `2`, computing no verdict at all (the same lane a missing `--story` occupies in `references/finalize.md`). So there is no `reloop` to route on and no gate artifact to re-read: fix it by re-issuing the command without the paths. Under `--profile light` the flag is a no-op, since that profile runs no ANDs at all. Then proceed to Stage 6 (`references/finalize.md`). **Partial-by-design exception:** if this run delivered only a deliberate *strict subset* of the Epic's stories (in-scope ⊊ Epic — e.g. a conditional / evidence-gated Epic where the operator scoped a subset; this is distinct from ingest-and-scope.md's already-`done`-skipping, which still ends with every story `done`) — do **not** author an Epic-level gate: a PASS would misrepresent an incomplete Epic as complete. Record the per-story advance(s) and proceed to Stage 6 with the Epic left in its partial / conditional state (the `partial-complete` terminal outcome — see `references/finalize.md`).
- **`defer`** (gate_status CONCERNS, or non-critical code-review / NFR findings that did not flip the gate) → append the open items to the ledger at `{workflow.deferred_work_path}` using the schema below, then **advance** anyway. The Epic keeps moving; the parked work is visible. **On `advance` or `defer`, an operator-evidence AC still owed its evidence is parked too**: an uncovered P2 or P3 criterion may leave the gate at PASS or CONCERNS, so the story can move without it. It still counts toward TEA's overall coverage, so it can also FAIL the gate, and a FAIL goes to `operator_owed.py` (the next bullet), never to this ledger. It is owed while its live results file holds no `pass` record for it at the commit the gate measured, or while TEA holds it below FULL with only the records it counted there; append a row with `source` `gate` naming the AC, the evidence it owes (for a partly recorded AC, the ids of the records TEA counted and the part still owed) and that file.
- **A FAIL only operator evidence can change is not a re-loop.** On every gate_status FAIL, first run the command below (for a decomposed child, `--story-file` is its parent's story file). Under `--light`, pass `--profile light` and no `--nfr` or `--test-review`; in either profile, pass `--cycle-profile` exactly as the gate took it. On `owed: true`, take `escalate` with `kind` `operator-evidence-owed`: `source` is the trace report's path, `decision_needed` names the ACs in `operator`, what each owes, `assessed_commit`, the live results file to record into, and that `/ucg-resolve` closes it once the records are there, once the operator narrows the AC in writing, or once the story file carries the operator's written move of the AC out of the story ("A moved AC leaves the story's list" below), and `evidence` is TEA's gap line for the first of those ACs. Write no `class:` line, run no `bmad-correct-course`, spend no re-loop, and commit nothing after the assessed commit, since a later commit makes the record stale. Attended, the operator may record it now, or move the AC in that form, which you record as the `/ucg-resolve` close would, logging their in-session ruling as a named Operator notes entry in `.decision-log.md` and citing it as `Operator notes <entry>`: the form on disk before the re-gate, the owner as an owned line names one, the AC's open `gate-gap:` lines logged again as owned, and the `.moved-<story_id>` record; then re-gate the same commit in-session. For a decomposed child's AC, record `defer`, propose the re-plan and stop there, re-gating nothing. Otherwise `/ucg-resolve` closes it with the records on disk, or with the move in the story file and its `.moved-<story_id>` record, and writes `.regate-<story_id>`, and the resume re-gates that commit rather than re-driving the story (`references/execute.md`'s resume rule). An open operator-evidence AC that already holds a `pass` record TEA counted at the assessed commit is still owed: TEA held it below FULL because the record covers only part of the criterion, and no re-loop can record the rest or narrow the AC, so the script lists it in `operator` and in `partial`, which maps it to the ids of the records TEA counted. For each AC in `partial`, `decision_needed` names the record ids TEA already counted, says they cover only part of the criterion, and asks the operator to record the rest or to narrow or move the AC in writing. On `evaluated: false`, the story file tags an operator-evidence AC but the script could not read trace's coverage matrix (there is no trace report, or it names no absolute `tempCoverageMatrixPath`, the file it names is gone or unreadable, or the matrix or the summary is not this gate's, names no commit or measured another one), so it cannot tell evidence still owed from work a re-loop can build, and `owed` is `false` only because nothing was read. Two such FAILs keep the `reloop` route below, as they did before the script could tell them apart: one in the hand-authored trace files ("Non-web stack" above), logged `gate-provenance: hand-authored`, which hold no coverage matrix by design, and a decomposed child's when no parent AC its sprint-status row claims carries that tag, since a sibling's tag owes it nothing. Otherwise take `escalate` with `kind` `operator-evidence-owed`. Before you write its sidecar, move whichever of the story's `trace-<story_id>.md`, `gate-decision-<story_id>.json` and `e2e-trace-summary-<story_id>.json` exist aside, all in one step, as "After a move, check that trace scored no moved AC" (under "Run the gate") moves them before trace, so the re-gate its close owes runs trace again and never reads this cycle's report; once `/ucg-resolve` closes it, a resume that finds them moved aside routes `gate-owed` as that paragraph says. `source` is the trace report's path as moved aside (with no report, the gate decision's, or else the summary's), `evidence` is the script's last reason, which says why the matrix could not be read, and `decision_needed` opens with "The operator-evidence check could not read trace's coverage matrix", then names this run's id, its number among this story's escalations with that opening (one past the ones the decision log already records), the commit under assessment as the assessed commit, in full as `git rev-parse` prints it, why the matrix could not be read, whether one of this story at this commit came before, and what the close waits on: nothing for the first at that commit, whose re-gate runs trace again, and for a later one the operator's written word that trace can leave a coverage matrix the check can read there. `/ucg-resolve` keys its close on that opening phrase. Log the script's JSON and the `decision_needed` you write, since the next such escalation takes its number, and whether one came before at this commit, from the log. Write no `class:` line, run no `bmad-correct-course`, spend no re-loop, since what kept the check from the matrix is the files trace left, which no build work changes, and commit nothing after the assessed commit, since the re-gate its close owes measures that commit. On `evaluated: true` and `owed: false`, the `reloop` route below stands; log the script's `reasons`.
```
uv run {skill-root}/scripts/operator_owed.py --trace-output {workflow.trace_output_dir} --story <story_id> --story-file <story file> --profile production --nfr {nfr-assessment.md} --test-review {test-review.md} --tests-ran {workflow.implementation_artifacts}/.tests-ran-<story_id>
```
**A moved AC leaves the story's list.** A written operator ruling can move an AC out of the story, to another story or to a row of the deferred-work ledger, and the story file then carries the move in this form and no other. The AC's numbered item leaves `## Acceptance Criteria`, and a note under an H2 heading of its own after that section, one that does not say "acceptance criteria", names the retired number, the owner, as an owned `gate-gap:` line names one (a story of this Epic not yet `done`, or else a ledger row as `"<Epic heading> <ledger id>"`), and the ruling (`Operator notes <entry>` or `decision <id>`, with `<id>` its `.decisions.json` id). The note starts with no `<n>.` and holds no `**Gate-ability:**` text: the parsers that read the section fold an unnumbered line into the AC above it and read a tag there as that AC's, so a note left in the list, or one that quotes a tag, changes another AC. The number is retired: no other AC is renumbered and no later AC takes it (`references/define-done.md`, step 1), since live records key on `AC-<n>`. The AC also leaves the `acceptanceCriteria` list of the story's ATDD checklist; it had no scaffold, so no test moves. These edits are the operator's own, or yours at their written direction, and no commit carries them before the re-gate, since nothing may land after the assessed commit: the commit that carries the gate's files once the story advances stages them ("Commit the gate's evidence before the next story starts", above). Whoever applies this form, for any written ruling (the `/ucg-resolve` close, you at the operator's written direction in an attended run, or you for an Operator notes entry or an answer to another escalation that the re-read at each cycle's start finds), writes `{workflow.implementation_artifacts}/.moved-<story_id>`, one line per moved AC opened by its `AC-<n>`, `AC-<n> to <owner> per <ruling>`, adding to any lines already there, and logs a `moved:` line in `.decision-log.md` that records the move for a reader and that no step reads. The record also takes an `oracle=<absolute path>` line for each oracle source the operator edited, with the move or after a refusal of the check: a relative one is resolved against `{project-root}`, and only a path inside the work tree `git rev-parse --show-toplevel` prints is recorded. Every later gate cycle of the story, the commit that carries the gate's files and a resume read the moved set from the `AC-<n>` that opens each line that is not an `oracle=` line, and the sources from the `oracle=` lines, of this record alone. A written return of a moved AC to the story is applied by the `/ucg-resolve` close, or by you at the operator's written direction in an attended run: it deletes the AC's line from the record, and the record once no AC line is left, so no check runs then; puts the numbered item back under its old number; takes its entry out of the H2 note; restores it to the checklist's `acceptanceCriteria`; and logs its open `gate-gap:` lines again without the `owned-by` marker. The advance route removes the record once the commit that carries the gate's files is made ("Commit the gate's evidence before the next story starts", above). Whoever records the move also logs each open `gate-gap:` line on the moved AC again with `owned-by` the same owner per the same ruling ("An owned `gate-gap:` line is not this story's to close", under "Backfill the gate evidence"), so automate leaves it alone. On `advance` or `defer`, append one ledger row per moved AC, with `source` `gate`, `severity` `med`, `story` this story, a `reason` naming the AC, its owner, the ruling and each owned `gate-gap:` line on it, which then writes no row of its own, and a `suggested_action` naming the owner, written once, as an owned line's row is. A decomposed child's AC is not moved in this form: it lives in its parent's story file, which is never edited and which every sibling reads, so retiring it there would retire it for each of them; `/ucg-resolve` records `defer` for such a move and proposes a re-plan of the split instead. WAIVED is no route for a moved AC: TEA keeps a waived criterion in every count, and the AC is no longer this story's. Every gate cycle of a story with that record names the main-tree story file and its sources to trace and checks trace's matrix before `gate_eval.py` runs ("After a move, check that trace scored no moved AC", under "Run the gate"), so an AC the operator moved never reaches the `reloop` route.
- **`reloop`** (gate_status FAIL, or a production signal downgraded an advance, or a sweep-scope or delta-profile cap) → **generalize before fixing.** Before `bmad-correct-course` writes any fix, take the verdict's `reasons` and the review's findings and, for each finding: (1) name, in ONE line, the defect CLASS the finding is an instance of; (2) state whether any earlier review of this story or this Epic already found that class: the previous gate artifacts and `{workflow.implementation_artifacts}/.class-ledger-<epic_id>.md` are the evidence, and they are already on disk, so this is a read, not a judgment call; (3) where the class is a repeat, the fix must close the CLASS (every sibling instance the same seam admits, not the one instance the reviewer demonstrated), and the log records why the class-level fix was not taken when the class was first named. A measured run spent five of six reviews re-finding one class ("an assertion that cannot go red") one seam over each time, with the class-killing move available from day one; the generalize step is what makes cycle N read cycle N-1 instead of re-buying it. Record one `class:` line per finding in this re-loop's `.decision-log.md` entry, and append any class not already present to `.class-ledger-<epic_id>.md` (create on first use; named for the Epic, so a later Epic starts a fresh ledger while this Epic's survives across its own invocations for exactly the resume case; one line per class, `- <class, one line> (first named <story_id>, cycle <n>)`; **append-only**: Execute step 1 reads it before every story and re-loop, so a class named once is warned about everywhere after, including across stories, which no per-story artifact can do). **A score that does not move indicts the FIX STRATEGY, not the code:** when two consecutive gate evaluations of this story have moved `review_score` by less than 3 (production; under `--light` no review score exists, so the trigger there is two consecutive re-loops whose findings name any class already in the ledger), the generalize answers above are mandatory *in writing* before any further fix: a re-loop whose findings all name the same class as the previous re-loop's is a re-loop about to be spent badly. **A cap-only re-loop skips the ceremony.** When a cap alone produced the verdict (the `reasons` show only the sweep-scope cap, the delta-profile cap, or both, with no gate FAIL and no failed production signal), there is no finding to generalize and nothing to diagnose: re-run the full three-axis sweep where the sweep cap fired and refresh the marker with `scope=full`, then re-run the gate as the FULL instrument (**dropping `--cycle-profile`**, because the delta cap is lifted by the flag's absence and a re-gate that keeps it caps again forever), writing no `class:` lines, appending nothing to `.class-ledger-<epic_id>.md` and no row to `{workflow.deferred_work_path}` save the `sweep` row its re-sweep owes for a red the story's changes do not explain (`references/execute.md` step 2), and skipping `bmad-correct-course` entirely; such evaluations do not count toward the flat-score tripwire, and a capped CONCERNS keeps its findings for the next gate's own `defer` route: parking them is that gate's job, not this re-loop's. A cap-only re-gate re-measures without re-driving the story, so the turn-ceiling rule below never turns it into `escalate`. Otherwise, run `bmad-correct-course` to diagnose and adjust, then re-run the story (back through Execute, `references/execute.md`), **within the remaining turn budget**. Re-run the gate after. If the re-loop would exceed `{workflow.max_turns_per_story}`, treat it as `escalate` instead; the count is the `turns` value the Stop hook records in `{workflow.implementation_artifacts}/.budget-<story_id>.json`. When the hook left a turn-budget marker for this story, that escalation's sidecar is the marker's promotion (`references/execute.md`, "Promoting the turn-budget marker").
**A red backfill sweep and the `gate-gap:` lines take this route their own way.** A re-loop that ended its cycle before trace ("A red backfill sweep ends the cycle at a re-loop", under "Backfill the gate evidence") takes the full route above, with its red and every open `gate-gap:` line of its cycle that is neither `unmeasured`, `unkilled` nor owned as its findings, and the gate after it is a full one. On a `reloop` from `gate_eval.py` that is not cap-only, each open `gate-gap:` line that is neither `unmeasured`, `unkilled` nor owned is among the findings the generalize step reads, though none of them is a reason for the verdict. An open `gate-gap:` line in a cycle whose re-loop is cap-only is not one of that re-loop's findings, so it gets no `class:` line and no ledger row here: like a capped CONCERNS's findings, it goes to the next gate, by its `gate-gap:` line ("A reported gap stays open until a later pass measures it closed", under the same section). No `gate-gap:` line, on any criterion, sends a story to this route: only the verdict or a red backfill sweep does.
- **`escalate`** (gate_status NOT_EVALUATED, meaning the gate could not be read; a FAIL whose operator-evidence check could not read trace's coverage matrix, `evaluated: false` above; budget exhausted on a FAIL; a FAIL only operator evidence can change, above; or any gate cycle of a story with a `.moved-<story_id>` record whose check exits 1 or 2, under "Run the gate") → **stop.** Do not advance, do not defer the failing item. Record the reason and the verdict JSON in `.decision-log.md`, and write the typed escalation sidecar `{workflow.implementation_artifacts}/escalation-<story_id>.json` (shape in `references/execute.md`, under "Escalation sidecar") so the pending decision is readable without the transcript. In an attended run, surface the blocker to the user. In headless, this is a `blocked` outcome: emit the JSON in Stage 6 (`references/finalize.md`).
**INVARIANT: a P0/critical FAIL never defers.** A failing gate (or a P0/P1/overall threshold miss) is `reloop` or `escalate`, never `defer`. Only non-gate-blocking work (CONCERNS, non-critical findings, parked decisions, and the rows open `gate-gap:` lines become) is allowed onto the ledger. If you find yourself about to write a FAIL or a critical finding to the ledger, you are violating the gate: re-loop within budget or escalate instead. A row from a `gate-gap:` line is neither a FAIL nor a critical finding, whatever its criterion's priority, so it belongs on the ledger and never re-loops or escalates the story.
An open `gate-gap:` line is neither a FAIL nor a critical finding, whatever its criterion's priority, so the ledger row it becomes on `advance` or `defer` keeps this rule ("A reported gap stays open until a later pass measures it closed", under "Backfill the gate evidence", says why). A gap automate finds on a P0 criterion is backfilled rather than parked ("Automate backfills every gap it finds on a P0 criterion", under the same section), and `gate_eval.py` decides on the test, so a `gate-gap:` line on a P0 criterion is only ever a risk or a gap nobody has measured yet, a backfilled test that was never written, a backfilled test that did not kill its mutant, or a risk or a gap a written ruling assigned to another owner ("An owned `gate-gap:` line is not this story's to close", under the same section).
If any orchestrated sub-skill blocks on interactive input mid-run, treat it as `escalate` for that story — write the typed escalation sidecar `{workflow.implementation_artifacts}/escalation-<story_id>.json` and stop; do not answer its prompt blind.
## Deferred-work ledger schema
Append to `{workflow.deferred_work_path}` (create on first use). One heading per Epic, then a row per parked item; `status` is `open` at write time:
```markdown
# Deferred Work — <epic>
| id | source | severity | story | reason | suggested_action | status |
|----|--------|----------|-------|--------|------------------|--------|
| d1 | gate | low | <story-id> | <why parked> | <what to do later> | open |
```
- `source` ∈ `gate` (CONCERNS, an operator-evidence AC's evidence still owed, an AC the operator moved out of the story, or an open `gate-gap:` line: a coverage gap automate reported rather than backfilled, a risk on a P0 criterion it left unmeasured, a gap whose rows could not run, the behaviour under a gap whose rows only a test that reads source text killed, a backfilled test that was never written, a backfilled test that did not kill its mutant, or a risk or a gap a written ruling assigned to another owner), `code-review` (non-critical finding), `nfr` (non-FAIL finding), `decision` (parked decision), `sweep` (a non-critical finding: a case outside the story's changes that went red in one sweep and green in the next at the same tree, `references/execute.md` step 2).
- `severity` ∈ `low`, `med`, `high`. A `high` that maps to a gate FAIL or a P0/critical finding does **not** belong here: re-loop or escalate it. A row from an open `gate-gap:` line is always `med`: whatever its criterion's priority, it is neither a gate FAIL nor a P0/critical finding, so it belongs here and never re-loops or escalates the story.
- `id` is unique within the Epic heading (append `d2`, `d3`, … ). Note that the id is unique only WITHIN its heading, so `d1` under two Epics is two different decisions; a project-wide reader must key them by more than the raw column (`/ucg-resolve` mints an id for exactly this reason).
- `status` ∈ `open`, `resolved`. **This gate only ever appends rows, and never rewrites one** — but the column is not frozen forever: `/ucg-resolve` flips `open` to `resolved` when an operator closes a parked decision, and that single transition is the one sanctioned edit to an existing row. Everything else about a row is immutable once written: never restate its `id`, `source`, `severity`, `story`, `reason` or `suggested_action`, because the ledger is the durable account of what was parked and rewriting it loses the history the Epic close-out reads.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |