@sabaiway/agent-workflow-kit 9.0.0 → 10.1.0

package/tools/queue-audit.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+// The backlog queue as a CLASSIFIED corpus, not a prose pile.
+//
+// `docs/plans/queue.md` is the one long-lived surface in this family with no type, cap, rotation or
+// exit event: rows accumulate, a closed row stays listed because its 26 lines of measurements have
+// nowhere else to live, and a heading can say one thing while its body says another. The file's own
+// header already asked for the discipline in prose ("a DONE entry is <=5 lines") and it did not hold.
+// This module is the half prose cannot do — it says, per row and with the literal evidence, whether
+// the row is still WORK.
+//
+// Four classes, and the boundaries between them are deliberately conservative, because the consumer
+// of a `terminal` verdict is a DELETION:
+//
+//   live       no status marker decides otherwise — the default, and what a queue should hold.
+//   terminal   the row is DEAD — done, closed, superseded, moot, declined: a marker in the TITLE, or
+//              a marker OPENING a bold status line in the body (`**CLOSED 2026-07-20 …**`). The body
+//              decides when the title is silent — the real shape of a row that was closed in place.
+//   parked     the row is FROZEN, not dead: `PARKED` / `STOPPED` carry a stated resume condition, so
+//              deleting one loses work that is only waiting. Reported, never deleted, never a refusal.
+//   record     the row is not work at all: a TALLY counter or a SEQUENCING note.
+//   ambiguous  the row contradicts itself (a terminal AND a live marker in the title, or a bold
+//              terminal body under an explicitly QUEUED title). REPORTED, never auto-deleted.
+//
+// A terminal WORD in ordinary prose is NOT a status: rows routinely cite a sibling that was CLOSED or
+// explain why something was CUT, and reading that as the row's own state would delete live work. Only
+// the title and a bold status line are status positions.
+//
+// Markdown is read through the family's ONE block model (references/scripts/markdown-blocks.mjs) and
+// the ONE bullet scan the other queue reader uses (fold-scope.mjs) — fences, CRLF, indented headings
+// and the backtick-info-string rule are THEIR problem, never a second hand-rolled grammar here. A
+// document either of them refuses is a loud refusal, never a silent empty read.
+//
+// Pure string functions plus a thin CLI. Read-only: it reads the file it is pointed at and writes
+// nothing. Dependency-free, Node >= 22. No side effects on import.
+
+
+import { tokenizeMarkdown, fail } from '../references/scripts/markdown-blocks.mjs';
+import { bulletBlocks } from './fold-scope.mjs';
+import { CARRY_WORK, CLASSES, DEFAULTS, UNREAD_ITEM, classifyRow, titleOf } from './queue-audit-rows.mjs';
+
+// The row grammar is re-exported so one import names the whole reader: the CLI, the tests and any
+// consumer ask this module, and the split into a rules half stays an implementation detail.
+export { CLASSES, DEFAULTS, TERMINAL_MARKERS, FROZEN_MARKERS, LIVE_MARKERS, RECORD_PREFIXES, classifyRow, leadMarkers } from './queue-audit-rows.mjs';
+
+// The `[from, to)` body-line window a `--section` names: it opens after that heading and closes at
+// the next heading of the SAME level or higher, so a level-3 subheading stays inside. An absent
+// section is a named refusal — auditing the whole file when the caller asked for one section would
+// report rows the caller never meant to judge, and a deletion would follow.
+// `frontLines` is not decoration: every line number this module reports is a FILE line, frontmatter
+// included (the row manifest already adds it), so a refusal that named body-relative lines would send
+// a reader to the wrong place in the very file it is refusing.
+// ATX allows an optional CLOSING run of `#`, so `## Pending ##` and `## Pending` are the SAME
+// heading. Comparing raw text made them two: the audit took one, and every row under the other left
+// the domain silently — a section full of dead rows reported as zero rows and exit 0.
+const canonicalHeading = (text) =>
+  String(text ?? '')
+    .replace(/\r/g, '')
+    .replace(/\s+#+\s*$/, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+const sectionWindow = (headings, lines, section, frontLines = 0) => {
+  if (!section) return { from: 0, to: lines.length };
+  const wanted = canonicalHeading(section);
+  const matches = headings.filter((heading) => canonicalHeading(heading.text) === wanted);
+  // A usage error, not a document refusal: what is wrong is the ARGUMENT, and the CLI contract
+  // promises 2 for that. AMBIGUITY refuses on the same footing as absence: taking the first of two
+  // same-named headings would leave every row under the second one outside the audit — invisible to
+  // the caps, absent from the report a deletion is driven by, and silently so.
+  if (matches.length === 0) throw fail(2, `no section heading "${wanted}" in the queue — the audit refuses to guess its domain.`);
+  if (matches.length > 1) {
+    throw fail(2, `${matches.length} section headings read "${wanted}" (lines ${matches.map((h) => frontLines + h.index + 1).join(', ')}) — the audit refuses to pick one and leave the rest unjudged.`);
+  }
+  const [open] = matches;
+  const next = headings.find((heading) => heading.index > open.index && heading.level <= open.level);
+  return { from: open.index + 1, to: next ? next.index : lines.length };
+};
+
+// auditQueue(text, { section, label }) -> { rows, counts }. Each row carries its 1-based FILE line
+// (frontmatter included), the title as written, its class and the literal evidence for that class.
+export const auditQueue = (text, { section = null, label = 'the queue' } = {}) => {
+  const { lines, headings, fencedLines, frontLines } = tokenizeMarkdown(String(text ?? ''), label);
+  const { from, to } = sectionWindow(headings, lines, section, frontLines);
+  // A fence CONTINUES a queue row rather than ending it, and the cap judges the row's PHYSICAL span.
+  // Both halves are the same defect: a row carrying a code block reported one line and hid whatever
+  // followed the fence — its length from the cap, and a closure from the classifier.
+  // A list item this grammar cannot read is a REFUSAL, never a silence. `*` and `+` open a list in
+  // every Markdown dialect and a bare `-` is an empty item; none of them is a row here, and dropping
+  // them made a section of dead work report "0 rows" and exit 0 — a gate answering about a domain it
+  // never looked at. The queue writes `-` rows; anything else is corrected by hand, not guessed at.
+  for (let index = from; index < to; index += 1) {
+    if (fencedLines.has(index) || !UNREAD_ITEM.test(lines[index])) continue;
+    throw fail(2, `line ${frontLines + index + 1} opens a list item this audit does not read ("${lines[index].trim().slice(0, 40)}") — a queue row is a "- " bullet, and judging around this one would report a domain that was never looked at.`);
+  }
+  const rows = bulletBlocks(lines, fencedLines, from, to, { fenceContinues: true }).map((block) => {
+    const { klass, evidence } = classifyRow(block.lines, block.gaps);
+    return {
+      line: frontLines + block.start + 1,
+      lines: block.span,
+      title: titleOf(block.lines, block.gaps).text,
+      klass,
+      evidence,
+    };
+  });
+  const counts = Object.fromEntries(CLASSES.map((klass) => [klass, rows.filter((row) => row.klass === klass).length]));
+  return { rows, counts, total: rows.length };
+};
+
+// checkQueue(text, options) -> { ok, problems, notes }. A problem is a REFUSAL and every one of them
+// names a location: the family's bar is locations, never counts. An ambiguous row is a NOTE — it is
+// exactly the case a human must settle, and failing on it would make the cap unpassable by anyone
+// who did not already know the answer.
+export const checkQueue = (text, options = {}) => {
+  const { maxRows = DEFAULTS.maxRows, maxRowLines = DEFAULTS.maxRowLines, label = 'the queue' } = options;
+  const { rows, counts, total } = auditQueue(text, { section: options.section ?? null, label });
+  const problems = [];
+  const notes = [];
+
+  for (const row of rows) {
+    if (row.klass === 'terminal' || row.klass === 'record') {
+      problems.push(
+        `${label}:${row.line}: a ${row.klass} row is still listed (${row.evidence}) — its story belongs to the ` +
+          `ADR or the changelog, and the row leaves the queue in the same commit: ${row.title.slice(0, 80)}`,
+      );
+    }
+    if (row.klass === 'ambiguous') {
+      notes.push(`${label}:${row.line}: ambiguous (${row.evidence}) — settle it by hand: ${row.title.slice(0, 80)}`);
+    }
+    if (row.klass === 'parked') {
+      notes.push(`${label}:${row.line}: parked (${row.evidence}) — frozen, not dead: ${row.title.slice(0, 80)}`);
+    }
+    if (CARRY_WORK.has(row.klass) && row.lines > maxRowLines) {
+      problems.push(
+        `${label}:${row.line}: the row is ${row.lines} lines, over the ${maxRowLines}-line cap — a row names the ` +
+          `work; the measurements belong to a record or an ADR: ${row.title.slice(0, 80)}`,
+      );
+    }
+  }
+
+  // Both caps count EVERY row that still carries work, frozen and ambiguous included. Counting only
+  // `live` would let the queue grow without limit through the Frozen bucket — moving a row there, or
+  // leaving it self-contradicting, would buy room the cap is there to deny.
+  const working = rows.filter((row) => CARRY_WORK.has(row.klass)).length;
+  if (working > maxRows) {
+    problems.push(
+      `${label}: ${working} rows carry work, over the ${maxRows}-row cap — a backlog nobody can read is a dump. ` +
+        'Close, delete or fold rows before filing another.',
+    );
+  }
+
+  return { ok: problems.length === 0, problems, notes, counts, total };
+};
+
+// One tab-separated line per row: line, class, row-length, title. Deterministic and stable, so it can
+// be diffed between runs and used as the manifest a deletion is driven by.
+export const formatReport = (audit, { label = 'the queue' } = {}) => {
+  const head = [
+    `# queue-audit — ${label}`,
+    `# ${audit.total} rows: ${CLASSES.map((klass) => `${audit.counts[klass]} ${klass}`).join(' · ')}`,
+    '# line\tclass\tlines\ttitle\tevidence',
+  ];
+  const body = audit.rows.map((row) => [row.line, row.klass, row.lines, row.title, row.evidence].join('\t'));
+  return [...head, ...body].join('\n');
+};

