@feigi/fleet-ctl 3.24.7 → 3.24.9

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.
Files changed (35) hide show
  1. package/agents/fleet-implementer-slow-high.agent.md +2 -2
  2. package/agents/fleet-implementer-slow-medium.agent.md +2 -2
  3. package/agents/fleet-implementer-smol-high.agent.md +2 -2
  4. package/agents/fleet-implementer-task-high.agent.md +2 -2
  5. package/agents/fleet-implementer-task-max.agent.md +2 -2
  6. package/agents/fleet-review-comments.agent.md +1 -1
  7. package/agents/fleet-review-correctness.agent.md +1 -1
  8. package/agents/fleet-review-runner.agent.md +2 -2
  9. package/agents/fleet-review-silent-failure.agent.md +1 -1
  10. package/agents/fleet-review-simplify.agent.md +1 -1
  11. package/agents/fleet-review-snapshot.agent.md +1 -2
  12. package/agents/fleet-review-test-run.agent.md +2 -3
  13. package/agents/fleet-review-tests.agent.md +2 -2
  14. package/agents/fleet-review-types.agent.md +1 -1
  15. package/agents/fleet-review-verifier.agent.md +1 -1
  16. package/commands/review-and-fix.md +9 -9
  17. package/commands/run-merge-bot.md +14 -14
  18. package/commands/run-team-help.md +1 -1
  19. package/package.json +1 -1
  20. package/scripts/ci-state.mjs +25 -26
  21. package/scripts/compute-spend.mjs +22 -22
  22. package/scripts/diff-stats.mjs +12 -12
  23. package/scripts/fleet-heartbeat.mjs +9 -9
  24. package/scripts/fleet-state.mjs +15 -15
  25. package/scripts/fleet-tick.mjs +63 -63
  26. package/scripts/frontmatter-check.mjs +10 -11
  27. package/scripts/ledger-grammar.mjs +12 -13
  28. package/scripts/member-outcomes.mjs +8 -9
  29. package/scripts/merge-gate.mjs +2 -4
  30. package/scripts/pr-overlap.mjs +31 -30
  31. package/scripts/shortlist.mjs +6 -8
  32. package/scripts/staleness.mjs +21 -21
  33. package/scripts/tier-check.mjs +14 -14
  34. package/scripts/tier-roles.mjs +12 -12
  35. package/skills/next-ticket/SKILL.md +5 -5
@@ -129,7 +129,7 @@ you are alive while you wait on it.
129
129
 
130
130
  **The `eval` kernel is shared with every sibling member and with the
131
131
  controller that dispatched you — namespace every binding you make in it, and
132
- never hand it a relative path.** Measured on #1447, live, three ways in one
132
+ never hand it a relative path.** Measured live, three ways in one
133
133
  run: two sibling implementers dispatched in the same batch, and the
134
134
  controller above them, reported the SAME Python kernel pid and the same
135
135
  runner file, and each could read the others' top-level variables — a bare
@@ -188,7 +188,7 @@ wrong.** Moving, reordering or wrapping a statement has effects the ticket
188
188
  never mentions — the last command of a script sets its exit status, a
189
189
  relocated line changes what `set -e` covers, a hoisted guard changes what runs
190
190
  first. **Ask which of the ticket's own acceptance criteria your restructuring
191
- could newly violate, and test that path.** Measured: #265 required "no path in
191
+ could newly violate, and test that path.** Measured: a ticket required "no path in
192
192
  the script exits 1", and the fix for it moved a guard to the file's end,
193
193
  regressing the default dry run from exit 0 to exit 1 — the ticket's exact
194
194
  defect, relocated onto the path nobody tested. The implementer had enumerated
@@ -129,7 +129,7 @@ you are alive while you wait on it.
129
129
 
130
130
  **The `eval` kernel is shared with every sibling member and with the
131
131
  controller that dispatched you — namespace every binding you make in it, and
132
- never hand it a relative path.** Measured on #1447, live, three ways in one
132
+ never hand it a relative path.** Measured live, three ways in one
133
133
  run: two sibling implementers dispatched in the same batch, and the
134
134
  controller above them, reported the SAME Python kernel pid and the same
135
135
  runner file, and each could read the others' top-level variables — a bare
@@ -188,7 +188,7 @@ wrong.** Moving, reordering or wrapping a statement has effects the ticket
188
188
  never mentions — the last command of a script sets its exit status, a
189
189
  relocated line changes what `set -e` covers, a hoisted guard changes what runs
190
190
  first. **Ask which of the ticket's own acceptance criteria your restructuring
191
- could newly violate, and test that path.** Measured: #265 required "no path in
191
+ could newly violate, and test that path.** Measured: a ticket required "no path in
192
192
  the script exits 1", and the fix for it moved a guard to the file's end,
193
193
  regressing the default dry run from exit 0 to exit 1 — the ticket's exact
194
194
  defect, relocated onto the path nobody tested. The implementer had enumerated
@@ -129,7 +129,7 @@ you are alive while you wait on it.
129
129
 
130
130
  **The `eval` kernel is shared with every sibling member and with the
131
131
  controller that dispatched you — namespace every binding you make in it, and
132
- never hand it a relative path.** Measured on #1447, live, three ways in one
132
+ never hand it a relative path.** Measured live, three ways in one
133
133
  run: two sibling implementers dispatched in the same batch, and the
134
134
  controller above them, reported the SAME Python kernel pid and the same
135
135
  runner file, and each could read the others' top-level variables — a bare
@@ -188,7 +188,7 @@ wrong.** Moving, reordering or wrapping a statement has effects the ticket
188
188
  never mentions — the last command of a script sets its exit status, a
189
189
  relocated line changes what `set -e` covers, a hoisted guard changes what runs
190
190
  first. **Ask which of the ticket's own acceptance criteria your restructuring
191
- could newly violate, and test that path.** Measured: #265 required "no path in
191
+ could newly violate, and test that path.** Measured: a ticket required "no path in
192
192
  the script exits 1", and the fix for it moved a guard to the file's end,
193
193
  regressing the default dry run from exit 0 to exit 1 — the ticket's exact
194
194
  defect, relocated onto the path nobody tested. The implementer had enumerated
@@ -129,7 +129,7 @@ you are alive while you wait on it.
129
129
 
130
130
  **The `eval` kernel is shared with every sibling member and with the
131
131
  controller that dispatched you — namespace every binding you make in it, and
132
- never hand it a relative path.** Measured on #1447, live, three ways in one
132
+ never hand it a relative path.** Measured live, three ways in one
133
133
  run: two sibling implementers dispatched in the same batch, and the
134
134
  controller above them, reported the SAME Python kernel pid and the same
135
135
  runner file, and each could read the others' top-level variables — a bare
@@ -188,7 +188,7 @@ wrong.** Moving, reordering or wrapping a statement has effects the ticket
188
188
  never mentions — the last command of a script sets its exit status, a
189
189
  relocated line changes what `set -e` covers, a hoisted guard changes what runs
190
190
  first. **Ask which of the ticket's own acceptance criteria your restructuring
191
- could newly violate, and test that path.** Measured: #265 required "no path in
191
+ could newly violate, and test that path.** Measured: a ticket required "no path in
192
192
  the script exits 1", and the fix for it moved a guard to the file's end,
193
193
  regressing the default dry run from exit 0 to exit 1 — the ticket's exact
194
194
  defect, relocated onto the path nobody tested. The implementer had enumerated
@@ -129,7 +129,7 @@ you are alive while you wait on it.
129
129
 
130
130
  **The `eval` kernel is shared with every sibling member and with the
131
131
  controller that dispatched you — namespace every binding you make in it, and
132
- never hand it a relative path.** Measured on #1447, live, three ways in one
132
+ never hand it a relative path.** Measured live, three ways in one
133
133
  run: two sibling implementers dispatched in the same batch, and the
134
134
  controller above them, reported the SAME Python kernel pid and the same
135
135
  runner file, and each could read the others' top-level variables — a bare
@@ -188,7 +188,7 @@ wrong.** Moving, reordering or wrapping a statement has effects the ticket
188
188
  never mentions — the last command of a script sets its exit status, a
189
189
  relocated line changes what `set -e` covers, a hoisted guard changes what runs
190
190
  first. **Ask which of the ticket's own acceptance criteria your restructuring
191
- could newly violate, and test that path.** Measured: #265 required "no path in
191
+ could newly violate, and test that path.** Measured: a ticket required "no path in
192
192
  the script exits 1", and the fix for it moved a guard to the file's end,
193
193
  regressing the default dry run from exit 0 to exit 1 — the ticket's exact
194
194
  defect, relocated onto the path nobody tested. The implementer had enumerated
@@ -7,7 +7,7 @@ model: "@task:medium"
7
7
  <!-- Prompt adapted from Anthropic's vendored `comment-analyzer`
8
8
  agent
9
9
  (marketplace plugin `pr-review-toolkit`, agent file `comment-analyzer.md`),
