@feigi/fleet-ctl 3.139.0 → 3.140.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.
@@ -17,7 +17,7 @@ Label names in this file are roles; the Label map gives the string to type; a me
17
17
 
18
18
  See **Specialists** — those constraints are not optional.
19
19
  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, and check it in either scope. Out of the PR's ticket scope → defer and file, but **the claim bar runs first:** a suggestion whose claim is about shape — step 5's worth-a-claim bar, recorded `claimKind: shape` — gets no refuter and goes to the `PR #<pr> review: the suggestion band, checked` record, and every other out-of-scope suggestion gets the same refuter an in-scope one does, dispatched the same way, before it is filed. 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 host repository, and `fatal: not a git repository` (exit 128) is the usual pass, not a failure — an outer repository whose ignore rules cover your scratch dir is a pass too; before any `git commit` it must resolve to your scratch path, which catches a forgotten `git init` under any enclosing repository — compare resolved forms (`realpath`), since `--show-toplevel` can report a symlinked parent such as `/tmp` or a symlinked `$HOME` under its resolved name.* 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. **Out of scope the refuter decides only where the suggestion is filed — it defers either way, never applied.** Refuted → the `PR #<pr> review: the suggestion band, checked` record, never an open issue. Survived, or its refuter crashed or abstained → its own open issue labelled `needs-triage`, citing the verdict, or the run that crashed, in the body. There is no cap on these refuters; your final verdict (step 4) says how many you dispatched against out-of-scope suggestions. "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.**
