@sabaiway/agent-workflow-kit 10.0.0 → 10.1.0

package/CHANGELOG.md

@@ -4,6 +4,30 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 10.1.0 — no work without a specification, and a ratchet that does not trust its own file (AD-121)
+
+A shipped tool that no LIVE contract claims is now a REFUSAL, not a preference. `tools/spec-coverage.mjs`
+(the rule) and `tools/spec-coverage-cli.mjs` (argv, fs and the one write) read each contract's own
+`## Module` list as the coverage map — coverage is never declared twice — and a project declares the
+check as a gate. Measured at adoption in this repo: 122 tool modules, 14 governed by a contract.
+
+The other 108 are owed, and what is owed is never STORED — it is a subtraction. `adopted` is the set
+measured once at adoption and never rewritten; `settled` names the adopted paths whose contract has
+since been written; the debt is the difference. So there is no list a hand can edit into a lie: the
+only editable claim is "this one was paid", and every run checks that claim against the contracts
+themselves — a settled path no live contract covers refuses, and refuses twice, because the tool is
+uncovered again. A stored debt list was the first design and a review killed it: `--write-debt`
+refusing to add a path guaranteed nothing while nobody was obliged to use it.
+
+The scope file is validated before it is used: a wrong schema, an empty `roots` or `extensions`, a
+non-string entry, or a census of ZERO files all refuse — a gate that passes because it looked at
+nothing is not a pass. Exclusions are path-component boundaries, so excluding `x/fixtures` never also
+hides `x/fixtures-escape.mjs`. `draft` and `retired` contracts cover nothing.
+
+Also in this release: `tools/spec-check.mjs` counts a scenario marker as a WHOLE ordinal, so a store
+reaching ten scenarios no longer refuses a correct binding while naming the wrong scenario
+(`spec:x/S1` used to occur twice the moment `spec:x/S11` was written beside it).
+
 ## 10.0.0 — a symlinked docs file gets named instead of skipped (AD-119)
 
 Mirrors the memory canon: `references/scripts/check-docs-size.mjs` no longer lets a symlinked docs

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '10.0.0'
+  version: '10.1.0'
 ---
 
 # agent-workflow-kit

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "10.0.0",
+  "version": "10.1.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "10.0.0",
+  "version": "10.1.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/tools/fold-scope.mjs

@@ -44,25 +44,52 @@ const contains = (haystack, needle) => normalize(haystack).toLowerCase().include
 // AND a boundary: it closes the block it interrupts, so text past a fence can never join the bullet
 // before it (which would let a far-side literal satisfy a near-side claim). A `-` plus any whitespace
 // run opens a block; a blank or indented line continues it; any other unindented line closes it.