package/tools/script-priors.mjs

@@ -33,6 +33,7 @@ export const SCRIPT_PRIORS = Object.freeze([
   prior('spec-schema.test.mjs', '4.6.0', '4.6.1', 'a12d6d3f5d32c6dabdee7e15af7d2ab15a0ced37515d1844fe0951f60cddbc99'),
   prior('spec-schema.mjs', '4.7.0', '4.7.0', '40b5b038d5ec5ed53c327c6d269d22fe5fa2bed99ae711fbf84306ad047be452'),
   prior('spec-schema.test.mjs', '4.7.0', '4.7.0', 'fde896419924223e54cfcabfdb1ef5807df5386fac700ed7c1463b6e7f81501b'),
+  prior('check-docs-size.mjs', '4.6.0', '6.0.0', '22d020c3668cdbfb4cbc1f67a8a85b2baa2d0c4956808a50626d37409e81ab38'),
 ]);
 
 export const digestOf = (bytes) => createHash('sha256').update(bytes).digest('hex');

package/tools/spec-check.mjs

@@ -43,7 +43,17 @@ const dirOf = (rel) => rel.slice(0, rel.lastIndexOf('/'));
 const leafOf = (rel) => rel.slice(rel.lastIndexOf('/') + 1);
 const bare = (rel) => (rel.endsWith('/') ? rel.slice(0, -1) : rel);
 const lineCount = (text) => text.replace(/\n$/, '').split('\n').length;
