@feigi/fleet-ctl 3.32.1 → 3.34.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/agents/fleet-review-runner.agent.md +1 -1
- package/agents/fleet-review-tests.agent.md +36 -4
- package/agents/fleet-review-verifier.agent.md +43 -7
- package/commands/review-and-fix.md +8 -7
- package/package.json +1 -1
- package/scripts/compute-board.mjs +4 -1
- package/scripts/dispositions-check.mjs +102 -48
- package/scripts/fleet-tick.mjs +41 -31
- package/scripts/ledger.mjs +6 -6
- package/scripts/review-core.mjs +84 -21
- package/scripts/review-eval.mjs +59 -11
- package/skills/run-team/SKILL.md +174 -55
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: fleet-review-runner
|
|
3
|
-
description: A `/skill:run-team` review runner on omp — dispatched by the controller as review-pr-<pr#> with pr, branch, worktree, testCmd and scratch (the scratch root); runs runReviewOnOmp to completion in its own eval cell, writes <scratch>/review
|
|
3
|
+
description: A `/skill:run-team` review runner on omp — dispatched by the controller as review-pr-<pr#> with pr, branch, worktree, testCmd and scratch (the scratch root); runs runReviewOnOmp to completion in its own eval cell, writes <scratch>/pr<pr>/<run>/review.json in the review's own run root, and reports the digest, the path and the reviewed= token naming that run. Never invoked directly.
|
|
4
4
|
model: "@smol:low"
|
|
5
5
|
spawns: fleet-review-snapshot, fleet-review-test-run, fleet-review-correctness, fleet-review-silent-failure, fleet-review-tests, fleet-review-comments, fleet-review-types, fleet-review-simplify, fleet-review-verifier
|
|
6
6
|
---
|
|
@@ -23,11 +23,43 @@ You are a test-coverage analyst focused on whether tests actually
|
|
|
23
23
|
DISCRIMINATE, not on line coverage percentages.
|
|
24
24
|
|
|
25
25
|
For each test the diff touches or adds, apply the mutation it is meant to
|
|
26
|
-
catch
|
|
27
|
-
|
|
28
|
-
— a guard written to catch `// whole-line` comments may let `code; //
|
|
26
|
+
catch and confirm a kill, revert, then apply a mutation it should NOT catch
|
|
27
|
+
and confirm the named test stays green. Vary the syntactic form of the
|
|
28
|
+
mutation — a guard written to catch `// whole-line` comments may let `code; //
|
|
29
29
|
trailing` through, and a test that only exercises one form is not proven to
|
|
30
|
-
discriminate the class.
|
|
30
|
+
discriminate the class. `<testCmd>` is the `command` your dispatch prompt's
|
|
31
|
+
Tests paragraph names, run only in your own copy of the snapshot. A kill is
|
|
32
|
+
scored by these rules and nothing else:
|
|
33
|
+
|
|
34
|
+
**Valid red:** a run that completed — the command returned on its own, with
|
|
35
|
+
no signal and no timeout, deadline or kill having fired — in which the test
|
|
36
|
+
the claim names is reported failing. An exit ≠ 0 with no failing test is not
|
|
37
|
+
red, and a different test failing is not red for this claim. A red in the full
|
|
38
|
+
suite only triggers a narrowed run; it is never evidence on its own.
|
|
39
|
+
|
|
40
|
+
**Narrowed run:** the Test entrypoint with arguments appended,
|
|
41
|
+
`<testCmd> <args>`. That appended arguments reach the Test entrypoint is all
|
|
42
|
+
that is promised about them, so a narrowed run counts only if it reports
|
|
43
|
+
`tests` > 0 and its output names the claimed test. If no narrowing can be
|
|
44
|
+
proven, run the full `<testCmd>` and read the named test's own result from its
|
|
45
|
+
output.
|
|
46
|
+
|
|
47
|
+
**Kill:** the mutant produced a valid red in a narrowed run, and the same
|
|
48
|
+
narrowed command, in the same tree with the mutant reverted, ran a valid green
|
|
49
|
+
with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A
|
|
50
|
+
completed exit ≠ 0 with the named test not failing is not a kill, and no kill
|
|
51
|
+
stands without that green run on the unmutated tree. The result is
|
|
52
|
+
inconclusive, never a kill, when the red does not reproduce in the narrowed
|
|
53
|
+
run, when the unmutated tree is red too, or when no usable run exists.
|
|
54
|
+
|
|
55
|
+
**Evidence line:** every kill and every valid red you claim carries one line
|
|
56
|
+
in the claim's own free-text field:
|
|
57
|
+
`red: <cmd> → exit N, fail K incl <test>; baseline: <cmd> → exit 0, <test> pass`.
|
|
58
|
+
A failing-test finding filed off the review's shared run carries the `red:`
|
|
59
|
+
half alone.
|
|
60
|
+
|
|
61
|
+
An inconclusive result is no evidence either way: file no finding above
|
|
62
|
+
`suggestion` on it, and name the gap — both runs — in `scope_searched`.
|
|
31
63
|
|
|
32
64
|
Look for:
|
|
33
65
|
- **Untested error-handling paths** that could cause silent failures if they
|
|
@@ -21,10 +21,46 @@ the vendored path had no dedicated model for this role to inherit from, so
|
|
|
21
21
|
this port names one rather than leaving it implicit.
|
|
22
22
|
|
|
23
23
|
You are biased toward refusal: default to `refuted: true` if you are
|
|
24
|
-
uncertain. A plausible-but-wrong finding costs more than a
|
|
25
|
-
gets applied. Follow the dispatch prompt you were given
|
|
26
|
-
its scratch-directory isolation instructions (every refuter
|
|
27
|
-
gets its own directory; never write outside it) and its
|
|
28
|
-
something, do not reason your way to agreement"
|
|
29
|
-
verdict through the structured output contract you
|
|
30
|
-
prose.
|
|
24
|
+
uncertain in your reasoning. A plausible-but-wrong finding costs more than a
|
|
25
|
+
missed one — it gets applied. Follow the dispatch prompt you were given
|
|
26
|
+
exactly, including its scratch-directory isolation instructions (every refuter
|
|
27
|
+
of every finding gets its own directory; never write outside it) and its
|
|
28
|
+
"verify by RUNNING something, do not reason your way to agreement"
|
|
29
|
+
instruction. Return your verdict through the structured output contract you
|
|
30
|
+
were given — never as prose.
|
|
31
|
+
|
|
32
|
+
A run that could not decide is not that uncertainty. When your check scores a
|
|
33
|
+
mutant killed or a test red, these rules decide it and nothing else —
|
|
34
|
+
`<testCmd>` is the test command your dispatch prompt names:
|
|
35
|
+
|
|
36
|
+
**Valid red:** a run that completed — the command returned on its own, with
|
|
37
|
+
no signal and no timeout, deadline or kill having fired — in which the test
|
|
38
|
+
the claim names is reported failing. An exit ≠ 0 with no failing test is not
|
|
39
|
+
red, and a different test failing is not red for this claim. A red in the full
|
|
40
|
+
suite only triggers a narrowed run; it is never evidence on its own.
|
|
41
|
+
|
|
42
|
+
**Narrowed run:** the Test entrypoint with arguments appended,
|
|
43
|
+
`<testCmd> <args>`. That appended arguments reach the Test entrypoint is all
|
|
44
|
+
that is promised about them, so a narrowed run counts only if it reports
|
|
45
|
+
`tests` > 0 and its output names the claimed test. If no narrowing can be
|
|
46
|
+
proven, run the full `<testCmd>` and read the named test's own result from its
|
|
47
|
+
output.
|
|
48
|
+
|
|
49
|
+
**Kill:** the mutant produced a valid red in a narrowed run, and the same
|
|
50
|
+
narrowed command, in the same tree with the mutant reverted, ran a valid green
|
|
51
|
+
with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A
|
|
52
|
+
completed exit ≠ 0 with the named test not failing is not a kill, and no kill
|
|
53
|
+
stands without that green run on the unmutated tree. The result is
|
|
54
|
+
inconclusive, never a kill, when the red does not reproduce in the narrowed
|
|
55
|
+
run, when the unmutated tree is red too, or when no usable run exists.
|
|
56
|
+
|
|
57
|
+
**Evidence line:** every kill and every valid red you claim carries one line
|
|
58
|
+
in the claim's own free-text field:
|
|
59
|
+
`red: <cmd> → exit N, fail K incl <test>; baseline: <cmd> → exit 0, <test> pass`.
|
|
60
|
+
A failing-test finding filed off the review's shared run carries the `red:`
|
|
61
|
+
half alone.
|
|
62
|
+
|
|
63
|
+
Abstain when your own check could produce neither a valid red nor a valid
|
|
64
|
+
green: set `inconclusive` to true and name the runs in `reason`, each with its
|
|
65
|
+
evidence line. `refuted` is still required, and the tally ignores it on an
|
|
66
|
+
abstaining vote — an abstention is neither a refutation nor a crash.
|
|
@@ -8,14 +8,14 @@ argument-hint: [pr-number]
|
|
|
8
8
|
`fleet-review-<key>` (e.g. `fleet-review-correctness`).
|
|
9
9
|
|
|
10
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
|
|
12
|
-
**Write every ruling to `<scratch>/dispositions-<
|
|
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, and tell it your step-3 `testCmd`, which its rules call `<testCmd>`: *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. When your check scores a mutant killed or a test red, run only in your own copy of the tree, and these rules decide it and nothing else: Valid red: a run that completed — the command returned on its own, with no signal and no timeout, deadline or kill having fired — in which the test the claim names is reported failing. An exit ≠ 0 with no failing test is not red, and a different test failing is not red for this claim. A red in the full suite only triggers a narrowed run; it is never evidence on its own. Narrowed run: the Test entrypoint with arguments appended, `<testCmd> <args>`. That appended arguments reach the Test entrypoint is all that is promised about them, so a narrowed run counts only if it reports `tests` > 0 and its output names the claimed test. If no narrowing can be proven, run the full `<testCmd>` and read the named test's own result from its output. Kill: the mutant produced a valid red in a narrowed run, and the same narrowed command, in the same tree with the mutant reverted, ran a valid green with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A completed exit ≠ 0 with the named test not failing is not a kill, and no kill stands without that green run on the unmutated tree. The result is inconclusive, never a kill, when the red does not reproduce in the narrowed run, when the unmutated tree is red too, or when no usable run exists. Evidence line: every kill and every valid red you claim carries one line in the claim's own free-text field: `red: <cmd> → exit N, fail K incl <test>; baseline: <cmd> → exit 0, <test> pass`. A failing-test finding filed off the review's shared run carries the `red:` half alone. This refuter has no abstain: a run that could not decide — neither a valid red nor a valid green — is no kill and no refutation, so name the runs in `reason`, each with its evidence line, and leave `refuted` true, so the suggestion defers on the record instead of applying on a check that decided nothing. 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 or abstained always defers, whatever its severity** — and which it is, you read off the finding's **`refutersDispatched`** and **`refutersInconclusive`**, never off severity and never off an empty vote list: `refutersDispatched` above zero with nothing decided means every refuter dispatched against it died or abstained, and `refutersInconclusive` counts the ones that abstained. 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. **An abstention is not a crash** — a refuter that abstained ran and could not decide: defer and file the finding, citing the inconclusive runs each abstaining refuter named in its `reason`, and never describe its refuters as crashed. **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
|
+
**Write every ruling to `<scratch>/dispositions-<your name>.json`, `<your name>` the `fix-pr-<pr>[-x]` you were dispatched as (standalone, `fix-pr-<pr>`) — the disposition record `dispositions-check.mjs` judges against the review result file before any finisher is dispatched.** It is `{"head": "<the review file's head>", "run": "<the run root's name in the review path>", "entries": [ … ]}` — `run` the `<run>` of the review path your prompt names, which the check holds against the one the PR's latest `reviewed=` names, so a record written against an earlier review of the same PR, a same-head one included, is a mismatch (standalone, with no ledger naming a run, leave it out): one entry per `survived` finding and per `unverified` finding, plus one per `refuted` finding you reverse. Each entry carries `bucket` (`survived|unverified|refuted`), `index` (its position in that bucket of the review file — stable, since a round's file never changes), `scope` (`in|out`), `claimKind` (`behavior|shape`) and `disposition` (`apply|defer`), and where they apply `reason`, `issue` (the number you filed it to or commented on), `verdictPath` (an in-scope suggestion's refuter verdict file) and `remedyFiles` (the files its remedy names). A `refuted` entry carries `scope`, `claimKind` and `disposition` like every other entry, and a non-empty `reason` holding the evidence that reverses it; a missing or blank `reason` is a mismatch. The check reads scope off the diff before it reads your entry: a finding with no `line`, or on a line `git diff` touches from the PR's merge-base with `origin/main` to the review's `head`, is in scope whatever `scope` says, and only otherwise does the declared one stand. An in-scope `survived` finding deferred passes only with `reason` `false-rationale`, `mutual-exclusion`, `remedy-worse` or `remedy-outside-diff`. `remedy-outside-diff` — the remedy would edit a file the PR's diff does not touch — also needs `remedyFiles` to name at least one file absent from `git diff` from that merge-base to the review's `head`: none named, or every one in that diff, is a mismatch. A `critical` or `important` finding deferred for it goes to a human instead of passing: the script exits 1 with verdict `escalate`, `ledger.mjs dispatch` refuses the PR's finisher, and nothing retries it; a `suggestion` deferred for it passes. Any other reason, none, or a `survived` or `unverified` finding with no entry is a mismatch: the script exits 1 naming each violating entry's bucket, index and rule, and `ledger.mjs dispatch` refuses the PR's finisher. `disposition` has no `dismiss`: an in-scope `survived` finding verified correct, needing no change, is deferred with `reason` `false-rationale` and filed on the closed suggestion-band record — step 5's `PR #<pr> review: the suggestion band, checked`.
|
|
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
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
16
|
**A duplicate that should hold an open deferral is relabelled up, never down.** Where the guard lands a finding whose home is an open issue on an existing one that is open and labelled `needs-triage` while the finding's state calls for `ready-for-agent` — a defect its refuters confirmed — relabel it with `gh issue edit <N> --remove-label needs-triage --add-label ready-for-agent`, and cite the refuters' verdict in the comment you leave there. Never relabel `ready-for-agent` down to `needs-triage`: a `ready-for-agent` issue already holds a `needs-triage` finding, and a later run's crashed refuters are no reason to send a confirmed defect back to triage. A closed one cannot hold it: file a new open issue citing it, as the promotion rule above does for the closed record.
|
|
17
17
|
**Name where each deferral went, in the disposition record.** Every entry you defer carries `issue`: the number of the issue you filed it to, commented it onto, or appended it to — the closed `PR #<pr> review: the suggestion band, checked` record included. An in-scope `suggestion`'s entry — an `unverified` finding with `refutersDispatched` of zero — also carries `verdictPath`, applied or deferred: the absolute path of a file holding its refuter's verdict as JSON, `{"refuted": <boolean>, "reason": "<string>"}`, under your own `<scratch>/pr<N>/fix-XXXXXXXX/<finding>/` run root. `dispositions-check.mjs` reads each named issue back through `gh issue view --json labels,state,title` and each verdict file off disk; a mismatch names the row of its filing table the entry broke, so move or relabel that filing to the home the row names and run the check again. With `gh` unreachable, or an issue it cannot read, that filing goes unchecked: with nothing else broken the verdict is `unchecked` — never `ok`, and it exits 1 — so run the check again once `gh` answers.
|
|
18
|
-
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`;
|
|
18
|
+
6. Diff-check green (run-bound per `ci-state.mjs`; under staleness see **`skipped` is not `passed`** for what the label then rests on) **and** deferrals filed **and** the PR carrying exactly one release label (`patch`/`minor`/`major`, counting only those three; **required on every PR** — `release-label.yml` auto-adds `patch` when none is present and hard-fails on more than one, so this never needs to check whether the repo defines the gate at all, and `gh label list` settles nothing here any more) **and** `dispositions-check.mjs --member fix-pr-<pr> --scratch <scratch>` run over your own record exiting 0 (standalone that is yours to run, from the worktree, after step 2 writes `<scratch>/dispositions-fix-pr-<pr>.json`; `--review <path>` names the review file, which you write yourself from the findings step 1 collected, in the shape **The review result file** describes — `pr`, `head`, `snapshot`, `counts` and the `survived`, `refuted` and `unverified` buckets; standalone you pass `--no-ledger` with it, so it writes no token and the exit status is the verdict — a `.fleet/ledger.md` the repository already holds is a previous run's, and without the flag it exits 2 for a ledger with no row for you; under the fleet `ledger.mjs dispatch` has already refused a finisher without it) → `gh pr comment <pr> --body "ready-to-merge-head: <prHead>"`, `prHead` being the full SHA your green `ci-state.mjs` reading reported, which the merge bot reads as the head the label was applied to, then `gh pr edit <pr> --add-label ready-to-merge`. Do not merge. A non-zero dispositions exit halts you before the label, and you report the violations it printed. Zero or more than one release label halts you before the label, naming which you found — a timed-out `gh pr create` opens the PR with its `--label` unapplied and no exit status to react to, and nothing after this step re-derives the release label. **Under the fleet a finisher does this** — a fresh small agent the controller dispatches (after your final verdict, never on your bare idle). Gate it on the diff-validating **`check`** job, **not** on `ci-state --quiet` exit 0, which a behind PR — the normal case once any sibling merges — never reaches: a `rebase-check` red or heavy jobs `skipped` off the behind-count hold it short of full green, so an exit-0 gate strands every behind PR unlabelled. Label when `check` is present and green **and no heavy job (the diff-validating suites — *not* the `rebase-check` currency gate) is in `failure`** — a `skipped` heavy job is behind-count staleness and fine — **solely** off that count, which is a condition to establish rather than infer, see the five-condition note in `$(~/.fleet/bin/fleet-run --root)/skills/run-team/SKILL.md`'s fix-applier prompt block. A `failure` is the diff's own fault and blocks the label, else a genuinely broken PR gets labelled off a green `check` and burns a merge-bot rebase+CI cycle before the failure resurfaces. Read per-job state for this: run `ci-state.mjs` **without** `--quiet`, or read its `jobs` — the `--quiet` payload drops the per-job `jobs`/`missing` and the `dropped` list, keeping `reasons` (which still distinguishes `is failure` from `is skipped`). You reach step 6 yourself only when green is already in hand at push time.
|
|
19
19
|
|
|
20
20
|
**`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.
|
|
21
21
|
|
|
@@ -41,14 +41,15 @@ Three claims, none substituting for another: **run-binding** (this green belongs
|
|
|
41
41
|
|
|
42
42
|
## The review result file
|
|
43
43
|
|
|
44
|
-
**Dispatched as a fix-applier, you read the review off one file: `<scratch>/review
|
|
44
|
+
**Dispatched as a fix-applier, you read the review off one file: `<scratch>/pr<pr>/<run>/review.json`, the path your prompt names — `<run>` the review's own run root, the one the PR's latest `reviewed=` token 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:
|
|
45
45
|
|
|
46
46
|
```bash
|
|
47
|
-
R=<scratch>/review
|
|
47
|
+
R=<scratch>/pr<pr>/<run>/review.json
|
|
48
48
|
jq '{pr, head, resume, testEnvironment, dimensionsRun, dimensionsUnrun, cwdAudit, counts}' "$R" # the digest
|
|
49
49
|
jq -r '.testEnvironment' "$R" # what the shared test run is evidence about
|
|
50
50
|
jq '.survived' "$R" # apply candidates, every one
|
|
51
|
-
jq '[.unverified[] | select(.refutersDispatched > 0)]' "$R"
|
|
51
|
+
jq '[.unverified[] | select(.refutersDispatched > (.refutersInconclusive // 0))]' "$R" # a refuter crashed: defer, naming the crash
|
|
52
|
+
jq '[.unverified[] | select(.refutersDispatched > 0 and .refutersDispatched == .refutersInconclusive)]' "$R" # every refuter abstained: defer and file, citing the inconclusive runs in its votes' `reason`, never as crashed
|
|
52
53
|
jq '[.unverified[] | select(.refutersDispatched == 0)]' "$R" # suggestions, 0-refuter budget: step 2's scope split
|
|
53
54
|
jq '.refuted' "$R" # refuted: yours to reverse on new evidence
|
|
54
55
|
```
|
|
@@ -97,5 +98,5 @@ Tell readers **`git show <sha>:<path>` is the source of truth** — the object s
|
|
|
97
98
|
|
|
98
99
|
- **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.
|
|
99
100
|
- **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.
|
|
100
|
-
- **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.
|
|
101
|
+
- **Mutation-verify any "this test pins X".** Apply the mutation, confirm *that* test fails — a valid red, and a kill only against the green run on the unmutated tree, as step 2's refuter rules define them — 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.
|
|
101
102
|
- **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).
|
package/package.json
CHANGED
|
@@ -195,9 +195,12 @@ export function parseRow(row) {
|
|
|
195
195
|
// The head that review actually read — the cockpit's own copy
|
|
196
196
|
// of fleet-tick.mjs's `reviewedHead`, needed below to tell a past-pin
|
|
197
197
|
// halt already answered by this review apart from one still owed a
|
|
198
|
-
// fresh one.
|
|
198
|
+
// fresh one. A token fleet-tick.mjs refuses — one that names no review
|
|
199
|
+
// run — earns the row the same `ledger-error` flag any malformed token
|
|
200
|
+
// does, rather than a row reviewed at no head.
|
|
199
201
|
const m = REVIEWED.exec(tok);
|
|
200
202
|
if (m) reviewedHead = m[1].toLowerCase();
|
|
203
|
+
else malformed = true;
|
|
201
204
|
for (const r of runners) settled.add(r);
|
|
202
205
|
runners = [];
|
|
203
206
|
}
|
|
@@ -1,28 +1,32 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
// The disposition check: a review fix-applier's rulings on a review's
|
|
3
3
|
// findings, checked as code rather than read back from its report. The
|
|
4
|
-
// fix-applier writes its record to `<scratch>/dispositions-<
|
|
5
|
-
// the review result file
|
|
6
|
-
//
|
|
7
|
-
//
|
|
4
|
+
// fix-applier writes its record to `<scratch>/dispositions-fix-pr-<M>[-x].json`,
|
|
5
|
+
// one file per fix-applier; the review result file it answers is
|
|
6
|
+
// `<scratch>/pr<M>/<run>/review.json`, `<run>` the run root the PR's latest
|
|
7
|
+
// `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>` names. This
|
|
8
|
+
// script reads the two together, judges the record, and writes its verdict
|
|
9
|
+
// onto the PR's ledger row as a token `ledger.mjs dispatch` gates the PR's
|
|
10
|
+
// finisher on:
|
|
8
11
|
//
|
|
9
|
-
// dispositions-ok=fix-pr-<M>[-x]:<
|
|
10
|
-
// dispositions-mismatch=fix-pr-<M>[-x]:<
|
|
11
|
-
// dispositions-escalate=fix-pr-<M>[-x]:<
|
|
12
|
-
//
|
|
13
|
-
//
|
|
14
|
-
//
|
|
15
|
-
//
|
|
16
|
-
//
|
|
17
|
-
// dispositions-unchecked=fix-pr-<M>[-x]:<
|
|
18
|
-
//
|
|
12
|
+
// dispositions-ok=fix-pr-<M>[-x]:<run> every rule below held
|
|
13
|
+
// dispositions-mismatch=fix-pr-<M>[-x]:<run> at least one entry broke one
|
|
14
|
+
// dispositions-escalate=fix-pr-<M>[-x]:<run> a human rules: either every rule held
|
|
15
|
+
// but a critical or important finding
|
|
16
|
+
// was deferred `remedy-outside-diff`,
|
|
17
|
+
// or a rule broke and an earlier
|
|
18
|
+
// fix-applier's record on the same
|
|
19
|
+
// review already had
|
|
20
|
+
// dispositions-unchecked=fix-pr-<M>[-x]:<run> no rule broke, but where a deferral was
|
|
21
|
+
// filed could not be read
|
|
19
22
|
//
|
|
20
|
-
// `<
|
|
21
|
-
//
|
|
23
|
+
// `<run>` is the review's own run, so a verdict on one review never answers
|
|
24
|
+
// a later one — a second review at the same head included.
|
|
22
25
|
//
|
|
23
26
|
// The record:
|
|
24
27
|
//
|
|
25
28
|
// { "head": "<the review file's head>",
|
|
29
|
+
// "run": "<the review's run root, as the review path names it>",
|
|
26
30
|
// "entries": [ { "bucket": "survived" | "unverified" | "refuted",
|
|
27
31
|
// "index": <position in that bucket of the review file>,
|
|
28
32
|
// "scope": "in" | "out",
|
|
@@ -42,6 +46,11 @@
|
|
|
42
46
|
// never changes.
|
|
43
47
|
//
|
|
44
48
|
// Rules — each broken one is reported as `<bucket>[<index>]: <rule>`:
|
|
49
|
+
// - Run: with a ledger, `run` is the run the PR's latest `reviewed=` names. A
|
|
50
|
+
// record naming another run, or none, answers a review that is not this
|
|
51
|
+
// one — a fix-applier that ruled on an earlier review at the same head
|
|
52
|
+
// included — and is a mismatch. Without a ledger nothing names the run,
|
|
53
|
+
// and `run` is not read.
|
|
45
54
|
// - Coverage: a `survived` or `unverified` finding with no entry was
|
|
46
55
|
// dropped. An entry naming no finding, or a second entry for one finding,
|
|
47
56
|
// answers nothing.
|
|
@@ -76,7 +85,8 @@
|
|
|
76
85
|
// run root, `<scratch>/pr<N>/fix-XXXXXXXX/<finding>/`, holding a JSON
|
|
77
86
|
// object that validates against the refuter verdict schema
|
|
78
87
|
// `{refuted, reason}`. No `verdictPath`, a path outside that root, a file
|
|
79
|
-
// missing, or one failing the schema
|
|
88
|
+
// missing, or one failing the schema — or abstaining, `inconclusive:
|
|
89
|
+
// true` — is a mismatch. `refuted: true` puts
|
|
80
90
|
// the finding on filing row 4, where applying it is a mismatch too;
|
|
81
91
|
// `refuted: false` on row 5.
|
|
82
92
|
// - Filing: every deferral names in `issue` the issue it was filed to, and
|
|
@@ -89,6 +99,7 @@
|
|
|
89
99
|
// reason other than false-rationale
|
|
90
100
|
// 2 survived, in scope, deferred false-rationale closed suggestion-band record
|
|
91
101
|
// 3 unverified, its refuters dispatched and crashed open, needs-triage
|
|
102
|
+
// or abstained
|
|
92
103
|
// 4 in-scope suggestion, its refuter refuted it closed suggestion-band record
|
|
93
104
|
// 5 in-scope suggestion, its refuter let it survive applied, or deferred as row 1
|
|
94
105
|
// 6 out-of-scope suggestion alleging wrong behavior open, needs-triage
|
|
@@ -124,7 +135,9 @@
|
|
|
124
135
|
// the whole verdict: no token is written, no row is read, and `token` in the
|
|
125
136
|
// stdout payload is null. That is the shape of a standalone `/review-and-fix`
|
|
126
137
|
// with no controller, chosen by `--no-ledger` or by a ledger path that does
|
|
127
|
-
// not exist.
|
|
138
|
+
// not exist. With no `reviewed=` to name the review, `--review <path>` names
|
|
139
|
+
// its file, and is required; with a ledger it is refused, since the ledger
|
|
140
|
+
// already names one.
|
|
128
141
|
// A repository's `.fleet/ledger.md` outlives the fleet run that wrote it, so a
|
|
129
142
|
// standalone member in a worktree of such a repository would otherwise find
|
|
130
143
|
// the previous run's ledger, and a ledger that exists is never skipped: one
|
|
@@ -144,13 +157,17 @@ import { isCLI } from "./is-cli.mjs";
|
|
|
144
157
|
import { gitEnv } from "./git-env.mjs";
|
|
145
158
|
import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
|
|
146
159
|
import { parseMember, memberTokens } from "./ledger-grammar.mjs";
|
|
147
|
-
import { dispositionsToken,
|
|
160
|
+
import { deriveRun, dispositionsToken, LedgerError, rowNums } from "./fleet-tick.mjs";
|
|
148
161
|
import { VERDICT_SCHEMA } from "./review-core.mjs";
|
|
149
162
|
|
|
150
163
|
const NAME = "dispositions-check";
|
|
151
164
|
const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
|
|
152
165
|
const LEDGER_SCRIPT = join(SCRIPT_DIR, "ledger.mjs");
|
|
153
166
|
|
|
167
|
+
// Two spellings of one commit: either head a prefix of the other, the way a
|
|
168
|
+
// record's head (7-40 hex) is matched against its review's full head.
|
|
169
|
+
const sameHead = (a, b) => a.startsWith(b) || b.startsWith(a);
|
|
170
|
+
|
|
154
171
|
// ---------------------------------------------------------------------------
|
|
155
172
|
// pure core — no filesystem or process access until main()
|
|
156
173
|
// ---------------------------------------------------------------------------
|
|
@@ -166,7 +183,7 @@ const ENUMS = { scope: ["in", "out"], claimKind: ["behavior", "shape"], disposit
|
|
|
166
183
|
export const FILING_ROWS = Object.freeze({
|
|
167
184
|
1: { finding: "an in-scope survived finding deferred for an allowed reason other than false-rationale", open: "ready-for-agent" },
|
|
168
185
|
2: { finding: "an in-scope survived finding deferred false-rationale", record: true },
|
|
169
|
-
3: { finding: "an unverified finding whose refuters crashed", open: "needs-triage" },
|
|
186
|
+
3: { finding: "an unverified finding whose refuters crashed or abstained", open: "needs-triage" },
|
|
170
187
|
4: { finding: "an in-scope suggestion its refuter refuted", record: true },
|
|
171
188
|
5: { finding: "an in-scope suggestion its refuter let survive", open: "ready-for-agent" },
|
|
172
189
|
6: { finding: "an out-of-scope suggestion alleging wrong behavior", open: "needs-triage" },
|
|
@@ -209,8 +226,13 @@ function describeIssue({ state, title, labels }) {
|
|
|
209
226
|
return `${state.toLowerCase()}, titled ${JSON.stringify(title)}, labelled ${labels.length === 0 ? "nothing" : labels.join(", ")}`;
|
|
210
227
|
}
|
|
211
228
|
|
|
229
|
+
const ABSTAINED = "is inconclusive — its refuter abstained, so it decided nothing about the finding";
|
|
230
|
+
|
|
212
231
|
// Why `value` is not a refuter verdict, or null when it is: the shape
|
|
213
|
-
// VERDICT_SCHEMA declares, checked key by key.
|
|
232
|
+
// VERDICT_SCHEMA declares, checked key by key. An abstaining verdict
|
|
233
|
+
// (`inconclusive: true`) is refused on top: the in-scope suggestion refuter
|
|
234
|
+
// this reads is never offered an abstain, and one that abstained anyway
|
|
235
|
+
// decided nothing a filing row can be keyed on.
|
|
214
236
|
export function verdictProblem(value) {
|
|
215
237
|
if (value === null || typeof value !== "object" || Array.isArray(value)) return "is not a JSON object";
|
|
216
238
|
for (const key of VERDICT_SCHEMA.required) {
|
|
@@ -221,6 +243,7 @@ export function verdictProblem(value) {
|
|
|
221
243
|
if (declared === undefined) return `carries ${key}, which a refuter verdict does not`;
|
|
222
244
|
if (typeof v !== declared.type) return `has a ${key} that is not a ${declared.type}`;
|
|
223
245
|
}
|
|
246
|
+
if (value.inconclusive === true) return ABSTAINED;
|
|
224
247
|
return null;
|
|
225
248
|
}
|
|
226
249
|
|
|
@@ -372,7 +395,9 @@ function shapeErrors(e) {
|
|
|
372
395
|
* record, or null when there is none to read (`recordProblem` then says why).
|
|
373
396
|
* `touched` is touchedLines() for the review's head; `diffFiles` every file
|
|
374
397
|
* name `git diff <merge-base>...<head>` lists, required only when an entry
|
|
375
|
-
* defers `remedy-outside-diff`; `
|
|
398
|
+
* defers `remedy-outside-diff`; `run` the review's run root name, or null when
|
|
399
|
+
* no ledger names it — a record answers it only by carrying the same `run`;
|
|
400
|
+
* `roots` the directories an absolute finding
|
|
376
401
|
* or remedy path is read relative to. `filing` is `{pr, issue(n), verdict(path)}`,
|
|
377
402
|
* required only when an entry defers or is an in-scope suggestion: `issue`
|
|
378
403
|
* answers `{state, title, labels}` — `state` upper-case, `labels` names — or
|
|
@@ -381,7 +406,7 @@ function shapeErrors(e) {
|
|
|
381
406
|
* `review` must pass reviewProblem() — a bucket missing or holding a
|
|
382
407
|
* non-object is a TypeError here, not a violation.
|
|
383
408
|
*/
|
|
384
|
-
export function checkDispositions({ review, record, recordProblem = null, touched, diffFiles = null, roots = [], filing = null }) {
|
|
409
|
+
export function checkDispositions({ review, record, recordProblem = null, run = null, touched, diffFiles = null, roots = [], filing = null }) {
|
|
385
410
|
const violations = [];
|
|
386
411
|
const escalations = [];
|
|
387
412
|
const unchecked = [];
|
|
@@ -403,6 +428,9 @@ export function checkDispositions({ review, record, recordProblem = null, touche
|
|
|
403
428
|
if (!/^[0-9a-f]{7,40}$/.test(head) || !sameHead(head, reviewHead)) {
|
|
404
429
|
at(null, null, `the record answers head ${JSON.stringify(record.head ?? null)}, not the review's ${review.head}`);
|
|
405
430
|
}
|
|
431
|
+
if (run !== null && record.run !== run) {
|
|
432
|
+
at(null, null, `the record answers run ${JSON.stringify(record.run ?? null)}, not the review's ${run}`);
|
|
433
|
+
}
|
|
406
434
|
}
|
|
407
435
|
|
|
408
436
|
const seen = new Map();
|
|
@@ -527,7 +555,7 @@ export function formatEscalation({ bucket, index, severity, files }) {
|
|
|
527
555
|
}
|
|
528
556
|
|
|
529
557
|
// The row text with `token` in place of every verdict the same member wrote
|
|
530
|
-
// for the same review
|
|
558
|
+
// for the same review run — a re-run replaces its own earlier verdict rather
|
|
531
559
|
// than leaving two to disagree. Unchanged when the token is already the only
|
|
532
560
|
// one. Separators a removal leaves doubled are folded.
|
|
533
561
|
export function withVerdict(rowText, token) {
|
|
@@ -536,7 +564,7 @@ export function withVerdict(rowText, token) {
|
|
|
536
564
|
const words = String(rowText).trim().split(/\s+/).filter(Boolean);
|
|
537
565
|
const kept = words.filter((w) => {
|
|
538
566
|
const d = dispositionsToken(w);
|
|
539
|
-
return d === null || d.member.name !== mine.member.name ||
|
|
567
|
+
return d === null || d.member.name !== mine.member.name || d.run !== mine.run;
|
|
540
568
|
});
|
|
541
569
|
if (kept.length === words.length - 1 && words.includes(token)) return words.join(" ");
|
|
542
570
|
const folded = kept.join(" ").replace(/·(?:\s+·)+/g, "·").replace(/^·\s*|\s*·$/g, "").trim();
|
|
@@ -544,16 +572,16 @@ export function withVerdict(rowText, token) {
|
|
|
544
572
|
}
|
|
545
573
|
|
|
546
574
|
// Whether a fix-applier on PR `pr` with a lower retry suffix than `member`
|
|
547
|
-
// already has a mismatch or escalate on the ledger for `
|
|
548
|
-
// that resolves to the PR, since a row can be split. An unchecked verdict
|
|
549
|
-
// no failure of a record, and a verdict on another review
|
|
575
|
+
// already has a mismatch or escalate on the ledger for review `run` — on any
|
|
576
|
+
// row that resolves to the PR, since a row can be split. An unchecked verdict
|
|
577
|
+
// is no failure of a record, and a verdict on another review counts for
|
|
550
578
|
// nothing, so a new review starts the count again.
|
|
551
|
-
export function failedBefore(rows, pr, member,
|
|
579
|
+
export function failedBefore(rows, pr, member, run) {
|
|
552
580
|
const mine = member.retry ?? "";
|
|
553
581
|
return rows.some((r) => rowNums(r).pr === pr && r.split(/\s+/).some((w) => {
|
|
554
582
|
const d = dispositionsToken(w);
|
|
555
583
|
return d !== null && (d.verdict === "mismatch" || d.verdict === "escalate") && d.member.number === pr
|
|
556
|
-
&& (d.member.retry ?? "") < mine &&
|
|
584
|
+
&& (d.member.retry ?? "") < mine && d.run === run;
|
|
557
585
|
}));
|
|
558
586
|
}
|
|
559
587
|
|
|
@@ -563,7 +591,7 @@ export function failedBefore(rows, pr, member, head) {
|
|
|
563
591
|
|
|
564
592
|
const die = makeDie(NAME);
|
|
565
593
|
const { arg, has, sweep, stray } = defineFlags(die, {
|
|
566
|
-
flags: { member: "value", scratch: "value", repo: "value", ledger: "value", "no-ledger": "bool" },
|
|
594
|
+
flags: { member: "value", scratch: "value", repo: "value", ledger: "value", "no-ledger": "bool", review: "value" },
|
|
567
595
|
});
|
|
568
596
|
|
|
569
597
|
// The one git primitive. An ambient GIT_DIR or GIT_WORK_TREE — a hook, a
|
|
@@ -652,7 +680,9 @@ function verdictReader(scratch, pr) {
|
|
|
652
680
|
return { problem: `cannot be read as JSON — ${e.message}` };
|
|
653
681
|
}
|
|
654
682
|
const why = verdictProblem(value);
|
|
655
|
-
|
|
683
|
+
if (why === null) return { refuted: value.refuted };
|
|
684
|
+
// An abstention validates against the schema; it is refused as evidence, not as a malformed file.
|
|
685
|
+
return { problem: why === ABSTAINED ? why : `fails the refuter verdict schema — it ${why}` };
|
|
656
686
|
};
|
|
657
687
|
}
|
|
658
688
|
|
|
@@ -694,7 +724,7 @@ function readJson(path) {
|
|
|
694
724
|
}
|
|
695
725
|
|
|
696
726
|
function main() {
|
|
697
|
-
const usage = "usage: dispositions-check.mjs --member fix-pr-<M>[-x] --scratch <dir> [--repo <path>] [--ledger <path> | --no-ledger]";
|
|
727
|
+
const usage = "usage: dispositions-check.mjs --member fix-pr-<M>[-x] --scratch <dir> [--repo <path>] [--ledger <path> | --no-ledger --review <path>]";
|
|
698
728
|
const name = arg("member");
|
|
699
729
|
const scratch = arg("scratch");
|
|
700
730
|
if (!name || !scratch) die(usage);
|
|
@@ -706,8 +736,36 @@ function main() {
|
|
|
706
736
|
const repo = arg("repo") ?? process.cwd();
|
|
707
737
|
const standalone = has("no-ledger");
|
|
708
738
|
if (standalone && arg("ledger") !== null) die("--no-ledger and --ledger contradict: name one");
|
|
739
|
+
const ledgerFile = standalone ? null : ledgerInUse(arg("ledger"), repo);
|
|
709
740
|
|
|
710
|
-
|
|
741
|
+
// The review the record answers. With a ledger it is the one PR M's latest
|
|
742
|
+
// `reviewed=` names — `<scratch>/pr<M>/<run>/review.json`, read off the
|
|
743
|
+
// same per-PR fold `ledger.mjs dispatch` gates the finisher by, so the check
|
|
744
|
+
// and the gate never judge two different reviews. Without one nothing names
|
|
745
|
+
// it, so `--review` must.
|
|
746
|
+
let data = null, row = null, run = null, reviewPath;
|
|
747
|
+
if (ledgerFile === null) {
|
|
748
|
+
reviewPath = arg("review");
|
|
749
|
+
if (reviewPath === null) die(`no ledger names PR #${pr}'s review — pass --review <path> for the review file ${member.name}'s record answers`);
|
|
750
|
+
} else {
|
|
751
|
+
if (arg("review") !== null) die(`--review and a ledger contradict: with a ledger the review is the one PR #${pr}'s latest reviewed= names`);
|
|
752
|
+
data = JSON.parse(runLedger(ledgerFile, ["read"], "read the ledger"));
|
|
753
|
+
// The verdict lands on the row carrying the member on its own PR's row —
|
|
754
|
+
// where `ledger.mjs dispatch` wrote it, and where the gate reads PR M's
|
|
755
|
+
// tokens from.
|
|
756
|
+
row = data.rows.find((r) => rowNums(r).pr === pr && memberTokens(r).some((t) => t.name === member.name));
|
|
757
|
+
if (row === undefined) die(`${member.name} is on no row of PR #${pr} — \`ledger.mjs dispatch\` records a fix-applier before its record can be checked; with no controller, pass --no-ledger`);
|
|
758
|
+
let latest;
|
|
759
|
+
try {
|
|
760
|
+
latest = deriveRun({ rows: data.rows, dispatched: data.dispatched, drain: data.drain }, []).reviewed.find((r) => r.pr === pr);
|
|
761
|
+
} catch (e) {
|
|
762
|
+
if (!(e instanceof LedgerError)) throw e;
|
|
763
|
+
die(`${e.message} — fleet-tick.mjs refuses this ledger, so PR #${pr}'s latest review cannot be read off it`);
|
|
764
|
+
}
|
|
765
|
+
if (latest === undefined) die(`PR #${pr} has no reviewed= on the ledger — no review for ${member.name}'s record to answer`);
|
|
766
|
+
run = latest.run;
|
|
767
|
+
reviewPath = join(scratch, `pr${pr}`, run, "review.json");
|
|
768
|
+
}
|
|
711
769
|
let review;
|
|
712
770
|
try {
|
|
713
771
|
review = readJson(reviewPath);
|
|
@@ -718,7 +776,9 @@ function main() {
|
|
|
718
776
|
if (problem !== null) die(`${reviewPath} ${problem}`);
|
|
719
777
|
const head = String(review.head).toLowerCase();
|
|
720
778
|
|
|
721
|
-
|
|
779
|
+
// One record per fix-applier: a retry, or a fix-applier answering a later
|
|
780
|
+
// review, writes its own and never replaces an earlier one's.
|
|
781
|
+
const recordPath = join(scratch, `dispositions-${member.name}.json`);
|
|
722
782
|
let record = null, recordProblem = null;
|
|
723
783
|
if (!existsSync(recordPath)) {
|
|
724
784
|
recordProblem = `no disposition record at ${recordPath}`;
|
|
@@ -748,30 +808,24 @@ function main() {
|
|
|
748
808
|
// file the PR moved away or removed is a file the PR's diff names.
|
|
749
809
|
const diffFiles = git(repo, ["diff", "--no-color", "--no-ext-diff", "--no-renames", "--name-only", "-z", base, head],
|
|
750
810
|
`list the files of ${base}..${head}`).split("\0").filter(Boolean);
|
|
751
|
-
const ledgerFile = standalone ? null : ledgerInUse(arg("ledger"), repo);
|
|
752
811
|
|
|
753
812
|
const { violations, escalations, unchecked } = checkDispositions({
|
|
754
|
-
review, record, recordProblem, touched: touchedLines(diff), diffFiles, roots: [review.snapshot, top],
|
|
813
|
+
review, record, recordProblem, run, touched: touchedLines(diff), diffFiles, roots: [review.snapshot, top],
|
|
755
814
|
filing: { pr, issue: issueReader(repo), verdict: verdictReader(scratch, pr) },
|
|
756
815
|
});
|
|
757
|
-
//
|
|
758
|
-
//
|
|
759
|
-
// tokens from. No ledger, no row: the exit status below is the verdict, and
|
|
760
|
-
// with no earlier fix-applier's verdict to count, a broken rule is always a
|
|
816
|
+
// No ledger, no row: the exit status below is the verdict, and with no
|
|
817
|
+
// earlier fix-applier's verdict to count, a broken rule is always a
|
|
761
818
|
// mismatch.
|
|
762
|
-
const data = ledgerFile === null ? null : JSON.parse(runLedger(ledgerFile, ["read"], "read the ledger"));
|
|
763
819
|
// A mismatch an earlier fix-applier already drew on this review makes this
|
|
764
820
|
// one the second: it is written as an escalate, which no fix-applier answers.
|
|
765
821
|
// A broken rule outranks an escalation, and an escalation a filing the
|
|
766
822
|
// tracker could not answer.
|
|
767
|
-
const secondMismatch = violations.length > 0 && data !== null && failedBefore(data.rows, pr, member,
|
|
823
|
+
const secondMismatch = violations.length > 0 && data !== null && failedBefore(data.rows, pr, member, run);
|
|
768
824
|
const verdict = violations.length > 0 ? (secondMismatch ? "escalate" : "mismatch")
|
|
769
825
|
: escalations.length > 0 ? "escalate" : unchecked.length > 0 ? "unchecked" : "ok";
|
|
770
|
-
const token = `dispositions-${verdict}=${member.name}:${
|
|
826
|
+
const token = data === null ? null : `dispositions-${verdict}=${member.name}:${run}`;
|
|
771
827
|
|
|
772
828
|
if (data !== null) {
|
|
773
|
-
const row = data.rows.find((r) => rowNums(r).pr === pr && memberTokens(r).some((t) => t.name === member.name));
|
|
774
|
-
if (row === undefined) die(`${member.name} is on no row of PR #${pr} — \`ledger.mjs dispatch\` records a fix-applier before its record can be checked; with no controller, pass --no-ledger`);
|
|
775
829
|
const key = row.split(/\s/)[0];
|
|
776
830
|
if (!/^#[0-9]+$/.test(key)) die(`the row carrying ${member.name} has no #<n> key for \`ledger.mjs row\` to rewrite it by: ${row}`);
|
|
777
831
|
const text = row.slice(key.length).trim();
|
|
@@ -786,9 +840,9 @@ function main() {
|
|
|
786
840
|
console.error(`${member.name}: ${u.bucket}[${u.index}]: where it was filed is unchecked — #${u.issue} could not be read through gh: ${u.problem}`);
|
|
787
841
|
}
|
|
788
842
|
if (secondMismatch) {
|
|
789
|
-
console.error(`${member.name}: escalate — an earlier fix-applier's record on review ${
|
|
843
|
+
console.error(`${member.name}: escalate — an earlier fix-applier's record on review ${run} already failed this check; no further fix-applier answers PR #${pr}, a human does`);
|
|
790
844
|
}
|
|
791
|
-
console.log(JSON.stringify({ member: member.name, pr, head, verdict, token
|
|
845
|
+
console.log(JSON.stringify({ member: member.name, pr, head, verdict, token, violations, escalations, unchecked }));
|
|
792
846
|
// exitCode, not exit(): stdout to a pipe is written asynchronously, and an
|
|
793
847
|
// exit() here could cut the payload off.
|
|
794
848
|
process.exitCode = verdict === "ok" ? 0 : 1;
|