@feigi/fleet-ctl 3.86.0 → 3.86.1

package/commands/review-and-fix.md

@@ -76,7 +76,7 @@ jq '.refuted' "$R"                                               # refuted: your
 
 `eval` loading `scripts/review-eval.mjs` through the Resolver (`fleet-run --path review-eval.mjs`) and calling `runReviewOnOmp({pr, branch, worktree, testCmd, scratch})` is the fleet's **default** review path. Its `scratch` is the scratch root, never `<scratch>/pr<N>`: the review creates that partition itself and refuses a `scratch` already ending in one, or one that is not an absolute path.
 
-`$(~/.fleet/bin/fleet-run --root)/skills/run-team/SKILL.md`'s Reviewers section owns its dispatch. It cuts the snapshot, sizes the fan-out, adversarially verifies every **critical/important** finding, and has `agent()` return **into the script**, so no report can go undelivered, the failure that cost one fleet five reports on one PR and four on another. It does **not** verify the `suggestion` band — that gets 0 refuters by policy, which is why step 2 checks each one itself — an in-scope one before applying it, an out-of-scope one above the claim bar before filing it. **You cannot run it** — the one member that runs it is the `review-pr-<pr#>` runner (`agents/fleet-review-runner.agent.md`), never a reader of this file.
+`$(~/.fleet/bin/fleet-run --root)/skills/run-team/SKILL.md`'s **The reviewer** bullet owns its dispatch, and `references/reviewers.md` (**A review runs off your turn and relays nothing**) says what it does. It cuts the snapshot, sizes the fan-out, adversarially verifies every **critical/important** finding, and has `agent()` return **into the script**, so no report can go undelivered, the failure that cost one fleet five reports on one PR and four on another. It does **not** verify the `suggestion` band — that gets 0 refuters by policy, which is why step 2 checks each one itself — an in-scope one before applying it, an out-of-scope one above the claim bar before filing it. **You cannot run it** — the one member that runs it is the `review-pr-<pr#>` runner (`agents/fleet-review-runner.agent.md`), never a reader of this file.
 
 It cannot ask the user anything and cannot wait on CI — rebasing, watching checks, binding and labelling stay here.
 

package/package.json

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

package/scripts/compute-spend.mjs