20
- **Write every ruling to `<scratch>/dispositions-<your name>.json`, `<your name>` the `fix-pr-<pr>[-x]` you were dispatched as (standalone, `fix-pr-<pr>`) — the disposition record `dispositions-check.mjs` judges against the review result file before any finisher is dispatched.** It is `{"head": "<the review file's head>", "run": "<the run root's name in the review path>", "entries": [ … ]}` — `run` the `<run>` of the review path your prompt names, which the check holds against the one the PR's latest `reviewed=` names, so a record written against an earlier review of the same PR, a same-head one included, is a mismatch (standalone, with no ledger naming a run, leave it out): one entry per `survived` finding and per `unverified` finding, plus one per `refuted` finding you reverse. Each entry carries `bucket` (`survived|unverified|refuted`), `index` (its position in that bucket of the review file — stable, since a round's file never changes), `scope` (`in|out`), `claimKind` (`behavior|shape`) and `disposition` (`apply|defer`), and where they apply `reason`, `issue` (the number you filed it to or commented on), `verdictPath` (a suggestion's refuter verdict file, in scope and, above the claim bar, out of scope) and `remedyFiles` (the files its remedy names). A `refuted` entry carries `scope`, `claimKind` and `disposition` like every other entry, and a non-empty `reason` holding the evidence that reverses it; a missing or blank `reason` is a mismatch. The check reads scope off the diff before it reads your entry: a finding with no `line`, or on a line `git diff` touches from the PR's merge-base with `origin/main` to the review's `head`, is in scope whatever `scope` says, and only otherwise does the declared one stand. An in-scope `survived` finding deferred passes only with `reason` `false-rationale`, `mutual-exclusion`, `remedy-worse` or `remedy-outside-diff`. `remedy-outside-diff` — the remedy would edit a file the PR's diff does not touch — also needs `remedyFiles` to name at least one file absent from `git diff` from that merge-base to the review's `head`: none named, or every one in that diff, is a mismatch. A `critical` or `important` finding deferred for it goes to a human instead of passing: the script exits 1 with verdict `escalate`, `ledger.mjs dispatch` refuses the PR's finisher, and nothing retries it; a `suggestion` deferred for it passes. Any other reason, none, or a `survived` or `unverified` finding with no entry is a mismatch: the script exits 1 naming each violating entry's bucket, index and rule, and `ledger.mjs dispatch` refuses the PR's finisher. `disposition` has no `dismiss`: an in-scope `survived` finding verified correct, needing no change, is deferred with `reason` `false-rationale` and filed on the suggestion-band record — step 5's `PR #<pr> review: the suggestion band, checked`.
20
+ **Write every ruling to `<scratch>/dispositions-<your name>.json`, `<your name>` the `fix-pr-<pr>[-x]` you were dispatched as (standalone, `fix-pr-<pr>`) — the disposition record `dispositions-check.mjs` judges against the review result file before any finisher is dispatched.** It is `{"head": "<the review file's head>", "run": "<the run root's name in the review path>", "entries": [ … ]}` — `run` the `<run>` of the review path your prompt names, which the check holds against the one the PR's latest `reviewed=` names, so a record written against an earlier review of the same PR, a same-head one included, is a mismatch (standalone, with no ledger naming a run, leave it out): one entry per `survived` finding and per `unverified` finding, plus one per `refuted` finding you reverse. Each entry carries `bucket` (`survived|unverified|refuted`), `index` (its position in that bucket of the review file — stable, since a round's file never changes), `scope` (`in|out`), `claimKind` (`behavior|shape`) and `disposition` (`apply|defer`), and where they apply `reason`, `issue` (the number you filed it to or commented on), `verdictPath` (a suggestion's refuter verdict file, in scope and, above the claim bar, out of scope) and `remedyFiles` (the files its remedy names). A `refuted` entry carries `scope`, `claimKind` and `disposition` like every other entry, and a non-empty `reason` holding the evidence that reverses it; a missing or blank `reason` is a mismatch. The check reads scope off the diff before it reads your entry: a finding with no `line`, or on a line `git diff` touches from the PR's merge-base with `origin/main` to the review's `head`, is in scope whatever `scope` says, and only otherwise does the declared one stand. An in-scope `survived` finding deferred passes only with `reason` `false-rationale`, `mutual-exclusion`, `remedy-worse` or `remedy-outside-diff`. `remedy-outside-diff` — the remedy would edit a file the PR's diff does not touch — also needs `remedyFiles` to name at least one file absent from `git diff` from that merge-base to the review's `head`: none named, or every one in that diff, is a mismatch. A `critical` or `important` finding deferred for it goes to the maintainer instead of passing: the script exits 1 with verdict `escalate`, `ledger.mjs dispatch` refuses the PR's finisher until answered; 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 suggestion-band record — step 5's `PR #<pr> review: the suggestion band, checked`.
21
21
  **Give every entry whose finding stands a Charge:** `charge` — `false-claim`, `unmet`, `both` or `none` — and, with `none` only, a `chargeReason`: `defect-outside-acceptance` (a defect outside the ticket's acceptance criteria, which no text the implementer wrote claims is otherwise), `not-the-implementers-text` (the false text predates the PR, or comes from the ticket) or `claim-about-untouched-code` (a claim about code the change does not touch). A `survived` finding not deferred `false-rationale` stands, and so does every `refuted` one you reverse; an `unverified` one never does. Charge the work as submitted — a finding you apply is charged as if it were still there — by the definitions of `closed_own_ticket` and `minted_false_claim` in the header of `docs/metrics/tier-outcomes.tsv`, against the ticket as its implementer was dispatched with it; an entry scoped `out` is charged `none`. The check requires a Charge on every standing entry of the record answering the PR's first review — the first that counted no survived and no unverified finding, or else the first a fix-applier answered — and a record answering a later review, or one checked with no ledger, needs none. Wherever a `charge` or `chargeReason` appears it is judged: an unknown value, `none` with no `chargeReason`, a `chargeReason` with any other `charge` or with none, and an out-of-scope entry charged anything but `none` are each a mismatch.
22
22
  3. **Run `checkCmd` and `testCmd` before you commit**, from the worktree, each copied verbatim — not a runner you picked. `checkCmd` is the Recipe's Check step and `testCmd` is the command your dispatcher handed you; **standalone, with no dispatcher to hand you them, they are the repo's own Check step and Test entrypoint**, read off the repo's Recipe cache (`derive-testcmd.sh <repo> check` prints the first, `derive-testcmd.sh <repo> test` the second). Read them 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 all three 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 — `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run push-sync.mjs --branch <branch>`, which pushes the explicit refspec `HEAD:refs/heads/<branch>` and then moves the worktree holding `<branch>` to the pushed SHA, or names why it did not and exits 3 with the push landed: 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`), 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 a refspec push alone leaves the claim worktree's `refs/heads/<branch>` at its old tip — 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. Seen twice in one run, and caught only by a finisher's reading. `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` on a commit you push, or on the push itself.** 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 on what reaches the branch — 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.
23
23
  **Under the fleet, run the two through `recipe-check.mjs`, not one by one:** from the worktree, after `git add` and before the commit, `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run recipe-check.mjs --member <your name> --testCmd "<testCmd>" --reports <scratch>/reports` — `<your name>` the `fix-pr-<pr>[-x]` you were dispatched as, and `<testCmd>` the whole command you were handed, one quoted argument. It runs the Recipe's Check step, which is `checkCmd`, then `<testCmd>` exactly as handed, against the staged tree, and records both results beside your report. The record is keyed to the tree, so run it again after any content change or rebase — a message-only amend keeps it valid — and the controller refuses an `applied` report whose head's tree has no green record. After the commit, and before you push or report, compare `git rev-parse 'HEAD^{tree}'` with the `tree` field of your record, `<scratch>/reports/<your name>.check.json`. A commit hook that rewrote and re-staged files after the record was written makes the two differ. When they do, list the paths it changed, `git diff --name-only "$(jq -r .tree <scratch>/reports/<your name>.check.json)" HEAD`. If the PR changes every listed path anyway, run `recipe-check.mjs` again with the same arguments: right after the commit the index holds the committed tree, so the re-run runs both commands on that tree and records it, leaving the head's sha as it is. A listed path the PR does not otherwise change is a stale base the hook staged rather than left unstaged, and a re-run would record it green: `git fetch origin && git rebase origin/main`, take the commit back with `git reset --soft HEAD^`, put each such path alone back with `git restore --source=HEAD --staged --worktree -- <that path>`, run `recipe-check.mjs`, then `git commit -C ORIG_HEAD` and compare again. A hook that stages such a path again on the rebased base → push nothing and report that cause. Equal trees need no re-run. Exit 1 is red; exit 2 and 4 are refusals that record nothing: your brief says how each ends; exit 75 (no slot free) and exit 143, 130 or 129 (a SIGTERM, SIGINT or SIGHUP, nothing recorded) are no test result: run it again, with `timeout: 0` on the call for a signal. **Standalone, with no report to settle against,** run `checkCmd` and `testCmd` yourself, each copied verbatim.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.139.0",
3
+ "version": "3.140.0",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -11,14 +11,18 @@
11
11
  //
12
12
  // dispositions-ok=fix-pr-<M>[-x]:<run> every rule below held
13
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
14
+ // dispositions-escalate=fix-pr-<M>[-x]:<run> the maintainer answers: either every
15
+ // rule held but a critical or important
16
+ // finding was deferred
17
+ // `remedy-outside-diff`, or a rule broke
18
+ // and an earlier fix-applier's record on
19
+ // the same review already had
20
20
  // dispositions-unchecked=fix-pr-<M>[-x]:<run> no rule broke, but where a deferral was
21
21
  // filed could not be read
22
+ // escalation-answer=<run>:<bucket>[<index>]:upheld|sent-back
23
+ // the maintainer's answer to one escalated
24
+ // finding, written by --uphold and
25
+ // --send-back and by nothing else
22
26
  //
23
27
  // `<run>` is the review's own run, so a verdict on one review never answers
24
28
  // a later one — a second review at the same head included.
@@ -95,6 +99,7 @@
95
99
  // is escalated rather than passed: the verdict is `escalate`, and the
96
100
  // output names each such finding. A `suggestion` passes as `ok`. A record
97
101
  // that also breaks a rule is a `mismatch`, its escalations printed too.
102
+ // The maintainer's answers (below) clear an escalation.
98
103
  // - Refuter evidence: a suggestion — an `unverified` finding no refuter
99
104
  // was dispatched against (`refutersDispatched` zero or absent) — needs
100
105
  // `verdictPath` when it is in scope, by the presumption above or by its
@@ -156,12 +161,41 @@
156
161
  // never ok, and never a mismatch, since the record broke nothing. Run the
157
162
  // check again once `gh` answers.
158
163
  //
164
+ // Escalation answers: the maintainer answers an escalated finding `upheld` —
165
+ // the deferral stands — or `sent-back` — the finding is applied in this PR.
166
+ // `--uphold <list>` and `--send-back <list>`, each a comma-separated list of
167
+ // `<bucket>[<index>]` as the output prints it, record the answers for the
168
+ // escalated member, `--member fix-pr-<M>[-x]`, in one write that adds
169
+ // `escalation-answer=<run>:<bucket>[<index>]:upheld|sent-back` per finding to
170
+ // the PR's row and replaces the escalate with the verdict the record then
171
+ // earns: `ok` — `unchecked` when a filing could not be read — with every
172
+ // finding upheld; `mismatch`, or `escalate` when an earlier fix-applier's
173
+ // record on the same review already failed, with any sent back. A send-back
174
+ // is a failure like any other. `<run>` is the review whose escalation the
175
+ // answer settles, so an answer on one review answers nothing on a later one.
176
+ //
177
+ // Every record judged against a review reads that review's answers off the
178
+ // PR's rows, whether or not the run records any: an upheld finding is no
179
+ // escalation, and an entry that defers a sent-back finding is a violation
180
+ // whatever its reason. Running the check again with no answer flags therefore
181
+ // reproduces the verdict and its violations.
182
+ //
183
+ // A run that records answers refuses — exit 2, the cause named, the ledger
184
+ // byte-identical — unless: a ledger is in use; the PR's current dispositions
185
+ // verdict on its latest review is an escalate naming the member; no
186
+ // fix-applier on the PR is live; the record, judged with the answers already
187
+ // on the row, breaks no rule; every listed finding is one the record escalates,
188
+ // none listed twice or both ways; and every escalation of the record has an
189
+ // answer. A record that breaks a rule has no outside-diff escalate to answer:
190
+ // a second failure on one review clears only with a new review.
191
+ //
159
192
  // Exit status: 0 ok; 1 mismatch, escalate or unchecked; 2 nothing judged and
160
- // nothing written — a bad flag, no valid Label map (the message names
161
- // `label-map.mjs ensure`), an unreadable or malformed review file, a
162
- // record file that exists but cannot be read, a git or ledger failure. A
163
- // missing or unparseable RECORD is judged, not refused: the fix-applier wrote
164
- // nothing a reader can use, so every finding it had to cover is dropped.
193
+ // nothing written — a bad flag, an answer the run refuses to record, no valid
194
+ // Label map (the message names `label-map.mjs ensure`), an unreadable or
195
+ // malformed review file, a record file that exists but cannot be read, a git
196
+ // or ledger failure. A missing or unparseable RECORD is judged, not refused:
197
+ // the fix-applier wrote nothing a reader can use, so every finding it had to
198
+ // cover is dropped.
165
199
  //
166
200
  // Without a ledger the record is judged all the same and the exit status is
167
201
  // the whole verdict: no token is written, no row is read, and `token` in the
@@ -189,7 +223,7 @@ import { isCLI } from "./is-cli.mjs";
189
223
  import { gitEnv } from "./git-env.mjs";
190
224
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
191
225
  import { readLabelMap } from "./label-map.mjs";
192
- import { parseMember, memberTokens, rowNums, dispositionsToken, firstReview, prTokens } from "./ledger-grammar.mjs";
226
+ import { parseMember, memberTokens, rowNums, dispositionsToken, escalationAnswerToken, escalationAnswers, firstReview, prTokens } from "./ledger-grammar.mjs";
193
227
  import { deriveRun, LedgerError } from "./fleet-tick.mjs";
194
228
  import { VERDICT_SCHEMA } from "./review-core.mjs";
195
229
 
@@ -212,6 +246,8 @@ export const ALLOWED_DEFER = Object.freeze(["false-rationale", "mutual-exclusion
212
246
  const COVERED = ["survived", "unverified"];
213
247
  const BUCKETS = [...COVERED, "refuted"];
214
248
  const ENUMS = { scope: ["in", "out"], claimKind: ["behavior", "shape"], disposition: ["apply", "defer"] };
249
+ // The rule an entry breaks when it defers a finding the maintainer sent back.
250
+ const SENT_BACK = "sent back to be applied in this PR — the maintainer answered this finding's escalation, and this entry defers it; a deferral is a mismatch whatever its reason";
215
251
 
216
252
  // A Charge: what a finding that stands on a PR's first review says about the
217
253
  // work as submitted. `none` names one of CHARGE_REASONS; no other Charge does.
@@ -491,10 +527,15 @@ function chargeProblem(e, { inScope, required }) {
491
527
  * `charges` is whether the record answers the PR's first review (firstReview()
492
528
  * in ledger-grammar.mjs), where every entry whose finding stands carries a
493
529
  * Charge; a Charge an entry carries anywhere is judged all the same.
530
+ * `answers` is the maintainer's escalation answers for the review's run
531
+ * (escalationAnswers() in ledger-grammar.mjs): a finding's address,
532
+ * `<bucket>[<index>]`, to `upheld` or `sent-back`. An upheld finding is no
533
+ * escalation, and an entry that defers a sent-back finding is a violation
534
+ * whatever its reason.
494
535
  * `review` must pass reviewProblem() — a bucket missing or holding a
495
536
  * non-object is a TypeError here, not a violation.
496
537
  */
497
- export function checkDispositions({ review, record, recordProblem = null, run = null, touched, diffFiles = null, roots = [], filing = null, charges = false }) {
538
+ export function checkDispositions({ review, record, recordProblem = null, run = null, touched, diffFiles = null, roots = [], filing = null, charges = false, answers = new Map() }) {
498
539
  const violations = [];
499
540
  const escalations = [];
500
541
  const unchecked = [];
@@ -552,6 +593,13 @@ export function checkDispositions({ review, record, recordProblem = null, run =
552
593
  const inScope = presumed !== null || e.scope === "in";
553
594
  const charge = chargeProblem(e, { inScope, required: charges && stands(bucket, e) });
554
595
  if (charge !== null) at(bucket, index, charge);
596
+ // The maintainer sent this finding back to be applied in this PR: an entry
597
+ // that defers it breaks that answer whatever its reason, so nothing else
598
+ // about the deferral is judged.
599
+ if (e.disposition === "defer" && answers.get(key) === "sent-back") {
600
+ at(bucket, index, SENT_BACK);
601
+ return;
602
+ }
555
603
  if (bucket === "refuted" && !e.reason?.trim()) {
556
604
  at(bucket, index, "a reversed refutation names its evidence in reason, and this one names none");
557
605
  return;
@@ -610,7 +658,7 @@ export function checkDispositions({ review, record, recordProblem = null, run =
610
658
  return;
611
659
  }
612
660
  const severity = finding.severity;
613
- if (severity !== "suggestion") escalations.push({ bucket, index, severity: severity ?? null, files: outside });
661
+ if (severity !== "suggestion" && answers.get(key) !== "upheld") escalations.push({ bucket, index, severity: severity ?? null, files: outside });
614
662
  }
615
663
  }
616
664
  // Where the deferral must be filed. `claimKind` is trusted, never judged.
@@ -648,7 +696,7 @@ export function formatViolation({ bucket, index, rule }) {
648
696
  }
649
697
 
650
698
  export function formatEscalation({ bucket, index, severity, files }) {
651
- return `${bucket}[${index}]: a ${severity ?? "severity-less"} finding deferred remedy-outside-diff, its remedy in ${files.join(", ")} — a human rules`;
699
+ return `${bucket}[${index}]: a ${severity ?? "severity-less"} finding deferred remedy-outside-diff, its remedy in ${files.join(", ")} — the maintainer answers`;
652
700
  }
653
701
 
654
702
  // The row text with `token` in place of every verdict the same member wrote
@@ -688,7 +736,7 @@ export function failedBefore(rows, pr, member, run) {
688
736
 
689
737
  const die = makeDie(NAME);
690
738
  const { arg, has, sweep, stray } = defineFlags(die, {
691
- flags: { member: "value", scratch: "value", repo: "value", ledger: "value", "no-ledger": "bool", review: "value" },
739
+ flags: { member: "value", scratch: "value", repo: "value", ledger: "value", "no-ledger": "bool", review: "value", uphold: "value", "send-back": "value" },
692
740
  });
693
741
 
694
742
  // The one git primitive. An ambient GIT_DIR or GIT_WORK_TREE — a hook, a
@@ -834,8 +882,31 @@ function readJson(path) {
834
882
  return JSON.parse(readFileSync(path, "utf8"));
835
883
  }
836
884
 
885
+ // A finding's address as the check prints it: its bucket and its position in
886
+ // that bucket of the review file.
887
+ const ADDRESS = new RegExp(`^(${BUCKETS.join("|")})\\[(0|[1-9][0-9]*)\\]$`);
888
+
889
+ // The findings a `--uphold` or `--send-back` list names, each `<bucket>[<index>]`
890
+ // — or null when the flag is absent. A second occurrence of the flag would be
891
+ // read by nothing, so it is refused rather than dropped.
892
+ function addressList(flag) {
893
+ const raw = arg(flag);
894
+ if (raw === null) return null;
895
+ if (process.argv.filter((a) => a === `--${flag}`).length > 1) die(`--${flag} is given twice — name every finding in one comma-separated list`);
896
+ const list = raw.split(",").map((a) => a.trim());
897
+ const bad = list.find((a) => !ADDRESS.test(a));
898
+ if (bad !== undefined) die(`--${flag} names ${JSON.stringify(bad)}, which is no <bucket>[<index>] — a bucket is ${BUCKETS.join(", ")}, an index a whole number from 0`);
899
+ return list;
900
+ }
901
+
902
+ // Addresses in the record's own order: by bucket, then by index.
903
+ const byAddress = (a, b) => {
904
+ const [x, y] = [a, b].map((s) => ADDRESS.exec(s));
905
+ return BUCKETS.indexOf(x[1]) - BUCKETS.indexOf(y[1]) || Number(x[2]) - Number(y[2]);
906
+ };
907
+
837
908
  function main() {
838
- const usage = "usage: dispositions-check.mjs --member fix-pr-<M>[-x] --scratch <dir> [--repo <path>] [--ledger <path> | --no-ledger --review <path>]";
909
+ const usage = "usage: dispositions-check.mjs --member fix-pr-<M>[-x] --scratch <dir> [--repo <path>] [--ledger <path> | --no-ledger --review <path>] [--uphold <list>] [--send-back <list>]";
839
910
  const name = arg("member");
840
911
  const scratch = arg("scratch");
841
912
  if (!name || !scratch) die(usage);
@@ -845,9 +916,25 @@ function main() {
845
916
  if (member === null || member.family !== "fix-pr") die(`'${name}' is not a fix-applier — expected fix-pr-<M>, a -b, -c … suffix allowed`);
846
917
  const pr = member.number;
847
918
  const repo = arg("repo") ?? process.cwd();
919
+ // The maintainer's answers, when this run records them: `--uphold` and
920
+ // `--send-back`, each a list of the escalated findings answered that way.
921
+ // Told before anything is read, since a list that cannot be one is a usage error.
922
+ const uphold = addressList("uphold");
923
+ const sendBack = addressList("send-back");
924
+ const listed = new Map();
925
+ for (const [flag, list, answer] of [["--uphold", uphold, "upheld"], ["--send-back", sendBack, "sent-back"]]) {
926
+ for (const a of list ?? []) {
927
+ if (listed.has(a)) die(listed.get(a) === answer ? `${flag} lists ${a} twice` : `${a} is listed in both --uphold and --send-back — a finding is answered one way`);
928
+ listed.set(a, answer);
929
+ }
930
+ }
931
+ const recording = listed.size > 0;
848
932
  const standalone = has("no-ledger");
849
933
  if (standalone && arg("ledger") !== null) die("--no-ledger and --ledger contradict: name one");
850
934
  const ledgerFile = standalone ? null : ledgerInUse(arg("ledger"), repo);
935
+ if (recording && ledgerFile === null) {
936
+ die(`${uphold !== null ? "--uphold" : "--send-back"} records the maintainer's answer on the ledger row, and no ledger is in use — run it for the escalated member where the run's ledger is`);
937
+ }
851
938
  // Without a ledger nothing names the review the record answers, so `--review`
852
939
  // must; with one, the latest `reviewed=` already does. Both are usage errors,
853
940
  // so they are told before the Label map, the ledger or the tracker is read.
@@ -870,7 +957,7 @@ function main() {
870
957
  // same per-PR fold `ledger.mjs dispatch` gates the finisher by, so the check
871
958
  // and the gate never judge two different reviews. Without one it is the
872
959
  // `--review` path the checks above required.
873
- let data = null, row = null, run = null, charges = false, reviewPath;
960
+ let data = null, row = null, run = null, charges = false, reviewPath, answers = new Map();
874
961
  if (ledgerFile === null) {
875
962
  reviewPath = arg("review");
876
963
  } else {
@@ -889,9 +976,30 @@ function main() {
889
976
  }
890
977
  if (latest === undefined) die(`PR #${pr} has no reviewed= on the ledger — no review for ${member.name}'s record to answer`);
891
978
  run = latest.run;
979
+ // Answers clear the escalate they answer and nothing else: the PR's current
980
+ // verdict on this review must be that escalate, and no fix-applier on the PR
981
+ // may be working — its landing would answer the review in its own right.
982
+ if (recording) {
983
+ const current = latest.dispositions;
984
+ if (current === null || current.verdict !== "escalate" || current.member !== member.name) {
985
+ die(`PR #${pr}'s current dispositions verdict on review ${run} is ${current === null ? "none" : `${current.verdict} from ${current.member}`}, not an escalate from ${member.name} — escalation answers clear the escalate they answer, and nothing else`);
986
+ }
987
+ if (latest.fixLive.length > 0) {
988
+ die(`${latest.fixLive.join(", ")} still live on PR #${pr} — a fix-applier answering review ${run} has not settled, so the answers wait: settle it, then record them`);
989
+ }
990
+ }
991
+ // Every record judged against this review reads the answers recorded for it.
992
+ // A token that only looks like one answers nothing, and says so.
993
+ const tokens = prTokens(data.rows, pr);
994
+ answers = escalationAnswers(tokens, run);
995
+ for (const t of tokens) {
996
+ if (t.startsWith("escalation-answer=") && escalationAnswerToken(t) === null) {
997
+ console.error(`${NAME}: ignoring malformed token ${t} on PR #${pr}'s row — it answers nothing`);
998
+ }
999
+ }
892
1000
  // Charges are required only on the record answering the PR's first
893
1001
  // review; this record answers `run`, so `run` counts as answered.
894
- charges = firstReview(prTokens(data.rows, pr), [run])?.run === run;
1002
+ charges = firstReview(tokens, [run])?.run === run;
895
1003
  reviewPath = join(scratch, `pr${pr}`, run, "review.json");
896
1004
  }
897
1005
  let review;
@@ -937,17 +1045,44 @@ function main() {
937
1045
  const diffFiles = git(repo, ["diff", "--no-color", "--no-ext-diff", "--no-renames", "--name-only", "-z", base, head],
938
1046
  `list the files of ${base}..${head}`).split("\0").filter(Boolean);
939
1047
 
940
- const { violations, escalations, unchecked } = checkDispositions({
941
- review, record, recordProblem, run, touched: touchedLines(diff), diffFiles, roots: [review.snapshot, top], charges,
942
- filing: { pr, roles, issue: issueReader(repo), verdict: verdictReader(scratch, pr) },
1048
+ const touched = touchedLines(diff);
1049
+ const filing = { pr, roles, issue: issueReader(repo), verdict: verdictReader(scratch, pr) };
1050
+ const judge = (answered) => checkDispositions({
1051
+ review, record, recordProblem, run, touched, diffFiles, roots: [review.snapshot, top], charges, answers: answered, filing,
943
1052
  });
1053
+ let judged = judge(answers);
1054
+ let recorded = [];
1055
+ if (recording) {
1056
+ // The answers go on the row only when they answer exactly what the record
1057
+ // escalates, judged with the answers already there. A record that breaks a
1058
+ // rule has no outside-diff escalate to answer; a finding the record does not
1059
+ // escalate, or an escalated one left unanswered, makes an answer that
1060
+ // settles nothing.
1061
+ if (judged.violations.length > 0) {
1062
+ die(`${member.name}'s record breaks a rule, so its escalate is no outside-diff one: the maintainer's answers clear an escalate whose record breaks none. A broken rule is a mismatch, and after an earlier failure on review ${run} a second failure, which only a new review of the PR clears — run the check without --uphold and --send-back to judge it. It breaks:\n`
1063
+ + judged.violations.map((v) => ` ${member.name}: ${formatViolation(v)}`).join("\n"));
1064
+ }
1065
+ const open = judged.escalations.map((x) => `${x.bucket}[${x.index}]`).sort(byAddress);
1066
+ for (const a of [...listed.keys()].sort(byAddress)) {
1067
+ if (!open.includes(a)) die(`${a} is not one of ${member.name}'s escalated findings${open.length > 0 ? ` (${open.join(", ")})` : " — its record escalates none"}`);
1068
+ }
1069
+ const unanswered = open.filter((a) => !listed.has(a));
1070
+ if (unanswered.length > 0) {
1071
+ die(`${member.name}'s record escalates ${open.join(", ")}, and ${unanswered.join(", ")} ${unanswered.length === 1 ? "has" : "have"} no answer — every escalated finding is answered in one run, with --uphold or --send-back`);
1072
+ }
1073
+ answers = new Map([...answers, ...listed]);
1074
+ judged = judge(answers);
1075
+ recorded = open.map((a) => [a, listed.get(a)]);
1076
+ }
1077
+ const { violations, escalations, unchecked } = judged;
944
1078
  // No ledger, no row: the exit status below is the verdict, and with no
945
1079
  // earlier fix-applier's verdict to count, a broken rule is always a
946
1080
  // mismatch.
947
1081
  // A mismatch an earlier fix-applier already drew on this review makes this
948
- // one the second: it is written as an escalate, which no fix-applier answers.
949
- // A broken rule outranks an escalation, and an escalation a filing the
950
- // tracker could not answer.
1082
+ // one the second: it is written as an escalate, which only a new review of
1083
+ // the PR clears. A finding the maintainer sent back counts as a broken rule
1084
+ // like any other, here and in failedBefore(). A broken rule outranks an
1085
+ // escalation, and an escalation a filing the tracker could not answer.
951
1086
  const secondMismatch = violations.length > 0 && data !== null && failedBefore(data.rows, pr, member, run);
952
1087
  const verdict = violations.length > 0 ? (secondMismatch ? "escalate" : "mismatch")
953
1088
  : escalations.length > 0 ? "escalate" : unchecked.length > 0 ? "unchecked" : "ok";
@@ -957,9 +1092,13 @@ function main() {
957
1092
  const key = row.split(/\s/)[0];
958
1093
  if (!/^#[0-9]+$/.test(key)) die(`the row carrying ${member.name} has no #<n> key for \`ledger.mjs row\` to rewrite it by: ${row}`);
959
1094
  const text = row.slice(key.length).trim();
960
- const updated = withVerdict(text, token);
1095
+ const answerTokens = recorded.map(([a, answer]) => `escalation-answer=${run}:${a}:${answer}`);
1096
+ const updated = withVerdict([text, ...answerTokens].join(" · "), token);
961
1097
  if (updated === text) console.error(` ${member.name}: row ${key} already carries ${token} — not written again`);
962
- else runLedger(ledgerFile, ["row", key, updated], `write ${token} onto row ${key}`);
1098
+ else runLedger(ledgerFile, ["row", key, updated], `write ${recorded.length > 0 ? `the escalation answers and ${token}` : token} onto row ${key}`);
1099
+ }
1100
+ if (recorded.length > 0) {
1101
+ console.error(`${member.name}: recorded the maintainer's escalation answers on review ${run} — ${recorded.map(([a, answer]) => `${a} ${answer === "sent-back" ? "sent back" : answer}`).join(", ")}`);
963
1102
  }
964
1103
 
965
1104
  for (const v of violations) console.error(`${member.name}: ${formatViolation(v)}`);
@@ -268,16 +268,18 @@ export const prTokens = (rows, pr) => streams(rows).get(pr) ?? [];
268
268
  // dispositions-check.mjs's verdict on a review fix-applier's disposition
269
269
  // record: `dispositions-ok=fix-pr-<M>[-x]:<run>`,
270
270
  // `dispositions-mismatch=…`, `dispositions-escalate=…` (a critical or
271
- // important deferral, or a second mismatch on one review, that a human rules
272
- // on) or `dispositions-unchecked=…` (no rule broke, but where a deferral was
273
- // filed could not be read), `<run>` the run of the review the record
274
- // answers, as its `reviewed=` names it. `ledger.mjs dispatch` refuses a
275
- // finisher on anything but an ok. A
276
- // mismatch returns the PR to fixDue for one retry; an escalate is a hold only
277
- // a human answers, so the tick never re-offers the PR for it; an unchecked is
278
- // answered by running the check again, so the tick never offers a
279
- // fix-applier for it either. A token outside this shape is no verdict at all,
280
- // which the gate reads as unchecked: fail closed.
271
+ // important deferral, or a second mismatch on one review, that the
272
+ // maintainer answers) or `dispositions-unchecked=…` (no rule broke, but where
273
+ // a deferral was filed could not be read), `<run>` the run of the review the
274
+ // record answers, as its `reviewed=` names it. `ledger.mjs dispatch` refuses a
275
+ // finisher on anything but an ok. A mismatch returns the PR to fixDue for one
276
+ // retry. An escalate clears one of two ways: the maintainer's escalation
277
+ // answers, recorded through dispositions-check.mjs, replace an escalate over
278
+ // a deferral outside the PR's diff with the verdict they give, and a second
279
+ // mismatch on one review clears only when a new review of the PR counts again
280
+ // from none. An unchecked is answered by running the check again, so the tick
281
+ // offers no fix-applier for it. A token outside this shape is no verdict at
282
+ // all, which the gate reads as unchecked: fail closed.
281
283
  export function dispositionsToken(tok) {
282
284
  const m = /^dispositions-(ok|mismatch|escalate|unchecked)=([^:\s]+):(run-[A-Za-z0-9]{8})$/i.exec(tok);
283
285
  if (!m) return null;
@@ -286,6 +288,38 @@ export function dispositionsToken(tok) {
286
288
  return { verdict: m[1].toLowerCase(), member, run: m[3] };
287
289
  }
288
290
 
291
+ // The maintainer's answer to one finding a fix-applier's record escalated, as
292
+ // dispositions-check.mjs writes it onto the PR's row, and the only writer:
293
+ // `escalation-answer=<run>:<bucket>[<index>]:upheld` (the deferral stands) or
294
+ // `…:sent-back` (the finding is applied in this PR). `<run>` is the run of the
295
+ // review whose escalation it answers, as its `reviewed=` names it, and
296
+ // `<bucket>[<index>]` the finding's address as the check prints it. It is no
297
+ // dispositions verdict and no member, so neither dispositionsToken() nor
298
+ // parseToken() claims it, and a token outside this shape answers nothing.
299
+ const ESCALATION_ANSWER = /^escalation-answer=(run-[A-Za-z0-9]{8}):(survived|unverified|refuted)\[(0|[1-9][0-9]*)\]:(upheld|sent-back)$/;
300
+ export function escalationAnswerToken(tok) {
301
+ const m = typeof tok === "string" ? ESCALATION_ANSWER.exec(tok) : null;
302
+ return m === null ? null : { run: m[1], bucket: m[2], index: Number(m[3]), answer: m[4] };
303
+ }
304
+
305
+ /**
306
+ * The answers `tokens` (prTokens()) carry for review `run`: a Map from a
307
+ * finding's address, `<bucket>[<index>]`, to `upheld` or `sent-back`. An answer
308
+ * recorded against another run counts for nothing, so a new review starts
309
+ * from none. A finding carrying both answers reads as sent back — the stricter
310
+ * reading, as currentDispositions() reads one fix-applier's two verdicts.
311
+ */
312
+ export function escalationAnswers(tokens, run) {
313
+ const answers = new Map();
314
+ for (const tok of tokens) {
315
+ const a = escalationAnswerToken(tok);
316
+ if (a === null || a.run !== run) continue;
317
+ const address = `${a.bucket}[${a.index}]`;
318
+ if (answers.get(address) !== "sent-back") answers.set(address, a.answer);
319
+ }
320
+ return answers;
321
+ }
322
+
289
323
  /**
290
324
  * A PR's first review, read off its `tokens` (prTokens()): walking its
291
325
  * `reviewed=` tokens in ledger order, the first that counted no survived and
@@ -1986,9 +1986,12 @@ function dispositionsRefusal(pr, review) {
1986
1986
  }
1987
1987
  if (v.verdict === "escalate") {
1988
1988
  return `dispositions escalate — ${v.member} deferred a finding above suggestion severity because its remedy lies outside the PR's diff, `
1989
- + "or its record drew a second mismatch on this review; either needs a human's ruling: "
1990
- + `review ${review.run} gets no finisher and no retry; dispositions-check.mjs --member ${v.member} `
1991
- + "--scratch <scratch> names each escalated finding or violating entry by bucket and index, for the PR comment that hands it to a human";
1989
+ + `or its record drew a second mismatch on this review: review ${review.run} gets no finisher until the escalate clears. `
1990
+ + "An outside-diff deferral clears when the maintainer's escalation answers are recorded with "
1991
+ + `dispositions-check.mjs --member ${v.member} --scratch <scratch> --uphold '<list>' --send-back '<list>'; `
1992
+ + "a second mismatch clears only with a new review of the PR. "
1993
+ + `dispositions-check.mjs --member ${v.member} --scratch <scratch> alone names each escalated finding or violating entry by bucket and index, `
1994
+ + "for the PR comment that hands it to the maintainer";
1992
1995
  }
1993
1996
  return null;
1994
1997
  }
@@ -611,14 +611,9 @@ answers that one: the check's stderr names it, and the record's issue number
611
611
  needs correcting); the tick offers no fix-applier for it. `dispositions
612
612
  mismatch` — no finisher: the tick prints `DISPATCH fix-pr PR#<M>` for it, and
613
613
  the next-suffix fix-applier answers it (**Then dispatch a fix-applier**).
614
- `dispositions escalate` — no finisher, no
615
- retry and no further fix-applier: either a `critical` or `important` finding was
616
- deferred `remedy-outside-diff`, or a second mismatch was drawn on one review, and
617
- only a human can rule on either. Post the check's output, which names each
618
- escalated finding or violating entry, with `gh pr comment <M>`, and flag the PR
619
- for a human; re-running the check reprints it. Dispatch no fix-applier and no
620
- finisher for that review, and expect no `fix-due` row for it; a new
621
- review of the PR starts the check again. **On any PR with a
614
+ `dispositions escalate` — no finisher, no `fix-due` row: a finding above
615
+ `suggestion` deferred `remedy-outside-diff` clears with the maintainer's answers,
616
+ a second mismatch only with a new review (**Dispositions escalation**). **On any PR with a
622
617
  returned review, `0/<n>/0` included, it refuses too while a fix-applier on the
623
618
  PR is still live, verdict or not** —
624
619
  `fix-pr-<M>[-x] still live`: settle it, run the check for it, then dispatch
@@ -783,9 +778,14 @@ re-run the check for the mismatched member to reprint them. It writes its own
783
778
  record, and when it reports you run the check for it exactly as for the first
784
779
  one. `ok` ends it. A second failure on the same review is written as
785
780
  `dispositions-escalate=fix-pr-<M>-b:<run>` in place of a mismatch: the tick
786
- prints no `DISPATCH fix-pr` for it, `dispatch` refuses the finisher naming
787
- `dispositions escalate`, and you post the check's output with `gh pr comment <M>`
788
- and flag the PR for a human. A new review of the PR counts again from none.
781
+ prints no `DISPATCH fix-pr` for it. Post the check's output with
782
+ `gh pr comment <M>`. A second failure is flagged for a human. A new review of
783
+ the PR counts again from none. An escalate whose check printed no violations is
784
+ the maintainer's to answer instead, one yes/no per escalated finding: yes upholds
785
+ the deferral, no sends it back to be applied in this PR. With every finding
786
+ explicitly answered this session, record them with `dispositions-check.mjs`
787
+ `--uphold` and `--send-back`: `ok` gets the finisher, `mismatch` the tick's
788
+ retry, `escalate` is a second failure. See references/dispositions-escalation.md.
789
789
 
790
790
  ### The main-gain hit
791
791
 
@@ -0,0 +1,36 @@
1
+ # Dispositions escalation: what you do with an escalate
2
+
3
+ What SKILL.md's **Dispositions escalation** points at: the message, the records and the comment that clear a `dispositions escalate` whose check printed no violations — a `critical`, `important` or severity-less finding a fix-applier deferred `remedy-outside-diff`, its record breaking no rule. An escalate whose check printed violations is a second mismatch on one review: no answer clears it, you comment and flag the PR for a human, and a new review of the PR counts again from none.
4
+
5
+ ## Ask the maintainer
6
+
7
+ Post the check's output with `gh pr comment <M>`: it names each escalated finding, and re-running the check for the escalated member reprints it. Then put one message to the maintainer, with one yes/no for each escalated finding. Each finding is named by:
8
+
9
+ - its address, `<bucket>[<index>]` as the check printed it, its severity and its claim, read from `<scratch>/pr<M>/<run>/review.json`;
10
+ - its remedy files, as the check printed them;
11
+ - the issue it was filed to and the fix-applier's reason, read from the escalated member's record `<scratch>/dispositions-<member>.json`.
12
+
13
+ Yes means upheld: the deferral stands. No means sent back: the finding is applied in this PR.
14
+
15
+ Record nothing until every finding has an answer, and nothing without the maintainer's explicit answer in this session. Answers arrive in pieces, so hold each until the last is in; silence, a default and your own reading of the finding are no answer.
16
+
17
+ ## Record the answers
18
+
19
+ On the answers, in this order:
20
+
21
+ 1. Run `dispositions-check.mjs --member <member> --scratch <scratch> --uphold '<list>' --send-back '<list>'`, `<member>` the escalated fix-applier and each list the findings answered that way, `<bucket>[<index>]` separated by commas. Quote each list — `[` opens a glob under zsh — and pass a flag only for a list that has a finding in it. One write puts an `escalation-answer=<run>:<bucket>[<index>]:upheld|sent-back` token per finding on the PR's row and replaces the escalate with the verdict the answers earn. It refuses instead, exit 2 and the ledger untouched, naming the cause: the PR's current verdict on its latest review is not an escalate from that member, a fix-applier on the PR is live, the record breaks a rule, a finding is not one the record escalates or is listed twice or both ways, or an escalated finding has no answer.
22
+ 2. Record one line per finding: `ledger.mjs ruled <M> "escalation answer <bucket>[<index>]: upheld|sent back — <reason>"`, the maintainer's reason.
23
+ 3. Post one PR comment under the escalate comment, quoting the answers.
24
+
25
+ The verdict then decides what follows:
26
+
27
+ - `ok`: dispatch the finisher, as for any `ok`. An upheld finding passes; its deferral is judged by every other rule as before.
28
+ - `mismatch`: a sent-back finding is a broken rule, so the tick prints `DISPATCH fix-pr PR#<M>` and the retry runs as any mismatch's does. The retry's `--violations` are the check's lines as printed, the sent-back ones included; re-run the check for the member to reprint them. The retry's record is judged with the answers: deferring a sent-back finding again, for any reason, is a second failure, and applying it while deferring an upheld one `remedy-outside-diff` passes.
29
+ - `escalate`: an earlier fix-applier on the review had already failed, so the send-back is the second failure. Comment, flag the PR for a human, and a new review of the PR counts again from none.
30
+ - `unchecked`: the answers are recorded, but a filing could not be read. Run the check again once `gh` answers; it reads the answers already on the row.
31
+
32
+ An answer belongs to one review. A new review counts from none, so the same finding deferred again on it escalates again.
33
+
34
+ ## Any other answer
35
+
36
+ The maintainer may rule otherwise: close the PR, re-review it. Record `ledger.mjs ruled <M> <decision>` and carry it out.