@sabaiway/agent-workflow-kit 10.0.0 → 10.2.0

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:\")