@sabaiway/agent-workflow-kit 12.0.0 → 12.1.0

package/tools/now-status.mjs

@@ -0,0 +1,145 @@
+import { bulletBlocks, isSweep } from './plan-shape.mjs';
+import { canonicalHeading } from './queue-audit.mjs';
+import { CARRY_WORK, CLASSES, leadMarkers, titleOf } from './queue-audit-rows.mjs';
+
+export const NOW_STATUS = Object.freeze({
+  LANDED: 'landed',
+  IN_PROGRESS: 'in progress',
+  PENDING: 'pending',
+  UNJUDGED: 'unjudged',
+});
+
+export const NOW_ANNOTATION = Object.freeze({
+  CLAIM: 'claim',
+  ANOMALY: 'anomaly',
+  RED_PROOF: 'red-proof',
+});
+
+const EVIDENCE_SOURCE = Object.freeze({
+  PATH: 'path fact',
+  CHANGED: 'changed set',
+  EXCLUSION: 'exclusion fact',
+});
+const PHASE_PREFIX = '## Phase: ';
+const PRIORITY_HEADING = canonicalHeading('## Pending / backlog');
+
+export const isWithheld = (block) => typeof block?.withheld === 'string';
+const CHECKED_TASK = /(?:^|\s)\[[xX]\](?:\s|$)/;
+
+const getResponsibility = (raw) => String(raw ?? '').split(' | ')[3] ?? '';
+const getJudgedProse = (raw) => titleOf([getResponsibility(raw)]).judged;
+
+export const readProseClaim = (raw) => {
+  const prose = getJudgedProse(raw);
+  return CHECKED_TASK.test(prose) || leadMarkers(prose).length > 0 ? 'done' : null;
+};
+
+const getChangedDetail = ({ staged, unstaged, untracked }) => {
+  const parts = [staged ? 'staged' : null, unstaged ? 'unstaged' : null, untracked ? 'untracked' : null].filter(Boolean);
+  return parts.join(', ');
+};
+
+const getPathDecision = (row, evidence) => {
+  const pathFact = evidence.pathFact;
+  if (!pathFact) return { status: NOW_STATUS.UNJUDGED, detail: 'path fact unavailable', evidenceSource: EVIDENCE_SOURCE.PATH };
+  const present = pathFact.kind !== 'absent';
+  if (row.verb === 'create') {
+    return { status: present ? NOW_STATUS.LANDED : NOW_STATUS.PENDING, detail: null, evidenceSource: EVIDENCE_SOURCE.PATH };
+  }
+  if (row.verb === 'delete') {
+    return { status: present ? NOW_STATUS.PENDING : NOW_STATUS.LANDED, detail: null, evidenceSource: EVIDENCE_SOURCE.PATH };
+  }
+  if (!present) return { status: NOW_STATUS.PENDING, detail: 'post-state unmet', evidenceSource: EVIDENCE_SOURCE.PATH };
+  return {
+    status: NOW_STATUS.UNJUDGED,
+    detail: evidence.excluded === true ? 'excluded from git here, no changed-set evidence' : 'no base-motion reader',
+    evidenceSource: EVIDENCE_SOURCE.EXCLUSION,
+  };
+};
+
+const getAnnotations = (row, evidence, status) => {
+  const claim = readProseClaim(row.raw) && status !== NOW_STATUS.LANDED
+    ? [{ kind: NOW_ANNOTATION.CLAIM, text: 'claimed done' }]
+    : [];
+  const overBudget = row.budgetLines && evidence.pathFact?.kind === 'regular' && evidence.pathFact.lines > row.budgetLines
+    ? [{ kind: NOW_ANNOTATION.ANOMALY, text: `over budget ${evidence.pathFact.lines}/${row.budgetLines}` }]
+    : [];
+  const redProof = evidence.redProof
+    ? [{ kind: NOW_ANNOTATION.RED_PROOF, text: evidence.redProof.currency ?? String(evidence.redProof) }]
+    : [];
+  return [...claim, ...overBudget, ...redProof];
+};
+
+// A set has no single post-state, so a sweep row is reduced only under modify: the verb refuses it before any evidence arm.
+const SWEEP_VERB_REFUSAL = Object.freeze({ status: NOW_STATUS.UNJUDGED, detail: 'a sweep row is judged as a set only under modify', evidenceSource: EVIDENCE_SOURCE.PATH });
+
+export const judgeRow = (row, evidence = {}) => {
+  const changed = Boolean(evidence.staged || evidence.unstaged || evidence.untracked);
+  const decision = isSweep(row.path) && row.verb !== 'modify'
+    ? SWEEP_VERB_REFUSAL
+    : changed
+      ? { status: NOW_STATUS.IN_PROGRESS, detail: getChangedDetail(evidence), evidenceSource: EVIDENCE_SOURCE.CHANGED }
+      : getPathDecision(row, evidence);
+  return { row, ...decision, annotations: getAnnotations(row, evidence, decision.status) };
+};
+
+const getPhaseSteps = (parsed, heading) => {
+  const document = parsed.document;
+  const next = document.headings.find((candidate) => candidate.index > heading.index && candidate.level <= heading.level);
+  const end = next?.index ?? document.lines.length;
+  return bulletBlocks(document.lines, document.fencedLines, heading.index + 1, end).map((block) => ({
+    name: block.lines.join(' ').replace(/^-\s+/, '').replace(/\s+/g, ' ').trim(),
+    status: NOW_STATUS.UNJUDGED,
+    detail: 'no evidence reader',
+    evidenceSource: null,
+    annotations: [],
+  }));
+};
+
+const getMarkers = (name, steps) => {
+  const currentIndex = steps.findIndex(({ status }) => status !== NOW_STATUS.LANDED && status !== NOW_STATUS.IN_PROGRESS);
+  return {
+    name,
+    steps,
+    inProgress: steps.filter(({ status }) => status === NOW_STATUS.IN_PROGRESS),
+    current: currentIndex < 0 ? null : steps[currentIndex],
+    next: currentIndex < 0 ? null : steps[currentIndex + 1] ?? null,
+  };
+};
+
+export const derivePhase = (parsed, judged) => {
+  const complete = judged.length > 0 && judged.every(({ status }) => status === NOW_STATUS.LANDED);
+  if (!complete) return getMarkers('ledger', judged);
+  const verification = parsed.document.headings.find(({ text }) => text === '## Verification');
+  const heading = parsed.document.headings.find(({ index, text }) => index > verification.index && text.startsWith(PHASE_PREFIX));
+  const steps = heading ? getPhaseSteps(parsed, heading) : [];
+  return getMarkers(heading ? heading.text.slice(PHASE_PREFIX.length) : 'Cleanup', steps);
+};
+
+const getBucketKey = (buckets) => JSON.stringify(buckets ?? []);
+const getBucketLabel = (buckets) => buckets.length === 0
+  ? 'document'
+  : buckets.map(({ text, line }) => `${text} (line ${line})`).join(' > ');
+const isPriorityBucket = (buckets) => buckets.some(({ level, text }) => level === 2 && canonicalHeading(text) === PRIORITY_HEADING);
+const getCounts = (rows) => Object.fromEntries(CLASSES.map((klass) => [klass, rows.filter((row) => row.klass === klass).length]));
+
+export const foldQueue = (rows) => {
+  const folded = rows.reduce((buckets, row) => {
+    const path = row.buckets ?? [];
+    const key = getBucketKey(path);
+    const found = buckets.find((bucket) => bucket.key === key);
+    const entry = {
+      name: row.name || `unnamed (line ${row.line})`,
+      line: row.line,
+      klass: row.klass,
+      evidence: row.evidence,
+      position: (found?.rows.length ?? 0) + 1,
+    };
+    const entries = CARRY_WORK.has(row.klass) ? [...(found?.rows ?? []), entry] : found?.rows ?? [];
+    return found
+      ? buckets.map((bucket) => bucket.key === key ? { ...bucket, sourceRows: [...bucket.sourceRows, row], rows: entries } : bucket)
+      : [...buckets, { key, path, label: getBucketLabel(path), order: isPriorityBucket(path) ? 'priority' : 'position', sourceRows: [row], rows: entries }];
+  }, []);
+  const buckets = folded.map(({ key, sourceRows, ...bucket }) => ({ ...bucket, counts: getCounts(sourceRows) }));
+  return { buckets, counts: getCounts(rows), total: rows.length };
+};

package/tools/plan-shape-facts.mjs

@@ -120,7 +120,7 @@ const compileGlob = (pattern) => {
   }
 };
 
-const expandPatterns = (repoFiles, patterns) => Object.fromEntries(patterns.map((pattern) => {
+export const expandPatterns = (repoFiles, patterns) => Object.fromEntries(patterns.map((pattern) => {
   const compiled = compileGlob(pattern);
   if (!compiled) throw planError(`unsupported glob in plan path: ${pattern}`);
   return [pattern, repoFiles.filter((path) => compiled.test(path))];

package/tools/queue-audit-cli.mjs

@@ -5,8 +5,9 @@
 // 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.
+// Exit codes: 0 accept; 1 refuse (a terminal/record row still listed, a cap breach, or — when and
+// only when `--require-names` is named — a row whose name is not a sentence); 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';
@@ -17,7 +18,7 @@ const HELP = `queue-audit — classify the backlog queue's rows (agent-workflow
 
 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]
+  node queue-audit-cli.mjs --check  <queue-file> [--section "…"] [--max-rows N] [--max-row-lines N] [--require-names]
 
 --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.
@@ -25,6 +26,10 @@ Usage:
           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.
+--require-names  the opt-in a project adds once its rows are named: a row whose name is not a plain
+          sentence refuses with exit 1 instead of printing a note. Without it every name finding is
+          a NOTE and the verdict is byte for byte what it was, so a queue that has not migrated is
+          never bricked by an upgrade it did not ask for.
 
 Classes: ${CLASSES.join(' · ')}. Defaults: --max-rows ${DEFAULTS.maxRows}, --max-row-lines ${DEFAULTS.maxRowLines}.
 
@@ -44,7 +49,7 @@ const parseArgv = (argv) => {
   // 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 };
+  const options = { mode: null, path: null, section: null, requireNames: false };
   // 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.
@@ -69,6 +74,9 @@ const parseArgv = (argv) => {
       once(arg);
       options.section = valueOf(argv, index, arg);
       index += 1;
+    } else if (arg === '--require-names') {
+      once(arg);
+      options.requireNames = true;
     } else if (arg === '--max-rows' || arg === '--max-row-lines') {
       once(arg);
       const value = Number(valueOf(argv, index, arg));
@@ -79,12 +87,11 @@ const parseArgv = (argv) => {
   }
   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`);
+  // A check-only option named beside `--report` used to be accepted and then ignored, and the run
+  // still exited 0. Those options belong to `--check`; naming one here is usage, not a no-op.
+  const checkOnlyInReport = ['--max-rows', '--max-row-lines', '--require-names'].filter((flag) => seen.has(flag));
+  if (options.mode === 'report' && checkOnlyInReport.length) {
+    throw fail(2, `${checkOnlyInReport.join(' and ')} ${checkOnlyInReport.length > 1 ? 'are' : 'is'} a --check option — --report lists every row and judges no check-only rule`);
   }
   return options;
 };

package/tools/queue-audit-rows.mjs

@@ -23,6 +23,8 @@
 //
 // Pure string functions. No IO, no argv, no side effects on import. Dependency-free, Node >= 22.
 
+import { nameOf } from './queue-row-name.mjs';
+
 // 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.
@@ -37,7 +39,9 @@ export const FROZEN_MARKERS = ['PARKED', 'STOPPED'];
 // 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.
+// Not work: a counter and an ordering note. Read by POSITION like every other status — the head of
+// the title, or the head of a ` — `-separated segment, and everywhere but the title head the marker
+// owes a DATE adjacent to it, the form the counter is always written in.
 export const RECORD_PREFIXES = ['TALLY', 'SEQUENCING'];
 
 export const CLASSES = ['live', 'terminal', 'parked', 'record', 'ambiguous'];
@@ -97,7 +101,9 @@ export const titleOf = (blockLines, gaps = new Set()) => {
   // 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 };
+  const text = flatten(display.raw).replace(/`/g, '');
+  const { name, id } = nameOf(nameSource(text));
+  return { text, name, id, judged: flatten(judged.raw), endLine: display.endLine };
 };
 
 // A word-boundary match that survives punctuation the corpus writes (`— CLOSED 2026-08-21 ·`), and
@@ -126,9 +132,11 @@ export const titleOf = (blockLines, gaps = new Set()) => {
 export const UNREAD_ITEM = /^(?:[*+](?:\s+\S|\s*$)|-\s*$)/;
 
 const IDENT = '[A-Za-z0-9_-]';
+const wordMatches = (text, marker, { anyCase = false } = {}) =>
+  Array.from(String(text).matchAll(new RegExp(`(?<!${IDENT})${marker}(?!${IDENT})`, anyCase ? 'giu' : 'gu')));
 const carries = (text, marker, { anyCase = false } = {}) =>
   /^[A-Za-z]+$/.test(marker)
-    ? new RegExp(`(?<!${IDENT})${marker}(?!${IDENT})`, anyCase ? 'i' : '').test(text)
+    ? wordMatches(text, marker, { anyCase }).length > 0
     : text.includes(marker);
 
 const markersIn = (text, list, options) => list.filter((marker) => carries(text, marker, options));
@@ -189,14 +197,17 @@ const DATED_STATUS = /^(?:\s*\+\s*[A-Z][A-Z-]*)*\s*\d{4}-\d{2}-\d{2}/;
 // `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 } = {}) => {
+export const leadMarkers = (span, list = TERMINAL_MARKERS, { requireDate = true, anyCase = false } = {}) => {
   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]) : [];
+  // The tick joins the answer only when the LIST being asked about carries it. Prepending it to a
+  // frozen, live or RECORD answer named the wrong marker in the evidence a deletion is read from.
+  const named = word ? list.filter((m) => anyCase ? m.toLowerCase() === word[1].toLowerCase() : m === word[1]) : [];
+  const withTick = (found) => (tick && list.includes('✅') ? ['✅', ...found] : found);
   if (named.length && (!requireDate || DATED_STATUS.test(rest.slice(word[1].length)))) {
-    return tick ? ['✅', ...named] : named;
+    return withTick(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.
@@ -213,14 +224,54 @@ export const leadMarkers = (span, list = TERMINAL_MARKERS, { requireDate = true
 // 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) => [
+const statusMarkersIn = (title, list, options) => [
   ...new Set(
     String(title)
       .split(SEGMENT_SPLIT)
-      .flatMap((segment) => leadMarkers(segment, list)),
+      .flatMap((segment) => leadMarkers(segment, list, options)),
   ),
 ];
 
+// The NAME is what remains after the row's own STATUS declarations, and this is where the two
+// grammars meet: the readability judge owns the sentence, this module owns the status vocabulary, so
+// the drop happens HERE rather than by restating four marker lists in a second home. Every LEADING
+// ` — `-segment that OPENS with a status word is removed before the name is cut — measured on the
+// live corpus, `PARKED 2026-08-21 by AD-105 (…) — QUEUED 2026-08-20 — B — A-PLAN-REVIEW-…` was
+// passing the readability bar with its own PARKED declaration as the row's "name", which is the
+// exact class of unreadable row the bar exists for. The date is not required here: the question is
+// only whether a human reading the head of that segment meets a status word instead of a name.
+// Stated residual: the segments are judged on the DISPLAY text, so a QUOTED status word opening a
+// segment drops it too — a stricter name, never a missed one.
+// The CASE asymmetry is the classifier's own and it holds here too: terminal, frozen and record
+// words are SHOUTED, live words are not. Reading all four case-insensitively deleted the name of a
+// row that opens with an ordinary verb — `Tally the remaining broken gates — ROW-A` lost its whole
+// name to a `TALLY` that was never there. And the remainder is returned as a SLICE of the display
+// title, never re-joined from the split parts: re-joining rewrote every en dash the row wrote into
+// an em dash, so the "name" stopped being the bytes a human is shown.
+const SHOUTED_STATUS = [...TERMINAL_MARKERS, ...FROZEN_MARKERS, ...RECORD_PREFIXES];
+const opensWithStatus = (segment) =>
+  leadMarkers(segment, SHOUTED_STATUS, { requireDate: false }).length > 0
+  // The DATED bare tick is a status the weaker question cannot see — that arm is guarded by
+  // `requireDate` — and it was the one form of status this drop still left inside a name:
+  // `✅ 2026-08-20 — PARKED 2026-08-21 by AD-105 — A-ROW` was named by its own status text and
+  // passed the bar with no finding at all, which is the blocker this drop exists to close.
+  || leadMarkers(segment, TERMINAL_MARKERS).length > 0
+  || leadMarkers(segment, LIVE_MARKERS, { requireDate: false, anyCase: true }).length > 0;
+const nameSource = (title) => {
+  const text = String(title);
+  let at = 0;
+  for (const segment of text.split(SEGMENT_SPLIT)) {
+    const start = text.indexOf(segment, at);
+    if (!opensWithStatus(segment)) return text.slice(start);
+    at = start + segment.length;
+  }
+  return '';
+};
+
+const datedMarkersIn = (title, list, options) => list.filter((marker) =>
+  wordMatches(title, marker, options).some((match) => DATED_STATUS.test(String(title).slice(match.index + match[0].length))),
+);
+
 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);
@@ -233,15 +284,20 @@ const boldStatusMarkers = (blockLines, from, { list = TERMINAL_MARKERS, gaps, ..
 
 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.
+// classifyRow(blockLines) -> { klass, evidence }. The order of the arms IS the rule: a
+// contradiction is judged before the state it contradicts, and `live` is what survives when nothing
+// else decided. A RECORD is a state like any other and is reduced with the rest: returning it early
+// made `QUEUED 2026-09-04 — TALLY 2026-09-04 — A-ROW` a deletable `record` while the row said it was
+// open, and hid a `DONE …` beside a `TALLY …` behind a single verdict.
 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}` };
+  const records = String(title)
+    .split(SEGMENT_SPLIT)
+    .flatMap((segment, index) => leadMarkers(segment, RECORD_PREFIXES, { requireDate: index !== 0 })
+      .map((prefix) => ({ prefix, index, tick: segment.trimStart().startsWith('✅') })));
+  const [record] = records;
 
   // 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
@@ -250,8 +306,20 @@ export const classifyRow = (blockLines, gaps) => {
   // 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 bodyTerminalAt = boldStatusMarkers(blockLines, endLine, { gaps });
+  // Narrowing the live reading to a status POSITION may never move a row INTO a deletable class.
+  // The narrow reading is what lets `Rows still pending a rename — A-ROW — PARKED 2026-09-04` be
+  // parked instead of ambiguous; applied to the same name beside a dated `DONE`, it deleted the
+  // contradiction and handed the row to a purge. So wherever the row already declares a TERMINAL or
+  // a RECORD state, the wide reading — a live word anywhere in the title, in any case — is added
+  // back: there it can only ever ADD ambiguity, and this grammar errs toward keeping a row.
+  const deletable = Boolean(titleTerminal.length || record || bodyTerminalAt);
+  const titleLive = [...new Set([
+    ...statusMarkersIn(title, LIVE_MARKERS, { anyCase: true, requireDate: false }),
+    ...datedMarkersIn(title, LIVE_MARKERS, { anyCase: true }),
+    ...(deletable ? markersIn(title, LIVE_MARKERS, { anyCase: true }) : []),
+  ])];
+  const bodyTerminal = bodyTerminalAt;
   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 —
@@ -264,8 +332,18 @@ export const classifyRow = (blockLines, gaps) => {
   // `✅ 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.
+  // A tick OPENING the record's own segment is consumed by that status exactly as a terminal status
+  // consumes its own: without this, `A-ROW — ✅ TALLY 2026-09-04` took the mention arm and became
+  // `ambiguous`, dropping the record refusal the row had always earned. It consumes THAT tick and no
+  // other, counted rather than assumed: suppressing every tick in the title made
+  // `✅ Plan 3 / 3 — a readable name — ✅ TALLY 2026-09-04` a DELETABLE record while one of its two
+  // done markers had nothing to do with the counter. Counting the ticks EVERY record segment
+  // consumes is what keeps `✅ TALLY 2026-09-04 — ✅ SEQUENCING 2026-09-04` the record it is.
+  const ticks = (String(title).match(/✅/gu) ?? []).length;
+  const consumed = records.filter((sighting) => sighting.tick).length;
   const mentioned = markersIn(title, [...TERMINAL_MARKERS, ...FROZEN_MARKERS]).filter(
-    (marker) => !titleTerminal.includes(marker) && !titleFrozen.includes(marker),
+    (marker) => !titleTerminal.includes(marker) && !titleFrozen.includes(marker)
+      && !(marker === '✅' && consumed > 0 && ticks <= consumed),
   );
   if (!titleTerminal.length && !titleFrozen.length && mentioned.length) {
     return { klass: 'ambiguous', evidence: `title mentions ${mentioned.join(', ')} outside a status position` };
@@ -276,6 +354,10 @@ export const classifyRow = (blockLines, gaps) => {
   // 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 = [
+    record && {
+      klass: 'record',
+      evidence: `${record.index === 0 ? 'title' : `title segment ${record.index + 1}`} opens with ${record.prefix}`,
+    },
     titleTerminal.length && { klass: 'terminal', evidence: `title: ${titleTerminal.join(', ')}` },
     titleFrozen.length && { klass: 'parked', evidence: `title: ${titleFrozen.join(', ')}` },
     titleLive.length && { klass: 'live', evidence: `title: ${titleLive.join(', ')}` },
@@ -306,5 +388,3 @@ export const classifyRow = (blockLines, gaps) => {
 
   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

@@ -8,7 +8,7 @@
 // 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
+// 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.
@@ -37,10 +37,12 @@
 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';
+import { nameFindings } from './queue-row-name.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';
+export { CLASSES, DEFAULTS, TERMINAL_MARKERS, FROZEN_MARKERS, LIVE_MARKERS, RECORD_PREFIXES, classifyRow, leadMarkers, titleOf } from './queue-audit-rows.mjs';
+export { nameOf, nameFindings } from './queue-row-name.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
@@ -52,7 +54,7 @@ export { CLASSES, DEFAULTS, TERMINAL_MARKERS, FROZEN_MARKERS, LIVE_MARKERS, RECO
 // 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) =>
+export const canonicalHeading = (text) =>
   String(text ?? '')
     .replace(/\r/g, '')
     .replace(/\s+#+\s*$/, '')
@@ -77,10 +79,34 @@ const sectionWindow = (headings, lines, section, frontLines = 0) => {
 };
 
 // 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.
+// (frontmatter included), the title as written, its class and the literal evidence for that class —
+// and beside them the fields a RENDERER reads: the row's plain `name`, the `id` the one parse cut
+// at, the `nameFindings` that name is judged by, and the line-numbered heading `buckets` it sits
+// under. They are computed here, once, so no consumer becomes a second grammar over this document.
 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);
+  // ONE heading set answers BOTH questions this module asks of a heading — where a `--section` ends,
+  // and which bucket a row sits in — so the rows of the whole document are scanned FIRST and a
+  // heading a row SWALLOWS is refused. The tokenizer reads a 1-3-space indented ATX line as a
+  // heading (deliberately: a consumer's unit grammar is refused rather than guessed at) while the
+  // bullet scan reads the same line as a row CONTINUATION, and DECIDING between them silently was
+  // tried twice and was wrong twice: read raw, a `  ## Details` in a row's body ended the section
+  // early and every row after it went unjudged, and a `  ### Details` became an ancestor bucket of
+  // every following row; dropped, a `## Heading` one space under a `- ` row — where the document
+  // ends the list item and this scan does not — let the section run past a real heading into the
+  // next one. The column that would tell them apart is not knowable here either: a TAB after the
+  // bullet puts the row's body at a tab stop this hand-written reader does not compute.
+  // So the arithmetic is gone and the disposition is the one this file already gives an unread list
+  // item: a token this document reads two ways is corrected by hand. The corpus writes none — zero
+  // indented ATX headings in the 850 KB queue and in every plan and reference doc — and the
+  // correction is one keystroke in either direction, which the refusal names.
+  const documentBlocks = bulletBlocks(lines, fencedLines, 0, lines.length, { fenceContinues: true });
+  const insideARow = (index) => documentBlocks.some((block) => index > block.start && index < block.start + block.span);
+  const documentHeadings = headings.filter(({ index }) => {
+    if (!insideARow(index)) return true;
+    throw fail(2, `line ${frontLines + index + 1} is a heading this document and its row scan read differently ("${lines[index].trim().slice(0, 40)}") — the row above swallows it as body while the document opens a section there, and judging around it would report a domain that was never looked at. Indent it past three spaces to make it body, or to column 0 to make it a heading.`);
+  });
+  const { from, to } = sectionWindow(documentHeadings, 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.
@@ -92,14 +118,28 @@ export const auditQueue = (text, { section = null, label = 'the queue' } = {}) =
     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 blocks = bulletBlocks(lines, fencedLines, from, to, { fenceContinues: true });
+  const bucketsByStart = new Map();
+  const positionedHeadings = documentHeadings.map(({ index, level, text: headingText }) => ({
+    index, level, text: headingText, line: frontLines + index + 1,
+  }));
+  const events = [
+    ...positionedHeadings.map((heading) => ({ kind: 'heading', index: heading.index, heading })),
+    ...blocks.map((block) => ({ kind: 'row', index: block.start, block })),
+  ].sort((left, right) => left.index - right.index);
+  events.reduce((stack, event) => {
+    if (event.kind === 'heading') return [...stack.filter(({ level }) => level < event.heading.level), event.heading];
+    bucketsByStart.set(event.block.start, stack.map(({ level, text: headingText, line }) => ({ level, text: headingText, line })));
+    return stack;
+  }, []);
+  const rows = blocks.map((block) => {
     const { klass, evidence } = classifyRow(block.lines, block.gaps);
+    const { text: title, name, id } = titleOf(block.lines, block.gaps);
     return {
-      line: frontLines + block.start + 1,
-      lines: block.span,
-      title: titleOf(block.lines, block.gaps).text,
-      klass,
-      evidence,
+      title, name, id,
+      nameFindings: CARRY_WORK.has(klass) ? nameFindings(name, id) : [],
+      klass, line: frontLines + block.start + 1, lines: block.span,
+      buckets: bucketsByStart.get(block.start), evidence,
     };
   });
   const counts = Object.fromEntries(CLASSES.map((klass) => [klass, rows.filter((row) => row.klass === klass).length]));
@@ -109,7 +149,9 @@ export const auditQueue = (text, { section = null, label = 'the queue' } = {}) =
 // 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.
+// who did not already know the answer. A NAME finding is the same shape with an opt-in: a note by
+// default, so a gate line written before this contract keeps its verdict byte for byte, and a
+// problem under `requireNames`, which a project adds once its rows are named.
 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 });
@@ -129,6 +171,10 @@ export const checkQueue = (text, options = {}) => {
     if (row.klass === 'parked') {
       notes.push(`${label}:${row.line}: parked (${row.evidence}) — frozen, not dead: ${row.title.slice(0, 80)}`);
     }
+    const nameResults = options.requireNames ? problems : notes;
+    for (const finding of row.nameFindings) {
+      nameResults.push(`${label}:${row.line}: name ${JSON.stringify(row.name)} (${finding.cause}) — ${finding.message}`);
+    }
     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 ` +