@feigi/fleet-ctl 3.69.2 → 3.71.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.
@@ -42,8 +42,11 @@ from the repository root by `sh -c`:
42
42
  and rewrites nothing: the frozen or locked mode where the tool has one.
43
43
  `true` when nothing needs installing. It must leave every file exactly as
44
44
  checked out; build output the repository ignores is fine.
45
- - **Test entrypoint** — the whole suite, the way CI runs it. Members run it
46
- with their own arguments appended (`sh -c '<test> "$@"'`), so prefer a form
45
+ - **Test entrypoint** — every test step in the merge-gating CI jobs that can
46
+ run in a fresh worktree on this host. Which steps qualify is yours to
47
+ decide, by reading CI and the repository. Members run it with their own
48
+ arguments appended (`sh -c '<test> "$@"'`), so it is one invocation: an
49
+ `&&` chain hands those arguments to its last command alone. Prefer a form
47
50
  where an appended test file or test name lands as an argument to the test
48
51
  runner. The cache reader refuses a command whose first word does not
49
52
  resolve from the repository root (a builtin, a `PATH` entry, or an
@@ -53,6 +56,13 @@ from the repository root by `sh -c`:
53
56
  resolves under its own directory option, e.g.
54
57
  `git -C web ls-files -- '*.test.ts'`: the reader accepts a quoted pattern
55
58
  unchecked.
59
+ - **Uncovered steps** — what the Test entrypoint leaves out, passed as
60
+ `--uncovered`: one JSON array of `{"step": "<the CI step>", "reason": "<why
61
+ it is left out>"}`, `'[]'` when it leaves out nothing. When no single
62
+ invocation covers every qualifying step, take the widest one and list every
63
+ qualifying step it leaves out; that is never a reason to report
64
+ `RECIPE NOT PROVEN`. A test step that cannot run here — it needs a service
65
+ this host lacks, secrets, or another OS — is listed too, with that reason.
56
66
 
57
67
  ## 2. Prove it — this procedure exactly
58
68
 
@@ -61,7 +71,7 @@ script creates and removes; `<repo>`'s own tree is never touched.
61
71
 
62
72
  **First run, to see the output** — no proof flags:
63
73
 
64
- ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --test '<test>'
74
+ ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --test '<test>' --uncovered '<uncovered>'
65
75
 
66
76
  It exits 1 with `NOT PROVEN — no proof given` once both commands ran, and
67
77
  names the Test entrypoint's output file (`test output: <path>`). Any other
@@ -74,7 +84,7 @@ and revise.
74
84
  text off that summary line, as printed, into `--count-line`, and the number
75
85
  of tests that ran into `--test-count`:
76
86
 
77
- ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --test '<test>' \
87
+ ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --test '<test>' --uncovered '<uncovered>' \
78
88
  --count-line '<literal text of the count line>' --test-count <n>
79
89
 
80
90
  The number is the tests that ran — never the skipped, the failed, or a
@@ -92,14 +102,14 @@ and revise.
92
102
  must change a tracked file; the script runs it in the throwaway worktree,
93
103
  requires the suite to go red, and discards the worktree after:
94
104
 
95
- ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --test '<test>' \
105
+ ~/.fleet/bin/fleet-run recipe-prove.mjs <repo> --install '<install>' --test '<test>' --uncovered '<uncovered>' \
96
106
  --mutate '<shell command that breaks one test>' --mutation '<one line: what it breaks>'
97
107
 
98
108
  Exit 0 is the proof holding: the script wrote the Recipe cache and printed
99
109
  `PROVEN` and the cache's contents. Exit 1 is `NOT PROVEN`, with the reason;
100
110
  no cache was written. Exit 2 means no verdict on the proof: it could not be
101
- attempted (no `origin/main`, not a repository) or the cache could not be
102
- written — report it, do not work around it.
111
+ attempted (no `origin/main`, not a repository, a malformed `--uncovered`) or
112
+ the cache could not be written — report it, do not work around it.
103
113
 
104
114
  The script bounds each command it runs itself — the Install step, both Test
105
115
  runs and the mutation — and refuses one still running at that bound as
@@ -14,7 +14,7 @@ argument-hint: [pr-number]
14
14
  **Write every ruling to `<scratch>/dispositions-<your name>.json`, `<your name>` the `fix-pr-<pr>[-x]` you were dispatched as (standalone, `fix-pr-<pr>`) — the disposition record `dispositions-check.mjs` judges against the review result file before any finisher is dispatched.** It is `{"head": "<the review file's head>", "run": "<the run root's name in the review path>", "entries": [ … ]}` — `run` the `<run>` of the review path your prompt names, which the check holds against the one the PR's latest `reviewed=` names, so a record written against an earlier review of the same PR, a same-head one included, is a mismatch (standalone, with no ledger naming a run, leave it out): one entry per `survived` finding and per `unverified` finding, plus one per `refuted` finding you reverse. 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` (a suggestion's refuter verdict file, in scope and, above the claim bar, out of scope) and `remedyFiles` (the files its remedy names). A `refuted` entry carries `scope`, `claimKind` and `disposition` like every other entry, and a non-empty `reason` holding the evidence that reverses it; a missing or blank `reason` is a mismatch. 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. `disposition` has no `dismiss`: an in-scope `survived` finding verified correct, needing no change, is deferred with `reason` `false-rationale` and filed on the closed suggestion-band record — step 5's `PR #<pr> review: the suggestion band, checked`.