10
- which this definition replaces (#1349, per #1303's ruling on #1296/#1303).
10
+ which this definition replaces.
11
11
  Its `model:` is the `@task:medium` route, which resolves through the
12
12
  operator's `modelRoles`. The pre-cutover review host's PREVIOUS per-call
13
13
  override for this dimension was `sonnet` (the vendor's own frontmatter
@@ -6,7 +6,7 @@ model: "@slow:high"
6
6
 
7
7
  <!-- Prompt adapted from Anthropic's vendored `code-reviewer` agent
8
8
  (marketplace plugin `pr-review-toolkit`, agent file `code-reviewer.md`),
9
- which this definition replaces (#1349, per #1303's ruling on #1296/#1303).
9
+ which this definition replaces.
10
10
  Its `model:` is the `@slow:high` route, which resolves through the
11
11
  operator's `modelRoles`; that agent's own frontmatter pinned `opus`. Adapted, not
12
12
  copied verbatim: the vendor's freeform "Output Format"/confidence-score
@@ -26,8 +26,8 @@ This agent's `spawns:` frontmatter above names the 9 agent types
26
26
  the 6 specialist dimensions, `fleet-review-verifier`) — an allowlist, not
27
27
  `"*"`, so a future dimension added to `review-core.mjs` without a matching
28
28
  update here fails loud (`Cannot spawn '<name>'. Allowed: ...`) instead of
29
- silently. Before #2102 this field was missing entirely and `tools` was never
30
- set either, so
29
+ silently. Before this field existed, with `tools` never
30
+ set either,
31
31
  the backward-compat `spawns` default (`omp://task-agent-discovery.md:38-39`
32
32
  — missing `spawns` defaults to `*` only when `tools` includes `task`) never
33
33
  fired: every spawn from this agent's cell was refused, 110+ times in one
@@ -7,7 +7,7 @@ model: "@task:high"
7
7
  <!-- Prompt adapted from Anthropic's vendored `silent-failure-hunter`
8
8
  agent
9
9
  (marketplace plugin `pr-review-toolkit`, agent file `silent-failure-hunter.md`),
10
- which this definition replaces (#1349, per #1303's ruling on #1296/#1303).
10
+ which this definition replaces.
11
11
  The vendor's frontmatter was `model: inherit` with no per-call override
12
12
  either, so it ran at whatever the session inherited — a value this port
13
13
  cannot reproduce (there is no "session model" a named definition can
@@ -7,7 +7,7 @@ model: "@slow:high"
7
7
  <!-- Prompt adapted from Anthropic's vendored `code-simplifier`
8
8
  agent
9
9
  (marketplace plugin `pr-review-toolkit`, agent file `code-simplifier.md`),
10
- which this definition replaces (#1349, per #1303's ruling on #1296/#1303).
10
+ which this definition replaces.
11
11
  Its `model:` is the `@slow:high` route, which resolves through the
12
12
  operator's `modelRoles`; that agent's own frontmatter pinned `opus`. Unlike the
13
13
  vendor original (which edits code directly), this dispatch is
@@ -7,8 +7,7 @@ model: "@smol:low"
7
7
  Not adapted from a vendored definition — this dispatch has no upstream
8
8
  counterpart. It exists to give the snapshot step in `review-core.mjs` a named,
9
9
  tier-controlled identity instead of falling through
10
- to a session default; #1349 (per #1303's gap 3) forbids sending `model` on
11
- the `agent()` call itself.
10
+ to a session default; the `agent()` call itself may not carry `model`.
12
11
 
13
12
  `model: "@smol:low"`, which resolves through the operator's `modelRoles`, replaces
14
13
  the pre-cutover review host's previous `A.snapshotModel` default of `haiku` —
@@ -7,10 +7,9 @@ model: "@smol:low"
7
7
  Not adapted from a vendored definition — this dispatch has no upstream
8
8
  counterpart. It exists to give the shared test run in `review-core.mjs` a
9
9
  named, tier-controlled identity instead of falling through to a session
10
- default; #1349 (per #1303's gap 3) forbids sending `model` on the `agent()`
11
- call itself.
10
+ default; the `agent()` call itself may not carry `model`.
12
11
 
13
- It replaced one full-suite run per review dimension (#2315): every specialist
12
+ It replaced one full-suite run per review dimension: every specialist
14
13
  used to run the test command itself, so one review ran the suite up to six
15
14
  times on the same immutable snapshot. Now this dispatch runs it once and every
16
15
  specialist reads its counts and log.
@@ -7,14 +7,14 @@ model: "@task:medium"
7
7
  <!-- Prompt adapted from Anthropic's vendored `pr-test-analyzer`
8
8
  agent
9
9
  (marketplace plugin `pr-review-toolkit`, agent file `pr-test-analyzer.md`),
10
- which this definition replaces (#1349, per #1303's ruling on #1296/#1303).
10
+ which this definition replaces.
11
11
  Its `model:` is the `@task:medium` route, which resolves through the
12
12
  operator's `modelRoles`. The pre-cutover review host's PREVIOUS per-call
13
13
  override for this dimension was `sonnet` (the vendor's own frontmatter
14
14
  was `model: inherit` with no pin to preserve) — the "recoverable miss"
15
15
  downgrade argued in the DEFAULT_DIMENSIONS comment of the pre-cutover
16
16
  `plugin/workflows/review-pr.js` (as of a08fe810^): a weak `tests` pass
17
- leaves something a later run or a reader still catches. #1349's port
17
+ leaves something a later run or a reader still catches. The port
18
18
  (a08fe810) cut it from that comment; review-core.mjs's SIZE_TIER_DIMS comment
19
19
  keeps the other half, naming the dimensions that miss silently and
20
20
  permanently. -->
@@ -7,7 +7,7 @@ model: "@task:medium"
7
7
  <!-- Prompt adapted from Anthropic's vendored `type-design-analyzer`
8
8
  agent
9
9
  (marketplace plugin `pr-review-toolkit`, agent file `type-design-analyzer.md`),
10
- which this definition replaces (#1349, per #1303's ruling on #1296/#1303).
10
+ which this definition replaces.
11
11
  Its `model:` is the `@task:medium` route, which resolves through the
12
12
  operator's `modelRoles`. The pre-cutover review host's PREVIOUS per-call
13
13
  override for this dimension was `sonnet` (the vendor's own frontmatter
@@ -7,7 +7,7 @@ model: "@task:low"
7
7
  Not adapted from a vendored definition — this dispatch has no upstream
8
8
  counterpart. It exists to give the adversarial refute pass a named,
9
9
  tier-controlled identity instead of the pre-cutover review host's previous per-call
10
- `effort: verifierEffort` option, which #1349 (per #1303's gap 3) forbids: no
10
+ `effort: verifierEffort` option, which is forbidden: no
11
11
  `agent()` call may carry `effort` (or `model`) directly, tier lives here in
12
12
  this definition's own frontmatter.
13
13
 
@@ -12,8 +12,8 @@ argument-hint: [pr-number]
12
12
  **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.
13
13
  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.
14
14
  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.
15
- 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.
16
- 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.
15
+ 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** — 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 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 under the confirmed/torn split, which is 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 (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.
16
+ 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, 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.
17
17
 
18
18
  **`verdict: "no-ci"` — this repo has no `check` job to gate on at all**, and that is a different state from red or unknown, not a third way to skip the wait. Label off step 3's own green `testCmd` run instead of a `check` job that will never exist — and only once `ci-state.mjs` reads `no-ci` **without** the flag, since a repo whose CI is merely misconfigured exits 2 there rather than reading no-ci. `--declare-no-ci` is your caller-side declaration that step 3's run **is** this repo's gate: it flips the exit code and echoes itself into `reasons`, so finding it in the payload confirms only that you passed it, never that anyone verified anything. **No green `testCmd` run on record → do not label.** Say in your verdict that the repo has no CI configured and no declaration, and stop — inferring a pass from silence here is exactly the misconfigured-CI case the declaration exists to rule out. See `ci-state.mjs --pr <n> --declare-no-ci` below.
19
19
 
@@ -53,15 +53,15 @@ jq '.refuted' "$R" # refuted: your
53
53
 
54
54
  **Every finding in the file is yours to rule on, not the ones that read sharpest.** The file is the only complete copy a member can reach — the specialists' transcripts exist, but nothing you hold addresses one — so a finding you never read is one nobody rules on. `counts` is the check that you read them all: your apply/defer split covers every `survived` and `unverified` finding it counts, and your disposition record (step 2) carries an entry for each `refuted` one you reversed, with the evidence in its `reason`, which the controller copies to the ledger's `ruled` line.
55
55
 
56
- **Read `testEnvironment` and `cwdAudit` before you act on any result of the shared test run.** `testEnvironment` says whether the snapshot the specialists ran in was verified as the reviewed tree: verified, a red there is a fact about the tree; UNVERIFIED, tests that ask git what ships decline or fail for the environment, so a red or a short count there is not a finding until you reproduce it in the worktree, and not a reason to rule a dimension unrun either. `cwdAudit` is each specialist's audit of the checkout it inherited, `{dimension, state, line}`: `dirty` and `missing` are equally loud, because either names a checkout a specialist may have written to (#1433, #1673). Check it with `git -C <that path> status --porcelain -uall` — the path is in a `dirty` entry's `line`, and a `missing` entry's is the main checkout, the parent of `git rev-parse --path-format=absolute --git-common-dir` — and report what it printed; never revert content you did not write. A `dimensionsUnrun` entry is a dimension that did not cover its ground, its `reason` naming which failure: name it unrun in your report, because an absence of findings is not coverage, and re-run nothing — the review already re-dispatched every crashed specialist once, in-run.
56
+ **Read `testEnvironment` and `cwdAudit` before you act on any result of the shared test run.** `testEnvironment` says whether the snapshot the specialists ran in was verified as the reviewed tree: verified, a red there is a fact about the tree; UNVERIFIED, tests that ask git what ships decline or fail for the environment, so a red or a short count there is not a finding until you reproduce it in the worktree, and not a reason to rule a dimension unrun either. `cwdAudit` is each specialist's audit of the checkout it inherited, `{dimension, state, line}`: `dirty` and `missing` are equally loud, because either names a checkout a specialist may have written to. Check it with `git -C <that path> status --porcelain -uall` — the path is in a `dirty` entry's `line`, and a `missing` entry's is the main checkout, the parent of `git rev-parse --path-format=absolute --git-common-dir` — and report what it printed; never revert content you did not write. A `dimensionsUnrun` entry is a dimension that did not cover its ground, its `reason` naming which failure: name it unrun in your report, because an absence of findings is not coverage, and re-run nothing — the review already re-dispatched every crashed specialist once, in-run.
57
57
 
58
- **Scan the findings against each other for MUTUAL EXCLUSION, and rule before the conflicting change reaches the tree.** Refuters are blind to their siblings, so two can approve changes that cannot both land — one preserving a comment block another's change deletes, one keeping a binding another collapses. Two runs produced it: PR #332, and PR #404, where a refuter proved a variable collapse behavior-equivalent over 844 cases while its own blast-radius scan named the two comment blocks a *different* refuter had just established as guarding distinct pinned hazards. You hold every finding, so only you can see the pair — and the scan's two inputs arrive at different times, so run it twice. **Before you apply anything**, group the findings by `file:line` and by whether one's fix undoes another's; that is in the findings' own text. **Then as each refuter you dispatch reports**, read its blast radius against what you have already ruled on. **A conflicting pair goes to a SINGLE refuter, briefed with both claims** — that is what settled #332's, one refuter ruling *"B wins: A's premise is false"* where two independent refuters would each have approved their own side. Defer only when no single refuter can settle it, with the equivalence evidence recorded in the filed issue so the work is not redone. Never let both reach the tree and hope the diff coheres.
58
+ **Scan the findings against each other for MUTUAL EXCLUSION, and rule before the conflicting change reaches the tree.** Refuters are blind to their siblings, so two can approve changes that cannot both land — one preserving a comment block another's change deletes, one keeping a binding another collapses. Two runs produced it; in one, a refuter proved a variable collapse behavior-equivalent over 844 cases while its own blast-radius scan named the two comment blocks a *different* refuter had just established as guarding distinct pinned hazards. You hold every finding, so only you can see the pair — and the scan's two inputs arrive at different times, so run it twice. **Before you apply anything**, group the findings by `file:line` and by whether one's fix undoes another's; that is in the findings' own text. **Then as each refuter you dispatch reports**, read its blast radius against what you have already ruled on. **A conflicting pair goes to a SINGLE refuter, briefed with both claims** — that is what settled one such pair, one refuter ruling *"B wins: A's premise is false"* where two independent refuters would each have approved their own side. Defer only when no single refuter can settle it, with the equivalence evidence recorded in the filed issue so the work is not redone. Never let both reach the tree and hope the diff coheres.
59
59
 
60
- **A finding whose suggested fix quotes text another applied finding deletes goes stale on arrival.** Measured on PR #405: `survived[5]`'s pin was written as `/not inside a git repository/`, wording `survived[3]` removes as fabricated, so applying both as written would have produced a pin matching nothing — no conflict at the diff level, and it passes for the wrong reason. **Re-derive, never copy:** apply the finding that changes the text first, then derive the assertion from the post-fix tree. A `suggested_fix` is a hypothesis the review never ran; only the claim was refuted against.
60
+ **A finding whose suggested fix quotes text another applied finding deletes goes stale on arrival.** Measured once: `survived[5]`'s pin was written as `/not inside a git repository/`, wording `survived[3]` removes as fabricated, so applying both as written would have produced a pin matching nothing — no conflict at the diff level, and it passes for the wrong reason. **Re-derive, never copy:** apply the finding that changes the text first, then derive the assertion from the post-fix tree. A `suggested_fix` is a hypothesis the review never ran; only the claim was refuted against.
61
61
 
62
- **A `refuted=false` verdict is not an instruction to apply.** It says the finding survived refutation, not that the change is worth making — the two come apart exactly when the refuter confirms behavior-equivalence and falsifies the finding's *reason* in the same run. In the #404 case the stated house-style premise was measurably false and the stated cost understated. Behavior-neutral plus a false rationale is a defer, however clean the verdict reads.
62
+ **A `refuted=false` verdict is not an instruction to apply.** It says the finding survived refutation, not that the change is worth making — the two come apart exactly when the refuter confirms behavior-equivalence and falsifies the finding's *reason* in the same run. In the variable-collapse case the stated house-style premise was measurably false and the stated cost understated. Behavior-neutral plus a false rationale is a defer, however clean the verdict reads.
63
63
 
64
- **Extending a finding to sibling sites is a new claim at every added site, and each needs its own measurement.** A verified finding covers the sites its refuters measured. On PR #764 a `survived` 2-0 finding was rightly extended from one site to five, but its prescribed replacement reason was false at one of the five — only a per-site mutation separated them: deleting all five restores at once reddened four, not five. Fix each added site on the reason you measured there, never on a copied one.
64
+ **Extending a finding to sibling sites is a new claim at every added site, and each needs its own measurement.** A verified finding covers the sites its refuters measured. On one PR a `survived` 2-0 finding was rightly extended from one site to five, but its prescribed replacement reason was false at one of the five — only a per-site mutation separated them: deleting all five restores at once reddened four, not five. Fix each added site on the reason you measured there, never on a copied one.
65
65
 
66
66
  ## Specialists
67
67
 
@@ -78,7 +78,7 @@ It cannot ask the user anything and cannot wait on CI — rebasing, watching che
78
78
  - **Cut TWO trees, not one — a shared snapshot is not enough.** Mutation probing is a *write*, so a mutating specialist and read-only specialists cannot share a copy: the readers then observe the mutant exactly as if it were real code. Give them `snap-ro`, pristine and **never written**, and one private copy **per mutating specialist**. Keep every one out of the worktree. Observed with a single shared snapshot: three specialists read two *different* in-flight mutations, one reporting the PR's own bug as still present; elsewhere three watched their file go clean → `M` mid-analysis; twice a reviewer came one step from filing a false finding. Reverting a probe does not help — it leaves a window where every concurrent reader sees a lie, and serializing does not close it because readers are concurrent with the *mutator*.
79
79
  - **Do not trust the obvious contamination check.** `diff -rq` and `md5` against the mutating tree both returned *clean* — because the probe had been reverted between the two reads. A clean diff against a live tree is not evidence in either direction; only `snap-ro` and the object store settle it.
80
80
  - **`git archive` carries tracked files only.** No installed dependencies, no gitignored runner or config. Provision in the same step — run the Install step in the copy (read it off the worktree or main checkout, `derive-testcmd.sh <worktree or main checkout> install`; pointed at the copy it refuses, since a copy holds no Recipe cache) or symlink in what it produced in the worktree, copy in what the runner needs — or specialists silently have no runnable suite and reason from source instead of measuring. That failure is invisible: you get confident prose where you asked for a measurement.
81
- - **Initialize the copy before anyone measures in it — a bare `git archive` tree cannot validly run every suite.** It is not a git repository, so anything that asks git about the checkout breaks: `derive_workspace_id` shells out to `git rev-parse`, falls back to the directory basename and the hook tests fail on the *name* — naming the dir after the repo makes those pass **by coincidence, not correctness** — while every sweep that asks git what ships declines instead of running, which is the silent half (measured on this repo at `ffa9026`: 2401 tests, 2382 pass, 19 skipped in an extraction against 2401/2401/0 in a worktree, the totals identical). `git init && git add -A -f && git commit` in the extracted copy is what makes a count mean what it looks like; the review's snapshot agent does exactly that and verifies it by comparing the new commit's tree hash against the reviewed commit's (#1056), and a hand-cut tree needs the same before you read a count off it. Suites that need the real worktree for some *other* reason — the stack below — still do.
81
+ - **Initialize the copy before anyone measures in it — a bare `git archive` tree cannot validly run every suite.** It is not a git repository, so anything that asks git about the checkout breaks: `derive_workspace_id` shells out to `git rev-parse`, falls back to the directory basename and the hook tests fail on the *name* — naming the dir after the repo makes those pass **by coincidence, not correctness** — while every sweep that asks git what ships declines instead of running, which is the silent half (measured on this repo at `ffa9026`: 2401 tests, 2382 pass, 19 skipped in an extraction against 2401/2401/0 in a worktree, the totals identical). `git init && git add -A -f && git commit` in the extracted copy is what makes a count mean what it looks like; the review's snapshot agent does exactly that and verifies it by comparing the new commit's tree hash against the reviewed commit's, and a hand-cut tree needs the same before you read a count off it. Suites that need the real worktree for some *other* reason — the stack below — still do.
82
82
  - **Give specialists a stack-free test command, not the worktree's runner, and their own scratch dir** — `<scratch>/pr<N>/fleet-review-<key>/`, resolved to an absolute path that you write into that specialist's prompt; a specialist never derives its own. Specialists inherit no environment, and one falling back to the default config runs a `globalSetup` that brings the shared compose stack up and tears it down, recreating the DB mid-run for every sibling. **The snapshot does not cover this** — the compose project name comes from the environment, not the working directory, so three agents on three copies still collide. But `./agent-test` does not fix it either: it exports **one** `TEST_COMPOSE_PROJECT`/port triple per *worktree* (`ab-<issue>`), so N concurrent specialists sharing it tear down each other's postgres mid-run. Observed: a probe returned `No test files found / No such container` and would have read as a test failure. So tell specialists the repo's test command directly — the Test entrypoint, read off the Recipe cache the way step 3 reads it (`derive-testcmd.sh <worktree or main checkout> test` prints it; the snapshot carries no `.fleet/` cache, so pointing it at the snapshot refuses) — when it brings up no shared stack, and the repo's own stack-free config when it does; never name a config the repo does not have, which sends every specialist into a missing-file error that reads as a broken tree rather than a bad instruction. Keep `./agent-test` for your own verification. **Hand that command with its reading rule: `tests 0` is a failed run, not a pass.** A command is not self-checking: a path glob or filter that matches nothing can exit 0 having run nothing. Measured with `node --test` over a glob matching no file: bash passes the pattern through literally, node globs it itself and finds no files, and you get `ℹ tests 0` / exit 0 — and `# tests 0` to a pipe on older node, so a rule that greps only for `ℹ` finds nothing in a CI log and cannot tell a zero-test run from a full one. Do not count on the shell to catch it: zsh errors (`no matches found`, exit 1) and bash does not, so the guard has to be the reading rule. **And zero is not the only no-work count.** **0 passes with no failures** is everything skipped, and a count **materially below the full suite** is a partial copy of the tree — which is the *documented* behavior, since the prompt tells specialists to run their probe work inside their own copy of the snapshot and nothing anchors an expected count for them. `review-core.mjs` classifies the first itself, in `unrunReason`; the second it structurally cannot, because that function is kept pure and so never learns how many tests the tree has. Handing the rule over with the command is the only guard the partial-copy case has. Carry the rule, not the command: wherever a repo has a stack, N concurrent specialists sharing one runner collide, and the escape is whatever that repo's stack-free config is.
83
83
  - **Completion is not delivery — but you can reach a specialist, so never wait idle.** A specialist you dispatched reports when it settles; if a report is missing, `hub send` it by name and ask for the report. Judge delivery by whether a report came out. **Do not settle a dimension you hold no report for**: ask the specialist, then the controller by name; only when neither answers, rule and name that dimension **unrun** — a killed specialist never reports, so waiting on one is unbounded. Never ship "dispatched, never delivered" as settled; a ruling citing a report you do not hold gets verified from source, never applied on trust.
84
84
  - **Apply only once the fan-out is settled — every report either in hand or accounted for.** Collection is not guaranteed; a report that never arrived is an open dimension, not a smaller set. And editing while they read is the same defect as probing — one specialist reviewed uncommitted code that was never in the PR diff.
@@ -87,7 +87,7 @@ Tell readers **`git show <sha>:<path>` is the source of truth** — the object s
87
87
 
88
88
  **Brace a ref held in a variable — `git show "${SHA}:<path>"` — because quoting is not what fixes it.** zsh reads a `:x` suffix after an unbraced parameter as a history modifier, inside double quotes as well as outside, so git is handed a ref nobody typed; braces end the parameter name before the colon. Measured, fully quoted: the construct that fails loudly on one path exits 0 on another and prints the *commit* instead of the blob — and the silent shape is the hazard, because a survival `grep -c` scores it as a plausible hit and re-anchors a citation that was correct. A literal ref is unaffected either way; quote regardless — not for zsh's sake, which splits and globs an expansion's *result* only under `SH_WORD_SPLIT`/`GLOB_SUBST`, both off by default (measured: `V="a b"` unquoted still arrives as one argument), but so the same line survives a `bash` runner, where an unquoted path holding a space does split — measured, `fatal: path 'has' does not exist`.
89
89
 
90
- **The fan-out scales to the diff — the review computes it, you don't.** Its snapshot agent runs `diff-stats.mjs`, and `selectDimensions` keeps the applicable subset of the six-specialist catalog (fleet-review-correctness, fleet-review-silent-failure, fleet-review-tests, fleet-review-comments, fleet-review-types, fleet-review-simplify): fleet-review-correctness always; drop fleet-review-tests with no test changes, and fleet-review-types / fleet-review-silent-failure / fleet-review-simplify with no source; a docs-only PR keeps only fleet-review-correctness + fleet-review-comments. **Then the size tier applies a floor on top:** a `single-file` or `small` profile keeps fleet-review-correctness + fleet-review-silent-failure + fleet-review-comments, plus fleet-review-tests when the diff touches a test file — so a small source PR runs three, not five. **fleet-review-comments is unconditional on the floor** (#218): it used to need a docs *file* in the diff, but `classify()` scores `.js`/`.mjs` `src` via the code-extension check and `.sh` `src` by falling through everything else, so a PR whose whole substance was prose in a `.js`/`.mjs`/`.sh` comment scored `docs: 0` and lost the one specialist whose job it was — measured five times in production, all correction-class PRs, with `dimensionsUnrun` empty each time because the trim was by design. **The floor outranks the no-source drop for fleet-review-silent-failure** (#236): a one-file `.yml` or `.github/` shell change runs fleet-review-correctness + fleet-review-silent-failure, which is the pair a swallowed error in CI needs. Above the size tier the no-source drop still stands, and `tests-only` outranks the size tier for a diff with no config file — a no-src, no-config diff that also touches a test file gets no fleet-review-silent-failure; a tests-only diff that also carries a config file keeps it (#739). `single-file` is one file at *any* size. Profile unknown → the full six, the safe direction. Pin a subset explicitly with `args.dimensions` (keys or dimension objects). Dispatching by hand instead of automatically: apply the same heuristic yourself — two or three for annotation-only or single-file, the full six for production code.
90
+ **The fan-out scales to the diff — the review computes it, you don't.** Its snapshot agent runs `diff-stats.mjs`, and `selectDimensions` keeps the applicable subset of the six-specialist catalog (fleet-review-correctness, fleet-review-silent-failure, fleet-review-tests, fleet-review-comments, fleet-review-types, fleet-review-simplify): fleet-review-correctness always; drop fleet-review-tests with no test changes, and fleet-review-types / fleet-review-silent-failure / fleet-review-simplify with no source; a docs-only PR keeps only fleet-review-correctness + fleet-review-comments. **Then the size tier applies a floor on top:** a `single-file` or `small` profile keeps fleet-review-correctness + fleet-review-silent-failure + fleet-review-comments, plus fleet-review-tests when the diff touches a test file — so a small source PR runs three, not five. **fleet-review-comments is unconditional on the floor**: it used to need a docs *file* in the diff, but `classify()` scores `.js`/`.mjs` `src` via the code-extension check and `.sh` `src` by falling through everything else, so a PR whose whole substance was prose in a `.js`/`.mjs`/`.sh` comment scored `docs: 0` and lost the one specialist whose job it was — measured five times in production, all correction-class PRs, with `dimensionsUnrun` empty each time because the trim was by design. **The floor outranks the no-source drop for fleet-review-silent-failure**: a one-file `.yml` or `.github/` shell change runs fleet-review-correctness + fleet-review-silent-failure, which is the pair a swallowed error in CI needs. Above the size tier the no-source drop still stands, and `tests-only` outranks the size tier for a diff with no config file — a no-src, no-config diff that also touches a test file gets no fleet-review-silent-failure; a tests-only diff that also carries a config file keeps it. `single-file` is one file at *any* size. Profile unknown → the full six, the safe direction. Pin a subset explicitly with `args.dimensions` (keys or dimension objects). Dispatching by hand instead of automatically: apply the same heuristic yourself — two or three for annotation-only or single-file, the full six for production code.
91
91
 
92
92
  **If the ticket is a *correction* — stale docs, wrong comments, bad citations — hunt the defect inside the correction itself.** Four such tickets in one fleet run each shipped a new wrong claim in the fix: a misattributed package, a three-item list at inverted polarity (two items were the *negations* of the claims being marked stale, so the banner asserted currently-true facts were false), a commit body citing a line that held something else, and a banner whose own supporting sentence confirmed the bullet it marked as wrong. Nobody hunts this unprompted because the diff "obviously" improves accuracy. Read every corrected sentence literally and ask whether each clause is true under that reading.
93
93
 
@@ -50,7 +50,7 @@ Obeying a fired signal blindly stalls the queue on a non-conflict; ignoring one
50
50
 
51
51
  ## The labelled head
52
52
 
53
- `ready-to-merge` is a finisher's verdict on one tree, and it does not expire when that tree does. **A GitHub label does not follow the branch** — #180 is the record, and the query below is what reads it: `labeled ready-to-merge`, then commits and a `head_ref_force_pushed`, then `merged`, with no `unlabeled` anywhere between. The label stayed put while the head moved out from under it. Every other guard in this chain — the finisher's dispatch pin, the halt on a moved head, the worktree audit — runs *before* the label exists, so none of them is watching this window. You are the last gate, and **re-deriving the head is a requirement here, not bot discretion**: merge only a head that still carries the audit the label stands for.
53
+ `ready-to-merge` is a finisher's verdict on one tree, and it does not expire when that tree does. **A GitHub label does not follow the branch** — one merged PR's timeline is the record, and the query below is what reads it: `labeled ready-to-merge`, then commits and a `head_ref_force_pushed`, then `merged`, with no `unlabeled` anywhere between. The label stayed put while the head moved out from under it. Every other guard in this chain — the finisher's dispatch pin, the halt on a moved head, the worktree audit — runs *before* the label exists, so none of them is watching this window. You are the last gate, and **re-deriving the head is a requirement here, not bot discretion**: merge only a head that still carries the audit the label stands for.
54
54
 
55
55
  **Read the timeline before `gh pr update-branch` and before anything else that can move the head.** Your own rebase lands commits after the label by construction, so once you have rebased this read can no longer tell your commits from someone else's:
56
56
 
@@ -71,7 +71,7 @@ What this gate deliberately does not answer. It does not ask *who* audited — a
71
71
 
72
72
  For each labeled PR clearing the hold rule, lowest first:
73
73
 
74
- **Before step 1, check the ledger for an unresolved conflict hold on this PR (#2064).** Read the ticket row that names it — the same lookup step 4 below uses (`ledger.mjs read`). A `conflict-hold:#<pr>` token with no `fix-pr-<n>` settled (`applied:`/`no-op`) *after* it — reading the row left to right, past whatever dispatched after the LATEST hold token — is unresolved: a fix-applier already owns this PR's conflict, from this pass or an earlier one. **Skip it**: do not rebase, do not touch the row, do not report `rebase-fallback-#<pr>` again. Report `conflict-held-#<pr>` and move to the next labeled PR. Only once a fix-applier dispatched after the hold has settled does it clear — proceed through the sequence below as normal from there.
74
+ **Before step 1, check the ledger for an unresolved conflict hold on this PR.** Read the ticket row that names it — the same lookup step 4 below uses (`ledger.mjs read`). A `conflict-hold:#<pr>` token with no `fix-pr-<n>` settled (`applied:`/`no-op`) *after* it — reading the row left to right, past whatever dispatched after the LATEST hold token — is unresolved: a fix-applier already owns this PR's conflict, from this pass or an earlier one. **Skip it**: do not rebase, do not touch the row, do not report `rebase-fallback-#<pr>` again. Report `conflict-held-#<pr>` and move to the next labeled PR. Only once a fix-applier dispatched after the hold has settled does it clear — proceed through the sequence below as normal from there.
75
75
 
76
76
  1. If the PR is behind `origin/main`, update it **server-side first**: `gh pr update-branch <pr> --rebase`. That's an API call, not a push — no local git command runs, so the force-push classifier denial this step used to hit (`git push --force-with-lease`, judged and intermittently denied per invocation — 2 allowed / 2 denied on byte-identical invocations in one session; `settings.json` has since gained an `autoMode.allow` entry for exactly that command, so adding one is not the missing fix) never enters. The call is async, so this is two blocks. The fire block reads the head the rebase starts from and makes the call, in seconds:
77
77
 
@@ -111,11 +111,11 @@ For each labeled PR clearing the hold rule, lowest first:
111
111
  "$pr_head"
112
112
  ```
113
113
 
114
- **Fire once; only the poll is ever re-issued.** `pre` is the one reading nothing after the rebase can reconstruct: once the rebase lands, the ref it was read from *is* the rebased head. So a fire block run a second time reads the rebased head as its `pre`, `gh pr update-branch` answers `UNPROCESSABLE: There are no new commits on the base branch`, and a rebase that landed reports as the already-current row below, never verified. The poll only reads, so re-issuing it with the same `rc` and `pre` is safe — and it is the half that gets cut off. Each of its loops is capped at 60 × 5s, and the PR object's measured lag alone outruns that cap on the common landed-with-lag path (#1895's own repro: 75.6s wall-clock at re-poll attempt 14, 129.2s at attempt 24 — a separate measurement from the pr_head-catchup pass below, whose attempt 14/24 wall-clock times differ from these). One re-issue is enough, never a loop of them: the ref poll alone ends inside the 600000 ceiling below, so a re-issued poll finds the ref already moved on its first read and waits out only the PR object's cap. The poll:
114
+ **Fire once; only the poll is ever re-issued.** `pre` is the one reading nothing after the rebase can reconstruct: once the rebase lands, the ref it was read from *is* the rebased head. So a fire block run a second time reads the rebased head as its `pre`, `gh pr update-branch` answers `UNPROCESSABLE: There are no new commits on the base branch`, and a rebase that landed reports as the already-current row below, never verified. The poll only reads, so re-issuing it with the same `rc` and `pre` is safe — and it is the half that gets cut off. Each of its loops is capped at 60 × 5s, and the PR object's measured lag alone outruns that cap on the common landed-with-lag path (measured repro: 75.6s wall-clock at re-poll attempt 14, 129.2s at attempt 24 — a separate measurement from the pr_head-catchup pass below, whose attempt 14/24 wall-clock times differ from these). One re-issue is enough, never a loop of them: the ref poll alone ends inside the 600000 ceiling below, so a re-issued poll finds the ref already moved on its first read and waits out only the PR object's cap. The poll:
115
115
 
116
116
  `bash` backgrounds any call past about 60s even with `timeout` set — so run the poll block in one Python `eval` cell through `subprocess.run`, its cell `timeout` at 900s or more, above both caps back to back; never `bash` plus `wait`.
117
117
 
118
- **Poll `git ls-remote`, not `gh pr view headRefOid`** — the PR object's head is precisely the field that desyncs, so polling it asks the one source that can be wrong about the thing you are waiting for. Measured, feigi/claude-config#903: the rebase landed and moved the branch ref, `headRefOid` stayed on the pre-rebase SHA with `mergeable_state: unknown` and no CI run on the new head, and the loop burned all 60 iterations reading a landed rebase as un-landed — straight into the fallback, whose local rebase would then have replayed commits the remote already carried. `ls-remote` reads the ref itself and carries no local state, the same reason the `fetch.prune` note below re-derives a reading from `git ls-remote origin` rather than trusting a number measured while the ref was missing. Keep the `headRefOid` read, as the `pr_head` the printf reports: it is no longer the gate, and its *disagreement* with `post` is the desync signal you want on the record. That is why the poll block re-polls it only once the ref has moved — to let the PR object catch up, never to decide whether the rebase landed.
118
+ **Poll `git ls-remote`, not `gh pr view headRefOid`** — the PR object's head is precisely the field that desyncs, so polling it asks the one source that can be wrong about the thing you are waiting for. Measured: the rebase landed and moved the branch ref, `headRefOid` stayed on the pre-rebase SHA with `mergeable_state: unknown` and no CI run on the new head, and the loop burned all 60 iterations reading a landed rebase as un-landed — straight into the fallback, whose local rebase would then have replayed commits the remote already carried. `ls-remote` reads the ref itself and carries no local state, the same reason the `fetch.prune` note below re-derives a reading from `git ls-remote origin` rather than trusting a number measured while the ref was missing. Keep the `headRefOid` read, as the `pr_head` the printf reports: it is no longer the gate, and its *disagreement* with `post` is the desync signal you want on the record. That is why the poll block re-polls it only once the ref has moved — to let the PR object catch up, never to decide whether the rebase landed.
119
119
 
120
120
  **Check the call's exit status before polling, and bound the poll.** The head never moving *is* the failure case, so an `until` that waits for it to move spins forever in exactly the states the fallback exists for — the escapes named below are unreachable from a loop that never exits. Read the four outcomes off `rc` and `post`:
121
121
 
@@ -130,11 +130,11 @@ For each labeled PR clearing the hold rule, lowest first:
130
130
 
131
131
  **A desync that DOES survive the cap is the one state that needs a controller.** The rebase landed; GitHub's PR object did not follow. CI is bound to the stale head or absent entirely, so the merge gate cannot clear no matter how long you wait, and no merge-bot action fixes it — do not retry the rebase, and do not rebase locally, because the remote is already correct. Report it and stop.
132
132
 
133
- **The controller's remedy is close-and-reopen, and it has a precondition that must be checked FIRST.** Reopening requires the PR's recorded head to still be reachable from the branch — and a rebase orphans it by construction, which is the very event that produced the desync. So before closing anything, run `git merge-base --is-ancestor <pr_head> origin/<branch>`. Non-ancestor → **do not close**: GitHub refuses to reopen a PR whose head is unreachable (measured on #903 — three reopen attempts, `Could not open the pull request` each time), and the only recovery is opening a replacement PR from the same branch, which loses the review thread and every label on it. Close-and-reopen is normally reversible; past an orphaning rebase it is a one-way door.
133
+ **The controller's remedy is close-and-reopen, and it has a precondition that must be checked FIRST.** Reopening requires the PR's recorded head to still be reachable from the branch — and a rebase orphans it by construction, which is the very event that produced the desync. So before closing anything, run `git merge-base --is-ancestor <pr_head> origin/<branch>`. Non-ancestor → **do not close**: GitHub refuses to reopen a PR whose head is unreachable (measured — three reopen attempts, `Could not open the pull request` each time), and the only recovery is opening a replacement PR from the same branch, which loses the review thread and every label on it. Close-and-reopen is normally reversible; past an orphaning rebase it is a one-way door.
134
134
 
135
135
  This also repairs a branch carrying a merge commit — GitHub's rebase drops those too.
136
136
 
137
- **A worktree for this branch, if one exists, goes stale here** — the API rebased the remote, not your checkout. Expected, not a divergence. To prove it holds nothing unique, run `git cherry origin/<branch> HEAD` from the worktree **before the merge, never after**, and **not** `git cherry origin/main HEAD`: `main` never contained this PR's commits before the merge either, so it reads `+` for all of them regardless of staleness and proves nothing (measured, feigi/claude-config#149). The window is the point: step 4 deletes the remote branch once the PR lands (`delete-merged-branch.sh`; a repo that auto-deletes head branches removes it at the merge itself), so `origin/<branch>` outlives the merge only until the next pruning fetch, and step 4's `prove-merge.sh` runs one seconds later (`grep -n 'git fetch --quiet origin' scripts/prove-merge.sh`, plain, which prunes under the `fetch.prune=true` this machine's global config sets — `git config --show-origin --get fetch.prune`). Past that fetch the probe fails on a missing ref, an error easy to misread as the divergence it was meant to rule out.
137
+ **A worktree for this branch, if one exists, goes stale here** — the API rebased the remote, not your checkout. Expected, not a divergence. To prove it holds nothing unique, run `git cherry origin/<branch> HEAD` from the worktree **before the merge, never after**, and **not** `git cherry origin/main HEAD`: `main` never contained this PR's commits before the merge either, so it reads `+` for all of them regardless of staleness and proves nothing (measured). The window is the point: step 4 deletes the remote branch once the PR lands (`delete-merged-branch.sh`; a repo that auto-deletes head branches removes it at the merge itself), so `origin/<branch>` outlives the merge only until the next pruning fetch, and step 4's `prove-merge.sh` runs one seconds later (`grep -n 'git fetch --quiet origin' scripts/prove-merge.sh`, plain, which prunes under the `fetch.prune=true` this machine's global config sets — `git config --show-origin --get fetch.prune`). Past that fetch the probe fails on a missing ref, an error easy to misread as the divergence it was meant to rule out.
138
138
 
139
139
  **Neither result halts this path, and a `+` here is not the diverged-worktree STOP.** The clean answer is the absence of a `+`, not the absence of output: `git cherry` prints a line per commit in `origin/<branch>..HEAD`, `-` where the upstream already holds an equivalent patch and `+` where it does not, so it never goes silent merely because the rebase superseded everything. A worktree that has not fetched since the API rebase — the state this step leaves it in, since no local git command runs here — reads nothing; one that has fetched reads `-` for every rebased commit. Both are clean (measured 2026-08-29 in a scratch repo: a bare remote, a branch rebased onto an advanced `main` and force-pushed, and a clone left at the pre-rebase head — `git cherry origin/feat HEAD` printed nothing before that clone fetched and a `-` per rebased commit after, while an unpushed commit added on top raised a `+` in both). A `+` names a commit the worktree holds and that branch does not — say so alongside the merge, since it is the only signal that something local is unpushed, but it does not stop the merge, because nothing local reaches the remote from here: this step rebases through the API and pushes nothing, and step 4 merges the remote head, so an unpushed local commit is structurally unable to enter the merge. That STOP lives in the fallback (server-side rebase unavailable) and does not halt for the reason just ruled out here: neither path can carry a local commit to the remote, because neither pushes. What differs is what gets verified — the fallback rebases the worktree and verifies *that* head, so a commit only the worktree holds makes the verified tree something other than the reviewed head; here the worktree is only read, never rebased, so a `+` is a report, not a halt.
140
140
 
@@ -152,7 +152,7 @@ For each labeled PR clearing the hold rule, lowest first:
152
152
 
153
153
  **Compare the worktree head against the branch REF, and never against `gh pr view <pr> --json headRefOid -q .headRefOid`** — the PR object's head is the field that desyncs from the branch, which is why step 1 polls `git ls-remote` rather than it. Never `git rev-parse origin/<branch>` either: that is this clone's cached copy of the ref, so a worktree sitting on a stale copy agrees with it by construction and every tree this check exists to catch passes. The `headRefOid` read stays, and stays demoted — a value disagreeing with the ref is the PR-object desync above, a fact for the report, never the operand this check turns on. **An empty ref read is neither equal nor a mismatch**: the read failed, or the head branch is not on `origin` at all (a fork PR), so report the ref as unreadable and stop, `blocked` — an empty string compares unequal to every sha, so without this clause a failed read renders as a diverged worktree, the same hole `[ -n "$pre" ]` closes on the way into the poll above.
154
154
 
155
- **Why the ref and not `headRefOid`: during the PR object's lag both operands go stale in the SAME direction, so that compare fails OPEN as readily as it fails closed.** The false STOP is the visible half — the worktree holds the rebased head, the PR object still holds the pre-rebase sha, and a correct tree comes back `worktree-diverged-#<pr>`, costing a pass. The silent half is the one that ships: a worktree that has not fetched since the rebase sits on that same pre-rebase sha, so BOTH sides read it, the check reads **Equal**, and this fallback verifies a tree the remote no longer has while step 4 merges the head it does — a green measured against a tree no merge will take, which is the exact failure the STOP arm below exists to prevent, reached through the arm that passes. Measured at the sibling site (`run-team/SKILL.md` phase 1, #1168) in a scratch repo: a clone unfetched since the rebase resolved `origin/<branch>` to the pre-rebase commit with its subject unchanged, while `git ls-remote origin refs/heads/<branch>` read the true tip from that same clone. **Re-reading `headRefOid` on a settle window does not reach that half at all** — it fires only where the two disagree — which is why the operand changes here rather than the verdict gaining a window.
155
+ **Why the ref and not `headRefOid`: during the PR object's lag both operands go stale in the SAME direction, so that compare fails OPEN as readily as it fails closed.** The false STOP is the visible half — the worktree holds the rebased head, the PR object still holds the pre-rebase sha, and a correct tree comes back `worktree-diverged-#<pr>`, costing a pass. The silent half is the one that ships: a worktree that has not fetched since the rebase sits on that same pre-rebase sha, so BOTH sides read it, the check reads **Equal**, and this fallback verifies a tree the remote no longer has while step 4 merges the head it does — a green measured against a tree no merge will take, which is the exact failure the STOP arm below exists to prevent, reached through the arm that passes. Measured at the sibling site (`run-team/SKILL.md` phase 1) in a scratch repo: a clone unfetched since the rebase resolved `origin/<branch>` to the pre-rebase commit with its subject unchanged, while `git ls-remote origin refs/heads/<branch>` read the true tip from that same clone. **Re-reading `headRefOid` on a settle window does not reach that half at all** — it fires only where the two disagree — which is why the operand changes here rather than the verdict gaining a window.
156
156
 
157
157
  **Unequal → `git fetch origin` and read the ref once more, then decide on that second reading. Bounded at one re-read, never a third.** Neither operand is a cached value, so a stable second reading cannot flip the verdict; what the re-read is for is the ref MOVING while you verify, which is live here because one way into this fallback is a step-1 poll whose cap ran out with the ref unmoved, and that call is async — it can land a moment after you gave up on it. The two readings differ → the head is not settled and the audit behind the label verified a tree that is already gone, so **refuse: report `head-moved-after-label-#<pr>` and stop**, label untouched, the same verdict and the same remedy — a fresh finisher against the new head — the gate above reaches for a head that moved after the audit. Do not read a third time; that is the unbounded wait step 1 had to be written out of. The two readings agree → the mismatch is real and belongs to one of the two arms below. **`Equal` is not among the outcomes a surviving mismatch can reach**: a worktree that is not on the branch ref never passes this check, whatever the PR object says.
158
158
 
@@ -180,7 +180,7 @@ For each labeled PR clearing the hold rule, lowest first:
180
180
 
181
181
  **A repo that gates on currency cannot merge from this path — and this one does.** The fallback leaves the remote head behind `origin/main` on purpose, which is the exact condition `rebase-check` fails on: `.github/workflows/ci.yml` checks out `pull_request.head.sha` and exits 1 when the merge-base is not the base tip. It is an expected job, so `ci-state.mjs` reports non-green, step 3's gate never opens, and `mergeStateStatus` cannot read `CLEAN` either. The four checks above are still the honest verification of the *content*, but they do not clear that gate. So here the fallback **ends without merging**: report `rebase-fallback-#<pr>` as blocked and hand it back — choosing between resolving the conflict and turning `allow_update_branch` on is a human's call. Step 4's merge is reachable from this path only where no expected job gates on currency.
182
182
 
183
- **When that hand-back is a conflict, record it on the ledger before you report — your report is gone when you exit, and nothing else durable says the PR is stuck (#2064).** It is a conflict when the fallback's local rebase stopped on conflicting paths, whether you then resolved them for verification or aborted: nothing on this path pushes, so the remote head still carries the conflict either way. Not when the server-side rebase failed only because `allow_update_branch` is off and the local rebase applied clean — there is nothing for a fix-applier to resolve. The stopped rebase already named the conflicting paths — read them before you resolve or abort (`git -C <worktree> diff --name-only --diff-filter=U`) — so a later auditor can tell what collided from the row text alone, without re-reading this report (#2064 story 15). Append the hold to the ticket row that names the PR — the row whose first `PR#` mention is `PR#<pr>`, or the row keyed `#<pr>` when none does — as one rewrite of that row's own text, never a bare line — **unless it already carries one unresolved.** Read the row fresh (below) before writing: if its last `conflict-hold:#<pr>` has no `fix-pr-<n>` settled after it, the row already says what you are about to say — a duplicate write teaches the tick nothing new, and once a fix-applier already working the first hold settles in place before your copy, the tick reads your copy as a fresh hold that settle never cleared. Report `rebase-fallback-#<pr>` and stop there; only write when the row's last hold (if any) has a settled fix-pr after it, or carries no hold at all.
183
+ **When that hand-back is a conflict, record it on the ledger before you report — your report is gone when you exit, and nothing else durable says the PR is stuck.** It is a conflict when the fallback's local rebase stopped on conflicting paths, whether you then resolved them for verification or aborted: nothing on this path pushes, so the remote head still carries the conflict either way. Not when the server-side rebase failed only because `allow_update_branch` is off and the local rebase applied clean — there is nothing for a fix-applier to resolve. The stopped rebase already named the conflicting paths — read them before you resolve or abort (`git -C <worktree> diff --name-only --diff-filter=U`) — so a later auditor can tell what collided from the row text alone, without re-reading this report. Append the hold to the ticket row that names the PR — the row whose first `PR#` mention is `PR#<pr>`, or the row keyed `#<pr>` when none does — as one rewrite of that row's own text, never a bare line — **unless it already carries one unresolved.** Read the row fresh (below) before writing: if its last `conflict-hold:#<pr>` has no `fix-pr-<n>` settled after it, the row already says what you are about to say — a duplicate write teaches the tick nothing new, and once a fix-applier already working the first hold settles in place before your copy, the tick reads your copy as a fresh hold that settle never cleared. Report `rebase-fallback-#<pr>` and stop there; only write when the row's last hold (if any) has a settled fix-pr after it, or carries no hold at all.
184
184
 
185
185
  ```bash
186
186
  ~/.fleet/bin/fleet-run ledger.mjs read # the row: `#<key> <text>`
@@ -226,7 +226,7 @@ For each labeled PR clearing the hold rule, lowest first:
226
226
 
227
227
  4. `gh pr merge <pr> --merge` (no-ff). It can exit silently — confirm with `gh pr view <pr> --json state,mergedAt,mergeCommit` before claiming it merged. **Never `--delete-branch` on this call** — the head branch is deleted below, by `delete-merged-branch.sh`, never by `gh`.
228
228
 
229
- **`--merge` (no-ff) is load-bearing, not stylistic — and do not let a content claim reach you worded as a graph-shape one.** It always writes a **two-parent** merge commit, even where the branch is trivially fast-forwardable, and step 5's proof *requires* that: `prove-merge.sh` dies at `has no second parent — not a merge commit` and exits **2** on a single-parent merge. Exit 2 is "could not evaluate the claim at all", not "the claim is false" — so a real fast-forward leaves you with no proof to report and a halt, not a failed proof. Measured on #908: a controller brief predicted "the merge will be a fast-forward", and the merge tree *was* byte-identical to the reviewed head (`988f29d1`, `git diff <pin> <merge>` empty) — but the commit still had two parents, which is the only reason the proof was available. "The merge adds nothing" is a statement about content; **never write it as "fast-forward", which is a statement about shape, and which would have broken step 5.**
229
+ **`--merge` (no-ff) is load-bearing, not stylistic — and do not let a content claim reach you worded as a graph-shape one.** It always writes a **two-parent** merge commit, even where the branch is trivially fast-forwardable, and step 5's proof *requires* that: `prove-merge.sh` dies at `has no second parent — not a merge commit` and exits **2** on a single-parent merge. Exit 2 is "could not evaluate the claim at all", not "the claim is false" — so a real fast-forward leaves you with no proof to report and a halt, not a failed proof. Measured once: a controller brief predicted "the merge will be a fast-forward", and the merge tree *was* byte-identical to the reviewed head (`988f29d1`, `git diff <pin> <merge>` empty) — but the commit still had two parents, which is the only reason the proof was available. "The merge adds nothing" is a statement about content; **never write it as "fast-forward", which is a statement about shape, and which would have broken step 5.**
230
230
 
231
231
  **Prove which head landed.** A rebase-then-merge leaves no trace of *which* version went in, and "I rebased" is exactly the claim asserted without doing it:
232
232
 
@@ -236,11 +236,11 @@ For each labeled PR clearing the hold rule, lowest first:
236
236
 
237
237
  **No rebase happened because the PR was already current? Pass the head twice.** That is the normal case in a pass, not an edge case, and `pre == post` selects a proof path built for it. Never invent a plausible-looking `pre` to make the arguments differ — a `pre` that never landed satisfies the pre-rebase leg by construction, and passing one is the single easiest way to turn a stale merge into `proved=true`.
238
238
 
239
- **Read `gates`, not the flat fields.** The payload's flat fields are observations, and one of them being true or false says nothing about the verdict on its own. `gates` is the verdict's own working: `proved` is true exactly when every value in it is true. Membership is per-invocation — on the rebase path it carries `preDidNotLand` (leg 1), on the no-rebase path it does not, because leg 1 is dropped there. That is why `preIsAncestor:true` sits next to `proved:true` on the no-rebase path and is **not** a contradiction: leg 1 wants it false, and leg 1 is not a gate on that path (#18). A sanity check written against `preIsAncestor === false` rejects correct merges; write it against `gates` instead.
239
+ **Read `gates`, not the flat fields.** The payload's flat fields are observations, and one of them being true or false says nothing about the verdict on its own. `gates` is the verdict's own working: `proved` is true exactly when every value in it is true. Membership is per-invocation — on the rebase path it carries `preDidNotLand` (leg 1), on the no-rebase path it does not, because leg 1 is dropped there. That is why `preIsAncestor:true` sits next to `proved:true` on the no-rebase path and is **not** a contradiction: leg 1 wants it false, and leg 1 is not a gate on that path. A sanity check written against `preIsAncestor === false` rejects correct merges; write it against `gates` instead.
240
240
 
241
241
  Exit **0** proved, **1** disproved, **2** the script could not evaluate the claim at all — the merge is unreachable from `origin/main`, is not a merge commit, or an argument does not resolve. Treat 2 as "ask a human", not as a disproof.
242
242
 
243
- **A `rebase-fallback-#<pr>` merge is expected to disprove here.** Step 1's fallback never lands a rebased head on the remote, so `pre == post` and `headWasCurrent` reads false — `prove-merge.sh` exits **1**, correctly (`prove-merge.test.mjs`'s `ATTACK: un-rebased head that merged cleanly still proves false` pins exactly this shape). That is the honest answer, not a script fault. Report the merge as **argued** — backed by the fallback's four checks — and never as `proved`; a merge whose ancestry was not proved is never reported as proved.
243
+ **A `rebase-fallback-#<pr>` merge is expected to disprove here.** Step 1's fallback never lands a rebased head on the remote, so `pre == post` and `headWasCurrent` reads false — `prove-merge.sh` exits **1**, correctly. That is the honest answer, not a script fault. Report the merge as **argued** — backed by the fallback's four checks — and never as `proved`; a merge whose ancestry was not proved is never reported as proved.
244
244
 
245
245
  **Delete the head branch from `origin`** — this bot owns that step, and no repo setting does it for you. Without it a merged branch is never `[gone]`, so `reap.sh` never reaps it or its worktree. The same step also drops `in-progress` from every issue this PR closes: the merge is the only point where the ticket number and the fact of completion are known together, and nothing else clears it.
246
246
 
@@ -248,7 +248,7 @@ For each labeled PR clearing the hold rule, lowest first:
248
248
  ~/.fleet/bin/fleet-run delete-merged-branch.sh <pr>
249
249
  ```
250
250
 
251
- Exit 0 the branch is gone from `origin` — `deleted`, `alreadyGone` (a repo that still auto-deletes), or `skipped` for a fork PR, whose branch is not ours. **1 the branch is still on `origin` — report it as `branch-delete-failed-#<pr>`, never swallow it**: either a push landed on it after the merge (the delete is leased to the merged head, so it refuses rather than destroy commits `main` never received) or the push failed. The script reads the deletion back from `origin` rather than trusting the push's exit status. Exit 2 could not tell what to delete — the PR is not MERGED, a `gh` or `ls-remote` read failed, or the lookup for other open PRs on the branch failed (nothing is deleted then); call this only after the merge is confirmed at the top of this step. **Exit 3 the branch is kept on purpose — another open PR uses it as its head or its base** (#2295): deleting it would close the PRs headed by it, and may close rather than retarget the PRs based on it. Nothing was pushed. Its stdout is one `branch-kept-#<pr>` line per such PR, naming that open PR, not the merged one — report each line as printed. A deliberate keep, not a failure: never retry it, and never report it as `branch-delete-failed`. The branch stays on `origin`, so it is not `[gone]` and `reap.sh` leaves it and its worktree in place.
251
+ Exit 0 the branch is gone from `origin` — `deleted`, `alreadyGone` (a repo that still auto-deletes), or `skipped` for a fork PR, whose branch is not ours. **1 the branch is still on `origin` — report it as `branch-delete-failed-#<pr>`, never swallow it**: either a push landed on it after the merge (the delete is leased to the merged head, so it refuses rather than destroy commits `main` never received) or the push failed. The script reads the deletion back from `origin` rather than trusting the push's exit status. Exit 2 could not tell what to delete — the PR is not MERGED, a `gh` or `ls-remote` read failed, or the lookup for other open PRs on the branch failed (nothing is deleted then); call this only after the merge is confirmed at the top of this step. **Exit 3 the branch is kept on purpose — another open PR uses it as its head or its base**: deleting it would close the PRs headed by it, and may close rather than retarget the PRs based on it. Nothing was pushed. Its stdout is one `branch-kept-#<pr>` line per such PR, naming that open PR, not the merged one — report each line as printed. A deliberate keep, not a failure: never retry it, and never report it as `branch-delete-failed`. The branch stays on `origin`, so it is not `[gone]` and `reap.sh` leaves it and its worktree in place.
252
252
 
253
253
  **Exit 4 the branch half succeeded but the label half did not — report every token line the step printed on stdout, never swallow one.** `label-drop-failed-#<issue>` is one issue whose removal failed: a merged ticket that keeps the label is invisible the moment it is reopened. `label-read-failed-#<pr>` means what the PR closes could not be determined — never read it as "nothing to drop". When the branch half exits 1, 2 or 3 that code wins, and the same token lines are still printed ahead of the branch output. On any non-zero exit, report every token line; never retry.
254
254
 
@@ -274,7 +274,7 @@ A rebase resolved the wrong way silently reverts work already in `main`. It look
274
274
  ~/.fleet/bin/fleet-run no-undo-audit.sh <worktree> <branch>
275
275
  ```
276
276
 
277
- It refuses (exit 1) on a dirty worktree. Exit **2** is not that refusal: it means the audit could not answer at all — a bad argument, no such worktree, a worktree git does not answer for (its linkage is broken, and git still answers at rc 0 — for the enclosing repo when the `.git` is gone, from another worktree's HEAD and index when it names that worktree's admin dir, against another directory's files when `core.worktree` moves the working tree there), `BASE_REF` is not spelled `origin/<branch>` or `refs/remotes/<path>` (#1565), `BASE_REF` names the audited branch (#1565), a ref that does not resolve, a probe that could not run, or a conflicting path no pathspec can name — and it emits no payload. What it will **not** do is spend a 2 on the formatting of `worktree` or `branch`: those two echo the arguments you handed it rather than reporting a finding, so an escaper that cannot render one leaves that field and its `*Rewritten` flag as JSON `null` and the run still delivers `clean`, `stash`, `conflicts[]` and `atRisk[]` at its own exit code, naming the field and the escaper on stderr. Read a `null` there as "this run could not render the path or branch you passed in" — it is **never** "there is no worktree", and never a path: pasting it into a command builds a pathspec matching nothing, the same empty-reads-as-proven trap the `conflictsRewritten[]` note below describes. Treat 2 as "ask a human", never as "the worktree is dirty"; there is nothing to commit and hunting for it wastes the pass. **Never** `git clean`, `git checkout .`, `git reset --hard`, or `git stash` to make it pass — that work is unrecoverable and is not on the remote, and stashing it clears `porcelain` so the audit passes on the next run without the work ever shipping. The stash count it prints is reported, not gated: the stack is repo-global across worktrees, so a nonzero count is usually the maintainer's. It can also come back `unknown` rather than a number. Usually the list came back empty and the audit cannot call that an empty stash: `refs/stash` is not absent, which an unreadable ref, an unreadable reflog, or a ref pointing at a missing object each produce just as a genuinely empty stash would. The fourth cause is the opposite shape: `refs/stash` **is** absent while its reflog is not, so the entries it names are unreachable rather than gone. One cause is neither shape: `git stash list` printed entries and then exited nonzero, so what it printed is short — a corrupt loose object behind an entry that is not the tip does this, and the audit reports `unknown` there rather than the number it could have counted. The audit's line says which of them you have. None is the same thing as an empty stash and the audit no longer conflates them. The number it prints is a floor, not a proof: a reflog that is merely truncated — some entries lost, the rest still parsing — drops the missing entries from `git stash list` itself, so the audit and your own read of the list come up short by the same ones and neither reports it. Read `git stash list` yourself when the count is nonzero **or `unknown`** — an entry naming this branch may be a dead member's only copy — and never pop, drop or apply an entry you did not create. On `unknown` do not stop at that list: the causes git stays silent about leave it empty at rc 0, so the list alone shows you nothing. The missing-object cause is the one git is not silent about: `git stash list`'s own stderr there already ends `fatal: bad object refs/stash`, naming that cause outright, so read that line first. The corrupt loose object is named outright too — `fatal: loose object … is corrupt`, printed after the entries git could read — and the audit's own line carries that text for you either way. For the causes it stays silent on, read the files behind it. Set `c=$(git rev-parse --git-common-dir)` — the stack is repo-global, and a linked worktree's `.git` is a file, so `.git/refs/stash` reaches nothing — then `ls -l "$c"/refs/stash "$c"/logs/refs/stash`, where a mode of `----------` on either, or a `Permission denied` from `ls` itself, is the fault, and `cat "$c"/logs/refs/stash`, which still names the branch when `refs/stash` is the unreadable one. `No such file or directory` for `refs/stash` alone, with the reflog listing beside it, is the fourth cause: recover from the SHAs `cat` prints, do not rebase over it. A missing `refs/stash` file is not an empty stash: `git gc` packs it into `packed-refs`. When both reads instead come back with nothing to recover from — `cat` denied, or a reflog that is present but blank — `git show refs/stash` still resolves the ref whether loose or packed, printing the `WIP on <branch>` label; it prints no diff beside that label when the stashed change was staged before `git stash`, so read the content with `git stash show -p refs/stash`, which prints the hunk either way. Both fail only where the ref FILE is itself the broken one — unreadable, holding text that is not a SHA, or gone with nothing in `packed-refs` — and there the SHA `cat` already printed, in the reflog's second field, is what `git stash show -p <that sha>` recovers instead. That fallback is a SHA `cat` printed, so it is gone where the reflog is the denied read too — both files unreadable, `refs/stash` holding text that is not a SHA while the reflog cannot be read, or `refs/stash` gone with nothing in `packed-refs` while the reflog cannot be read — and nothing ref-based recovers there: `git stash list` is still empty at rc 0, `git show refs/stash` answers `ambiguous argument` and `git stash show -p refs/stash` answers `not a valid reference`, and no SHA was printed to hand them instead. Restore read permission where the mode is yours to fix — on whichever of the two files `ls` gave a `----------`, or on the `logs/refs` directory when `ls` failed before printing a mode at all. Only the both-files-unreadable shape then has `git stash list` name the entry again on its own, measured, because the ref file's own content was never touched, only its permission. The other two shapes leave `refs/stash` itself broken — deleted, or holding garbage text — so restoring the reflog's mode only unlocks the SHA `cat` now prints; `git stash list` stays empty at rc 0 until you clear the broken ref and re-point it yourself. `git update-ref refs/stash <that sha>` works directly once `refs/stash` is already gone; where it instead holds garbage text, `git update-ref` refuses that too (`reference broken`, even with `-d`) until you `rm` the file first. Either path is measured to list the entry again as a new `stash@{0}` (an empty-subject entry the update itself adds), pushing the recovered one down to `stash@{1}` rather than restoring it to its original slot. Where there is no mode left to fix — both files are simply gone, with nothing in `packed-refs` and no reflog to read either — `git fsck` still prints a `dangling commit <sha>` line per stash entry, objects loose or packed — at a nonzero exit in the unreadable-ref shape, so read its lines and not its status — and `git stash show -p <that sha>` prints the hunk there, refusing anything that is not a stash (`is not a stash-like commit`). Treat it as a lead, not a listing: no `stash@{N}` comes back with it, and an entry someone dropped on purpose is indistinguishable from a live one. Read the at-risk commits the audit lists first; those are what a careless resolution deletes.
277
+ It refuses (exit 1) on a dirty worktree. Exit **2** is not that refusal: it means the audit could not answer at all — a bad argument, no such worktree, a worktree git does not answer for (its linkage is broken, and git still answers at rc 0 — for the enclosing repo when the `.git` is gone, from another worktree's HEAD and index when it names that worktree's admin dir, against another directory's files when `core.worktree` moves the working tree there), `BASE_REF` is not spelled `origin/<branch>` or `refs/remotes/<path>`, `BASE_REF` names the audited branch, a ref that does not resolve, a probe that could not run, or a conflicting path no pathspec can name — and it emits no payload. What it will **not** do is spend a 2 on the formatting of `worktree` or `branch`: those two echo the arguments you handed it rather than reporting a finding, so an escaper that cannot render one leaves that field and its `*Rewritten` flag as JSON `null` and the run still delivers `clean`, `stash`, `conflicts[]` and `atRisk[]` at its own exit code, naming the field and the escaper on stderr. Read a `null` there as "this run could not render the path or branch you passed in" — it is **never** "there is no worktree", and never a path: pasting it into a command builds a pathspec matching nothing, the same empty-reads-as-proven trap the `conflictsRewritten[]` note below describes. Treat 2 as "ask a human", never as "the worktree is dirty"; there is nothing to commit and hunting for it wastes the pass. **Never** `git clean`, `git checkout .`, `git reset --hard`, or `git stash` to make it pass — that work is unrecoverable and is not on the remote, and stashing it clears `porcelain` so the audit passes on the next run without the work ever shipping. The stash count it prints is reported, not gated: the stack is repo-global across worktrees, so a nonzero count is usually the maintainer's. It can also come back `unknown` rather than a number. Usually the list came back empty and the audit cannot call that an empty stash: `refs/stash` is not absent, which an unreadable ref, an unreadable reflog, or a ref pointing at a missing object each produce just as a genuinely empty stash would. The fourth cause is the opposite shape: `refs/stash` **is** absent while its reflog is not, so the entries it names are unreachable rather than gone. One cause is neither shape: `git stash list` printed entries and then exited nonzero, so what it printed is short — a corrupt loose object behind an entry that is not the tip does this, and the audit reports `unknown` there rather than the number it could have counted. The audit's line says which of them you have. None is the same thing as an empty stash and the audit no longer conflates them. The number it prints is a floor, not a proof: a reflog that is merely truncated — some entries lost, the rest still parsing — drops the missing entries from `git stash list` itself, so the audit and your own read of the list come up short by the same ones and neither reports it. Read `git stash list` yourself when the count is nonzero **or `unknown`** — an entry naming this branch may be a dead member's only copy — and never pop, drop or apply an entry you did not create. On `unknown` do not stop at that list: the causes git stays silent about leave it empty at rc 0, so the list alone shows you nothing. The missing-object cause is the one git is not silent about: `git stash list`'s own stderr there already ends `fatal: bad object refs/stash`, naming that cause outright, so read that line first. The corrupt loose object is named outright too — `fatal: loose object … is corrupt`, printed after the entries git could read — and the audit's own line carries that text for you either way. For the causes it stays silent on, read the files behind it. Set `c=$(git rev-parse --git-common-dir)` — the stack is repo-global, and a linked worktree's `.git` is a file, so `.git/refs/stash` reaches nothing — then `ls -l "$c"/refs/stash "$c"/logs/refs/stash`, where a mode of `----------` on either, or a `Permission denied` from `ls` itself, is the fault, and `cat "$c"/logs/refs/stash`, which still names the branch when `refs/stash` is the unreadable one. `No such file or directory` for `refs/stash` alone, with the reflog listing beside it, is the fourth cause: recover from the SHAs `cat` prints, do not rebase over it. A missing `refs/stash` file is not an empty stash: `git gc` packs it into `packed-refs`. When both reads instead come back with nothing to recover from — `cat` denied, or a reflog that is present but blank — `git show refs/stash` still resolves the ref whether loose or packed, printing the `WIP on <branch>` label; it prints no diff beside that label when the stashed change was staged before `git stash`, so read the content with `git stash show -p refs/stash`, which prints the hunk either way. Both fail only where the ref FILE is itself the broken one — unreadable, holding text that is not a SHA, or gone with nothing in `packed-refs` — and there the SHA `cat` already printed, in the reflog's second field, is what `git stash show -p <that sha>` recovers instead. That fallback is a SHA `cat` printed, so it is gone where the reflog is the denied read too — both files unreadable, `refs/stash` holding text that is not a SHA while the reflog cannot be read, or `refs/stash` gone with nothing in `packed-refs` while the reflog cannot be read — and nothing ref-based recovers there: `git stash list` is still empty at rc 0, `git show refs/stash` answers `ambiguous argument` and `git stash show -p refs/stash` answers `not a valid reference`, and no SHA was printed to hand them instead. Restore read permission where the mode is yours to fix — on whichever of the two files `ls` gave a `----------`, or on the `logs/refs` directory when `ls` failed before printing a mode at all. Only the both-files-unreadable shape then has `git stash list` name the entry again on its own, measured, because the ref file's own content was never touched, only its permission. The other two shapes leave `refs/stash` itself broken — deleted, or holding garbage text — so restoring the reflog's mode only unlocks the SHA `cat` now prints; `git stash list` stays empty at rc 0 until you clear the broken ref and re-point it yourself. `git update-ref refs/stash <that sha>` works directly once `refs/stash` is already gone; where it instead holds garbage text, `git update-ref` refuses that too (`reference broken`, even with `-d`) until you `rm` the file first. Either path is measured to list the entry again as a new `stash@{0}` (an empty-subject entry the update itself adds), pushing the recovered one down to `stash@{1}` rather than restoring it to its original slot. Where there is no mode left to fix — both files are simply gone, with nothing in `packed-refs` and no reflog to read either — `git fsck` still prints a `dangling commit <sha>` line per stash entry, objects loose or packed — at a nonzero exit in the unreadable-ref shape, so read its lines and not its status — and `git stash show -p <that sha>` prints the hunk there, refusing anything that is not a stash (`is not a stash-like commit`). Treat it as a lead, not a listing: no `stash@{N}` comes back with it, and an entry someone dropped on purpose is indistinguishable from a live one. Read the at-risk commits the audit lists first; those are what a careless resolution deletes.
278
278
 
279
279
  **4. Take `main`'s side wholesale, then re-apply the branch's delta on top.** Never blanket `-X ours` / `-X theirs`. The branch's side is by definition *pre-merge* text — on a docs or comment hunk it carries claims a later PR already corrected, and keeping it reintroduces them silently.
280
280
 
@@ -354,7 +354,7 @@ Arm with `persistent: true`, description `ready-to-merge label on this repo's PR
354
354
  - 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.
355
355
  - 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.
356
356
  - **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.
357
- - **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="849 850 "` and `cur="849 850 852 "`: the bare form runs **one** iteration with the whole list glued into a single value and emits `ready-to-merge label added: PR #849 850 852`, one nonsense event naming no PR, while the real new PR is never reported; the heredoc form emits `PR #852` 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.
357
+ - **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.
358
358
  - 60s poll — remote API, stay off rate limits.
359
359
  - 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.
360
360
 
@@ -7,7 +7,7 @@ This command only prints instructions — it never starts the fleet itself.
7
7
  `run-team` is a `disable-model-invocation` skill, invoke-only by design (the
8
8
  fleet writes to a live repo and must never start unasked). That flag also
9
9
  hides it from the human `/` picker, not just from the model's own
10
- auto-invoke list (#1381) — so there is nothing to browse to
10
+ auto-invoke list — so there is nothing to browse to
11
11
  there.
12
12
 
13
13
  To start the fleet, type this exactly — don't pick it from a list, type it: