bmad-module-ultracode-goal 7.2.0 → 7.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -19,7 +19,7 @@
19
19
  "name": "bmad-module-ultracode-goal",
20
20
  "source": "./",
21
21
  "description": "Supercharges BMAD with Claude Code's Auto Mode, Auto Memory, and hooks: autonomous Epic execution to a machine-checked, TEA-gated Definition-of-Done. Execute Epics. Accumulate Knowledge. Deliver Outcomes.",
22
- "version": "7.2.0",
22
+ "version": "7.3.0",
23
23
  "author": {
24
24
  "name": "Armel"
25
25
  },
@@ -20,7 +20,7 @@ The installer CLI is invoked via `npx bmad-module-ultracode-goal <subcommand>`.
20
20
 
21
21
  ### The `[workflow]` customize.toml keys
22
22
 
23
- The keys in the shipped `[workflow]` block of `customize.toml` (including `persistent_facts`, `tea_config_path`, `trace_output_dir`, `implementation_artifacts`, `deferred_work_path`, `epic_branch_prefix`, `protected_branches`, `max_turns_per_story`, `story_token_budget` (**deprecated, no-op**), `parallel_max_concurrency` (**deprecated, no-op**), `allowlist_commands`, `on_epic_complete`, `on_escalation`, `cross_session_recall`, `cross_session_recall_store`, and `graphify_integration`) are the supported override surface. Teams and users override them in `_bmad/custom/ultracode-goal.toml` (and `.user.toml`) with base → team → user resolution (scalars override, tables deep-merge, arrays append). Renaming or removing a key, or changing how it resolves, is a contract change. See [architecture](../architecture.md).
23
+ The keys in the shipped `[workflow]` block of `customize.toml` (including `persistent_facts`, `tea_config_path`, `trace_output_dir`, `implementation_artifacts`, `deferred_work_path`, `epic_branch_prefix`, `protected_branches`, `max_turns_per_story`, `story_token_budget` (**deprecated, no-op**), `parallel_max_concurrency` (**deprecated, no-op**), `allowlist_commands`, `backfill_sweep`, `on_epic_complete`, `on_escalation`, `cross_session_recall`, `cross_session_recall_store`, and `graphify_integration`) are the supported override surface. Teams and users override them in `_bmad/custom/ultracode-goal.toml` (and `.user.toml`) with base → team → user resolution (scalars override, tables deep-merge, arrays append). Renaming or removing a key, or changing how it resolves, is a contract change. See [architecture](../architecture.md).
24
24
 
25
25
  `story_token_budget` is **deprecated** as of the deprecation note in `CHANGELOG.md`: it is still shipped, still accepted, and still resolves, so existing overrides keep working and nothing errors. It is a no-op; no layer reads it any more. The runaway bound is turns only, via `max_turns_per_story`. The key stays enumerated here (and stays in `customize.toml`) precisely because removing it would be the contract break this section forbids.
26
26
 
@@ -61,6 +61,7 @@ skills/ultracode-goal/
61
61
  │ ├── mutate_check.py # mutation harness: attributable-red proof for the story's guards
62
62
  │ ├── probe_servers.py # which URLs a test runner may reuse already answer, from which folder; stops a server the run left up
63
63
  │ ├── link_worktree_deps.py # links the main tree's dependency folders into the gate worktree
64
+ │ ├── carry_build_cache.py # carries the gate worktree's build folders aside across its rebuild
64
65
  │ ├── gate_trail.py # per-story evidence trail (gate-trail.md) at finalize
65
66
  │ ├── formalize_check.py # readiness kernel behind the /ucg-formalize gate
66
67
  │ ├── status_render.py # read-side render behind /ucg-status
