@feigi/fleet-ctl 3.88.13 → 3.89.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feigi/fleet-ctl",
-  "version": "3.88.13",
+  "version": "3.89.0",
   "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
   "license": "Apache-2.0",
   "repository": {

package/scripts/ledger.mjs

@@ -846,7 +846,7 @@ if (cmd === "read") {
 } else if (cmd === "check") {
   runCheck();
 } else if (cmd === "dispatch") {
-  runDispatch();
+  await runDispatch();
 } else if (cmd === "settle") {
   if (FROM_REPORT) await runSettleFromReport();
   else runSettle();
@@ -1894,6 +1894,36 @@ function dispositionsRefusal(pr, review) {
   return null;
 }
 
+// Why PR `pr`'s finisher waits on its ruling, or null when it does not: the
+// PR is an implementer's — a settled `impl-<N>=PR#<pr>` token on a row names
+// it, the token tier-outcomes.mjs `append` resolves a ticket from — and the
+// main checkout's tier-outcomes.tsv has no row whose `pr` is it. Any row
+// passes, whatever its date or verdicts, so a replacement finisher is never
+// held once the first passed. The ledger lives in the main checkout's
+// `.fleet/` (fleet-dir.mjs), so the file is found beside that directory —
+// no git, no gh. A missing file is no row (`append` creates it); one that
+// cannot be read or parsed refuses, naming it, and is never a pass.
+// tier-outcomes.mjs is imported here, not at the top: its import graph is
+// several modules no other subcommand loads.
+async function rulingRefusal(pr) {
+  const { parseTierOutcomes, implementerClaims } = await import("./tier-outcomes.mjs");
+  const tickets = [...new Set(implementerClaims(data, pr).map((c) => c.ticket))];
+  if (tickets.length === 0) return null;
+  const tsv = join(dirname(dirname(resolve(file))), "docs", "metrics", "tier-outcomes.tsv");
+  if (existsSync(tsv)) {
+    let rows;
+    try {
+      rows = parseTierOutcomes(readFileSync(tsv, "utf8"));
+    } catch (e) {
+      return `cannot read the PR's ruling off ${tsv}: ${e.code ?? e.message} — fix the file, then dispatch the finisher again`;
+    }
+    if (rows.some((r) => r.pr === String(pr))) return null;
+  }
+  return `PR #${pr}, the implementer PR of ${tickets.length === 1 ? "ticket" : "tickets"} ${tickets.map((n) => `#${n}`).join(", ")}, has no ruling — `
+    + `${tsv} has no row for it; rule its review with \`~/.fleet/bin/fleet-run tier-outcomes.mjs append ${pr} --closed-own-ticket yes|no `
+    + `--minted-false-claim yes|no --note "<text>"\`, then dispatch the finisher again`;
+}
+
 // The open `ready-to-merge` PRs, ascending, as gh answers from the ledger's
 // own directory with runCheck()'s environment: the queue a merge bot is
 // dispatched against, recorded on its `## Dispatched` entry. Anything but a
@@ -1925,7 +1955,7 @@ function queueSnapshot() {
   return [...new Set(prs)].sort((a, b) => a - b);
 }
 
-function runDispatch() {
+async function runDispatch() {
   const usage = "usage: ledger.mjs dispatch <ticket|pr> <member>, or dispatch merge-bot";
   if (rest.length === 0 || rest.length > 2) die(usage);
   const [key, name] = rest.length === 2 ? rest : [null, rest[0]];
@@ -2047,8 +2077,11 @@ function runDispatch() {
   // run the tick reads — and no fix-applier on the PR is still live. A PR
   // whose latest review counts no survived and no unverified finding had
   // nothing for a fix-applier to rule on, and one never reviewed has no
-  // review file: neither is gated on a verdict. Refused here, before anything
-  // is written, so the check cannot be skipped by forgetting to run it.
+  // review file: neither is gated on a verdict. Then an implementer's PR
+  // waits on its ruling, its tier-outcomes row, written while the PR is open
+  // and its review evidence still in scratch; see rulingRefusal(). Refused
+  // here, before anything is written, so no check can be skipped by
+  // forgetting to run it.
   if (member.family === "finisher-pr") {
     const fold = tickFold("conflict hold and dispositions verdict");
     if (fold.conflictHeld.includes(member.number)) {
@@ -2056,7 +2089,7 @@ function runDispatch() {
         + `and let it settle applied:/no-op, then dispatch the finisher again — not dispatching ${member.name}`);
     }
     const review = fold.reviewed.find((r) => r.pr === member.number);
-    const refusal = dispositionsRefusal(member.number, review);
+    const refusal = dispositionsRefusal(member.number, review) ?? await rulingRefusal(member.number);
     if (refusal !== null) die(`${member.name}: ${refusal} — not dispatching ${member.name}`);
   }
   // Every error caught here carries its own cause and remedy — a row's `tier=`

package/scripts/tier-outcomes.mjs

@@ -495,7 +495,8 @@ function closingNumbers(pr) {
 
 // Every settled `impl-<N>=PR#<pr>` token in the run ledger's rows, each with the
 // row that carries it and its ticket N. The dispatched list is not read.
-function implementerClaims(ledger, pr) {
+// Exported for ledger.mjs's finisher dispatch, which gates the same PRs.
+export function implementerClaims(ledger, pr) {
   const claims = [];
   for (const text of ledger?.rows ?? []) {
     const key = text.split(/\s/)[0];

package/skills/run-team/SKILL.md

@@ -195,9 +195,9 @@ owes beyond its call:
      once the run is draining with no open PR and no live implementer.
   3. `~/.fleet/bin/fleet-run closeout.mjs finish --reason "<reason>"`, which
      then records `fleet-heartbeat.mjs --stop` last, because every reader takes
-     a recorded stop as the end of the run. A `NEED tier-outcomes append
-     <pr>` is a PR the ledger marks reviewed with no verdict row: append it with
-     the verdict you rule (**Guard: accumulate per PR**) and run `finish` again.
+     a recorded stop as the end of the run. A `NEED tier-outcomes append <pr>`
+     is a reviewed PR with no verdict row — for an implementer's, one that never
+     reached its finisher: append it with the verdict you rule (**Guard: accumulate per PR**) and run `finish` again.
      A PR closing none or several: a row only if an impl token names it.
      A step it fails is explained in references/close-out.md. Exit 0 is the run
      closed.
@@ -280,10 +280,10 @@ digest asks of you:
 **A refutation resting on an injection nothing proved landed is not a refutation — it is a cell that never ran.** See references/reviewers.md.
 
 **Guard: accumulate per PR, never conclude inside one run.** **Append one row to
-`docs/metrics/tier-outcomes.tsv` when you rule each PR's review, with
+`docs/metrics/tier-outcomes.tsv` when you rule each PR's review, before its finisher, with
 `~/.fleet/bin/fleet-run tier-outcomes.mjs append <pr> --closed-own-ticket yes|no --minted-false-claim yes|no --note "<text>"`,
 never by hand** (that file's header carries the column meanings). The script
-fills `tier` itself; never type one in. That append is the whole duty. See references/pull.md.
+fills `tier` itself; never type one in. `ledger.mjs dispatch` refuses the finisher until the row exists. That append is the whole duty. See references/pull.md.
 
 **A verdict is a measurement only if it post-dates the run that produced it.** See references/reviewers.md.
 
@@ -520,7 +520,7 @@ Pointers: the `/resume` rules are in `references/phase-0.md`; the tick HOLD tier
 
 ## The finisher gate
 
-Dispatch a finisher only when every test here passes at once — the review returned, the fix-applier's report arrived, your outbox to it is empty and no ruling is owed; hold otherwise, and on a repo with no CI and no declaration report it and add no label.
+Dispatch a finisher only when every test here passes at once — the review returned, the fix-applier's report arrived, your outbox to it is empty, no reply is owed and the PR's ruling is recorded; hold otherwise, and on a repo with no CI and no declaration report it and add no label.
 
 ### The tests
 
@@ -542,8 +542,8 @@ Dispatch a finisher only when every test here passes at once — the review retu
   by name. An empty outbox catches neither — *vacuously* empty on the
   implementer's firing, *genuinely* empty on a mid-work push. **The outbox is
   the last test, not the only one, and it stands wherever a fix-applier
-  exists**, so never dispatch off it while you do owe it a ruling: empty it
-  first — including any ruling you have withdrawn or reversed — then dispatch
+  exists**, so never dispatch off it while you do owe it a reply: empty it
+  first — including any reply you have withdrawn or reversed — then dispatch
   (below); a final report is not proof it stopped. A PR that needs nothing fixed
   reaches a finisher through the **fix-applier reports `no-op`** bullet below,
   never by waiting for a second CI event; a red that fired before the review
@@ -560,7 +560,7 @@ Dispatch a finisher only when every test here passes at once — the review retu
   itself, so nothing further is owed and no further event is coming. Edit either bullet without the other and what strands is exactly the PR that needed no fixes.
 - **`ci-state.mjs --pr <N>` reads `verdict: "no-ci"`** → the CI edge never
   fires: dispatch the finisher off the reviewer's final verdict the moment it
-  lands, never while you still owe it a ruling. Its gate is then the
+  lands, never while you still owe it a reply. Its gate is then the
   `--declare-no-ci` declaration, not a `check` job: with it, label off the
   reviewer's verified suite run; **without it, do not label** — report that this
   repo has no CI configured and no declaration, and stop. See `review-and-fix.md` step 6.
@@ -593,9 +593,9 @@ with `dispatch-prompt.mjs render finisher --kind fresh --member finisher-pr-<pr#
 (`--kind repair` once an earlier finisher reported `labelled` without the label landing), record it with
 `ledger.mjs dispatch <pr#> finisher-pr-<pr#>` before the call, then **dispatch
 it with the `agent` that command printed and omit `model` on the call**. **Never dispatch
-one while you still owe the fix-applier a ruling. The test is your OUTBOX, not the
+one while you still owe the fix-applier a reply. The test is your OUTBOX, not the
 member's last message** — anything you have decided that it has not received,
-including a ruling you have since **withdrawn or reversed**, a withdrawal
+including a reply you have since **withdrawn or reversed**, a withdrawal
 recorded only in the ledger included. **That is the test of THIS condition
 only**: the report condition above is the other. Relay everything — reversals
 too — then dispatch. See references/finisher.md.
@@ -642,7 +642,7 @@ merge, and a finisher on it would race the conflict fix-applier rebasing it.
 Dispatch that fix-applier, let it settle `applied:`/`no-op`, then dispatch the
 finisher again.
 
-**An unanswered question from the member is an outbox item, and it blocks dispatch with the same weight as a ruling you have already made.** See references/finisher.md.
+**An unanswered question from the member is an outbox item, and it blocks dispatch with the same weight as a reply you have already decided on.** See references/finisher.md.
 
 **A final report is not proof the member stopped.** **The standing CI facts are
 in the fix-applier body, not in per-event messages.**

package/skills/run-team/references/close-out.md

@@ -22,8 +22,10 @@
      metrics, commits the three metrics files and opens their PR, sets the
      phase-0 receipt aside as `.fleet/phase0.previous.json`, then records
      `fleet-heartbeat.mjs --stop` last, because every reader takes a recorded
-     stop as the end of the run. A `NEED tier-outcomes append <pr>` is a PR
-     the ledger marks reviewed with no verdict row: append it with the verdict
+     stop as the end of the run. A `NEED tier-outcomes append <pr>` is a
+     reviewed PR with no verdict row — for an implementer's PR, one that never
+     reached its finisher, since `ledger.mjs dispatch` refuses that finisher
+     until the row exists: append it with the verdict
      you rule (**Guard: accumulate per PR**) and run `finish` again. A reviewed
      PR that closes no issue, or several, with no settled `impl-<N>=PR#<pr>`
      token naming it takes no row: the check names it in a `note` line and

package/skills/run-team/references/finisher.md

@@ -28,10 +28,10 @@ Its four duties are a checklist — audit the
 worktree, confirm every deferral has a tracker home and re-run the acceptance
 mutation, apply one release label, report — and the
 merge gate downstream still catches whatever it gets wrong. **Never dispatch
-one while you still owe the fix-applier a ruling**: the pinned SHA is only as good
+one while you still owe the fix-applier a reply**: the pinned SHA is only as good
 as the guarantee nothing else is inbound. **The test is your OUTBOX, not the
 member's last message** — anything you have decided that it has not received,
-including a ruling you have since **withdrawn or reversed**. **That is the test
+including a reply you have since **withdrawn or reversed**. **That is the test
 of THIS condition only**: an empty outbox says nothing is inbound from you, and
 nothing about whether the member considers itself finished, which is what the
 report condition above is for. A withdrawal you
@@ -71,9 +71,9 @@ and will act on it. Relay everything — reversals too — then dispatch.
   anything to, so the outbox is *vacuously* empty, and on a fix-applier's
   mid-work push nothing has been sent since the dispatch, so it is *genuinely*
   empty. **The outbox is the last test, not the only one, and it stands wherever
-  a fix-applier exists** — that is exactly where a ruling you still owe it is
+  a fix-applier exists** — that is exactly where a reply you still owe it is
   outstanding, so never dispatch off it while you do. Empty your outbox to it
-  first — including any ruling you have withdrawn or reversed — then dispatch
+  first — including any reply you have withdrawn or reversed — then dispatch
   (*The fix-applier pushes and exits; the finisher is dispatched fresh*); a final report is not proof it stopped. A PR that needs nothing fixed
   reaches a finisher through the **fix-applier reports `no-op`** bullet below,
   never by waiting for a second CI event this head will never produce. The
@@ -102,12 +102,21 @@ and will act on it. Relay everything — reversals too — then dispatch.
   waiting for it stalls the whole PR — the same silent-stall shape reported
   before this verdict existed. Dispatch the finisher off the reviewer's final
   verdict instead, the moment it lands — and, same as above, never while you still
-  owe it a ruling — or hold anything else it has not received, a ruling you have
+  owe it a reply — or hold anything else it has not received, a reply you have
   withdrawn or reversed included. The finisher's gate is then the
   `--declare-no-ci` declaration, not a `check` job: with it, label off the
   reviewer's verified suite run; **without it, do not label** — report that this
   repo has no CI configured and no declaration, and stop. Absence never reads as
   pass. See `review-and-fix.md` step 6.
+- **The PR's ruling is recorded** → an implementer's PR, one a settled
+  `impl-<N>=PR#<M>` token on the ledger names, gets its finisher only once the
+  main checkout's `docs/metrics/tier-outcomes.tsv` has a row for it, appended
+  when you rule its review (SKILL.md's **Guard: accumulate per PR**).
+  `ledger.mjs dispatch` refuses the finisher until that row exists, after its
+  conflict-hold and dispositions refusals, and prints the `tier-outcomes.mjs
+  append` command to run. Any row for the PR passes, so a replacement finisher
+  is never held once the first passed; a PR no such token names is not gated.
+  No flag skips it: a PR `append` refuses is fixed on the ledger, as at close-out.
 
 Gate on the `check` job, **not** on `ci-state --quiet` exit 0: a behind PR never
 reaches full green, so an exit-0 gate strands it unlabelled. The finisher reads
@@ -138,7 +147,7 @@ no verified suite run on record` and add no label.
 ## An unanswered question from the member is an outbox item
 
 **An unanswered question from the member is an outbox item, and it blocks
-dispatch with the same weight as a ruling you have already made.** It does not
+dispatch with the same weight as a reply you have already decided on.** It does not
 feel like one — you have decided nothing yet, so the outbox reads empty — but a
 member waiting on you is a member that will push once you answer, and the SHA
 you are about to pin is exactly what that push moves. Measured on one run: