@feigi/fleet-ctl 3.86.0 → 3.87.0

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/commands/run-merge-bot.md

@@ -237,6 +237,8 @@ For each labeled PR clearing the hold rule, lowest first:
 
    - **`head-moved-after-label`** — the PR head is neither `pre` nor `post`, nor a head whose net change the gate proved identical to `pre`'s (`rebaseCarry`, which names both). **Any third SHA is a push that landed while you waited on CI, and no CI check can see it**: `ci-state.mjs` selects the run whose `headSha` equals the *current* PR head (`scripts/ci-state.mjs`, the `r.headSha === prHead` filter), so a member's push plus its own green run satisfies every CI check while the audit behind the label belongs to a tree that is gone. A carry is proven only for the head `gh pr view` read; a different head at `ci-state`'s own read is still this row. The remedy is a fresh finisher against the new head, label untouched.
    - **`main-gain-removed:<path>`** — merging this head would remove lines `main` gained after the PR's work began: lines a later merge landed, deleted by a branch commit that every rebase since has replayed without a conflict, so no conflict preview and no `origin/main...HEAD` read is sure to show them. `mainGain.hits[]` names each file, the landing key (`#<n>` for a merged PR, else the landing commit's 12-character SHA), the removed lines, and the `ack` line to copy. Skip the PR, leave the label alone, and report `main-gain-removed:<path>-#<pr>` with the hit list and the keys. Never restore the lines yourself — the removal may be deliberate. It clears when the PR stops removing them or its body carries `main-gain-removal: <path> <key> - <why>` for every hit; the gate reads the body each run, so editing it is enough. An acknowledged removal is listed in `mainGain.acknowledged[]` and the gate passes it — name each one, with its reason, in your report. Your report's `refused[]` entry for the PR carries the gate's `reason` as it printed it, `main-gain-removed:<path>`, and the gate's `--out` file above stays where the gate wrote it: the controller parks the PR off that entry, at the `head` and `bodyDigest` that file records the gate refused, and no merge bot is dispatched on the PR's account until its head or its body changes — though a bot dispatched for another queued PR may still evaluate it again.
+
+     Each hit line carries a `kind`: `modified` when the hunk that removed it also adds lines, none of which claimed it as an in-place edit, or `deleted` when the hunk only removes lines. A removed line edited in place that keeps every token of its text is not a hit; the gate lists it in `mainGain.edited[]` and passes it.
    - **`main-gain-unanswerable`** — the main-gain check could not answer: a head object the main checkout does not hold after `git fetch origin`, a merge that does not resolve cleanly, a blame that failed. `mainGain.reason` says which. Stop and report `main-gain-unanswerable-#<pr>` with it, label untouched.
    - **`behind:<n>`** — you are the only place currency is proven, and a sibling merge since your rebase expires it (the staleness below).
    - **`instrument-set-changed` / `instruments-unanswerable`** — the instrument re-check the controller runs before its own gates (`run-team/SKILL.md`, **You read your instruments out of a tree every member can write to**), taken at this seat because nothing dispatches a merge bot to read that rule. Report `<reason>-#<pr>` with what the gate printed, leave the label alone, and do **not** re-run the gate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feigi/fleet-ctl",
-  "version": "3.86.0",
+  "version": "3.87.0",
   "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/main-gain.mjs

@@ -29,12 +29,16 @@
 // Removed lines are read off the merge the head would actually produce:
 // `git merge-tree --write-tree <base> <head>`, diffed against `<base>` with
 // rename detection on. That is right for a head that is behind `<base>` too,
-// where a three-dot diff is not. Every removed line is a candidate, including
-// one replaced by other text, and every line of a deleted file is. A removed
-// line whose exact text is added back in the same file is a move, not a
-// candidate. Binary files cannot be read line by line and are listed in
-// `unchecked[]` instead of blocking. A merge-tree that reports conflicts is a
-// head that cannot merge as it stands, which is no answer about its content.
+// where a three-dot diff is not. Every removed line is a candidate, and every
+// line of a deleted file is, except a move: a removed line whose exact text is
+// added back in the same file. A candidate edited in place is not a hit: an
+// added line of the same hunk that still holds every token of it claims it, and
+// each added line claims at most one. A token is a run of letters, digits or
+// underscores, or else one other character that is not whitespace, so
+// appending a name to an import is an in-place edit and dropping one is not.
+// Binary files cannot be read line by line and are listed in `unchecked[]`
+// instead of blocking. A merge-tree that reports conflicts is a head that
+// cannot merge as it stands, which is no answer about its content.
 //
 // Each hit carries a landing key: `#<n>` when the landing commit's subject is
 // GitHub's merge subject for PR n, otherwise that commit's 12-character