@@ -109,7 +110,7 @@ Configuration resolves in three layers, base → team → user, via `resolve_cus
109
110
 
110
111
  Neither override file is created by any installer, and a missing one is not an error: the resolver loads it non-required and treats absence as an empty table, so a fresh project resolves the base layer alone. You create them when you first need to override something. Do not mistake them for the `config.toml` and `config.user.toml` already sitting in that directory: those are BMAD's own configuration, and a UCG knob written there resolves to nothing.
111
112
 
112
- Merge semantics: **scalars override**, **tables deep-merge**, **arrays append**. At activation the skill runs `resolve_customization.py --skill {skill-root} --key workflow`; if that fails, it resolves the three files itself in the same order. The shipped base layer defines the run's knobs: the TEA/artifact paths (`tea_config_path`, `trace_output_dir`, `implementation_artifacts`, `deferred_work_path`), the git guardrails (`epic_branch_prefix`, `protected_branches`), the turn budget (`max_turns_per_story`; `story_token_budget` remains as a deprecated no-op key), `parallel_max_concurrency` (deprecated no-op since the `--parallel` retirement), the `allowlist_commands`, the two lifecycle hooks (`on_epic_complete`, `on_escalation`), the [health check](./health-check.md) family (`health_check_repo`, `health_check_seen_cache`, `health_check_queue_path`, `health_check_autosubmit`), and the two optional integrations, both off by default: [`cross_session_recall`](./cross-session-recall.md) with its store folder `cross_session_recall_store`, and the third-party [`graphify_integration`](./knowledge-graph-refresh.md). Teams and users override without editing the shipped file. Remember that a budget or branch override only reaches the *enforcement* layer because preflight threads it into the hook env (see layer 2 above).
113
+ Merge semantics: **scalars override**, **tables deep-merge**, **arrays append**. At activation the skill runs `resolve_customization.py --skill {skill-root} --key workflow`; if that fails, it resolves the three files itself in the same order. The shipped base layer defines the run's knobs: the TEA/artifact paths (`tea_config_path`, `trace_output_dir`, `implementation_artifacts`, `deferred_work_path`), the git guardrails (`epic_branch_prefix`, `protected_branches`), the turn budget (`max_turns_per_story`; `story_token_budget` remains as a deprecated no-op key), `parallel_max_concurrency` (deprecated no-op since the `--parallel` retirement), the `allowlist_commands`, the opt-in `backfill_sweep` (the gate's sweep before it commits a backfilled test, `full` by default), the two lifecycle hooks (`on_epic_complete`, `on_escalation`), the [health check](./health-check.md) family (`health_check_repo`, `health_check_seen_cache`, `health_check_queue_path`, `health_check_autosubmit`), and the two optional integrations, both off by default: [`cross_session_recall`](./cross-session-recall.md) with its store folder `cross_session_recall_store`, and the third-party [`graphify_integration`](./knowledge-graph-refresh.md). Teams and users override without editing the shipped file. Remember that a budget or branch override only reaches the *enforcement* layer because preflight threads it into the hook env (see layer 2 above).
113
114
 
114
115
  The three TOML layers merge once, but a branch or budget value then travels two ways: the conductor reads it directly, while the hooks only see it if preflight re-injects it as env:
115
116
 
@@ -94,6 +94,8 @@ Under `--profile light` none of this applies: the trace gate is the whole decisi
94
94
 
95
95
  Independent of profile, a per-story gate is also handed the story's `.tests-ran-<story_id>` marker via `--tests-ran`. Execute writes a `scope=<full|scoped>` line into that marker beside `baseline=`, naming which sweep form the green run behind this gate was: the full three-axis sweep, or a re-loop iteration's affected-set sweep (changed packages plus their dependents, still cache-defeated, with the resolved package list printed and recorded on a `packages=` line). The script reads the line and applies one rule: **a story only moves forward off a full-scope sweep.** `scope=full` passes the verdict through; `scope=scoped` caps `advance` at `reloop`, and caps `defer` too, because defer's route advances the story after parking its concerns. A missing marker, a marker with no `scope=` line, or an unrecognised value gets the same cap, fail-closed, with a reason naming what was wrong.
96
96
 
97
+ The gate writes the marker too, when it commits a test `bmad-testarch-automate` backfilled, always with `scope=full`. By default its sweep before that commit is the full three-axis sweep. With the opt-in `backfill_sweep = "scoped"` in `customize.toml`, a backfill that stages test files alone, on a story whose full step-5 sweep went green at the commit the backfill builds on, re-runs only the checks of the packages that hold those files and every check that reads files across packages or git's file list, unless that check's own declared inputs exclude every staged path, and prints each check it leaves out. Its marker then keeps `scope=full` beside a `sweep=` line naming the two green captures it rests on, which the script does not read, and one scoped sweep never builds on another.
98
+
97
99
  Two boundaries:
98
100
 
99
101
  - `--epic-level` refuses `--tests-ran` outright (an invocation error, exit 2): the epic roll-up gates no sweep of its own, since every story proved its own scope before reaching `done`.
@@ -103,7 +105,7 @@ The verdict JSON carries the recognised value as `sweep_scope` (or `null`), so a
103
105
 
104
106
  ## The delta cycle profile
105
107
 
106
- A mid-loop re-gate may declare `--cycle-profile delta`: only the assessor dimension(s) whose findings produced the previous reloop re-run in full, while the other assessors re-check their prior artifact against the diff since the commit they assessed. The script caps a delta gate's verdict at `reloop` (defer too, for the sweep-cap reason): a delta gate can say "not yet, and here is why", never move the story. Advancing requires the full instrument, every assessor over a `scope=full` sweep, so the oracle's finality is untouched and a wrong guess costs one extra full gate rather than an unearned advance. The fallback is mechanical: any prior finding without a clean dimension attribution means the full gate runs. `bmad-testarch-automate` sits outside this choice: after a story's first gate cycle, full or delta, it searches only the diff since the previous gate and re-runs the mutation rows behind the gaps that gate backfilled and behind every gap still open, and the full instrument runs it at that scope too. It backfills every gap it finds on a P0 criterion, in any cycle, so trace counts the new test and the script decides; only a gap on another criterion is reported instead, when it lies outside that scope or while operator live results sit at the commit under assessment. A reported gap stays open until a pass at a later commit finds its mutants killed, and it never changes the route a verdict takes. Automate confirms each test it backfills in the same pass, with the test copied into the worktree, and a test that leaves its mutant alive (perhaps an equivalent mutant, which no test can kill) is logged as an `unkilled` gap that no later pass writes another test for while that code stands. `--epic-level` refuses the flag (invocation error, exit 2); omitting it is the full behaviour, and the `cycle_profile` JSON key appears exactly when the flag was supplied.
108
+ A mid-loop re-gate may declare `--cycle-profile delta`: only the assessor dimension(s) whose findings produced the previous reloop re-run in full, while the other assessors re-check their prior artifact against the diff since the commit they assessed. The script caps a delta gate's verdict at `reloop` (defer too, for the sweep-cap reason): a delta gate can say "not yet, and here is why", never move the story. Advancing requires the full instrument, every assessor over a `scope=full` sweep, so the oracle's finality is untouched and a wrong guess costs one extra full gate rather than an unearned advance. The fallback is mechanical: any prior finding without a clean dimension attribution means the full gate runs. `bmad-testarch-automate` sits outside this choice: after a story's first gate cycle, full or delta, it searches only the diff since the previous gate and re-runs the mutation rows behind the gaps that gate backfilled and behind every gap still open, and the full instrument runs it at that scope too. It backfills every gap it finds on a P0 criterion, in any cycle, so trace counts the new test and the script decides; only a gap on another criterion is reported instead, when it lies outside that scope or while operator live results sit at the commit under assessment. A reported gap stays open until a pass at a later commit finds its mutants killed, and it never changes the route a verdict takes. Automate confirms each test it backfills in the same pass, with the test copied into the worktree, and a test that leaves its mutant alive (perhaps an equivalent mutant, which no test can kill) is logged as an `unkilled` gap that no later pass writes another test for while that code stands. A test that reads the code's source text instead of executing it, where no test runner can execute that code, measures only its spelling: the behaviour stays an `unmeasured` gap naming the test and what could execute the code, and no test that reads source text closes it. `--epic-level` refuses the flag (invocation error, exit 2); omitting it is the full behaviour, and the `cycle_profile` JSON key appears exactly when the flag was supplied.
107
109
 
108
110
  ## The thresholds
109
111
 
@@ -177,4 +177,8 @@ Each of these was hit while verifying real work, and each one first looked like
177
177
 
178
178
  **Stop a dev server before an unattended drive.** A test runner that reuses a server already answering at its URL, as Playwright does with `reuseExistingServer` (which TEA's framework scaffold turns on outside CI), attaches the gate's runs in its measurement worktree to the dev server you left running from your own checkout. Those browser runs then exercise your checkout's source, not the commit under assessment, and a mutation the gate writes into the worktree never reaches them. The gate checks the URLs a runner config may reuse and never stops a server unless it reads as one the run itself left up (below): it gives the worktree's runs their own server on a free port when a scratch runner config can, whether or not one answers, and otherwise tells every assessor the limit, so a risk that only a browser run could measure goes unmeasured. Observed: a gate's worktree runs attached to a vite dev server listening on `[::1]:3001` that had been started from the main tree, and automate left the source mutation behind one acceptance criterion unrun, since no run from the worktree could reach it. With the dev server stopped, the runner starts its own from the worktree, but a server it starts through a launcher such as turbo, which runs it in a process group of its own, outlives the run that started it, and with reuse on the runs after it reuse it, serving the files as they were when it started: the gate turns reuse off through its scratch config where it can, and otherwise reads a mutation row run through such a server as one that cannot run. A start command in your runner config that runs the server itself (the package's own dev script rather than turbo's) keeps it from outliving the run. On Linux the gate stops a server the run itself left up, such as one the sweep right before the gate started through turbo, at each of its checks and once more when the story's gate ends, so those servers do not pile up over an Epic, and the decision log names each one it stopped. It stops one only when every process of it is yours, has no controlling terminal and started after the current story's baseline marker was written, the process that started its session has exited, nothing else that still runs in that session started before the marker or is the parent of one of its processes (a watcher or supervisor that can start it again), and it runs from your project or the gate's worktree. A server of yours can meet all of that: one inside the project and on a port the gate checks, started in the background by a command that has since exited (a script's, or another agent session's) or from a terminal you then close (a `nohup ... &`), with nothing that began before the story still running in its session, reads as the run's and is stopped. So does one that a watcher of yours starts again after the story began, when the watcher too began after the story and runs in the server's process group, or starts the server through a command that then exits and either began after the story or had that command give the server a session of its own. That marker is written when the story starts, and the resume of a stopped or blocked run keeps it, so such a server you start between a run and its resume is stopped too. So stop it before you start or resume a drive, as this tip says, or start it outside the project, on another port or from a terminal you keep open.
179
179
 
180
+ **Expect one cold Cargo build per gated story, not two.** The production gate replaces its measurement worktree once automate has finished, and `git worktree remove --force` deletes every ignored folder with it. The gate carries the worktree's Cargo build folders (`target`, `src-tauri/target`) out before that removal and back after the new worktree is added, and does the same across a `reloop`, so only the story's first gate setup builds from nothing. After an `escalate`, `advance` or `defer` verdict it carries nothing, and an escalation deletes what it had carried, so a re-gate after an escalation builds cold again. The decision log's honesty line names each folder it carried, skipped or could not move.
181
+
182
+ **Turn on `backfill_sweep = "scoped"` when a backfill's full sweep costs you more than it tells you.** When the gate commits a test `bmad-testarch-automate` backfilled, it runs the full three-axis sweep first, which on a large monorepo can take longer than the story did. With the key set to `scoped` in your team or user `customize.toml` layer, a backfill that stages test files alone re-runs only the checks those files can change, and trusts Execute's step 5 for the rest: the green capture step 5 left in `evidence-<story_id>/` as `sweep-step5-<short sha>.log` at the commit the backfill builds on. Set the key before the story's Execute runs: a step 5 that ran with it unset saved no such capture, and the gate then runs the full sweep.
183
+
180
184
  **Pin the parallelism of the verification suite if it is timing-sensitive.** Observed: a full-concurrency test run was flaky two green in five, because one unrelated gate crept past a 10-second default timeout under contention while taking 1.7 seconds alone. Pinning the runner to one worker (`ava --concurrency=1`; your runner's own name for it will differ) was green every time. A flaky verification tier makes every story's evidence unreliable, which is worse than a slow one.
@@ -65,7 +65,7 @@ Note this is fail-closed on purpose: a missing or unreadable gate artifact escal
65
65
 
66
66
  ## Gate re-loops on a sweep-scope or delta cap
67
67
 
68
- A per-story gate can return `reloop` with a `PASS` gate status when a cap fired rather than a finding: the `reasons` name either the sweep-scope cap (the `.tests-ran` marker says `scope=scoped`, or the marker/`scope=` line is missing) or the delta-profile cap (`--cycle-profile delta` was declared). Neither is an error; both mean "not yet, and here is why": a story only advances off a full-scope sweep judged by the full gate instrument. The remedy is the cap-only re-loop, which skips the generalize ceremony entirely: re-run the full three-axis sweep, refresh the marker with `scope=full`, and re-run the gate without `--cycle-profile`. See the cap sections in the [gate model](./gate-model.md).
68
+ A per-story gate can return `reloop` with a `PASS` gate status when a cap fired rather than a finding: the `reasons` name either the sweep-scope cap (the `.tests-ran` marker says `scope=scoped`, or the marker/`scope=` line is missing) or the delta-profile cap (`--cycle-profile delta` was declared). Neither is an error; both mean "not yet, and here is why": a story only advances off a full-scope sweep judged by the full gate instrument. The remedy is the cap-only re-loop, which skips the generalize ceremony entirely: re-run the full three-axis sweep, refresh the marker with `scope=full`, and re-run the gate without `--cycle-profile`. A marker that carries a `sweep=` line beside `scope=full` is no cause: the gate wrote it after a scoped backfill sweep (`backfill_sweep = "scoped"`), and the script reads only its `scope=` line. See the cap sections in the [gate model](./gate-model.md).
69
69
 
70
70
  ## The gate stopped a server, or left one up
71
71
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://json.schemastore.org/package.json",
3
3
  "name": "bmad-module-ultracode-goal",
4
- "version": "7.2.0",
4
+ "version": "7.3.0",
5
5
  "description": "BMAD module — Run a BMAD Epic autonomously to a machine-checked, TEA-gated Definition-of-Done.",
6
6
  "keywords": [
7
7
  "bmad",
@@ -43,6 +43,22 @@ parallel_max_concurrency = 8
43
43
  # git and `uv run` command the references prescribe covered by this list.
44
44
  allowlist_commands = ["git status", "git add", "git commit", "git rev-parse", "git diff", "git check-ignore", "git worktree", "npm test", "npm run lint", "npm run build", "pytest", "uv run", "date"]
45
45
 
46
+ # --- Gate backfill sweep (opt-in) ---
47
+ # The sweep the gate runs before it commits a test bmad-testarch-automate
48
+ # backfilled. "full" (default) = the full three-axis sweep, cache-defeated, as
49
+ # Execute's step 5 runs it. "scoped" = when every path the backfill stages is a
50
+ # test file (named as its toolchain names one, and mentioned by no other file
51
+ # outside the run's own records) and Execute's full step-5 sweep went green at
52
+ # the commit the backfill builds on, re-run only the checks of the packages
53
+ # that hold those files and every check that reads files across packages or
54
+ # git's file list (unless its own declared inputs exclude every staged path),
55
+ # and print each check left out. It trusts that earlier full sweep for every
56
+ # check it does not re-run, which is why it is opt-in. The tests-ran marker
57
+ # keeps scope=full and gains a sweep= line naming both captures. Any other
58
+ # backfill runs the full sweep. A scalar: a team or user layer overrides it;
59
+ # any value other than "scoped" reads as "full".
60
+ backfill_sweep = "full"
61
+
46
62
  # --- Hook fired at epic completion (prompt or shell command); empty = none ---
47
63
  on_epic_complete = ""
48
64
 
@@ -107,7 +107,7 @@ uv run {skill-root}/scripts/claim_check.py --message {workflow.implementation_ar
107
107
 
108
108
  The second `--message` is there because the record names files the message may only describe. Its `not_in_diff` lists the paths it reads as named in either text that the staged diff does not touch, each a claim about the tree that needs no judgment to refute; paths git ignores (the mutation ledger the record cites, a story file under an ignored artifact tree) are listed apart, in `ignored`, since no commit can carry them. A record names its own artifacts from the folder that holds them (`sweep.sh`, `red-phase/INDEX.md`), so the command names three folders with `--artifacts-root` (the run folder, this story's scratch folder and its evidence folder) and a fourth with `--tea-config`, the TEA test-artifacts root that holds `atdd-checklist-<story_id>.md`, resolved from the TEA config as preflight resolves it (`scripts/preflight_check.py`, `_tea_artifacts_root`), and such a name is read there: one that does not exist from `{project-root}` but exists in one of them lands in `ignored` when each copy that holds it is either ignored by git or outside the work tree, and in `not_in_diff` otherwise; one that exists from `{project-root}`, that a file the tree holds could be, or that is in none of them, is read from `{project-root}` as before. A file this commit claims and never wrote, named bare, under a folder the tree does not hold, or under an empty or ignored-only folder inside an untracked one (git lists only the topmost untracked folder), cannot be told from an artifact of that name, so a copy in one of the folders reads it as the copy: the hunk pass below, which finds the hunk for each edit the message or the notes say this commit makes, is what catches it. For each path in `not_in_diff`: stage it if this commit changed it; if the work tree shows no change there, the edit did not happen, so make it or remove the claim; and reword the message or correct the story record itself (not only its scratch copy) when the text says this commit changed a file it did not. A path under this story's `.scratch-<story_id>/` or `evidence-<story_id>/` is never staged, since both folders stay untracked: the record names it on purpose, as its own evidence, and it may stay listed. A text may name an unchanged file on purpose, if it says so. Run the check again until every path left in `not_in_diff` is one a text names on purpose and says so. Then make one pass over the claims the diff itself adds (its new comment and header lines, the story's new completion notes) and each line of the message, for a superlative or a property: "exactly", "every", "always", "cannot", "not X but Y", "composed", or a claim that something exists or does not exist yet. Each one either cites evidence this cycle already produced (a test, a mutation row, a printed measurement) or is softened to what that evidence shows; start no new run to back a sentence, since the usual fix is to weaken the sentence, not to strengthen the code. In the same pass, read `git diff --cached` once and find the hunk for each edit the message or the notes say this commit makes ("now says", "narrowed", "landed", "fixed"), path or no path: an edit described by its content has a path too, and an edit whose script failed leaves no hunk. And look for a claim this commit makes false without touching it: a forward reference to what it lands in a comment or doc elsewhere in the tree. Search the project's own files with the Grep tool, case-insensitive, for this story's id, "does not exist yet" and "owed by", and for the name of each file the commit adds, leaving out the installed skill, the run folder and this story's own record and tests; correct a hit only when it refers to what this commit lands, in this commit, staged with this story's paths, unless a sibling story's uncommitted edits share its file, in which case log it to `.decision-log.md` for that story instead. Re-stage every file this pass edited, in its own `git add` call, then commit from the message file (`-F`). Run the same check before any re-commit step 5 makes, and before an amend with `--amend` added, on every run for that amend, a reword's re-run included: it compares the texts with what the amend would commit (the index against `HEAD`'s first parent, or the empty tree at a root commit), so a path the amended commit already carries from `HEAD` stays out of `not_in_diff`, and for that amend the hunk pass reads `git diff --cached <base>`, with the `base` the check printed.
109
109
 
110
- 5. **Re-verify on the committed HEAD.** Re-run the authoritative suite (tests + lint + build, the same scope step 2 ran this cycle: all three axes including the declared gate set when full; the same resolved package set when this re-loop cycle legitimately ran scoped, per step 2's re-loop rule) on the just-committed, clean tree and **PRINT** the result before advancing. **Run it cache-defeating.** Committing changes a file's git *tracking state* and not one of its bytes, so a content-addressed cache key is unchanged and this re-run replays the pre-commit answer verbatim, observing nothing: eight of eight tasks reported cached, returning in 719ms immediately after a commit, is the whole failure. Pass `--force` (or invoke the package's runner directly), because the one thing this step must actually execute is the tracked-file gates against the newly tracked fileset. Step 2's marks show a story's **new** files to a **conformance gate scoped to *tracked* files** (a `git ls-files`-based ref/ownership/architecture-boundary check) before the commit, but three kinds of new file still hide from it there, so the gate skips them and reports green at step 2, then reds the instant the commit tracks them: a generated or `.gitignore`d file, which no mark can reach; a file created after step 2's last mark; and, for a gate that reads the staged content (one built on git grep --cached, say), every new file, since a mark holds an empty blob. This committed tree is the exact fileset CI and the Stage-5 gate will see, so a story that is green pre-commit but red here is a **false green** the pre-commit run and any transcript-only evaluator (a `/goal` an operator started, say) both miss. A red 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 too: a red the story's changes do not explain whose second sweep shows no red leaves this step green, with nothing committed. A red means the story is **not** done: remediate, write a fresh `.tests-ran-<story_id>` marker, and re-commit (amend or a follow-up within the story boundary) until the committed HEAD is green, and only then advance. **That fresh marker carries the same `baseline=<sha>` line as step 2's**: the verbatim, whitespace-stripped content of `{workflow.implementation_artifacts}/.baseline-<story_id>`, **copied, never re-derived from `git rev-parse HEAD`**. The story's baseline has not moved; HEAD has, because step 4 just committed. Re-deriving it here would re-anchor the story to that commit and quietly retire the freshness net for the rest of it, which is the very replayed-marker hole the line exists to close, and without the line the guard denies the re-commit outright, so a story that legitimately needs remediation could never close. The fresh marker also re-states `scope=` (and `packages=` when scoped) to match what THIS re-verify actually ran, because the `scope=` line the gate will read through `--tests-ran` is the one written here, not step 2's. **Rewrite `{workflow.implementation_artifacts}/.commit-<story_id>` from `git rev-parse HEAD` once this step's HEAD is green**, in step 4's format: every time, including when nothing was remediated, because an amend replaces the SHA step 4 recorded and a follow-up commit moves it. This marker is the one step-0 artifact whose rule is *refresh*, not *keep*: the baseline names where the story started and must never move, this one names where it ended and must never be stale. That re-commit carries the SAME staging rule as step 4: stage in a prior, SEPARATE tool call (`git add <this story's paths>`), then run the commit (or `git commit --amend`) as a second, distinct call. `git commit -a` and a chained `git add … && git commit` are unsupported here too: the staged index is still empty when the guard pre-evaluates the command string, so the re-commit is denied.
110
+ 5. **Re-verify on the committed HEAD.** Re-run the authoritative suite (tests + lint + build, the same scope step 2 ran this cycle: all three axes including the declared gate set when full; the same resolved package set when this re-loop cycle legitimately ran scoped, per step 2's re-loop rule) on the just-committed, clean tree and **PRINT** the result before advancing. **Run it cache-defeating.** Committing changes a file's git *tracking state* and not one of its bytes, so a content-addressed cache key is unchanged and this re-run replays the pre-commit answer verbatim, observing nothing: eight of eight tasks reported cached, returning in 719ms immediately after a commit, is the whole failure. Pass `--force` (or invoke the package's runner directly), because the one thing this step must actually execute is the tracked-file gates against the newly tracked fileset. Step 2's marks show a story's **new** files to a **conformance gate scoped to *tracked* files** (a `git ls-files`-based ref/ownership/architecture-boundary check) before the commit, but three kinds of new file still hide from it there, so the gate skips them and reports green at step 2, then reds the instant the commit tracks them: a generated or `.gitignore`d file, which no mark can reach; a file created after step 2's last mark; and, for a gate that reads the staged content (one built on git grep --cached, say), every new file, since a mark holds an empty blob. This committed tree is the exact fileset CI and the Stage-5 gate will see, so a story that is green pre-commit but red here is a **false green** the pre-commit run and any transcript-only evaluator (a `/goal` an operator started, say) both miss. A red 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 too: a red the story's changes do not explain whose second sweep shows no red leaves this step green, with nothing committed. A red means the story is **not** done: remediate, write a fresh `.tests-ran-<story_id>` marker, and re-commit (amend or a follow-up within the story boundary) until the committed HEAD is green, and only then advance. **That fresh marker carries the same `baseline=<sha>` line as step 2's**: the verbatim, whitespace-stripped content of `{workflow.implementation_artifacts}/.baseline-<story_id>`, **copied, never re-derived from `git rev-parse HEAD`**. The story's baseline has not moved; HEAD has, because step 4 just committed. Re-deriving it here would re-anchor the story to that commit and quietly retire the freshness net for the rest of it, which is the very replayed-marker hole the line exists to close, and without the line the guard denies the re-commit outright, so a story that legitimately needs remediation could never close. The fresh marker also re-states `scope=` (and `packages=` when scoped) to match what THIS re-verify actually ran, because the `scope=` line the gate will read through `--tests-ran` is the one written here, not step 2's. **Rewrite `{workflow.implementation_artifacts}/.commit-<story_id>` from `git rev-parse HEAD` once this step's HEAD is green**, in step 4's format: every time, including when nothing was remediated, because an amend replaces the SHA step 4 recorded and a follow-up commit moves it. This marker is the one step-0 artifact whose rule is *refresh*, not *keep*: the baseline names where the story started and must never move, this one names where it ended and must never be stale. That re-commit carries the SAME staging rule as step 4: stage in a prior, SEPARATE tool call (`git add <this story's paths>`), then run the commit (or `git commit --amend`) as a second, distinct call. `git commit -a` and a chained `git add … && git commit` are unsupported here too: the staged index is still empty when the guard pre-evaluates the command string, so the re-commit is denied. When `{workflow.backfill_sweep}` is `scoped`, capture this step's sweep in `evidence-<story_id>/` as `sweep-step5-<short sha>.log` ("Evidence never goes in scratch", above): the gate's scoped backfill sweep builds on that capture and names it (`references/gate.md`, "A backfill of test files alone may scope its sweep"), and without it the gate runs the full sweep. No marker this file writes carries a `sweep=` line.
111
111
 
112
112
  **Sub-skill halt catch-all.** If any orchestrated sub-skill blocks on interactive input mid-run, treat it as escalate for that story: write the typed escalation sidecar `{workflow.implementation_artifacts}/escalation-<story_id>.json` (shape below, under "Escalation sidecar") and stop; do not answer its prompt blind. A sub-skill that is not installed at all (the Skill tool does not know its name) takes the same route: escalate, and never substitute another skill (`bmad-build`, `bmad-build-auto`, or BMAD's deprecated `bmad-create-story` and `bmad-dev-story` for UCG's story skills) or hand-author the work it would have produced.
113
113
 
@@ -167,6 +167,8 @@ One object, never an array: the file is already named per story, so a list would
167
167
 
168
168
  `kind` is **open vocabulary**. A reader renders whatever string it finds and never validates it against a fixed list, in particular never against the red-kind vocabulary the semantic scan returns in `references/preflight.md`, which classifies *planning-artifact* reds and has no term for anything that happens at run time. `budget-overrun` is a live `kind` and sits deliberately outside that vocabulary; a reader that validated against it would silently drop the most common escalation there is. `operator-evidence-owed` is a live `kind` too: the story is delivered and gated except evidence only a person can record (`references/gate.md`). So is `evidence-commit-rejected`: the story advanced, and a repo commit hook rejected its evidence commit in a way the gate may not answer, so that evidence waits, uncommitted, for the operator (`references/gate.md`'s advance route). So is `coupled-stories`: the earlier of two stories that are green only together owes clauses only the later story's build satisfies, and moving them narrows its AC, which only the operator may rule on (the story loop's "Two stories green only together").
169
169
 
170
+ **An escalated story keeps no gate build.** The gate carries its worktree's build folders into `<stash>` only for a story it will gate again (`references/gate.md`, the first caveat under "Measure the commit, not the working tree", which says what `<stash>` is), and an escalation stops the story instead, whatever route it came by. So whenever you are about to write this sidecar and `<stash>` holds a build folder, run `uv run {skill-root}/scripts/carry_build_cache.py drop --stash <stash>` right before you write it, so a session that ends between the two leaves no build behind a story it escalated. It deletes each folder `<stash>` holds, never through a link, and prints what it deleted, skipped and failed to delete; log that in `.decision-log.md` beside the escalation. The story's re-gate, once the operator answers, builds cold.
171
+
170
172
  **Promoting the turn-budget marker.** The `budget_stop.py` Stop hook writes only its own markdown, `{workflow.implementation_artifacts}/.escalation-<story_id>.md`. It stays a recorder: it emits no JSON and starts no process, and its marker records a count without stopping the drive, so the story still goes on to its gate. **Execute is the sole promoter of that markdown, and the story's gate decides whether it promotes.** A marker counts only while the story's recorded count (`turns` in `{workflow.implementation_artifacts}/.budget-<story_id>.json`) is at or past `{workflow.max_turns_per_story}`: after `/ucg-resolve` closes a `budget-overrun` escalation and resets that counter, the marker left on disk is the answered escalation's residue, and nothing below applies to it. **When the gate advances the story (`advance`, or `defer`, whose route advances anyway), do not promote the marker.** The gate decides completion, and none of the decisions the marker asks for has anything left to act on once the story is done: in a real project, every overrun escalation written for a story that then passed its gate was left open and never answered. Log a sizing note in `.decision-log.md` instead, naming the story and the hook's count against `{workflow.max_turns_per_story}`; Finalize's run report carries it. The note records the turns the drive spent, and never says a row of this shape should be split: sizing reads a row's criteria, never its turns ("Sizing: a story too large to drive" above), and the turns follow how the drive waited. **When the gate escalates the story on the turn count** (a re-loop that would exceed the ceiling, which `references/gate.md` turns into `escalate`), promote the marker as that escalation's sidecar: read the `.escalation-<story_id>.md` the hook left behind and write the typed sidecar from it, mapping `source` to that markdown's path, `kind` to `budget-overrun`, `decision_needed` to the human decision the marker asks for (re-scope, split, or hand off), and `evidence` to one line quoted from the marker. The gate can escalate on the count before the hook has written a marker (a re-loop expected to take several responses, from a count still under the ceiling); write the same `budget-overrun` sidecar then from `{workflow.implementation_artifacts}/.budget-<story_id>.json`, with `source` that file's path and `evidence` its count, so `/ucg-resolve` still resets the counter when it closes it. A cap-only `reloop` (a sweep-scope or delta cap) is not that verdict: the full re-gate it leads to decides. A story that escalates for its own reason (a gate file that cannot be read, a sub-skill halt) keeps that reason's sidecar, and the marker's count goes into the decision log beside it. A resume that finds the count already at or past the ceiling escalates before step 0 with the same `kind`, as "Authoring the `/goal` condition" above says. Keeping promotion here means one code path produces the typed JSON whatever the escalation's origin, instead of two writers racing on a file three readers depend on.
171
173
 
172
174
  **Leave the markdown in place — never delete it, never rewrite it.** It is the hook's own record of the count. For a story that advanced it is the sizing note's source, and for a story that escalates it is the residual that survives a session which died before this promotion, so consuming it could destroy the only evidence that an escalation happened at all.
@@ -17,13 +17,23 @@ The gate reads artifacts TEA produces. In **production**, before running the gat
17
17
  **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:
18
18
 
19
19
  1. Stage the test files this pass's summary (`automation-summary-<story_id>-<sha>.md`, with `<sha>` the `gate-backfill-base:` commit; "Automate's summary records its rows" below) names as written or changed, by explicit path, in one call. `git status --porcelain --untracked-files=all` lists them: the plain `git status --porcelain` lists a new directory instead of the files in it, so a test in a new folder would look absent. A path it lists that the summary does not name is not part of the backfill and stays unstaged. 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.
20
- 2. With them staged, so that a gate reading git's file list sees a new test file, run the full three-axis sweep over the main tree, cache-defeated and printed, as `references/execute.md` step 5 runs it. A red `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.
21
- 3. Once the sweep is green, write a fresh `.tests-ran-<story_id>` marker as step 5 writes one: its `baseline=` line copied from `.baseline-<story_id>`, never re-derived, and `scope=full`.
20
+ 2. With them staged, so that a gate reading git's file list sees a new test file, run the full three-axis sweep over the main tree, cache-defeated and printed, as `references/execute.md` step 5 runs it. 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.
21
+ 3. Once the sweep is green, write a fresh `.tests-ran-<story_id>` marker as step 5 writes one: its `baseline=` line copied from `.baseline-<story_id>`, never re-derived, and `scope=full`. 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`.
22
22
  4. Run `references/execute.md` step 4's claim check on the commit message, then commit from the message file, in a call separate from the staging call, as step 4 requires. The guard allows this commit as it allows the evidence commit in "Route on the verdict": the story is still current, its marker was written in a prior call, and the index is not empty. A repo commit hook that rejects this commit is read as step 2's red, and `references/execute.md` step 4's own rule for a hook rejection does not apply to it: when a change to the backfilled test files alone answers the hook, make it there, stage it, and go back to step 2, whose sweep runs again before step 3 writes a fresh marker and this step retries the commit, all within step 2's budget of two fixes; when the hook needs a change to any other path, or rejects the commit again after the second fix, commit nothing, and take "A red backfill sweep ends the cycle at a re-loop" below. A `commit-msg` hook that rejects the message alone asks for no file change: Git runs it only once every `pre-commit` job has passed, so reword the message file, run the claim check again and retry the commit with the marker as it stands, re-running no sweep. That retry counts as one of step 2's two fixes, and a rejection after the second still takes "A red backfill sweep ends the cycle at a re-loop" below. A change a `pre-commit` job staged on its way there rides the retry as it would ride an accepted commit. A path the re-run claim check has you stage or edit is a file change, which takes the rule above. A rejection whose output does not show that a `commit-msg` hook made it is read as step 2's red, as above.
23
- 5. Refresh `.commit-<story_id>` from `HEAD`, log `gate-backfill: <sha>`, naming the new commit, in `.decision-log.md`, and 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").
23
+ 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.
24
24
 
25
25
  The new commit is now the commit under assessment: the worktree is rebuilt at it, trace, NFR and test review measure it, and the verdict's `assessed-commit` line names it. The backfill belongs to this gate cycle and is not a re-loop: it writes no `class:` line, spends no re-loop, and never meets the turn-ceiling check that runs before a re-loop, though its sweep spends turns like any wait (`references/execute.md`, "Waiting spends turns").
26
26
 
27
+ **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:
28
+
29
+ - the story's `.tests-ran-<story_id>` marker reads `scope=full` and holds no `sweep=` line, so a scoped sweep never builds on another;
30
+ - `.commit-<story_id>`, `git rev-parse HEAD` and the `gate-backfill-base:` commit are one commit;
31
+ - `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);
32
+ - 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;
33
+ - every fix step 2 makes stays inside those files.
34
+
35
+ 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.
36
+
27
37
  **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).
28
38
 
29
39
  **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:
@@ -41,26 +51,28 @@ The new commit is now the commit under assessment: the worktree is rebuilt at it
41
51
 
42
52
  (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.)
43
53
 
44
- **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). 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.
54
+ **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.
45
55
 
46
56
  **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).
