agent-coord-mcp 0.26.5 → 0.26.7

package/src/tools/records.ts

@@ -0,0 +1,747 @@
+/*
+ * Record verbs: `next_unblocked` · `claim` · `land`.
+ *
+ * These turn coordinator RECIPES into bus VERBS, so a forgotten step fails closed
+ * instead of looking healthy. The measured cost of the recipe: twelve merges went
+ * 23 hours unlogged, and the queue/DONE loop failed three times in nine hours with
+ * the rule written down each time.
+ *
+ * THE MARKDOWN IS AUTHORITATIVE (ADR-003). These read and write the documents
+ * directly rather than the derived store: a store import is a second source of
+ * truth, and the failure this phase exists to remove is exactly a second source
+ * that drifts.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import {
+  parseWorkDoc,
+  renderWorkDoc,
+  queueItemsOf,
+  doneEntriesOf,
+  type QueueItem,
+  type WorkDoc,
+  phaseCitationsIn,
+  newlyTickedInDiff,
+} from "@davidbalzan/groundwork-seam";
+import { ensureWorktreeTool } from "./worktrees.js";
+import { haltState } from "./stall.js";
+import { readSubs, evaluate, commitEvaluation, eventIsDerived, type RecordEvent } from "./events.js";
+
+const QUEUE_DOC = "docs/QUEUE.md";
+const DONE_DOC = "docs/DONE.md";
+const BOARD_DOC = "docs/WORKSTREAMS.md";
+const PRIORITY_ORDER = { P1: 0, P2: 1, P3: 2 } as const;
+
+const readDoc = (repo: string, rel: string): { text: string; doc: WorkDoc } | null => {
+  const p = path.join(repo, rel);
+  if (!existsSync(p)) return null;
+  const text = readFileSync(p, "utf8");
+  return { text, doc: parseWorkDoc(text) };
+};
+
+/**
+ * Write a document back HUNK-FAITHFULLY: everything the seam did not model is
+ * replayed verbatim, and an UNCHANGED file is not written at all.
+ *
+ * The round trip is byte-exact on all three live documents (measured before this
+ * was built, not assumed). Re-rendering an untouched file would still be a write,
+ * and a write is a diff someone has to review — so the no-op case returns false.
+ */
+function writeDoc(repo: string, rel: string, doc: WorkDoc, original: string): boolean {
+  const out = renderWorkDoc(doc);
+  if (out === original) return false;
+  writeFileSync(path.join(repo, rel), out);
+  return true;
+}
+
+const git = (repo: string, args: string[]): string =>
+  execFileSync("git", args, { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+
+/** `#123` / `owner/repo#123` → "123". */
+function prNumber(pr: string): string | null {
+  const m = /#(\d+)\b/.exec(String(pr)) ?? /^(\d+)$/.exec(String(pr).trim());
+  return m ? (m[1] as string) : null;
+}
+
+// ---------- blocked / no-downstream ----------
+
+const BLOCKED_RE = /\bblocked (?:by|on)\b[:\s]*([^\s·,.;]+)/i;
+
+/** The blocker an item names, if it names one. */
+export function blockedBy(item: QueueItem): string | null {
+  const m = BLOCKED_RE.exec(String(item.text));
+  return m ? (m[1] as string).replace(/[`*]/g, "") : null;
+}
+
+const keyOf = (i: QueueItem) => String(i.text).replace(/\s+/g, " ").slice(0, 60);
+
+/**
+ * A DONE summary a human would have written.
+ *
+ * The first `write:true` run produced
+ * `- [x] Kit: **THE ROOT GATE HAND-LISTS ITS FOUR PACKAGES BY NAME WH — …`:
+ * truncated MID-WORD at 60 characters, leaving an unbalanced `**`. It parses, so
+ * the glyph contract accepts it, and it reads as a line someone abandoned
+ * half-way. Cut on a word boundary and drop emphasis markers rather than leaving
+ * half of one.
+ */
+export function summarize(text: string, max = 96): string {
+  const flat = String(text).replace(/\s+/g, " ").replace(/\*\*/g, "").trim();
+  if (flat.length <= max) return flat;
+  const cut = flat.slice(0, max);
+  const at = cut.lastIndexOf(" ");
+  return `${(at > max * 0.6 ? cut.slice(0, at) : cut).replace(/[\s\-—·,;:]+$/, "")}…`;
+}
+
+/**
+ * Items nothing else waits on.
+ *
+ * "BLOCKS NOTHING" IS NOT "COSTS NOTHING TO DEFER" — and an item that blocks
+ * nothing also ANNOUNCES nothing when it stalls. Everything else surfaces through
+ * the thing waiting on it; these have no such witness, so they go missing silently
+ * and their absence is found by someone re-reading the plan. That is why they are
+ * a SEPARATE AXIS here and not folded into the skipped-because-blocked list: those
+ * are two different states with two different remedies, and one list covering both
+ * leaves the reader to infer which.
+ *
+ * LIMIT, stated because it bounds the claim: dependency is detected from the TEXT.
+ * An unstated dependency is invisible to this, so "no downstream" means "nothing in
+ * the queue SAYS it waits on this", never "nothing waits on this".
+ */
+export function noDownstream(items: QueueItem[]): QueueItem[] {
+  const open = items.filter((i) => !i.done);
+  const named = new Set<string>();
+  for (const i of open) {
+    const b = blockedBy(i);
+    if (b) named.add(b.toLowerCase());
+  }
+  return open.filter((i) => {
+    if (blockedBy(i)) return false; // it waits on something: not this axis
+    const key = keyOf(i).toLowerCase();
+    for (const n of named) if (n.length > 3 && key.includes(n)) return false;
+    return true;
+  });
+}
+
+// ---------- next_unblocked ----------
+
+export const nextUnblockedSchema = { project: z.string().min(1), repo: z.string().optional() };
+
+export async function nextUnblockedTool(args: { project: string; repo?: string }) {
+  // A HALT IS A NAMED STATE AND IT BLOCKS THE LANE, not a suggestion. Handing out
+  // the next item during a board cutover or a cited BLOCKER is how work lands on
+  // a base nobody meant to be building on.
+  const halt = haltState();
+  if (halt.halted) {
+    return {
+      ok: false as const,
+      error: `HALTED by ${halt.by}: ${halt.reason}. No item is handed out while a halt is set — clear it with set_halt{clear:true} when the named condition is gone.`,
+      halted: true,
+    };
+  }
+  const repo = args.repo ?? process.cwd();
+  const q = readDoc(repo, QUEUE_DOC);
+  if (!q) return { ok: false as const, error: `no ${QUEUE_DOC} under '${repo}'` };
+  const items = queueItemsOf(q.doc);
+  const open = items.filter((i) => !i.done);
+  const ranked = open
+    .map((i, idx) => ({ i, idx }))
+    .sort((a, b) => (PRIORITY_ORDER[a.i.priority ?? "P3"] ?? 3) - (PRIORITY_ORDER[b.i.priority ?? "P3"] ?? 3) || a.idx - b.idx);
+
+  const skipped: { item: string; blockedBy: string }[] = [];
+  let pick: QueueItem | null = null;
+  for (const { i } of ranked) {
+    const b = blockedBy(i);
+    // NEVER STALL THE LANE waiting on a reorder: a blocked top item is skipped,
+    // visibly, and the next unblocked one is taken.
+    if (b) {
+      skipped.push({ item: keyOf(i), blockedBy: b });
+      continue;
+    }
+    pick = i;
+    break;
+  }
+
+  const silent = noDownstream(open);
+  // AN AXIS THAT FIRES ON EVERYTHING IS NOISE. If no item in the queue declares a
+  // dependency, then "nothing waits on this" is true of every item and the axis
+  // cannot discriminate — listing all of them trains the reader to skim, which is
+  // the severity finding one file over. Say the axis is uninformative instead.
+  const undiscriminating = silent.length === open.length && open.length > 1;
+  return {
+    ok: true as const,
+    project: args.project,
+    open: open.length,
+    next: pick ? { id: pick.id, priority: pick.priority, text: pick.text } : null,
+    skipped,
+    boardHunks: skipped.map((s) => `⏭ skipped — blocked by ${s.blockedBy}`),
+    // A SEPARATE AXIS, deliberately. See noDownstream().
+    noDownstream: undiscriminating
+      ? {
+          count: silent.length,
+          items: [],
+          why:
+            `NO ITEM IN THIS QUEUE DECLARES A DEPENDENCY, so "nothing waits on this" is true of all ${open.length} and this axis ` +
+            "cannot discriminate. Reporting every item would train you to skim it. Every item's absence here is equally silent, " +
+            "which is a fact about the QUEUE rather than about any item — declare dependencies (`blocked by <id>`) and this becomes useful.",
+        }
+      : {
+          count: silent.length,
+          items: silent.slice(0, 10).map((i) => ({ id: i.id, priority: i.priority, key: keyOf(i) })),
+          why:
+            "nothing in the queue says it waits on these, so their absence is SILENT — they need an explicit check at each stage boundary. " +
+            "Detected from item text: an unstated dependency is invisible here.",
+        },
+  };
+}
+
+// ---------- claim ----------
+
+/**
+ * Insert or replace ONE row in the workstreams table, as TEXT.
+ *
+ * 2.4b: "a verb only fails closed if it is the ONLY path — nothing currently
+ * stops a coordinator editing the board directly instead of calling `claim`."
+ * `claim` used to RETURN a `boardHunk` for someone to paste by hand, which is
+ * the same discipline with a nicer API. Every legacy row on the board today is
+ * hand-written, and that is why `stall_check`'s vcs half has nothing to
+ * resolve: a pasted row carries a path, a `claim`-written row carries a real
+ * branch ref.
+ *
+ * Text insertion rather than a re-render: the rest of the file stays
+ * byte-identical, the same reason `land` appends its DONE line as text. A board
+ * this verb rewrote wholesale would be a diff nobody could review.
+ */
+export function upsertBoardRow(text: string, agentId: string, row: string): { text: string; action: "inserted" | "replaced" | "unchanged" } {
+  const lines = text.split("\n");
+  const header = lines.findIndex((l) => /^\|\s*Stream\s*\|/i.test(l));
+  if (header === -1) return { text, action: "unchanged" };
+  // The table ends at the first line that is not a row.
+  let end = header + 1;
+  while (end < lines.length && /^\s*\|/.test(lines[end])) end++;
+
+  // OWNER MATCHED ON THE CELL, NOT ON THE WHOLE LINE. An agent id appearing in
+  // a "Last note" cell is not that agent's row — the occurrence-vs-position
+  // defect this repo has re-derived at four granularities.
+  const ownerOf = (l: string) => (l.split("|")[2] ?? "").replace(/[`*\s]/g, "");
+  const existing = lines.findIndex((l, i) => i > header + 1 && i < end && ownerOf(l) === agentId);
+
+  if (existing !== -1) {
+    if (lines[existing] === row) return { text, action: "unchanged" };
+    lines[existing] = row;
+    return { text: lines.join("\n"), action: "replaced" };
+  }
+  lines.splice(end, 0, row);
+  return { text: lines.join("\n"), action: "inserted" };
+}
+
+export const claimSchema = {
+  project: z.string().min(1),
+  agentId: z.string().min(1),
+  itemId: z.string().optional(),
+  repo: z.string().optional(),
+  base: z.string().optional(),
+  task: z.string().optional(),
+  write: z.boolean().optional(),
+};
+
+export async function claimTool(args: { project: string; agentId: string; itemId?: string; repo?: string; base?: string; task?: string; write?: boolean }) {
+  const halt = haltState();
+  if (halt.halted) {
+    return {
+      ok: false as const,
+      error: `HALTED by ${halt.by}: ${halt.reason}. Claiming is refused while a halt is set.`,
+      halted: true,
+    };
+  }
+  const repo = args.repo ?? process.cwd();
+  const q = readDoc(repo, QUEUE_DOC);
+  if (!q) return { ok: false as const, error: `no ${QUEUE_DOC} under '${repo}'` };
+  const items = queueItemsOf(q.doc);
+  let item = args.itemId ? items.find((i) => i.id === args.itemId) : null;
+  if (args.itemId && !item) return { ok: false as const, error: `no queue item with id '${args.itemId}'` };
+  if (!item) {
+    const next = await nextUnblockedTool({ project: args.project, repo });
+    if (!next.ok || !next.next) return { ok: false as const, error: "no unblocked item to claim" };
+    item = items.find((i) => i.id === next.next!.id) ?? null;
+  }
+  if (!item) return { ok: false as const, error: "no unblocked item to claim" };
+
+  // TASK 1 LANDED, SO THE PLACEHOLDER IS GONE RATHER THAN LEFT SWITCHED OFF.
+  //
+  // While `ensure_worktree` did not exist this returned a loud warning that the
+  // worktree was NOT ensured — conditional on the verb's absence, because a
+  // warning that never clears stops being read. The verb exists now, so `claim`
+  // CALLS it: the interface is unchanged and the gap is closed rather than
+  // annotated. An interface with a placeholder nobody removes is how a temporary
+  // state becomes canon.
+  //
+  // A worktree that cannot be ensured is a REFUSAL, not a warning. Binding an
+  // item to an agent with nowhere isolated to work is the shared-checkout failure
+  // this pair exists to prevent.
+  const wt = await ensureWorktreeTool({
+    agentId: args.agentId,
+    repo,
+    base: args.base ?? "main",
+    task: args.task,
+  });
+  if (!wt.ok) {
+    return {
+      ok: false as const,
+      error: `cannot claim: no isolated worktree — ${wt.error}`,
+      item: { id: item.id, priority: item.priority },
+    };
+  }
+
+  // A NEW TASK DOES NOT START FROM A STALE TREE.
+  //
+  // `ensure_worktree` is idempotent and reuses the agent's existing tree, which
+  // is right mid-slice (1.3) and wrong here: `claim` MEANS "start something
+  // new", and a tree left on last week's base produces the confidently-wrong
+  // inventories the worker card warns about, with nothing about the result
+  // looking stale.
+  //
+  // A freshly CREATED tree is cut from origin/<base> and needs no check — this
+  // only ever fires on reuse.
+  if (!wt.created && wt.atBase === false) {
+    return {
+      ok: false as const,
+      error:
+        `cannot claim: the worktree at ${wt.path} is NOT at ${wt.base}` +
+        `${wt.behindBy ? ` (${wt.behindBy} commit(s) behind)` : ""} — it is on '${wt.branch}' at ${String(wt.sha).slice(0, 8)}. ` +
+        `A new task started here would be based on stale content, and nothing about the result would look stale. ` +
+        `Run \`refresh_worktrees\` to fast-forward idle trees, or finish and land the work already in it.`,
+      item: { id: item.id, priority: item.priority },
+      worktree: { path: wt.path, branch: wt.branch, sha: wt.sha, base: wt.base, atBase: false },
+    };
+  }
+
+  const boardHunk = `| ${keyOf(item)} | ${args.agentId} | \`${wt.branch}\` · ${wt.path} | 🚧 In Progress | — | claimed |`;
+
+  // 2.4b — THE VERB WRITES THE ROW. Reported by default, applied with
+  // write:true, matching `land`. A returned hunk that a human pastes is the
+  // same discipline with a nicer API, and the pasted rows are why the board
+  // carries paths where a claim would have carried a resolvable branch ref.
+  let board: { action: string; path?: string } = { action: "reported" };
+  const b = readDoc(repo, BOARD_DOC);
+  if (!b) {
+    board = { action: `no ${BOARD_DOC} under '${repo}' — row NOT written` };
+  } else if (args.write) {
+    const next = upsertBoardRow(b.text, args.agentId, boardHunk);
+    if (next.action !== "unchanged") writeFileSync(path.join(repo, BOARD_DOC), next.text);
+    board = { action: next.action, path: BOARD_DOC };
+  }
+
+  return {
+    ok: true as const,
+    project: args.project,
+    agentId: args.agentId,
+    item: { id: item.id, priority: item.priority, text: item.text },
+    boardHunk,
+    board,
+    worktreeEnsured: true,
+    worktree: { path: wt.path, sha: wt.sha, branch: wt.branch, created: wt.created, base: wt.base },
+  };
+}
+
+// ---------- land ----------
+
+export const landSchema = {
+  project: z.string().min(1),
+  pr: z.string().min(1),
+  queueItemId: z.string().optional(),
+  repo: z.string().optional(),
+  base: z.string().optional(),
+  write: z.boolean().optional(),
+};
+
+export async function landTool(args: {
+  project: string;
+  pr: string;
+  queueItemId?: string;
+  repo?: string;
+  base?: string;
+  write?: boolean;
+}) {
+  const repo = args.repo ?? process.cwd();
+  const base = args.base ?? "main";
+  const n = prNumber(args.pr);
+  // A CITED PR OR REFUSE. A `DONE:` without a ref cannot be tied to anything by
+  // anyone, ever — which is its own finding, not a formatting preference.
+  if (!n) {
+    return { ok: false as const, error: `'${args.pr}' names no PR number — a DONE entry with no ref can never be tied to the work. Cite owner/repo#N.` };
+  }
+
+  // MERGED ON THE TARGET'S TIP, NOT THE MERGE BASE.
+  //
+  // "What does the thing I am merging INTO have that I do not?" is answered only
+  // by the target's tip: the merge base is the point the branch DIVERGED from, so
+  // anything landed after the cut is missing from it too — comparing against it is
+  // exactly as blind as comparing against the branch (kit#102/#103). Squash merges
+  // leave no ancestor either, so the citation in the merge SUBJECT is the tie.
+  const ref = `origin/${base}`;
+  let landedIn: string | null = null;
+  let reason: string | null = null;
+  try {
+    const subjects = git(repo, ["log", "-n", "400", "--format=%H %s", ref]);
+    const hit = subjects.split("\n").find((l) => new RegExp(`\\(#${n}\\)|#${n}\\b`).test(l));
+    landedIn = hit ? (hit.split(" ")[0] as string) : null;
+  } catch (e) {
+    reason = `could not read ${ref} (${String((e as Error).message).split("\n")[0]}) — NOT checked, which is not the same as checked and absent`;
+  }
+  if (reason) return { ok: false as const, error: reason };
+  if (!landedIn) {
+    return {
+      ok: false as const,
+      error: `#${n} is not on ${ref} — refusing to record it as landed. Compared against the TARGET TIP (${ref}), not a merge base: an item merged after this branch was cut is missing from the base too.`,
+      comparedAgainst: ref,
+    };
+  }
+
+  const q = readDoc(repo, QUEUE_DOC);
+  const d = readDoc(repo, DONE_DOC);
+  if (!q || !d) return { ok: false as const, error: `need both ${QUEUE_DOC} and ${DONE_DOC} under '${repo}'` };
+
+  const items = queueItemsOf(q.doc);
+
+  // WHICH ITEM A PR CLOSES IS A JUDGEMENT, AND GUESSING IT CLOSED THE WRONG ONE.
+  //
+  // The first real use of this verb matched `#116` against an item that merely
+  // MENTIONED #116 in its body — an item about seam ids — and reported it closed.
+  // With write:true it would have closed unrelated, still-open work. That is the
+  // occurrence-vs-position defect I fixed for sweep tags, reintroduced here in a
+  // different matcher hours later: a citation IN an item's text is not a claim
+  // that the item is closed BY it.
+  //
+  // There is no positional convention to anchor on, so the honest fix is not a
+  // better guess: `land` CLOSES ONLY WHAT IT IS TOLD TO CLOSE. Without an explicit
+  // `queueItemId` it closes nothing and reports the candidates for the caller to
+  // pick, saying so.
+  const candidates = items.filter((i) => !i.done && new RegExp(`#${n}\\b`).test(String(i.text)));
+  const target = args.queueItemId ? items.find((i) => i.id === args.queueItemId) : null;
+  if (args.queueItemId && !target) return { ok: false as const, error: `no queue item with id '${args.queueItemId}'` };
+
+  // CLOSE = STATUS ONLY. The item's priority and body BYTES are untouched: the
+  // seam re-renders `- [x] (P2) <text>` from the same text it parsed, so closing
+  // cannot reword an item. That is asserted by a fixture, not by inspection.
+  let queueChanged = false;
+  if (target) {
+    target.done = true;
+    queueChanged = true;
+  }
+
+  const already = doneEntriesOf(d.doc).some((e) => new RegExp(`#${n}\\b`).test(String(e.ref ?? "")));
+
+  // A DONE LINE A HUMAN WOULD NOT HAVE WRITTEN IS NOT A DONE LINE.
+  //
+  // First real use produced `- [x] PR #117 — #117 · 2026-08-28`: no description of
+  // the work, and a BARE ref where every existing entry carries `owner/repo#N`.
+  // The glyph contract parses it, so a shape check would pass it — and it tells a
+  // reader nothing, which is the whole job of the file.
+  //
+  // So: the summary comes from the item being closed, and a bare `#N` is reported
+  // as UNDER-QUALIFIED rather than silently written.
+  const bareRef = !/[\w.-]+\/[\w.-]+#\d+/.test(String(args.pr));
+  const summary = target ? summarize(target.text) : null;
+
+  const doneLine =
+    already || !summary ? null : `- [x] ${summary} — ${args.pr} · ${new Date().toISOString().slice(0, 10)}`;
+
+  // APPEND TO DONE.md — the half this verb exists for.
+  //
+  // The first `write:true` run closed the queue item and wrote NOTHING to
+  // DONE.md: it did half the loop, and the half it skipped is the one that failed
+  // three times in nine hours and left twelve merges unlogged for 23 hours. A verb
+  // built to close that gap that does not write DONE is the gap with a tool in
+  // front of it.
+  //
+  // Appended as TEXT to the last done block so the rest of the file is replayed
+  // byte-for-byte: `renderWorkDoc` reproduces every unmodelled line verbatim, and
+  // an entry added to the record model renders through the pinned glyph contract.
+  const wrote: string[] = [];
+  if (args.write) {
+    if (queueChanged && writeDoc(repo, QUEUE_DOC, q.doc, q.text)) wrote.push(QUEUE_DOC);
+    if (doneLine) {
+      const blocks = d.doc.blocks;
+      let last = -1;
+      for (let i = 0; i < blocks.length; i++) if (blocks[i]?.kind === "done") last = i;
+      if (last === -1) {
+        return {
+          ok: false as const,
+          error: `${DONE_DOC} has no parsed done block to append to — refusing to guess where the entry goes. A DONE.md that parses to zero entries is a defect in the log, not an empty log.`,
+        };
+      }
+      const block = blocks[last] as { kind: "done"; entries: unknown[] };
+      const parsed = parseWorkDoc(`## Done\n${doneLine}\n`);
+      const entry = doneEntriesOf(parsed)[0];
+      if (!entry) {
+        return { ok: false as const, error: `the composed DONE line does not parse as done.v1: ${doneLine}` };
+      }
+      block.entries.push(entry);
+      if (writeDoc(repo, DONE_DOC, d.doc, d.text)) wrote.push(DONE_DOC);
+    }
+  }
+
+  // 6.2 — EMIT ONLY AS A CONSEQUENCE OF THE RECORD CHANGING.
+  //
+  // Read back from disk, AFTER the write, and refuse to emit anything whose ref
+  // is not there. The ordering is the guarantee: an event cannot exist without
+  // the record entry that caused it, because the record is what is consulted to
+  // decide whether to emit. An event stream that can say "task X complete"
+  // while DONE.md does not is a second source of truth, and record-vs-state
+  // divergence is the defect this fleet hit most this week.
+  //
+  // Reported, never thrown: a delivery failure must not undo a merge that has
+  // already happened. `land` is a RECORDER.
+  let events: { emitted: RecordEvent[]; deliveries: unknown[]; refused: string[] } = { emitted: [], deliveries: [], refused: [] };
+  if (args.write && target) {
+    const after = readDoc(repo, DONE_DOC);
+    const recordText = after?.text ?? "";
+    const ev: RecordEvent = { kind: "item", target: target.id, ref: args.pr, summary: summarize(target.text) };
+    const derived = eventIsDerived(recordText, ev);
+    if (!derived.ok) {
+      events.refused.push(derived.error);
+    } else {
+      const now = Date.now();
+      const { subs, deliveries } = evaluate(readSubs(), ev, now);
+      commitEvaluation(subs);
+      events = { emitted: [ev], deliveries, refused: [] };
+    }
+  }
+
+  return {
+    ok: true as const,
+    project: args.project,
+    pr: `#${n}`,
+    comparedAgainst: ref,
+    landedIn: landedIn.slice(0, 8),
+    queueItem: target ? { id: target.id, closed: true, textUnchanged: true } : null,
+    events,
+    candidates: target
+      ? undefined
+      : candidates.map((i) => ({ id: i.id, priority: i.priority, key: keyOf(i) })),
+    ...(target || !candidates.length
+      ? {}
+      : {
+          note_candidates:
+            `${candidates.length} open item(s) MENTION #${n}; none was closed. A citation in an item's text is not a claim ` +
+            `that the item is closed by it — pass queueItemId to close one deliberately.`,
+        }),
+    doneEntry: doneLine,
+    ...(bareRef
+      ? {
+          refWarning:
+            `'${args.pr}' is an UNDER-QUALIFIED ref — every entry in DONE.md carries owner/repo#N, and a bare #N does not ` +
+            `identify a repository. Pass the full ref; the glyph contract would parse the bare one and it would tell a reader nothing.`,
+        }
+      : {}),
+    ...(summary || already ? {} : { doneEntryWithheld: "no queue item named, so there is no description to write — a DONE line reading only 'PR #N' is not one a human would write" }),
+    alreadyLogged: already,
+    written: wrote,
+    note: args.write ? undefined : "reporting only — pass write:true to apply. The markdown is authoritative; a report is not a write.",
+  };
+}
+
+/* ────────────────────────────────────────────────────────────────────────────
+ * `merge` — THE MERGE STEP CONSUMES THE CHECK VERDICT, STRUCTURALLY.
+ *
+ * MEASURED COST: kit#123 was merged on a red CI. The wait-loop read `test fail`
+ * and the merge command ran anyway — the instrument RAN, its result was READ,
+ * and the control flow did not DEPEND on it. That is the same shape as the six
+ * shell-pattern mutations that reported clean the same day: a check whose
+ * outcome nothing branches on is decoration, and it trains the reader to skip
+ * it precisely because the outcome afterwards was fine.
+ *
+ * A rule saying "wait for green" cannot fix that, because the failure was not
+ * ignorance of the rule — the coordinator wrote the loop, read the failure, and
+ * merged. So the verdict is not returned for a caller to honour: the merge is
+ * DOWNSTREAM OF IT IN ONE CALL. There is no ordering of this verb in which the
+ * check runs and the merge ignores it.
+ *
+ * Naturally this cannot stop someone typing `gh pr merge`. It removes the
+ * unpoliced step from the path that is meant to be used, and it makes the
+ * bypass a visible choice rather than a loop that looked correct.
+ * ──────────────────────────────────────────────────────────────────────────── */
+
+/** One check as we judge it, normalised across gh's two rollup shapes. */
+export type CheckRow = { name: string; state: string; verdict: "pass" | "fail" | "pending" };
+
+/**
+ * gh reports CheckRun as status+conclusion and StatusContext as a bare state,
+ * and a rollup routinely contains BOTH. Reading only one shape silently scores
+ * the other as unknown — so normalise explicitly and let anything unrecognised
+ * fall to `pending`, which refuses. An unreadable check is not a passing one.
+ */
+export function normalizeChecks(rollup: unknown[]): CheckRow[] {
+  return (rollup ?? []).map((r) => {
+    const c = (r ?? {}) as Record<string, unknown>;
+    const name = String(c.name ?? c.context ?? "(unnamed)");
+    const status = String(c.status ?? "").toUpperCase();
+    const raw = String(c.conclusion ?? c.state ?? "").toUpperCase();
+    if (status && status !== "COMPLETED") return { name, state: status, verdict: "pending" as const };
+    if (raw === "SUCCESS") return { name, state: raw, verdict: "pass" as const };
+    // NEUTRAL and SKIPPED are deliberately NOT passes. A check that declined to
+    // run has not evidenced anything, and scoring it green is the unread-input
+    // defect: reporting clean on something never read.
+    if (raw === "FAILURE" || raw === "ERROR" || raw === "TIMED_OUT" || raw === "CANCELLED" || raw === "ACTION_REQUIRED")
+      return { name, state: raw, verdict: "fail" as const };
+    return { name, state: raw || status || "UNKNOWN", verdict: "pending" as const };
+  });
+}
+
+export const mergeSchema = {
+  project: z.string().min(1),
+  pr: z.string().min(1),
+  repo: z.string().optional(),
+  method: z.enum(["squash", "merge", "rebase"]).optional(),
+  write: z.boolean().optional(),
+};
+
+/** Injected so every refusal branch is provable offline; defaults to real gh. */
+export type PrFacts = {
+  state: string;
+  mergeable: string;
+  checks: unknown[];
+  /** Unified diff of the PR, for the ticked-box audit. */
+  diff?: string;
+  /** Everything that will survive the merge as a citation: title + commit subjects + body. */
+  citationText?: string;
+};
+const ghFacts = (repo: string, n: string): PrFacts => {
+  const out = execFileSync("gh", ["pr", "view", n, "--json", "state,mergeable,statusCheckRollup"], {
+    cwd: repo,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  const j = JSON.parse(out) as Record<string, unknown>;
+  const gh = (args: string[]) => {
+    try {
+      return execFileSync("gh", args, { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    } catch {
+      return "";
+    }
+  };
+  // The citation must survive the MERGE, so what counts is what lands in
+  // history: the PR title (which becomes the squash subject) and the commit
+  // subjects. The body is included because a reviewer reads it, but a claim
+  // that lives only in a comment thread is not a record.
+  const meta = JSON.parse(gh(["pr", "view", n, "--json", "title,body,commits"]) || "{}") as Record<string, unknown>;
+  const subjects = ((meta.commits as { messageHeadline?: string }[] | undefined) ?? [])
+    .map((c) => c.messageHeadline ?? "")
+    .join("\n");
+  return {
+    state: String(j.state ?? ""),
+    mergeable: String(j.mergeable ?? ""),
+    checks: (j.statusCheckRollup as unknown[]) ?? [],
+    diff: gh(["pr", "diff", n]),
+    citationText: [String(meta.title ?? ""), subjects, String(meta.body ?? "")].join("\n"),
+  };
+};
+
+/**
+ * The act of merging, injected.
+ *
+ * NOT a testability nicety: with only `facts` injected, a test that supplied
+ * passing checks and `write:true` fell through to the REAL `gh pr merge` and
+ * tried to merge an actual PR. It failed only because that PR was already
+ * merged. A test suite that can merge a live pull request is a worse defect
+ * than anything this verb exists to catch, so the side effect is now something
+ * a caller hands in.
+ */
+export type DoMerge = (repo: string, n: string, method: string) => void;
+const ghMerge: DoMerge = (repo, n, method) => {
+  execFileSync("gh", ["pr", "merge", n, `--${method}`, "--delete-branch"], {
+    cwd: repo,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+};
+
+export async function mergeTool(
+  args: { project: string; pr: string; repo?: string; method?: string; write?: boolean },
+  facts: (repo: string, n: string) => PrFacts = ghFacts,
+  doMerge: DoMerge = ghMerge,
+) {
+  const repo = args.repo ?? process.cwd();
+  const n = prNumber(args.pr);
+  if (!n) return { ok: false as const, error: `'${args.pr}' names no PR number. Cite owner/repo#N.` };
+
+  let f: PrFacts;
+  try {
+    f = facts(repo, n);
+  } catch (e) {
+    // NOT CHECKED IS NOT CHECKED-AND-GREEN. If we cannot read the verdict we
+    // cannot have consumed it, and this verb's whole claim is that it did.
+    return {
+      ok: false as const,
+      error: `could not read the checks for #${n} (${String((e as Error).message).split("\n")[0]}) — NOT read, which is not the same as read and passing.`,
+    };
+  }
+
+  const checks = normalizeChecks(f.checks);
+  const failed = checks.filter((c) => c.verdict === "fail");
+  const pending = checks.filter((c) => c.verdict === "pending");
+  // EVERY RETURN CARRIES THE POPULATION IT JUDGED. "All passed" over an empty
+  // set is the sentence this verb exists to make unsayable.
+  const verdict = { population: checks.length, checks, failed: failed.map((c) => c.name), pending: pending.map((c) => c.name) };
+
+  if (f.state !== "OPEN") return { ok: false as const, error: `#${n} is ${f.state || "not OPEN"} — nothing to merge.`, verdict };
+
+  // NO CHECKS IS NOT PASSING CHECKS.
+  //
+  // Same invariant as the stall clock: no alerts is not no stalls, and a clock
+  // that stopped reads quiet exactly like a system that is fine. An empty
+  // rollup is the strongest-looking green there is — zero failures — and it is
+  // evidence of nothing at all.
+  if (checks.length === 0)
+    return { ok: false as const, error: `#${n} reports ZERO checks. No checks is not passing checks — an empty rollup has zero failures and evidences nothing.`, verdict };
+
+  if (failed.length)
+    return { ok: false as const, error: `#${n} has ${failed.length} of ${checks.length} check(s) FAILING: ${failed.map((c) => c.name).join(", ")}. Refusing to merge.`, verdict };
+
+  if (pending.length)
+    return { ok: false as const, error: `#${n} has ${pending.length} of ${checks.length} check(s) not yet terminal: ${pending.map((c) => c.name).join(", ")}. A check still running has not returned a verdict to consume.`, verdict };
+
+  // EVERY NEWLY-TICKED CHECKBOX MUST BE CITED, CHECKED AT THE MERGE.
+  //
+  // Twice in one day a PR carried two things and left one unrecorded: kit#126
+  // ticked 4.4 and named it nowhere, and all five of Task 5's boxes shipped
+  // inside kit#127 alongside a CI fix. The pattern is not carelessness — a PR
+  // that fixes an incident AND delivers planned work gets the incident
+  // remembered and the work forgotten, because the incident is what everyone
+  // is talking about. Review caught neither; the coordinator found both after
+  // the fact.
+  //
+  // So it is checked where the record is actually made. `doctor`'s
+  // `phase-checkbox` finds this too, but only AFTER the merge, against DONE.md
+  // and merged subjects — by which time the claim is already in history
+  // unevidenced. The citation grammar is shared through seam rather than
+  // copied, because a copied grammar is two grammars the moment one is fixed.
+  const ticked = newlyTickedInDiff(f.diff ?? "");
+  if (ticked.size) {
+    const cited = phaseCitationsIn(f.citationText ?? "");
+    const uncited = [...ticked].filter((k) => !cited.has(k));
+    if (uncited.length) {
+      const names = uncited.map((k) => { const [p, id] = k.split(":"); return `Phase ${p} Task ${id}`; });
+      return {
+        ok: false as const,
+        error:
+          `#${n} ticks ${ticked.size} phase checkbox(es) and ${uncited.length} of them are UNCITED: ${names.join(", ")}. ` +
+          `Once this merges, the tick claims progress that nothing in history evidences. Name them in the PR title or a commit subject (e.g. "${names[0]}") — the subject is what survives a squash merge.`,
+        verdict,
+        uncited: names,
+      };
+    }
+  }
+
+  if (f.mergeable === "CONFLICTING")
+    return { ok: false as const, error: `#${n} is CONFLICTING with its base.`, verdict };
+
+  if (!args.write)
+    return { ok: true as const, merged: false as const, verdict, note: `#${n} would merge: all ${checks.length} check(s) pass. Pass write:true to apply.` };
+
+  doMerge(repo, n, args.method ?? "squash");
+  return { ok: true as const, merged: true as const, verdict };
+}