@@ -167,8 +167,8 @@ function roleFromNamePatterns(hay) {
   // dispatch against an ALREADY-OPEN PR, not new ticket work — measured
   // meta.json descriptions "Resolve conflict on PR <n>" and "Rebase and
   // resolve conflicts for PR #<n>", the same rebase/conflict-resolver shape
-  // `run-team/SKILL.md` calls "a rebase-resolver" sent into an open PR's
-  // worktree. It carries no ticket, no dispatch counter and no new-work verb —
+  // `run-team/references/isolation.md` calls "a rebase-resolver" in a prior-run
+  // worktree, here sent into an open PR's worktree. It carries no ticket, no dispatch counter and no new-work verb —
   // only a PR number — so it is remediation on that PR's path to merge,
   // exactly the category `fix-pr-<n>`'s applier already occupies here. It is
   // NOT `merge-bot`: that bucket's number is a per-run dispatch counter, never

package/scripts/fleet-heartbeat.mjs

@@ -13,7 +13,7 @@
 // WHY A HOLD AND NOT A WATCHER — the ruling, measured before it was made:
 //
 //   A backgrounded watcher does not wake an idle agent. Measured twice in one
-//   run (run-team/SKILL.md, "A member runs its test suite in the foreground"):
+//   run (run-team/references/member-lifecycle.md, "A member runs its test suite in the foreground"):
 //   `fix-pr-1184` backgrounded its suite plus a Monitor and sat idle for
 //   roughly two hours; neither ever woke it. run-merge-bot.md's CI gate states
 //   the same rule as a rule — "whatever wakes you is external and may never
@@ -28,7 +28,7 @@
 //   do.
 //
 // WHY IT TAKES NO CONTROLLER STATE — every flag below has a default. A monitor
-// event is a wake-up, never a verdict (SKILL.md's Monitor rules), so this
+// event is a wake-up, never a verdict (run-team/SKILL.md, "A monitor event is a wake-up, never a verdict"), so this
 // script never reads or reports fleet state: counts captured before a
 // twenty-minute hold and printed after it are a stale verdict, and a stale
 // verdict is how a reconcile prints an ACTION nobody can take. The controller

package/scripts/fleet-tick.mjs

@@ -239,8 +239,9 @@ const mkRow = (role, actual, target, detail) => (action, { acts = false, extra =
 // transcript; the session directory is the phase-0 receipt's, which
 // tier-check.mjs reads itself when an entry omits it. Without a receipt of
 // this run, `<session>` stays a placeholder the controller fills in, as
-// `<file>` does — one batch file, one entry per held member (SKILL.md's
-// phase-2 tier check).
+// `<file>` does — one batch file, one entry per held member, the shape under
+// **The batch file is a JSON array, one entry per dispatched member** in
+// run-team/references/tick-rows.md.
 const tierCheckStep = (members, session) => "run ~/.fleet/bin/fleet-run tier-check.mjs --batch <file> with "
   + JSON.stringify(members.map((member) => (session ? { member } : { member, session: "<session>" })));
 

package/scripts/ledger.mjs

@@ -293,15 +293,16 @@ if (!cmd) die("usage: ledger.mjs [--file <path>] [--require-file] row|token|file
 // the documented convention IS one quoted argument, and `check` is the only
 // subcommand where it is: every caller that instructs running it spells it
 // `ledger.mjs check "<subject>"` (the finisher's deferred-finding filing duty,
-// review-and-fix's filing step), while run-team/SKILL.md's ledger section
-// spells the other three `filed <issue> <subject>`, `row <ticket> <text>` and
-// `ruled <pr> <decision>` — a bare multi-word tail, as did this file's own
-// usage strings for them. Applied there, the rule refused what the docs
-// prescribe: measured on the tree ahead of this narrowing, `filed 999 the
+// review-and-fix's filing step), while run-team/SKILL.md, as it stood when
+// this was measured, spelled the other three `filed <issue> <subject>`,
+// `row <ticket> <text>` and `ruled <pr> <decision>` — a bare multi-word tail,
+// as did this file's own usage strings for them. Applied there, the rule
+// refused what the docs prescribed: measured on the tree ahead of this
+// narrowing, `filed 999 the
 // --basee flag is unread`, `row 42 the --basee flag is unread` and `ruled 77
 // the --basee flag is unread` each exited 2, where the tree before this guard
 // existed answered all three at exit 0. The guard was ruled back to
-// `check` rather than respelling three conventions SKILL.md carries, two
+// `check` rather than respelling three conventions SKILL.md then carried, two
 // other tickets holding that file open.
 //
 // Stated here and nowhere else. This paragraph is the one copy of why
@@ -329,9 +330,9 @@ if (!cmd) die("usage: ledger.mjs [--file <path>] [--require-file] row|token|file
 // 2 now. Quoting the subject accepts it unchanged. The trade taken
 // is that this refusal is loud and recoverable where the wrong-subject
 // answer it replaces was silent. One residual of that trade is not this
-// file's to close: SKILL.md's ledger section spells `check <subject>`
-// unquoted inside the same entry that spells `filed <issue> <subject>`, where
-// the instructions that tell a caller to RUN it quote the subject.
+// file's to close: run-team/references/ledger.md's `filed and ruled` section
+// spells `check <subject>` unquoted, where the instructions that tell a caller
+// to RUN it quote the subject.
 //
 // Narrowed on `check` too, not closed: a lone stray with no subject beside it
 // is a one-element tail, so it is still taken as the subject and answered at
@@ -652,15 +653,15 @@ async function acquireLock() {
       // indistinguishable at this instant from a live reaper mid-takeover.
       // Naming the pid alone points an operator at a process that no longer
       // exists; naming `${REAP}` is what lets them find the file
-      // `run-team/SKILL.md`'s runbook tells them to remove by hand, once
-      // nothing is writing.
+      // run-team/references/ledger.md's Writer policy section tells them to
+      // remove by hand, once nothing is writing.
       if (dead) {
         die(`cannot lock ${file} — held by pid ${pid}, which is dead; ${REAP} is blocking its takeover — if nothing is currently writing, remove it by hand`);
       }
       // No pid at all is the other permanent wedge pid-lock.mjs's header describes: an
       // empty or partial `${LOCK}` whose writer died before writing its pid,
       // read as live forever by design. There is no process to point at, so
-      // name `${LOCK}` itself — the file the same runbook says to remove.
+      // name `${LOCK}` itself — the file the same Writer policy section says to remove.
       if (pid === null) {
         die(`cannot lock ${file} — ${LOCK} holds ${JSON.stringify(holder)}, not a pid, so it is never taken over — if nothing is currently writing, remove it by hand`);
       }
@@ -2087,8 +2088,9 @@ function runDispatch() {
     line = `#${member.number} ${member.name}`;
     data.rows.push(line);
   } else if (i !== -1) {
-    // A row `row` already wrote the live token into (SKILL.md's phase 2
-    // does) keeps it as it is rather than gaining a second copy.
+    // A row `row` already wrote the live token into (run-team/SKILL.md's
+    // `NEED resume` bullet records the row with `ledger.mjs row` before
+    // `ledger.mjs dispatch`) keeps it as it is rather than gaining a second copy.
     const row = data.rows[i];
     line = carries(row, member.name, true) ? row : `${row} · ${member.name}`;
     data.rows[i] = line;

package/scripts/staleness.mjs

@@ -125,8 +125,8 @@ if (!path) die("--path <path> is required");
 // both would refuse, the more specific wording wins, and nothing above here
 // has run a git call.
 //
-// One consequence the caller has to be told about, so run-team/SKILL.md says
-// it too: a needle that starts with `--`, given BARE, never reaches this
+// One consequence the caller has to be told about, so run-team/references/pull.md
+// says it too: a needle that starts with `--`, given BARE, never reaches this
 // script's question — `arg()` refuses it as a missing value, at exit 2, which
 // is the verdict that keeps the ticket in the queue. `--gone -- '<value>'`
 // (separatedNeedles() above) is the opt-in past that, one flag at a time.

package/scripts/tier-check.mjs

@@ -5,7 +5,7 @@
 // what omp's own record says it RESOLVED, for every member dispatched by
 // named definition. Not a lint — a refusal, run after every Pull's dispatch,
 // whose verdict on an implementer lands on the ledger, where fleet-tick.mjs
-// holds the next Pull until there is one (run-team/SKILL.md's phase 2).
+// holds the next Pull until there is one (run-team/SKILL.md, **The tier check**).
 //
 // Declared is the definition's own frontmatter — `model: "@<role>:<level>"`,
 // a fleet tier route, never a vendor id. Resolved is read back
@@ -48,10 +48,11 @@
 // A batch file, not one member: `--batch` takes a JSON array, and the
 // failure line — `member: declared <m>/<l> resolved <m>/<l>` — is printed
 // once per member that mismatched, not once per invocation. Under Pull,
-// run-team's phase 2 calls this after every Pull's dispatch with a batch of
-// one, the member just dispatched. See run-team/SKILL.md's phase-2 dispatch
-// paragraph for the batch file's exact entry shape and how the controller
-// obtains each field.
+// run-team runs this after every Pull's dispatch with a batch of one, the
+// member just dispatched (run-team/SKILL.md, **The tier check**). The batch
+// file's exact entry shape and how the controller obtains each field are under
+// **The batch file is a JSON array, one entry per dispatched member** in
+// run-team/references/tick-rows.md.
 //
 // An implementer (`impl-<N>`, ledger-grammar.mjs's name) is judged on the
 // ledger's terms, not the caller's: the definition it should have
@@ -194,12 +195,14 @@ export function formatOmpExpectation(r) {
 // held rather than replacing it, since `row` rewrites the whole line
 // (ledger.mjs's `data.rows[i] = line`) and a bare mismatch note would drop
 // `class=`, `KILLED` or `→ PR#` tokens a prior `row` call wrote for the same
-// ticket. Idempotent on the identical note: the documented loop is check,
-// fix, re-check (SKILL.md's "fix the definition or the dispatch and re-run
-// the check before continuing"), and a member that still mismatches for the
-// SAME reason on a later run must not grow the row a second time — a
-// DIFFERENT note (a changed pair) still appends, since that is new
-// information the row does not carry yet.
+// ticket. Idempotent on the identical note: the check can run again for a
+// member it already judged, while what clears a mismatch is a new member
+// (run-team/SKILL.md, **The tier check**: "Clear a mismatch by fixing the
+// definition or the dispatch and dispatching the replacement at the right
+// tier"), so a re-run that finds the SAME pair for the SAME member adds
+// nothing and must not grow the row a second time — a DIFFERENT note (a
+// changed pair, or the replacement's own line, which names the replacement)
+// still appends, since that is new information the row does not carry yet.
 export function appendedLedgerText(existingText, mismatchNote) {
   const trimmed = String(existingText ?? "").trim();
   if (!trimmed) return mismatchNote;

package/scripts/tier-outcomes.mjs

@@ -92,7 +92,8 @@ const LEDGER_SCRIPT = join(SCRIPT_DIR, "ledger.mjs");
 // ---------------------------------------------------------------------------
 
 // APPENDED TO, never inserted into: every awk read-out in the file's header
-// and in run-team/SKILL.md indexes by position.
+// and in run-team/references/pull.md (**Accumulate per PR, never conclude a
+// tier result inside one run**) indexes by position.
 export const COLUMNS = Object.freeze([
   "run_date", "pr", "ticket", "class", "tier", "closed_own_ticket",
   "minted_false_claim", "note", "sizing", "profile", "loc", "files",