@feigi/fleet-ctl 3.18.14 → 3.19.0

package/agents/fleet-recipe-deriver.agent.md

@@ -0,0 +1,109 @@
+---
+name: fleet-recipe-deriver
+description: Derives a repository's Recipe — its Install step and Test entrypoint — by reading the repository, proves both with recipe-prove.mjs, and reports. Dispatched by the run-team controller in phase 0, or by a standalone next-ticket or review-and-fix session, when the repository has no usable Recipe cache. Never invoked directly.
+model: "@task:medium"
+---
+
+You derive one repository's **Recipe**: the **Install step** (the shell command
+that materialises its dependencies in a fresh checkout) and the **Test
+entrypoint** (the shell command that runs its suite). The fleet keeps no table
+of technologies — no lockfile map, no test-file pattern, no list of build
+tools — so you are the only part of it that reads a repository and decides
+how it is built and tested. You decide by reading; a script proves what you
+decided; nothing is cached on a guess.
+
+Your dispatch prompt gives you `<repo>` (the repository's main checkout, an
+absolute path) and `<scratch>` (a directory that is yours alone). Read files
+under `<repo>`; write only under `<scratch>`. **Never edit, create or delete a
+file under `<repo>`, and never write `.fleet/recipe.json` yourself** — the
+proof below is the cache's only writer, and it writes only on proof.
+
+## 1. Read the repository
+
+`git -C <repo> fetch origin`, then read what a new engineer would read, at
+`origin/main` (`git -C <repo> show origin/main:<path>`, `git -C <repo>
+ls-tree -r --name-only origin/main`):
+
+- the README and any CONTRIBUTING or development guide;
+- the build and manifest files at the root and one level down — whatever this
+  repository uses to declare dependencies and tasks;
+- `.github/workflows/*` (or the repository's other CI configuration): the
+  step that runs the suite in CI is the repository's own statement of what
+  its suite is, and the step before it is usually its install;
+- scripts the repository tracks for running tests (a `Makefile` target, a
+  `scripts/test`, a tracked `agent-test`).
+
+Propose one Install step and one Test entrypoint, both shell commands run
+from the repository root by `sh -c`:
+
+- **Install step** — the form that installs exactly what the repository pins
+  and rewrites nothing: the frozen or locked mode where the tool has one.
+  `true` when nothing needs installing. It must leave every file exactly as
+  checked out; build output the repository ignores is fine.
+- **Test entrypoint** — the whole suite, the way CI runs it. Members run it
+  with their own arguments appended (`sh -c '<test> "$@"'`), so prefer a form
+  where an appended test file or test name lands as an argument to the test
+  runner. The cache reader refuses a command whose first word does not
+  resolve from the repository root (a builtin, a `PATH` entry, or an
+  executable path), one ending in `;`, `&` or a newline, and one containing a
+  word that starts with `#`.
+
+## 2. Prove it — this procedure exactly
+
+Every run below happens in a throwaway worktree of `origin/main` that the
+script creates and removes; `<repo>`'s own tree is never touched.
+
+**First run, to see the output** — no proof flags:
+
+    ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --test '<test>'
+
+It exits 1 with `NOT PROVEN — no proof given` once both commands ran, and
+names the Test entrypoint's output file (`test output: <path>`). Any other
+`NOT PROVEN` reason is about your commands — read it, and the log it names,
+and revise.
+
+**Then prove it, with ONE of:**
+
+- **The count proof** — when the runner prints how many tests it ran. Copy
+  that summary line's text, as printed, into `--count-line`, and the number it
+  carries into `--test-count`:
+
+      ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --test '<test>' \
+        --count-line '<literal text of the count line>' --test-count <n>
+
+  Copy only text that is the same on every run — the count, not a duration.
+  A count of 0 is a failed proof, never a pass.
+- **The mutation proof** — when the runner prints no count, or prints one
+  you cannot pin. It needs the unmutated run green. Choose one test and write
+  a shell command that breaks it deliberately: change an expected value in
+  the test, or the code that test checks, so the test must fail. The command
+  must change a tracked file; the script runs it in the throwaway worktree,
+  requires the suite to go red, and discards the worktree after:
+
+      ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --test '<test>' \
+        --mutate '<shell command that breaks one test>' --mutation '<one line: what it breaks>'
+
+Exit 0 is the proof holding: the script wrote the Recipe cache and printed
+`PROVEN` and the cache's contents. Exit 1 is `NOT PROVEN`, with the reason;
+no cache was written. Exit 2 means no verdict on the proof: it could not be
+attempted (no `origin/main`, not a repository) or the cache could not be
+written — report it, do not work around it.
+
+You may revise and re-run after a `NOT PROVEN` you can act on — a wrong
+command, a count line you mis-copied, a mutation that changed nothing — **at
+most four `recipe-prove.mjs` runs in all**, the first one included. Never
+weaken the proof to get past it: a suite that stays green under a real
+mutation, or reports zero tests, is the finding, not an obstacle.
+
+## 3. Report
+
+Your last message is exactly one of:
+
+- `RECIPE PROVEN` followed by the JSON line `recipe-prove.mjs` printed.
+- `RECIPE NOT PROVEN` followed by the last run's `NOT PROVEN` reason
+  verbatim, the commands you tried, and one line naming the cause:
+  **vacuous** (the suite ran no tests, or none a mutation could reach),
+  **did not run** (a command not found or not executable — a toolchain this
+  machine lacks), **dirty install** (the Install step changes the tree), or
+  **unreadable** (you could not tell from the repository how it is built or
+  tested).

package/commands/review-and-fix.md

@@ -10,7 +10,7 @@ argument-hint: [pr-number]
    See **Specialists** — those constraints are not optional.
 2. Plan the actions. Split explicitly into **apply now** / **defer**. A finding is deferred, never dropped. **Every `suggestion` — the review's `severity`, the plugin's *Suggestions* bucket — arrives unchecked: the review budgets that band 0 refuters, so nothing has looked at it yet.** Checking it is now your job, not nobody's. So split it by SCOPE first. Out of the PR's ticket scope → defer and file. In scope → dispatch one refuter against it, biased to refuse, and hand it this instruction verbatim with one substitution: resolve `<scratch>/pr<N>/<finding>/` in it to an absolute path under your own run root — `mktemp -d` once per round for `<scratch>/pr<N>/fix-XXXXXXXX/`, never bare `pr<N>`, since finding ids restart at 1 each round too — and write that absolute path into the refuter's prompt in its place; a refuter never derives its own path: *Try to REFUTE this finding. Default to refuted=true if uncertain. Verify by RUNNING something — compile it, run the test, apply the mutation. Do not reason your way to agreement. Observe that run synchronously — run the command, wait for it, read its exit code. Never poll a log file for a completion marker: prefer ONE blocking run to a poll loop, and treat its return as permission to look, never as the answer. Reading a log the run has already finished writing is fine; waiting on one is not. If you match a test reporter's own output, accepting both `ℹ` and `#` is necessary but NOT sufficient — strip SGR escapes first as well. node's prefix moves with the node version and with whether stdout is a TTY, and color wraps the whole line so it begins with ESC and no prefix anchor matches at all, which returns empty at exit 0 — indistinguishable from a hung run and from a run of zero tests. For an uncolored baseline use `env -u FORCE_COLOR`; `FORCE_COLOR=` empty still enables color, so it is not a control. State your search scope AND what your pattern would have missed. A grep over one ref does not support a claim about history; a pattern built from the token a diff removed does not support a claim that the category is empty. A failure injection with no positive control has produced NO result, never a negative one. Before you read an injected fault — an env var, an argv word, a mutant — as having had no effect, prove the injection reached the child: one run whose output differs with it present versus absent, or the child echoing the injected value back. Uncontrolled, the cell is unrun — say so in your verdict instead of reporting a no-effect result. Build such an invocation as an array expanded braced and quoted — `cfg=(SETB=1 BADJ=1); env "${cfg[@]}" sh ./probe.sh` — or inline the assignments literally — `env SETB=1 BADJ=1 sh ./probe.sh`; NEVER from an unquoted scalar — `cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh` — which under zsh passes ONE argument, sets a variable literally named `SETB` to `1 BADJ=1`, never sets `BADJ` at all, and still exits 0. `env $cfg[@]` is not the portable spelling either: measured, bash word-splits it into `SETB=1` and `BADJ=1[@]`, so the injection variable is set to a corrupted value, while zsh behaves exactly as with the bare `$cfg` — `BADJ` never set, exit 0. Everything you write — mutants, fixtures, scratch repos — goes under `<scratch>/pr<N>/<finding>/` and nowhere else; the checkout and any worktree are never write targets, though `git show`/`git archive` at a pinned ref read fine anywhere. Chain the directory change into the command, `cd "$D" && git …`, never `cd "$D"; git …`, so a failed `cd` cannot leave a `git` command running in the checkout — and bracket a fixture's own git with `git rev-parse --show-toplevel`: before `git init` it must NOT resolve to the repository, and a fresh scratch dir's `fatal: not a git repository` (exit 128) is the pass, not a failure; before any `git commit` it must resolve to your scratch path — compare resolved forms (`realpath`), since `--show-toplevel` can report `/private/tmp/…` for a `/tmp` scratch dir on macOS.* That last clause is the whole mechanism — a refuter left to reason its way to agreement rubber-stamps, and "apply only what survives" silently degrades into "apply everything in scope". Apply only what survives; a refuted one defers with the refutation in its body. "In scope" means the ticket's scope, not merely the same files — and applying one still never licenses editing a file the ticket has no business in. **A finding in `unverified` whose refuters ran and crashed always defers, whatever its severity** — and which of the two it is, you read off the finding's **`refutersDispatched`**, never off severity and never off an empty vote list: above zero with nothing surviving means every refuter dispatched against it died, and at `critical` that is every one of them. Only a `survived` finding has been checked; severity says how much a finding would matter if true, never whether anything looked. **Deferring a crash is your move, and re-running it is not** — the review already re-dispatched every crashed refuter pair once, in-run, so a crash that reaches you crashed twice, and the result's `resume` field names the one move left, which is not yours: nothing replays a review that ran in a runner's kernel — it is reported, not acted on. So say *in the deferral* that its refuters crashed rather than that it went unchecked, and re-run nothing for it. **A `suggestion` is also in `unverified`, for a different reason — `refutersDispatched` of zero, the 0-refuter budget the workflow gives that band by policy, so nothing looked *there* — and the scope split above, not this rule, covers it.**
    **Write every ruling to `<scratch>/dispositions-<pr>.json`, beside the review result file — the disposition record `dispositions-check.mjs` judges against it before any finisher is dispatched.** It is `{"head": "<the review file's head>", "entries": [ … ]}`: one entry per `survived` finding and per `unverified` finding, plus one per `refuted` finding you reverse, its evidence in `reason`. Each entry carries `bucket` (`survived|unverified|refuted`), `index` (its position in that bucket of the review file — stable, since a round's file never changes), `scope` (`in|out`), `claimKind` (`behavior|shape`) and `disposition` (`apply|defer`), and where they apply `reason`, `issue` (the number you filed it to or commented on), `verdictPath` (an in-scope suggestion's refuter verdict file) and `remedyFiles` (the files its remedy names). The check reads scope off the diff before it reads your entry: a finding with no `line`, or on a line `git diff` touches from the PR's merge-base with `origin/main` to the review's `head`, is in scope whatever `scope` says, and only otherwise does the declared one stand. An in-scope `survived` finding deferred passes only with `reason` `false-rationale`, `mutual-exclusion`, `remedy-worse` or `remedy-outside-diff`. `remedy-outside-diff` — the remedy would edit a file the PR's diff does not touch — also needs `remedyFiles` to name at least one file absent from `git diff` from that merge-base to the review's `head`: none named, or every one in that diff, is a mismatch. A `critical` or `important` finding deferred for it goes to a human instead of passing: the script exits 1 with verdict `escalate`, `ledger.mjs dispatch` refuses the PR's finisher, and nothing retries it; a `suggestion` deferred for it passes. Any other reason, none, or a `survived` or `unverified` finding with no entry is a mismatch: the script exits 1 naming each violating entry's bucket, index and rule, and `ledger.mjs dispatch` refuses the PR's finisher.
-3. **Run `testCmd` before you commit**, from the worktree, copied verbatim — not a runner you picked. `testCmd` is the command your dispatcher handed you; **standalone, with no dispatcher to hand you one, it is the repo's own test command**, the Test entrypoint in the repo's Recipe cache (`derive-testcmd.sh <repo> test` prints it) — here `node --test plugin/scripts/*.test.mjs`, which is this repo's example and not a value any derivation guarantees. Read it off the repo, never invent one: "not a runner you picked" is what this step forbids, and on the standalone path nothing else defines the referent. With no Recipe cache, run the Recipe derivation step; never fall back to a runner of your own choosing. `tests 0` is a FAILED run, not a pass: a glob matching nothing still exits 0. **Zero is not the only no-work count.** A run reporting **0 passes with no failures** skipped everything it collected, and a count **materially below the whole suite** means you ran a partial tree — this suite reported `tests 937` when this line was written, so compare what you get against a full run rather than against zero. The number drifts; that is the safe direction, because a stale one produces a loud false red while its absence produces a silent false green. Red, zero-test, or either no-work count → fix it or move the finding to defer; never commit over it. Then commit and push — `git push origin HEAD:<branch>`, the explicit refspec: this step also runs from a `--detach` worktree (`run-team/SKILL.md`'s worktree-recreation form), where a bare `git push` exits 128 (`fatal: You are not currently on a branch`) and any push whose destination is `HEAD` rather than a full or branch refname (`-u` or not, forced or not) exits 1 (`error: The destination you provided is not a full refname`) — and report the test result alongside the SHA. **Then reconcile the PR body with what you actually did.** It merges into the permanent record and nothing downstream re-derives it: your commit messages are yours to fix and usually get fixed, the body is neither. Removing a change, or reversing one, leaves the body asserting work the diff no longer contains. Measured twice in one run — one body kept asserting a calibration its own fix had just deleted as false, another kept claiming a hunk the fix had removed as "this diff owns it" — both caught by a finisher's reading rather than by any rule, and both would otherwise have merged intact. `gh pr edit <pr> --body-file <path>`, and re-read the body against the final diff rather than against your memory of it. **Never `--no-verify`.** The fleet runs in repos it knows nothing about: it must not assume a pre-commit hook exists, and must never bypass one that does — a hook that fails is a finding to report, not an obstacle. Nothing re-reviews what you commit here, so this run is the only gate between your edit and a merge.
+3. **Run `testCmd` before you commit**, from the worktree, copied verbatim — not a runner you picked. `testCmd` is the command your dispatcher handed you; **standalone, with no dispatcher to hand you one, it is the repo's own test command**, the Test entrypoint in the repo's Recipe cache (`derive-testcmd.sh <repo> test` prints it) — here `node --test plugin/scripts/*.test.mjs`, which is this repo's example and not a value any derivation guarantees. Read it off the repo, never invent one: "not a runner you picked" is what this step forbids, and on the standalone path nothing else defines the referent. With no usable Recipe cache (`derive-testcmd.sh` refuses), run the Recipe derivation step first — dispatch a `task` member, agent `fleet-recipe-deriver`, its prompt naming the main checkout's absolute path as `<repo>` and a scratch directory of its own; it proves both commands in a throwaway worktree and writes the cache only on proof, and its `RECIPE NOT PROVEN` is a stop, reported with its reason. Never fall back to a runner of your own choosing. `tests 0` is a FAILED run, not a pass: a glob matching nothing still exits 0. **Zero is not the only no-work count.** A run reporting **0 passes with no failures** skipped everything it collected, and a count **materially below the whole suite** means you ran a partial tree — this suite reported `tests 937` when this line was written, so compare what you get against a full run rather than against zero. The number drifts; that is the safe direction, because a stale one produces a loud false red while its absence produces a silent false green. Red, zero-test, or either no-work count → fix it or move the finding to defer; never commit over it. Then commit and push — `git push origin HEAD:<branch>`, the explicit refspec: this step also runs from a `--detach` worktree (`run-team/SKILL.md`'s worktree-recreation form), where a bare `git push` exits 128 (`fatal: You are not currently on a branch`) and any push whose destination is `HEAD` rather than a full or branch refname (`-u` or not, forced or not) exits 1 (`error: The destination you provided is not a full refname`) — and report the test result alongside the SHA. **Then reconcile the PR body with what you actually did.** It merges into the permanent record and nothing downstream re-derives it: your commit messages are yours to fix and usually get fixed, the body is neither. Removing a change, or reversing one, leaves the body asserting work the diff no longer contains. Measured twice in one run — one body kept asserting a calibration its own fix had just deleted as false, another kept claiming a hunk the fix had removed as "this diff owns it" — both caught by a finisher's reading rather than by any rule, and both would otherwise have merged intact. `gh pr edit <pr> --body-file <path>`, and re-read the body against the final diff rather than against your memory of it. **Never `--no-verify`.** The fleet runs in repos it knows nothing about: it must not assume a pre-commit hook exists, and must never bypass one that does — a hook that fails is a finding to report, not an obstacle. Nothing re-reviews what you commit here, so this run is the only gate between your edit and a merge.
 4. **Under the fleet, do not hold this wait.** The controller owns a persistent CI Monitor and dispatches a finisher once your report has arrived and CI is green — so push, then report to the controller a **final verdict** (every specialist you dispatched + its outcome + your apply/defer adjudication + the pushed SHA) and stop. A specialist that has neither reported nor been relayed to you is not a verdict line — ask the controller for it by name before ruling; see **Specialists**. The controller keys "review complete" on that verdict, **never on you merely going idle** — a slow specialist can still be running when your turn ends, and finishing off idle-alone ships a premature label (observed: a PR labelled while its contract-test specialist was still running and about to surface a vacuous pin). A turn-based reviewer re-reading `gh pr checks` each idle cycle rebuilds its whole context for nothing the Monitor lacks. **Standalone (no controller): watch** the run until the diff-validating jobs are green (bind via `ci-state.mjs` below); fix a **genuine** failure and repeat from 3. **Staleness is not a failure:** a `rebase-check` red or heavy jobs `skipped` **solely from a non-zero behind-count** never clears by waiting and must not be rebased away here — see **`skipped` is not `passed`** and **Do NOT rebase to label** below for what it looks like and why. Stop watching and go to 6. A turn-based reviewer that "waits for green" on a behind PR stalls forever and ends its turn without labelling. **`ci-state.mjs` returns `verdict: "no-ci"`** → there is no run to watch, so don't: go straight to 6 and let that step's `--declare-no-ci` branch decide.
 5. File each deferred finding: `gh issue create --label <ready-for-agent|needs-triage>` with the finding, `file:line`, why deferred, `Deferred from PR #<pr> review`, and **the finding's `dimension` in the issue body** — the review returns it on every finding, and a backlog that does not carry it cannot be attributed to the specialist that generated it. **The label follows the finding's state, not this step** — but it is never omitted; an unlabelled issue is invisible to both `candidates.mjs --require-label` and the cockpit's pool query, reachable only by a human. **The bar here is whether the DEFECT is confirmed — never whether the remedy is settled.** Confirmed defect with the remedy still open → `ready-for-agent`, and say in the body that the remedy is open. Torn → `needs-triage`, narrowed: torn means **unsure anything is broken**, not unsure how to fix it. **A finding a refuter CHECKED and did not survive is neither** — it is not a confirmed defect, and you are not unsure whether anything is broken: you measured that nothing is. Refutations go as **one issue per review, titled `PR #<pr> review: the suggestion band, checked`, labelled `wontfix`, and CLOSED** — #483, #542, #571 and #934 are the precedent, and a run that files them open instead has to be corrected afterwards, as one was on 2026-08-27. Left open they read as queued agent work and rot into filing artifacts; a measured triage pass found a quarter of its `needs-triage` backlog was refuted records, bulk-closable by title shape. Closed is still a durable home — `check` reads the tracker at `--state all`, so a future run re-deriving the finding lands on the evidence rather than re-litigating it. Split the band only where an entry is **not** a refutation: a residual the refuter surfaced, or a finding refused as out of scope and never checked, is real deferred work — and real deferred work earns its own open issue only past a second bar. **Worth a claim: a finding whose own claim is that correct code could be shaped better — style, naming, layout, redundancy, a micro-simplification — never gets its own open issue.** Its only open question is "is this worth doing?", which answers itself under the triage bar #239 repriced: measured 2026-08-15→31, 133 issues were triage-closed `wontfix` in sixteen days, 121 of them review deferrals, mostly this shape (`docs/adr/0002-filing-second-bar-worth-a-claim.md`). Append it to the same closed record issue under a `Below the claim bar` heading — `file:line`, dimension, the claim, and a re-open trigger per entry. Closed is a durable home for these too: `check` reads `--state all`, so a run re-deriving the finding lands on the record instead of re-filing — and a later review returning the same finding as `survived`, or a maintainer hitting it, is the promotion signal: file it open then, citing the record. **An in-scope rediscovery step 2 applied is that same promotion signal, and it files nothing** — so the record carries no mark unless you write one: run `check` over each finding step 2 applied as well, and where its tracker rows put one on a `Below the claim bar` entry, comment on that record issue, opening `Promoted — applied, not filed`, and name the entry, that its refuter let it through, and the commit carrying the fix. That comment is the mark ADR 0002's Trigger A counts for this path, and it is **not** a cross-reference — measured on this tracker, a comment mints `cross-referenced` on the issue its own text *names*, never on the issue it sits under (#1033's comment citing #1453 landed on #1453's timeline and nowhere else), so the fixed opening is what carries the signal instead. **The bar reads the finding's claim, never its review band** — a finding that alleges wrong behavior, whatever band it sat in, `unverified`-with-crashed-refuters included, is above this bar and files open under the confirmed/torn split; #591's conflation is exactly why a band cannot carry this decision. Do **not** reach for phase 0's **decided?** test here. That is a *consumption* gate, priced for a seat where implementer divergence costs a claim, a worktree and a dispatch; at filing time divergence costs one PR review the maintainer already runs. Same test, two seats, opposite correct answers — and reading it in this seat took `needs-triage` from 11 to 135 before it was repriced (#239, ruled 2026-08-18). **Dedupe through `~/.fleet/bin/fleet-run ledger.mjs check "<subject>"`, never a bare `gh issue list --search`** — the duplicate class that guard exists to catch was filed from *here*: the ledger row for the finding rediscovered five times in one measured run carries a reviewer's own source tag, `(review-pr-108)`. `check` reads this run's filed list *and* the tracker at `--state all`, so a closed duplicate still counts. Exit **1** is already filed in this run; exit **3** is a clean ledger with matching tracker rows that score against the subject — read the ones it prints and comment on the existing follow-up rather than filing a second issue. **Exit 0 is not automatically "safe to file"**: it covers `clean`, `soft-hit` and `unverified` alike, and an unreachable `gh` degrades to a ledger-only answer that says `TRACKER NOT CHECKED`, so read the stdout `verdict` to tell a tracker that was searched and clean from one nobody read — under `unverified`, search it yourself before filing — or, for the applied-promotion comment above, before treating a tracker nobody could read as a reason to skip it. **`soft-hit` is the answer that costs most to misread**: it means related rows were found and none of them was established as a duplicate — a near-miss above the floor, or tracker rows the scorer rates 0.00 — so read the rows it printed and decide, and never treat that exit 0 as permission. Exit **2** is a usage error, meaning nothing was checked at all: fix the invocation and re-run, never read it as a duplicate. Full exit-code and `verdict` semantics live in `$(~/.fleet/bin/fleet-run --root)/skills/run-team/SKILL.md`'s **Run ledger** section — read them there rather than restating them here. **The guard dedupes, it never drops:** a duplicate becomes a comment on the issue that already covers it, never a dropped finding. **Record every issue you create, at once:** immediately after each `gh issue create`, run `~/.fleet/bin/fleet-run ledger.mjs filed <N> "<subject>"` — `<N>` the number `gh issue create` printed, and **the same subject string you passed to `check`**, so the next `check` for that finding meets it in the filed list instead of scoring a rewording. Without it the guard's ledger half never holds a row, and its exit **1** can never fire. If `filed` fails, retry it once; if it fails again, leave the issue alone — it exists and is correct — and report it as `unrecorded: #N <subject>`, so the controller runs `filed` for it. Report `filed: #N <subject>` for every issue you created — under the fleet, in your report to the controller. **The one window the guard cannot see:** `check` → `gh issue create` → `filed` is three commands, and the ledger's lock covers each alone, so two filers can both read `clean` in the seconds before either records. That gap is accepted, never a reason to skip `filed`. Post the numbers as one PR comment.
 6. Diff-check green (run-bound per `ci-state.mjs`; under staleness see **`skipped` is not `passed`** for what the label then rests on) **and** deferrals filed **and** the PR carrying exactly one release label (`patch`/`minor`/`major`, counting only those three; **required on every PR** — `release-label.yml` auto-adds `patch` when none is present and hard-fails on more than one, so this never needs to check whether the repo defines the gate at all, and `gh label list` settles nothing here any more) **and** `dispositions-check.mjs --member fix-pr-<pr> --scratch <scratch>` run over your own record exiting 0 (standalone that is yours to run, from the worktree, after step 2 writes `<scratch>/dispositions-<pr>.json`; it reads the review file beside it, which you write yourself from the findings step 1 collected, in the shape **The review result file** describes — `pr`, `head`, `snapshot`, `counts` and the `survived`, `refuted` and `unverified` buckets; standalone you pass `--no-ledger`, so it writes no token and the exit status is the verdict — a `.fleet/ledger.md` the repository already holds is a previous run's, and without the flag it exits 2 for a ledger with no row for you; under the fleet `ledger.mjs dispatch` has already refused a finisher without it) → `gh pr edit <pr> --add-label ready-to-merge`. Do not merge. A non-zero dispositions exit halts you before the label, and you report the violations it printed. Zero or more than one release label halts you before the label, naming which you found — a timed-out `gh pr create` opens the PR with its `--label` unapplied and no exit status to react to (#375), and nothing after this step re-derives the release label. **Under the fleet a finisher does this** — a fresh small agent the controller dispatches (after your final verdict, never on your bare idle). Gate it on the diff-validating **`check`** job, **not** on `ci-state --quiet` exit 0, which a behind PR — the normal case once any sibling merges — never reaches: a `rebase-check` red or heavy jobs `skipped` off the behind-count hold it short of full green, so an exit-0 gate strands every behind PR unlabelled. Label when `check` is present and green **and no heavy job (the diff-validating suites — *not* the `rebase-check` currency gate) is in `failure`** — a `skipped` heavy job is behind-count staleness and fine — **solely** off that count, which is a condition to establish rather than infer, see the five-condition note in `$(~/.fleet/bin/fleet-run --root)/skills/run-team/SKILL.md`'s fix-applier prompt block. A `failure` is the diff's own fault and blocks the label, else a genuinely broken PR gets labelled off a green `check` and burns a merge-bot rebase+CI cycle before the failure resurfaces. Read per-job state for this: run `ci-state.mjs` **without** `--quiet`, or read its `jobs` — the `--quiet` payload drops the per-job `jobs`/`missing` and the `dropped` list, keeping `reasons` (which still distinguishes `is failure` from `is skipped`). You reach step 6 yourself only when green is already in hand at push time.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feigi/fleet-ctl",
-  "version": "3.18.14",
+  "version": "3.19.0",
   "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
   "license": "Apache-2.0",
   "repository": {

package/scripts/ambient-git-vars-mjs-prose.test.mjs

@@ -243,6 +243,18 @@ const COVERED_MJS = {
   // another repository does not change the answer" (the diff and merge-base)
   // and "… does not change which ledger is found" (the common dir).
   "dispositions-check.mjs": 1,
+  // ONE scrubbed env, built once and handed to every child — the `git(args,
+  // cwd)` primitive behind the common-dir, origin/main, worktree, status and
+  // diff calls, AND the one `sh -c` runner of the Install step, the Test
+  // entrypoint and the mutation. An ambient GIT_DIR would answer the first for
+  // another repository and run the Recipe against that repository's tree while
+  // the cache landed here. Measured in recipe-prove.test.mjs, "an ambient
+  // GIT_DIR naming another repository does not change the answer" (the git
+  // primitive) and "the Install step and the Test entrypoint run against their
+  // own worktree whatever GIT_DIR the caller exports" (the `sh -c` runner). The
+  // cache reader child gets the same env but unsets both itself, so no
+  // fixture can tell its env apart.
+  "recipe-prove.mjs": 1,
 };
 
 // The two-name-only exemption list #1599's second design question answers

package/scripts/derive-testcmd.sh

@@ -30,7 +30,8 @@
 #
 # At least one of testCount/mutation is the proof; a cache carrying neither,
 # or `installClean` anything but `true`, is an UNPROVEN Recipe and refused like
-# an absent one. Written only by the deriving agent; no script writes it.
+# an absent one. Written only by recipe-prove.mjs, the derivation step's proof,
+# and only once that proof holds; this script never writes it.
 #
 # INVALID on failure to RUN, never on failing tests: the command this script
 # is asked for must name something that resolves from <repo> (a builtin, a

package/scripts/recipe-derivation-prose.test.mjs

@@ -0,0 +1,99 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { between, paragraph, phrase } from "./prose-pin.mjs";
+
+// The Recipe derivation step's prose: where it lives in run-team's phase 0,
+// what reuses a cache instead of deriving, when a run re-derives and when it
+// stalls, and the deriver definition that carries the proof procedure. The
+// proof's own behaviour is recipe-prove.test.mjs's; this file pins that the
+// runbook routes to it, and that every refusal naming "the Recipe derivation
+// step" names a step that exists.
+const PLUGIN = join(import.meta.dirname, "..");
+const read = (rel) => readFileSync(join(PLUGIN, rel), "utf8");
+const RUN_TEAM = read("skills/run-team/SKILL.md");
+const DERIVER = read("agents/fleet-recipe-deriver.agent.md");
+const PROVER = read("scripts/recipe-prove.mjs");
+
+const phase0 = () => between(RUN_TEAM, "## Phase 0 — shortlist", "## Phase 1 — Pull", "run-team/SKILL.md phase 0");
+// The step spans its quoted dispatch prompt, so it is bounded by the next
+// rule's opener rather than by a blank line.
+const step = () => between(phase0(), "**Derive the Recipe — the Recipe derivation step — before the fold-in below", "**Mid-run, a cache that stops running", "the phase-0 Recipe derivation step");
+const stall = () => paragraph(phase0(), "**Mid-run, a cache that stops running is re-derived once", "the re-derive-once and stall rule");
+
+test("phase 0 derives the Recipe before the fold-in and before the first claim", () => {
+  const p0 = phase0();
+  const at = p0.indexOf("**Derive the Recipe");
+  assert.ok(at !== -1 && at < p0.indexOf("**Fold in every PR a prior run left open"),
+    "the Recipe derivation step must come before the fold-in: folded-in PRs are reviewed, and a review reads the Test entrypoint from the cache");
+  assert.match(step(), phrase("before the first claim."));
+});
+
+test("a present, valid cache is used as it stands — derivation is the controller's, once per run start", () => {
+  const s = step();
+  assert.match(s, phrase("Both exit 0 → the cache is present and valid: use it as it stands and derive nothing."));
+  assert.match(s, phrase("one derivation per run start at most, never one per member, and a member never derives."));
+  assert.match(s, phrase("agent `fleet-recipe-deriver`"));
+});
+
+test("the dispatch names the proof: a clean install, and a non-zero count or a mutation turning the run red", () => {
+  const s = step();
+  assert.match(s, phrase("the Install step must leave the tree clean"));
+  assert.match(s, phrase("the runner's own non-zero count, or a deliberate mutation of one test that turns the run red."));
+  assert.match(s, phrase("Only a proof writes the cache"));
+});
+
+test("an invalid cache is re-derived once; a failed derivation stalls the run instead of looping", () => {
+  const s = stall();
+  assert.match(s, phrase("dispatch `derive-recipe` again exactly as above, then retry what refused."));
+  assert.match(s, phrase("A red suite never triggers it: a failing test is a finding, not a stale Recipe."));
+  assert.match(s, phrase("`RECIPE NOT PROVEN` from any derivation, or a second invalid-cache refusal after this run's one re-derivation, halts the run"));
+  assert.match(s, phrase("It is never a loop: no third derivation, and never a cache written by hand."));
+});
+
+test("the claim paragraph sends an absent or invalid cache to the derivation step, and infers no Install step", () => {
+  const p = paragraph(RUN_TEAM, "**The Install step comes from the Recipe cache", "run-team/SKILL.md claim Install paragraph");
+  assert.match(p, phrase("never pass or infer one."));
+  assert.match(p, phrase("No cache is phase 0's Recipe derivation step not having run"));
+});
+
+// Every refusal that sends its reader to re-derive names the step by the same
+// words. If phase 0 stopped carrying a step by that name, each refusal would
+// point at nothing.
+test("every refusal naming the Recipe derivation step names one that phase 0 carries", () => {
+  const sources = {
+    "derive-testcmd.sh": read("scripts/derive-testcmd.sh").match(/^derive="([^"]*)"/m),
+    "claim-ticket.sh": read("scripts/claim-ticket.sh").match(/^rederive="([^"]*)"/m),
+    "review-core.mjs": read("scripts/review-core.mjs").match(/DERIVATION_STEP =\s*"([^"]*)"/),
+  };
+  for (const [file, m] of Object.entries(sources)) {
+    assert.ok(m, `${file}: could not find its derivation-step message — update this test`);
+    assert.match(m[1], /run the Recipe derivation step \(run-team phase 0, before the first claim/, `${file} no longer names the step`);
+  }
+  assert.match(step(), /the Recipe derivation step/);
+});
+
+test("the deriver is told never to write the cache itself, and to prove through recipe-prove.mjs", () => {
+  assert.match(DERIVER, phrase("never write `.fleet/recipe.json` yourself"));
+  assert.match(DERIVER, phrase("~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --test '<test>'"));
+  assert.match(DERIVER, phrase("A count of 0 is a failed proof, never a pass."));
+  assert.match(DERIVER, phrase("requires the suite to go red"));
+});
+
+test("every flag the deriver's procedure passes is one recipe-prove.mjs accepts", () => {
+  // The invocations are the indented command blocks naming recipe-prove.mjs;
+  // flags elsewhere in the definition (its `git` reads) are not the proof's.
+  const blocks = DERIVER.split(/\n[ \t]*\n/).filter((b) => /^ {4,}/.test(b) && b.includes("recipe-prove.mjs"));
+  assert.equal(blocks.length, 3, "expected the observe, count-proof and mutation-proof invocations — update this test");
+  const used = new Set(blocks.join("\n").match(/--[a-z][a-z-]+/g));
+  const accepted = new Set(PROVER.match(/new Set\(\[([^\]]*)\]\)/)[1].match(/--[a-z-]+/g));
+  assert.ok(used.size >= 6, `found only ${[...used].join(", ")} in the deriver — the procedure lost its proof flags`);
+  for (const flag of used) assert.ok(accepted.has(flag), `the deriver passes ${flag}, which recipe-prove.mjs does not accept`);
+});
+
+test("the deriver reports one of two lines, naming vacuity as a cause", () => {
+  assert.match(DERIVER, /`RECIPE PROVEN` followed by the JSON line/);
+  assert.match(DERIVER, /`RECIPE NOT PROVEN` followed by the last run's `NOT PROVEN` reason/);
+  assert.match(DERIVER, /\*\*vacuous\*\*/);
+});

package/scripts/recipe-prove.mjs

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+// Prove a repository's Recipe — its Install step and Test entrypoint — and
+// write the Recipe cache only if the proof holds. This is the Recipe
+// derivation step's proof, and the ONE writer of the cache derive-testcmd.sh
+// reads: the deriving agent chooses both commands by reading the repository,
+// and this script is what turns that choice into a cache, or refuses to.
+//
+//   recipe-prove.mjs <repo> --install <cmd> --test <cmd>
+//                    [--count-line <literal> --test-count <n>]
+//                    [--mutate <cmd> --mutation <description>]
+//
+// Every check runs in a throwaway worktree of `origin/main`, detached and
+// removed afterwards, so neither the caller's checkout nor its uncommitted
+// state takes part — `derivedAt` is the commit the proof ran against:
+//
+//   1. The Install step runs (`sh -c`, from the worktree root) and must exit
+//      0, then `git status --porcelain -uall` must print nothing: an install
+//      that rewrites a tracked file, or creates one the tree neither tracks
+//      nor ignores, corrupts every worktree it later runs in. That is the
+//      same check, in the same form, a claim re-asserts on every Install.
+//   2. The Test entrypoint runs and must RUN — 126/127 is the shell's "cannot
+//      execute"/"not found". A red suite is not a failed proof by itself.
+//   3. Real tests must be shown to have executed, by at least one of:
+//      - the count proof: `--count-line` is a literal the run's own output
+//        must contain (the runner's summary line, read off a previous run),
+//        carrying `--test-count`, a positive integer. `tests 0` is a failed
+//        proof however honestly the runner reports it.
+//      - the mutation proof: the unmutated run must be green; `--mutate` is a
+//        shell command that must change a tracked file (the deliberate
+//        failing mutation of one test, or of the code one test covers) — run
+//        against the tree restored to HEAD, so a file the unmutated run itself
+//        rewrote is not credited to it; the run must then go red. A mutation
+//        that leaves the run green is a suite that runs nothing that matters.
+//   With neither, nothing is proven: the refusal still names where the test
+//   run's output is, so the caller can read the count line off it.
+//
+// On proof, the cache is written atomically to <workspace>/.fleet/recipe.json
+// — <workspace> being the directory holding the repository's common git dir,
+// the place derive-testcmd.sh reads it from — and then read back through
+// derive-testcmd.sh for both fields. A cache the reader refuses is rolled
+// back to whatever stood before, so the reader stays the one authority on
+// what a usable cache is. A failed proof never touches an existing cache.
+//
+// Exit 0: proven, cache written (its path and contents on stdout).
+// Exit 1: NOT PROVEN — no cache written; the reason on stderr.
+// Exit 2: no verdict on the proof — it could not be attempted (usage, not a
+//         repository, origin/main missing, the worktree could not be made), or
+//         a filesystem fault stopped it before the cache was settled (the
+//         cache or its temp file could not be written).
+
+import { spawnSync } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { gitEnv, workspaceDirFromGitCommonDir } from "./git-env.mjs";
+import { isDigits } from "./arg.mjs";
+
+const NAME = "recipe-prove";
+const USAGE =
+  "usage: recipe-prove.mjs <repo> --install <cmd> --test <cmd> [--count-line <literal> --test-count <n>] [--mutate <cmd> --mutation <description>]";
+const READER = join(dirname(fileURLToPath(import.meta.url)), "derive-testcmd.sh");
+
+// Scrubbed once, for every child: an ambient GIT_DIR or GIT_WORK_TREE — set
+// by a git hook, `rebase --exec` or `bisect run` — would retarget the git
+// calls below at another repository, and the Install step and Test entrypoint
+// at that repository's tree, while the cache still landed here.
+const ENV = gitEnv();
+
+class Refusal extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+const cannot = (message) => new Refusal(2, message);
+const notProven = (message) => new Refusal(1, message);
+
+function parseArgs(argv) {
+  const [repo, ...rest] = argv;
+  if (!repo || repo.startsWith("--")) throw cannot(USAGE);
+  const flags = new Set(["--install", "--test", "--count-line", "--test-count", "--mutate", "--mutation"]);
+  const a = {};
+  for (let i = 0; i < rest.length; i += 2) {
+    const [flag, value] = [rest[i], rest[i + 1]];
+    // A value that is itself one of these flags is a missing value — `--install
+    // --test x` would otherwise run `--test` as the Install step.
+    if (!flags.has(flag) || value === undefined || flags.has(value)) throw cannot(USAGE);
+    if (flag in a) throw cannot(`${flag} given twice`);
+    a[flag] = value;
+  }
+  for (const f of ["--install", "--test"]) {
+    if (!a[f] || !a[f].trim()) throw cannot(`${f} needs a non-empty command — ${USAGE}`);
+  }
+  if (("--count-line" in a) !== ("--test-count" in a)) throw cannot("--count-line and --test-count go together");
+  if ("--test-count" in a && !isDigits(a["--test-count"])) {
+    throw cannot(`--test-count must be a whole number, got '${a["--test-count"]}'`);
+  }
+  if (("--mutate" in a) !== ("--mutation" in a)) throw cannot("--mutate and --mutation go together");
+  return {
+    repo,
+    install: a["--install"],
+    test: a["--test"],
+    countLine: a["--count-line"],
+    testCount: a["--test-count"],
+    mutate: a["--mutate"],
+    mutation: a["--mutation"],
+  };
+}
+
+function git(args, cwd) {
+  const r = spawnSync("git", args, { cwd, env: ENV, encoding: "utf8" });
+  return { ok: r.status === 0, out: (r.stdout ?? "").replace(/\n$/, ""), err: (r.stderr ?? "").trim() };
+}
+
+// Run a Recipe command through `sh -c` from the worktree root, its output to
+// a log file rather than a pipe: a real suite's output has no useful size
+// bound, and the log is what the caller reads a count line off. A command
+// killed by a signal (an OOM kill, a timeout wrapper) has no exit status, so
+// it is refused here and never reported as one: a crashed run must not count
+// as a red suite.
+function sh(cmd, cwd, log) {
+  const fd = openSync(log, "a");
+  try {
+    const r = spawnSync("sh", ["-c", cmd], { cwd, env: ENV, stdio: ["ignore", fd, fd] });
+    if (r.error) throw cannot(`could not start sh: ${r.error.message}`);
+    if (r.signal) throw notProven(`'${cmd}' was killed by ${r.signal}, so it has no exit status to read; output: ${log}`);
+    return r.status;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+const didNotRun = (rc) => rc === 126 || rc === 127;
+
+// `-uall` for the reason the header gives: an untracked, unignored file an
+// install creates dirties the tree as surely as a rewrite, and the untracked
+// mode is config — under status.showUntrackedFiles=no it is invisible unless
+// pinned.
+function treeChanges(wt) {
+  const s = git(["status", "--porcelain", "-uall"], wt);
+  if (!s.ok) throw notProven(`could not read the tree state in the throwaway worktree: ${s.err}`);
+  return s.out;
+}
+
+function prove(o, wt, logs) {
+  const installLog = join(logs, "install.log");
+  const irc = sh(o.install, wt, installLog);
+  if (didNotRun(irc)) {
+    throw notProven(`the Install step '${o.install}' did not run (exit ${irc}: not executable or not found); install output: ${installLog}`);
+  }
+  if (irc !== 0) throw notProven(`the Install step '${o.install}' failed (exit ${irc}); install output: ${installLog}`);
+  const dirty = treeChanges(wt);
+  if (dirty) throw notProven(`the Install step changed the tree (first: ${dirty.split("\n")[0]}); it must leave every file as checked out`);
+
+  const testLog = join(logs, "test.log");
+  const trc = sh(o.test, wt, testLog);
+  const where = `test output: ${testLog}`;
+  if (didNotRun(trc)) {
+    throw notProven(`the Test entrypoint '${o.test}' did not run (exit ${trc}: not executable or not found); ${where}`);
+  }
+  if (o.countLine === undefined && o.mutate === undefined) {
+    throw notProven(`no proof given — pass --count-line/--test-count or --mutate/--mutation (the run exited ${trc}); ${where}`);
+  }
+
+  const proof = {};
+  if (o.countLine !== undefined) {
+    const n = Number(o.testCount);
+    if (n === 0) throw notProven(`vacuous: a test count of 0 is a run that executed no tests; ${where}`);
+    if (!new RegExp(`(^|[^0-9])0*${n}([^0-9]|$)`).test(o.countLine)) {
+      throw notProven(`the count line '${o.countLine}' does not carry the test count ${n}`);
+    }
+    if (!readFileSync(testLog, "utf8").includes(o.countLine)) {
+      throw notProven(`vacuous: the Test entrypoint's output does not contain the count line '${o.countLine}' — no evidence any test ran; ${where}`);
+    }
+    proof.testCount = n;
+  }
+  if (o.mutate !== undefined) {
+    if (trc !== 0) {
+      throw notProven(`the unmutated run is already red (exit ${trc}), so a mutation turning it red proves nothing — use the count proof; ${where}`);
+    }
+    // What the unmutated Test run rewrote is not the mutation's work: restore
+    // every tracked file first, so the change read below is the mutation's alone.
+    const reset = git(["reset", "--hard", "-q", "HEAD"], wt);
+    if (!reset.ok) throw notProven(`could not restore the tree before the mutation: ${reset.err}`);
+    const mutateLog = join(logs, "mutate.log");
+    const mrc = sh(o.mutate, wt, mutateLog);
+    if (mrc !== 0) throw notProven(`the mutation command '${o.mutate}' failed (exit ${mrc}); its output: ${mutateLog}`);
+    // Against HEAD, not the index: a mutation that stages its edit (`git mv`,
+    // `git add`) changed a tracked file just as surely.
+    const changed = git(["diff", "HEAD", "--name-only"], wt);
+    if (!changed.ok) throw notProven(`could not read what the mutation changed: ${changed.err}`);
+    if (!changed.out) throw notProven(`the mutation (${o.mutation}) changed no tracked file — mutate a test, or the code a test covers`);
+    const mutatedLog = join(logs, "test-mutated.log");
+    const red = sh(o.test, wt, mutatedLog);
+    if (didNotRun(red)) throw notProven(`the Test entrypoint did not run on the mutated tree (exit ${red}); test output: ${mutatedLog}`);
+    if (red === 0) {
+      throw notProven(`vacuous: the mutation (${o.mutation}) did not turn the run red — the suite ran nothing it changed; test output: ${mutatedLog}`);
+    }
+    proof.mutation = `${o.mutation} — turned the run red (exit ${red}); changed ${changed.out.split("\n").join(", ")}`;
+  }
+  return proof;
+}
+
+// Write, then read back through the one reader. A cache it refuses is undone:
+// the prior bytes restored, or the file removed when none stood before.
+function writeCache(cache, recipe, repo) {
+  mkdirSync(dirname(cache), { recursive: true });
+  const prior = existsSync(cache) ? readFileSync(cache) : null;
+  const tmp = `${cache}.${process.pid}.tmp`;
+  try {
+    writeFileSync(tmp, `${JSON.stringify(recipe)}\n`);
+    renameSync(tmp, cache);
+  } catch (e) {
+    rmSync(tmp, { force: true });
+    throw e;
+  }
+  for (const field of ["install", "test"]) {
+    const r = spawnSync("sh", [READER, repo, field], { env: ENV, encoding: "utf8" });
+    if (r.status !== 0 || r.stdout.replace(/\n$/, "") !== recipe[field]) {
+      if (prior === null) unlinkSync(cache);
+      else writeFileSync(cache, prior);
+      throw notProven(`the Recipe cache reader refuses what was proven: ${(r.stderr || r.stdout).trim()}`);
+    }
+  }
+}
+
+// Best-effort, and never allowed to replace the proof's own outcome — a proof
+// that held, or a Refusal that names why it did not, is what the caller reads.
+// An Install step that leaves read-only directories behind (a Go module cache
+// is the usual one; the repo ignores them) makes both git's removal and a
+// plain recursive delete fail, so the fallback makes the tree writable first.
+// The prune always runs: it is what drops the registration of a worktree
+// whose directory is gone.
+function removeWorktree(wt, repo) {
+  if (!git(["worktree", "remove", "--force", wt], repo).ok) {
+    spawnSync("chmod", ["-R", "u+w", wt], { stdio: "ignore" });
+    try {
+      rmSync(wt, { recursive: true, force: true });
+    } catch (e) {
+      process.stderr.write(`${NAME}: could not remove the throwaway worktree ${wt}: ${e.message}\n`);
+    }
+  }
+  git(["worktree", "prune"], repo);
+}
+
+function main(argv) {
+  const o = parseArgs(argv);
+  if (!git(["rev-parse", "--git-dir"], o.repo).ok) throw cannot(`${o.repo} is not a git repository`);
+  const common = git(["rev-parse", "--path-format=absolute", "--git-common-dir"], o.repo);
+  const workspace = common.ok ? workspaceDirFromGitCommonDir(common.out, o.repo) : null;
+  if (!workspace) throw cannot(`cannot resolve the common git dir of ${o.repo}: ${common.err}`);
+  const sha = git(["rev-parse", "--verify", "origin/main^{commit}"], o.repo);
+  if (!sha.ok) throw cannot("origin/main does not resolve to a commit — fetch it; the proof runs against it");
+
+  const logs = mkdtempSync(join(tmpdir(), `${NAME}-`));
+  const wt = join(logs, "wt");
+  const add = git(["worktree", "add", "--detach", wt, sha.out], o.repo);
+  if (!add.ok) throw cannot(`could not create the throwaway worktree: ${add.err}`);
+  let proof;
+  try {
+    proof = prove(o, wt, logs);
+  } finally {
+    removeWorktree(wt, o.repo);
+  }
+
+  const recipe = { install: o.install, test: o.test, derivedAt: sha.out, installClean: true, ...proof };
+  const cache = join(workspace, ".fleet", "recipe.json");
+  writeCache(cache, recipe, o.repo);
+  process.stdout.write(`${NAME}: PROVEN — Recipe cache written to ${cache}\n${JSON.stringify(recipe)}\n`);
+}
+
+try {
+  main(process.argv.slice(2));
+} catch (e) {
+  // A fault outside the proof — the cache or its temp file could not be
+  // written — is "no verdict" (2), never the NOT PROVEN (1) a stack trace's
+  // exit status would read as.
+  if (!(e instanceof Refusal)) {
+    process.stderr.write(`${NAME}: ${e.message}\n`);
+    process.exit(2);
+  }
+  // The closing sentence on a line of its own: most reasons end in a log path,
+  // and a `.` riding on one would read as part of it.
+  const msg = e.code === 1 ? `NOT PROVEN — ${e.message}\nNo Recipe cache written.` : e.message;
+  process.stderr.write(`${NAME}: ${msg}\n`);
+  process.exit(e.code);
+}

package/scripts/recipe-prove.test.mjs

@@ -0,0 +1,537 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync, spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tempDir } from "./temp-dir.mjs";
+import { writeExecStub } from "./exec-stub.mjs";
+
+// recipe-prove.mjs is the Recipe derivation step's proof and the ONE writer of
+// the Recipe cache: the deriving agent chooses the Install step and the Test
+// entrypoint by reading the repository, and this script is what turns that
+// guess into a cache — or refuses to. These fixtures stand in for two
+// ecosystems the plugin keeps no knowledge of: a Maven-shaped repo and a
+// Go-shaped one, each run through a stub of its own toolchain on PATH, so the
+// suite needs neither `mvn` nor `go` and still exercises a command the
+// plugin never names.
+const SCRIPT = join(import.meta.dirname, "recipe-prove.mjs");
+const READER = join(import.meta.dirname, "derive-testcmd.sh");
+
+// Fixture construction must not inherit an ambient GIT_DIR: under one, `git
+// init` re-inits whatever it names and the fixture is built nowhere.
+const FIXTURE_ENV = { ...process.env, GIT_DIR: undefined, GIT_WORK_TREE: undefined };
+
+// A stub `mvn`: `test` counts the @Test methods under src/test/java, prints
+// Surefire's own summary line, and fails when a test asserts 1 == 2. Any other
+// goal stands in for a dependency fetch and writes into `target/`, which the
+// fixture ignores — the build output a real install leaves behind.
+const MVN = `#!/bin/sh
+if [ "$1" = -q ]; then shift; fi
+case $1 in
+test)
+  n=0; fail=0
+  for f in $(find src/test/java -name '*Test.java' 2>/dev/null); do
+    c=$(grep -c '@Test' "$f"); n=$((n + c))
+    if grep -q 'assertEquals(1, 2)' "$f"; then fail=1; fi
+  done
+  if [ "$n" -eq 0 ]; then echo "No tests to run."; exit 0; fi
+  echo "Tests run: $n, Failures: $fail, Errors: 0, Skipped: 0"
+  if [ "$fail" -ne 0 ]; then echo "BUILD FAILURE"; exit 1; fi
+  echo "BUILD SUCCESS" ;;
+*) mkdir -p target && : > target/deps ;;
+esac
+`;
+
+// A stub `go`: `go test ./...` reports "[no test files]" and passes when no
+// _test.go is tracked — the vacuous green the real one gives — and otherwise
+// passes only while Add still adds. It prints no test count, like the real
+// one without -v: the mutation proof is the only proof this fixture offers.
+const GO = `#!/bin/sh
+[ "$1" = test ] || exit 0
+if [ -z "$(find . -name '*_test.go' -not -path './.git/*')" ]; then
+  printf '?   \\texample.com/calc\\t[no test files]\\n'; exit 0
+fi
+if grep -q 'return a + b' calc.go; then printf 'ok  \\texample.com/calc\\t0.001s\\n'; exit 0; fi
+printf -- '--- FAIL: TestAdd\\nFAIL\\texample.com/calc\\n'; exit 1
+`;
+
+function toolchain() {
+  const bin = tempDir("recipe-prove-bin-");
+  writeExecStub(join(bin, "mvn"), MVN);
+  writeExecStub(join(bin, "go"), GO);
+  return bin;
+}
+const BIN = toolchain();
+
+const MAVEN_FILES = {
+  "pom.xml": "<project><modelVersion>4.0.0</modelVersion><groupId>x</groupId><artifactId>foo</artifactId><version>1</version></project>\n",
+  ".gitignore": "target/\n",
+  "src/main/java/x/Foo.java": "package x; public class Foo { public int one() { return 1; } }\n",
+  "src/test/java/x/FooTest.java":
+    "package x;\nimport org.junit.jupiter.api.Test;\nimport static org.junit.jupiter.api.Assertions.assertEquals;\n" +
+    "class FooTest {\n  @Test void one() { assertEquals(1, new Foo().one()); }\n}\n",
+};
+
+const GO_FILES = {
+  "go.mod": "module example.com/calc\n\ngo 1.22\n",
+  "calc.go": "package calc\n\nfunc Add(a, b int) int { return a + b }\n",
+  "calc_test.go":
+    'package calc\n\nimport "testing"\n\nfunc TestAdd(t *testing.T) {\n\tif Add(1, 2) != 3 {\n\t\tt.Fatal("Add")\n\t}\n}\n',
+};
+
+function git(dir, ...a) {
+  return execFileSync("git", a, { cwd: dir, stdio: "pipe", env: FIXTURE_ENV, encoding: "utf8" }).trim();
+}
+
+function write(dir, files) {
+  for (const [name, body] of Object.entries(files)) {
+    mkdirSync(join(dir, name, ".."), { recursive: true });
+    writeFileSync(join(dir, name), body);
+  }
+}
+
+// A repository whose `origin/main` is the commit holding `files` — the ref the
+// proof runs against. Set with update-ref, so no remote is needed.
+function repo(files) {
+  const dir = tempDir("recipe-prove-");
+  git(dir, "init", "-q");
+  git(dir, "config", "user.email", "t@t");
+  git(dir, "config", "user.name", "t");
+  write(dir, files);
+  git(dir, "add", "-A");
+  git(dir, "commit", "-q", "-m", "files");
+  git(dir, "update-ref", "refs/remotes/origin/main", "HEAD");
+  return { dir, head: git(dir, "rev-parse", "HEAD") };
+}
+
+function withoutTests(files) {
+  return Object.fromEntries(Object.entries(files).filter(([n]) => !/(^src\/test\/|_test\.go$)/.test(n)));
+}
+
+const cachePath = (dir) => join(dir, ".fleet", "recipe.json");
+
+function prove(dir, args, { env = {}, cwd = dir } = {}) {
+  const tmp = tempDir("recipe-prove-tmp-");
+  const r = spawnSync(process.execPath, [SCRIPT, dir, ...args], {
+    encoding: "utf8",
+    cwd,
+    env: { ...FIXTURE_ENV, PATH: `${BIN}:${process.env.PATH}`, TMPDIR: tmp, ...env },
+    timeout: 60_000,
+  });
+  return { status: r.status, out: r.stdout, err: r.stderr, tmp };
+}
+
+function read(dir, field) {
+  const r = spawnSync("sh", [READER, dir, field], {
+    encoding: "utf8",
+    env: { ...FIXTURE_ENV, PATH: `${BIN}:${process.env.PATH}` },
+  });
+  return { status: r.status, out: r.stdout.replace(/\n$/, ""), err: r.stderr };
+}
+
+const MAVEN_PROOF = ["--install", "mvn -q dependency:go-offline", "--test", "mvn -q test", "--count-line", "Tests run: 1,", "--test-count", "1"];
+const GO_PROOF = [
+  "--install", "go mod download",
+  "--test", "go test ./...",
+  "--mutate", "printf 'package calc\\n\\nfunc Add(a, b int) int { return a - b }\\n' > calc.go",
+  "--mutation", "Add subtracts instead of adding",
+];
+
+test("a Maven-shaped repo gets a proven cache: the count proof, derivedAt, installClean — and the reader accepts it", () => {
+  const { dir, head } = repo(MAVEN_FILES);
+  const r = prove(dir, MAVEN_PROOF);
+  assert.equal(r.status, 0, r.err);
+  const cache = JSON.parse(readFileSync(cachePath(dir), "utf8"));
+  assert.deepEqual(cache, {
+    install: "mvn -q dependency:go-offline",
+    test: "mvn -q test",
+    derivedAt: head,
+    installClean: true,
+    testCount: 1,
+  });
+  assert.deepEqual([read(dir, "install").out, read(dir, "test").out], ["mvn -q dependency:go-offline", "mvn -q test"]);
+});
+
+test("a Go-shaped repo gets a proven cache through the mutation proof, which records what turned the run red", () => {
+  const { dir, head } = repo(GO_FILES);
+  const r = prove(dir, GO_PROOF);
+  assert.equal(r.status, 0, r.err);
+  const cache = JSON.parse(readFileSync(cachePath(dir), "utf8"));
+  assert.equal(cache.install, "go mod download");
+  assert.equal(cache.test, "go test ./...");
+  assert.equal(cache.derivedAt, head);
+  assert.equal(cache.installClean, true);
+  assert.equal(cache.testCount, undefined);
+  assert.match(cache.mutation, /^Add subtracts instead of adding — turned the run red \(exit 1\); changed calc\.go$/);
+  assert.equal(read(dir, "test").out, "go test ./...");
+});
+
+test("the Maven fixture with its tests deleted gets NO cache, and the refusal names vacuity", () => {
+  const { dir } = repo(withoutTests(MAVEN_FILES));
+  const r = prove(dir, MAVEN_PROOF);
+  assert.equal(r.status, 1, r.err);
+  assert.match(r.err, /NOT PROVEN — vacuous: the Test entrypoint's output does not contain the count line 'Tests run: 1,'/);
+  assert.match(r.err, /No Recipe cache written/);
+  assert.equal(existsSync(cachePath(dir)), false);
+});
+
+test("the Go fixture with its tests deleted gets NO cache: the mutation leaves the run green, which is vacuity", () => {
+  const { dir } = repo(withoutTests(GO_FILES));
+  const r = prove(dir, GO_PROOF);
+  assert.equal(r.status, 1, r.err);
+  assert.match(r.err, /NOT PROVEN — vacuous: the mutation \(Add subtracts instead of adding\) did not turn the run red/);
+  assert.equal(existsSync(cachePath(dir)), false);
+});
+
+test("a count proof of zero tests is a failed proof, even when the runner prints exactly that", () => {
+  const { dir } = repo(withoutTests(MAVEN_FILES));
+  const r = prove(dir, ["--install", "true", "--test", "echo 'tests 0'", "--count-line", "tests 0", "--test-count", "0"]);
+  assert.equal(r.status, 1);
+  assert.match(r.err, /NOT PROVEN — vacuous: a test count of 0/);
+  assert.equal(existsSync(cachePath(dir)), false);
+});
+
+test("the claimed count must be the number on the count line, not any number", () => {
+  const { dir } = repo(MAVEN_FILES);
+  const r = prove(dir, ["--install", "true", "--test", "mvn -q test", "--count-line", "Tests run: 1,", "--test-count", "7"]);
+  assert.equal(r.status, 1);
+  assert.match(r.err, /the count line 'Tests run: 1,' does not carry the test count 7/);
+  assert.equal(existsSync(cachePath(dir)), false);
+});
+
+test("an Install step that changes a tracked file is not proven", () => {
+  const { dir } = repo(MAVEN_FILES);
+  const r = prove(dir, ["--install", "echo '<!-- -->' >> pom.xml", ...MAVEN_PROOF.slice(2)]);
+  assert.equal(r.status, 1);
+  assert.match(r.err, /NOT PROVEN — the Install step changed the tree \(first:  M pom\.xml\)/);
+  assert.equal(existsSync(cachePath(dir)), false);
+});
+
+test("an Install step that creates a file the tree neither tracks nor ignores is not proven", () => {
+  const { dir } = repo(MAVEN_FILES);
+  const r = prove(dir, ["--install", ": > deps.lock", ...MAVEN_PROOF.slice(2)]);
+  assert.equal(r.status, 1);
+  assert.match(r.err, /the Install step changed the tree \(first: \?\? deps\.lock\)/);
+});
+
+test("an Install step whose output the repo ignores IS proven — build output is not a dirty tree", () => {
+  // The stub mvn's dependency goal writes target/deps; the fixture ignores
+  // target/. Refusing here would refuse every repo whose install builds.
+  const { dir } = repo(MAVEN_FILES);
+  const r = prove(dir, MAVEN_PROOF);
+  assert.equal(r.status, 0, r.err);
+});
+
+test("an Install step or Test entrypoint that does not RUN is named as such", () => {
+  const { dir } = repo(MAVEN_FILES);
+  const i = prove(dir, ["--install", "no-such-installer-xyz", ...MAVEN_PROOF.slice(2)]);
+  assert.equal(i.status, 1);
+  assert.match(i.err, /NOT PROVEN — the Install step 'no-such-installer-xyz' did not run \(exit 127: not executable or not found\)/);
+  const t = prove(dir, ["--install", "true", "--test", "no-such-runner-xyz", "--count-line", "x 1", "--test-count", "1"]);
+  assert.equal(t.status, 1);
+  assert.match(t.err, /NOT PROVEN — the Test entrypoint 'no-such-runner-xyz' did not run \(exit 127/);
+  assert.equal(existsSync(cachePath(dir)), false);
+});
+
+test("an Install step that fails is not proven", () => {
+  const { dir } = repo(MAVEN_FILES);
+  const r = prove(dir, ["--install", "exit 3", ...MAVEN_PROOF.slice(2)]);
+  assert.equal(r.status, 1);
+  assert.match(r.err, /NOT PROVEN — the Install step 'exit 3' failed \(exit 3\)/);
+});
+
+test("the mutation proof refuses a red baseline: a mutation turning a red run red proves nothing", () => {
+  const { dir } = repo(GO_FILES);
+  const r = prove(dir, ["--install", "true", "--test", "go test ./... && exit 1", ...GO_PROOF.slice(4)]);
+  assert.equal(r.status, 1);
+  assert.match(r.err, /the unmutated run is already red \(exit 1\), so a mutation turning it red proves nothing — use the count proof/);
+});
+
+test("a mutation that changes no tracked file is refused, not counted as red", () => {
+  const { dir } = repo(GO_FILES);
+  const r = prove(dir, ["--install", "true", "--test", "go test ./...", "--mutate", ": > new_test.go", "--mutation", "adds a file"]);
+  assert.equal(r.status, 1);
+  assert.match(r.err, /the mutation \(adds a file\) changed no tracked file/);
+});
+
+test("a mutation that stages its edit still counts as changing a tracked file", () => {
+  const { dir } = repo(GO_FILES);
+  const r = prove(dir, [...GO_PROOF.slice(0, 4), "--mutate", `${GO_PROOF[5]} && git add calc.go`, "--mutation", "Add subtracts, staged"]);
+  assert.equal(r.status, 0, r.err);
+  assert.match(JSON.parse(readFileSync(cachePath(dir), "utf8")).mutation, /changed calc\.go$/);
+});
+
+test("no proof given is a refusal that still shows where the run's output is", () => {
+  const { dir } = repo(MAVEN_FILES);
+  const r = prove(dir, ["--install", "true", "--test", "mvn -q test"]);
+  assert.equal(r.status, 1);
+  assert.match(r.err, /NOT PROVEN — no proof given/);
+  const log = r.err.match(/test output: (\S+)/);
+  assert.ok(log, r.err);
+  assert.match(readFileSync(log[1], "utf8"), /Tests run: 1, Failures: 0/);
+  assert.equal(existsSync(cachePath(dir)), false);
+});
+
+test("the proof runs against origin/main, not the checkout's own HEAD, and derivedAt says so", () => {
+  // The local branch has deleted the tests; origin/main still has them. A
+  // proof run against the checkout would be vacuous — against origin/main it
+  // is not.
+  const { dir, head } = repo(MAVEN_FILES);
+  rmSync(join(dir, "src", "test"), { recursive: true });
+  git(dir, "commit", "-q", "-am", "drop tests locally");
+  const r = prove(dir, MAVEN_PROOF);
+  assert.equal(r.status, 0, r.err);
+  assert.equal(JSON.parse(readFileSync(cachePath(dir), "utf8")).derivedAt, head);
+});
+
+test("a failed proof leaves an existing cache byte-identical — it never writes on a guess", () => {
+  const { dir } = repo(withoutTests(MAVEN_FILES));
+  mkdirSync(join(dir, ".fleet"));
+  writeFileSync(cachePath(dir), "prior bytes");
+  const r = prove(dir, MAVEN_PROOF);
+  assert.equal(r.status, 1);
+  assert.equal(readFileSync(cachePath(dir), "utf8"), "prior bytes");
+});
+
+test("a cache the reader would refuse is not left behind: it is rolled back to what stood before", () => {
+  // `mvn -q test;` runs fine under sh -c, but a trailing `;` would let a
+  // runner-appended argument run as its own command, so the reader refuses it.
+  const { dir } = repo(MAVEN_FILES);
+  mkdirSync(join(dir, ".fleet"));
+  writeFileSync(cachePath(dir), "prior bytes");
+  const r = prove(dir, ["--install", "true", "--test", "mvn -q test;", "--count-line", "Tests run: 1,", "--test-count", "1"]);
+  assert.equal(r.status, 1, r.err);
+  assert.match(r.err, /NOT PROVEN — the Recipe cache reader refuses what was proven: .*ends in ';'/);
+  assert.equal(readFileSync(cachePath(dir), "utf8"), "prior bytes");
+
+  const { dir: fresh } = repo(MAVEN_FILES);
+  const f = prove(fresh, ["--install", "true", "--test", "mvn -q test;", "--count-line", "Tests run: 1,", "--test-count", "1"]);
+  assert.equal(f.status, 1);
+  assert.equal(existsSync(cachePath(fresh)), false, "no prior cache: the refused one is removed, not left");
+});
+
+test("from a linked worktree the cache lands beside the common git dir — the main checkout the reader reads", () => {
+  const { dir, head } = repo(MAVEN_FILES);
+  const wt = join(tempDir("recipe-prove-wt-"), "wt");
+  git(dir, "worktree", "add", "-q", "--detach", wt);
+  const r = prove(wt, MAVEN_PROOF);
+  assert.equal(r.status, 0, r.err);
+  assert.equal(JSON.parse(readFileSync(cachePath(dir), "utf8")).derivedAt, head);
+  assert.equal(existsSync(cachePath(wt)), false);
+});
+
+test("the throwaway worktree is removed afterwards, proven or not", () => {
+  const { dir } = repo(MAVEN_FILES);
+  prove(dir, MAVEN_PROOF);
+  prove(dir, ["--install", "exit 3", ...MAVEN_PROOF.slice(2)]);
+  assert.equal(git(dir, "worktree", "list", "--porcelain").split("\n").filter((l) => l.startsWith("worktree ")).length, 1);
+});
+
+test("an ambient GIT_DIR naming another repository does not change the answer", () => {
+  const { dir, head } = repo(MAVEN_FILES);
+  const { dir: other } = repo(withoutTests(MAVEN_FILES));
+  const r = prove(dir, MAVEN_PROOF, { env: { GIT_DIR: join(other, ".git"), GIT_WORK_TREE: other } });
+  assert.equal(r.status, 0, r.err);
+  assert.equal(JSON.parse(readFileSync(cachePath(dir), "utf8")).derivedAt, head);
+  assert.equal(existsSync(cachePath(other)), false);
+});
+
+test("a proof that cannot be attempted exits 2, distinct from a Recipe that is not proven", () => {
+  const usage = spawnSync(process.execPath, [SCRIPT], { encoding: "utf8", env: FIXTURE_ENV });
+  assert.equal(usage.status, 2);
+  assert.match(usage.stderr, /usage: recipe-prove\.mjs <repo> --install <cmd> --test <cmd>/);
+
+  const notRepo = prove(tempDir("recipe-prove-norepo-"), MAVEN_PROOF);
+  assert.equal(notRepo.status, 2);
+  assert.match(notRepo.err, /is not a git repository/);
+
+  const { dir } = repo(MAVEN_FILES);
+  git(dir, "update-ref", "-d", "refs/remotes/origin/main");
+  const noMain = prove(dir, MAVEN_PROOF);
+  assert.equal(noMain.status, 2);
+  assert.match(noMain.err, /origin\/main does not resolve to a commit/);
+
+  const { dir: half } = repo(MAVEN_FILES);
+  const r = prove(half, ["--install", "true", "--test", "mvn -q test", "--count-line", "Tests run: 1,"]);
+  assert.equal(r.status, 2);
+  assert.match(r.err, /--count-line and --test-count go together/);
+
+  const nan = prove(half, ["--install", "true", "--test", "mvn -q test", "--count-line", "Tests run: 1,", "--test-count", "1e0"]);
+  assert.equal(nan.status, 2);
+  assert.match(nan.err, /--test-count must be a whole number, got '1e0'/);
+
+  // A flag where a value belongs is a missing value, never the command. The
+  // fixture must be one whose swallowed value would otherwise be ACCEPTED: with
+  // `--install --test "mvn -q test"` the later iteration refuses on its own
+  // and the guard under test is never what fires.
+  const missing = prove(half, ["--install", "--test", "--test", "mvn -q test"]);
+  assert.equal(missing.status, 2);
+  assert.match(missing.err, /^recipe-prove: usage:/);
+  assert.equal(git(half, "worktree", "list", "--porcelain").split("\n").filter((l) => l.startsWith("worktree ")).length, 1,
+    "a refusal at the argument boundary creates no worktree");
+});
+
+test("the proof leaves no worktree directory behind in its temp dir", () => {
+  const { dir } = repo(MAVEN_FILES);
+  const r = prove(dir, MAVEN_PROOF);
+  assert.equal(r.status, 0, r.err);
+  for (const d of readdirSync(r.tmp)) {
+    assert.deepEqual(readdirSync(join(r.tmp, d)).filter((n) => n === "wt"), [], `${d} still holds the throwaway worktree`);
+  }
+});
+
+// Whether the process ignores file modes: root writes into a 0555 directory.
+const IGNORES_MODES = process.getuid?.() === 0 && "root ignores file modes";
+
+// An Install step whose output the repo ignores and leaves read-only — a Go
+// module cache is the usual one. git's own removal of the worktree fails on it.
+const READ_ONLY_INSTALL = "mkdir -p build/x && : > build/x/f && chmod 555 build/x";
+const IGNORING_BUILD = { ...MAVEN_FILES, ".gitignore": "target/\nbuild/\n" };
+
+test("read-only install output cannot turn a proof that held into a crash", { skip: IGNORES_MODES }, () => {
+  const { dir, head } = repo(IGNORING_BUILD);
+  const r = prove(dir, ["--install", READ_ONLY_INSTALL, ...MAVEN_PROOF.slice(2)]);
+  assert.equal(r.status, 0, r.err);
+  assert.equal(JSON.parse(readFileSync(cachePath(dir), "utf8")).derivedAt, head);
+  for (const d of readdirSync(r.tmp)) {
+    assert.deepEqual(readdirSync(join(r.tmp, d)).filter((n) => n === "wt"), [], `${d} still holds the throwaway worktree`);
+  }
+  assert.equal(git(dir, "worktree", "list", "--porcelain").split("\n").filter((l) => l.startsWith("worktree ")).length, 1);
+});
+
+test("read-only install output does not replace a refusal's reason with a stack trace", { skip: IGNORES_MODES }, () => {
+  const { dir } = repo(IGNORING_BUILD);
+  const r = prove(dir, ["--install", READ_ONLY_INSTALL, "--test", "echo 'tests 0'", "--count-line", "tests 0", "--test-count", "0"]);
+  assert.equal(r.status, 1);
+  assert.match(r.err, /NOT PROVEN — vacuous: a test count of 0/);
+  assert.doesNotMatch(r.err, /ENOTEMPTY/);
+  assert.equal(existsSync(cachePath(dir)), false);
+});
+
+test("a cache that cannot be written is exit 2 with its reason, never a stack trace or a NOT PROVEN", { skip: IGNORES_MODES }, () => {
+  const { dir } = repo(MAVEN_FILES);
+  mkdirSync(join(dir, ".fleet"));
+  chmodSync(join(dir, ".fleet"), 0o555);
+  try {
+    const r = prove(dir, MAVEN_PROOF);
+    assert.equal(r.status, 2, r.err);
+    assert.match(r.err, /^recipe-prove: EACCES/);
+    assert.doesNotMatch(r.err, /\n\s+at /);
+    assert.doesNotMatch(r.err, /NOT PROVEN/);
+    assert.equal(r.out, "");
+  } finally {
+    chmodSync(join(dir, ".fleet"), 0o755);
+  }
+});
+
+test("a command killed by a signal is refused, never counted as a red or a green run", () => {
+  // The count proof: the output carries the count line, then the run dies.
+  const { dir } = repo(MAVEN_FILES);
+  const t = prove(dir, ["--install", "true", "--test", "echo 'tests 3'; kill -9 $$", "--count-line", "tests 3", "--test-count", "3"]);
+  assert.equal(t.status, 1, t.err);
+  assert.match(t.err, /NOT PROVEN — 'echo 'tests 3'; kill -9 \$\$' was killed by SIGKILL/);
+  assert.equal(existsSync(cachePath(dir)), false);
+
+  // The mutation proof: the unmutated run is green, the mutated one dies — a
+  // crash is not a test failing.
+  const { dir: go } = repo(GO_FILES);
+  const dies = "if grep -q 'a - b' calc.go; then kill -9 $$; else go test ./...; fi";
+  const m = prove(go, ["--install", "true", "--test", dies, ...GO_PROOF.slice(4)]);
+  assert.equal(m.status, 1, m.err);
+  assert.match(m.err, /NOT PROVEN — '.*kill -9 \$\$.*' was killed by SIGKILL/);
+  assert.equal(existsSync(cachePath(go)), false);
+});
+
+test("an untracked file an Install step creates is seen even under status.showUntrackedFiles=no", () => {
+  const { dir } = repo(MAVEN_FILES);
+  git(dir, "config", "status.showUntrackedFiles", "no");
+  const r = prove(dir, ["--install", ": > deps.lock", ...MAVEN_PROOF.slice(2)]);
+  assert.equal(r.status, 1, r.err);
+  assert.match(r.err, /the Install step changed the tree \(first: \?\? deps\.lock\)/);
+  assert.equal(existsSync(cachePath(dir)), false);
+});
+
+test("the claimed count is a whole number on the count line, leading zeros aside", () => {
+  const claim = (line, n) => {
+    const { dir } = repo(MAVEN_FILES);
+    return { dir, ...prove(dir, ["--install", "true", "--test", `echo '${line}'`, "--count-line", line, "--test-count", n]) };
+  };
+  // 1 is a substring of 11 and of 21, and is not the number either line carries.
+  for (const line of ["Tests run: 11", "21 passed"]) {
+    const r = claim(line, "1");
+    assert.equal(r.status, 1, `${line}: ${r.err}`);
+    assert.match(r.err, /does not carry the test count 1/);
+    assert.equal(existsSync(cachePath(r.dir)), false);
+  }
+  // A runner that zero-pads its count still carries it.
+  const padded = claim("tests 01", "1");
+  assert.equal(padded.status, 0, padded.err);
+  assert.equal(JSON.parse(readFileSync(cachePath(padded.dir), "utf8")).testCount, 1);
+});
+
+test("the Install step and the Test entrypoint run against their own worktree whatever GIT_DIR the caller exports", () => {
+  // Each command asks git where it is: with an ambient GIT_DIR/GIT_WORK_TREE
+  // reaching the `sh -c` child, the answer is the other repository.
+  const here = 'test "$(git rev-parse --show-toplevel)" = "$(pwd -P)"';
+  const args = ["--install", here, "--test", `${here} && mvn -q test`, "--count-line", "Tests run: 1,", "--test-count", "1"];
+  const { dir } = repo(MAVEN_FILES);
+  const control = prove(dir, args);
+  assert.equal(control.status, 0, `the commands pass without an ambient GIT_DIR: ${control.err}`);
+
+  const { dir: other } = repo(withoutTests(MAVEN_FILES));
+  const { dir: dir2 } = repo(MAVEN_FILES);
+  const r = prove(dir2, args, { env: { GIT_DIR: join(other, ".git"), GIT_WORK_TREE: other } });
+  assert.equal(r.status, 0, r.err);
+});
+
+test("exit 126 and 127 both mean a command did not RUN, in the Install step and in the Test entrypoint", () => {
+  const { dir } = repo({ ...MAVEN_FILES, "t.sh": "echo 'Tests run: 1,'\n" });
+  // t.sh is committed 0644: `sh -c ./t.sh` exits 126, "found but not executable".
+  const i = prove(dir, ["--install", "./t.sh", ...MAVEN_PROOF.slice(2)]);
+  assert.equal(i.status, 1);
+  assert.match(i.err, /the Install step '\.\/t\.sh' did not run \(exit 126/);
+  const t = prove(dir, ["--install", "true", "--test", "./t.sh", "--count-line", "Tests run: 1,", "--test-count", "1"]);
+  assert.equal(t.status, 1);
+  assert.match(t.err, /the Test entrypoint '\.\/t\.sh' did not run \(exit 126/);
+});
+
+test("a mutation command that fails, or that leaves nothing runnable, or that breaks git itself, is refused for that reason", () => {
+  const { dir } = repo(GO_FILES);
+  const failing = prove(dir, ["--install", "true", "--test", "go test ./...", "--mutate", "exit 3", "--mutation", "x"]);
+  assert.equal(failing.status, 1);
+  assert.match(failing.err, /the mutation command 'exit 3' failed \(exit 3\)/);
+
+  // The Test entrypoint is an executable the mutation deletes: the mutated run
+  // exits 127, which is not a red suite.
+  const { dir: tool } = repo({ tool: "#!/bin/sh\necho 'Tests run: 1,'\n" });
+  git(tool, "update-index", "--chmod=+x", "tool");
+  git(tool, "commit", "-q", "--amend", "--no-edit");
+  git(tool, "update-ref", "refs/remotes/origin/main", "HEAD");
+  const gone = prove(tool, ["--install", "true", "--test", "./tool", "--mutate", "rm tool", "--mutation", "delete the runner"]);
+  assert.equal(gone.status, 1);
+  assert.match(gone.err, /the Test entrypoint did not run on the mutated tree \(exit 127\)/);
+
+  // A mutation that removes the worktree's link to its repository leaves
+  // git unable to say what changed.
+  const { dir: blind } = repo(GO_FILES);
+  const lost = prove(blind, ["--install", "true", "--test", "go test ./...", "--mutate", "rm .git", "--mutation", "orphan the tree"]);
+  assert.equal(lost.status, 1);
+  assert.match(lost.err, /could not read what the mutation changed/);
+});
+
+test("the mutation is credited only with what it changed, never with what the unmutated Test run rewrote", () => {
+  // t.sh is red while state.txt holds anything, and otherwise writes into it:
+  // the unmutated run rewrites a tracked file.
+  const files = { "state.txt": "", "t.sh": "if [ -s state.txt ]; then exit 1; fi\necho run > state.txt\n" };
+  const { dir } = repo(files);
+  const noop = prove(dir, ["--install", "true", "--test", "sh t.sh", "--mutate", "true", "--mutation", "no-op"]);
+  assert.equal(noop.status, 1, noop.err);
+  assert.match(noop.err, /the mutation \(no-op\) changed no tracked file/);
+  assert.equal(existsSync(cachePath(dir)), false);
+
+  // A genuine mutation of a file the run also rewrites is still a mutation.
+  const { dir: real } = repo(files);
+  const r = prove(real, ["--install", "true", "--test", "sh t.sh", "--mutate", "echo x > state.txt", "--mutation", "poison the state"]);
+  assert.equal(r.status, 0, r.err);
+  assert.match(JSON.parse(readFileSync(cachePath(real), "utf8")).mutation, /changed state\.txt$/);
+});

package/skills/next-ticket/SKILL.md

@@ -76,7 +76,7 @@ gh label create in-progress --color FBCA04 --force   # first time only
 gh issue edit <N> --add-label in-progress
 ```
 
-Infer branch/worktree convention from `git worktree list` / `git branch -r` — commonly `feat|fix|refactor/<N>-slug` and `.worktrees/<N>-slug`. Branch off fresh `origin/main`, install deps, run test baseline.
+Infer branch/worktree convention from `git worktree list` / `git branch -r` — commonly `feat|fix|refactor/<N>-slug` and `.worktrees/<N>-slug`. Branch off fresh `origin/main`, run the Install step, run the Test entrypoint as the baseline — both the repo's **Recipe**, read from its Recipe cache: `~/.fleet/bin/fleet-run derive-testcmd.sh . install` and `… . test` print them. **No usable cache (either refuses) → run the Recipe derivation step first:** dispatch a `task` member, agent `fleet-recipe-deriver`, its prompt naming the main checkout's absolute path as `<repo>` and a scratch directory of its own; it reads the repo, proves both commands in a throwaway worktree and writes the cache only on proof. `RECIPE NOT PROVEN` → stop and give the maintainer its reason; never pick a command yourself.
 
 Abandoned before PR opens → remove `in-progress`.
 
@@ -90,7 +90,7 @@ Come back here. The sizing path hands off; this step always follows.
 
 ```bash
 git fetch origin && git rebase origin/main   # rebase, never merge main in
-<test command>                               # re-run after rebasing
+<test command>                               # the Recipe's Test entrypoint; re-run after rebasing
 git push --force-with-lease -u origin HEAD
 gh pr create --base main --body "…
 

package/skills/run-team/SKILL.md

@@ -361,6 +361,52 @@ phase, or in any later one, asks the maintainer which tickets to take.
    before this run's own first tick or beat, either of which writes the mark
    the guard reads. Older archives, hand-named ones included, are left alone.
 
+   **Derive the Recipe — the Recipe derivation step — before the fold-in below
+   and before the first claim.** Every claim runs this repository's Install
+   step and bakes its Test entrypoint into the member's runner, and every
+   review reads the Test entrypoint, all out of the **Recipe cache**
+   (`.fleet/recipe.json` beside the common git dir); no script infers either
+   command. Check it first: `~/.fleet/bin/fleet-run derive-testcmd.sh .
+   install` and `~/.fleet/bin/fleet-run derive-testcmd.sh . test`. **Both exit
+   0 → the cache is present and valid: use it as it stands and derive
+   nothing.** Either refuses → derive it. This step is yours: one derivation
+   per run start at most, never one per member, and a member never derives.
+   Dispatch a `task` member named `derive-recipe`, agent
+   `fleet-recipe-deriver`, and wait for its report — nothing in this run can
+   claim before it lands:
+
+   > Derive, prove and cache the Recipe of the repository at `<repo>`. Your
+   > scratch directory is `<scratch>/derive-recipe/`; write nowhere else.
+   > Follow your definition's procedure exactly, and end with its report line.
+
+   `<repo>` is this main checkout's absolute path and `<scratch>` is resolved
+   to an absolute path before you send it. The member reads the repository,
+   proposes both commands and proves them with `recipe-prove.mjs` in a
+   throwaway worktree of `origin/main`: the Install step must leave the tree
+   clean, and the Test entrypoint must be shown to run real tests — the
+   runner's own non-zero count, or a deliberate mutation of one test that
+   turns the run red. Only a proof writes the cache, with `derivedAt` (the
+   `origin/main` commit it ran against) and the proof itself. **`RECIPE
+   PROVEN`** → re-run both `derive-testcmd.sh` reads; their output is the
+   Recipe this run uses. **`RECIPE NOT PROVEN`** → stall, below.
+
+   **Mid-run, a cache that stops running is re-derived once, then the run
+   stalls.** A claim or a review that refuses because the Recipe cache is
+   invalid — a command that no longer runs, or an Install step that changed
+   the tree — is the one mid-run trigger: dispatch `derive-recipe` again
+   exactly as above, then retry what refused. The Install step's refusals
+   fire after the claim has labelled the ticket and created its worktree, so
+   release that claim with `release-ticket.sh` first (**Release the claims
+   that never became PRs**). A red suite never triggers it: a failing test is
+   a finding, not a stale Recipe. **Stall:** `RECIPE NOT PROVEN` from any
+   derivation, or a second invalid-cache refusal after this run's one
+   re-derivation, halts the run — no Pull, no claim, no review dispatch — and
+   you report `STALL — Recipe not proven: <cause>` to the maintainer with the
+   deriver's reason verbatim. A repository the fleet cannot run needs human
+   hands, the `ready-for-human` cause: a toolchain this machine lacks, or a
+   suite that runs no tests the proof can see. It is never a loop: no third
+   derivation, and never a cache written by hand.
+
    **Fold in every PR a prior run left open, before shortlisting.** A chore PR
    carrying that run's own metrics, or ticket work whose review was deferred —
    both are reviewable work no member otherwise picks up, because the Shortlist
@@ -730,7 +776,7 @@ oldest-first slot; its row is rewritten to `impl-<N> …` when it is pulled,
 because `row` replaces the whole line.
 
 **Claiming.** `~/.fleet/bin/fleet-run claim-ticket.sh <N> impl-<N> implementer --apply` does
-the label, worktree, branch, frozen install, lockfile-clean assertion, and the
+the label, worktree, branch, the Recipe's Install step, the clean-tree assertion, and the
 isolation runner in one serial pass. The two arguments are always that literal
 pair — `impl-<N>` as `<slug>`, `implementer` as `<type>` — so the claim is
 branch `implementer/<N>-impl-<N>`, worktree `.worktrees/<N>-impl-<N>`. Never
@@ -738,9 +784,12 @@ read them off `git branch -r` or `git worktree list`: human branches on origin
 (`fix/…`, `docs/…`) have another shape, and the script takes both arguments as
 free text, so a pair copied from one claims under that shape at exit 0.
 
-**Infer `<install>` — never default to `npm install`.** A lockfile-mutating
-install in a throwaway worktree corrupts it for everyone; the script derives the
-frozen form from the lockfile and refuses to guess.
+**The Install step comes from the Recipe cache — never pass or infer one.** The
+claim reads it, and the Test entrypoint, through `derive-testcmd.sh`, runs the
+Install step in the fresh worktree and refuses if it left any file changed: an
+install that rewrites the tree in a throwaway worktree corrupts it for everyone.
+No cache is phase 0's Recipe derivation step not having run; an invalid one is
+its re-derive-once rule.
 
 **Materialize the isolation envelope as a file, not a briefing.** The runner is
 tracked at the repo root since #55, so every checkout has one; it derives its
@@ -2128,14 +2177,15 @@ The fix-applier prompt and every refuter brief carry the rule and the safe
 invocation form; the merge bot's brief is the wrong seat, because a bot
 reads gates and never injects a fault.
 
-**Where `testCmd` comes from:** the repo's own test command, the one you hand
-specialists per **Give specialists a stack-free test command** above — in this
-repo `node --test plugin/scripts/*.test.mjs`. Pass the same string to the
-review, to the fix-applier, and to the finisher — whose duty-2 mutation gate
-runs it too — so every gate runs one command. Omit it from the review args and
-the review (`review-core.mjs`, in a runner) now DERIVES it
-from the repo under review (#142) instead of defaulting to a fixed string —
-refusing outright if it can't; the fix-applier has no such fallback, so
+**Where `testCmd` comes from:** the repository's Test entrypoint, out of the
+Recipe cache phase 0's Recipe derivation step proved —
+`~/.fleet/bin/fleet-run derive-testcmd.sh . test` prints it, in this repo
+`node --test plugin/scripts/*.test.mjs` — and the one you hand specialists per
+**Give specialists a stack-free test command** above. Pass the same string to
+the review, to the fix-applier, and to the finisher — whose duty-2 mutation
+gate runs it too — so every gate runs one command. Omit it from the review args
+and the review (`review-core.mjs`, in a runner) reads the same cache itself,
+refusing outright when there is none; the fix-applier has no such fallback, so
 substituting `<testCmd>` with nothing leaves it no gate at all.
 
 **Where `<branch>` comes from:** the PR's head branch —