agent-coord-mcp 0.26.18 → 0.26.20

package/dist/tools/records.js

@@ -0,0 +1,1205 @@
+/*
+ * 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, renderWorkDocForWrite, queueItemsOf, doneEntriesOf, phaseCitationsDetailed, newlyTickedInDiff, sweepTagOf, awaitingOf, refsIn, refsMatch, workstreamsV1RowsOf, } from "@davidbalzan/groundwork-seam";
+import { ensureWorktreeTool } from "./worktrees.js";
+import { boardRefFor, classifyBoardRef } from "./board-ref.js";
+import { haltState, isInFlightStatus } from "./stall.js";
+import { readSubs, evaluate, commitEvaluation, eventIsDerived } 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 };
+const readDoc = (repo, rel) => {
+    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.
+ */
+/**
+ * EVERY SUPPORTED WRITE OF A WORK DOC GOES THROUGH HERE, and it stamps.
+ *
+ * `renderWorkDocForWrite` records identity for any queue item that lacks it,
+ * including rows this caller did not author (q-c50e9b83) — the absorbed raw
+ * append is exactly the case, and stamping only the caller's own rows would keep
+ * the defect and move the blame. Every id written is the one the item already
+ * has, so nothing changes value.
+ *
+ * Returns what it stamped so the caller can report it rather than leaving an
+ * absorbing writer to find it in a diff.
+ */
+/**
+ * A WRITE WHOSE BASE MOVED UNDER IT. Thrown, never returned, because a refusal
+ * that can be ignored is how the silent loss happened in the first place.
+ */
+export class StaleWriteError extends Error {
+    rel;
+    detail;
+    alreadyWritten;
+    constructor(rel, detail, alreadyWritten) {
+        super(`refusing to write ${rel}: it changed on disk after this call read it (${detail}). ` +
+            `Nothing was overwritten. Re-read and retry.` +
+            (alreadyWritten.length ? ` ALREADY WRITTEN by this call: ${alreadyWritten.join(", ")} — that write stands.` : ""));
+        this.rel = rel;
+        this.detail = detail;
+        this.alreadyWritten = alreadyWritten;
+        this.name = "StaleWriteError";
+    }
+}
+/** What moved, in terms a caller can act on without diffing the file itself. */
+function describeDrift(original, current) {
+    const ol = original.split("\n");
+    const cl = current.split("\n");
+    let i = 0;
+    while (i < ol.length && i < cl.length && ol[i] === cl[i])
+        i++;
+    return (`${ol.length} → ${cl.length} line(s), ${original.length} → ${current.length} byte(s)` +
+        (i < Math.max(ol.length, cl.length) ? `, first difference at line ${i + 1}` : ""));
+}
+/**
+ * ⛔ COMPARE-AND-SWAP, AND THE RE-READ IS THE WHOLE POINT.
+ *
+ * This function used to compare the rendered text against `original` — the
+ * caller's IN-MEMORY snapshot from when it read — and then write. It never looked
+ * at the file again. Anything written in between was clobbered with no error, no
+ * diff, and nothing in the return value: `{ written: true }` came back for a
+ * write that had destroyed someone else's row.
+ *
+ * Measured before fixing: two writers taking the same original and both
+ * committing leave TWO rows where three should be, and the first writer's row is
+ * simply gone. This is not hypothetical — four processes write these documents
+ * (the aide from its own clone, `claim`, `land`, worker seats), and `land --write`
+ * ran six times in one afternoon against a queue the aide was editing.
+ *
+ * So the file is re-read immediately before the write and must still match what
+ * the caller read. On a mismatch this REFUSES — loudly, by throwing — and names
+ * what moved. A refused write is recoverable; a silent overwrite is not, and the
+ * loser of the race never learns it lost.
+ *
+ * What this does NOT claim: it is not a lock. Two processes can still interleave
+ * between this re-read and the `writeFileSync` a few microseconds later. The
+ * window goes from "the whole duration of the caller's work" — parsing, git
+ * calls, composing a line — down to two adjacent statements. That is a large
+ * reduction and not zero, and a lock is the stronger fix if this ever proves
+ * insufficient.
+ *
+ * EXPORTED FOR TESTS, deliberately. The race it guards is BETWEEN PROCESSES —
+ * the aide's clone, `claim`, `land` — and `landTool` runs synchronously from its
+ * read to its write, so no in-process test can interleave them. An end-to-end
+ * attempt passed identically with the guard removed, i.e. it proved nothing. A
+ * data-loss guard is worth a narrow export to be testable at the level it lives.
+ */
+export function writeDoc(repo, rel, doc, original, alreadyWritten = []) {
+    const { text, stamped } = renderWorkDocForWrite(doc);
+    if (text === original)
+        return { written: false, stamped: [] };
+    const p = path.join(repo, rel);
+    const current = existsSync(p) ? readFileSync(p, "utf8") : "";
+    if (current !== original) {
+        throw new StaleWriteError(rel, describeDrift(original, current), alreadyWritten);
+    }
+    writeFileSync(p, text);
+    return { written: true, stamped };
+}
+const git = (repo, args) => execFileSync("git", args, { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+/** `#123` / `owner/repo#123` → "123". */
+function prNumber(pr) {
+    const m = /#(\d+)\b/.exec(String(pr)) ?? /^(\d+)$/.exec(String(pr).trim());
+    return m ? m[1] : null;
+}
+/**
+ * The `owner/repo` a BARE `#N` in this repo's docs should be read as naming —
+ * the same derivation `groundwork doctor` makes (`originRepoOf`) before it ties
+ * a closed item's citation to DONE.md. `land` must decide "already cited" with
+ * the SAME rule the auditor will apply, or the two disagree again one level
+ * down: a bare `#77` in an item body is a tie for doctor only when the origin
+ * URL says which repo, and it is a tie here under exactly that condition.
+ * Null (no remote, not a repo) means an unknown context, never a guessed one.
+ */
+function originRepoOf(repo) {
+    try {
+        const url = git(repo, ["remote", "get-url", "origin"]);
+        const m = /[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?$/.exec(url);
+        return m ? m[1] : null;
+    }
+    catch {
+        return 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) {
+    const m = BLOCKED_RE.exec(String(item.text));
+    return m ? m[1].replace(/[`*]/g, "") : null;
+}
+const keyOf = (i) => 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, max = 96) {
+    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) {
+    // ⚠ THE SECOND `!i.done` IN THIS FILE, AND IT IS DELIBERATE — the reconciliation
+    // asked for by ⟨q-7d2e04b8⟩. `nextUnblockedTool` passes an ALREADY-FILTERED
+    // list, so this re-filter is a no-op on that path; it is kept because this
+    // function is EXPORTED and its contract is "given items, which have nothing
+    // waiting on them", which must hold for a caller that hands it raw items.
+    //
+    // The two are not the same predicate and must not be merged: this one is
+    // `!done`, while the router's also subtracts the delivery join. Collapsing
+    // them would make an exported helper inherit a routing policy.
+    const open = items.filter((i) => !i.done);
+    const named = new Set();
+    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;
+    });
+}
+/* ────────────────────────────────────────────────────────────────────────────
+ * DELIVERED — READ THE RECORD'S STRUCTURE, NOT A SUBSTRING OF THE FILE.
+ *
+ * This was `doneText.includes(id) || boardText.includes(id)` over two whole
+ * documents, so ANY MENTION ANYWHERE counted as "handed out" — including a row
+ * written specifically to warn that an item must NOT be built (q-2ba7f0c5).
+ * The inversion is the finding: the more carefully a coordinator documents why
+ * something must not be routed, the more completely it disappears from the verb
+ * that routes.
+ *
+ * MEASURED ON `origin/main` @17b72ff, and the numbers moved the fix twice:
+ *
+ *   q-11257590  hidden by the AIDE'S OWN `🚧 In Progress` ROW, which merely
+ *               MENTIONS it in its Last note. A status-only rule leaves it
+ *               hidden — the occurrence-vs-position defect one level in — so
+ *               identification has to be the row's SUBJECT, not any of its cells.
+ *   q-ad0fc8d4  hidden by its own `⏸ Returned to the aide unbuilt` row.
+ *   q-507e80c4  hidden with NO PARSED ROW AT ALL: the id sits in board prose
+ *               outside the table, which a whole-file substring test cannot
+ *               distinguish from a lane.
+ *   q-507e80c4  ALSO hidden by a DONE entry that CITES it as the still-open
+ *               part (b) of work whose part (a) landed — the canon case
+ *               q-912a67e8 requires, LIVE today rather than latent.
+ *
+ * Neither half is fixed by relabelling a row: that is satisfying a guard by
+ * editing what it reads (q-507e80c4 constraint 1) and it would destroy the
+ * warning the row exists to give.
+ */
+/** The ids a board row names as ITS OWN SUBJECT — the Stream cell only. */
+function rowSubjectIds(row) {
+    return [...String(row.stream).matchAll(/\b(q-[0-9a-f]{8})\b/g)].map((m) => m[1]);
+}
+/**
+ * Does the board show this item as IN SOMEBODY'S HANDS?
+ *
+ * Two conditions, and both are needed — measured, not reasoned:
+ *   STATUS  the row is in flight (`isInFlightStatus`, shared with `stall_check`
+ *           since #219 rather than a second glyph list). `⏸ Parked`,
+ *           `⏸ Returned`, `⏳ Queued`, `⛔ Blocked`, `🚫 Unstaffable`,
+ *           `🔻 Orphaned` describe work nobody holds, so they do not silence.
+ *   SUBJECT the row's Stream cell names the item — by recorded id, or by the
+ *           text prefix `claim` has always written there. A mention in a Last
+ *           note is one lane REFERRING to another item — the aide's live row
+ *           does exactly this — and a status-only rule would still hide it.
+ *
+ * THE PREFIX ARM IS FOR THE ROWS ALREADY ON THE BOARD, and without it this fix
+ * would have shipped a transitional hole in its own negative control: every row
+ * `claim` wrote before this change carries `keyOf(item)` — a 60-character text
+ * prefix — and no id at all, so an id-only rule leaves a lane's OWN live item
+ * routable. Measured: q-2ba7f0c5's row, written minutes earlier by the
+ * pre-merge server, was offered back while it was in hand. Rows written from
+ * here carry the id (see `claim`), so the prefix arm is the compatibility half
+ * rather than the mechanism, and it is deliberately still SUBJECT-only.
+ */
+function boardHoldsItem(rows, id, text) {
+    const key = keyOf({ text }).replace(/\s+/g, " ").trim();
+    return rows.some((r) => {
+        if (!isInFlightStatus(r.status))
+            return false;
+        if (rowSubjectIds(r).includes(id))
+            return true;
+        const stream = String(r.stream).replace(/\s+/g, " ").trim();
+        return key.length >= 20 && stream.startsWith(key.slice(0, Math.min(key.length, 60)));
+    });
+}
+/**
+ * Is this DONE entry the RECORD OF THIS ITEM CLOSING, rather than an entry that
+ * merely MENTIONS it?
+ *
+ * ⛔ THE SIGIL ARM WAS REMOVED ⟨q-4a1e70c5⟩. It answered yes whenever `⟨id⟩`
+ * appeared ANYWHERE in an entry, on a census that had inverted: today
+ * `docs/DONE.md` carries more sigil mentions than bare ones, because `⟨id⟩` is the
+ * house spelling everything else teaches — so the COMPLIANT way to cite an item
+ * became the spelling that meant "delivered". Measured before removal, on 143
+ * open rows: ELEVEN false positives, ZERO independent true positives (every row
+ * it correctly excluded was already excluded by `!i.done`, which runs first), and
+ * a MISS on its own founding case — the row recorded as q-b4e7c209 had its work
+ * merged under a different row's citation, stayed `[ ]`, and was offered as top
+ * P1 twice.
+ *
+ * ⚠ THE SPELLING RULE DID NOT FAIL BECAUSE THE SPELLING FLIPPED. IT FAILED
+ * BECAUSE SPELLING WAS NEVER THE SIGNAL. Entries name item ids for several
+ * reasons this repo's own canon REQUIRES — a residual gap must cite its queue
+ * item — so no reading of that file separates a closure from a mention. Three
+ * replacements were measured and each was worse or equal: position does not
+ * discriminate (a known-false and a known-true entry are structurally identical,
+ * and only 2 of 252 entries lead with a sigil); `DoneEntry.id` is a derived `d-`
+ * id, not the item's; and the citation-slot tie `queue-done-loop` uses gives 23
+ * false positives, because open rows cite refs as EVIDENCE.
+ *
+ * ✅ WHAT SURVIVES IS THE COMPOSED-SUMMARY ARM, and it is a DIFFERENT EVIDENCE
+ * CLASS — the same distinction that keeps `boardHoldsItem`. It does not infer
+ * delivery from prose: it requires the entry to carry the item's own
+ * deterministically composed text, `summarize(item.text)`, which a VERB writes.
+ * A citation cannot accidentally satisfy it.
+ *
+ * ⚠ IT IS CURRENTLY UNEXERCISED BY THIS REPO'S CORPUS — 0 of 143 open, 0 of 9
+ * closed — AND THAT IS NOT EVIDENCE THAT IT IS DEAD. The cause is practice, not
+ * code: rows here are closed with `land --write` and the composed line is then
+ * OVERWRITTEN with hand-written prose, so the structural record it would match is
+ * destroyed within the minute. **Do not re-derive "dead code" from another zero
+ * count.** Its input returns the moment a closing entry keeps what `land` wrote.
+ *
+ * ⛔ AND WHAT IS NO LONGER GUARDED, because a removal that does not name its own
+ * cost is worse than the guard: A ROW WHOSE WORK MERGED UNDER ANOTHER ROW'S
+ * CITATION IS ELIGIBLE AGAIN, AND NOTHING IN `next_unblocked` WILL NOTICE.
+ * Accepted knowingly — the arm that claimed to cover it did not, on the one live
+ * instance it had. Closing such a row is coordinator discipline, not a predicate.
+ */
+function doneRecordsDelivery(entries, id, text) {
+    const norm = (v) => v.replace(/\s+/g, " ").replace(/\*\*/g, "").trim();
+    const target = norm(summarize(text)).replace(/…$/, "");
+    return entries.some((e) => {
+        // A leading recorded-id token is stripped before comparing, so an entry
+        // written as `⟨id⟩ <summary>` and one written as `<summary>` agree.
+        const body = norm(String(e.text)).replace(/^⟨q-[0-9a-f]{8}⟩\s*/, "");
+        return target.length >= 12 && body.startsWith(target);
+    });
+}
+// ---------- next_unblocked ----------
+export const nextUnblockedSchema = { project: z.string().min(1), repo: z.string().optional() };
+export async function nextUnblockedTool(args) {
+    // 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,
+            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, error: `no ${QUEUE_DOC} under '${repo}'` };
+    const items = queueItemsOf(q.doc);
+    // The seam's own count of unticked rows — the number every axis must add back
+    // up to. Taken BEFORE any exclusion so it cannot inherit one.
+    const parsedOpen = items.filter((i) => !i.done).length;
+    // ALREADY-DELIVERED ITEMS ARE NEVER RE-OFFERED, and `!i.done` alone does not
+    // establish that.
+    //
+    // MEASURED, 2026-09-01: an item whose work had merged in #196 was still `[ ]`
+    // in the queue — closing it is a separate act from landing it — so it stayed
+    // eligible. A compaction then re-issued its id, it surfaced as the top item,
+    // and it was routed back to the worker that had closed it an hour earlier.
+    // That worker declined because it recognised its own acceptance criteria:
+    // RETAINED CONTEXT, which is not a control and which a `/clear` or a
+    // compaction removes silently.
+    //
+    // So delivery is read from the RECORD instead: an item cited in docs/DONE.md,
+    // or already carrying a 🚧 row on the board, has been handed out. Stable ids
+    // (Task 21.1) are what make this join reliable — with a content-hash id the
+    // board row and the DONE entry stopped matching the moment anyone reworded
+    // the item, which is how the memory was lost in the first place.
+    // ⛔⛆ `delivered` IS A REASON, NOT AN ERASURE (⟨q-7d2e04b8⟩). This set used to
+    // be subtracted from `open` BEFORE any axis ran, so an item it excluded could
+    // appear on NO axis by construction — the one guarantee this verb's contract
+    // makes is that it never skips silently, and this was the one path that did.
+    //
+    // MEASURED on the live queue at `a032069`: the file held 143 open rows, the
+    // seam parsed all 143, and this verb reported `open: 129`. Its declared axes
+    // accounted for ONE. Fourteen rows were outside the router's universe and
+    // nothing in the response said so — invisible from the only seat that would
+    // notice, because a worker asking for the next item still gets a real one.
+    //
+    // ⚠ THE REASON IS NOW CARRIED, so exclusion and explanation cannot drift apart:
+    // a row is excluded BY a named cause, and the cause is what gets reported.
+    const deliveredBy = new Map();
+    const doneDoc = readDoc(repo, DONE_DOC);
+    const boardDoc = readDoc(repo, BOARD_DOC);
+    const boardText = boardDoc?.text ?? "";
+    const doneEntries = doneDoc ? doneEntriesOf(doneDoc.doc) : [];
+    const boardRows = boardDoc ? workstreamsV1RowsOf(boardDoc.doc) : [];
+    for (const i of items) {
+        if (i.done)
+            continue; // already off `open` by the checkbox; not an exclusion this axis owns
+        // Board first, and the order is load-bearing for the REPORT rather than the
+        // routing: both causes exclude, but a live 🚧 row is a different remedy
+        // (wait, or ask its owner) from a landed delivery (close the row).
+        if (boardHoldsItem(boardRows, i.id, String(i.text)))
+            deliveredBy.set(i.id, "board");
+        else if (doneRecordsDelivery(doneEntries, i.id, String(i.text)))
+            deliveredBy.set(i.id, "done");
+    }
+    const open = items.filter((i) => !i.done && !deliveredBy.has(i.id));
+    // THE AXIS THE SUBTRACTION USED TO SKIP. Every row absent from `open` for this
+    // reason is named here, INCLUDING correctly-delivered ones: a correct exclusion
+    // reported silently is the same defect as an incorrect one.
+    const delivered = items
+        .filter((i) => !i.done && deliveredBy.has(i.id))
+        .map((i) => ({ item: keyOf(i), id: i.id, reason: deliveredBy.get(i.id) }));
+    // ⛔⛆ A DUPLICATED ID IS A SILENT DOUBLE-EXCLUSION, AND IT IS THIS ROW'S OWN
+    // DEFECT ONE LEVEL DOWN. Queue ids are STABLE, derived from the row's text, so
+    // two rows with identical text carry the SAME id — verified: `- [ ] (P1) an
+    // identical row` twice yields `q-c9f3ded8` twice.
+    //
+    // Everything downstream is keyed by id, so ONE delivery record then excludes
+    // BOTH rows: measured on a fixture, a single DONE entry took `parsedOpen: 3`
+    // to `offered: 1`. The accounting still reconciles — both are named — so the
+    // self-check above CANNOT catch it, which is exactly why it needs its own axis
+    // rather than a flag on `reconciles`.
+    //
+    // ⭐ WHY THIS AXIS AND NOT A COUNT: a MISSING row can always be argued to be a
+    // filter working as designed; a row reported TWICE cannot be anything but the
+    // accounting. It is the one symptom here that does not rest on a count.
+    const idCounts = new Map();
+    for (const i of items)
+        if (!i.done)
+            idCounts.set(i.id, (idCounts.get(i.id) ?? 0) + 1);
+    const duplicateIds = [...idCounts.entries()]
+        .filter(([, n]) => n > 1)
+        .map(([id, rows]) => ({
+        id,
+        rows,
+        why: `${rows} open rows share the id ${id} — stable ids are derived from row TEXT, so identical rows collide. Every axis here is keyed by id, so one delivery record excludes all ${rows}. Reword one row to separate them.`,
+    }));
+    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 = [];
+    // NOT WORKER-CLAIMABLE (Task 15.4). Measured: 13-14 of the open queue is
+    // `[SWEEP:canon]`/`[SWEEP:canon.N]` — canon prose the aide and coordinator
+    // author directly into the playbook, never assigned as code work. Handing
+    // one out here is the exact defect: `next_unblocked` offered one outside
+    // the caller's lane while the rest of what remained was this same family.
+    // Skipped VISIBLY, same discipline as a blocked top item — never silently
+    // dropped, so a caller can tell "nothing left for me" from "nothing left".
+    const notClaimable = [];
+    // AWAITING A HUMAN (q-e334937d). "Unblocked" means dependency-free, and an
+    // item awaiting a ruling is dependency-free and unbuildable at once. Measured
+    // 2026-09-02: this verb offered q-11257590 as next; the lane read the
+    // acceptance PROSE to learn it awaited David, declined, and picked by hand —
+    // a read every lane offered it would pay again. The fact is now a FIELD on
+    // the item (`**[AWAITS:<who>]**`, read by the seam), never inferred from
+    // prose. Its own axis, checked FIRST: it is the most specific thing that can
+    // be true of an item, and "three items wait on a human" is a fact David can
+    // act on where "nothing to route" is not. Skipped for routing, never dropped.
+    //
+    // GATHERED OVER EVERY OPEN ITEM, NOT OVER `open` — measured on the real queue
+    // the first time this ran: q-11257590 carried the marker and appeared in NO
+    // bucket, because the board holds a "⏸ Parked — awaits David" row naming it
+    // and the delivered-join above reads any board mention as "handed out". The
+    // row written to WARN about the item was what hid it. Routing still honours
+    // the join; this report does not, because its reader is the human the item
+    // waits on, and a pending decision does not stop being pending when someone
+    // writes it on the board.
+    const awaitingDecision = [];
+    for (const i of items) {
+        if (i.done)
+            continue;
+        const who = awaitingOf(i);
+        if (who)
+            awaitingDecision.push({ item: keyOf(i), id: i.id, who, onBoard: boardText.includes(i.id) });
+    }
+    let pick = null;
+    for (const { i } of ranked) {
+        if (awaitingOf(i))
+            continue; // reported above; never routed
+        const tag = sweepTagOf(i);
+        if (tag && /^canon(\.\d+)?$/.test(tag)) {
+            notClaimable.push({ item: keyOf(i), sweepTag: tag });
+            continue;
+        }
+        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,
+        project: args.project,
+        open: open.length,
+        // ⛔ THE SELF-CHECK, because the defect this replaces was a NUMBER NOTHING
+        // EXPLAINED and the only thing that ever caught it was someone counting the
+        // file by hand. `parsedOpen` is every unticked row the seam sees; `offered`
+        // is what routing considered; `excluded` is what the axes account for. When
+        // `reconciles` is false, rows have left the universe with no named cause —
+        // the exact condition that was previously unobservable from the response.
+        //
+        // ⚠ IT REPORTS RATHER THAN THROWS: a router that refuses to hand out work
+        // because its own bookkeeping is off strands every lane, which is worse than
+        // the miscount. The caller gets a real item AND the discrepancy.
+        accounting: {
+            parsedOpen,
+            offered: open.length,
+            excluded: delivered.length,
+            reconciles: parsedOpen === open.length + delivered.length,
+        },
+        // A NAMED AXIS, not a subtraction. See the comment at `deliveredBy`.
+        delivered,
+        // A ROW REPORTED TWICE CANNOT BE A FILTER WORKING AS DESIGNED. See above.
+        duplicateIds,
+        next: pick ? { id: pick.id, priority: pick.priority, text: pick.text } : null,
+        skipped,
+        // A SEPARATE AXIS from `skipped` (blocked) — this is "not this caller's
+        // to take" rather than "blocked on something else". Collapsing the two
+        // would read a claimability gap as a dependency, which is a different
+        // remedy (route it, don't wait for it).
+        notClaimable,
+        // A THIRD AXIS, and not a variant of either above: `skipped` waits on
+        // another ITEM, `notClaimable` is not this caller's to take, and this waits
+        // on a HUMAN. The remedy differs each time (wait · route · ask), so one
+        // list covering them would leave the reader to infer which applies.
+        awaitingDecision,
+        boardHunks: [
+            ...skipped.map((s) => `⏭ skipped — blocked by ${s.blockedBy}`),
+            ...notClaimable.map((s) => `⏭ skipped — not worker-claimable (${s.sweepTag})`),
+            ...awaitingDecision.map((a) => `⏸ skipped — awaiting decision from ${a.who} (${a.id})`),
+            ...duplicateIds.map((d) => `⚠ ${d.rows} open rows share the id ${d.id} — one record excludes all of them`),
+            ...delivered.map((d) => d.reason === "board"
+                ? `⏭ not offered — already on the board (${d.id})`
+                : `⏭ not offered — delivery recorded in DONE.md (${d.id})`),
+        ],
+        // 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, agentId, row) {
+    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) => (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) {
+    const halt = haltState();
+    if (halt.halted) {
+        return {
+            ok: false,
+            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, 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, 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, error: "no unblocked item to claim" };
+        item = items.find((i) => i.id === next.next.id) ?? null;
+    }
+    if (!item)
+        return { ok: false, 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,
+            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,
+            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 },
+        };
+    }
+    // THE CELL NAMES THE REMOTE-TRACKING REF, not the bare local branch.
+    //
+    // A bare name resolves in the checkout that created it and nowhere else, so
+    // the same board read differently from two checkouts and whether a row was
+    // measurable depended on who last ran `git fetch` — a property of the reader
+    // rather than of the work. Writing `origin/<branch>` makes the cell mean the
+    // same thing everywhere.
+    //
+    // It does not resolve YET, because a freshly cut branch is unpushed. That is
+    // correct and `stall_check` says so in those words: an unpushed lane has no
+    // shared evidence of activity, which is an absence of evidence rather than a
+    // stall.
+    const intendedRef = boardRefFor(wt.branch ?? "");
+    /*
+     * AND NOW ACTUALLY ENFORCED AT THE WRITE.
+     *
+     * The comment here used to claim exactly that — "enforced at the WRITE as well
+     * as the read, a rule the writer can defeat is a rule the writer defeats" —
+     * and it was FALSE. `boardRefFor` PREFIXES `origin/`; it refuses nothing. So
+     * `claim` could still write `origin/main` into a board cell, which
+     * `stall_check` then correctly refuses to measure, leaving a row that can
+     * never stall and never be measured. board-ref.ts's own header states the
+     * rule; #197 shipped the read half and I wrote the sentence and did not do it.
+     *
+     * A rule carrying a false mechanism is worse than an absent rule: the next
+     * reader derives from the mechanism, and this one asserted the very coverage
+     * it lacked.
+     *
+     * REFUSED: the four kinds that are structurally wrong however fresh the lane
+     * is — a shared ref (measures the fleet), a path (not a ref at all), another
+     * agent's branch (measures their work), and an empty cell.
+     *
+     * ALLOWED: `unpushed` and `local-only`, deliberately. A freshly cut branch is
+     * ALWAYS unpushed, so refusing those would refuse every legitimate claim —
+     * the over-narrowing I have now made twice in this classifier's history, where
+     * a rule meant to make a check honest disabled it instead. `merged` is allowed
+     * too but noted, since re-claiming onto a landed branch is unusual rather than
+     * structurally broken.
+     */
+    const refusable = new Set(["shared", "path", "unscoped", "empty"]);
+    const cellVerdict = classifyBoardRef(repo, args.agentId, `\`${intendedRef}\``, `origin/${args.base ?? "main"}`);
+    if (refusable.has(cellVerdict.kind)) {
+        return {
+            ok: false,
+            error: `cannot claim: the board cell would name '${intendedRef}', which is not a per-agent activity signal ` +
+                `(${cellVerdict.kind}) — ${"why" in cellVerdict ? cellVerdict.why : ""} ` +
+                `The row would be unmeasurable the moment it was written, so it is refused here rather than reported later.`,
+            item: { id: item.id, priority: item.priority },
+            worktree: { path: wt.path, branch: wt.branch },
+        };
+    }
+    // THE ROW NAMES THE ITEM BY ID, so the delivered-join can recognise a row this
+    // verb itself wrote. Measured on the live board: `keyOf` is the item's text
+    // prefix and the recorded `⟨id⟩` token is not part of `text`, so NO
+    // claim-written row has ever carried an id — the join could only ever match
+    // HAND-WRITTEN rows, which is the opposite of what it was for. Stamping it
+    // makes the identification recorded rather than derived from a 60-character
+    // prose prefix that any rewording changes.
+    const boardHunk = `| ⟨${item.id}⟩ ${keyOf(item)} | ${args.agentId} | \`${intendedRef}\` · ${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: "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,
+        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(),
+    /** One-line result, written after the citation on the closed item's line. */
+    result: z.string().optional(),
+};
+export async function landTool(args) {
+    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, 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 = null;
+    let reason = 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] : null;
+    }
+    catch (e) {
+        reason = `could not read ${ref} (${String(e.message).split("\n")[0]}) — NOT checked, which is not the same as checked and absent`;
+    }
+    if (reason)
+        return { ok: false, error: reason };
+    if (!landedIn) {
+        return {
+            ok: false,
+            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, 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, error: `no queue item with id '${args.queueItemId}'` };
+    // CLOSE = STATUS + CITATION. 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.
+    //
+    // AND THE LINE CITES WHAT CLOSED IT (q-6d21ff84). `doctor:queue-done-loop`
+    // requires a `[x]` item's FIRST LINE to cite the PR that DONE.md records —
+    // that strictness is what makes a closure machine-checkable, and the repo
+    // paid for it. This verb ticked the box and wrote DONE.md and left line 1
+    // uncited, so EVERY successful `land` turned main red at the next root gate
+    // and the coordinator hand-repaired a file the verb had just written
+    // (`c29becd`, and again on q-e334937d). The writer and the auditor were built
+    // to different contracts; the fix belongs in the writer, because loosening
+    // the auditor to accept what the writer emits is how a check stops being one.
+    //
+    // A SUFFIX, NOT A REWRITE. The existing text is preserved byte-for-byte as a
+    // prefix; ` · **closed by <ref>[ — <result>]**` is appended — the exact form
+    // q-40449919 carries after its manual repair. Line 1 only, because line 1 is
+    // all `item.text` is and all the check reads; a citation on a continuation
+    // line satisfies nothing (the occurrence-vs-position trap, hit twice).
+    //
+    // IDEMPOTENT: an item whose line already cites this PR (in any spelling
+    // `refsIn` ties to it) is left byte-identical, so a second `land` cannot
+    // double-cite and a hand-cited item is not re-cited.
+    let queueChanged = false;
+    let citationAppended = null;
+    // The DONE entry and the emitted event describe the WORK, from the text the
+    // item had BEFORE the citation was appended — otherwise the summary would
+    // carry the citation the DONE line already ends with, twice on one line.
+    const originalText = target ? String(target.text) : null;
+    if (target) {
+        target.done = true;
+        queueChanged = true;
+        const prRef = refsIn(args.pr)[0] ?? { raw: args.pr, repo: null, number: n };
+        const contextRepo = originRepoOf(repo);
+        const alreadyCited = refsIn(String(target.text)).some((r) => refsMatch(r, prRef, { contextRepo }));
+        if (!alreadyCited) {
+            citationAppended = ` · **closed by ${args.pr}${args.result ? ` — ${args.result.trim()}` : ""}**`;
+            target.text = `${target.text}${citationAppended}`;
+        }
+    }
+    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 = originalText !== null ? summarize(originalText) : 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 = [];
+    let stampedNotSupplied = [];
+    // A stale-base refusal is a RESULT, not a crash: the caller needs to know
+    // nothing was clobbered, what moved, and what this call had already written
+    // before it stopped. Thrown inside writeDoc so it cannot be ignored; converted
+    // here so the verb still answers.
+    try {
+        if (args.write) {
+            if (queueChanged) {
+                const w = writeDoc(repo, QUEUE_DOC, q.doc, q.text, wrote);
+                if (w.written)
+                    wrote.push(QUEUE_DOC);
+                // Rows stamped that this call did not ask to touch. `queueItemId` is the
+                // one item the caller supplied, so anything else here is a row that
+                // arrived unstamped from somewhere: the absorption this verb would
+                // otherwise carry to main under its own name.
+                stampedNotSupplied = w.stamped.filter((id) => id !== args.queueItemId);
+            }
+            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,
+                        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];
+                const parsed = parseWorkDoc(`## Done\n${doneLine}\n`);
+                const entry = doneEntriesOf(parsed)[0];
+                if (!entry) {
+                    return { ok: false, 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).written)
+                    wrote.push(DONE_DOC);
+            }
+        }
+    }
+    catch (e) {
+        if (e instanceof StaleWriteError) {
+            return {
+                ok: false,
+                error: e.message,
+                staleWrite: { doc: e.rel, drift: e.detail, alreadyWritten: e.alreadyWritten },
+            };
+        }
+        throw e;
+    }
+    // 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: [], deliveries: [], refused: [] };
+    if (args.write && target) {
+        const after = readDoc(repo, DONE_DOC);
+        const recordText = after?.text ?? "";
+        const ev = { kind: "item", target: target.id, ref: args.pr, summary: summarize(originalText ?? "") };
+        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,
+        project: args.project,
+        pr: `#${n}`,
+        comparedAgainst: ref,
+        landedIn: landedIn.slice(0, 8),
+        // THE ABSORBING WRITER LEARNS IT ABSORBED SOMETHING. The aide's
+        // diff-before-rename guard REFUSES on a foreign change; this REPORTS one it
+        // fixed, so a foreign row cannot pass silently in either direction.
+        ...(stampedNotSupplied.length
+            ? {
+                stampedNotSupplied,
+                stampNote: `recorded an id for ${stampedNotSupplied.length} queue item(s) this call did not supply (${stampedNotSupplied.join(", ")}) — ` +
+                    `they arrived unstamped, most likely a raw text append, and would have reddened doctor:queue-id-recorded on whoever committed next. ` +
+                    `Each id written is the one the item already had, so no value changed.`,
+            }
+            : {}),
+        queueItem: target
+            ? {
+                id: target.id,
+                closed: true,
+                // `textUnchanged` keeps its meaning — the priority and the body bytes
+                // the item had are all still there, in place. What is new is a SUFFIX
+                // on line 1, reported separately so a reader can tell "reworded" from
+                // "cited": null when the line already cited this PR.
+                textUnchanged: citationAppended === null,
+                bodyPreserved: true,
+                citationAppended,
+            }
+            : 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.",
+    };
+}
+/**
+ * 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) {
+    return (rollup ?? []).map((r) => {
+        const c = (r ?? {});
+        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" };
+        if (raw === "SUCCESS")
+            return { name, state: raw, verdict: "pass" };
+        // 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" };
+        return { name, state: raw || status || "UNKNOWN", verdict: "pending" };
+    });
+}
+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(),
+};
+const ghFacts = (repo, n) => {
+    const out = execFileSync("gh", ["pr", "view", n, "--json", "state,mergeable,statusCheckRollup"], {
+        cwd: repo,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+    const j = JSON.parse(out);
+    const gh = (args) => {
+        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"]) || "{}");
+    const subjects = (meta.commits ?? [])
+        .map((c) => c.messageHeadline ?? "")
+        .join("\n");
+    return {
+        state: String(j.state ?? ""),
+        mergeable: String(j.mergeable ?? ""),
+        checks: j.statusCheckRollup ?? [],
+        diff: gh(["pr", "diff", n]),
+        citationText: [String(meta.title ?? ""), subjects, String(meta.body ?? "")].join("\n"),
+    };
+};
+const ghMerge = (repo, n, method) => {
+    execFileSync("gh", ["pr", "merge", n, `--${method}`, "--delete-branch"], {
+        cwd: repo,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+};
+export async function mergeTool(args, facts = ghFacts, doMerge = ghMerge) {
+    const repo = args.repo ?? process.cwd();
+    const n = prNumber(args.pr);
+    if (!n)
+        return { ok: false, error: `'${args.pr}' names no PR number. Cite owner/repo#N.` };
+    let f;
+    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,
+            error: `could not read the checks for #${n} (${String(e.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, 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, 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, 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, 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) {
+        /*
+         * A RELATIONAL CITATION DOES NOT EVIDENCE A TICK.
+         *
+         * "unblocks Phase 5.2 Task 15.6" names the task without claiming it is done,
+         * so a PR that ticks 15.6's box and cites it that way is exactly as
+         * unevidenced as one that never mentioned it. Measured on the other side of
+         * this grammar the same day: doctor read that sentence in DONE.md as a
+         * completion claim and red-gated main.
+         *
+         * The two cases are REPORTED SEPARATELY, because they need different fixes
+         * and "UNCITED" would send someone looking for a citation that is already
+         * there. A relational citation needs REWORDING; an absent one needs ADDING.
+         */
+        const detail = phaseCitationsDetailed(f.citationText ?? "");
+        const closes = new Set(detail.filter((c) => c.relation === "claim").map((c) => c.key));
+        const relational = new Map(detail.filter((c) => c.relation === "reference").map((c) => [c.key, c.marker]));
+        const uncited = [...ticked].filter((k) => !closes.has(k));
+        if (uncited.length) {
+            const nameOf = (k) => { const [p, id] = k.split(":"); return `Phase ${p} Task ${id}`; };
+            const names = uncited.map(nameOf);
+            const worded = uncited.filter((k) => relational.has(k));
+            const missing = uncited.filter((k) => !relational.has(k));
+            const parts = [];
+            if (missing.length) {
+                parts.push(`${missing.length} NOT CITED AT ALL: ${missing.map(nameOf).join(", ")} — name them in the PR title or a commit ` +
+                    `subject (e.g. "${nameOf(missing[0])}"), the subject being what survives a squash merge`);
+            }
+            if (worded.length) {
+                parts.push(`${worded.length} cited only RELATIONALLY: ` +
+                    worded.map((k) => `${nameOf(k)} (after '${relational.get(k)}')`).join(", ") +
+                    ` — that names the task without claiming it is done, so it evidences nothing. Reword it, or drop the tick`);
+            }
+            return {
+                ok: false,
+                error: `#${n} ticks ${ticked.size} phase checkbox(es) and ${uncited.length} of them are UNEVIDENCED. ` +
+                    `${parts.join(". ")}. Once this merges, the tick claims progress nothing in history supports.`,
+                verdict,
+                uncited: names,
+            };
+        }
+    }
+    if (f.mergeable === "CONFLICTING")
+        return { ok: false, error: `#${n} is CONFLICTING with its base.`, verdict };
+    if (!args.write)
+        return { ok: true, merged: false, 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, merged: true, verdict };
+}
+//# sourceMappingURL=records.js.map