-// Blocks are returned RAW (their own lines) — the queue reader needs the field lines inside them.
-const bulletBlocks = (lines, fencedLines, from, to) => {
+// Blocks are returned RAW (their own lines) — the queue reader needs the field lines inside them —
+// each carrying the body index it OPENS at, because a second reader (queue-audit.mjs) reports rows by
+// file line and a scan that dropped the index would have to re-derive it against a different grammar.
+//
+// `fenceContinues` is the SECOND reader's question, and it is a different one. A deferral row asks
+// what a bullet CLAIMS, so a fence must cut it. A queue row asks what a bullet COSTS and whether it
+// is still work, and there the fence-as-boundary is a hole: measured, a row carrying a code block
+// reported ONE line and its `**DONE 2026-01-01:**` two lines further down was invisible, so the
+// per-row cap could be walked straight past and a closure went unseen.
+//
+// Under the option only a NESTED fence continues an open block — one whose opening line is indented,
+// which is what makes it part of the list item at all. A fence opening at column 0 is a
+// DOCUMENT-level block and still closes the row, exactly as an unindented line does; absorbing it
+// charged a one-line row for six. The run is decided ONCE, at its opening line, so a content line
+// inside it cannot re-decide the question.
+//
+// The absorbed lines never enter `lines` — a marker inside a quotation is not a status — so the
+// block records where they were: `span` is the row's PHYSICAL extent, and `gaps` holds the `lines`
+// indices a fence run follows, so a reader assembling a multi-line span cannot join text from both
+// sides of a code block into one claim.
+export const bulletBlocks = (lines, fencedLines, from, to, { fenceContinues = false } = {}) => {
   const blocks = [];
   let current = null;
+  let absorbing = null;
   const close = () => {
     if (current) blocks.push(current);
     current = null;
   };
   for (let index = from; index < to; index += 1) {
     if (fencedLines.has(index)) {
-      close();
+      if (absorbing === null) absorbing = Boolean(fenceContinues && current && /^\s+\S/.test(lines[index]));
+      if (!absorbing) close();
+      else {
+        current.span += 1;
+        current.gaps.add(current.lines.length - 1);
+      }
       continue;
     }
+    absorbing = null;
     const line = lines[index];
     if (BULLET.test(line)) {
       close();
-      current = [line];
+      current = { start: index, lines: [line], span: 1, gaps: new Set() };
     } else if (current && (line.trim() === '' || /^\s+\S/.test(line))) {
-      current.push(line);
+      current.lines.push(line);
+      current.span += 1;
     } else {
       close();
     }
@@ -83,7 +110,7 @@ export const extractAcceptance = (planText) => {
   if (!open) return [];
   const next = headings.find((heading) => heading.index > open.index && heading.level <= 2);
   return bulletBlocks(lines, fencedLines, open.index + 1, next ? next.index : lines.length)
-    .map((block) => normalize(block.join('\n').replace(/^-\s+/, '')))
+    .map((block) => normalize(block.lines.join('\n').replace(/^-\s+/, '')))
     .filter(Boolean);
 };
 
@@ -134,7 +161,7 @@ const exposureOf = (value) => {
 
 const topLevelRows = (queueText) => {
   const { lines, fencedLines } = tokenizeMarkdown(String(queueText ?? ''), 'the queue');
-  return bulletBlocks(lines, fencedLines, 0, lines.length).map((block) => block.join('\n'));
+  return bulletBlocks(lines, fencedLines, 0, lines.length).map((block) => block.lines.join('\n'));
 };
 
 const EMPTY_ROW = () => ({ found: false, matches: 0, fields: {}, missing: [...ROW_FIELDS], duplicates: [], exposure: null, closed: null, claimInInvariant: false });

package/tools/queue-audit-cli.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// The CLI half of the queue auditor: argv and fs, no rule (the rule is queue-audit.mjs).
+//
+// Split for the same reason fold-scope is split — a module you can hold whole is the unit of review,
+// and the rules file had reached the source-size cap. Read-only: it reads the file it is pointed at
+// and writes nothing. Dependency-free, Node >= 22.
+//
+// Exit codes: 0 accept; 1 refuse (a terminal/record row still listed, or a cap breach); 2 usage —
+// a missing/unknown flag, a flag with no value, an unreadable path, or a section that is not there.
+
+import { readFileSync } from 'node:fs';
+import { fail } from '../references/scripts/markdown-blocks.mjs';
+import { isDirectRun } from './direct-run.mjs';
+import { CLASSES, DEFAULTS, auditQueue, checkQueue, formatReport } from './queue-audit.mjs';
+
+const HELP = `queue-audit — classify the backlog queue's rows (agent-workflow family).
+
+Usage:
+  node queue-audit-cli.mjs --report <queue-file> [--section "## Pending / backlog (newest)"]
+  node queue-audit-cli.mjs --check  <queue-file> [--section "…"] [--max-rows N] [--max-row-lines N]
+
+--report  one tab-separated line per row: file line, class, row length, title, the literal evidence.
+          Deterministic — this is the manifest a deletion is driven by, never a regex guess.
+--check   refuses when a terminal or record row is still listed, when a row over the per-row line cap
+          carries work (live, parked and ambiguous alike), or when more rows than the row cap carry
+          work. Ambiguous rows are reported and never refuse on their own: a row that contradicts
+          itself, or names a status word outside a status position, is settled by a human.
+
+Classes: ${CLASSES.join(' · ')}. Defaults: --max-rows ${DEFAULTS.maxRows}, --max-row-lines ${DEFAULTS.maxRowLines}.
+
+Exit codes: 0 accept; 1 refuse; 2 usage (missing/unknown flag, unreadable path, bad section).`;
+
+// A flag whose value is MISSING refuses. `--section` with nothing after it used to fall through to
+// `null`, which means "audit the whole document" — silently widening the domain of a report a
+// deletion is driven by, in exactly the direction that costs live rows.
+const valueOf = (argv, index, flag) => {
+  const value = argv[index + 1];
+  if (value === undefined || value === '' || value.startsWith('--')) throw fail(2, `${flag} takes a value`);
+  return value;
+};
+
+const parseArgv = (argv) => {
+  // `--help` is answered ONLY when it is the whole invocation. A help flag that wins from anywhere
+  // makes `--check <dirty-file> --help` exit 0 — the gate's refusal replaced by a help page, which
+  // is the same bypass a second mode flag would be, reached by a flag nobody reads as dangerous.
+  if (argv.length === 1 && (argv[0] === '--help' || argv[0] === '-h')) return { mode: 'help' };
+  const options = { mode: null, path: null, section: null };
+  // Every option here is a SINGLETON. A repeat used to win silently: a second `--section` moved the
+  // domain the report covers and a softer `--max-rows` moved the ratchet, both without a word — and
+  // both in the direction that lets a queue keep rows a check would have refused.
+  const seen = new Set();
+  const once = (flag) => {
+    if (seen.has(flag)) throw fail(2, `${flag} was given twice — each option is named exactly once`);
+    seen.add(flag);
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--help' || arg === '-h') throw fail(2, '--help is answered only when it is the whole invocation — it never rides another mode');
+    else if (arg === '--report' || arg === '--check') {
+      // The mode is set ONCE. A later flag overwriting an earlier one would let `--check <f>
+      // --report <f>` answer a refusal question with an exit-0 report — the gate's verdict replaced
+      // by a listing, silently. Repetition is as wrong as conflict: both mean the caller asked two
+      // questions and only one was answered.
+      if (options.mode) throw fail(2, `--${options.mode} was already given — name exactly one of --report or --check`);
+      options.mode = arg.slice(2);
+      options.path = valueOf(argv, index, arg);
+      index += 1;
+    } else if (arg === '--section') {
+      once(arg);
+      options.section = valueOf(argv, index, arg);
+      index += 1;
+    } else if (arg === '--max-rows' || arg === '--max-row-lines') {
+      once(arg);
+      const value = Number(valueOf(argv, index, arg));
+      if (!Number.isInteger(value) || value <= 0) throw fail(2, `${arg} takes a positive integer, got "${argv[index + 1]}"`);
+      options[arg === '--max-rows' ? 'maxRows' : 'maxRowLines'] = value;
+      index += 1;
+    } else throw fail(2, `unknown argument "${arg}" — run with --help`);
+  }
+  if (!options.mode) throw fail(2, 'one of --report or --check is required — run with --help');
+  if (!options.path) throw fail(2, `${`--${options.mode}`} takes a queue file path`);
+  // A cap named beside `--report` used to be accepted and then ignored, and the run still exited 0 —
+  // so an operator who meant to ask a question about the caps was told nothing and read the silence
+  // as an answer. The caps belong to `--check`; naming one here is a usage error, not a no-op.
+  const capsInReport = ['--max-rows', '--max-row-lines'].filter((flag) => seen.has(flag));
+  if (options.mode === 'report' && capsInReport.length) {
+    throw fail(2, `${capsInReport.join(' and ')} ${capsInReport.length > 1 ? 'are' : 'is'} a --check option — --report lists every row and judges no cap`);
+  }
+  return options;
+};
+
+export const main = (argv, { log = console.log, error = console.error } = {}) => {
+  let options;
+  try {
+    options = parseArgv(argv);
+  } catch (err) {
+    error(err.message);
+    return err.exitCode ?? 2;
+  }
+  if (options.mode === 'help') {
+    log(HELP);
+    return 0;
+  }
+
+  let text;
+  try {
+    text = readFileSync(options.path, 'utf8');
+  } catch (err) {
+    error(`cannot read ${options.path}: ${err.message}`);
+    return 2;
+  }
+
+  try {
+    if (options.mode === 'report') {
+      log(formatReport(auditQueue(text, { section: options.section, label: options.path }), { label: options.path }));
+      return 0;
+    }
+    const result = checkQueue(text, { ...options, label: options.path });
+    for (const note of result.notes) log(note);
+    for (const problem of result.problems) error(problem);
+    log(
+      `${options.path}: ${result.total} rows — ` +
+        CLASSES.map((klass) => `${result.counts[klass]} ${klass}`).join(' · '),
+    );
+    return result.ok ? 0 : 1;
+  } catch (err) {
+    error(err.message);
+    return err.exitCode ?? 1;
+  }
+};
+
+// `process.exitCode`, never `process.exit()`: stdout is a PIPE under a gate runner, and an immediate
+// exit drops whatever of a large `--report` has not been flushed yet. A truncated manifest is worse
+// than none — it is the document a deletion is driven by, and a short one reads as a complete one.
+if (isDirectRun(import.meta.url)) process.exitCode = main(process.argv.slice(2));

package/tools/queue-audit-rows.mjs

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+// The STATUS GRAMMAR of a queue row: what one row says about its own state, and the literal evidence
+// for saying it. The DOCUMENT pass — which rows exist, which section they live in, what the caps say
+// — is queue-audit.mjs, and the argv/fs half is queue-audit-cli.mjs. Split at the seam the source-size
+// practice asks for: a module you can hold whole is the unit of review.
+//
+// Five 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 declares two states, or names a status word outside a status position.
+//              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.
+//
+// Pure string functions. No IO, no argv, no side effects on import. Dependency-free, Node >= 22.
+
+// The closed list the queue actually uses. `DONE` and `CLOSED` are the two fold-scope already knows
+// (its CLOSED_MARKERS); the rest are the states this corpus grew on its own. The check mark is a
+// marker in its own right because the file's DONE-entry convention leads with it.
+export const TERMINAL_MARKERS = ['✅', 'DONE', 'CLOSED', 'RESOLVED', 'DECIDED', 'SUPERSEDED', 'MOOT', 'DECLINED'];
+
+// FROZEN, not dead: each of these carries a stated condition under which the work resumes (measured:
+// "costs nothing until one is adopted again", "do NOT open tranche 4", "do NOT schedule without
+// recurring incidents"). They are classified apart precisely so a deletion pass cannot take them.
+export const FROZEN_MARKERS = ['PARKED', 'STOPPED'];
+
+// A title marker that declares the row still OPEN. Only these two: they are the ones the corpus
+// writes deliberately, and a wider list would turn ordinary words into status.
+export const LIVE_MARKERS = ['QUEUED', 'PENDING'];
+
+// Not work: a counter and an ordering note. Matched at the START of the title only.
+export const RECORD_PREFIXES = ['TALLY', 'SEQUENCING'];
+
+export const CLASSES = ['live', 'terminal', 'parked', 'record', 'ambiguous'];
+
+// The classes that still carry work, and therefore still cost a reader attention: both caps judge
+// exactly these.
+export const CARRY_WORK = new Set(['live', 'parked', 'ambiguous']);
+
+export const DEFAULTS = { maxRows: 60, maxRowLines: 12 };
+
+// A row is judged on the text it DECLARES, never on the text it QUOTES, and this is the ONE place
+// that distinction is made. Every quotation this grammar can recognise is removed before any marker
+// is looked for, and each is replaced by a SPACE so the tokens around it never become neighbours:
+//
+//   inline code  `` `DONE 2026-01-01` is parser input `` names a literal. Stripping the backticks and
+//                keeping the text turned a row ABOUT the parser into a closed row — a deletion.
+//   indented     a body line indented past the row's own continuation (2 spaces here, plus Markdown's
+//   code block   4) is a code block, so `      **DONE 2026-02-01:** sample` is sample output, not this
+//                row's status.
+//
+// A fenced region is handled one level up, by the block scan, and reaches here as a `gaps` boundary.
+// What remains is deliberately NOT exhaustive: this is a hand-written reader over a corpus, so the
+// residue is stated in the contract rather than guessed at, and the classes it can still misread are
+// reported (`ambiguous`), never deleted.
+const INLINE_CODE = /`[^`\n]*`/g;
+const CODE_INDENT = /^\s{6,}\S/;
+const quoteFree = (line) => String(line ?? '').replace(/\r/g, '').replace(INLINE_CODE, ' ');
+const judgeable = (line) => (CODE_INDENT.test(String(line ?? '')) ? '' : quoteFree(line));
+
+// The TITLE is the row's first bold span — `- **… — queued 2026-08-26.** prose` — and it ENDS where
+// that span closes, even when it wraps over several lines. Both halves matter: taking the whole first
+// line would read a sibling named in the prose after the title (`Its sibling was CLOSED …`) as this
+// row's own status, and taking only the first line would lose the marker of a title that wraps — the
+// common shape here, since a named row puts its id and `queued <date>` on the second line. A row with
+// no bold span falls back to its first line.
+export const titleOf = (blockLines, gaps = new Set()) => {
+  // A title never closes ACROSS a code block: the fenced lines a row absorbs are elided from its
+  // lines, so without this bound an opener above a fence and a `:**` below it become adjacent and a
+  // title assembles itself out of two halves the document never joined.
+  const upTo = [...gaps].filter((at) => at >= 0).sort((a, b) => a - b)[0];
+  const reach = upTo === undefined ? blockLines.length : upTo + 1;
+  const span = (render) => {
+    const first = render(String(blockLines[0] ?? ''));
+    const joined = blockLines.slice(0, reach).map(render).join('\n');
+    const open = first.indexOf('**');
+    const close = open === -1 ? -1 : joined.indexOf('**', open + 2);
+    return {
+      raw: close === -1 ? first : joined.slice(open + 2, close),
+      endLine: close === -1 ? 0 : joined.slice(0, close).split('\n').length - 1,
+    };
+  };
+  const flatten = (raw) => raw.replace(/^\s*[-*]\s+/, '').replace(/[*_]/g, '').replace(/\s+/g, ' ').trim();
+  // TWO renderings of one title, and the split is the point. `text` is what a HUMAN reads in the
+  // manifest, so it keeps every word the row wrote — eliding quoted code there turned readable titles
+  // into gaps ("codex and") in the very document a deletion is driven by. `judged` is what the
+  // MARKERS are looked for in, with quotations removed, so a row that names a literal is never
+  // mistaken for a row that declares a state.
+  const display = span((line) => String(line ?? '').replace(/\r/g, ''));
+  const judged = span(quoteFree);
+  return { text: flatten(display.raw).replace(/`/g, ''), judged: flatten(judged.raw), endLine: display.endLine };
+};
+
+// A word-boundary match that survives punctuation the corpus writes (`— CLOSED 2026-08-21 ·`), and
+// that never fires inside a longer word (`UNDECIDED`, `PARKED-ish`). The HYPHEN is a boundary that
+// does NOT count: every row id here is a kebab slug, so `IS-A-CLOSED-LIST` carries the word CLOSED as
+// part of a NAME, and reading that as the row's own status would delete live work (measured — it was
+// the only false positive in the 272-row corpus). The check mark is not a word character, so it is
+// matched literally.
+//
+// CASE is asymmetric, and the asymmetry is measured, not stylistic. A real status here is SHOUTED
+// (`QUEUED` · `DONE` · `CLOSED` · `PARKED`), while the same words in lower case are ordinary prose:
+// matching terminal markers case-insensitively flipped EIGHT live rows to terminal in one pass —
+// "(decided 2026-07-22)", "…is DEFERRED until resolved", "the class gets asked for … done" — every
+// one a false positive, every one a deletion. Live markers are the opposite: the corpus writes
+// `queued 2026-08-26` in lower case, so a case-sensitive live marker never fires and the
+// contradiction arm that PROTECTS a row goes dead. So: terminal and frozen are case-sensitive, live
+// is not. The cost of the split is a non-standard lower-case dead row staying `live` — visible, and
+// far cheaper than deleting work.
+// ONE identifier-aware boundary, used by every marker test here: a marker glued to any identifier
+// character — letter, DIGIT, underscore or hyphen — belongs to a NAME, not to a status. Measured
+// misses when it was letters-and-hyphen only: `DONE2-STATE-IS-UNREACHABLE` and
+// `CLOSED_LOOP-DESIGN-IS-UNDOCUMENTED` are live rows named after the thing they fix.
+// A TOP-LEVEL list item the row grammar does not take: a `*` or `+` bullet — with content or EMPTY,
+// since an empty one still opens a list whose indented content the audit would then never judge — or
+// a `-` with nothing after it. Indented items are nested content of a row and are read as its body.
+export const UNREAD_ITEM = /^(?:[*+](?:\s+\S|\s*$)|-\s*$)/;
+
+const IDENT = '[A-Za-z0-9_-]';
+const carries = (text, marker, { anyCase = false } = {}) =>
+  /^[A-Za-z]+$/.test(marker)
+    ? new RegExp(`(?<!${IDENT})${marker}(?!${IDENT})`, anyCase ? 'i' : '').test(text)
+    : text.includes(marker);
+
+const markersIn = (text, list, options) => list.filter((marker) => carries(text, marker, options));
+
+// A BOLD status line: `**CLOSED 2026-07-20 (…):** the story`. Anchored at the start of the line
+// (indent allowed) so a bold phrase mid-sentence is never a status, and requiring the marker to open
+// the bold span so `**Fix (small canon change):**` cannot become one.
+// A bold status may WRAP: the opener sits on one line and the `:**` on the next — two rows of the
+// live corpus are written that way, and a per-line matcher called both of them live, which is a
+// false GREEN from the gate that authorises deletions. So the span is read across continuation
+// lines, bounded so a `**` that never closes cannot swallow the rest of the row.
+const BOLD_OPEN = /^\s*\*\*\s*(.*)$/;
+const BOLD_SPAN_LINES = 4;
+
+// A span never reaches ACROSS a code block. The fenced lines a row absorbs are elided from its
+// lines, so without the gap set an opener above a fence and a `:**` below it become adjacent and
+// assemble into one claim that the document never made.
+const boldSpanAt = (blockLines, index, gaps = new Set()) => {
+  const first = BOLD_OPEN.exec(judgeable(blockLines[index]));
+  if (!first) return null;
+  let span = first[1];
+  for (let step = 0; step < BOLD_SPAN_LINES; step += 1) {
+    const close = span.indexOf('**');
+    if (close !== -1) return span.slice(0, close).replace(/:\s*$/, '');
+    const next = blockLines[index + step + 1];
+    if (next === undefined || gaps.has(index + step)) return null;
+    span += ` ${judgeable(next).trim()}`;
+  }
+  return null;
+};
+// The marker must OPEN the bold span, as a WHOLE token. A QUALIFIED closure closes a PART of the row,
+// not the row: `**PART (2) IS CLOSED …**`, `**SECOND FACE CLOSED …**`, `**+ bare-lane DECIDED …**`,
+// `**DISPOSITION DECIDED …**` all leave work behind, and five of the six body-decided rows in the live
+// corpus were exactly that shape. The token boundary matters too — `**CLOSED-loop design:**` is a
+// subheading about a loop, not a closure. A bare check mark with no word after it (`**✅ 2026-08-20:**`)
+// IS a status: the corpus leads its done entries with it.
+const LEAD_WORD = new RegExp(`^([A-Za-z]+)(?!${IDENT})`);
+const DATE = /^\d{4}-\d{2}-\d{2}/;
+// A real status carries its DATE, and that is measured, not stylistic: across the 272-row corpus the
+// status forms are `DONE 2026-08-21 ·`, `CLOSED 2026-07-20 (…)`, `SUPERSEDED 2026-08-21 by the row
+// above`, `PARKED 2026-08-21 by AD-105`, `RESOLVED 2026-08-25 —`; the same words in prose never do —
+// `STOPPED. That is`, `PARKED rather than`, `RESOLVED; the npm-pack`, `SUPERSEDED by a`. Requiring
+// the date is what keeps a row NAMED after the machinery it fixes (`CLOSED STATUS PARSER DROPS ROWS`,
+// `**DONE criteria:**`) out of the deletion set. A marker without one is not ignored — it makes the
+// row `ambiguous`, for a human.
+// The date is ADJACENT to the marker. A 40-character window of arbitrary text between the two was
+// measured wrong: `**DONE criteria due 2026-09-01:**` — a live row stating when its criteria are due
+// — read as a closure, and this verdict authorises a DELETION. The only gap the corpus actually
+// writes is a SECOND shouted status word introduced by `+`: `DONE + SHIPPED 2026-07-09`,
+// `DONE + PUBLISHED 2026-08-25` (measured — those three rows and nothing else in 6900 lines). So the
+// gap is exactly that, never prose: a `+` must introduce every extra word, which is what keeps
+// `DONE criteria due <date>` and `DONE CRITERIA <date>` out of the deletion set.
+const DATED_STATUS = /^(?:\s*\+\s*[A-Z][A-Z-]*)*\s*\d{4}-\d{2}-\d{2}/;
+
+// The markers OPENING a span, as whole tokens. A leading check mark alone declares NOTHING: the
+// corpus writes `**✅ ENTRY GATE OPEN:**` for a live gate, so the mark must be followed by a terminal
+// word or by a date — the form its done entries actually use (`**✅ 2026-08-20 (AD-100):**`).
+// `requireDate: false` answers the WEAKER question — does this span OPEN with a status word at all —
+// which is what separates "no status here" from "a status word with no date beside it". The second
+// is not silence: it is a row a human has to settle.
+export const leadMarkers = (span, list = TERMINAL_MARKERS, { requireDate = true } = {}) => {
+  let rest = String(span).replace(/\r/g, '').trimStart();
+  const tick = rest.startsWith('✅');
+  if (tick) rest = rest.slice(1).trimStart();
+  const word = LEAD_WORD.exec(rest);
+  const named = word ? list.filter((m) => m === word[1]) : [];
+  if (named.length && (!requireDate || DATED_STATUS.test(rest.slice(word[1].length)))) {
+    return tick ? ['✅', ...named] : named;
+  }
+  // A BARE check mark declares nothing on its own — the corpus writes `**✅ ENTRY GATE OPEN …**` for
+  // a LIVE gate — so it counts only in its DATED form, and the weaker question never takes it.
+  // Measured: dropping that guard turned three live rows into ambiguous, this one among them.
+  if (!named.length && tick && list.includes('✅') && requireDate && DATE.test(rest)) return ['✅'];
+  return [];
+};
+
+// A STATUS sits at the head of the title or at the head of one of its segments — `✅ DONE 2026-…`,
+// `A-ROW — ✅ CLOSED 2026-…`, `SUPERSEDED 2026-… by the row above`. A marker anywhere else is a
+// MENTION: `THE CLOSED state drops live work` is a defect report about closed state, not a closed
+// row, and deleting it would take live work. ONLY the documented separators split a segment — the
+// spaced dash family the corpus writes its status after. A bare hyphen would cut every kebab id into
+// pieces; a bracket or a colon would make `(CLOSED is an input)` and `note: DONE is a token` into
+// status heads, which is a row ABOUT status words being deleted for containing them.
+const SEGMENT_SPLIT = /\s+[—–]\s+/;
+const statusMarkersIn = (title, list) => [
+  ...new Set(
+    String(title)
+      .split(SEGMENT_SPLIT)
+      .flatMap((segment) => leadMarkers(segment, list)),
+  ),
+];
+
+const boldStatusMarkers = (blockLines, from, { list = TERMINAL_MARKERS, gaps, ...options } = {}) => {
+  for (let offset = from + 1; offset < blockLines.length; offset += 1) {
+    const span = boldSpanAt(blockLines, offset, gaps);
+    if (span === null) continue;
+    const found = leadMarkers(span, list, options);
+    if (found.length) return { markers: found, offset };
+  }
+  return null;
+};
+
+const evidenceOf = (parts) => parts.filter(Boolean).join(' + ');
+
+// classifyRow(blockLines) -> { klass, evidence }. The order of the arms IS the rule: a record is
+// judged before any status, a contradiction before the state it contradicts, and `live` is what
+// survives when nothing else decided.
+export const classifyRow = (blockLines, gaps) => {
+  const { judged: title, endLine } = titleOf(blockLines, gaps);
+  // The prefix must be a whole token: `TALLYING-FAILURES-HAS-NO-RUNG` and `SEQUENCING-BUG-IN-THE-
+  // DISPATCHER` are work, and a bare `startsWith` would have the checker demand their deletion.
+  const record = RECORD_PREFIXES.find((prefix) => new RegExp(`^${prefix}(?!${IDENT})`).test(title));
+  if (record) return { klass: 'record', evidence: `title opens with ${record}` };
+
+  // EVERY status of every class is gathered BEFORE anything is decided. Deciding as they were found
+  // made two states unreachable: a frozen title returned before the contradiction arms could see a
+  // live marker beside it, so `PARKED … — QUEUED …` read as simply parked, and the body was scanned
+  // for terminal markers only, so a dated `**PARKED 2026-08-21 …**` closing a row in place was not a
+  // state at all.
+  const titleFrozen = statusMarkersIn(title, FROZEN_MARKERS);
+  const titleTerminal = statusMarkersIn(title, TERMINAL_MARKERS);
+  const titleLive = markersIn(title, LIVE_MARKERS, { anyCase: true });
+  const bodyTerminal = boldStatusMarkers(blockLines, endLine, { gaps });
+  const bodyFrozen = boldStatusMarkers(blockLines, endLine, { gaps, list: FROZEN_MARKERS });
+  // The body declares LIVE too, and leaving it out of the table was the dangerous half: a row whose
+  // body said `**QUEUED 2026-08-20:**` and then `**CLOSED 2026-01-01:**` was read as simply closed —
+  // a contradiction handed to a deletion as a verdict. A live marker never needs its date here (the
+  // corpus writes `queued` in lower case, and the arm that reads it PROTECTS the row).
+  const bodyLive = boldStatusMarkers(blockLines, endLine, { gaps, list: LIVE_MARKERS, requireDate: false });
+  // A marker the title carries somewhere OTHER than a status head. It cannot decide the row, and it
+  // cannot be ignored either — a human settles it. The check mark STAYS in this path, and the
+  // asymmetry with the body side is measured, not an oversight: in a TITLE the corpus writes
+  // `✅ Plan 3 / 3 — …` as a done marker (ten such rows), so dropping it turned ten reported rows
+  // silent; in a BOLD BODY span it writes `**✅ ENTRY GATE OPEN …**` for a gate that OPENED. Same
+  // glyph, two positions, two meanings — and the position is what this module already reads.
+  const mentioned = markersIn(title, [...TERMINAL_MARKERS, ...FROZEN_MARKERS]).filter(
+    (marker) => !titleTerminal.includes(marker) && !titleFrozen.includes(marker),
+  );
+  if (!titleTerminal.length && !titleFrozen.length && mentioned.length) {
+    return { klass: 'ambiguous', evidence: `title mentions ${mentioned.join(', ')} outside a status position` };
+  }
+  // A row that declares two states declares none: it is REPORTED, and a human settles it. The title
+  // and the body are read into ONE table and reduced by CLASS, never by position — an earlier version
+  // let the title's own state hide the body's, so a terminal title above a `**PARKED <date>:**` body
+  // stayed terminal and kept authorising a deletion while the row declared two things. Two sightings
+  // of the SAME class are one state (a title and a body that agree do not contradict).
+  const sightings = [
+    titleTerminal.length && { klass: 'terminal', evidence: `title: ${titleTerminal.join(', ')}` },
+    titleFrozen.length && { klass: 'parked', evidence: `title: ${titleFrozen.join(', ')}` },
+    titleLive.length && { klass: 'live', evidence: `title: ${titleLive.join(', ')}` },
+    bodyTerminal && { klass: 'terminal', evidence: `body +${bodyTerminal.offset}: ${bodyTerminal.markers.join(', ')}` },
+    bodyFrozen && { klass: 'parked', evidence: `body +${bodyFrozen.offset}: ${bodyFrozen.markers.join(', ')}` },
+    bodyLive && { klass: 'live', evidence: `body +${bodyLive.offset}: ${bodyLive.markers.join(', ')}` },
+  ].filter(Boolean);
+  const declared = [...new Set(sightings.map((s) => s.klass))];
+  if (declared.length > 1) return { klass: 'ambiguous', evidence: evidenceOf(sightings.map((s) => s.evidence)) };
+  if (declared.length === 1 && declared[0] !== 'live') {
+    return { klass: declared[0], evidence: evidenceOf(sightings.map((s) => s.evidence)) };
+  }
+
+  // A bold body span that OPENS with a status word but carries no date beside it is the residue of
+  // the date rule, and silence is the wrong answer for it: `**DONE criteria due 2026-09-01:**` used
+  // to be read as a closure, and the fix must not turn it into "nothing to see". It is REPORTED as
+  // ambiguous — visible to a human, never deletable by a machine. Measured: with the bare-check-mark
+  // guard in place, zero rows in the live 314-row corpus and zero in the 62-row purge archive take
+  // this arm, so it closes a door without moving a single existing verdict.
+  const undated = boldStatusMarkers(blockLines, endLine, { gaps, requireDate: false })
+    ?? boldStatusMarkers(blockLines, endLine, { gaps, list: FROZEN_MARKERS, requireDate: false });
+  if (undated) {
+    return {
+      klass: 'ambiguous',
+      evidence: `body +${undated.offset}: ${undated.markers.join(', ')} with no date beside it`,
+    };
+  }
+
+  return { klass: 'live', evidence: 'no status marker' };
+};
+
+// The `[from, to)` body-line window a `--section` names: it opens after that heading and closes at

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/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`),
+];