agent-coord-mcp 0.26.16 → 0.26.18

package/dist/tools/records.js

@@ -1,686 +0,0 @@
-/*
- * 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, phaseCitationsIn, newlyTickedInDiff, sweepTagOf, } from "@davidbalzan/groundwork-seam";
-import { ensureWorktreeTool } from "./worktrees.js";
-import { boardRefFor } from "./board-ref.js";
-import { haltState } 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.
- */
-function writeDoc(repo, rel, doc, original) {
-    const out = renderWorkDoc(doc);
-    if (out === original)
-        return false;
-    writeFileSync(path.join(repo, rel), out);
-    return true;
-}
-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;
-}
-// ---------- 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) {
-    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;
-    });
-}
-// ---------- 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);
-    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 = [];
-    // 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 = [];
-    let pick = null;
-    for (const { i } of ranked) {
-        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,
-        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,
-        boardHunks: [
-            ...skipped.map((s) => `⏭ skipped — blocked by ${s.blockedBy}`),
-            ...notClaimable.map((s) => `⏭ skipped — not worker-claimable (${s.sweepTag})`),
-        ],
-        // 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. Enforced at the WRITE as well as the read (board-ref.ts) — a rule the
-    // writer can defeat is a rule the writer defeats.
-    const boardHunk = `| ${keyOf(item)} | ${args.agentId} | \`${boardRefFor(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: "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(),
-};
-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 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 = [];
-    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,
-                    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.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: [], 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(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,
-        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.",
-    };
-}
-/**
- * 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) {
-        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,
-                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, 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