@@ -43,10 +47,15 @@
 // with an empty reason does not count. Acknowledged hits move from `hits[]`
 // to `acknowledged[]` and both are reported.
 //
-// Stdout: one JSON line, `{head, base, since, hits, acknowledged, unchecked,
-// reason}`, `since` being R as an ISO timestamp. Each hit is `{path, key,
-// landed, lines: [{line, text}], ack}`, `path` the file's name on `<base>` and
-// `ack` the body line to copy, reason left for the author to write.
+// Stdout: one JSON line, `{head, base, since, hits, acknowledged, edited,
+// unchecked, reason}`, `since` being R as an ISO timestamp. Each hit is `{path,
+// key, landed, lines: [{line, text, kind}], ack}`, `path` the file's name on
+// `<base>` and `ack` the body line to copy, reason left for the author to
+// write. `kind` is `modified` when the hunk that removed the line also adds
+// lines, and `deleted` when it only removes them. `edited` lists the gained
+// lines an in-place edit kept, as `{path, line, text, replacement}`, the
+// `replacement` being the added line that holds their tokens. An edited line is
+// not a hit and needs no acknowledgement.
 //
 //   0  clean, or every hit acknowledged
 //   1  at least one unacknowledged hit             reason main-gain-removed:<first path>
@@ -130,33 +139,72 @@ function changedPaths(tree) {
   return out;
 }
 
-// Removed lines `[{line, text}]` and added texts, or `binary`, for one path.
+// The hunks of one path, `{removed: [{line, text}], added: [text]}` each, in
+// diff order, or `binary`. Removed lines are numbered on `<base>`.
 function fileDiff(tree, oldPath, newPath) {
   const paths = oldPath === newPath ? [oldPath] : [oldPath, newPath];
   const r = git(["diff-tree", "-r", "-M", "-p", "-U0", "--no-color", "--no-ext-diff", "--no-textconv", baseRev, tree, "--", ...paths]);
   if (r === null) unanswerable(`diff-unreadable:${oldPath}`);
-  const removed = [];
-  const added = [];
-  let inHunk = false;
+  const hunks = [];
+  let hunk = null;
   let oldLine = 0;
   for (const line of r.stdout.split("\n")) {
     if (line.startsWith("diff --git ")) {
-      inHunk = false;
+      hunk = null;
       continue;
     }
     const h = /^@@ -(\d+)(?:,\d+)? \+\d+(?:,\d+)? @@/.exec(line);
     if (h) {
-      inHunk = true;
+      hunk = { removed: [], added: [] };
+      hunks.push(hunk);
       oldLine = Number(h[1]);
-    } else if (!inHunk) {
+    } else if (hunk === null) {
       if (line.startsWith("Binary files ")) return { binary: true };
     } else if (line.startsWith("-")) {
-      removed.push({ line: oldLine++, text: line.slice(1) });
+      hunk.removed.push({ line: oldLine++, text: line.slice(1) });
     } else if (line.startsWith("+")) {
-      added.push(line.slice(1));
+      hunk.added.push(line.slice(1));
+    }
+  }
+  return { binary: false, hunks };
+}
+
+// The tokens an in-place edit keeps: a run of letters, digits or underscores is
+// one token, and each other character that is not whitespace is one.
+const TOKEN = /[\p{L}\p{N}_]+|[^\s\p{L}\p{N}_]/gu;
+function tokensOf(text) {
+  const counts = new Map();
+  for (const t of text.match(TOKEN) ?? []) counts.set(t, (counts.get(t) ?? 0) + 1);
+  return counts;
+}
+
+// Each unclaimed added line of one hunk claims at most one removed line of that
+// hunk. Removed lines choose in turn, most tokens first so a short line does not
+// take the added line a long one needs, and each takes the first unclaimed added
+// line still holding every token of it. That is greedy: a removed line can stay
+// a hit where another pairing would have matched every line, an error toward
+// blocking. The rarest token of a removed line bounds the added lines tried for
+// it.
+function claimInPlace(removed, added) {
+  const index = new Map();
+  for (const a of added) {
+    if (a.claimed) continue;
+    a.tokens = tokensOf(a.text);
+    for (const t of a.tokens.keys()) {
+      if (!index.has(t)) index.set(t, []);
+      index.get(t).push(a);
+    }
+  }
+  const size = (counts) => [...counts.values()].reduce((s, n) => s + n, 0);
+  for (const c of [...removed].sort((x, y) => size(y.tokens) - size(x.tokens))) {
+    if (c.tokens.size === 0) continue;
+    const pool = [...c.tokens.keys()].map((t) => index.get(t) ?? []).reduce((best, l) => (l.length < best.length ? l : best));
+    const a = pool.find((x) => !x.claimed && [...c.tokens].every(([t, n]) => (x.tokens.get(t) ?? 0) >= n));
+    if (a) {
+      a.claimed = true;
+      c.replacement = a.text;
     }
   }
-  return { binary: false, removed, added };
 }
 
 // line number on `<base>` → {sha, time, summary} for the requested lines,
