bmad-module-ultracode-goal 3.2.0 → 4.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +1 -1
- package/README.md +15 -15
- package/docs/_internal/STABILITY.md +3 -3
- package/docs/architecture.md +3 -1
- package/docs/cross-session-recall.md +3 -3
- package/docs/getting-started.md +2 -2
- package/docs/operating-tips.md +2 -0
- package/docs/troubleshooting.md +27 -3
- package/package.json +1 -1
- package/skills/ucg-resolve/SKILL.md +15 -0
- package/skills/ucg-status/SKILL.md +34 -1
- package/skills/ultracode-goal/references/execute.md +9 -5
- package/skills/ultracode-goal/references/finalize.md +1 -1
- package/skills/ultracode-goal/references/gate.md +9 -6
- package/skills/ultracode-goal/references/preflight.md +20 -11
- package/skills/ultracode-goal/scripts/gate_trail.py +230 -36
- package/skills/ultracode-goal/scripts/hooks/budget_stop.py +5 -3
- package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +210 -71
- package/skills/ultracode-goal/scripts/mutate_check.py +340 -56
- package/skills/ultracode-goal/scripts/preflight_check.py +155 -27
- package/skills/ultracode-goal/scripts/probe_servers.py +201 -0
- package/skills/ultracode-goal/scripts/status_render.py +69 -1
- package/skills/ultracode-goal/scripts/story_sizing.py +14 -9
|
@@ -12,7 +12,7 @@ The gate reads artifacts TEA produces. In **production**, before running the gat
|
|
|
12
12
|
2. Once automate has finished, log its `gate-gap:` lines ("A reported gap stays open until a later pass measures it closed" below), commit its backfill if it made one ("When automate backfills" below), then rebuild the gate worktree at the commit under assessment ("Rebuild the worktree once automate has finished" below). A red backfill sweep ends the cycle here instead, before trace ("A red backfill sweep ends the cycle at a re-loop" below), and nothing else automate's pass or its backfill produces does: a `gate-gap:` line never ends a cycle. A sub-skill that blocks on input or is not installed still escalates the story, at this step or any other, as `references/execute.md`'s sub-skill halt catch-all says.
|
|
13
13
|
3. `bmad-testarch-trace` (re)builds the traceability matrix and writes the gate decision.
|
|
14
14
|
|
|
15
|
-
`bmad-testarch-nfr` (produces `nfr-assessment.md`) and `bmad-testarch-test-review` are independent of each other and of trace, so once step 2 is done, run them in any order, or concurrently with trace. None of the three may edit a file in the worktree, so none of them runs a mutant: an assessor that would probe one names the mutant it would run as a finding in its own artifact instead, and when you delegate NFR or test review, tell it so. `gate_eval.py` consumes all three artifacts without caring how they were produced. (`bmad-testarch-test-review` normally runs in Execute per story: run it here only if you lack a current `test-review.md` for the story. One written before automate's backfill is not current, since no review has read the tests the backfill added.) In **`--light`**, skip all of the above and run only `bmad-testarch-trace`, then the gate with `--profile light` (trace gate only, with no NFR/review AND).
|
|
15
|
+
`bmad-testarch-nfr` (produces `nfr-assessment.md`) and `bmad-testarch-test-review` are independent of each other and of trace, so once step 2 is done, run them in any order, or concurrently with trace, except that no two of them run tests at once under a scratch runner config that gives the worktree's runs their own server ("A server the gate set reuses does not follow the commit" below): each such run starts that server on the one port the config names, so a second one would find the port taken and run no test. None of the three may edit a file in the worktree, so none of them runs a mutant: an assessor that would probe one names the mutant it would run as a finding in its own artifact instead, and when you delegate NFR or test review, tell it so. `gate_eval.py` consumes all three artifacts without caring how they were produced. (`bmad-testarch-test-review` normally runs in Execute per story: run it here only if you lack a current `test-review.md` for the story. One written before automate's backfill is not current, since no review has read the tests the backfill added.) In **`--light`**, skip all of the above and run only `bmad-testarch-trace`, then the gate with `--profile light` (trace gate only, with no NFR/review AND).
|
|
16
16
|
|
|
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
|
|
|
@@ -47,7 +47,7 @@ The new commit is now the commit under assessment: the worktree is rebuilt at it
|
|
|
47
47
|
|
|
48
48
|
**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
49
|
|
|
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. 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.
|
|
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.
|
|
51
51
|
|
|
52
52
|
**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
53
|
|
|
@@ -55,7 +55,7 @@ The new commit is now the commit under assessment: the worktree is rebuilt at it
|
|
|
55
55
|
|
|
56
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.
|
|
57
57
|
- 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
|
-
- 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 load a conftest.py, or jest or
|
|
58
|
+
- 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 when a Node test file's process exits non-zero after the row's test passes or is skipped, 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 of the same name passes or is skipped in a file Node lists before it, or when the last thing Node prints for that file is an uncaught error that a child process printed), 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
59
|
|
|
60
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 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:
|
|
61
61
|
|
|
@@ -67,15 +67,16 @@ A line closes when an automate pass at a later commit than the one the line name
|
|
|
67
67
|
|
|
68
68
|
## Measure the commit, not the working tree
|
|
69
69
|
|
|
70
|
-
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.
|
|
70
|
+
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:
|
|
71
71
|
|
|
72
72
|
- **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.
|
|
73
73
|
- **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.
|
|
74
|
+
- **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 that answers is not the gate's to stop. 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 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 answers before it runs the next one. 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.
|
|
74
75
|
- **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.
|
|
75
76
|
|
|
76
|
-
**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. 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.
|
|
77
|
+
**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.
|
|
77
78
|
|
|
78
|
-
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.
|
|
79
|
+
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.
|
|
79
80
|
|
|
80
81
|
## Non-web stack: the red phase by hand, and the trace artifacts where trace cannot run
|
|
81
82
|
|
|
@@ -162,6 +163,8 @@ Resolve `{nfr-assessment.md}` and `{test-review.md}` to the paths TEA wrote them
|
|
|
162
163
|
|
|
163
164
|
Do not recompute TEA thresholds or re-judge `gate_status` — read it as given. The script already ANDs the production signals (an `advance` is downgraded to `reloop` if `nfr-assessment.md` overallStatus is FAIL, or `test-review.md` score < 80 or recommendation is Block). Record the full verdict JSON and its `reasons` in `.decision-log.md` for this story.
|
|
164
165
|
|
|
166
|
+
**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. 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`.
|
|
167
|
+
|
|
165
168
|
**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.
|
|
166
169
|
|
|
167
170
|
**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.
|
|
@@ -17,8 +17,8 @@ Pass the profile Stage 1 confirmed: `--profile light` on a `--light` run, `--pro
|
|
|
17
17
|
```
|
|
18
18
|
{green: bool, budget: int,
|
|
19
19
|
blockers: [{id, kind, severity, detail, remediable: bool}],
|
|
20
|
-
checks: {cc_version, goal_ok, workflows_ok, automemory_ok,
|
|
21
|
-
git_unborn, framework_present, framework_kind, test_artifacts_dirs,
|
|
20
|
+
checks: {cc_version, goal_ok, workflows_ok, automemory_ok, hook_onfailure_ok,
|
|
21
|
+
git_branch, git_clean, git_unborn, framework_present, framework_kind, test_artifacts_dirs,
|
|
22
22
|
sprint_status_present, project_context_count, tea_flags, tea_skills, story_skills,
|
|
23
23
|
impl_artifacts_tracked}}
|
|
24
24
|
```
|
|
@@ -193,22 +193,31 @@ Do these in order; each must be asserted, not assumed:
|
|
|
193
193
|
- **Epic branch.** Assert you are on `{workflow.epic_branch_prefix}<epic-id>`. When step 1 reported `git_branch`, step 2's remediation already created it, and this is a **re-assertion, not a rebuild** — the same treatment the resume path gives it. Create it here when it does not yet exist — and note that `budget == 0` does **not** by itself put you on it: `git_branch` fires on a protected branch and nothing else, so a run started on some unrelated feature branch clears the gate having never been asked about its branch, and step 2 has no bullet that fires for it. That case lands here, so resolve it here rather than routing back: check out the base this Epic should branch from (a `{workflow.protected_branches}` branch, per execute.md's "off a protected branch" precondition — or the base the operator named in Stage 1) and cut `{workflow.epic_branch_prefix}<epic-id>` from there. Do **not** branch from wherever HEAD happens to sit; an Epic branch cut off an unrelated feature branch carries that branch's uncommitted work into the run's history and makes the branch-deletion rollback destructive. Rollback for this run is git (per-story commits) — `/rewind` checkpoints miss Bash-driven changes, so the branch is the real undo. If the tree is dirty (`git_clean: false`), resolve before branching — the last budget re-run was at the end of step 2, and step 3 has since written its scan sidecar and appended to `.decision-log.md`, so `budget == 0` does **not** imply a clean tree by the time you arrive here (`git_clean` counts untracked files).
|
|
194
194
|
- **What the branch does not undo.** Deleting this branch undoes what git tracks. When step 1 reported `impl_artifacts_tracked: false`, git ignores what the run writes under `{workflow.implementation_artifacts}`, so it undoes the code only: the story files the run creates there survive it, and so does every edit to a file there that git does not track (`sprint-status.yaml` or `deferred-work.md`, unless the project tracks them). Whatever that value, the run folder (`.decision-log.md`, a ruling file) and the test-artifacts tree survive too when git ignores them: check a file path inside each with `git check-ignore`, since a rule that ignores a folder's contents does not match the bare folder. Exit 0 means ignored and 1 means not; 128 means the path is outside the repository or beyond a symlink, which git does not track either. The launch briefing says what survives.
|
|
195
195
|
- **Purge stale run markers.** Delete any `{workflow.implementation_artifacts}/.escalation-*`, `{workflow.implementation_artifacts}/.on-escalation-fired-*`, `{workflow.implementation_artifacts}/.budget-*`, `{workflow.implementation_artifacts}/.heartbeat-*` and `{workflow.implementation_artifacts}/.stall-*` an earlier run left behind, before the hooks that write them are armed: a stale escalation marker makes this run look like it already escalated, a stale fired-marker silently swallows this run's first escalation ping, which is the one an absent operator is waiting on, and a stale turn counter is already at or past the ceiling, so this run's **first** Stop marks the story at the ceiling, and a resume's step-0 ceiling check escalates it, before it has done a single turn of work, and a stale heartbeat's gap since the PRIOR run would fire this run's stall rule on its first resume about an idle nobody had. Those five dot-prefixed families only. **On a resume, purge nothing.** A resume re-asserts the environment rather than rebuilding it, and the turn counter is the one piece of that environment a resume must inherit: zeroing `.budget-*` on re-entry would hand an in-flight story a fresh ceiling every time it stopped, so a run could evade the budget indefinitely by resuming. A counter the operator has deliberately cleared is a different thing, and `/ucg-resolve` clears exactly that one when it closes a `budget-overrun` or an `operator-evidence-owed` escalation. In particular do **not** delete `escalation-*.json`: the typed sidecar is an operator-facing artifact like `run-status.json` and `run-result.json`, neither of which is purged at arming either, and it is named per story rather than per run, so arming cannot tell a deliberately-pending sidecar from a stale one. A decision the operator chose to leave pending lives in exactly that file, and a prior run's unresolved escalation surfacing at `/ucg-resolve` is correct: it genuinely is still pending. Sidecar staleness is handled at read time instead, by the run-scoped marker scan in `references/execute.md`. **The story pointer is the exception to both rules.** On a fresh run and a resume alike, delete `{workflow.implementation_artifacts}/.current-story`. No stage removes it, Finalize included, so on arrival here it names whichever story an earlier session drove last: once this run's Stop hook is armed, every Stop before this invocation's first step 0 (the launch briefing's included) is booked to that story's counter (on a fresh run, recreating the one this purge just removed), and the freshly armed guard would take that story's persisted tests-ran marker as current. A resume is not exempt, because a run that blocked here and was re-invoked re-enters at this stage as a resume, with an earlier run's pointer still on disk. Deleting it costs nothing a later step needs: step 0 writes it afresh before any implementation, the gate-owed route and the evidence-commit resume each re-set it themselves, and with no pointer the Stop hook counts nothing.
|
|
196
|
-
- **Hooks.** Idempotently merge the **PreToolUse** guard (`scripts/hooks/guard_pretooluse.py`) and the **Stop** budget hook (`scripts/hooks/budget_stop.py`) into `{project-root}/.claude/settings.local.json` (gitignored, machine-local, honored after the workspace trust dialog). Re-merge every run
|
|
196
|
+
- **Hooks.** Idempotently merge the **PreToolUse** guard (`scripts/hooks/guard_pretooluse.py`) and the **Stop** budget hook (`scripts/hooks/budget_stop.py`) into `{project-root}/.claude/settings.local.json` (gitignored, machine-local, honored after the workspace trust dialog). Re-merge every run: do not assume a prior run left them. A merge that would change nothing makes no write: when the file's UCG entries already match what this run would write (both script paths, the all-tools matcher, the guard item's `"onFailure": "block"`, each command quoted as the templates below write it, and every injected value equal to this run's resolved scalars) and the allowlist entries are present, assert instead of writing. `--assert-armed` alone is not that comparison, because it confirms the injected variables are present, not that their values are this run's. A write that is refused follows "A refused settings write" in step 2.
|
|
197
197
|
|
|
198
198
|
**Replace, never append.** When the merge writes, it first removes every inner item whose `command` names either script, and then adds this run's, so a prior run's entry (one a skipped disarm left, or one carrying another run's injected env) cannot sit beside the fresh one. `--assert-armed` checks that the script paths appear, not how many entries carry them, so it would pass with both.
|
|
199
199
|
|
|
200
|
+
**Arm the guard so that a guard that fails refuses the call.** Each UCG inner item is a `command` hook. The guard's item carries `"onFailure": "block"` beside `"type"` and `"command"`; the budget hook's item carries no `onFailure` key. Written out, with `<env>` the `KEY='value'` prefix the env bullet below injects (empty when the process env carries those values):
|
|
201
|
+
|
|
202
|
+
- guard: `{"type": "command", "command": "<env> uv run '{skill-root}/scripts/hooks/guard_pretooluse.py'", "onFailure": "block"}`
|
|
203
|
+
- budget: `{"type": "command", "command": "<env> uv run '{skill-root}/scripts/hooks/budget_stop.py'"}`
|
|
204
|
+
|
|
205
|
+
With the key, Claude Code refuses the tool call when the guard cannot start (`uv` missing from `PATH`, say), crashes, exits with a code other than 0 or 2, or times out. Without it each of those lets the call run unchecked, because Claude Code reads a hook that failed as no objection. Claude Code honors the key from 2.1.295, the minimum step 1's `cc_version` check enforces; an older one ignores it silently. Write the value exactly `"block"`, in lower case: Claude Code drops a whole item whose `onFailure` is any value other than `"continue"` or `"block"`, so a mistyped one leaves no guard at all. The cost comes with the all-tools matcher below. A guard that cannot run refuses every tool call, Read and Edit included, so the session cannot repair it, and the fix is made outside the session: put `uv` back on `PATH`, or mend whatever else broke, or remove the guard item from `.claude/settings.local.json` by hand as SECURITY.md describes, then resume the run. The Stop budget hook carries no `onFailure`: Claude Code ignores the key on `Stop`, and the budget hook never blocks a stop by design, so it has no failure the key could turn into a refusal. A run armed before this key existed (by UCG 3.x or earlier) has a guard item without it: a fresh preflight replaces that item here, and a resume, which never reaches this stage, re-merges through this bullet when its `--assert-armed` names the missing key (`references/execute.md`, the re-assertion sweep).
|
|
206
|
+
|
|
207
|
+
**Quote each injected value and the script path in single quotes, as the templates do.** Claude Code runs the command through a shell, which splits it at every unquoted space. Left unquoted, a project or skill path that holds a space (a project under `~/My Projects`, say) hands the rest of that path to the shell as the command to run, or to `uv run` as the script, so the hook never starts: Claude Code then refuses every tool call under the guard's key, and skips the budget hook without a word. Single quotes keep each value and the path one word, as the recall store value is kept (`references/ingest-and-scope.md`); write a single quote inside a value as `'\''`. `--assert-armed` reads each UCG hook command the way the shell splits it, and fails one that would not start its script as `<env> uv run <script>`.
|
|
208
|
+
|
|
200
209
|
**Arm the PreToolUse group with a matcher that covers EVERY tool, not just `Bash`.** Use `"matcher": "*"`, or omit the `matcher` key entirely the way the `Stop` group already does. Five of the guard's seven invariants are Bash/git, so `Bash` is the natural choice and it is the choice both known installs made, but the other two, the Cross-Session Recall latch rules, gate other tools too. While a latch is present the guard denies Read, Grep, Glob, Write, Edit, MultiEdit and NotebookEdit calls that name the recall store, the file-tool calls that would change the latch itself, and every claude-mem MCP call. Claude Code only invokes a PreToolUse group for tools its matcher selects, so under `Bash` the hook is never run for any of those calls: the guard would deny each one correctly if it were asked, and it is never asked. Those two then enforce nothing outside Bash while every log line says the hooks are armed, which is the worst of both: a control that reports itself active and is not.
|
|
201
210
|
|
|
202
|
-
Then **assert they are active**: re-read the resolved settings and confirm both script paths appear **and** that the PreToolUse group's matcher is the all-tools form. A presence-only assertion passes on a `Bash`-only arming, which is exactly the state this bullet exists to prevent. The same assertion is scriptable: `preflight_check.py --assert-armed` performs it (branch, both hooks under their own events, matcher form, injected env, and the UCG story skills `ucg-create-story` and `ucg-dev-story`) in one read and fail-closes with named reasons. Pass `--epic-branch-prefix {workflow.epic_branch_prefix}` and one `--protected-branch <name>` per entry in `{workflow.protected_branches}`, exactly as step 1 does: omit either and it asserts the branch against its hardcoded defaults (`ultracode/epic-`, `main, master`), silently no-opping those overrides and failing a correctly armed run on a false RED. The resume path leans on it (`references/execute.md`), and it is equally valid here. It reads `.claude/settings.local.json`, the file this bullet's arming writes, so an arming that lives in another settings layer fail-closes, which is the correct answer for a control this stage must be able to disarm and re-merge. Invariants that live only in memory are context, not enforcement, and memory does not block a `git commit`.
|
|
203
|
-
- **Inject the hook env from the resolved scalars.** Both hooks read config from env first ("env wins so the conductor can inject per run") and fall back to hardcoded defaults (`main/master`, `25`, `ultracode/epic-`) otherwise
|
|
204
|
-
- `ULTRACODE_PROTECTED_BRANCHES={workflow.protected_branches}` (comma-separated)
|
|
205
|
-
- `ULTRACODE_IMPL_ARTIFACTS={workflow.implementation_artifacts}`
|
|
206
|
-
- `ULTRACODE_MAX_TURNS={workflow.max_turns_per_story}`
|
|
207
|
-
- `ULTRACODE_EPIC_BRANCH_PREFIX={workflow.epic_branch_prefix}`
|
|
208
|
-
- `ULTRACODE_TEST_ARTIFACTS
|
|
211
|
+
Then **assert they are active**: re-read the resolved settings and confirm both script paths appear **and** that the PreToolUse group's matcher is the all-tools form **and** that every guard item carries `"onFailure": "block"` **and** that each UCG command quotes its injected values and script path. A presence-only assertion passes on a `Bash`-only arming, which is exactly the state this bullet exists to prevent. The same assertion is scriptable: `preflight_check.py --assert-armed` performs it (branch, both hooks under their own events, matcher form, the guard's `onFailure`, how the shell splits each UCG command, injected env, and the UCG story skills `ucg-create-story` and `ucg-dev-story`) in one read and fail-closes with named reasons. Pass `--epic-branch-prefix {workflow.epic_branch_prefix}` and one `--protected-branch <name>` per entry in `{workflow.protected_branches}`, exactly as step 1 does: omit either and it asserts the branch against its hardcoded defaults (`ultracode/epic-`, `main, master`), silently no-opping those overrides and failing a correctly armed run on a false RED. The resume path leans on it (`references/execute.md`), and it is equally valid here. It reads `.claude/settings.local.json`, the file this bullet's arming writes, so an arming that lives in another settings layer fail-closes, which is the correct answer for a control this stage must be able to disarm and re-merge. Invariants that live only in memory are context, not enforcement, and memory does not block a `git commit`.
|
|
212
|
+
- **Inject the hook env from the resolved scalars.** Both hooks read config from env first ("env wins so the conductor can inject per run") and fall back to hardcoded defaults (`main/master`, `25`, `ultracode/epic-`) otherwise, so a `customize.toml` override of any of these **silently no-ops at the enforcement layer** unless you pass it through. Set these on the hook commands (in the `settings.local.json` hook `command`, each value in single quotes as the templates above write them: `KEY='value' uv run '…'`) or in the process env the hooks inherit:
|
|
213
|
+
- `ULTRACODE_PROTECTED_BRANCHES='{workflow.protected_branches}'` (comma-separated)
|
|
214
|
+
- `ULTRACODE_IMPL_ARTIFACTS='{workflow.implementation_artifacts}'`
|
|
215
|
+
- `ULTRACODE_MAX_TURNS='{workflow.max_turns_per_story}'`
|
|
216
|
+
- `ULTRACODE_EPIC_BRANCH_PREFIX='{workflow.epic_branch_prefix}'`
|
|
217
|
+
- `ULTRACODE_TEST_ARTIFACTS='<the resolved TEA test-artifacts root>'`: deliberately **not** a `{workflow.…}` scalar (no such workflow key exists, and a `{workflow.test_artifacts}` placeholder would never be filled by config resolution). Inject the same root TEA config resolution yields (`scripts/preflight_check.py`, `_tea_artifacts_root`): the tea-config `test_artifacts` value with `{project-root}` substituted (a relative value resolves under the project root), defaulting to `{project-root}/_bmad-output/test-artifacts` when tea config names none. This is the directory the guard reads the story's `atdd-checklist-<story-id>.md` from; leave it unset and the un-skip proof below is out of scope and silently enforces nothing.
|
|
209
218
|
- The same PreToolUse guard also enforces the Cross-Session Recall latch from `{workflow.implementation_artifacts}/.mem-state.json`: the merged hook reads it automatically, fail-closed, with no new env var to inject. While a latch is present, whatever its version or colour, it denies every claude-mem call; every tool call that names the recall store, except the two pinned recall scripts (`scripts/mem_recall.py` and `scripts/mem_observation.py` under `uv run` or python); and every tool call that would change the latch itself, except those same scripts. Reading the latch stays allowed. **It enforces nothing unless the matcher above covers every tool**, because most of what it denies is a file-tool or MCP call, and a group matched on `Bash` is never invoked for one. This is the invariant that makes the all-tools matcher load-bearing rather than tidy.
|
|
210
219
|
- **Un-skip proof (production only).** With `ULTRACODE_TEST_ARTIFACTS` injected, the guard reads the **staged post-image** of every acceptance-test file the story's `atdd-checklist-<story-id>.md` lists in its `generatedTestFiles` frontmatter (`git show :<path>`) and denies the commit while any of them still contains `test.skip(`. A checklist with no such list, or one that names no JS/TS test file, is scanned whole for test-file paths instead, and a list that cannot be read as a list denies. It proves the marker is absent from the blob being committed, so it fires on a story's *first* commit too, where there is no prior blob to diff against. Caveat worth stating plainly: **`test.skip(` is a JS/Vitest-specific token** (the Playwright/Vitest form TEA's ATDD generates today, which is web/JS-only), so a pytest (`@pytest.mark.skip`) or Go (`t.Skip()`) stack marks skips differently and this check would not see them. Under `--light` there is no atdd-checklist, so the check stays inert.
|
|
211
|
-
- **The commit/push guard anchors on each segment's leading token (`fp-7ac2643`).** The guard splits the command into shell segments and flags one only when `git` is that segment's **leading** token, once leading `VAR=val` assignments, shell keywords and group openers (`if`/`then`/`else`/`fi`, `for`/`while`/`until`/`do`/`done`, `case`/`esac`, `!`, and `(`/`{`, whether spaced or glued to the command name), and known exec wrappers (`env`, `command`, `sudo`, `time`, `nice`, `nohup`, `timeout`, `setsid`, `stdbuf`, `ionice`, `doas`, plus the string payload of a `sh|bash|zsh|dash` invoked with any `-c`-bearing flag cluster, `-lc` and `-cx` included) are stripped, and the subcommand it would then run is exactly `commit` or `push`, or any subcommand that is not one of git's built-in commands (spelled as git spells them), which counts as both, since what an alias runs, or whether an external `git-<name>` command shadows it, cannot be read from the command: so a git alias, even a read-only one (an alias `st` for `status`), and an external command run through git meet the commit and push gates, and the deny says to run the git command an alias stands for, or the external command by its own name. The keyword strip is what keeps a commit inside a compound command (`if true; then git commit …; fi`, `for … do git commit … done`, `( git commit … )`) reachable by the gates: without it a keyword sits in the leading position, the segment classifies as carrying no git write, and the protected-branch, tests-ran, freshness and empty-index gates are all skipped at once. Segment splitting covers `&&`, `||`, `;`, `|`, a newline, **and a lone `&`** (`npm run build & git commit …` is two segments, not one); those separator sets are applied as a **union** rather than merged into one regex, because splitting on `&` or a newline is quote-blind and a lone set would tear `git -c alias.x='a&b' commit` into fragments that each escape detection. So a verb merely *mentioned* inside an `echo`, a log line, or a here-string in a verification command is no longer denied, while a real `FOO=bar git commit`, `sudo git commit` or `timeout 30 git commit` still is: on a `{workflow.protected_branches}` branch both verbs are denied, and on the epic branch, before the story's `.tests-ran-<story_id>` marker exists, a real `git commit` is denied (the marker gate is commit-only: a real `git push` is never marker-gated). Residual, stated rather than hidden: a wrapper **not** on that list (`xargs git commit`, say) leaves a non-`git` leading token and is allowed through, so the tests-ran marker and the remote's branch protection are the nets behind this one. Three shapes still take the older matches-anywhere path and deny on a mention: a segment whose quoting cannot be parsed, one that hides its command inside a `$(…)` substitution or backticks, and, the newest, a **listed** shell wrapper (`sh|bash|zsh|dash`) whose command-string payload cannot be located at all, meaning no `-c`-bearing flag cluster with an operand after it, or nesting deeper than the shell-recursion cap. That third lane exists because locating the payload by the bare token `-c` alone missed every combined form (`bash -lc`, `sh -lc`, `bash -cx`, `zsh -ic`), and a wrapper whose payload went unread classified as carrying no git write and skipped all four commit gates. It is fail-closed in the same direction as the other two, and it has the same cost: `bash <script> "…git commit…"` now denies on the mention, so a verification command's own arguments must not spell a write verb. **Do not read the anchoring as having eliminated the false-positive class: it narrowed it, and the remainder bites prose about commits in particular.** Markdown prose names identifiers in backticks, and an apostrophe (`don't`) is unbalanced quoting, so a run-log line describing a commit denial routinely hits both fallbacks; a line that *leads* with the verb is a real verb-leading segment and denies on its own, and so does a line that leads with `git` and a word that is not one of git's commands. The rule that avoids all of it: **write prose with Write/Edit, never a Bash heredoc.** The guard's git gates read **Bash command strings alone**, so a decision-log append made with the file tools reaches none of them and no phrasing of the log can trip a gate. Now that the group is armed for every tool, the hook IS invoked for a `Write`, and it does decide on file tools, but only through its Cross-Session Recall rules: it denies a file-tool call that names the recall store or would change the run latch, and a decision-log append is neither, so it passes. Do not narrow the matcher back to `Bash` on the strength of this clause: that would leave those rules enforcing nothing. Reserve Bash for commands you actually mean to run. (execute.md step 4 covers the narrower marker-written-in-the-same-compound-command trap.)
|
|
220
|
+
- **The commit/push guard anchors on each segment's leading token (`fp-7ac2643`).** The guard splits the command into shell segments and flags one only when `git` is that segment's **leading** token, once leading `VAR=val` assignments, shell keywords and group openers (`if`/`then`/`else`/`fi`, `for`/`while`/`until`/`do`/`done`, `case`/`esac`, `!`, and `(`/`{`, whether spaced or glued to the command name), and known exec wrappers (`env`, `command`, `sudo`, `time`, `nice`, `nohup`, `timeout`, `setsid`, `stdbuf`, `ionice`, `doas`, plus the string payload of a `sh|bash|zsh|dash` invoked with any `-c`-bearing flag cluster, `-lc` and `-cx` included) are stripped, and the subcommand it would then run is exactly `commit` or `push`, or any subcommand that is not one of git's built-in commands (spelled as git spells them), which counts as both, since what an alias runs, or whether an external `git-<name>` command shadows it, cannot be read from the command: so a git alias, even a read-only one (an alias `st` for `status`), and an external command run through git meet the commit and push gates, and the deny says to run the git command an alias stands for, or the external command by its own name. The keyword strip is what keeps a commit inside a compound command (`if true; then git commit …; fi`, `for … do git commit … done`, `( git commit … )`) reachable by the gates: without it a keyword sits in the leading position, the segment classifies as carrying no git write, and the protected-branch, tests-ran, freshness and empty-index gates are all skipped at once. Segment splitting covers `&&`, `||`, `;`, `|`, a newline, **and a lone `&`** (`npm run build & git commit …` is two segments, not one); those separator sets are applied as a **union** rather than merged into one regex, because splitting on `&` or a newline is quote-blind and a lone set would tear `git -c alias.x='a&b' commit` into fragments that each escape detection. So a verb merely *mentioned* inside an `echo`, a log line, or a here-string in a verification command is no longer denied, while a real `FOO=bar git commit`, `sudo git commit` or `timeout 30 git commit` still is: on a `{workflow.protected_branches}` branch both verbs are denied, and on the epic branch, before the story's `.tests-ran-<story_id>` marker exists, a real `git commit` is denied (the marker gate is commit-only: a real `git push` is never marker-gated). Residual, stated rather than hidden: a wrapper **not** on that list (`xargs git commit`, say) leaves a non-`git` leading token and is allowed through, so the tests-ran marker and the remote's branch protection are the nets behind this one. Three shapes still take the older matches-anywhere path and deny on a mention: a segment whose quoting cannot be parsed, one that hides its command inside a `$(…)` substitution or backticks, and, the newest, a **listed** shell wrapper (`sh|bash|zsh|dash`) whose command-string payload cannot be located at all, meaning no `-c`-bearing flag cluster with an operand after it, or nesting deeper than the shell-recursion cap. That third lane exists because locating the payload by the bare token `-c` alone missed every combined form (`bash -lc`, `sh -lc`, `bash -cx`, `zsh -ic`), and a wrapper whose payload went unread classified as carrying no git write and skipped all four commit gates. It is fail-closed in the same direction as the other two, and it has the same cost: `bash <script> "…git commit…"` now denies on the mention, so a verification command's own arguments must not spell a write verb. Two more shapes fail closed. A segment whose command sits behind a run of more than 32 exec wrappers is read through the first 32 only, and counts as both a commit and a push whatever follows them. And a command the guard cannot classify at all, because reading it raised an error, is denied outright, whatever it holds, as is a commit or push whose checks raise one, and so is any other call the guard raises an error while deciding on (an event or a Bash input that is not a JSON object, JSON nested past what Python reads), with the error named, so the guard exits 0 or 2 and nothing else. What it cannot catch itself (an interpreter or `uv` that cannot start, a timeout) Claude Code refuses, under the guard item's `"onFailure": "block"` above; without that key a hook that ends on an error makes no decision, and the command would go through, as one led by about a thousand `env` words once did. **Do not read the anchoring as having eliminated the false-positive class: it narrowed it, and the remainder bites prose about commits in particular.** Markdown prose names identifiers in backticks, and an apostrophe (`don't`) is unbalanced quoting, so a run-log line describing a commit denial routinely hits both fallbacks; a line that *leads* with the verb is a real verb-leading segment and denies on its own, and so does a line that leads with `git` and a word that is not one of git's commands. The rule that avoids all of it: **write prose with Write/Edit, never a Bash heredoc.** The guard's git gates read **Bash command strings alone**, so a decision-log append made with the file tools reaches none of them and no phrasing of the log can trip a gate. Now that the group is armed for every tool, the hook IS invoked for a `Write`, and it does decide on file tools, but only through its Cross-Session Recall rules: it denies a file-tool call that names the recall store or would change the run latch, and a decision-log append is neither, so it passes. Do not narrow the matcher back to `Bash` on the strength of this clause: that would leave those rules enforcing nothing. Reserve Bash for commands you actually mean to run. (execute.md step 4 covers the narrower marker-written-in-the-same-compound-command trap.)
|
|
212
221
|
- **Allowlist.** Pre-populate the tool allowlist with `{workflow.allowlist_commands}` so the unattended run can run tests/lint/build/commit without a permission prompt that no one is there to approve. Write one `Bash(<entry>:*)` allow rule per entry, with the entry exactly as it stands (`Bash(git worktree:*)` for `git worktree`). That rule matches the entry alone, or the entry, a space and anything after it, which is how `git worktree` covers the gate's `git worktree add <tmp-path> <commit>`. A rule without `:*` matches one exact command, so the stage's own calls would stop for approval. The entries land in the same `settings.local.json`, so a refused write here follows the same rule.
|
|
213
222
|
|
|
214
223
|
### Launch briefing (interactive only)
|
|
@@ -18,7 +18,8 @@ this script forms no judgment of its own and produces no verdict:
|
|
|
18
18
|
| acceptance criterion | acceptance checklist | trace report coverage |
|
|
19
19
|
| planned test | acceptance checklist | trace report coverage |
|
|
20
20
|
| result | acceptance checklist | trace report coverage |
|
|
21
|
-
| gate verdict |
|
|
21
|
+
| gate verdict | `escalate` while its escalation is open, else |
|
|
22
|
+
| | the recorded verdict, else gate_status mapped |
|
|
22
23
|
| | through gate_eval.GATE_VERDICT |
|
|
23
24
|
| commit | git log over the story's baseline range |
|
|
24
25
|
|
|
@@ -26,10 +27,27 @@ The verdict cell is `gate_eval.GATE_VERDICT[gate_status]` and nothing else. An
|
|
|
26
27
|
unrecognized gate_status is rendered verbatim rather than re-classified, and the
|
|
27
28
|
production AND is NEVER re-applied here: it already ran when the gate decided,
|
|
28
29
|
and re-running it at finalize would be a second, later judgment. When the run
|
|
29
|
-
recorded its own verdict for a story (a
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
30
|
+
recorded its own verdict for a story (a JSON object carrying a `verdict` key,
|
|
31
|
+
fenced or inline in backticks, under that story's heading in `.decision-log.md`,
|
|
32
|
+
which `references/gate.md` has the run write before each gate cycle as
|
|
33
|
+
`### Story <story_id>: gate`), that recorded verdict wins over the mapped one,
|
|
34
|
+
because it is what the run actually acted on - including any downgrade the gate
|
|
35
|
+
applied at decision time.
|
|
36
|
+
|
|
37
|
+
A story whose escalation is still open renders `escalate`, whatever verdict the
|
|
38
|
+
log or the gate artifact holds. The `escalate` route stops AFTER logging the
|
|
39
|
+
verdict it escalated from: a FAIL only operator evidence can change, or a
|
|
40
|
+
re-loop past the turn ceiling, leaves `gate_eval.py`'s `reloop` as the only
|
|
41
|
+
verdict JSON in the log, and FAIL maps to `reloop` too, so without this the
|
|
42
|
+
trail showed a story waiting on operator evidence as one owing a code fix. Open
|
|
43
|
+
is read exactly as a resume reads it (`preflight_check._escalation_of`): the
|
|
44
|
+
typed sidecar `escalation-<story>.json` is on disk, its id is not closed, and
|
|
45
|
+
its kind is not a handoff. A story whose sprint-status row reads `done`
|
|
46
|
+
advanced, so a sidecar beside it is not where it stopped: one an older run left
|
|
47
|
+
beside a story that later advanced is residue, and is not rendered. The one
|
|
48
|
+
kind the advance route itself writes, `evidence-commit-rejected`, owes a commit
|
|
49
|
+
and not a verdict: the story keeps the verdict it advanced on, and its
|
|
50
|
+
verdict-source line names the open escalation.
|
|
33
51
|
|
|
34
52
|
The recorded verdict is honoured ONLY for a story whose own gate artifact
|
|
35
53
|
resolved. A verdict with no artifact behind it - recorded by an earlier
|
|
@@ -38,7 +56,10 @@ would render `advance` beside `Gate artifact: n/a` while `gate_eval.py` itself
|
|
|
38
56
|
would refuse the same story with NOT_EVALUATED -> escalate. The trail must not
|
|
39
57
|
disagree with the gate in the gate's own column, so such a story renders `n/a`
|
|
40
58
|
and its verdict-source line says why. The decision log still holds the verdict;
|
|
41
|
-
what this report declines to do is present it as gated evidence.
|
|
59
|
+
what this report declines to do is present it as gated evidence. An open
|
|
60
|
+
escalation is not bound by this rule: with no artifact the gate returns
|
|
61
|
+
`escalate` too, so the story renders `escalate` and its verdict-source line
|
|
62
|
+
says that no gate artifact resolved.
|
|
42
63
|
|
|
43
64
|
FAIL-SOFT. Every source is optional. A missing, short or unparseable file
|
|
44
65
|
renders `n/a` in its cell and the synthesis continues. This is the opposite of
|
|
@@ -133,8 +154,32 @@ _AMBIGUOUS_AC_HEADERS = frozenset({"id", "criterion", "criteria"})
|
|
|
133
154
|
# either would render test ids or file numbers as criteria.
|
|
134
155
|
_OVERRIDE_AC_HEADERS = frozenset(_AC_HEADERS - {"id", "acs"})
|
|
135
156
|
|
|
136
|
-
|
|
157
|
+
# A heading whose first word is `Story`, with the id after it and the rest of the
|
|
158
|
+
# line. Which of these name a story is `_story_heading_id`'s call: most are prose
|
|
159
|
+
# (`### Story ORDER: one deviation`), and a prose heading must not end a story's
|
|
160
|
+
# entries.
|
|
161
|
+
_STORY_HEADING = re.compile(
|
|
162
|
+
r"^(#{2,4})[ \t]+story[ \t]+([\w.\-]*\w)(.*)$", re.IGNORECASE | re.MULTILINE
|
|
163
|
+
)
|
|
164
|
+
# The rest of the line in the heading `references/gate.md` ("Run the gate") has
|
|
165
|
+
# the run write before each gate cycle: `### Story <story_id>: gate`.
|
|
166
|
+
_GATE_HEADING_TAIL = re.compile(r":[ \t]*gate[ \t]*", re.IGNORECASE)
|
|
137
167
|
_JSON_FENCE = re.compile(r"```(?:json)?\s*\n(\{.*?\})\s*\n```", re.DOTALL)
|
|
168
|
+
# A JSON object as a single-backtick code span, the way some runs log
|
|
169
|
+
# `gate_eval.py`'s result inside a sentence. `[^`]` keeps it inside one span.
|
|
170
|
+
_INLINE_JSON = re.compile(r"(?<!`)`(\{[^`]*\})`(?!`)")
|
|
171
|
+
# The per-story gate file a `gate_eval.py` result says it read, in its `reasons`
|
|
172
|
+
# (`gate read from gate-decision-<story>.json`). That wording is not a contract
|
|
173
|
+
# (docs/_internal/STABILITY.md), so it is used only to refuse a verdict object
|
|
174
|
+
# that names another story's file, never to accept one.
|
|
175
|
+
_GATE_READ_FROM = re.compile(
|
|
176
|
+
r"gate\s+read\s+from\s+(?:gate-decision|e2e-trace-summary)-([\w.\-]+?)\.json"
|
|
177
|
+
)
|
|
178
|
+
|
|
179
|
+
# The one escalation kind the gate's advance route writes (references/gate.md,
|
|
180
|
+
# "Commit the gate's evidence before the next story starts"): the story keeps its
|
|
181
|
+
# `advance` verdict, and only the evidence commit is owed.
|
|
182
|
+
EVIDENCE_COMMIT_REJECTED = "evidence-commit-rejected"
|
|
138
183
|
|
|
139
184
|
|
|
140
185
|
# --------------------------------------------------------------------------
|
|
@@ -552,12 +597,98 @@ def verdict_for(gate_status: str | None, recorded: str | None) -> str:
|
|
|
552
597
|
return gate_eval.GATE_VERDICT.get(gate_status.upper(), gate_status)
|
|
553
598
|
|
|
554
599
|
|
|
555
|
-
def
|
|
600
|
+
def _is_gate_heading(match: re.Match[str]) -> bool:
|
|
601
|
+
"""True iff a `_STORY_HEADING` match is the heading `references/gate.md` has
|
|
602
|
+
the run write before each gate cycle, `### Story <story_id>: gate`."""
|
|
603
|
+
level, _, tail = match.groups()
|
|
604
|
+
return level == "###" and bool(_GATE_HEADING_TAIL.fullmatch(tail))
|
|
605
|
+
|
|
606
|
+
|
|
607
|
+
def _story_heading_id(match: re.Match[str], keys: set[str]) -> str | None:
|
|
608
|
+
"""The story id a `_STORY_HEADING` match names, or None for a prose heading.
|
|
609
|
+
|
|
610
|
+
Three shapes name a story: an id that starts with a digit, as a numeric
|
|
611
|
+
sprint key does (`7-1`, `92-0a`), the shape this reader has always read; an
|
|
612
|
+
id that is one of `keys`, the keys sprint-status lists, so a letter-prefixed
|
|
613
|
+
key (`lp-0-1-...`) is read too; and the gate-cycle heading
|
|
614
|
+
(`_is_gate_heading`), whatever its id. Any other heading
|
|
615
|
+
(`### Story committed and re-verified`) is prose, and ends no story's
|
|
616
|
+
entries.
|
|
617
|
+
"""
|
|
618
|
+
ident = match.group(2)
|
|
619
|
+
if ident[0].isdigit() or ident in keys or _is_gate_heading(match):
|
|
620
|
+
return ident
|
|
621
|
+
return None
|
|
622
|
+
|
|
623
|
+
|
|
624
|
+
def _names_another_story(payload: dict, ident: str) -> bool:
|
|
625
|
+
"""True iff the object's `reasons` say it read another story's gate file.
|
|
626
|
+
|
|
627
|
+
A heading's span can run far past its own entries in a log that heads its
|
|
628
|
+
stories in another shape: measured on a real epic, one story's span held two
|
|
629
|
+
later stories' verdicts and none of its own.
|
|
630
|
+
"""
|
|
631
|
+
reasons = payload.get("reasons")
|
|
632
|
+
if not isinstance(reasons, list):
|
|
633
|
+
return False
|
|
634
|
+
for named in _GATE_READ_FROM.findall(" ".join(str(reason) for reason in reasons)):
|
|
635
|
+
if _components(named) and not (
|
|
636
|
+
_heading_matches_story(ident, named) or _heading_matches_story(named, ident)
|
|
637
|
+
):
|
|
638
|
+
return True
|
|
639
|
+
return False
|
|
640
|
+
|
|
641
|
+
|
|
642
|
+
def _first_verdict(span: str, ident: str) -> str | None:
|
|
643
|
+
"""The verdict of the first JSON object in `span` that is story `ident`'s.
|
|
644
|
+
|
|
645
|
+
Read fenced or inline, in the order they stand. An object carrying
|
|
646
|
+
`"epic_level": true` is the Epic-level gate's roll-up, which follows the
|
|
647
|
+
last story's entries under no story heading of its own, so it is never a
|
|
648
|
+
story's verdict, and neither is one whose `reasons` name another story's
|
|
649
|
+
gate file. `strict=False` lets a string a log wrapped across lines still
|
|
650
|
+
parse.
|
|
651
|
+
"""
|
|
652
|
+
found = sorted(
|
|
653
|
+
[(m.start(), m.group(1)) for m in _JSON_FENCE.finditer(span)]
|
|
654
|
+
+ [(m.start(), m.group(1)) for m in _INLINE_JSON.finditer(span)]
|
|
655
|
+
)
|
|
656
|
+
for _, raw in found:
|
|
657
|
+
try:
|
|
658
|
+
payload = json.loads(raw, strict=False)
|
|
659
|
+
except (ValueError, TypeError):
|
|
660
|
+
continue
|
|
661
|
+
if not isinstance(payload, dict) or not payload.get("verdict"):
|
|
662
|
+
continue
|
|
663
|
+
if payload.get("epic_level") or _names_another_story(payload, ident):
|
|
664
|
+
continue
|
|
665
|
+
return str(payload["verdict"])
|
|
666
|
+
return None
|
|
667
|
+
|
|
668
|
+
|
|
669
|
+
def recorded_verdicts(decision_log: Path | None, keys: set[str] | None = None) -> dict[str, str]:
|
|
556
670
|
"""Verdicts the run recorded per story in its decision log.
|
|
557
671
|
|
|
558
|
-
A story heading
|
|
559
|
-
|
|
560
|
-
|
|
672
|
+
A story heading (`_story_heading_id`, with `keys` the sprint-status keys)
|
|
673
|
+
followed by a JSON object carrying a `verdict` key, fenced or inline in
|
|
674
|
+
backticks, is read as the verdict the run acted on. Prose headings without
|
|
675
|
+
such an object contribute nothing, which is the common case.
|
|
676
|
+
|
|
677
|
+
A heading's entries run to the next story heading, so the FIRST verdict
|
|
678
|
+
object after it is its own: a log whose later stories are headed in another
|
|
679
|
+
shape puts their verdicts in an earlier story's span, and the Epic-level
|
|
680
|
+
roll-up follows the last story's (`_first_verdict` skips the roll-up, and
|
|
681
|
+
any object whose `reasons` name another story's gate file). A later heading
|
|
682
|
+
for the same id whose span holds a verdict object replaces the earlier
|
|
683
|
+
verdict. `references/gate.md` ("Run the gate") has the run write
|
|
684
|
+
`### Story <story_id>: gate` before each gate cycle, so a later heading in
|
|
685
|
+
that shape is a later cycle, and when its span holds no verdict object it
|
|
686
|
+
drops the earlier one: the trail falls back to the gate artifact rather
|
|
687
|
+
than show an earlier cycle's verdict, and the story's last cycle decides.
|
|
688
|
+
Any other later heading for the id (`### Story 7-1: re-loop 1`, a note on
|
|
689
|
+
what the re-loop owes) is no cycle, so with no verdict object of its own it
|
|
690
|
+
keeps the verdict before it: a downgraded or capped `reloop` followed by a
|
|
691
|
+
re-loop's notes must not read as the gate file's mapped `advance`.
|
|
561
692
|
|
|
562
693
|
Keyed by the heading's id VERBATIM. It used to be keyed by
|
|
563
694
|
`numeric_prefix(...)`, which collapsed every alphanumeric child id of one
|
|
@@ -570,19 +701,20 @@ def recorded_verdicts(decision_log: Path | None) -> dict[str, str]:
|
|
|
570
701
|
text = read_text(decision_log)
|
|
571
702
|
if not text:
|
|
572
703
|
return {}
|
|
704
|
+
listed = keys or set()
|
|
705
|
+
headings = [
|
|
706
|
+
(match, ident)
|
|
707
|
+
for match in _STORY_HEADING.finditer(text)
|
|
708
|
+
if (ident := _story_heading_id(match, listed))
|
|
709
|
+
]
|
|
573
710
|
out: dict[str, str] = {}
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
except (ValueError, TypeError):
|
|
582
|
-
continue
|
|
583
|
-
if isinstance(payload, dict) and payload.get("verdict"):
|
|
584
|
-
out[match.group(1)] = str(payload["verdict"])
|
|
585
|
-
break
|
|
711
|
+
for index, (match, ident) in enumerate(headings):
|
|
712
|
+
end = headings[index + 1][0].start() if index + 1 < len(headings) else len(text)
|
|
713
|
+
verdict = _first_verdict(text[match.end() : end], ident)
|
|
714
|
+
if verdict:
|
|
715
|
+
out[ident] = verdict
|
|
716
|
+
elif _is_gate_heading(match):
|
|
717
|
+
out.pop(ident, None)
|
|
586
718
|
return out
|
|
587
719
|
|
|
588
720
|
|
|
@@ -631,6 +763,46 @@ def resolve_recorded_verdicts(recorded: dict[str, str], stories: list[str]) -> d
|
|
|
631
763
|
return out
|
|
632
764
|
|
|
633
765
|
|
|
766
|
+
def sprint_rows(impl_artifacts: Path | None, repo: Path) -> dict[str, str]:
|
|
767
|
+
"""sprint-status.yaml's rows, key to status, located and read as a resume
|
|
768
|
+
reads them (`preflight_check`). Fail-soft: no impl-artifacts dir, or no
|
|
769
|
+
readable file, reads as no rows."""
|
|
770
|
+
if impl_artifacts is None:
|
|
771
|
+
return {}
|
|
772
|
+
import preflight_check # noqa: PLC0415 (sibling script, path set above)
|
|
773
|
+
|
|
774
|
+
text = read_text(preflight_check._locate_sprint_status(repo, impl_artifacts))
|
|
775
|
+
return preflight_check._parse_development_status(text) if text else {}
|
|
776
|
+
|
|
777
|
+
|
|
778
|
+
def open_escalations(impl_artifacts: Path | None, stories: list[str], repo: Path) -> dict[str, str]:
|
|
779
|
+
"""Each story whose escalation is still open, mapped to its sidecar's kind.
|
|
780
|
+
|
|
781
|
+
Imported from `preflight_check.py` rather than re-implemented, so the trail
|
|
782
|
+
calls a sidecar open exactly when a resume would stop on it. A story whose
|
|
783
|
+
sprint-status row reads `done` is left out (module docstring), unless its
|
|
784
|
+
sidecar is the advance route's own `evidence-commit-rejected`. Fail-soft like
|
|
785
|
+
every other source: no impl-artifacts dir reads as no escalation, and an
|
|
786
|
+
unreadable sprint-status reads as no row, so an open sidecar still renders
|
|
787
|
+
`escalate` (never quietly green). An unreadable sidecar is open, as the
|
|
788
|
+
resume reads it, and its kind renders as `unreadable`.
|
|
789
|
+
"""
|
|
790
|
+
if impl_artifacts is None:
|
|
791
|
+
return {}
|
|
792
|
+
import preflight_check # noqa: PLC0415 (sibling script, path set above)
|
|
793
|
+
|
|
794
|
+
rows = sprint_rows(impl_artifacts, repo)
|
|
795
|
+
out: dict[str, str] = {}
|
|
796
|
+
for story in stories:
|
|
797
|
+
escalation = preflight_check._escalation_of(impl_artifacts, story, repo)
|
|
798
|
+
if escalation is None or escalation["state"] != "open":
|
|
799
|
+
continue
|
|
800
|
+
kind = escalation["kind"] or "unreadable"
|
|
801
|
+
if kind == EVIDENCE_COMMIT_REJECTED or rows.get(story) != "done":
|
|
802
|
+
out[story] = kind
|
|
803
|
+
return out
|
|
804
|
+
|
|
805
|
+
|
|
634
806
|
def _marker_sha(impl_artifacts: Path | None, name: str) -> str | None:
|
|
635
807
|
"""The first SHA-looking token in a marker file, or None when there is none."""
|
|
636
808
|
if impl_artifacts is None:
|
|
@@ -732,6 +904,7 @@ def story_section(
|
|
|
732
904
|
repo: Path,
|
|
733
905
|
recorded: dict[str, str],
|
|
734
906
|
range_end: str | None,
|
|
907
|
+
escalated: dict[str, str] | None = None,
|
|
735
908
|
) -> str:
|
|
736
909
|
checklist = checklist_path(test_artifacts, story) if profile == "production" else None
|
|
737
910
|
checklist_text = read_text(checklist)
|
|
@@ -749,24 +922,40 @@ def story_section(
|
|
|
749
922
|
# resolved (module docstring): with no artifact the gate itself would refuse
|
|
750
923
|
# the story, and the trail must not out-vote the gate in the gate's column.
|
|
751
924
|
recorded_verdict = recorded.get(story) if gate_source else None
|
|
752
|
-
|
|
925
|
+
# An open escalation is where the run stopped, after logging the verdict it
|
|
926
|
+
# escalated from, so it outranks that verdict, with or without a gate
|
|
927
|
+
# artifact (module docstring). An `evidence-commit-rejected` one owes a
|
|
928
|
+
# commit, not a verdict, so it changes no cell and is only named below.
|
|
929
|
+
kind = (escalated or {}).get(story)
|
|
930
|
+
stopped = bool(kind) and kind != EVIDENCE_COMMIT_REJECTED
|
|
931
|
+
verdict = "escalate" if stopped else verdict_for(gate_status, recorded_verdict)
|
|
753
932
|
start = baseline_sha(impl_artifacts, story)
|
|
754
933
|
commits = commit_cell(repo, start, range_end)
|
|
755
934
|
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
935
|
+
sidecar = f"`escalation-{story}.json` (kind `{kind}`)"
|
|
936
|
+
if stopped:
|
|
937
|
+
source = f"the open escalation {sidecar}"
|
|
938
|
+
if not gate_source:
|
|
939
|
+
source += ", and no gate artifact resolved for this story"
|
|
940
|
+
elif recorded_verdict:
|
|
941
|
+
source = "recorded in the decision log"
|
|
761
942
|
elif recorded.get(story):
|
|
762
|
-
|
|
763
|
-
"
|
|
764
|
-
"
|
|
943
|
+
source = (
|
|
944
|
+
"n/a (the decision log records a verdict, but no gate artifact resolved "
|
|
945
|
+
"for this story, so it is not rendered as gated evidence)"
|
|
765
946
|
)
|
|
766
947
|
else:
|
|
767
|
-
|
|
768
|
-
|
|
948
|
+
source = "the gate artifact's status, mapped by the gate's own table"
|
|
949
|
+
if kind == EVIDENCE_COMMIT_REJECTED:
|
|
950
|
+
source += (
|
|
951
|
+
f"; the escalation {sidecar} is still open, and owes the evidence "
|
|
952
|
+
"commit, not a verdict"
|
|
769
953
|
)
|
|
954
|
+
|
|
955
|
+
lines = [f"## Story {story}", ""]
|
|
956
|
+
lines.append(f"- Criteria and planned tests: {criteria_source or NA}")
|
|
957
|
+
lines.append(f"- Gate artifact: {gate_source or NA} (gate status `{gate_status or NA}`)")
|
|
958
|
+
lines.append(f"- Verdict source: {source}")
|
|
770
959
|
lines.append(f"- Baseline: `{start}`" if start else f"- Baseline: {NA}")
|
|
771
960
|
lines.append("")
|
|
772
961
|
lines.append(_row(list(COLUMNS)))
|
|
@@ -803,15 +992,19 @@ def render(
|
|
|
803
992
|
) -> str:
|
|
804
993
|
# Resolved against the story list, so `recorded` below is keyed by the SAME
|
|
805
994
|
# full story ids the sections are rendered for and every lookup is exact.
|
|
806
|
-
|
|
995
|
+
# The sprint-status keys and the story list tell a heading that names a
|
|
996
|
+
# letter-prefixed key from a prose one.
|
|
997
|
+
keys = set(sprint_rows(impl_artifacts, repo)) | set(stories)
|
|
998
|
+
recorded = resolve_recorded_verdicts(recorded_verdicts(decision_log, keys), stories)
|
|
807
999
|
baselines = {story: baseline_sha(impl_artifacts, story) for story in stories}
|
|
1000
|
+
escalated = open_escalations(impl_artifacts, stories, repo)
|
|
808
1001
|
|
|
809
1002
|
header = [
|
|
810
1003
|
f"# Gate trail: Epic {epic}",
|
|
811
1004
|
"",
|
|
812
1005
|
"Synthesized at finalize from the artifacts this run already wrote: the per-story "
|
|
813
1006
|
"acceptance checklist (production runs), the trace report, the gate decision file, "
|
|
814
|
-
"the decision log and the recorded baseline and end commits.",
|
|
1007
|
+
"the decision log, the open escalations and the recorded baseline and end commits.",
|
|
815
1008
|
"",
|
|
816
1009
|
"It renders the gate's verdicts; it never forms one. A cell whose source artifact "
|
|
817
1010
|
f"was absent or unreadable reads `{NA}`.",
|
|
@@ -862,6 +1055,7 @@ def render(
|
|
|
862
1055
|
repo=repo,
|
|
863
1056
|
recorded=recorded,
|
|
864
1057
|
range_end=range_end,
|
|
1058
|
+
escalated=escalated,
|
|
865
1059
|
)
|
|
866
1060
|
)
|
|
867
1061
|
return "\n".join(header + sections).rstrip() + "\n"
|