@feigi/fleet-ctl 0.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +9 -0
- package/LICENSE +202 -0
- package/NOTICE +18 -0
- package/agents/fleet-finisher.agent.md +7 -0
- package/agents/fleet-implementer-alt.agent.md +210 -0
- package/agents/fleet-implementer.agent.md +210 -0
- package/agents/fleet-merge-bot.agent.md +7 -0
- package/agents/fleet-review-comments.agent.md +40 -0
- package/agents/fleet-review-correctness.agent.md +43 -0
- package/agents/fleet-review-runner.agent.md +73 -0
- package/agents/fleet-review-silent-failure.agent.md +49 -0
- package/agents/fleet-review-simplify.agent.md +46 -0
- package/agents/fleet-review-snapshot.agent.md +24 -0
- package/agents/fleet-review-tests.agent.md +46 -0
- package/agents/fleet-review-types.agent.md +41 -0
- package/agents/fleet-review-verifier.agent.md +29 -0
- package/commands/review-and-fix.md +98 -0
- package/commands/run-merge-bot.md +357 -0
- package/commands/run-team-help.md +17 -0
- package/package.json +23 -0
- package/scripts/agent-test-dir-prose.test.mjs +59 -0
- package/scripts/agent-test.test.mjs +1636 -0
- package/scripts/ambient-git-vars-mjs-prose.test.mjs +354 -0
- package/scripts/ambient-git-vars-prose.test.mjs +192 -0
- package/scripts/ancestry-check-position-prose.test.mjs +175 -0
- package/scripts/apply-ruleset.test.mjs +420 -0
- package/scripts/arg-header-probes-prose.test.mjs +393 -0
- package/scripts/arg.mjs +600 -0
- package/scripts/arg.test.mjs +1354 -0
- package/scripts/board-cli.test.mjs +694 -0
- package/scripts/board-identity.test.mjs +429 -0
- package/scripts/board-liveness-banner.test.mjs +119 -0
- package/scripts/board-prev-shape.test.mjs +229 -0
- package/scripts/board-tryparse-null.test.mjs +119 -0
- package/scripts/board.html +471 -0
- package/scripts/board.mjs +2037 -0
- package/scripts/board.test.mjs +3086 -0
- package/scripts/brief-after-cut-prose.test.mjs +53 -0
- package/scripts/candidates-exit3-prose.test.mjs +302 -0
- package/scripts/candidates.mjs +674 -0
- package/scripts/candidates.test.mjs +2101 -0
- package/scripts/caveat-unification-prose.test.mjs +98 -0
- package/scripts/ci-comment-rot-prose.test.mjs +2025 -0
- package/scripts/ci-completes-premise-prose.test.mjs +257 -0
- package/scripts/ci-state-prose.test.mjs +113 -0
- package/scripts/ci-state.mjs +761 -0
- package/scripts/ci-state.test.mjs +1640 -0
- package/scripts/ci-vacuous-green.test.mjs +368 -0
- package/scripts/citation-sweep-prose.test.mjs +1572 -0
- package/scripts/claim-lifecycle.test.mjs +185 -0
- package/scripts/claim-ticket.sh +417 -0
- package/scripts/claim-ticket.test.mjs +1121 -0
- package/scripts/closing-keyword-prose.test.mjs +193 -0
- package/scripts/cockpit-launch-idempotent-prose.test.mjs +165 -0
- package/scripts/cockpit-tick-nonblocking.test.mjs +210 -0
- package/scripts/compute-board.mjs +579 -0
- package/scripts/compute-board.test.mjs +1060 -0
- package/scripts/compute-spend.mjs +329 -0
- package/scripts/compute-spend.test.mjs +451 -0
- package/scripts/cross-repo-citation-prose.test.mjs +156 -0
- package/scripts/cwd-isolation-pins.mjs +83 -0
- package/scripts/dedupe-guard-prose.test.mjs +243 -0
- package/scripts/derive-testcmd.sh +239 -0
- package/scripts/derive-testcmd.test.mjs +380 -0
- package/scripts/diff-stats.mjs +231 -0
- package/scripts/diff-stats.test.mjs +408 -0
- package/scripts/dispatch-block-golden-prose.test.mjs +1024 -0
- package/scripts/dispatch-block-pins-prose.test.mjs +615 -0
- package/scripts/drop-merged-label.sh +173 -0
- package/scripts/drop-merged-label.test.mjs +480 -0
- package/scripts/expected-jobs-prose.test.mjs +80 -0
- package/scripts/filing-bar-seat-prose.test.mjs +242 -0
- package/scripts/filing-claim-bar-prose.test.mjs +166 -0
- package/scripts/finisher-dispatch-premise-prose.test.mjs +312 -0
- package/scripts/finisher-halt-prose.test.mjs +106 -0
- package/scripts/finisher-name-prose.test.mjs +134 -0
- package/scripts/finisher-own-tree-prose.test.mjs +285 -0
- package/scripts/finisher-pin-race-prose.test.mjs +339 -0
- package/scripts/fix-applier-correction-rules-prose.test.mjs +201 -0
- package/scripts/fix-applier-result-file-prose.test.mjs +100 -0
- package/scripts/fleet-bootstrap +155 -0
- package/scripts/fleet-heartbeat.mjs +272 -0
- package/scripts/fleet-heartbeat.test.mjs +450 -0
- package/scripts/fleet-provenance +207 -0
- package/scripts/fleet-provenance.test.mjs +64 -0
- package/scripts/fleet-run +148 -0
- package/scripts/fleet-run.test.mjs +90 -0
- package/scripts/fleet-state.mjs +400 -0
- package/scripts/fleet-state.test.mjs +373 -0
- package/scripts/fleet-tick-prose.test.mjs +299 -0
- package/scripts/fleet-tick.mjs +832 -0
- package/scripts/fleet-tick.test.mjs +1332 -0
- package/scripts/force-with-lease-reason-prose.test.mjs +184 -0
- package/scripts/frontmatter-allowlist.json +64 -0
- package/scripts/frontmatter-check.mjs +256 -0
- package/scripts/frontmatter-check.test.mjs +436 -0
- package/scripts/git-env.mjs +124 -0
- package/scripts/git-env.test.mjs +149 -0
- package/scripts/git-status-untracked-mode-sweep.test.mjs +216 -0
- package/scripts/gone-walk.test.mjs +213 -0
- package/scripts/gp-sep-invariant-prose.test.mjs +188 -0
- package/scripts/head-moved-after-label-prose.test.mjs +233 -0
- package/scripts/immutable-body-claim-prose.test.mjs +413 -0
- package/scripts/implementer-model-tier.test.mjs +643 -0
- package/scripts/inflight-citation-prose.test.mjs +144 -0
- package/scripts/inflight-exit2-prose.test.mjs +81 -0
- package/scripts/inflight-probe-guard-prose.test.mjs +109 -0
- package/scripts/inflight-scan-scope-prose.test.mjs +57 -0
- package/scripts/inflight.sh +1106 -0
- package/scripts/inflight.test.mjs +2984 -0
- package/scripts/injection-control-prose.test.mjs +404 -0
- package/scripts/install-root-audit.test.mjs +464 -0
- package/scripts/instrument-check-prose.test.mjs +235 -0
- package/scripts/instruments.sh +394 -0
- package/scripts/instruments.test.mjs +787 -0
- package/scripts/issue-tracker-prose.test.mjs +71 -0
- package/scripts/json.sh +248 -0
- package/scripts/json.test.mjs +364 -0
- package/scripts/ledger-dispatch.test.mjs +516 -0
- package/scripts/ledger-grammar.mjs +85 -0
- package/scripts/ledger-grammar.test.mjs +142 -0
- package/scripts/ledger-read-require-file.test.mjs +197 -0
- package/scripts/ledger.mjs +1753 -0
- package/scripts/ledger.test.mjs +3554 -0
- package/scripts/line-distance-prose.test.mjs +245 -0
- package/scripts/liveness-rationale-prose.test.mjs +83 -0
- package/scripts/locale-pin-prose.test.mjs +189 -0
- package/scripts/member-outcome-prose.test.mjs +167 -0
- package/scripts/member-outcomes-header.test.mjs +148 -0
- package/scripts/member-outcomes-prose.test.mjs +63 -0
- package/scripts/member-outcomes.mjs +231 -0
- package/scripts/member-outcomes.test.mjs +507 -0
- package/scripts/member-prompt-prose.test.mjs +161 -0
- package/scripts/member-record.mjs +605 -0
- package/scripts/member-record.test.mjs +516 -0
- package/scripts/member-write-guard.mjs +279 -0
- package/scripts/member-write-guard.test.mjs +211 -0
- package/scripts/merge-commit-probe-prose.test.mjs +122 -0
- package/scripts/merge-gate.mjs +262 -0
- package/scripts/merge-gate.test.mjs +613 -0
- package/scripts/muted-git-guard-sweep.test.mjs +493 -0
- package/scripts/net-ssh-precedence-prose.test.mjs +91 -0
- package/scripts/net-watchdog-prose.test.mjs +79 -0
- package/scripts/net.sh +409 -0
- package/scripts/net.test.mjs +211 -0
- package/scripts/no-ci-gate-prose.test.mjs +108 -0
- package/scripts/no-undo-audit.sh +1134 -0
- package/scripts/no-undo-audit.test.mjs +3965 -0
- package/scripts/no-wave.test.mjs +138 -0
- package/scripts/node-floor-sweep.test.mjs +611 -0
- package/scripts/pointer-target-prose.test.mjs +186 -0
- package/scripts/pr-overlap.mjs +417 -0
- package/scripts/pr-overlap.test.mjs +695 -0
- package/scripts/printf-die-sweep.test.mjs +384 -0
- package/scripts/prompt-renderer.mjs +39 -0
- package/scripts/prompt-renderer.test.mjs +68 -0
- package/scripts/prose-pin.mjs +808 -0
- package/scripts/prose-pin.test.mjs +1034 -0
- package/scripts/prove-merge.sh +228 -0
- package/scripts/prove-merge.test.mjs +995 -0
- package/scripts/pull-table-relabel-prose.test.mjs +60 -0
- package/scripts/quiet-payload-prose.test.mjs +222 -0
- package/scripts/reap.sh +1768 -0
- package/scripts/reap.test.mjs +4395 -0
- package/scripts/reaping-prose.test.mjs +159 -0
- package/scripts/refuter-scratch-prose.test.mjs +135 -0
- package/scripts/release-label-required-prose.test.mjs +71 -0
- package/scripts/release-label-split-prose.test.mjs +169 -0
- package/scripts/release-ticket.sh +1716 -0
- package/scripts/release-ticket.test.mjs +5106 -0
- package/scripts/renovate-release-contract.test.mjs +379 -0
- package/scripts/repo-root.mjs +544 -0
- package/scripts/repo-root.test.mjs +873 -0
- package/scripts/reporter-output-rule-prose.test.mjs +208 -0
- package/scripts/review-agent-report-only.test.mjs +49 -0
- package/scripts/review-core-cwd-isolation.test.mjs +374 -0
- package/scripts/review-core-reads.test.mjs +478 -0
- package/scripts/review-core-refuter-scratch.test.mjs +148 -0
- package/scripts/review-core-snapshot-path.test.mjs +777 -0
- package/scripts/review-core-specialist-scratch.test.mjs +189 -0
- package/scripts/review-core-testcmd.test.mjs +288 -0
- package/scripts/review-core-unrun.test.mjs +530 -0
- package/scripts/review-core-unverified-discriminant.test.mjs +208 -0
- package/scripts/review-core.mjs +1028 -0
- package/scripts/review-eval-resolver-path.test.mjs +55 -0
- package/scripts/review-eval.mjs +197 -0
- package/scripts/review-host-fixture.mjs +73 -0
- package/scripts/review-in-run-retry.test.mjs +187 -0
- package/scripts/review-no-vendor-dispatch.test.mjs +45 -0
- package/scripts/review-path-default.test.mjs +796 -0
- package/scripts/review-runner-spawns.test.mjs +93 -0
- package/scripts/review-runner.test.mjs +155 -0
- package/scripts/review-tier-audit.test.mjs +140 -0
- package/scripts/run-artifact-pr-prose.test.mjs +341 -0
- package/scripts/run-merge-bot-prose.test.mjs +1391 -0
- package/scripts/scratch-partition-invariant-prose.test.mjs +74 -0
- package/scripts/scripts-path-citation-sweep.test.mjs +73 -0
- package/scripts/section-between-guard-prose.test.mjs +378 -0
- package/scripts/select-dimensions.test.mjs +674 -0
- package/scripts/shared-refusal.test.mjs +388 -0
- package/scripts/shell-traps-prose.test.mjs +507 -0
- package/scripts/shortlist.mjs +355 -0
- package/scripts/shortlist.test.mjs +366 -0
- package/scripts/slow-transport.mjs +72 -0
- package/scripts/snapshot-repo.test.mjs +772 -0
- package/scripts/snapshot-runner-audience-prose.test.mjs +129 -0
- package/scripts/spend-view.test.mjs +312 -0
- package/scripts/staleness-qualifier-prose.test.mjs +251 -0
- package/scripts/staleness-verdict-prose.test.mjs +142 -0
- package/scripts/staleness.mjs +414 -0
- package/scripts/staleness.test.mjs +893 -0
- package/scripts/stalled-member-liveness-prose.test.mjs +219 -0
- package/scripts/stash-prohibition-prose.test.mjs +313 -0
- package/scripts/strip-comments.mjs +44 -0
- package/scripts/tier-check.mjs +468 -0
- package/scripts/tier-check.test.mjs +726 -0
- package/scripts/tier-guard-gate-prose.test.mjs +216 -0
- package/scripts/tier-outcomes-header.test.mjs +586 -0
- package/scripts/tier-outcomes.mjs +441 -0
- package/scripts/tier-outcomes.test.mjs +342 -0
- package/scripts/tier-roles.mjs +250 -0
- package/scripts/tier-roles.test.mjs +316 -0
- package/scripts/tracker-block-copy-prose.test.mjs +288 -0
- package/scripts/triage-labels-gloss-prose.test.mjs +97 -0
- package/scripts/unattended-git-sweep.test.mjs +142 -0
- package/scripts/verify-sha-exit2-prose.test.mjs +269 -0
- package/scripts/verify-sha.sh +117 -0
- package/scripts/verify-sha.test.mjs +693 -0
- package/scripts/watcher-degraded-block.test.mjs +372 -0
- package/scripts/watcher-key-prose.test.mjs +106 -0
- package/scripts/within-run-pair-prose.test.mjs +208 -0
- package/scripts/worktree-audit.sh +482 -0
- package/scripts/worktree-audit.test.mjs +1407 -0
- package/scripts/worktree-head-prose.test.mjs +276 -0
- package/scripts/worktree-listing-sweep.test.mjs +217 -0
- package/scripts/worktree-model-prose.test.mjs +216 -0
- package/scripts/worktree.sh +470 -0
- package/skills/next-ticket/SKILL.md +138 -0
- package/skills/run-team/SKILL.md +3603 -0
- package/skills/run-team/references/ci-and-staleness.md +75 -0
- package/skills/run-team/references/correction-tickets.md +37 -0
- package/skills/run-team/references/isolation.md +23 -0
- package/skills/run-team/references/member-lifecycle.md +73 -0
- package/skills/run-team/references/reaping.md +73 -0
- package/skills/sizing-a-ticket/SKILL.md +39 -0
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: review a PR, apply recommended actions, push, watch checks until green
|
|
3
|
+
argument-hint: [pr-number]
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
1. Run the review yourself. **Dispatched as a fix-applier, skip this step**: the review already ran, and its result came with your prompt — see **The review result file**, which also holds the rulings on it that are yours to make. Re-running it re-reviews a PR nobody asked you to review. Otherwise — no `eval` access at your level — hand-dispatch the six `fleet-review-*` specialists yourself, by name:
|
|
7
|
+
|
|
8
|
+
`fleet-review-<key>` (e.g. `fleet-review-correctness`).
|
|
9
|
+
|
|
10
|
+
See **Specialists** — those constraints are not optional.
|
|
11
|
+
2. Plan the actions. Split explicitly into **apply now** / **defer**. A finding is deferred, never dropped. **Every `suggestion` — the review's `severity`, the plugin's *Suggestions* bucket — arrives unchecked: the review budgets that band 0 refuters, so nothing has looked at it yet.** Checking it is now your job, not nobody's. So split it by SCOPE first. Out of the PR's ticket scope → defer and file. In scope → dispatch one refuter against it, biased to refuse, and hand it this instruction verbatim with one substitution: resolve `<scratch>/pr<N>/<finding>/` in it to an absolute path under your own run root — `mktemp -d` once per round for `<scratch>/pr<N>/fix-XXXXXXXX/`, never bare `pr<N>`, since finding ids restart at 1 each round too — and write that absolute path into the refuter's prompt in its place; a refuter never derives its own path: *Try to REFUTE this finding. Default to refuted=true if uncertain. Verify by RUNNING something — compile it, run the test, apply the mutation. Do not reason your way to agreement. Observe that run synchronously — run the command, wait for it, read its exit code. Never poll a log file for a completion marker: prefer ONE blocking run to a poll loop, and treat its return as permission to look, never as the answer. Reading a log the run has already finished writing is fine; waiting on one is not. If you match a test reporter's own output, accepting both `ℹ` and `#` is necessary but NOT sufficient — strip SGR escapes first as well. node's prefix moves with the node version and with whether stdout is a TTY, and color wraps the whole line so it begins with ESC and no prefix anchor matches at all, which returns empty at exit 0 — indistinguishable from a hung run and from a run of zero tests. For an uncolored baseline use `env -u FORCE_COLOR`; `FORCE_COLOR=` empty still enables color, so it is not a control. State your search scope AND what your pattern would have missed. A grep over one ref does not support a claim about history; a pattern built from the token a diff removed does not support a claim that the category is empty. A failure injection with no positive control has produced NO result, never a negative one. Before you read an injected fault — an env var, an argv word, a mutant — as having had no effect, prove the injection reached the child: one run whose output differs with it present versus absent, or the child echoing the injected value back. Uncontrolled, the cell is unrun — say so in your verdict instead of reporting a no-effect result. Build such an invocation as an array expanded braced and quoted — `cfg=(SETB=1 BADJ=1); env "${cfg[@]}" sh ./probe.sh` — or inline the assignments literally — `env SETB=1 BADJ=1 sh ./probe.sh`; NEVER from an unquoted scalar — `cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh` — which under zsh passes ONE argument, sets a variable literally named `SETB` to `1 BADJ=1`, never sets `BADJ` at all, and still exits 0. `env $cfg[@]` is not the portable spelling either: measured, bash word-splits it into `SETB=1` and `BADJ=1[@]`, so the injection variable is set to a corrupted value, while zsh behaves exactly as with the bare `$cfg` — `BADJ` never set, exit 0. Everything you write — mutants, fixtures, scratch repos — goes under `<scratch>/pr<N>/<finding>/` and nowhere else; the checkout and any worktree are never write targets, though `git show`/`git archive` at a pinned ref read fine anywhere. Chain the directory change into the command, `cd "$D" && git …`, never `cd "$D"; git …`, so a failed `cd` cannot leave a `git` command running in the checkout — and bracket a fixture's own git with `git rev-parse --show-toplevel`: before `git init` it must NOT resolve to the repository, and a fresh scratch dir's `fatal: not a git repository` (exit 128) is the pass, not a failure; before any `git commit` it must resolve to your scratch path — compare resolved forms (`realpath`), since `--show-toplevel` can report `/private/tmp/…` for a `/tmp` scratch dir on macOS.* That last clause is the whole mechanism — a refuter left to reason its way to agreement rubber-stamps, and "apply only what survives" silently degrades into "apply everything in scope". Apply only what survives; a refuted one defers with the refutation in its body. "In scope" means the ticket's scope, not merely the same files — and applying one still never licenses editing a file the ticket has no business in. **A finding in `unverified` whose refuters ran and crashed always defers, whatever its severity** — and which of the two it is, you read off the finding's **`refutersDispatched`**, never off severity and never off an empty vote list: above zero with nothing surviving means every refuter dispatched against it died, and at `critical` that is every one of them. Only a `survived` finding has been checked; severity says how much a finding would matter if true, never whether anything looked. **Deferring a crash is your move, and re-running it is not** — the review already re-dispatched every crashed refuter pair once, in-run, so a crash that reaches you crashed twice, and the result's `resume` field names the one move left, which is not yours: nothing replays a review that ran in a runner's kernel — it is reported, not acted on. So say *in the deferral* that its refuters crashed rather than that it went unchecked, and re-run nothing for it. **A `suggestion` is also in `unverified`, for a different reason — `refutersDispatched` of zero, the 0-refuter budget the workflow gives that band by policy, so nothing looked *there* — and the scope split above, not this rule, covers it.**
|
|
12
|
+
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** — here `node --test plugin/scripts/*.test.mjs` — the same *effective* command `review-core.mjs` now derives for this repo rather than defaulting to (#142), the wording line 47 already uses: the derivation returns the bare string `node --test`, and every test file in this repo lives under `plugin/scripts/`, so the two cover the same suite today. Not the same string, and node's recursive default discovery widens the moment a test file lands anywhere else. 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. `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.
|
|
13
|
+
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.
|
|
14
|
+
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.
|
|
15
|
+
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) → `gh pr edit <pr> --add-label ready-to-merge`. Do not merge. Zero or more than one 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`, 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.
|
|
16
|
+
|
|
17
|
+
**`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.
|
|
18
|
+
|
|
19
|
+
**Bind green to the *run*, not to check conclusions.** `gh pr checks` aggregates across runs and reports a `pass` inherited from a **cancelled** run on a superseded SHA. Head-SHA binding misses it — the head is genuinely right; only the conclusions belong to another commit.
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
~/.fleet/bin/fleet-run ci-state.mjs --pr <n>
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
`ci-state.mjs` does the whole run-binding check and prints a `verdict` with reasons: it binds the run to the PR head, requires run `status` **completed** and **every expected job present** (the list derived from the workflow file, discovered by its `name:` under `.github/workflows/`, resolved from the repo root so the answer does not depend on your cwd — no `--workflow-file` needed unless two files share that name, or none carries it, both of which exit 2 saying so), and treats `skipped` as not-green. Exit 0 only when genuinely green. Its job-presence check is what catches the case above: a force-push cancels the run under you, its finished jobs keep the conclusions they already reached, while the jobs that never ran are absent rather than red — and an absent job reads as `pending` in an aggregating checks summary, never here: `ci-state.mjs` names it in the reason `expected jobs absent from the run: …` and refuses green.
|
|
26
|
+
|
|
27
|
+
**A repo with no workflow files at all is `verdict: "no-ci"`, never a silent pass.** That is a distinct state from "could not answer" (which still exits 2 — an unreadable or malformed workflow, an unreadable `.github/workflows/`, workflow files present under other names, or no repo root to resolve) and from `not-green` (a run that actually failed). Only genuine absence is `no-ci`; every failure to *read* is exit 2, so a misconfigured repo can never borrow the declarable verdict. Absence never means pass: without `--declare-no-ci`, `ci-state.mjs` exits 1 even though it isn't red — there is simply nothing to be green. Pass `--declare-no-ci` only once you've verified this repo's gate really is the reviewer's own `testCmd` run from step 3, and it exits 0 on that same `no-ci` verdict. Step 6 reads this same flag/verdict pair; don't invent a different check.
|
|
28
|
+
|
|
29
|
+
**Query at labelling time; never label off a watcher's summary.** A monitor stitches its event from reads taken at different moments, so it can stream `RUN COMPLETE: success` under a run id whose authoritative job list is a failure — observed: streamed all-five-green for run `165158547`, while `gh run view 165158547 --json jobs` reported `rebase-check failure` with three jobs **skipped**; the green belonged to the previous run on an earlier head. Head-SHA binding does not catch this, because the *run id* is wrong rather than the head. Watchers are for waking you up, never for deciding.
|
|
30
|
+
|
|
31
|
+
**A conclusion is not stable even for a fixed run id on an unchanged head.** A rerun rewrites the existing run in place instead of creating a new one, so a run you read as `success` can later read `failure` with nothing pushed. Observed twice in one run, on two PRs: a refresh workflow re-ran the currency check after `main` advanced and flipped the same id on the same SHA. So a cached conclusion is not merely stale, it can be *inverted* — re-query at the moment you decide. Also note the newest run on a branch is often a label or policy workflow rather than CI, so `--limit 1` can hide the CI result entirely.
|
|
32
|
+
|
|
33
|
+
**`skipped` is not `passed`**. When the currency check fails, the heavy jobs report `skipped` — they did **not** execute. A board of `check: success` / currency `failure` / three `skipped` reads as "nearly green" and is in fact *three required suites unverified*. That is not grounds to withhold the label (see below), but if you label under it, say the label rests on the checks that actually ran plus your own verification — never call it "CI green".
|
|
34
|
+
|
|
35
|
+
**Do NOT rebase to label**, and do not require a zero behind-count. Your green proves the diff is sound *against the base it was tested on* — that is what the label attests, and it does not expire. Requiring currency forces a full CI cycle every time any sibling lands (six wasted cycles in one run) and re-establishes nothing the merge bot will not. Rebase only when pushing a change, or when the bot bounces it back.
|
|
36
|
+
|
|
37
|
+
Three claims, none substituting for another: **run-binding** (this green belongs to this SHA) · **your green** (correct against its base) · **the bot's post-rebase green** (still correct against current `main`). Only the third catches a sibling renaming a symbol you use — a rebase can apply cleanly and still break the build, which is why it is the bot's job and not yours.
|
|
38
|
+
|
|
39
|
+
## The review result file
|
|
40
|
+
|
|
41
|
+
**Dispatched as a fix-applier, you read the review off one file: `<scratch>/review-<pr>.json`, the path your prompt names.** It holds the bare result object the review returned, in this key order — the digest `pr`, `head`, `resume`, `testEnvironment`, `dimensionsRun`, `dimensionsUnrun`, `cwdAudit`, `counts`, then `snapshot`, `survived`, `refuted`, `unverified` — the `review-pr-<pr#>` runner member (`agents/fleet-review-runner.agent.md`) writes it. The controller reads the digest and never the findings, so **every per-PR ruling in this section is yours** — nobody upstream has made one for you. A prompt that pastes the findings in instead of naming the file hands you the same buckets, and every ruling here applies to them unchanged. Read the file a bucket at a time with `jq`, never whole into your context — a review's result runs to tens of KB:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
R=<scratch>/review-<pr>.json
|
|
45
|
+
jq '{pr, head, resume, testEnvironment, dimensionsRun, dimensionsUnrun, cwdAudit, counts}' "$R" # the digest
|
|
46
|
+
jq -r '.testEnvironment' "$R" # what every test_run is evidence about
|
|
47
|
+
jq '.survived' "$R" # apply candidates, every one
|
|
48
|
+
jq '[.unverified[] | select(.refutersDispatched > 0)]' "$R" # refuters crashed, twice: defer, naming the crash
|
|
49
|
+
jq '[.unverified[] | select(.refutersDispatched == 0)]' "$R" # suggestions, 0-refuter budget: step 2's scope split
|
|
50
|
+
jq '.refuted' "$R" # refuted: yours to reverse on new evidence
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
**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 report names each `refuted` one you reversed, with the evidence, so the controller can copy it to the ledger's `ruled` line.
|
|
54
|
+
|
|
55
|
+
**Read `testEnvironment` and `cwdAudit` before you act on any `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
|
+
|
|
57
|
+
**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
|
+
|
|
59
|
+
**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
|
+
|
|
61
|
+
**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
|
+
|
|
63
|
+
**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
|
+
|
|
65
|
+
## Specialists
|
|
66
|
+
|
|
67
|
+
**The controller runs the review; everything below is the fallback for when it cannot.**
|
|
68
|
+
|
|
69
|
+
`eval` loading `scripts/review-eval.mjs` through the Resolver (`fleet-run --path review-eval.mjs`) and calling `runReviewOnOmp({pr, branch, worktree, testCmd, scratch})` is the fleet's **default** review path.
|
|
70
|
+
|
|
71
|
+
`$(~/.fleet/bin/fleet-run --root)/skills/run-team/SKILL.md`'s Reviewers section owns its dispatch. It cuts the snapshot, sizes the fan-out, adversarially verifies every **critical/important** finding, and has `agent()` return **into the script**, so no report can go undelivered, the failure that cost one fleet five reports on one PR and four on another. It does **not** verify the `suggestion` band — that gets 0 refuters by policy, which is why step 2 checks each in-scope one itself before applying it, and files the rest. **You cannot run it** — the one member that runs it is the `review-pr-<pr#>` runner (`agents/fleet-review-runner.agent.md`), never a reader of this file; this section is the fallback for a member dispatched without it, the `review-pr-<pr#>-b` reviewer the controller sends after a review failed twice included.
|
|
72
|
+
|
|
73
|
+
It cannot ask the user anything and cannot wait on CI — rebasing, watching checks, binding and labelling stay here.
|
|
74
|
+
|
|
75
|
+
- **A depth-2 member cannot dispatch** (`task.maxRecursionDepth: 2`): if `task` is absent at your depth, ask the controller to dispatch the specialists and relay their reports; never downgrade to a solo review.
|
|
76
|
+
- **Say read-only.** No `fleet-review-*` definition's frontmatter restricts tool access — a `.agent.md` prompt saying "report only" is instruction, not enforcement — so an agent hand-dispatched here, named or general-purpose, has write tools it must not use: one committed and pushed during a report-only dispatch. No commits, no pushes, no worktree edits.
|
|
77
|
+
- **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*.
|
|
78
|
+
- **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.
|
|
79
|
+
- **`git archive` carries tracked files only.** No `node_modules`, no gitignored runner or config. Provision in the same step — symlink `node_modules`, 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.
|
|
80
|
+
- **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
|
+
- **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. **That war story is from another repo, and the config-swap escape it calls for does not exist here** — `feigi/claude-config` has no compose file, no `globalSetup`, and no vitest, so there is no `vitest.ci.config.ts` to point anyone at. (It does now have CI — `.github/workflows/ci.yml` — but that runs `node --test`, not a stack.) Naming one sends every specialist into `Cannot find module`, which reads as a broken tree rather than a bad instruction. In *this* repo the collision is inert for a different reason: the `export TEST_COMPOSE_PROJECT=…` line `claim-ticket.sh` writes into the runner sets `TEST_COMPOSE_PROJECT`/`TEST_POSTGRES_PORT`/`TEST_OLLAMA_PORT` and **nothing reads them** — the suite is `node --test` throughout. So tell specialists `node --test plugin/scripts/*.test.mjs` directly, glob form — `review-core.mjs` derives the same effective command for this repo now rather than defaulting to it (#142), keeping this bullet's manual command in agreement with it — and keep `./agent-test` for your own verification. **Hand that command with its reading rule: `tests 0` is a failed run, not a pass.** A glob is not self-checking. Where it matches nothing, bash passes the pattern through literally, node globs it itself and finds no files, and you get `ℹ tests 0` / exit 0 — a green having run nothing. Read the count under either reporter: `node --test` prints `ℹ tests 0` to a terminal 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. Node v26.5.0 has no flag that fails a zero-test run. **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: in a repo that *does* have a stack, N concurrent specialists sharing one runner still collide, and the escape is whatever that repo's stack-free config is.
|
|
82
|
+
- **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.
|
|
83
|
+
- **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.
|
|
84
|
+
|
|
85
|
+
Tell readers **`git show <sha>:<path>` is the source of truth** — the object store cannot be contaminated by any agent, needs no copy, and touches nothing. Make it the default for settling *what the PR contains*, not a fallback. A finding that disagrees with it is a probe artifact. **Then bound the read — the guarantee is the blob, not the byte count.** `git show <sha>:<path> | sed -n 'A,Bp'` reads the same uncontaminatable object; take the file whole only once `| wc -l` says it is small — a count, not a feeling. Where the *change* is what you are settling, diff instead of reading: `git diff <base>...<head> -- <path>` for the PR's whole change, `git show <sha> -- <path>` only for one named commit's. That second form is scoped to that single commit and prints **nothing, at exit 0**, when the commit did not touch the path (measured) — the same silent green as `tests 0`, and it reads as "the PR changed nothing here". The cost of not bounding is never one-off: a specialist that dumps a 37 KB file carries it in its prefix for every remaining turn, re-billed as cache-read on each. Over one run's 92 subagents the 88 unpiped whole-file calls carried 434 KB (~110k tokens) — the single largest attributed line item in that run — against 319 piped ones. Agents already reach for the bounded form; nothing told them when it is required.
|
|
86
|
+
|
|
87
|
+
**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`.
|
|
88
|
+
|
|
89
|
+
**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
|
+
|
|
91
|
+
**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.
|
|
92
|
+
|
|
93
|
+
## Judging findings
|
|
94
|
+
|
|
95
|
+
- **Verify, don't reason.** "Removing X makes this compile/fail" → compile it in an isolated copy. One command. Four successive confident claims about one file were all wrong; the compiler settled it.
|
|
96
|
+
- **Distrust negative claims hardest.** "Nothing else references this", "the sweep is clean" — most likely false, least likely checked: a grep that found nothing looks like a grep never run. Make the specialist state its search scope. Negative claim vs specific finding with paths → paths win.
|
|
97
|
+
- **Mutation-verify any "this test pins X".** Apply the mutation, confirm *that* test fails, revert. Then one it should **not** catch, staying green — else you proved it fails, not that it discriminates. **One syntactic form is not the class:** a stripper killing `// whole-line` passed a guard that `code; // trailing` walked through.
|
|
98
|
+
- **Comments are findings**, and the most common one. A comment asserting what the code does not do is a defect. One run shipped five: an invented citation, a mis-stated failure mode, a test file named as covering what it had zero coverage of, an overstated cast fix, a claim its own dependency's source contradicts. Check every added assertion against the tree — **including comments in files this diff does not touch** but whose claims it falsifies (test-name references, "N of 3" counts, tracking-issue pointers).
|