47
57
 
48
58
  **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.
49
59
 
50
- **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. 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.
60
+ **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.
61
+
62
+ **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.
51
63
 
52
64
  **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.
53
65
 
54
- **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. 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). 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:
66
+ **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:
55
67
 
56
- - 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.
68
+ - 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.
57
69
  - 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.
58
70
  - 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.
59
71
 
60
- 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 `gate-gap:` line never changes the route the verdict takes, and each route treats the open lines this way:
72
+ 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:
61
73
 
62
74
  - 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.
63
- - 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. 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.
75
+ - 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.
64
76
  - Whatever the route, a line stays open, so the story's next gate cycle, when there is one, copies it.
65
77
 
66
78
  **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.
@@ -69,16 +81,16 @@ A line closes when an automate pass at a later commit than the one the line name
69
81
 
70
82
  ## Measure the commit, not the working tree
71
83
 
72
- 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 preserve), then `git worktree prune`; a resume that finds a dead session's stale `.gate-worktree-<story_id>` removes it the same way before creating its own. A step that only authors an artifact from already-recorded evidence has nothing to measure and needs no worktree; the rule binds every assessor that runs or times anything. Four caveats the setup owes, each a measured failure when skipped:
84
+ 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:
73
85
 
74
- - **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; measure both once per repo before committing to one.
86
+ - **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; 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.
75
87
  - **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.
76
88
  - **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.
77
89
  - **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.
78
90
 
79
- **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: 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), 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. 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. 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.
91
+ **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. 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.
80
92
 
81
- 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.
93
+ 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.
82
94
 
83
95
  ## Non-web stack: the red phase by hand, and the trace artifacts where trace cannot run
84
96
 
@@ -173,9 +185,9 @@ Do not recompute TEA thresholds or re-judge `gate_status` — read it as given.
173
185
 
174
186
  **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`.
175
187
 
176
- **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 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.
188
+ **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.
177
189
 
178
- **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, 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.
190
+ **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.
179
191
 
180
192
  **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.
181
193
 
@@ -235,7 +247,7 @@ Append to `{workflow.deferred_work_path}` (create on first use). One heading per
235
247
  | d1 | gate | low | <story-id> | <why parked> | <what to do later> | open |
236
248
  ```
237
249
 
238
- - `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, 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).
250
+ - `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).
239
251
  - `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.
240
252
  - `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).
241
253
  - `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.
@@ -0,0 +1,435 @@
1
+ #!/usr/bin/env -S uv run --script
2
+ # /// script
3
+ # requires-python = ">=3.11"
4
+ # dependencies = []
5
+ # ///
6
+ """Carry a gate worktree's build folders aside across its rebuild.
7
+
8
+ The gate (references/gate.md) replaces its measurement worktree with
9
+ `git worktree remove --force` and `git worktree add`, which deletes every
10
+ ignored folder the worktree held, Cargo's `target` among them, so each story
11
+ paid two cold builds. This script moves those build folders out of the
12
+ worktree into a stash right before the removal (`out`), and back to the same
13
+ paths right after the add (`back`). When the story escalates instead of
14
+ being gated again, `drop` deletes what the stash holds. It runs under
15
+ `uv run`, which the run's allowlist covers; a bare `mv` or `rm` is not on it.
16
+
17
+ Which folders. By default every Cargo build folder in the tree, outermost
18
+ only: a folder holding both `CACHEDIR.TAG` and `.rustc_info.json`, such as
19
+ the root's `target` or a Tauri app's `src-tauri/target`. A folder is judged by
20
+ what it holds, not by its name. The walk does not enter `.git`,
21
+ `node_modules`, a repository or worktree nested in the tree, a Python virtual
22
+ environment, any other cache folder (one holding `CACHEDIR.TAG` alone, such
23
+ as `.pytest_cache`) or a link. `--dir` names a build folder of another
24
+ toolchain instead, relative to the worktree; repeat it for several. Given any
25
+ `--dir`, nothing is discovered. Never carried: a test-result cache
26
+ (`.pytest_cache`, a turbo or nx cache), whose replayed results would stand in
27
+ for runs that never happened, a path reached through a link or a junction,
28
+ and a path that resolves outside the worktree or the stash.
29
+
30
+ How each folder moves. With `os.rename` only, to the same relative path, so a
31
+ tool that keys its cache on the folder's path finds it valid. A folder that
32
+ fails to move stays where it was: `out` leaves it in the worktree, which the
33
+ removal then deletes with it, so the next build is cold but never wrong.
34
+ Before `out` moves a Cargo build folder, it deletes the run results Cargo's
35
+ tools keep there (`criterion/`, `nextest/`, `tarpaulin/`, `llvm-cov/` and
36
+ `tmp/`, Cargo's `CARGO_TARGET_TMPDIR`, which Cargo never cleans, at its top
37
+ and at the top of every Cargo build folder inside it, such as
38
+ `llvm-cov-target`, and every `*.profraw` and `*.profdata` file in it), since
39
+ a mutant's run wrote them. Such a name is deleted only when it is a folder or
40
+ a link (the link itself); a plain file of that name stays. `out` clears
41
+ every folder it carries this way, a `--dir` one included, so a Cargo build
42
+ folder nested in another toolchain's folder loses its run results too. A folder whose run
43
+ results cannot all be deleted, an unreadable folder inside it included, is
44
+ not carried. `out` skips a folder the
45
+ stash already holds (`exists`), so nothing is merged. `back` skips a folder
46
+ whose parent the worktree does not have (`parent-missing`) or whose path the
47
+ worktree already holds (`exists`), and leaves it in the stash. The stash gets
48
+ a `.gitignore` holding `*` when `out` first creates it, so a status read of
49
+ the tree that holds it never lists its files. A stash `back` finds missing
50
+ holds nothing to carry.
51
+
52
+ How `drop` deletes. Every folder the stash holds, with everything in it,
53
+ never through a link: a link inside is deleted itself, never what it points
54
+ at, and a folder of the stash that is a link, or a stash that is one, is
55
+ skipped. The stash's `.gitignore` stays. A missing stash holds nothing to
56
+ delete; a stash it cannot reach (a parent folder it may not search) is
57
+ reported under `failed`. Since it deletes every folder it finds, `drop` refuses a stash that
58
+ is not a folder named `gate-build` holding the `.gitignore` reading `*` that
59
+ `out` writes, or one that holds a `.git`.
60
+
61
+ Usage:
62
+ uv run carry_build_cache.py out --worktree <path> --stash <path> [--dir <relpath> ...]
63
+ uv run carry_build_cache.py back --worktree <path> --stash <path> [--dir <relpath> ...]
64
+ uv run carry_build_cache.py drop --stash <path>
65
+
66
+ Output: JSON on stdout, `{"mode", "carried": [...], "cleared": [...],
67
+ "skipped": [{"path", "reason"}], "failed": [{"path", "error"}]}`, paths
68
+ relative to the worktree (to the stash for `drop`) with `/` separators;
69
+ `cleared` lists the run results `out` deleted, or the folders `drop` deleted,
70
+ and `reason` is `missing`, `exists`, `parent-missing`, `link`, `outside`,
71
+ `not-a-folder` or `test-result-cache`. Exit 0 when every folder was carried,
72
+ deleted or skipped, 1 when any failed, and 2 when the call is wrong: the
73
+ worktree is missing or not a folder, the stash is not a folder (for `out` and
74
+ `back`, a stash that is a link included), the stash and the worktree overlap,
75
+ a `--dir` is absolute or leaves the worktree, or `drop` was given a folder
76
+ that is not a stash.
77
+ """
78
+
79
+ from __future__ import annotations
80
+
81
+ import argparse
82
+ import json
83
+ import os
84
+ import shutil
85
+ import stat
86
+ import sys
87
+ from pathlib import Path
88
+
89
+ # The folder name the gate gives its stash; `drop` refuses any other.
90
+ STASH_NAME = "gate-build"
91
+ # Cargo writes both into every build folder it makes.
92
+ CARGO_MARKERS = ("CACHEDIR.TAG", ".rustc_info.json")
93
+ # What Cargo's tools leave in a build folder after a run: Criterion's
94
+ # baselines, nextest's archives and reports, tarpaulin's and cargo-llvm-cov's
95
+ # reports, the scratch folder Cargo gives integration tests and benches as
96
+ # `CARGO_TARGET_TMPDIR` and never cleans, and the coverage profiles of an
97
+ # instrumented run.
98
+ _RUN_RESULT_DIRS = ("criterion", "nextest", "tarpaulin", "llvm-cov", "tmp")
99
+ _RUN_RESULT_SUFFIXES = (".profraw", ".profdata")
100
+ # Folders the walk never enters, by name.
101
+ _UNWALKED = frozenset({".git", "node_modules", "__pycache__"})
102
+ # A folder holding one of these is another repository or worktree (`.git`), a
103
+ # Python virtual environment, or a cache (the Cache Directory Tagging spec).
104
+ _UNWALKED_MARKERS = frozenset({".git", "pyvenv.cfg", "CACHEDIR.TAG"})
105
+ # Caches that replay a test task's result instead of running it.
106
+ _RESULT_CACHE_NAMES = frozenset({".pytest_cache", ".turbo", ".nx"})
107
+ _RESULT_CACHE_UNDER_DOT_CACHE = frozenset({"turbo", "nx"})
108
+ _REPARSE_POINT = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
109
+
110
+
111
+ def _is_link(path: str | Path) -> bool:
112
+ """A symbolic link, or on Windows any reparse point, a junction included."""
113
+ try:
114
+ st = os.lstat(path)
115
+ except OSError:
116
+ return False
117
+ if stat.S_ISLNK(st.st_mode):
118
+ return True
119
+ return bool(getattr(st, "st_file_attributes", 0) & _REPARSE_POINT)
120
+
121
+
122
+ def _reached_through_a_link(root: Path, rel: str) -> bool:
123
+ """Whether any folder on the way from root to root/rel, rel included, is a link."""
124
+ current = str(root)
125
+ for part in Path(rel).parts:
126
+ current = os.path.join(current, part)
127
+ if _is_link(current):
128
+ return True
129
+ return False
130
+
131
+
132
+ def _common(a: str, b: str) -> str | None:
133
+ """The longest common path of a and b, or None for paths with no common
134
+ root (two Windows drives)."""
135
+ try:
136
+ return os.path.commonpath([a, b])
137
+ except ValueError:
138
+ return None
139
+
140
+
141
+ def _inside(path: Path, root: Path) -> bool:
142
+ real, real_root = os.path.realpath(path), os.path.realpath(root)
143
+ return real != real_root and _common(real, real_root) == real_root
144
+
145
+
146
+ def _is_cargo_folder(path: Path) -> bool:
147
+ return all(os.path.isfile(path / marker) for marker in CARGO_MARKERS)
148
+
149
+
150
+ def _is_result_cache(rel: str) -> bool:
151
+ parts = Path(rel).parts
152
+ if any(part in _RESULT_CACHE_NAMES for part in parts):
153
+ return True
154
+ return any(
155
+ parts[i] == ".cache" and parts[i + 1] in _RESULT_CACHE_UNDER_DOT_CACHE for i in range(len(parts) - 1)
156
+ )
157
+
158
+
159
+ def discover(root: Path) -> list[str]:
160
+ """Every Cargo build folder under root, outermost only, sorted."""
161
+ found: list[str] = []
162
+ for current, dirs, files in os.walk(root):
163
+ here = Path(current)
164
+ entries = set(dirs) | set(files)
165
+ if current != str(root) and entries & _UNWALKED_MARKERS:
166
+ if _is_cargo_folder(here):
167
+ found.append(Path(os.path.relpath(current, root)).as_posix())
168
+ dirs[:] = [] # a build folder, another cache, a nested repository or a virtual environment
169
+ continue
170
+ dirs[:] = [name for name in dirs if name not in _UNWALKED and not _is_link(here / name)]
171
+ return sorted(found)
172
+
173
+
174
+ def _outermost(rels: list[str]) -> list[str]:
175
+ """Each path once, without one that sits inside another of them."""
176
+ kept: list[str] = []
177
+ for rel in sorted(set(rels)):
178
+ if not any(rel.startswith(outer + "/") for outer in kept):
179
+ kept.append(rel)
180
+ return kept
181
+
182
+
183
+ def _raise(error: OSError) -> None:
184
+ """An `os.walk` onerror that stops the walk: a folder it cannot read is a
185
+ folder it cannot clear."""
186
+ raise error
187
+
188
+
189
+ def _delete_link(path: Path) -> None:
190
+ try:
191
+ os.unlink(path)
192
+ except OSError:
193
+ os.rmdir(path) # a junction on Windows
194
+
195
+
196
+ def _delete_folder(path: Path) -> None:
197
+ """Delete a folder with everything in it, or a link, which is deleted
198
+ itself and never followed. Raises OSError on a failure."""
199
+ if _is_link(path):
200
+ _delete_link(path)
201
+ else:
202
+ shutil.rmtree(path)
203
+
204
+
205
+ def _clear_run_results(folder: Path, rel: str, cleared: list[str]) -> None:
206
+ """Delete the run results Cargo's tools keep in folder and in every Cargo
207
+ build folder inside it, adding each to cleared. A run-result name is
208
+ deleted only when it is a folder or a link (the link itself, never what it
209
+ points at); a plain file of that name stays. Raises OSError when one
210
+ cannot be deleted or a folder in it cannot be read."""
211
+ for current, dirs, files in os.walk(folder, onerror=_raise):
212
+ here = Path(current)
213
+ cargo = _is_cargo_folder(here)
214
+ kept: list[str] = []
215
+ for name in sorted(dirs):
216
+ path = here / name
217
+ if cargo and name in _RUN_RESULT_DIRS:
218
+ _delete_folder(path)
219
+ cleared.append(Path(rel, os.path.relpath(path, folder)).as_posix())
220
+ elif not _is_link(path):
221
+ kept.append(name)
222
+ dirs[:] = kept
223
+ for name in sorted(files):
224
+ path = here / name
225
+ if (cargo and name in _RUN_RESULT_DIRS and _is_link(path)) or name.endswith(_RUN_RESULT_SUFFIXES):
226
+ if _is_link(path):
227
+ _delete_link(path)
228
+ else:
229
+ os.unlink(path)
230
+ cleared.append(Path(rel, os.path.relpath(path, folder)).as_posix())
231
+
232
+
233
+ def _prune_empty_parents(path: Path, root: Path) -> None:
234
+ """Remove the folders between root and path that the move left empty."""
235
+ parent = path.parent
236
+ while parent != root and root in parent.parents:
237
+ try:
238
+ parent.rmdir()
239
+ except OSError:
240
+ return
241
+ parent = parent.parent
242
+
243
+
244
+ def _make_stash(stash: Path) -> None:
245
+ stash.mkdir(parents=True, exist_ok=True)
246
+ ignore = stash / ".gitignore"
247
+ if not os.path.exists(ignore):
248
+ ignore.write_text("*\n", encoding="utf-8")
249
+
250
+
251
+ def _within(path: Path, root: Path) -> bool:
252
+ """Whether path resolves to root or to a path inside it."""
253
+ return os.path.realpath(path) == os.path.realpath(root) or _inside(path, root)
254
+
255
+
256
+ def carry(mode: str, worktree: Path, stash: Path, rel_dirs: list[str]) -> dict:
257
+ """Move each folder in rel_dirs from the worktree to the stash (`out`) or
258
+ from the stash to the worktree (`back`), at the same relative path."""
259
+ source_root, target_root = (worktree, stash) if mode == "out" else (stash, worktree)
260
+ carried: list[str] = []
261
+ cleared: list[str] = []
262
+ skipped: list[dict] = []
263
+ failed: list[dict] = []
264
+ for rel in rel_dirs:
265
+ source, target = source_root / rel, target_root / rel
266
+ parent_rel = Path(rel).parent.as_posix()
267
+ if _is_result_cache(rel):
268
+ skipped.append({"path": rel, "reason": "test-result-cache"})
269
+ elif not os.path.lexists(source):
270
+ skipped.append({"path": rel, "reason": "missing"})
271
+ elif _reached_through_a_link(source_root, rel) or (
272
+ parent_rel != "." and _reached_through_a_link(target_root, parent_rel)
273
+ ):
274
+ skipped.append({"path": rel, "reason": "link"})
275
+ elif not _inside(source, source_root):
276
+ skipped.append({"path": rel, "reason": "outside"})
277
+ elif not os.path.isdir(source):
278
+ skipped.append({"path": rel, "reason": "not-a-folder"})
279
+ elif mode == "back" and not os.path.isdir(target.parent):
280
+ skipped.append({"path": rel, "reason": "parent-missing"})
281
+ elif os.path.lexists(target):
282
+ skipped.append({"path": rel, "reason": "exists"})
283
+ elif not _within(target.parent, target_root):
284
+ skipped.append({"path": rel, "reason": "outside"})
285
+ else:
286
+ try:
287
+ if mode == "out":
288
+ # Every folder carried out, a `--dir` one included: the
289
+ # clearing finds each Cargo build folder inside it.
290
+ _clear_run_results(source, rel, cleared)
291
+ _make_stash(stash)
292
+ target.parent.mkdir(parents=True, exist_ok=True)
293
+ os.rename(source, target)
294
+ except OSError as exc:
295
+ failed.append({"path": rel, "error": str(exc)})
296
+ continue
297
+ carried.append(rel)
298
+ if mode == "back":
299
+ _prune_empty_parents(source, stash)
300
+ return {"mode": mode, "carried": carried, "cleared": cleared, "skipped": skipped, "failed": failed}
301
+
302
+
303
+ def drop(stash: Path) -> dict:
304
+ """Delete every folder the stash holds, never through a link."""
305
+ cleared: list[str] = []
306
+ skipped: list[dict] = []
307
+ failed: list[dict] = []
308
+ if _is_link(stash):
309
+ skipped.append({"path": ".", "reason": "link"})
310
+ elif os.path.isdir(stash):
311
+ try:
312
+ entries = sorted(os.listdir(stash))
313
+ except OSError as exc:
314
+ failed.append({"path": ".", "error": str(exc)})
315
+ entries = []
316
+ for entry in entries:
317
+ path = stash / entry
318
+ if _is_link(path):
319
+ skipped.append({"path": entry, "reason": "link"})
320
+ elif os.path.isdir(path):
321
+ try:
322
+ shutil.rmtree(path)
323
+ except OSError as exc:
324
+ failed.append({"path": entry, "error": str(exc)})
325
+ continue
326
+ cleared.append(entry)
327
+ return {"mode": "drop", "carried": [], "cleared": cleared, "skipped": skipped, "failed": failed}
328
+
329
+
330
+ def _relative_dir(raw: str, root: Path) -> str | None:
331
+ """`raw` as a `/` path relative to root, or None when it leaves it."""
332
+ if os.path.isabs(raw) or Path(raw).drive:
333
+ return None
334
+ full = os.path.normpath(os.path.join(root, raw))
335
+ rel = os.path.relpath(full, root)
336
+ if rel == os.curdir or rel == os.pardir or rel.startswith(os.pardir + os.sep):
337
+ return None
338
+ return Path(rel).as_posix()
339
+
340
+
341
+ def _overlap(a: Path, b: Path) -> bool:
342
+ real_a, real_b = os.path.realpath(a), os.path.realpath(b)
343
+ common = _common(real_a, real_b)
344
+ return common is not None and common in (real_a, real_b)
345
+
346
+
347
+ def _is_a_stash(stash: Path) -> str | None:
348
+ """Why the folder `drop` was given is not a stash `out` made, or None:
349
+ `drop` deletes every folder it holds, so a wrong path must never reach it."""
350
+ if stash.name != STASH_NAME:
351
+ return f"the stash must be a folder named {STASH_NAME}: {stash}"
352
+ try:
353
+ ignore = (stash / ".gitignore").read_text(encoding="utf-8")
354
+ except (OSError, UnicodeDecodeError):
355
+ ignore = None
356
+ if ignore is None or ignore.rstrip("\r\n") != "*":
357
+ return f"the stash holds no .gitignore reading * as out writes it: {stash}"
358
+ if os.path.lexists(stash / ".git"):
359
+ return f"the stash holds a .git, so it is a repository or a worktree: {stash}"
360
+ return None
361
+
362
+
363
+ def _error(message: str) -> int:
364
+ print(json.dumps({"error": message}), file=sys.stderr)
365
+ return 2
366
+
367
+
368
+ def main(argv: list[str] | None = None) -> int:
369
+ parser = argparse.ArgumentParser(description="Carry a gate worktree's build folders aside across its rebuild.")
370
+ parser.add_argument(
371
+ "mode",
372
+ choices=("out", "back", "drop"),
373
+ help="out: worktree to stash; back: stash to worktree; drop: delete what the stash holds",
374
+ )
375
+ parser.add_argument("--worktree", help="the gate's measurement worktree (out and back)")
376
+ parser.add_argument("--stash", required=True, help="the folder that holds the build folders between the two")
377
+ parser.add_argument(
378
+ "--dir",
379
+ action="append",
380
+ default=[],
381
+ help="a build folder to carry, relative to the worktree; repeat for several "
382
+ "(default: every Cargo build folder)",
383
+ )
384
+ args = parser.parse_args(argv)
385
+ if hasattr(sys.stdout, "reconfigure"):
386
+ sys.stdout.reconfigure(encoding="utf-8", errors="backslashreplace")
387
+ stash = Path(os.path.abspath(args.stash))
388
+ if args.mode == "drop":
389
+ if args.worktree or args.dir:
390
+ return _error("drop takes --stash alone")
391
+ try:
392
+ os.lstat(stash)
393
+ except FileNotFoundError:
394
+ pass # no stash: nothing to delete
395
+ except OSError as exc:
396
+ result = {"mode": "drop", "carried": [], "cleared": [], "skipped": [],
397
+ "failed": [{"path": ".", "error": str(exc)}]}
398
+ print(json.dumps(result, indent=2, ensure_ascii=False))
399
+ return 1
400
+ if os.path.lexists(stash) and not _is_link(stash):
401
+ if not os.path.isdir(stash):
402
+ return _error(f"the stash is not a folder: {stash}")
403
+ reason = _is_a_stash(stash)
404
+ if reason is not None:
405
+ return _error(reason)
406
+ result = drop(stash)
407
+ print(json.dumps(result, indent=2, ensure_ascii=False))
408
+ return 1 if result["failed"] else 0
409
+ if not args.worktree:
410
+ return _error(f"{args.mode} needs --worktree")
411
+ if _is_link(stash):
412
+ return _error(f"the stash is a link: {stash}")
413
+ if os.path.lexists(stash) and not os.path.isdir(stash):
414
+ return _error(f"the stash is not a folder: {stash}")
415
+ worktree = Path(os.path.abspath(args.worktree))
416
+ if not os.path.isdir(worktree):
417
+ return _error(f"the worktree is not a folder: {worktree}")
418
+ if _overlap(worktree, stash):
419
+ return _error(f"the stash and the worktree must not hold each other: {stash}")
420
+ rel_dirs = []
421
+ for raw in args.dir:
422
+ rel = _relative_dir(raw, worktree)
423
+ if rel is None:
424
+ return _error(f"--dir must be a folder inside the worktree: {raw}")
425
+ rel_dirs.append(rel)
426
+ if not rel_dirs:
427
+ root = worktree if args.mode == "out" else stash
428
+ rel_dirs = discover(root) if os.path.isdir(root) else []
429
+ result = carry(args.mode, worktree, stash, _outermost(rel_dirs))
430
+ print(json.dumps(result, indent=2, ensure_ascii=False))
431
+ return 1 if result["failed"] else 0
432
+
433
+
434
+ if __name__ == "__main__":
435
+ sys.exit(main())
@@ -71,6 +71,7 @@ from __future__ import annotations
71
71
  import argparse
72
72
  import hashlib
73
73
  import json
74
+ import os
74
75
  import re
75
76
  import sys
76
77
  import time
@@ -354,20 +355,35 @@ def _present_and_readable(path: Path | None) -> bool:
354
355
 
355
356
 
356
357
  # A story's run folders directly under impl-artifacts: `.scratch-<story_id>/`
357
- # (throwaway build space, which a dead run can leave behind) and
358
- # `evidence-<story_id>/` (captured output, which no step removes). Neither holds
359
- # a story file or a TEA artifact, so the story-file and leaked-artifact scans
360
- # skip every file below one of them; a folder so named deeper down is read.
361
- _RUN_FOLDER_RE = re.compile(r"^(?:evidence-|\.scratch-)")
362
-
363
-
364
- def _in_run_folder(path: Path, impl_artifacts: Path) -> bool:
365
- """True when the first path component below impl-artifacts is a run folder."""
366
- try:
367
- parts = path.relative_to(impl_artifacts).parts
368
- except ValueError:
369
- return False
370
- return len(parts) > 1 and bool(_RUN_FOLDER_RE.match(parts[0]))
358
+ # (throwaway build space, which a dead run can leave behind, and where the
359
+ # gate keeps its worktree's build folders between a removal and an add),
360
+ # `evidence-<story_id>/` (captured output, which no step removes) and
361
+ # `.gate-worktree-<story_id>/` (the gate's measurement worktree, which a dead
362
+ # session can leave behind with a build tree in it and, on a tracked artifact
363
+ # tree, copies of the story files). None holds a story file or a TEA artifact
364
+ # of this run, so the story-file and leaked-artifact scans never walk into
365
+ # one; a folder so named deeper down is read.
366
+ _RUN_FOLDER_RE = re.compile(r"^(?:evidence-|\.scratch-|\.gate-worktree-)")
367
+
368
+
369
+ def _files_outside_run_folders(impl_artifacts: Path, pattern: str) -> list[Path]:
370
+ """Every file under impl-artifacts whose name matches `pattern`, sorted.
371
+
372
+ The walk skips each top-level run folder instead of reading it and
373
+ dropping its files afterwards: a scratch folder can hold a build tree of
374
+ many thousands of files (a Cargo `target`), which every preflight would
375
+ otherwise list, stat and sort. The files it returns are the ones
376
+ `impl_artifacts.rglob(pattern)` finds outside those folders.
377
+ """
378
+ found: list[Path] = []
379
+ for current, dirs, files in os.walk(impl_artifacts):
380
+ if Path(current) == impl_artifacts:
381
+ dirs[:] = [name for name in dirs if not _RUN_FOLDER_RE.match(name)]
382
+ for name in files:
383
+ path = Path(current) / name
384
+ if path.match(pattern) and path.is_file():
385
+ found.append(path)
386
+ return sorted(found)
371
387
 
372
388
 
373
389
  def _story_files(impl_artifacts: Path, epic: str, story_keys: list[str]) -> list[Path]:
@@ -378,19 +394,19 @@ def _story_files(impl_artifacts: Path, epic: str, story_keys: list[str]) -> list
378
394
  The coverage check reads all of them, since a done parent's file covers its
379
395
  decomposed children, and so does the declared-id set. Which of them the
380
396
  per-story checks read is `_in_scope_story_files`'s call. A file inside a
381
- story's run folder is none (`_in_run_folder`).
397
+ story's run folder is none (`_files_outside_run_folders`).
382
398
  """
383
399
  if not impl_artifacts.is_dir():
384
400
  return []
385
401
  try:
386
- all_md = sorted(p for p in impl_artifacts.rglob("*.md") if p.is_file())
402
+ all_md = _files_outside_run_folders(impl_artifacts, "*.md")
387
403
  except OSError:
388
404
  return []
389
405
  prefix = f"{epic}-"
390
406
  files: list[Path] = []
391
407
  for path in all_md:
392
408
  name = path.name.lower()
393
- if name.startswith("sprint-status") or _in_run_folder(path, impl_artifacts):
409
+ if name.startswith("sprint-status"):
394
410
  continue
395
411
  if name.startswith(prefix) or any(name.startswith(f"{k.lower()}") for k in story_keys):
396
412
  files.append(path)
@@ -823,19 +839,19 @@ def _leaked_tea_artifacts(
823
839
  WRONG LOCATION, not on mere presence of a TEA file). UCG's own story notes /
824
840
  run sentinels are excluded even when their filename carries a marker token
825
841
  (see _is_ucg_impl_artifact), and so is every file inside a story's run
826
- folder (`_in_run_folder`): a scratch build's `libbacktrace-*.rlib` or a
827
- capture a tool named `trace.zip` is no TEA artifact.
842
+ folder (`_files_outside_run_folders`): a scratch build's `libbacktrace-*.rlib`
843
+ or a capture a tool named `trace.zip` is no TEA artifact.
828
844
  """
829
845
  if not impl_artifacts.is_dir():
830
846
  return []
831
847
  try:
832
- all_files = sorted(p for p in impl_artifacts.rglob("*") if p.is_file())
848
+ all_files = _files_outside_run_folders(impl_artifacts, "*")
833
849
  except OSError:
834
850
  return []
835
851
  leaked: list[Path] = []
836
852
  for path in all_files:
837
853
  name = path.name.lower()
838
- if not any(marker in name for marker in TEA_ARTIFACT_MARKERS) or _in_run_folder(path, impl_artifacts):
854
+ if not any(marker in name for marker in TEA_ARTIFACT_MARKERS):
839
855
  continue
840
856
  if _is_ucg_impl_artifact(path, name):
841
857
  continue