15
15
  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). 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.
16
16
  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 + how many refuters you dispatched against out-of-scope suggestions + the pushed SHA) and stop. A specialist that has not reported to you is not a verdict line — `hub send` it by name for its report, then ask the controller, 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.
17
- 5. File each deferred finding: `gh issue create --label 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 body also carries the evidence triage needs: the refuter's verdict — the `verdictPath` reason, or the review's votes — and the candidate remedy.** **Every issue you create is labelled `needs-triage`; only triage sets `ready-for-agent`** — and the label 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. **A confirmed defect does not settle its remedy**, so confirming one earns it no other label: a confirmed defect with the remedy still open files `needs-triage`, and so does a finding you are unsure is broken at all. **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** — 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 an out-of-scope finding its refuter let survive or never decided, 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.** **Neither does a gap in a prose guard — a test holding prose to its wording — unless something acts on the guarded text: an agent follows it as an instruction (a skill, a command, an agent definition, a script's header or usage text, `AGENTS.md`), or a program other than its own guard reads it.** Whether anything does is your judgement, as `claimKind` is, and a gap below this bar is recorded `claimKind: shape`. A gap in a guard's own code — a slow pattern, a dead branch, an unchecked spawn result — takes the stakes of the prose it guards, and a helper several guards share takes the highest of theirs. A missed wording already in the tree is no guard gap — that prose is wrong — and neither is an input already in the tree that trips a guard's code; each files on its own merits. Once the prose is corrected, the observed wording may join the guard's literal ban, never a reader built to catch wordings nobody has written. A below-bar finding's only open question is "is this worth doing?", which answers itself under the repriced triage bar: measured 2026-08-15→31, 133 issues were triage-closed `wontfix` in sixteen days, 121 of them review deferrals, mostly this shape. 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 promotion mark this path leaves, 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 (a comment citing a second issue landed on that issue'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, `needs-triage`, which is why a band cannot carry this decision. Do **not** reach for phase 0's **decided?** test here. That is a *consumption* gate, and whether a filed issue is decided enough to reach it is triage's call, never the filer's. **The cost of this rule is watched:** open `needs-triage` issues citing `Deferred from PR` above 40 on 3 consecutive run dates send the filing rule back to the maintainer — batch triage, a fleet triage role, or a different bar. **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.
17
+ 5. File each deferred finding: `gh issue create --label 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 body also carries the evidence triage needs: the refuter's verdict — the `verdictPath` reason, or the review's votes — and the candidate remedy.** **Every issue you create is labelled `needs-triage`; only triage sets `ready-for-agent`** — and the label 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. **A confirmed defect does not settle its remedy**, so confirming one earns it no other label: a confirmed defect with the remedy still open files `needs-triage`, and so does a finding you are unsure is broken at all. **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** — 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 an out-of-scope finding its refuter let survive or never decided, 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.** **Neither does a gap in a prose guard — a test holding prose to its wording — unless something acts on the guarded text: an agent follows it as an instruction (a skill, a command, an agent definition, a script's header or usage text, `AGENTS.md`), or a program other than its own guard reads it.** Whether anything does is your judgement, as `claimKind` is, and a gap below this bar is recorded `claimKind: shape`. A gap in a guard's own code — a slow pattern, a dead branch, an unchecked spawn result — takes the stakes of the prose it guards, and a helper several guards share takes the highest of theirs. A missed wording already in the tree is no guard gap — that prose is wrong — and neither is an input already in the tree that trips a guard's code; each files on its own merits. Once the prose is corrected, the observed wording may join the guard's literal ban, never a reader built to catch wordings nobody has written. A below-bar finding's only open question is "is this worth doing?", which answers itself under the repriced triage bar: measured 2026-08-15→31, 133 issues were triage-closed `wontfix` in sixteen days, 121 of them review deferrals, mostly this shape. 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 promotion mark this path leaves, 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 (a comment citing a second issue landed on that issue'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, `needs-triage`, which is why a band cannot carry this decision. Do **not** reach for phase 0's **decided?** test here. That is a *consumption* gate, and whether a filed issue is decided enough to reach it is triage's call, never the filer's. **The cost of this rule is watched:** open `needs-triage` issues citing `Deferred from PR` above 40 on 3 consecutive run dates send the filing rule back to the maintainer — batch triage, a fleet triage role, or a different bar. **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/references/ledger.md`, which `SKILL.md`'s **Run ledger** section points at — 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.
18
18
  **A duplicate that should hold an open deferral is a comment, never a relabel.** Where the guard lands a finding whose home is an open issue on an existing one that is open, cite the refuters' verdict — or the review's votes — in the comment you leave there, and change no label. Never relabel `ready-for-agent` down to `needs-triage`: a `ready-for-agent` issue already holds a `needs-triage` finding, because triage already promoted it, and a later run's crashed refuters are no reason to send it back. A closed one cannot hold it: file a new open issue citing it, as the promotion rule above does for the closed record.
19
19
  **Name where each deferral went, in the disposition record.** Every entry you defer carries `issue`: the number of the issue you filed it to, commented it onto, or appended it to — the closed `PR #<pr> review: the suggestion band, checked` record included. A `suggestion`'s entry — an `unverified` finding with `refutersDispatched` of zero — also carries `verdictPath`, applied or deferred, in scope and, above the claim bar, out of scope: the absolute path of a file holding its refuter's verdict as JSON, `{"refuted": <boolean>, "reason": "<string>"}`, under your own `<scratch>/pr<N>/fix-XXXXXXXX/<finding>/` run root. An out-of-scope one whose refuter crashed before any verdict reached you still names the path its verdict would have taken there; out of scope, that file missing or holding no decision files the finding open `needs-triage`, while in scope it is a mismatch. `dispositions-check.mjs` reads each named issue back through `gh issue view --json labels,state,title` and each verdict file off disk; a mismatch names the row of its filing table the entry broke, so move or relabel that filing to the home the row names and run the check again. With `gh` unreachable, or an issue it cannot read, that filing goes unchecked: with nothing else broken the verdict is `unchecked` — never `ok`, and it exits 1 — so run the check again once `gh` answers.
20
20
  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-fix-pr-<pr>.json`; `--review <path>` names the review file, 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` with it, 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 comment <pr> --body "ready-to-merge-head: <prHead>"`, `prHead` being the full SHA your green `ci-state.mjs` reading reported, which the merge bot reads as the head the label was applied to, then `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, 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.
@@ -376,7 +376,7 @@ Arm with `persistent: true`, description `ready-to-merge label on this repo's PR
376
376
  - Seed `seen` **before** the loop so PRs already handled — including ones skipped for `CHANGES_REQUESTED` or left on red CI — do not re-fire every minute. Only a label appearing after arming is an event. The seed poll is guarded the same way as every tick: a `gh` call failing on the very first poll must not arm on an empty `seen`, which would replay the whole labeled set as spurious events on tick one.
377
377
  - The `if cur=$(poll)` guard — seed and every tick alike — keeps `seen` intact when a `gh` call fails transiently; without it a failed poll reads as an empty labeled set and either arms on nothing (the seed) or wipes `seen` (a tick), both replaying the full labeled set as events on the next successful poll. The guard depends on `poll` ending in the bare `gh` call, not in a pipe: `tr` sits at the call sites (not inside `poll`) precisely so a failing `gh` call's exit status reaches `cur=$(poll)` / `seed=$(poll)` instead of being swallowed by `tr`, which exits 0 regardless of what it reads.
378
378
  - **A full page is not a whole reading either.** `gh pr list` stops at its `--limit` — 30 when the flag is absent — with exit 0 and no warning, so `poll` passes an explicit one (`cap`, one variable for the flag and the check), and `capcheck` says once when a poll fills it and once when one comes back under it: the DEGRADED/RECOVERED latch `run-team/SKILL.md`'s CI Monitor uses for the same cause, and never a line per tick. The numbers a capped poll did return are still real events; the line is for the labels past them, which fire nothing while it holds.
379
- - **The per-PR loop is heredoc-fed on purpose — `for n in $cur` is the one form that cannot work here.** This runs under zsh, which word-splits an unquoted command substitution's result but *not* an unquoted parameter expansion, and `cur` is a parameter. Measured on zsh 5.9 with `seen` holding two PR numbers and `cur` those two plus a third: the bare form runs **one** iteration with the whole list glued into a single value and emits one `ready-to-merge label added:` event with all three numbers glued into it, one nonsense event naming no PR, while the real new PR is never reported; the heredoc form emits the third alone. `run-team/SKILL.md`'s **Shell traps** carries the mechanism, the remedy table and the `</dev/null` trap that bites the next command added inside this loop. Note the contrast with step 1's `for _ in $(seq 1 60)`: that is a command substitution, it splits, and it is correct as written.
379
+ - **The per-PR loop is heredoc-fed on purpose — `for n in $cur` is the one form that cannot work here.** This runs under zsh, which word-splits an unquoted command substitution's result but *not* an unquoted parameter expansion, and `cur` is a parameter. Measured on zsh 5.9 with `seen` holding two PR numbers and `cur` those two plus a third: the bare form runs **one** iteration with the whole list glued into a single value and emits one `ready-to-merge label added:` event with all three numbers glued into it, one nonsense event naming no PR, while the real new PR is never reported; the heredoc form emits the third alone. `run-team/SKILL.md`'s **Shell traps** carries the mechanism and the `</dev/null` trap that bites the next command added inside this loop, and `run-team/references/shell-traps.md` carries the remedy table. Note the contrast with step 1's `for _ in $(seq 1 60)`: that is a command substitution, it splits, and it is correct as written.
380
380
  - 60s poll — remote API, stay off rate limits.
381
381
  - A held PR stays in `seen`, so its own label will not re-fire. Fine: what unblocks it is the **lower** PR getting labeled, which does fire, and step 4's re-evaluation picks up both in numeric order.
382
382
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.69.2",
3
+ "version": "3.71.0",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -1,6 +1,7 @@
1
1
  #!/bin/sh
2
- # Read one command of a repository's proven Recipe out of its Recipe cache:
3
- # `install` (the Install step) or `test` (the Test entrypoint).
2
+ # Read one field of a repository's proven Recipe out of its Recipe cache:
3
+ # `install` (the Install step), `test` (the Test entrypoint) or `uncovered`
4
+ # (the CI test steps the Test entrypoint leaves out).
4
5
  #
5
6
  # The fleet keeps no table of technologies. A Recipe is DERIVED by an agent
6
7
  # reasoning over the repository and PROVEN before it is written — the Install
@@ -27,11 +28,16 @@
27
28
  # installClean true the Install step left `git status --porcelain` empty
28
29
  # testCount integer >0, the test count the proving run reported, and/or
29
30
  # mutation string the deliberate failing mutation that turned it red
31
+ # uncovered array every test step of the merge-gating CI jobs the Test
32
+ # entrypoint does not run, `[]` when it runs them all:
33
+ # each entry `{ "step": <string>, "reason": <string> }`,
34
+ # both non-empty
30
35
  #
31
36
  # At least one of testCount/mutation is the proof; a cache carrying neither,
32
- # or `installClean` anything but `true`, is an UNPROVEN Recipe and refused like
33
- # an absent one. Written only by recipe-prove.mjs, the derivation step's proof,
34
- # and only once that proof holds; this script never writes it.
37
+ # `installClean` anything but `true`, or no well-formed `uncovered`, is an
38
+ # UNPROVEN Recipe and refused like an absent one. Written only by
39
+ # recipe-prove.mjs, the derivation step's proof, and only once that proof
40
+ # holds; this script never writes it.
35
41
  #
36
42
  # INVALID on failure to RUN, never on failing tests: the command this script
37
43
  # is asked for must name something that resolves from <repo> (a builtin, a
@@ -44,8 +50,9 @@
44
50
  # tree that probe reads instead of <repo>'s own index, for a caller that runs
45
51
  # the command in a worktree cut from a ref.
46
52
  #
47
- # Exit status: 0 the command is printed; 1 a refusal about the cache, the
48
- # repository or the arguments; 3 a tool this script needs to read the cache
53
+ # Exit status: 0 the field is printed, `uncovered` as one line of compact
54
+ # JSON; 1 a refusal about the cache, the repository or the arguments; 3 a
55
+ # tool this script needs to read the cache
49
56
  # (git, node, mktemp, cat) could not be started, mktemp could not create its
50
57
  # temp file, git did not run to an answer, node died mid-read, or node exited
51
58
  # non-zero with no reason and a status other than 2, its only verdict on the
@@ -116,7 +123,7 @@ derive="run the Recipe derivation step (run-team phase 0, before the first claim
116
123
  # the checkout still lists the old layout until someone updates it. Without
117
124
  # `--at` the probe reads <repo>'s own index, as for a caller that runs the
118
125
  # command in <repo> itself. Three arguments is neither shape: a refusal.
119
- usage="usage: derive-testcmd.sh <repo> <install|test> [--at <rev>]"
126
+ usage="usage: derive-testcmd.sh <repo> <install|test|uncovered> [--at <rev>]"
120
127
  rev=
121
128
  case $# in
122
129
  2) ;;
@@ -139,8 +146,8 @@ gitout=$(git -C "$repo" rev-parse --git-dir 2>&1) || {
139
146
  }
140
147
 
141
148
  case $field in
142
- install|test) ;;
143
- *) die "unknown Recipe field '$field' — expected install or test" ;;
149
+ install|test|uncovered) ;;
150
+ *) die "unknown Recipe field '$field' — expected install, test or uncovered" ;;
144
151
  esac
145
152
 
146
153
  # A <rev> is only ever consulted by the probe, which only the Test entrypoint
@@ -223,7 +230,13 @@ if (r.installClean !== true) bad("`installClean` is not true — the Install ste
223
230
  const counted = Number.isInteger(r.testCount) && r.testCount > 0;
224
231
  const mutated = typeof r.mutation === "string" && r.mutation.trim() !== "";
225
232
  if (!counted && !mutated) bad("it carries no proof of real tests — neither a positive `testCount` nor a `mutation`");
226
- const value = r[field];
233
+ if (!Array.isArray(r.uncovered)) bad("`uncovered` is not a list of { step, reason } entries — the CI test steps the Test entrypoint leaves out, `[]` for none");
234
+ const filled = (s) => typeof s === "string" && s.trim() !== "";
235
+ r.uncovered.forEach((u, i) => {
236
+ if (u === null || typeof u !== "object" || Array.isArray(u) || !filled(u.step) || !filled(u.reason))
237
+ bad(`\`uncovered\` entry ${i + 1} is not an object with a non-empty \`step\` and \`reason\``);
238
+ });
239
+ const value = field === "uncovered" ? JSON.stringify(r.uncovered) : r[field];
227
240
  fs.writeFileSync(lenFile, String(Buffer.byteLength(open + value + close)));