-const occurrences = (text, needle) => text.split(needle).length - 1;
+// A marker is counted as a WHOLE ordinal, never as a prefix of a longer one. A plain substring count
+// makes `spec:…/S1` occur twice the moment `spec:…/S11` is written in the same file — so a store
+// that reaches ten scenarios starts refusing bindings that are perfectly correct, and the refusal
+// names the wrong scenario. Measured here at S11.
+const occurrences = (text, needle) => {
+  let found = 0;
+  for (let at = text.indexOf(needle); at !== -1; at = text.indexOf(needle, at + needle.length)) {
+    if (!/[0-9]/.test(text[at + needle.length] ?? '')) found += 1;
+  }
+  return found;
+};
 // Containment is a question about path COMPONENTS, and only the platform's own path model answers
 // it. A textual prefix test reads "/repo\outside" as a child of "/repo" on a POSIX host — where the
 // backslash is an ordinary filename character — and it mis-reads a filesystem root ("/" or "C:\")

package/tools/spec-coverage-cli.mjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+// The CLI half of the coverage requirement: argv, fs and the debt record. No rule lives here (the
+// rule is spec-coverage.mjs), and the ratchet is enforced HERE because it is the only write.
+//
+// Exit codes: 0 accept; 1 refuse (an uncovered tool, or a settled debt entry still recorded); 2
+// usage — an unknown flag, a flag with no value, an unreadable scope or store, a reasonless write.
+
+import { readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { isDirectRun } from './direct-run.mjs';
+import { claimsOf, formatFindings, judgeCoverage, settleAfter } from './spec-coverage.mjs';
+
+export const SCOPE_PATH = join('docs', 'ai', 'spec-coverage.json');
+export const STORE_ROOT = join('docs', 'ai', 'specs');
+const REASON_MAX_BYTES = 300;
+
+const HELP = `spec-coverage — every shipped tool is governed by a contract, or the debt names it.
+
+Usage:
+  node spec-coverage-cli.mjs --report      [--root <dir>]
+  node spec-coverage-cli.mjs --check       [--root <dir>]
+  node spec-coverage-cli.mjs --write-debt --reason "<what was paid, and by which contract>" [--root <dir>]
+
+--report      one line per in-scope tool: the contract that covers it, or that none does.
+--check       refuses an in-scope tool no contract claims and is not recorded as debt, and a
+              recorded entry that is already settled — the record must not overstate the debt.
+--write-debt  records what was PAID: every adopted path whose contract now exists moves into the
+              settled set, and nothing else changes. It never touches the adoption baseline, so a
+              path outside it cannot be invented — it is refused by name. Write the contract first.
+
+Scope and debt: ${SCOPE_PATH}. Contracts: ${STORE_ROOT}. Exit codes: 0 accept; 1 refuse; 2 usage.`;
+
+const fail = (exitCode, message) => Object.assign(new Error(message), { exitCode });
+const posix = (p) => p.split(sep).join('/');
+
+// A scope this tool cannot trust is worse than no scope: `{}`, an empty `roots`, or an `exclude`
+// carrying an empty string all yield a census of ZERO tools and a cheerful PASS — a gate answering
+// about a domain it never looked at, which is the exact failure this whole rung exists to end.
+const validateScope = (scope, path) => {
+  const bad = (why) => { throw fail(2, `the coverage scope ${path} is unusable: ${why}`); };
+  if (scope === null || typeof scope !== 'object' || Array.isArray(scope)) bad('it is not an object');
+  if (scope.schema !== 1) bad(`schema must be 1, got ${JSON.stringify(scope.schema)}`);
+  const list = (key, required) => {
+    const value = scope[key];
+    if (value === undefined && !required) return [];
+    if (!Array.isArray(value) || value.some((v) => typeof v !== 'string' || v === '')) bad(`${key} must be an array of non-empty strings`);
+    if (required && value.length === 0) bad(`${key} is empty, so nothing would ever be judged`);
+    return value;
+  };
+  list('roots', true);
+  const extensions = list('extensions', true);
+  if (extensions.some((ext) => !ext.startsWith('.'))) bad('every extension starts with a dot');
+  list('exclude', false);
+  // Both recorded sets are PATHS. `Array.isArray` alone let `[42]` through, and a scope the tool
+  // cannot trust is the thing this validator exists to catch.
+  if (!Array.isArray(scope.adopted)) bad('adopted is the frozen set measured at adoption, and it must be an array');
+  list('adopted', false);
+  list('settled', false);
+  return scope;
+};
+
+const readJson = (path, what) => {
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch (err) {
+    throw fail(2, `cannot read ${what} ${path}: ${err.message}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw fail(2, `${what} ${path} is not valid JSON: ${err.message}`);
+  }
+};
+
+// Deterministic order in both walks: a report a human compares between runs must not depend on the
+// order a directory happens to be read in.
+const sorted = (entries) => [...entries].sort((a, b) => (a.name < b.name ? -1 : 1));
+
+export const specDocuments = (root, io = { readdirSync, readFileSync }) => {
+  const out = [];
+  const walk = (dir) => {
+    for (const entry of sorted(io.readdirSync(dir, { withFileTypes: true }))) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.name.endsWith('.md')) out.push({ rel: posix(relative(root, full)), text: io.readFileSync(full, 'utf8') });
+    }
+  };
+  walk(join(root, STORE_ROOT));
+  return out;
+};
+
+// A test file is never in scope: a contract governs the module, and its tests are the evidence FOR
+// that contract, not a second thing to write one for. A `<name>.test/` directory is the same answer.
+export const toolsIn = (root, scope, io = { readdirSync }) => {
+  const extensions = scope.extensions ?? ['.mjs'];
+  // A textual prefix is not a path. `.../fixtures` would also hide `.../fixtures-escape.mjs`, so a
+  // new tool could leave the scope by being named next to an excluded directory. The boundary is a
+  // path COMPONENT: the entry itself, or something under it.
+  const excluded = (rel) => (scope.exclude ?? []).some((prefix) => rel === prefix || rel.startsWith(`${prefix}/`));
+  const isTest = (name) => extensions.some((ext) => name.endsWith(`.test${ext}`));
+  const out = [];
+  const walk = (dir) => {
+    for (const entry of sorted(io.readdirSync(dir, { withFileTypes: true }))) {
+      const full = join(dir, entry.name);
+      const rel = posix(relative(root, full));
+      if (excluded(rel)) continue;
+      if (entry.isDirectory()) {
+        if (!entry.name.endsWith('.test')) walk(full);
+      } else if (extensions.some((ext) => entry.name.endsWith(ext)) && !isTest(entry.name)) out.push(rel);
+    }
+  };
+  for (const scopeRoot of scope.roots ?? []) walk(join(root, scopeRoot));
+  return out;
+};
+
+const parseArgv = (argv) => {
+  if (argv.length === 1 && (argv[0] === '--help' || argv[0] === '-h')) return { mode: 'help' };
+  const options = { mode: null, root: process.cwd(), reason: null };
+  const seen = new Set();
+  const valueOf = (index, flag) => {
+    const value = argv[index + 1];
+    if (value === undefined || value === '' || value.startsWith('--')) throw fail(2, `${flag} takes a value`);
+    return value;
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--report' || arg === '--check' || arg === '--write-debt') {
+      if (options.mode) throw fail(2, `--${options.mode} was already given — name exactly one mode`);
+      options.mode = arg.slice(2);
+    } else if (arg === '--root' || arg === '--reason') {
+      if (seen.has(arg)) throw fail(2, `${arg} was given twice — each option is named exactly once`);
+      seen.add(arg);
+      options[arg === '--root' ? 'root' : 'reason'] = valueOf(index, arg);
+      index += 1;
+    } else throw fail(2, `unknown argument "${arg}" — run with --help`);
+  }
+  if (!options.mode) throw fail(2, 'one of --report, --check or --write-debt is required — run with --help');
+  // A repayment with no stated reason is how a ratchet becomes a rubber stamp: the reason is recorded
+  // in the file it changes and is what the commit message and the changelog restate.
+  if (options.mode === 'write-debt' && !options.reason) throw fail(2, '--write-debt requires --reason "<what was paid, and by which contract>"');
+  if (options.reason && Buffer.byteLength(options.reason, 'utf8') > REASON_MAX_BYTES) {
+    throw fail(2, `a reason must be at most ${REASON_MAX_BYTES} UTF-8 bytes, got ${Buffer.byteLength(options.reason, 'utf8')}`);
+  }
+  return options;
+};
+
+export const main = (argv, { log = console.log, error = console.error, io } = {}) => {
+  let options;
+  try {
+    options = parseArgv(argv);
+  } catch (err) {
+    error(err.message);
+    return err.exitCode ?? 2;
+  }
+  if (options.mode === 'help') {
+    log(HELP);
+    return 0;
+  }
+
+  let scope;
+  let judged;
+  let unreadable;
+  try {
+    scope = validateScope(readJson(join(options.root, SCOPE_PATH), 'the coverage scope'), join(options.root, SCOPE_PATH));
+    const documents = specDocuments(options.root, io);
+    const found = claimsOf(documents);
+    unreadable = found.unreadable;
+    const tools = toolsIn(options.root, scope, io);
+    // A census of nothing is not a pass. Either the roots are wrong or the tree is not what the
+    // scope describes; both are refusals, never a green.
+    if (tools.length === 0) throw fail(2, `the declared roots (${(scope.roots ?? []).join(', ')}) hold no file this scope would judge — a census of zero is not a pass`);
+    judged = judgeCoverage({ tools, claims: found.claims, adopted: scope.adopted, settled: scope.settled ?? [] });
+  } catch (err) {
+    error(err.message);
+    return err.exitCode ?? 2;
+  }
+
+  if (options.mode === 'report') {
+    for (const { path, by } of judged.covered) log(`${path}\tcovered\t${by}`);
+    for (const path of judged.uncovered) log(`${path}\tuncovered\t-`);
+    for (const path of judged.debt) log(`${path}\tdebt\t-`);
+    return 0;
+  }
+
+  if (options.mode === 'write-debt') {
+    // What is PAYABLE is a subset of what was ADOPTED by construction — it is the owed set filtered,
+    // and the owed set is the baseline minus what is already settled. So this write cannot invent a
+    // path even in principle; `settleAfter` states that as a rule and refuses one directly, which is
+    // where it is asserted. A branch here would be unreachable, and an unreachable guard is not a
+    // guard: it is a claim nobody can check.
+    const next = settleAfter(scope.adopted, scope.settled ?? [], judged.payable);
+    // `adopted` is never rewritten here: it is the state this write is judged against.
+    writeFileSync(join(options.root, SCOPE_PATH), `${JSON.stringify({ ...scope, reason: options.reason, settled: next.settled }, null, 2)}\n`);
+    log(`spec-coverage: debt ${judged.debt.length} → ${judged.debt.length - next.added.length} (${next.added.length} paid and recorded)`);
+    log(`reason: ${options.reason}`);
+    return 0;
+  }
+
+  const findings = formatFindings({ ...judged, unreadable });
+  if (findings.length === 0) {
+    log(`spec-coverage: PASS — ${judged.covered.length} tool(s) governed by a contract, ${judged.debt.length} still owed`);
+    return 0;
+  }
+  error(`spec-coverage: FAIL — ${findings.length} finding(s) against ${join(options.root, SCOPE_PATH)}:`);
+  for (const line of findings) error(line);
+  error('spec-coverage: WHY — no work is done without a specification; a tool no contract governs promises nothing anyone can check.');
+  return 1;
+};
+
+if (isDirectRun(import.meta.url)) process.exitCode = main(process.argv.slice(2));

package/tools/spec-coverage.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// NO WORK IS DONE WITHOUT A SPECIFICATION — the half prose cannot do.
+//
+// The spec store answers "what does this module promise?" only for the modules somebody chose to
+// write a contract for, so a contract has been a suggestion: measured when this module was written,
+// 122 tool modules under `agent-workflow-kit/tools/` and 14 of them covered. This module makes the
+// contract a REQUIREMENT with a ratchet — a shipped tool no contract governs is a REFUSAL, and the
+// debt of today's uncovered tools may only shrink.
+//
+// The contract this module is built to is `docs/ai/specs/kit/spec-coverage.md`, and it was written
+// BEFORE this file. That order is the point: a contract amended after the code describes whatever
+// the last review happened to find, which makes review an open question with no bounded answer.
+//
+// Pure functions. No filesystem, no argv, no side effects on import — the CLI half owns all of that.
+// Dependency-free, Node >= 22.
+
+import { readSpecDocument } from '../references/scripts/spec-schema.mjs';
+
+// One `## Module` bullet, carried with the document that made the claim so a refusal can name the
+// owner. The two forms are the ones the spec schema already validates and there is no third here:
+// a `dir/` root covers by PREFIX, a file claim by EQUALITY. The trailing slash is what makes the
+// prefix test safe — `tools/manifest/` can never swallow `tools/manifest-validate.mjs`.
+// Only a LIVE contract claims shipped code. A `draft` is a proposal — it may name a module nobody
+// has built and bind a scenario to nothing — and a `retired` one has stopped promising anything. If
+// either counted, a tool could ship covered by a contract that was never in force.
+const CLAIMING_KINDS = new Set(['spec']);
+const CLAIMING_STATUS = 'live';
+
+export const claimsOf = (documents) => {
+  const claims = [];
+  const unreadable = [];
+  for (const { rel, text } of documents) {
+    const verdict = readSpecDocument(String(text ?? ''), rel);
+    // Only a CONTRACT claims code. A navigator (`kind: index`) lists children and a part belongs to
+    // the module its parent already claims, so neither is asked for a `## Module` — skipping them by
+    // KIND, never by the absence of the section, is what keeps the next line honest.
+    if (!CLAIMING_KINDS.has(verdict.kind) || verdict.status !== CLAIMING_STATUS) continue;
+    const module = verdict.structure?.module;
+    // A CONTRACT whose module cannot be read is its OWN finding, never a silent skip: the tools it
+    // would have covered would look uncovered and the refusal would name the wrong defect.
+    if (!module) unreadable.push({ rel, why: verdict.errors?.[0]?.message ?? 'no readable ## Module declaration' });
+    else for (const path of module.paths) claims.push({ path, form: module.form, by: rel });
+  }
+  return { claims, unreadable };
+};
+
+export const coveredBy = (claims, path) =>
+  claims.find((claim) => (claim.path.endsWith('/') ? path.startsWith(claim.path) : claim.path === path)) ?? null;
+
+// The verdict over one census. The debt is DERIVED — `adopted` minus `settled` — so there is no
+// stored list a hand can edit into a lie. Three findings:
+//   uncovered       a tool no contract covers and the derived debt does not owe — the refusal
+//   falselySettled  a path recorded as PAID whose contract is not there — the record claims what the
+//                   contracts do not say, and it is checked against them every run
+//   payable         a path still owed whose contract now EXISTS — the debt shrank and the record did
+//                   not, so run --write-debt; until then the record overstates what is owed
+export const judgeCoverage = ({ tools, claims, adopted = [], settled = [] }) => {
+  const paid = new Set(settled);
+  const owed = adopted.filter((path) => !paid.has(path));
+  const stillOwed = new Set(owed);
+  const present = new Set(tools);
+  const covered = [];
+  const uncovered = [];
+  for (const path of tools) {
+    const claim = coveredBy(claims, path);
+    if (claim) covered.push({ path, by: claim.by });
+    else if (!stillOwed.has(path)) uncovered.push(path);
+  }
+  const falselySettled = settled.filter((path) => present.has(path) && coveredBy(claims, path) === null);
+  const payable = owed.filter((path) => !present.has(path) || coveredBy(claims, path) !== null);
+  return { covered, uncovered, falselySettled, payable, debt: owed };
+};
+
+// What a `--write-debt` run may record: every path whose contract now exists moves into `settled`,
+// and nothing else changes. `adopted` is never touched, so a path that is not in it cannot be
+// invented — the run names it and says to write the contract.
+export const settleAfter = (adopted, settled, payable) => {
+  const unknown = payable.filter((path) => !adopted.includes(path));
+  if (unknown.length) return { ok: false, unknown };
+  return { ok: true, settled: [...new Set([...settled, ...payable])].sort(), added: payable };
+};
+
+export const formatFindings = ({ uncovered, falselySettled = [], payable = [], unreadable = [] }) => [
+  ...unreadable.map((u) => `  ${u.rel}: its ## Module cannot be read (${u.why}) — the tools it claims are unknown`),
+  ...uncovered.map((p) => `  ${p}: no contract under docs/ai/specs/ claims this module — write one, or it cannot ship`),
+  ...falselySettled.map((p) => `  ${p}: recorded as SETTLED, but no live contract claims it — the record asserts a contract that is not there`),
+  ...payable.map((p) => `  ${p}: still recorded as owed although it is covered now (or gone) — run --write-debt to record what was paid`),
+];