@@ -221,6 +269,7 @@ function check() {
 
   const hits = [];
   const unchecked = [];
+  const edited = [];
   // No commits of its own: the head is already on `<base>` and merges nothing.
   if (since !== null) {
     for (const { oldMode, status, oldPath, newPath } of changedPaths(tree)) {
@@ -234,25 +283,47 @@ function check() {
         unchecked.push(oldPath);
         continue;
       }
-      const addedBack = new Map();
-      for (const t of d.added) addedBack.set(t, (addedBack.get(t) ?? 0) + 1);
-      const candidates = d.removed.filter(({ text }) => {
-        const n = addedBack.get(text) ?? 0;
-        if (n === 0) return true;
-        addedBack.set(text, n - 1);
-        return false;
+      // A removed line whose exact text is added back in the same file is a
+      // move, and the added line is spent on it.
+      const addsByHunk = d.hunks.map(() => []);
+      const twins = new Map();
+      d.hunks.forEach((h, hunk) => {
+        for (const text of h.added) {
+          const a = { text, claimed: false, tokens: null };
+          addsByHunk[hunk].push(a);
+          if (!twins.has(text)) twins.set(text, []);
+          twins.get(text).push(a);
+        }
       });
-      if (candidates.length === 0) continue;
-      const blamed = blame(oldPath, candidates);
+      const candsByHunk = d.hunks.map(() => []);
+      d.hunks.forEach((h, hunk) => {
+        for (const { line, text } of h.removed) {
+          const spare = twins.get(text);
+          if (spare?.length) {
+            spare.pop().claimed = true;
+            continue;
+          }
+          const kind = h.added.length > 0 ? "modified" : "deleted";
+          candsByHunk[hunk].push({ line, text, kind, tokens: tokensOf(text), replacement: null });
+        }
+      });
+      d.hunks.forEach((_, hunk) => claimInPlace(candsByHunk[hunk], addsByHunk[hunk]));
+      const cands = candsByHunk.flat();
+      if (cands.length === 0) continue;
+      const blamed = blame(oldPath, cands);
       const byKey = new Map();
-      for (const c of candidates) {
+      for (const c of cands) {
         const b = blamed.get(c.line);
         if (b.time <= since) continue;
+        if (c.replacement !== null) {
+          edited.push({ path: oldPath, line: c.line, text: c.text, replacement: c.replacement });
+          continue;
+        }
         const key = landingKey(b.sha, b.summary);
         if (!byKey.has(key)) {
           byKey.set(key, { path: oldPath, key, landed: b.sha, lines: [], ack: `main-gain-removal: ${oldPath} ${key} - <why>` });
         }
-        byKey.get(key).lines.push(c);
+        byKey.get(key).lines.push({ line: c.line, text: c.text, kind: c.kind });
       }
       hits.push(...byKey.values());
     }
@@ -270,6 +341,7 @@ function check() {
     since: since === null ? null : new Date(since * 1000).toISOString(),
     hits: open,
     acknowledged,
+    edited,
     unchecked,
     reason: open.length ? `main-gain-removed:${open[0].path}` : null,
   };
@@ -282,7 +354,7 @@ try {
   result = check();
 } catch (e) {
   if (!(e instanceof Unanswerable)) die(`check failed: ${e.code ?? e.message} — could not evaluate`);
-  result = { since: null, hits: [], acknowledged: [], unchecked: [], reason: e.message, unknown: true };
+  result = { since: null, hits: [], acknowledged: [], edited: [], unchecked: [], reason: e.message, unknown: true };
 }
 const { unknown, ...payload } = result;
 writeAll(1, `${JSON.stringify({ head, base, ...payload })}\n`);

package/scripts/merge-gate.mjs

@@ -31,7 +31,7 @@
 // `bodyDigest`), or null with `head` when gh could not be read, `rebaseCarry`
 // naming the labelled head and the head accepted as carrying it (`{labelled,
 // accepted}`), or null when no carry was proven, `mainGain` echoing
-// main-gain.mjs's own payload — hits, acknowledged removals and unchecked
+// main-gain.mjs's own payload — hits, acknowledged removals, edited lines and unchecked
 // files — or null when it did not run or printed no JSON object; an unusable
 // payload is still echoed. Stderr: the children's own diagnostics, passed
 // straight through and never folded into stdout.
@@ -298,7 +298,7 @@ function readMainGain(root, prView) {
   const payload = isObject(v) ? v : null;
   const read = (usable) => ({ usable, exit: r.status, payload });
   if (r.error || r.signal || payload === null || payload.head !== prView.headRefOid) return read(false);
-  if (![payload.hits, payload.acknowledged, payload.unchecked].every(Array.isArray)) return read(false);
+  if (![payload.hits, payload.acknowledged, payload.edited, payload.unchecked].every(Array.isArray)) return read(false);
   if (!payload.hits.every((h) => isObject(h) && typeof h.path === "string" && h.path !== "")) return read(false);
   return read((r.status === 0 && payload.hits.length === 0) || (r.status === 1 && payload.hits.length > 0));
 }

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",

package/skills/run-team/SKILL.md

@@ -831,7 +831,7 @@ and flag the PR for a human. A new review of the PR counts again from none.
 
 | Failure | Response |
 |---|---|
-| Merge bot's gate finds the merge would remove lines `main` gained after the PR's work began (`main-gain-removed:<path>`, exit 1) | Relay `main-gain-removed:<path>-#<pr>` to a human with the hit list and the acknowledgement keys the bot printed. PR stays queued, label untouched, and no member is dispatched to restore the lines — the removal may be deliberate. `fleet-event.mjs merge-bot-report` parks it: a `parked=<head>:<body digest>:<reason>` token on its row, at the head and body digest the bot's gate reading `<scratch>/pr<pr>/merge-bot-<n>/ci.json` records it refused, and no bot is dispatched on its account — when nothing else queued is dispatchable the tick prints `HOLD (parked #<pr> <reason>)`, though a bot dispatched for another queued PR may still evaluate it again; a new head or an edited body lifts the park with no write. It clears when the PR stops removing them or its body carries `main-gain-removal: <path> <key> - <why>` for each hit |
+| Merge bot's gate finds the merge would remove lines `main` gained after the PR's work began (`main-gain-removed:<path>`, exit 1) | Relay `main-gain-removed:<path>-#<pr>` to a human with the hit list and the acknowledgement keys the bot printed. PR stays queued, label untouched, and no member is dispatched to restore the lines — the removal may be deliberate. `fleet-event.mjs merge-bot-report` parks it: a `parked=<head>:<body digest>:<reason>` token on its row, at the head and body digest the bot's gate reading `<scratch>/pr<pr>/merge-bot-<n>/ci.json` records it refused, and no bot is dispatched on its account — when nothing else queued is dispatchable the tick prints `HOLD (parked #<pr> <reason>)`, though a bot dispatched for another queued PR may still evaluate it again; a new head or an edited body lifts the park with no write. A hit line's `kind` is `modified` when its hunk also adds lines, `deleted` when it only removes lines; a gained line edited in place keeping every token is listed in `mainGain.edited[]`, not a hit. It clears when the PR stops removing them or its body carries `main-gain-removal: <path> <key> - <why>` for each hit |
 | Merge bot's gate cannot answer the main-gain check (`main-gain-unanswerable`, exit 2) | Report `main-gain-unanswerable-#<pr>` with what it printed, PR stays queued, label untouched |
 
 ## Failure handling