228
241
  process.stdout.write(open + value + close);
229
242
  ' "$cache" "$field" "$open" "$close" "$lenf" 2>"$errf") || rc=$?
@@ -292,6 +305,14 @@ esac
292
305
  value=${framed#"$open"}
293
306
  value=${value%"$close"}
294
307
 
308
+ # `uncovered` is data, not a command: nothing runs it and nothing appends to
309
+ # it, so none of the command checks below apply. JSON.stringify above made it
310
+ # one line.
311
+ if [ "$field" = uncovered ]; then
312
+ printf '%s\n' "$value"
313
+ exit 0
314
+ fi
315
+
295
316
  # claim-ticket.sh appends the runner's own arguments after this string
296
317
  # textually (`exec sh -c '<cmd> "$@"' agent-test "$@"`), so a command ending in
297
318
  # `;`, `&`, or a newline lets a real shell read the caller's "$@" as an
@@ -5,10 +5,17 @@
5
5
  // reads: the deriving agent chooses both commands by reading the repository,
6
6
  // and this script is what turns that choice into a cache, or refuses to.
7
7
  //
8
- // recipe-prove.mjs <repo> --install <cmd> --test <cmd>
8
+ // recipe-prove.mjs <repo> --install <cmd> --test <cmd> --uncovered <json>
9
9
  // [--count-line <literal> --test-count <n>]
10
10
  // [--mutate <cmd> --mutation <description>]
11
11
  //
12
+ // `--uncovered` is one JSON array, `[]` when the Test entrypoint runs every
13
+ // test step of the merge-gating CI jobs, and otherwise one
14
+ // `{ "step": <string>, "reason": <string> }` per step it leaves out, both
15
+ // non-empty. It is not proven — nothing here can run CI — but required, so a
16
+ // cache never stays silent about a step the Test entrypoint skips; it is
17
+ // written as given, as the cache's `uncovered`.
18
+ //
12
19
  // Every check runs in a throwaway worktree of `origin/main`, detached and
13
20
  // removed afterwards, so neither the caller's checkout nor its uncommitted
14
21
  // state takes part — `derivedAt` is the commit the proof ran against:
@@ -48,7 +55,8 @@
48
55
  // On proof, the cache is written atomically to <workspace>/.fleet/recipe.json
49
56
  // — <workspace> being the directory holding the repository's common git dir,
50
57
  // the place derive-testcmd.sh reads it from — and then read back through
51
- // derive-testcmd.sh for both fields, the Test entrypoint against `derivedAt`'s
58
+ // derive-testcmd.sh for every field, `uncovered` byte for byte as the compact
59
+ // JSON of the list given, the Test entrypoint against `derivedAt`'s
52
60
  // tree (`--at`): the tree the proof ran in, and the one a claim probes, so a
53
61
  // main checkout still on an older layout cannot refuse a Recipe that holds
54
62
  // where it runs. A cache the reader refuses is rolled
@@ -84,7 +92,7 @@ import { isDigits } from "./arg.mjs";
84
92
 
85
93
  const NAME = "recipe-prove";
86
94
  const USAGE =
87
- "usage: recipe-prove.mjs <repo> --install <cmd> --test <cmd> [--count-line <literal> --test-count <n>] [--mutate <cmd> --mutation <description>]";
95
+ "usage: recipe-prove.mjs <repo> --install <cmd> --test <cmd> --uncovered <json> [--count-line <literal> --test-count <n>] [--mutate <cmd> --mutation <description>]";
88
96
  const READER = join(dirname(fileURLToPath(import.meta.url)), "derive-testcmd.sh");
89
97
 
90
98
  // Scrubbed once, for every child: an ambient GIT_DIR or GIT_WORK_TREE — set
@@ -132,7 +140,7 @@ const READER_COULD_NOT_RUN = 3;
132
140
  function parseArgs(argv) {
133
141
  const [repo, ...rest] = argv;
134
142
  if (!repo || repo.startsWith("--")) throw cannot(USAGE);
135
- const flags = new Set(["--install", "--test", "--count-line", "--test-count", "--mutate", "--mutation"]);
143
+ const flags = new Set(["--install", "--test", "--uncovered", "--count-line", "--test-count", "--mutate", "--mutation"]);
136
144
  const a = {};
137
145
  for (let i = 0; i < rest.length; i += 2) {
138
146
  const [flag, value] = [rest[i], rest[i + 1]];
@@ -145,6 +153,8 @@ function parseArgs(argv) {
145
153
  for (const f of ["--install", "--test"]) {
146
154
  if (!a[f] || !a[f].trim()) throw cannot(`${f} needs a non-empty command — ${USAGE}`);
147
155
  }
156
+ if (!("--uncovered" in a)) throw cannot(`--uncovered is required: the CI test steps the Test entrypoint leaves out, as one JSON array, \`[]\` for none — ${USAGE}`);
157
+ const uncovered = parseUncovered(a["--uncovered"]);
148
158
  if (("--count-line" in a) !== ("--test-count" in a)) throw cannot("--count-line and --test-count go together");
149
159
  if ("--test-count" in a && !isDigits(a["--test-count"])) {
150
160
  throw cannot(`--test-count must be a whole number, got '${a["--test-count"]}'`);
@@ -163,9 +173,30 @@ function parseArgs(argv) {
163
173
  testCount: a["--test-count"],
164
174
  mutate: a["--mutate"],
165
175
  mutation: a["--mutation"],
176
+ uncovered,
166
177
  };
167
178
  }
168
179
 
180
+ // The same rule derive-testcmd.sh holds the cache to, applied before any
181
+ // command runs, so a malformed list is a usage error rather than a proof that
182
+ // held and a cache the reader then refuses.
183
+ function parseUncovered(json) {
184
+ let list;
185
+ try {
186
+ list = JSON.parse(json);
187
+ } catch (e) {
188
+ throw cannot(`--uncovered is not JSON: ${e.message}`);
189
+ }
190
+ if (!Array.isArray(list)) throw cannot("--uncovered is not a JSON array of { step, reason } entries, `[]` for none");
191
+ const filled = (s) => typeof s === "string" && s.trim() !== "";
192
+ list.forEach((u, i) => {
193
+ if (u === null || typeof u !== "object" || Array.isArray(u) || !filled(u.step) || !filled(u.reason)) {
194
+ throw cannot(`--uncovered entry ${i + 1} is not an object with a non-empty \`step\` and \`reason\``);
195
+ }
196
+ });
197
+ return list;
198
+ }
199
+
169
200
  // A git that cannot be started is no verdict, as for `sh` below: read as a
170
201
  // failed git command, it would surface as whatever that command's failure
171
202
  // means to its caller — a missing repository, an unfetched origin/main, a
@@ -343,9 +374,11 @@ function writeCache(cache, recipe, repo) {
343
374
  rmSync(tmp, { force: true });
344
375
  throw e;
345
376
  }
346
- for (const field of ["install", "test"]) {
377
+ for (const field of ["install", "test", "uncovered"]) {
347
378
  const r = spawnSync("sh", [READER, repo, field, ...(field === "test" ? ["--at", recipe.derivedAt] : [])], { env: ENV, encoding: "utf8" });
348
- if (r.status === 0 && r.stdout.replace(/\n$/, "") === recipe[field]) continue;
379
+ const expected = field === "uncovered" ? JSON.stringify(recipe.uncovered) : recipe[field];
380
+ const got = r.status === 0 ? r.stdout.replace(/\n$/, "") : null;
381
+ if (got === expected) continue;
349
382
  if (prior === null) unlinkSync(cache);
350
383
  else writeFileSync(cache, prior);
351
384
  if (r.error && !r.pid) throw cannot(`could not start sh to read the Recipe cache back: ${r.error.message}`);
@@ -366,6 +399,9 @@ function writeCache(cache, recipe, repo) {
366
399
  const stderrNote = probe.err ? `: ${probe.err}` : " and wrote nothing to stderr";
367
400
  throw noVerdict(`git started but does not run: \`git --version\` ${exit}${stderrNote}`);
368
401
  }
402
+ if (got !== null) {
403
+ throw notProven(`the Recipe cache reader reads \`${field}\` back as ${JSON.stringify(got)}, not the ${JSON.stringify(expected)} written`);
404
+ }
369
405
  const said = r.stderr.trim() || r.stdout.trim();
370
406
  throw notProven(`the Recipe cache reader refuses what was proven: ${said || `it wrote nothing and exited with status ${r.status}`}`);
371
407
  }
@@ -437,7 +473,7 @@ function main(argv) {
437
473
  removeWorktree(wt, o.repo);
438
474
  }
439
475
 
440
- recipe = { install: o.install, test: o.test, derivedAt: sha.out, installClean: true, ...proof };
476
+ recipe = { install: o.install, test: o.test, derivedAt: sha.out, installClean: true, ...proof, uncovered: o.uncovered };
441
477
  writeCache(cache, recipe, o.repo);
442
478
  } catch (e) {
443
479
  if (!(e instanceof Refusal && e.message.includes(logs))) removeLogs(logs);
@@ -122,6 +122,12 @@ export const SNAPSHOT_SCHEMA = {
122
122
  prHead: { type: "string" },
123
123
  testCmd: { type: "string" },
124
124
  testCmdError: { type: "string" },
125
+ // The Recipe's `uncovered` as derive-testcmd.sh printed it: the CI test
126
+ // steps the Test entrypoint leaves out, one line of JSON, `[]` for none.
127
+ // `uncoveredError` carries the reader's refusal instead when it could not
128
+ // be read, so an unread list never reads as an empty one.
129
+ uncovered: { type: "string" },
130
+ uncoveredError: { type: "string" },
125
131
  // The Recipe's Install step as the snapshot agent read it, and its exit
126
132
  // status in the snapshot. Optional, so an absent `installExit` is read
127
133
  // as an install that did not succeed, never as one that did:
@@ -499,9 +505,36 @@ export function environmentNote(snap) {
499
505
  note += `\nAfter the Install step the snapshot's status could not be read (${snap.statusError.trim()}), so what it left untracked is not known.`;
500
506
  if (shown.length)
501
507
  note += `\nAfter the Install step the snapshot reads untracked under the repository's own ignore rules: ${shown.join(", ")}${more > 0 ? `, and ${more} more (the whole status is in ${snap.runRoot ?? "the run root"}/status.txt)` : ""}.`;
508
+ note += uncoveredNote(snap);
502
509
  return note;
503
510
  }
504
511
 
512
+ // The CI test steps the Recipe's Test entrypoint leaves out, as the snapshot
513
+ // agent read them through the cache's one reader, ride on the end as one line
514
+ // naming each step and why: a green run here says nothing about them, and no
515
+ // specialist runs them. An empty list adds nothing. A list the agent could
516
+ // not read, or reported in another shape, is said so — never left to read as
517
+ // an empty one.
518
+ const oneLine = (s) => s.replace(/\s+/g, " ").trim();
519
+ function uncoveredNote(snap) {
520
+ let list = null;
521
+ if (snap && typeof snap.uncovered === "string") {
522
+ try {
523
+ list = JSON.parse(snap.uncovered);
524
+ } catch {
525
+ list = null;
526
+ }
527
+ }
528
+ if (Array.isArray(list) && list.every((u) => u && typeof u.step === "string" && typeof u.reason === "string")) {
529
+ if (!list.length) return "";
530
+ return `\nThe Recipe's Test entrypoint does not run these merge-gating CI test steps, and nothing in this review ran them: ${list.map((u) => `${oneLine(u.step)} (${oneLine(u.reason)})`).join("; ")}.`;
531
+ }
532
+ const why =
533
+ (snap && typeof snap.uncoveredError === "string" && snap.uncoveredError.trim() && oneLine(snap.uncoveredError)) ||
534
+ (snap && typeof snap.uncovered === "string" ? `it reported ${JSON.stringify(oneLine(snap.uncovered))}, not a list of steps` : "the snapshot agent reported nothing for it");
535
+ return `\nWhich merge-gating CI test steps the Recipe's Test entrypoint leaves out could not be read (${why}), so a passing run here is not known to cover them.`;
536
+ }
537
+
505
538
  function repoNote(snap) {
506
539
  if (snap && snap.repoVerified === true)
507
540
  return `Test environment: the snapshot is a git repository whose single commit holds
@@ -1085,6 +1118,15 @@ guess a command yourself: a refusal about the cache names the step that
1085
1118
  derives it; an exit-3 refusal names an environment fault, and the caller fixes
1086
1119
  that instead of deriving.
1087
1120
 
1121
+ Then read, out of the same cache, the merge-gating CI test steps that Test
1122
+ entrypoint leaves out:
1123
+
1124
+ ~/.fleet/bin/fleet-run derive-testcmd.sh ${worktree} uncovered
1125
+
1126
+ Report \`uncovered\` = its stdout, one line of JSON copied verbatim, ONLY if it
1127
+ exited 0. If it exited non-zero, report \`uncoveredError\` = its stderr and omit
1128
+ \`uncovered\`. Run none of the steps it lists.
1129
+
1088
1130
  Then size the diff:
1089
1131
 
1090
1132
  ~/.fleet/bin/fleet-run diff-stats.mjs --pr ${pr}
@@ -1100,7 +1142,8 @@ specialists into another run's tree. Report the HEAD sha, and — in
1100
1142
  STDOUT, copied verbatim. Only runRoot, path, head, pathVerified and repoVerified
1101
1143
  are ever required — diffStats, diffPath, diffLines, refHead and prHead are each
1102
1144
  omitted independently when their command failed, repoError only accompanies
1103
- a false repoVerified, and installError only replaces installCmd and installExit.`,
1145
+ a false repoVerified, installError only replaces installCmd and installExit,
1146
+ and uncoveredError only replaces uncovered.`,
1104
1147
  { label: `snapshot${forPr}`, phase: "Snapshot", agentType: SNAPSHOT_AGENT_TYPE, schema: SNAPSHOT_SCHEMA },
1105
1148
  );
1106
1149