@sabaiway/agent-workflow-kit 12.2.0 → 12.4.0

package/CHANGELOG.md

@@ -4,6 +4,101 @@ 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.
 
+## 12.4.0 — the epic tier gets its checker: `epic-shape` judges a capped concept file by one altitude predicate and one claim relation, renders its review brief, folds the findings by the same predicate, and closes it by rewriting one byte range (AD-138)
+
+**MINOR: one new tool, four verbs, four shipped modules; no deployed gate line changes its verdict.** The epic this
+family works under was settled after a six-round design consult whose brief had no altitude bar, and the file drifted
+within a day — a backticked hash in a state field, ground named in prose, an id paragraph above the first section. A
+prose bar has been measured failing under load here, so the rung is a tool. The contract is
+`docs/ai/specs/kit/epic-shape/` (index + `ledger.md` + `brief.md`, live, revision 1, S1–S16 bound).
+
+- **`tools/epic-shape-cli.mjs --check <epic>`** reads `docs/ai/epics/<ID>.md` through the no-follow door — the id is
+  the file stem — and refuses on: a frontmatter key set other than the substrate six plus `state: open | landed`,
+  `maxLines` other than 60, a file over 60 lines, a title other than `# Epic: <title>`, any heading outside the seven
+  sections in their order (Intent, Value, Non-goals, Acceptance, Specs, Stories ledger, Queue), a non-blank line
+  above Intent, a `## Queue` line outside `Row <ID> in <bucket>`, a second or non-date `Result line:`, a
+  `docs/plans/<name>.md` token other than the queue, and — the ALTITUDE BAR, one predicate over every body line
+  outside the two claim fields — a code fence line, a backtick span or a path-with-line citation (`something.ext:123`,
+  `dir/file:123`, backticked or bare); a mechanism written as plain prose passes, a stated residual, no word list.
+  The story ledger is six ` | ` fields per row (`S<N>`, name, `depends-on:`, `owns:`, `shared:`, `state:`), ids
+  contiguous from S1, at most 200 bytes counted OUTSIDE `owns:` and `shared:`; a claim is a repo-relative path in one
+  canonical spelling (a closed byte set — no whitespace, backtick, parenthesis, wildcard, pipe, colon or hash — no
+  `.`/`..` segment, no leading slash, an optional trailing slash as a directory prefix), never a file the checker
+  opens; a co-located test path (`foo.test.mjs`, `foo.test/`) is covered by `foo.mjs`. ONE claim relation between
+  distinct not-landed stories identified by (epic path, id): overlap is equality or a slash-boundary prefix;
+  owns × owns refuses inside and across epics; a pair with a shared side needs a transitive `depends-on` edge inside
+  one epic and is REPORTED (exit 0) across epics; the graph is closed and acyclic, a cycle named by its stories. The
+  sibling sweep reads the DIRECT entries of the store into an entry list — a symlinked or unreadable `.md` refuses
+  naming it, a `type: epic` file with a state outside `open | landed` refuses, an OPEN sibling is judged whole by
+  the same shape check and a refusal names the file (unknown never reads as "owns nothing"), a LANDED sibling is
+  its header only and contributes no story and no finding whatever its body holds, another type or a subdirectory
+  is skipped and counted — and prints `epic-shape: sweep <root>: epics read <n>; entries skipped <n>`, the handed
+  epic counted among the read.
+- **`--review-brief <epic>`** prints, for an epic `--check` accepts and for no other file, a deterministic brief: the
+  id and state, the guard verbatim ("Judge intent, value, boundaries, ownership and story order. A finding that names
+  a mechanism, a file line or an implementation choice is below this tier's altitude and is NOT counted."), the
+  seven sections, five questions one per line. The same render serves a design consult over a draft.
+- **`--fold <findings-file>`** reads entries by its own reader (column-0 `-`, `*`, `<n>.` with indented and blank
+  continuation), excises each entry's first citation (with its backticks only when the span is exactly the token),
+  judges the remainder by the same predicate and prints three named lists with counts — kept, discarded with a
+  reason each, lines outside entries; a zero-entry file refuses.
+- **`--close <epic>`** runs the check, then four conditions — every story `landed <date>`, a result-line date, the
+  header not already landed, the queue row not standing by parsed id or whole-token display title over
+  `queue-audit`'s parser of `<root>/docs/plans/queue.md` read whole (absent or unparseable refuses) — and on accept
+  rewrites ONLY the header `state` bytes through the one descriptor it read; a second hard link refuses without a
+  write; an epic outside a `docs/ai/epics/` store refuses.
+- **Grammar and exits.** `--help` alone, or exactly one verb and exactly one positional; a positional opening with
+  `-`, a second verb, a repeated positional and an empty invocation are usage. Exit 0 accept · 1 refuse · 2 usage.
+  Findings render as `epic-shape: <path>:<line>: <code>: <message>`. Nothing reads git.
+- **Modules and suites.** `tools/epic-shape.mjs` (232 lines — `EPIC_SECTIONS`, `parseEpic`, `parseStoryRow`,
+  `judgeAltitude`, `checkEpic`), `tools/epic-shape-ledger.mjs` (180 — `checkClaims`, `sweepSiblings`, `judgeClose`),
+  `tools/epic-shape-brief.mjs` (75 — `BRIEF_GUARD`, `renderBrief`, `readEntries`, `foldFindings`),
+  `tools/epic-shape-cli.mjs` (153 — argv and fs only, `main(argv, io)`); four suites under `tools/epic-shape.test/`
+  bind S1–S16 with every changed line covered. The tarball gains the four modules by name (301 files, from 297).
+
+Repo-only: this repo's own epic is rewritten to the contract inside its 60 lines (58) and its `--check` line is a
+declared gate before `coverage-check`; the engine canon gains `## The epic` (engine 5.3.0).
+
+## 12.3.0 — the purge archive is a tool: `queue-purge` snapshots a section's bytes and vouches for what leaves, and `queue-audit` exports the two surfaces it reads (AD-137)
+
+**MINOR: one new tool, two verbs, and the sibling's revision 6; no deployed gate line changes its verdict.** The canon has
+demanded a purge archive since the row grammar was written, as prose kept by hand — eight dated archives sat under
+`docs/ai/history/` tied by no checked fact to the queue they came out of. The rung is now a tool, and the contract is
+`docs/ai/specs/kit/queue-purge/` (live, revision 2, S1–S18 bound).
+
+- **`tools/queue-purge-cli.mjs snapshot <queue> --section <heading> --archive <file>`** writes the section's
+  heading line and range VERBATIM from the file's own bytes — every row, the preamble, the bucket headings — plus one
+  index entry per row (archived line, class, key, the title's first 80 characters) under a header that records the
+  date, the canonical section, the queue path, both byte lengths, the section sha256, the block sha256 (sealing every
+  other header field and the whole body) and the row count. A block is FRAMED by its recorded lengths, never found by
+  scanning backward; the archive grows by appended blocks, whole or not at all; a second snapshot of an unmoved
+  section refuses; a keyless row is archived and marked, with the count on stderr. `--check` reads the archive whole,
+  judges it intact, selects the last block for the section and refuses on exactly six causes — a key defect, not
+  intact, not moved, an addition, an unauthorised absence, a keyless entry — collected, each naming its row or offset.
+  The key of a row is its id and nothing else; a doubled id anywhere in the document refuses both verbs naming both
+  lines. Exit 0 accept · 1 refuse · 2 usage; `--archive` and `--section` are both required, every option and
+  positional at most once, `--help` only whole, an archive that resolves to the queue (path, symlink or hard link)
+  is usage, and the eight hand-written dated archives are foreign grammar (exit 2 naming line 1). Neither verb reads
+  a cap or judges a length or a name; the queue is byte-identical after both. Three modules under the 400-line cap —
+  `queue-purge-archive.mjs` (the grammar, the digests, the append-whole writer), `queue-purge.mjs` (the two verbs
+  over ONE document-wide parse), `queue-purge-cli.mjs` — and four suites under `tools/queue-purge.test/`.
+- **`queue-audit` revision 6 (`docs/ai/specs/kit/queue-audit/`, now a folder: index + `argv.md`).**
+  `authorisesRemoval(klass)` is exported from the row leaf — true for `terminal` and `record` only, false for every
+  other value, an unknown class included — and `checkQueue`'s still-listed refusal reads it, as the purge check does
+  over the class an archive block froze: two callers, one list. `auditQueue(text, { range })` — exclusive with
+  `section` — keeps the rows, counts, total and the unread-item refusal DOCUMENT-WIDE and adds
+  `range: { headingLine, from, to }` in file lines (half-open, an empty section included); a `section` call is
+  byte-identical to before, so a deployed gate line keeps its verdict. Scenarios S21 and S22 bind in
+  `queue-audit.test/check-queue.test.mjs`.
+- **The tarball** gains the three modules by name (297 files, from 294); the suites stay out of it.
+
+Repo-only, the tool's first live run: this repo's `## Pending / backlog` went from 257 rows / 7020 lines to 256 / 1717
+in the order the spec names — 8 doubled ids renamed, 120 keyless rows keyed, 8 ambiguous rows settled with no line
+added or deleted, one snapshot (257 rows, 655095 section bytes, no keyless note), five trim slices by bucket with
+every id byte-identical and one terminal row deleted, `--check` accepting at 256 rows; eight rows this release's own
+review filed after the check took the count to 264, so the gate line reads `--max-rows 264 --max-row-lines 10` under
+a one-sentence title with no ratchet log.
+
 ## 12.2.0 — the bundled agy bridge defaults to Gemini 3.8 Flash (High) (AD-136; antigravity-cli-bridge 5.7.0)
 
 **MINOR: a default moved, nothing was removed.** The kit bundles the agy bridge mirror, so the bridge's pin move rides

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: '12.2.0'
+  version: '12.4.0'
 ---
 
 # agent-workflow-kit

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "12.2.0",
+  "version": "12.4.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/epic-shape-brief.mjs

@@ -0,0 +1,75 @@
+import { checkEpic, judgeAltitude, EPIC_SECTIONS, findCitation } from './epic-shape.mjs';
+import { getLineCount } from './plan-shape.mjs';
+
+export const BRIEF_GUARD = 'Judge intent, value, boundaries, ownership and story order. A finding that names a mechanism, a file line or an implementation choice is below this tier\'s altitude and is NOT counted.';
+const QUESTIONS = Object.freeze([
+  'Intent: Is the intended change clear?',
+  'Value: Is the value worth the work?',
+  'Boundaries: Are the non-goals and acceptance boundaries clear?',
+  'Ownership: Does each story have distinct, declared ownership?',
+  'Story order: Do the dependencies express the required order?',
+]);
+const BRIEF_PREFIX = '# Epic review: ';
+const FIRST_LINE = 1;
+const ENTRY_START = /^(?:[-*]|\d+\.)(?:[ \t]|$)/;
+const INDENTED_LINE = /^[ \t]+\S/;
+const CR_END = /\r$/;
+const CITATION_SPAN = /(?<!`)(`+)(?!`)([\s\S]*?)(?<!`)\1(?!`)/g;
+const SPAN_CONTENT = 2;
+const CITATION_GAP = ' ';
+const ERROR = 'error';
+const makeEntry = (entry) => ({ ...entry, text: entry.lines.join('\n') });
+
+export const renderBrief = (text, path) => {
+  const { findings, epic } = checkEpic(text, path);
+  if (findings.length) return { findings, brief: null };
+  const sections = EPIC_SECTIONS.map((heading) => epic.sections.find((section) => section.heading === heading).text).join('');
+  const separator = sections.endsWith('\n') ? '\n' : '\n\n';
+  return `${BRIEF_PREFIX}${epic.id} (${epic.state})\n\n${BRIEF_GUARD}\n\n${sections}${separator}${QUESTIONS.join('\n')}\n`;
+};
+
+export const readEntries = (text) => {
+  const source = String(text ?? '');
+  const lines = source.split('\n').slice(0, getLineCount(source));
+  const read = lines.reduce((state, raw, index) => {
+    const line = index + FIRST_LINE;
+    if (ENTRY_START.test(raw.replace(CR_END, ''))) {
+      return { ...state, entries: state.current ? [...state.entries, makeEntry(state.current)] : state.entries,
+        current: { line, lines: [raw] } };
+    }
+    if (state.current && (raw.trim() === '' || INDENTED_LINE.test(raw))) {
+      return { ...state, current: { ...state.current, lines: [...state.current.lines, raw] } };
+    }
+    return { current: null, entries: state.current ? [...state.entries, makeEntry(state.current)] : state.entries,
+      outside: raw.trim() === '' ? state.outside : [...state.outside, { line, text: raw }] };
+  }, { entries: [], outside: [], current: null });
+  return { entries: read.current ? [...read.entries, makeEntry(read.current)] : read.entries, outside: read.outside };
+};
+
+const findCitationRange = (text) => {
+  const citation = findCitation(text);
+  if (!citation) return null;
+  const span = [...text.matchAll(CITATION_SPAN)].find((match) => match.index < citation.index && match.index + match[0].length > citation.end);
+  if (!span) return citation;
+  return span[SPAN_CONTENT] === citation.text ? { index: span.index, end: span.index + span[0].length } : null;
+};
+const judgeEntry = (entry) => {
+  const citation = findCitationRange(entry.text);
+  const remainder = citation ? entry.text.slice(0, citation.index) + CITATION_GAP + entry.text.slice(citation.end) : entry.text;
+  const lines = remainder.split('\n').map((line, index) => ({
+    ...judgeAltitude(index === 0 ? line.replace(ENTRY_START, '') : line), reasonLine: entry.line + index,
+  }));
+  const violation = lines.find((line) => line.below) ?? { ...judgeAltitude(remainder), reasonLine: entry.line };
+  return violation.below ? { ...entry, form: violation.form, reasonLine: violation.reasonLine,
+    reason: `${violation.form} is below concept altitude` } : null;
+};
+
+export const foldFindings = (text) => {
+  const { entries, outside } = readEntries(text);
+  const judged = entries.map((entry) => ({ entry, discarded: judgeEntry(entry) }));
+  const kept = judged.filter((item) => !item.discarded).map((item) => item.entry);
+  const discarded = judged.filter((item) => item.discarded).map((item) => item.discarded);
+  const findings = entries.length ? [] : [{ line: FIRST_LINE, code: 'empty-findings', severity: ERROR, message: 'the findings file contains no entries' }];
+  return { ok: findings.length === 0, findings, kept, discarded, outside,
+    counts: { kept: kept.length, discarded: discarded.length, outside: outside.length } };
+};

package/tools/epic-shape-cli.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+import { constants, openSync, closeSync, fstatSync, readdirSync, writeSync, ftruncateSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fail } from '../references/scripts/markdown-blocks.mjs';
+import { isDirectRun } from './direct-run.mjs';
+import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { checkEpic } from './epic-shape.mjs';
+import { checkClaims, sweepSiblings, judgeClose, STORE_PATH, QUEUE_PATH } from './epic-shape-ledger.mjs';
+import { renderBrief, foldFindings } from './epic-shape-brief.mjs';
+
+const EXIT = Object.freeze({ accept: 0, refuse: 1, usage: 2 });
+const CHECK = '--check';
+const BRIEF = '--review-brief';
+const FOLD = '--fold';
+const CLOSE = '--close';
+const VERBS = Object.freeze([CHECK, BRIEF, FOLD, CLOSE]);
+const HELP_FLAG = '--help';
+const HELP_ARITY = 1;
+const VERB_ARITY = 2;
+const FIRST_LINE = 1;
+const MARKDOWN_SUFFIX = '.md';
+const PREFIX = 'epic-shape:';
+const INFO = 'info';
+const STORE_TO_PROJECT = '../../..';
+const LANDED_BYTES = Buffer.from('landed');
+const HELP = `Usage:
+  node epic-shape-cli.mjs --check <epic>
+  node epic-shape-cli.mjs --review-brief <epic>
+  node epic-shape-cli.mjs --fold <findings-file>
+  node epic-shape-cli.mjs --close <epic>
+  node epic-shape-cli.mjs --help
+
+Only --close writes: the epic header state becomes landed.
+Exit codes: 0 accept, 1 refuse, 2 usage.`;
+
+const parseArgv = (argv) => {
+  if (argv.length === HELP_ARITY && argv[0] === HELP_FLAG) return { help: true };
+  const [verb, path] = argv;
+  if (argv.length !== VERB_ARITY || !VERBS.includes(verb) || !path || path.startsWith('-')) {
+    throw fail(EXIT.usage, 'use --help alone, or exactly one verb followed by exactly one path that does not open with a dash');
+  }
+  return { verb, path: resolve(path) };
+};
+const makeFailure = (path, code, message) => Object.assign(fail(EXIT.refuse, message), { path, code });
+const formatFinding = (finding, fallbackPath) => {
+  const path = finding.path ?? fallbackPath;
+  const prefix = `${path}: `;
+  const message = finding.message.startsWith(prefix) ? finding.message.slice(prefix.length) : finding.message;
+  return `${PREFIX} ${path}:${finding.line ?? FIRST_LINE}: ${finding.code}: ${message}`;
+};
+const printFindings = (findings, path, io) => {
+  for (const finding of findings) (finding.severity === INFO ? io.log : io.error)(formatFinding(finding, path));
+};
+const printAccept = (verb, path, log) => log(`${PREFIX} accept ${verb} ${path}`);
+const printSweep = (sweep, log) => log(`${PREFIX} sweep ${sweep.root}: epics read ${sweep.counts.epicsRead + FIRST_LINE}; entries skipped ${sweep.counts.skipped}`);
+const describeRead = (result) => result.code ?? result.className ?? result.outcome;
+const openWritable = (path, flags) => openSync(path, flags | constants.O_RDWR);
+const readInput = (path, read, writable) => {
+  const result = read(path, writable ? { keepFd: true, open: openWritable } : {});
+  if (result.outcome !== 'ok') throw makeFailure(path, 'read', describeRead(result));
+  return result;
+};
+const readDirectory = (root, read) => readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)).map((entry) => {
+  const name = entry.name;
+  if (entry.isDirectory()) return { name, outcome: 'directory' };
+  if (!name.endsWith(MARKDOWN_SUFFIX)) return { name, text: '' };
+  const result = read(join(root, name));
+  if (result.outcome === 'ok') return { name, text: result.content };
+  if (result.outcome === 'foreign') return { name, outcome: 'non-regular', kind: result.className };
+  return { name, outcome: 'unreadable', reason: describeRead(result) };
+});
+const readQueue = (path, read) => {
+  if (!STORE_PATH.test(path)) return { outcome: 'unreadable', reason: 'epic is outside a project store' };
+  const queuePath = resolve(dirname(path), STORE_TO_PROJECT, QUEUE_PATH);
+  const result = read(queuePath);
+  return result.outcome === 'ok' ? result.content : { outcome: result.outcome, reason: describeRead(result) };
+};
+
+const writeAll = (fd, bytes, position, path, offset = 0) => {
+  if (offset === bytes.length) return;
+  const written = writeSync(fd, bytes, offset, bytes.length - offset, position + offset);
+  if (written <= 0) throw makeFailure(path, 'write', 'the descriptor write made no progress');
+  writeAll(fd, bytes, position, path, offset + written);
+};
+const writeState = (input, range, path) => {
+  const stats = fstatSync(input.fd);
+  if (stats.nlink !== FIRST_LINE) throw makeFailure(path, 'hardlink', 'close refuses a file with a second hard link');
+  if (!stats.isFile() || stats.dev !== input.dev || stats.ino !== input.ino || stats.size !== input.bytes.length) throw makeFailure(path, 'changed-file', 'the held file changed after the check');
+  const suffix = Buffer.concat([LANDED_BYTES, input.bytes.subarray(range.end)]);
+  writeAll(input.fd, suffix, range.start, path);
+  ftruncateSync(input.fd, range.start + suffix.length);
+};
+const runFold = (input, path, io) => {
+  const result = foldFindings(input.content);
+  io.log(`${PREFIX} kept (${result.counts.kept})`);
+  for (const entry of result.kept) io.log(`${entry.line}: ${entry.text}`);
+  io.log(`${PREFIX} discarded (${result.counts.discarded})`);
+  for (const entry of result.discarded) io.log(`${entry.line}: ${entry.reason} (line ${entry.reasonLine})\n${entry.text}`);
+  io.log(`${PREFIX} outside (${result.counts.outside})`);
+  for (const line of result.outside) io.log(`${line.line}: ${line.text}`);
+  printFindings(result.findings, path, io);
+  if (!result.ok) return EXIT.refuse;
+  printAccept(FOLD, path, io.log);
+  return EXIT.accept;
+};
+const runEpic = (verb, input, path, io) => {
+  const entries = readDirectory(dirname(path), io.read).filter((entry) => entry.name !== basename(path));
+  const shape = checkEpic(input.content, path);
+  const sweep = sweepSiblings(entries, dirname(path));
+  const claims = shape.findings.length === 0 && sweep.ok
+    ? checkClaims([shape.epic, ...sweep.epics]) : { findings: [] };
+  const findings = [...shape.findings, ...sweep.findings, ...claims.findings];
+  const output = verb === BRIEF ? { ...io, log: io.error } : io;
+  printSweep(sweep, output.log);
+  if (findings.some((finding) => finding.severity !== INFO)) {
+    printFindings(findings, path, output);
+    return EXIT.refuse;
+  }
+  if (verb === CLOSE) {
+    const closed = judgeClose({ epic: input.content, path, queue: readQueue(path, io.read), entries });
+    printFindings(closed.findings, path, io);
+    if (!closed.ok) return EXIT.refuse;
+    writeState(input, closed.stateRange, path);
+  } else {
+    printFindings(findings, path, output);
+    if (verb === BRIEF) {
+      const brief = renderBrief(input.content, path);
+      if (typeof brief !== 'string') { printFindings(brief.findings, path, output); return EXIT.refuse; }
+      io.log(brief.slice(0, -FIRST_LINE));
+    }
+  }
+  printAccept(verb, path, output.log);
+  return EXIT.accept;
+};
+
+export const main = (argv, { log = console.log, error = console.error, read = readRegularFileNoFollow } = {}) => {
+  try {
+    const options = parseArgv(argv);
+    if (options.help) { log(HELP); return EXIT.accept; }
+    const input = readInput(options.path, read, options.verb === CLOSE);
+    try {
+      const io = { log, error, read };
+      return options.verb === FOLD ? runFold(input, options.path, io) : runEpic(options.verb, input, options.path, io);
+    } finally {
+      if (input.fd !== undefined) closeSync(input.fd);
+    }
+  } catch (failure) {
+    error(formatFinding({ path: failure.path, line: FIRST_LINE, code: failure.code ?? 'usage', message: failure.message }, argv[1] ?? 'invocation'));
+    return failure.exitCode === EXIT.usage ? EXIT.usage : EXIT.refuse;
+  }
+};
+
+if (isDirectRun(import.meta.url)) process.exitCode = main(process.argv.slice(VERB_ARITY));

package/tools/epic-shape-ledger.mjs

@@ -0,0 +1,180 @@
+import { posix } from 'node:path';
+import { tokenizeMarkdown } from '../references/scripts/markdown-blocks.mjs';
+import { parseHeader, checkEpic } from './epic-shape.mjs';
+import { auditQueue } from './queue-audit.mjs';
+import { unique } from './plan-shape.mjs';
+
+const FIRST_LINE = 1;
+const ERROR = 'error';
+const INFO = 'info';
+const OPEN = 'open';
+const LANDED = 'landed';
+const EPIC = 'epic';
+const OWN = 'owns';
+const CLAIM_FIELDS = Object.freeze([OWN, 'shared']);
+const FRONT_DELIMITER = '---';
+const CR_END = /\r$/;
+const MARKDOWN_SUFFIX = '.md';
+const TRAILING_SLASH = /\/$/;
+const SOURCE_EXTENSION = /^(.*[^/])(\.[^./]+)$/;
+const TEST_FILE = /\.test\.[^/]+$/;
+const TEST_SUFFIX = '.test';
+export const STORE_PATH = /^(?:(.*)\/)?docs\/ai\/epics\/([^/]+)\.md$/;
+export const QUEUE_PATH = 'docs/plans/queue.md';
+const TOKEN_EDGE = '[\\p{L}\\p{N}_-]';
+const REGEX_BYTES = /[.*+?^${}()|[\]\\]/g;
+const PARSE_REFUSALS = Object.freeze([1, 2]);
+const makeFinding = (path, line, code, message, severity = ERROR) => ({ path, line, code, message: `${path}: ${message}`, severity });
+const finishJudgement = (findings, data = {}) => ({ ...data, ok: !findings.some((finding) => finding.severity === ERROR), findings });
+const nameFindings = (findings, path) => findings.map((finding) => makeFinding(path, finding.line, finding.code, finding.message));
+const getIdentity = (story) => JSON.stringify([story.path, story.id]);
+
+const findReachable = (graph, pending, visited = new Set()) => {
+  const unseen = unique(pending.filter((id) => !visited.has(id)));
+  if (unseen.length === 0) return visited;
+  return findReachable(graph, unseen.flatMap((id) => graph.get(id) ?? []), new Set([...visited, ...unseen]));
+};
+const readGraph = (epic, rows) => {
+  const graph = new Map(rows.map((row) => [row.id, row.dependsOn]));
+  const reachable = new Map(rows.map((row) => [row.id, findReachable(graph, row.dependsOn)]));
+  const unknowns = rows.flatMap((row) => row.dependsOn.filter((id) => !graph.has(id))
+    .map((id) => makeFinding(epic.path, row.line, 'dependency-id', `${row.id} depends on absent story ${id}`)));
+  const cyclic = rows.filter((row) => reachable.get(row.id).has(row.id));
+  const groups = unique(cyclic.map((row) => JSON.stringify(cyclic.filter((other) =>
+    reachable.get(row.id).has(other.id) && reachable.get(other.id).has(row.id)).map((other) => other.id))));
+  const cycles = groups.map((group) => {
+    const ids = JSON.parse(group);
+    return makeFinding(epic.path, rows.find((row) => row.id === ids[0]).line, 'dependency-cycle', `dependency cycle includes ${ids.join(', ')}`);
+  });
+  return { reachable, findings: [...unknowns, ...cycles] };
+};
+
+const expandClaim = (path) => {
+  const source = SOURCE_EXTENSION.exec(path);
+  return source && !TEST_FILE.test(path)
+    ? [path, `${source[1]}${TEST_SUFFIX}${source[2]}`, `${source[1]}${TEST_SUFFIX}/`] : [path];
+};
+const hasPathOverlap = (left, right) => {
+  const a = left.replace(TRAILING_SLASH, '');
+  const b = right.replace(TRAILING_SLASH, '');
+  return a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+};
+const getClaims = (row) => CLAIM_FIELDS.flatMap((field) => row[field].map((path) => ({ field, path, ground: expandClaim(path) })));
+const hasClaimOverlap = (left, right) => left.ground.some((a) => right.ground.some((b) => hasPathOverlap(a, b)));
+const checkPair = (left, right) => {
+  if (getIdentity(left) === getIdentity(right)) return [];
+  const sameEpic = left.path === right.path;
+  const ordered = sameEpic && (left.reachable.has(right.id) || right.reachable.has(left.id));
+  return left.claims.flatMap((a) => right.claims.flatMap((b) => {
+    if (!hasClaimOverlap(a, b)) return [];
+    const owners = a.field === OWN && b.field === OWN;
+    if (!owners && ordered) return [];
+    const code = owners ? 'owns-overlap' : sameEpic ? 'shared-order' : 'shared-cross-epic';
+    const severity = owners || sameEpic ? ERROR : INFO;
+    const message = `${left.id} ${a.field} ${a.path} overlaps ${right.path} ${right.id} ${b.field} ${b.path}`;
+    return [makeFinding(left.path, left.line, code, message, severity)];
+  }));
+};
+
+export const checkClaims = (epics) => {
+  const parsed = epics.map((epic) => {
+    const rows = epic.rows;
+    const graph = readGraph(epic, rows);
+    const findings = rows.filter((row) => !row.valid)
+      .map((row) => makeFinding(epic.path, row.line, 'row-grammar', `${row.id} has invalid story fields or claim tokens`));
+    const stories = epic.state === OPEN ? rows.filter((row) => row.valid && row.state !== LANDED).map((row) => ({
+      path: epic.path, id: row.id, line: row.line, claims: getClaims(row), reachable: graph.reachable.get(row.id),
+    })) : [];
+    return { stories, findings: [...nameFindings(epic.findings, epic.path), ...findings, ...graph.findings] };
+  });
+  const stories = parsed.flatMap((epic) => epic.stories);
+  const collisions = stories.flatMap((left, index) => stories.slice(index + FIRST_LINE).flatMap((right) => checkPair(left, right)));
+  return finishJudgement([...parsed.flatMap((epic) => epic.findings), ...collisions]);
+};
+
+const readSiblingHeader = (text, path) => {
+  const lines = text.split('\n');
+  if (lines[0].replace(CR_END, '') !== FRONT_DELIMITER) return { fields: null, findings: [] };
+  const end = lines.findIndex((line, index) => index > 0 && line.replace(CR_END, '') === FRONT_DELIMITER);
+  if (end < 0) return { fields: null, findings: [makeFinding(path, FIRST_LINE, 'sibling-header', 'frontmatter opens but never closes')] };
+  try {
+    const frontmatter = tokenizeMarkdown(`${lines.slice(0, end + FIRST_LINE).join('\n')}\n`, path).frontmatter;
+    const { fields } = parseHeader(frontmatter);
+    const valid = Object.keys(fields).length === end - FIRST_LINE;
+    return valid ? { fields, findings: [] }
+      : { fields: null, findings: [makeFinding(path, FIRST_LINE, 'sibling-header', 'frontmatter contains an unreadable or repeated field')] };
+  } catch (error) {
+    if (!PARSE_REFUSALS.includes(error.exitCode)) throw error;
+    return { fields: null, findings: [makeFinding(path, FIRST_LINE, 'sibling-header', error.message)] };
+  }
+};
+const readSibling = (entry, root) => {
+  const skipped = { read: 0, skipped: FIRST_LINE, epics: [], findings: [] };
+  if (entry.outcome === 'directory' || entry.kind === 'directory') return skipped;
+  if (!entry.name.endsWith(MARKDOWN_SUFFIX)) return skipped;
+  const path = posix.join(root, entry.name);
+  if (typeof entry.text !== 'string' || entry.outcome) {
+    return { read: 0, skipped: 0, epics: [], findings: [makeFinding(path, FIRST_LINE, 'sibling-read', `${entry.outcome ?? 'unreadable'}: ${entry.reason ?? entry.kind ?? 'no readable text'}`)] };
+  }
+  const header = readSiblingHeader(entry.text, path);
+  if (header.findings.length) return { read: 0, skipped: 0, epics: [], findings: header.findings };
+  if (header.fields?.type !== EPIC) return skipped;
+  if (![OPEN, LANDED].includes(header.fields.state)) {
+    return { read: 0, skipped: 0, epics: [], findings: [makeFinding(path, FIRST_LINE, 'sibling-state', 'epic state is missing or outside open and landed')] };
+  }
+  if (header.fields.state === LANDED) return { read: FIRST_LINE, skipped: 0, epics: [], findings: [] };
+  const { epic, findings } = checkEpic(entry.text, path);
+  return { read: FIRST_LINE, skipped: 0, epics: findings.length ? [] : [epic], findings: nameFindings(findings, path) };
+};
+
+export const sweepSiblings = (entries, root) => {
+  if (!Array.isArray(entries)) {
+    return finishJudgement([makeFinding(root, FIRST_LINE, 'sibling-read', 'the direct entry list is unreadable')], { root, epics: [], counts: { epicsRead: 0, skipped: 0 } });
+  }
+  const results = entries.map((entry) => readSibling(entry, root));
+  const epics = results.flatMap((result) => result.epics);
+  return finishJudgement(results.flatMap((result) => result.findings), {
+    root, epics, counts: { epicsRead: results.reduce((sum, result) => sum + result.read, 0), skipped: results.reduce((sum, result) => sum + result.skipped, 0) },
+  });
+};
+
+const carriesToken = (title, id) => {
+  const escaped = id.replace(REGEX_BYTES, '\\$&');
+  return new RegExp(`(?<!${TOKEN_EDGE})${escaped}(?!${TOKEN_EDGE})`, 'u').test(title);
+};
+const checkQueueAbsence = (queue, path, id) => {
+  if (typeof queue !== 'string') {
+    return [makeFinding(path, FIRST_LINE, 'queue-read', `${queue?.outcome ?? 'absent'}: ${queue?.reason ?? 'no readable queue text'}`)];
+  }
+  try {
+    const { rows } = auditQueue(queue, { label: path });
+    return rows.filter((row) => row.id === id || carriesToken(row.title, id))
+      .map((row) => makeFinding(path, row.line, 'close-queue', `queue row still stands for ${id}: ${row.title}`));
+  } catch (error) {
+    if (!PARSE_REFUSALS.includes(error.exitCode)) throw error;
+    return [makeFinding(path, FIRST_LINE, 'queue-read', error.message)];
+  }
+};
+
+export const judgeClose = ({ epic: text, path, queue, entries }) => {
+  const checked = checkEpic(text, path);
+  const epic = checked.epic;
+  const base = { epic, stateRange: null };
+  if (checked.findings.length) return finishJudgement(nameFindings(checked.findings, path), base);
+  const store = STORE_PATH.exec(path);
+  if (!store) return finishJudgement([makeFinding(path, FIRST_LINE, 'close-path', 'close requires docs/ai/epics/<ID>.md in a project store')], base);
+  const root = store[1] === undefined ? '.' : store[1] || '/';
+  const queuePath = posix.join(root, QUEUE_PATH);
+  const sweep = sweepSiblings(entries, posix.dirname(path));
+  const claims = checkClaims([epic, ...sweep.epics.filter((sibling) => sibling.path !== posix.normalize(path))]);
+  const checks = [...sweep.findings, ...claims.findings];
+  const data = { ...base, root, queuePath, sweep };
+  if (!sweep.ok || !claims.ok) return finishJudgement(checks, data);
+  const stories = epic.rows.filter((row) => row.state !== LANDED)
+    .map((row) => makeFinding(path, row.line, 'close-stories', `${row.id} has not landed with a date`));
+  const result = epic.result ? [] : [makeFinding(path, FIRST_LINE, 'close-result', 'Acceptance has no Result line with a bare date')];
+  const state = epic.state === LANDED ? [makeFinding(path, FIRST_LINE, 'close-state', 'header state is already landed')] : [];
+  const findings = [...checks, ...stories, ...result, ...state, ...checkQueueAbsence(queue, queuePath, epic.id)];
+  const judged = finishJudgement(findings, data);
+  return { ...judged, stateRange: judged.ok ? epic.stateRange : null };
+};

package/tools/epic-shape.mjs

@@ -0,0 +1,232 @@
+import { tokenizeMarkdown } from '../references/scripts/markdown-blocks.mjs';
+import { bulletBlocks, getLineCount, unique } from './plan-shape.mjs';
+
+export const EPIC_SECTIONS = Object.freeze([
+  '## Intent', '## Value', '## Non-goals', '## Acceptance', '## Specs', '## Stories ledger', '## Queue',
+]);
+const [INTENT, , , ACCEPTANCE, , LEDGER, QUEUE] = EPIC_SECTIONS;
+const HEADER_KEYS = Object.freeze(['type', 'lastUpdated', 'scope', 'staleAfter', 'owner', 'maxLines', 'state']);
+const HEADER_STATES = Object.freeze(['open', 'landed']);
+const STORY_STATES = Object.freeze(['planned', 'in-flight']);
+const MAX_LINES = 60;
+const MAX_ROW_BYTES = 200;
+const FIELD_COUNT = 6;
+const FIRST_LINE = 1;
+const HEADER_TAIL_LINES = 2;
+const MARKDOWN_REFUSAL = 1;
+const FIELD_SEPARATOR = ' | ';
+const NONE = 'none';
+const EPIC_TYPE = 'epic';
+const TITLE_PREFIX = '# Epic: ';
+const RESULT_PREFIX = 'Result line:';
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+const DATE_TIME_SUFFIX = 'T00:00:00.000Z';
+const STORY_ID = /^S[1-9]\d*$/;
+const DEPENDENCIES = /^depends-on: (none|S[1-9]\d*(?:, S[1-9]\d*)*)$/;
+const CLAIM_FIELD = /^(owns|shared): (.+)$/;
+const CLAIM_FORBIDDEN = /[\s`()\*?\[\]{}|:#]/;
+const STATE_FIELD = /^state: (planned|in-flight|landed (\d{4}-\d{2}-\d{2}))$/;
+const HEADER_FIELD = /^([A-Za-z][A-Za-z0-9]*):([ \t]*)(.*?)[ \t]*\r?$/;
+const QUEUE_LINE = /^Row (\S+) in (\S(?:.*\S)?)$/;
+const RESULT_LINE = /^Result line: (\d{4}-\d{2}-\d{2})$/;
+const PLAN_PATH = /docs\/plans\/([^\s`()[\]{}<>|,:;"']+\.md)(?=$|[\s`()[\]{}<>|,:;"'.!?])/g;
+const QUEUE_NAME = 'queue.md';
+const FENCE_LINE = /^\s*(?:`{3,}[^`]*|~{3,}.*)$/;
+const BACKTICK_RUN = /`+/g;
+const CITATION = /[^\s`()[\]{}<>|:;,"'!?]+[./][^\s`()[\]{}<>|:;,"'!?]+:\d+(?![\dA-Za-z_])/;
+const TOP_BULLET = /^-\s+\S/;
+const BULLET_PREFIX = /^-\s+/;
+const INDENTED_LINE = /^\s+\S/;
+const MARKDOWN_ERROR_LINE = /:(\d+):/;
+const makeFinding = (line, code, message) => ({ line, code, message });
+const getFileLine = (document, index) => document.frontLines + index + FIRST_LINE;
+const getSection = (epic, heading) => epic.sections.find((section) => section.heading === heading);
+const getNonBlank = (entries) => entries.filter((entry) => entry.raw.trim() !== '');
+const getEntries = (document, start, end) => document.lines.slice(start, end).map((raw, offset) => ({
+  raw, index: start + offset, line: getFileLine(document, start + offset),
+}));
+export const isEpicDate = (value) => {
+  if (!DATE_PATTERN.test(value)) return false;
+  const date = new Date(`${value}${DATE_TIME_SUFFIX}`);
+  return Number.isFinite(date.getTime()) && date.toISOString() === `${value}${DATE_TIME_SUFFIX}`;
+};
+
+export const findCitation = (line) => {
+  const match = CITATION.exec(line);
+  return match ? { text: match[0], index: match.index, end: match.index + match[0].length } : null;
+};
+
+const hasBacktickSpan = (line) => {
+  const runs = [...line.matchAll(BACKTICK_RUN)];
+  return runs.some((opening, index) => runs.slice(index + FIRST_LINE).some((closing) => closing[0].length === opening[0].length));
+};
+
+export const judgeAltitude = (line) => {
+  const form = FENCE_LINE.test(line) ? 'fence' : hasBacktickSpan(line) ? 'backtick' : findCitation(line) ? 'citation' : null;
+  return { below: form !== null, form };
+};
+
+const isClaim = (token) => {
+  if (!token || token === NONE || token.startsWith('/') || CLAIM_FORBIDDEN.test(token)) return false;
+  const segments = token.replace(/\/$/, '').split('/');
+  return segments.every((segment) => segment !== '' && segment !== '.' && segment !== '..');
+};
+const parseClaims = (field, name) => {
+  const match = CLAIM_FIELD.exec(field ?? '');
+  if (!match || match[1] !== name) return null;
+  if (match[2] === NONE) return [];
+  const claims = match[2].split(',').map((claim) => claim.trim());
+  return claims.every(isClaim) ? claims : null;
+};
+
+export const parseStoryRow = (blockLines) => {
+  const lines = blockLines.map((line) => line.replace(/\r$/, ''));
+  const raw = lines[0] ?? '';
+  const parts = raw.replace(BULLET_PREFIX, '').split(FIELD_SEPARATOR).map((part) => part.trim());
+  const [id, name, dependencyField, ownsField, sharedField, stateField] = parts;
+  const dependencies = DEPENDENCIES.exec(dependencyField ?? '');
+  const owns = parseClaims(ownsField, 'owns');
+  const shared = parseClaims(sharedField, 'shared');
+  const stateMatch = STATE_FIELD.exec(stateField ?? '');
+  const date = stateMatch?.[2] ?? null;
+  const state = date ? 'landed' : stateMatch?.[1] ?? null;
+  const bodyLines = lines.slice(FIRST_LINE);
+  const body = bodyLines.join('\n').trimEnd();
+  const outsideClaims = [id, name, dependencyField, stateField].join(FIELD_SEPARATOR);
+  const countedBytes = Buffer.byteLength(outsideClaims + (body ? `\n${body}` : ''), 'utf8');
+  const valid = TOP_BULLET.test(raw) && parts.length === FIELD_COUNT && STORY_ID.test(id ?? '') && Boolean(name)
+    && Boolean(dependencies) && owns !== null && shared !== null
+    && (STORY_STATES.includes(state) || (state === 'landed' && isEpicDate(date)))
+    && bodyLines.every((line) => line.trim() === '' || INDENTED_LINE.test(line));
+  return {
+    raw, id: id ?? null, name: name ?? null, valid, countedBytes, body, bodyLines,
+    dependsOn: dependencies ? (dependencies[1] === NONE ? [] : unique(dependencies[1].split(', '))) : [],
+    owns: owns ?? [], shared: shared ?? [], state, date,
+    altitudeLine: parts.length === FIELD_COUNT ? outsideClaims : raw,
+  };
+};
+
+export const parseHeader = (frontmatter) => {
+  const lines = frontmatter.split('\n');
+  const entries = lines.slice(FIRST_LINE, -HEADER_TAIL_LINES).map((raw, index) => {
+    const match = HEADER_FIELD.exec(raw);
+    const prefix = lines.slice(0, index + FIRST_LINE).join('\n') + '\n';
+    const start = match ? Buffer.byteLength(prefix + `${match[1]}:${match[2]}`, 'utf8') : null;
+    return { key: match?.[1], value: match?.[3], line: index + FIRST_LINE + FIRST_LINE,
+      range: match ? { start, end: start + Buffer.byteLength(match[3], 'utf8') } : null };
+  });
+  const fields = Object.fromEntries(entries.filter((entry) => entry.key).map((entry) => [entry.key, entry.value]));
+  const findings = entries.flatMap((entry) => !entry.key || !HEADER_KEYS.includes(entry.key) || entry.value === ''
+    ? [makeFinding(entry.line, 'frontmatter', 'frontmatter must contain only the seven non-empty epic fields')] : []);
+  for (const key of HEADER_KEYS) {
+    if (entries.filter((entry) => entry.key === key).length !== FIRST_LINE) {
+      findings.push(makeFinding(FIRST_LINE, 'frontmatter', `frontmatter must carry ${key} exactly once`));
+    }
+  }
+  if (fields.type !== EPIC_TYPE) findings.push(makeFinding(FIRST_LINE, 'frontmatter', 'type must be epic'));
+  if (fields.maxLines !== String(MAX_LINES)) findings.push(makeFinding(FIRST_LINE, 'max-lines', `maxLines is frozen at ${MAX_LINES}`));
+  if (!HEADER_STATES.includes(fields.state)) findings.push(makeFinding(FIRST_LINE, 'header-state', 'header state must be open or landed'));
+  const states = entries.filter((entry) => entry.key === 'state');
+  return { fields, stateRange: states.length === FIRST_LINE ? states[0].range : null, findings };
+};
+
+const parseSections = (document, titleHeading) => document.headings.filter((heading) => heading !== titleHeading).map((heading, index, headings) => {
+  const end = headings[index + FIRST_LINE]?.index ?? document.lines.length;
+  const lines = document.lines.slice(heading.index + FIRST_LINE, end);
+  const raw = document.lines.slice(heading.index, end).join('\n');
+  return { heading: heading.text, index: heading.index, line: getFileLine(document, heading.index), end, lines,
+    text: raw + (end < document.lines.length ? '\n' : ''), entries: getEntries(document, heading.index + FIRST_LINE, end) };
+});
+
+export const parseEpic = (text, path) => {
+  const source = String(text ?? '');
+  const epicPath = String(path ?? '');
+  const id = epicPath.split('/').at(-1).replace(/\.md$/, '');
+  const base = { text: source, path: epicPath, id, title: null, fields: {}, state: null, stateRange: null,
+    sections: [], rows: [], queue: null, result: null, resultLines: [], ledgerEntries: [], document: null, findings: [] };
+  try {
+    const document = tokenizeMarkdown(source, epicPath);
+    const header = parseHeader(document.frontmatter);
+    const titleHeading = document.headings.find((heading) => heading.level === FIRST_LINE && heading.text.startsWith(TITLE_PREFIX));
+    const sections = parseSections(document, titleHeading);
+    const ledger = sections.find((section) => section.heading === LEDGER);
+    const blocks = ledger ? bulletBlocks(document.lines, document.fencedLines, ledger.index + FIRST_LINE, ledger.end) : [];
+    const rows = blocks.map((block) => ({ ...parseStoryRow(block.lines), index: block.start,
+      line: getFileLine(document, block.start), span: block.span }));
+    const queueEntries = getNonBlank(sections.find((section) => section.heading === QUEUE)?.entries ?? []);
+    const queueMatch = queueEntries.length === FIRST_LINE ? QUEUE_LINE.exec(queueEntries[0].raw.trim()) : null;
+    const resultLines = (sections.find((section) => section.heading === ACCEPTANCE)?.entries ?? [])
+      .filter((entry) => entry.raw.trim().startsWith(RESULT_PREFIX));
+    const resultMatch = resultLines.length === FIRST_LINE ? RESULT_LINE.exec(resultLines[0].raw.trim()) : null;
+    return {
+      ...base, ...header, document, titleHeading, title: titleHeading?.text.slice(TITLE_PREFIX.length).trim() ?? null,
+      state: header.fields.state ?? null, sections, rows, ledgerEntries: ledger?.entries ?? [], resultLines,
+      queue: queueMatch ? { id: queueMatch[1], bucket: queueMatch[2], line: queueEntries[0].line } : null,
+      result: resultMatch && isEpicDate(resultMatch[1]) ? { date: resultMatch[1], line: resultLines[0].line } : null,
+    };
+  } catch (error) {
+    if (error.exitCode !== MARKDOWN_REFUSAL) throw error;
+    return { ...base, findings: [makeFinding(Number(MARKDOWN_ERROR_LINE.exec(error.message)?.[1] ?? FIRST_LINE), 'markdown', error.message)] };
+  }
+};
+
+const checkSections = (epic) => {
+  const { document, titleHeading, sections } = epic;
+  const findings = [];
+  if (!epic.title || document.headings[0] !== titleHeading) {
+    findings.push(makeFinding(titleHeading ? getFileLine(document, titleHeading.index) : FIRST_LINE, 'title', `the first heading must be ${TITLE_PREFIX}<title>`));
+  }
+  if (sections.length !== EPIC_SECTIONS.length || sections.some((section, index) => section.heading !== EPIC_SECTIONS[index])) {
+    findings.push(makeFinding(sections[0]?.line ?? FIRST_LINE, 'headings', 'the seven epic sections must appear exactly once in their literal order, with no other headings'));
+  }
+  const intent = getSection(epic, INTENT);
+  const outside = getEntries(document, 0, intent?.index ?? document.lines.length)
+    .filter((entry) => entry.index !== titleHeading?.index && entry.raw.trim() !== '');
+  for (const entry of outside) findings.push(makeFinding(entry.line, 'outside-section', 'every non-blank body line after the title must lie inside a section'));
+  return findings;
+};
+
+const checkClosedLines = (epic) => {
+  const findings = [];
+  if (!epic.queue || epic.queue.id !== epic.id) {
+    findings.push(makeFinding(getSection(epic, QUEUE)?.line ?? FIRST_LINE, 'queue', `Queue must hold exactly one line: Row ${epic.id} in <bucket>`));
+  }
+  if (epic.resultLines.length > FIRST_LINE || (epic.resultLines.length === FIRST_LINE && !epic.result)) {
+    findings.push(makeFinding(epic.resultLines[0].line, 'result-line', 'Acceptance admits at most one Result line: YYYY-MM-DD with a date and nothing else'));
+  }
+  return findings;
+};
+
+const checkRows = (epic) => {
+  const findings = [];
+  if (epic.rows.length === 0) findings.push(makeFinding(getSection(epic, LEDGER)?.line ?? FIRST_LINE, 'empty-ledger', 'the ledger must carry at least S1'));
+  const covered = new Set(epic.rows.flatMap((row) => Array.from({ length: row.span }, (_, offset) => row.index + offset)));
+  for (const entry of getNonBlank(epic.ledgerEntries)) {
+    if (!covered.has(entry.index)) findings.push(makeFinding(entry.line, 'ledger-line', 'ledger content must belong to a top-level story bullet'));
+  }
+  for (const [index, row] of epic.rows.entries()) {
+    if (!row.valid) findings.push(makeFinding(row.line, 'row-grammar', 'a story must carry the six ordered fields, canonical claims and a valid state'));
+    if (row.id !== `S${index + FIRST_LINE}`) findings.push(makeFinding(row.line, 'story-ids', 'story ids must run contiguously from S1'));
+    if (row.countedBytes > MAX_ROW_BYTES) findings.push(makeFinding(row.line, 'row-bytes', `${row.id} has ${row.countedBytes} bytes outside owns and shared; the cap is ${MAX_ROW_BYTES}`));
+  }
+  return findings;
+};
+
+const checkAltitude = (epic) => {
+  const rowLines = new Map(epic.rows.map((row) => [row.index, row.altitudeLine]));
+  return epic.document.lines.flatMap((line, index) => {
+    const judgement = judgeAltitude(rowLines.get(index) ?? line);
+    return judgement.below ? [makeFinding(getFileLine(epic.document, index), 'altitude', `${judgement.form} is below concept altitude`)] : [];
+  });
+};
+const checkPlanPaths = (text) => text.split('\n').flatMap((line, index) => [...line.matchAll(PLAN_PATH)]
+  .filter((match) => match[1] !== QUEUE_NAME)
+  .map((match) => makeFinding(index + FIRST_LINE, 'plan-path', `${match[0]} is ephemeral; only docs/plans/queue.md may be stored`)));
+
+export const checkEpic = (text, path) => {
+  const epic = parseEpic(text, path);
+  const capFindings = getLineCount(epic.text) > MAX_LINES
+    ? [makeFinding(FIRST_LINE, 'line-cap', `the epic has ${getLineCount(epic.text)} lines; the cap is ${MAX_LINES}`)] : [];
+  const shapeFindings = epic.document ? [...checkSections(epic), ...checkClosedLines(epic), ...checkRows(epic), ...checkAltitude(epic)] : [];
+  return { findings: [...epic.findings, ...capFindings, ...checkPlanPaths(epic.text), ...shapeFindings], epic };
+};

package/tools/queue-audit-rows.mjs

@@ -49,6 +49,7 @@ 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 authorisesRemoval = (klass) => klass === 'terminal' || klass === 'record';
 
 export const DEFAULTS = { maxRows: 60, maxRowLines: 12 };
 

package/tools/queue-audit.mjs

@@ -36,12 +36,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 { CARRY_WORK, CLASSES, DEFAULTS, UNREAD_ITEM, authorisesRemoval, 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, titleOf } from './queue-audit-rows.mjs';
+export { CLASSES, DEFAULTS, TERMINAL_MARKERS, FROZEN_MARKERS, LIVE_MARKERS, RECORD_PREFIXES, authorisesRemoval, 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
@@ -83,7 +83,8 @@ const sectionWindow = (headings, lines, section, frontLines = 0) => {
 // 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' } = {}) => {
+export const auditQueue = (text, { section = null, range = null, label = 'the queue' } = {}) => {
+  if (section !== null && range !== null) throw fail(2, 'section and range are exclusive — name only one.');
   const { lines, headings, fencedLines, frontLines } = tokenizeMarkdown(String(text ?? ''), label);
   // 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
@@ -107,6 +108,7 @@ export const auditQueue = (text, { section = null, label = 'the queue' } = {}) =
     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);
+  const ranged = range === null ? null : sectionWindow(documentHeadings, lines, range, 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.
@@ -143,7 +145,14 @@ export const auditQueue = (text, { section = null, label = 'the queue' } = {}) =
     };
   });
   const counts = Object.fromEntries(CLASSES.map((klass) => [klass, rows.filter((row) => row.klass === klass).length]));
-  return { rows, counts, total: rows.length };
+  return {
+    rows, counts, total: rows.length,
+    ...(ranged === null ? {} : { range: {
+      headingLine: frontLines + ranged.from,
+      from: frontLines + ranged.from + 1,
+      to: frontLines + ranged.to + 1 - Number(ranged.to === lines.length && lines.at(-1) === ''),
+    } }),
+  };
 };
 
 // checkQueue(text, options) -> { ok, problems, notes }. A problem is a REFUSAL and every one of them
@@ -159,7 +168,7 @@ export const checkQueue = (text, options = {}) => {
   const notes = [];
 
   for (const row of rows) {
-    if (row.klass === 'terminal' || row.klass === 'record') {
+    if (authorisesRemoval(row.klass)) {
       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)}`,

package/tools/queue-purge-archive.mjs

@@ -0,0 +1,176 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants, openSync, closeSync, fstatSync, fsyncSync, readFileSync, writeFileSync, writeSync, unlinkSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { canonicalHeading } from './queue-audit.mjs';
+import { fail } from '../references/scripts/markdown-blocks.mjs';
+
+export const EXIT = Object.freeze({ accept: 0, refuse: 1, usage: 2 });
+const MAGIC = 'queue-purge: 1';
+const HEADER_FIELDS = ['date', 'section', 'queue-path', 'section-bytes', 'index-bytes', 'section-sha256', 'block-sha256', 'rows'];
+const BLOCK_DIGEST_FIELD = 'block-sha256';
+const TITLE_WIDTH = 80;
+const KEYLESS = '<keyless>';
+const LF = 0x0a;
+const HASH = 'sha256';
+const HEX_DIGEST = /^[a-f0-9]{64}$/;
+const COUNT = /^(0|[1-9][0-9]*)$/;
+const INDEX_COLUMNS = 4;
+const PRIVATE_MODE = 0o600;
+
+export const hashBytes = (bytes) => createHash(HASH).update(bytes).digest();
+export const renderTitle = (title) => String(title).replace(/\s+/g, ' ').trim().slice(0, TITLE_WIDTH);
+
+export const sliceSection = (bytes, range) => {
+  const starts = [0];
+  bytes.forEach((byte, offset) => { if (byte === LF) starts.push(offset + 1); });
+  const start = starts[range.headingLine - 1];
+  const end = starts[range.to - 1] ?? bytes.length;
+  if (start === undefined || end < start) throw fail(EXIT.usage, 'invalid section byte range');
+  return bytes.subarray(start, end);
+};
+
+const renderHeader = (fields, includeDigest = true) => Buffer.from([
+  MAGIC, ...HEADER_FIELDS.filter((field) => includeDigest || field !== BLOCK_DIGEST_FIELD)
+    .map((field) => `${field}: ${fields[field]}`), '', '',
+].join('\n'));
+
+const sealBlock = (headerBytes, body) => createHash(HASH).update(headerBytes).update(body).digest();
+
+export const frameBlock = ({ date, section, queuePath, sectionBytes, indexEntries }) => {
+  const indexBytes = Buffer.from(indexEntries.map(({ line, klass, id, title }) =>
+    `${line}\t${klass}\t${id ?? KEYLESS}\t${renderTitle(title)}\n`).join(''));
+  const body = Buffer.concat([sectionBytes, indexBytes]);
+  const fields = {
+    date, section: JSON.stringify(canonicalHeading(section)), 'queue-path': JSON.stringify(queuePath),
+    'section-bytes': sectionBytes.length, 'index-bytes': indexBytes.length,
+    'section-sha256': hashBytes(sectionBytes).toString('hex'), rows: indexEntries.length,
+  };
+  fields[BLOCK_DIGEST_FIELD] = sealBlock(renderHeader(fields, false), body).toString('hex');
+  return Buffer.concat([renderHeader(fields), body]);
+};
+
+const readHeader = (bytes, offset) => {
+  const state = { at: offset, line: 1 };
+  const readLine = () => {
+    const end = bytes.indexOf(LF, state.at);
+    if (end < 0) throw { line: state.line, truncated: true };
+    const line = bytes.subarray(state.at, end).toString('utf8');
+    state.at = end + 1;
+    state.line += 1;
+    return line;
+  };
+  const opening = readLine();
+  if (opening !== MAGIC) throw { line: 1 };
+  const fields = {};
+  const sealedParts = [bytes.subarray(offset, state.at)];
+  for (const field of HEADER_FIELDS) {
+    const start = state.at;
+    const line = readLine();
+    const prefix = `${field}: `;
+    if (!line.startsWith(prefix)) throw { line: state.line - 1 };
+    fields[field] = line.slice(prefix.length);
+    if (field !== BLOCK_DIGEST_FIELD) sealedParts.push(bytes.subarray(start, state.at));
+  }
+  const separator = state.at;
+  if (readLine() !== '') throw { line: state.line - 1 };
+  sealedParts.push(bytes.subarray(separator, state.at));
+  for (const field of ['section-bytes', 'index-bytes', 'rows']) {
+    if (!COUNT.test(fields[field]) || !Number.isSafeInteger(Number(fields[field]))) {
+      throw { line: HEADER_FIELDS.indexOf(field) + 2 };
+    }
+  }
+  for (const field of ['section-sha256', BLOCK_DIGEST_FIELD]) {
+    if (!HEX_DIGEST.test(fields[field])) throw { line: HEADER_FIELDS.indexOf(field) + 2 };
+  }
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(fields.date)) throw { line: 2 };
+  const readString = (field) => {
+    try {
+      const value = JSON.parse(fields[field]);
+      if (typeof value === 'string') return value;
+    } catch { /* The field's line is reported below. */ }
+    throw { line: HEADER_FIELDS.indexOf(field) + 2 };
+  };
+  return { fields, bodyStart: state.at, sealedHeader: Buffer.concat(sealedParts),
+    section: readString('section'), queuePath: readString('queue-path') };
+};
+
+const readIndex = (bytes) => {
+  if (bytes.length === 0) return [];
+  if (bytes.at(-1) !== LF) return null;
+  const lines = bytes.toString('utf8').slice(0, -1).split('\n');
+  const entries = lines.map((text) => {
+    const cells = text.split('\t');
+    if (cells.length !== INDEX_COLUMNS) return null;
+    const [line, klass, key, title] = cells;
+    if (!COUNT.test(line) || Number(line) < 1 || !Number.isSafeInteger(Number(line)) || !klass || !key || /\r/.test(text)) return null;
+    return { line: Number(line), klass, id: key === KEYLESS ? null : key, title };
+  });
+  return entries.includes(null) ? null : entries;
+};
+
+const judgeBlock = (block) => Boolean(block.indexEntries
+  && block.rowCount === block.indexEntries.length
+  && hashBytes(block.sectionBytes).equals(block.sectionDigest)
+  && sealBlock(block.sealedHeader, block.body).equals(block.blockDigest));
+
+export const readArchive = (bytes) => {
+  const archive = { bytes, blocks: [], intact: true, offset: 0, cause: null };
+  const refuse = (cause, line) => Object.assign(archive, {
+    intact: false, cause, line,
+    problem: cause === 'foreign' ? `foreign archive grammar at line ${line}`
+      : `archive not intact: block ${archive.blocks.length + 1} at byte offset ${archive.offset}; no key comparison performed`,
+  });
+  while (archive.offset < bytes.length) {
+    const offset = archive.offset;
+    const parsed = (() => {
+      try { return readHeader(bytes, offset); }
+      catch (error) {
+        const recognised = bytes.subarray(offset, offset + Buffer.byteLength(MAGIC)).equals(Buffer.from(MAGIC));
+        refuse(offset === 0 && !(recognised && error.truncated) ? 'foreign' : 'not-intact', error.line);
+        return null;
+      }
+    })();
+    if (!parsed) return archive;
+    const { fields, bodyStart, sealedHeader, section, queuePath } = parsed;
+    const sectionEnd = bodyStart + Number(fields['section-bytes']);
+    const end = sectionEnd + Number(fields['index-bytes']);
+    if (!Number.isSafeInteger(end) || end > bytes.length) return refuse('not-intact');
+    const block = {
+      date: fields.date, section, queuePath, offset, end, sealedHeader,
+      sectionBytes: bytes.subarray(bodyStart, sectionEnd), indexBytes: bytes.subarray(sectionEnd, end),
+      sectionDigest: Buffer.from(fields['section-sha256'], 'hex'),
+      blockDigest: Buffer.from(fields[BLOCK_DIGEST_FIELD], 'hex'),
+      rowCount: Number(fields.rows), body: bytes.subarray(bodyStart, end),
+      indexEntries: readIndex(bytes.subarray(sectionEnd, end)),
+    };
+    if (!judgeBlock(block)) return refuse('not-intact');
+    archive.blocks.push(block);
+    archive.offset = end;
+  }
+  return archive;
+};
+
+export const judgeIntact = (archive) => archive.intact && archive.offset === archive.bytes.length
+  && archive.blocks.every(judgeBlock);
+
+export const appendBlock = (path, blockBytes) => {
+  const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+  const staged = openSync(temporary, 'wx', PRIVATE_MODE);
+  try {
+    writeFileSync(staged, blockBytes);
+    fsyncSync(staged);
+    const complete = readFileSync(temporary);
+    if (!complete.equals(blockBytes)) throw fail(EXIT.refuse, `incomplete staged block for ${path}`);
+    const descriptor = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND
+      | constants.O_NOFOLLOW | constants.O_NONBLOCK, PRIVATE_MODE);
+    try {
+      if (!fstatSync(descriptor).isFile()) throw fail(EXIT.usage, `${path}: archive is not a regular file`);
+      const written = writeSync(descriptor, complete);
+      fsyncSync(descriptor);
+      if (written !== complete.length) throw fail(EXIT.refuse, `${path}: partial archive append (${written} of ${complete.length} bytes)`);
+    } finally { closeSync(descriptor); }
+  } finally {
+    try { closeSync(staged); }
+    finally { unlinkSync(temporary); }
+  }
+};

package/tools/queue-purge-cli.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import { constants, openSync, closeSync, fstatSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fail } from '../references/scripts/markdown-blocks.mjs';
+import { isDirectRun } from './direct-run.mjs';
+import { EXIT, appendBlock, readArchive } from './queue-purge-archive.mjs';
+import { snapshotQueue, checkPurge } from './queue-purge.mjs';
+
+const VERBS = ['snapshot', '--check'];
+const OPTIONS = new Map([['--section', 'section'], ['--archive', 'archive']]);
+const HELP_FLAGS = ['--help', '-h'];
+const HELP = `Usage:
+  node queue-purge-cli.mjs snapshot <queue-file> --section <heading> --archive <file>
+  node queue-purge-cli.mjs --check <queue-file> --section <heading> --archive <file>
+
+snapshot appends the section bytes and row index; --check verifies the purge without writing.
+Exit codes: 0 accept, 1 refuse, 2 usage. --help or -h must be the whole invocation.`;
+
+const parseArgv = (argv) => {
+  if (argv.length === 1 && HELP_FLAGS.includes(argv[0])) return { help: true };
+  const options = {};
+  const state = { index: 0 };
+  const readValue = (flag) => {
+    const value = argv[state.index + 1];
+    if (!value || value.startsWith('-') || VERBS.includes(value)) throw fail(EXIT.usage, `${flag} takes a value`);
+    state.index += 1;
+    return value;
+  };
+  while (state.index < argv.length) {
+    const arg = argv[state.index];
+    if (VERBS.includes(arg)) {
+      if (options.verb) throw fail(EXIT.usage, 'name exactly one verb: snapshot or --check');
+      options.verb = arg;
+      options.queuePath = readValue(arg);
+    } else if (OPTIONS.has(arg)) {
+      const field = OPTIONS.get(arg);
+      if (Object.hasOwn(options, field)) throw fail(EXIT.usage, `${arg} was given twice`);
+      options[field] = readValue(arg);
+    } else if (HELP_FLAGS.includes(arg)) throw fail(EXIT.usage, '--help is answered only as the whole invocation');
+    else throw fail(EXIT.usage, `unknown argument ${JSON.stringify(arg)}`);
+    state.index += 1;
+  }
+  if (!options.verb) throw fail(EXIT.usage, 'exactly one verb is required: snapshot or --check');
+  for (const [flag, field] of OPTIONS) if (!options[field]) throw fail(EXIT.usage, `${flag} is required`);
+  return options;
+};
+
+const readRegular = (path, read) => {
+  const descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const stats = fstatSync(descriptor);
+    if (!stats.isFile()) throw fail(EXIT.usage, `${path}: not a regular file`);
+    return read(descriptor, stats);
+  } finally { closeSync(descriptor); }
+};
+
+const readFiles = ({ queuePath, archive, verb }) => {
+  const queueReal = realpathSync(queuePath);
+  const queue = readRegular(queueReal, (descriptor, stats) => ({ bytes: readFileSync(descriptor), stats }));
+  if (!statSync(dirname(archive)).isDirectory()) throw fail(EXIT.usage, `${archive}: parent is not a directory`);
+  const archiveReal = (() => {
+    try { return realpathSync(archive); }
+    catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  })();
+  if (resolve(queuePath) === resolve(archive) || queueReal === archiveReal) {
+    throw fail(EXIT.usage, `${archive}: archive resolves to the queue ${queuePath}`);
+  }
+  const archiveBytes = (() => {
+    try {
+      return readRegular(archive, (descriptor, stats) => {
+        if (stats.dev === queue.stats.dev && stats.ino === queue.stats.ino) {
+          throw fail(EXIT.usage, `${archive}: archive is a hard link to the queue ${queuePath}`);
+        }
+        return readFileSync(descriptor);
+      });
+    } catch (error) {
+      if (error.code === 'ENOENT' && verb === 'snapshot') return Buffer.alloc(0);
+      throw error;
+    }
+  })();
+  if (!archiveBytes.length && verb === '--check') throw fail(EXIT.usage, `${archive}: empty archive`);
+  return { queueBytes: queue.bytes, archiveBytes };
+};
+
+export const main = (argv, { log = console.log, error = console.error } = {}) => {
+  const state = { fallback: EXIT.usage, options: null };
+  try {
+    const options = parseArgv(argv);
+    state.options = options;
+    if (options.help) { log(HELP); return EXIT.accept; }
+    const inputs = readFiles(options);
+    const args = { ...options, ...inputs, date: new Date().toISOString().split('T')[0] };
+    const result = options.verb === 'snapshot' ? snapshotQueue(args) : checkPurge(args);
+    for (const problem of result.problems) error(problem);
+    if (!result.ok) return EXIT.refuse;
+    if (options.verb === 'snapshot') {
+      state.fallback = EXIT.refuse;
+      appendBlock(options.archive, result.block);
+      const [block] = readArchive(result.block).blocks;
+      for (const note of result.notes) error(note);
+      log(`${options.archive}: ${block.rowCount} rows, ${block.sectionBytes.length} section bytes (${block.section})`);
+    } else log(`accept: ${options.section}; archive ${options.archive}`);
+    return EXIT.accept;
+  } catch (err) {
+    const paths = state.options ? `${state.options.queuePath}; archive ${state.options.archive}: ` : '';
+    error(`${paths}${err.message}`);
+    return [EXIT.refuse, EXIT.usage].includes(err.exitCode) ? err.exitCode : state.fallback;
+  }
+};
+
+if (isDirectRun(import.meta.url)) process.exitCode = main(process.argv.slice(2));

package/tools/queue-purge.mjs

@@ -0,0 +1,66 @@
+import { auditQueue, authorisesRemoval, canonicalHeading } from './queue-audit.mjs';
+import { EXIT, frameBlock, hashBytes, judgeIntact, readArchive, renderTitle, sliceSection } from './queue-purge-archive.mjs';
+import { fail } from '../references/scripts/markdown-blocks.mjs';
+
+const readInputs = ({ queueBytes, section, archiveBytes = Buffer.alloc(0) }) => {
+  if (!canonicalHeading(section)) throw fail(EXIT.usage, '--section is required');
+  const audit = auditQueue(queueBytes.toString('utf8'), { range: section });
+  const rows = audit.rows.filter(({ line }) => line >= audit.range.from && line < audit.range.to);
+  const problems = [];
+  const keys = new Map();
+  for (const row of audit.rows) {
+    if (!row.id) continue;
+    const earlier = keys.get(row.id);
+    if (earlier) problems.push(`key defect: doubled id ${row.id} at file lines ${earlier.line} and ${row.line}`);
+    else keys.set(row.id, row);
+  }
+  const archive = readArchive(archiveBytes);
+  if (archive.cause === 'foreign') throw fail(EXIT.usage, archive.problem);
+  return { rows, problems, archive, section: canonicalHeading(section), sectionBytes: sliceSection(queueBytes, audit.range) };
+};
+
+const selectBlock = (archive, section) => archive.blocks.findLast((block) => canonicalHeading(block.section) === section);
+const makeResult = (problems, notes = [], block) => ({ ok: problems.length === 0, problems, notes,
+  ...(block === undefined ? {} : { block }) });
+
+export const snapshotQueue = (options) => {
+  const { rows, problems, archive, section, sectionBytes } = readInputs(options);
+  const keyless = rows.filter(({ id }) => !id);
+  const notes = keyless.length ? [`${keyless.length} keyless rows archived in ${section}`] : [];
+  if (!judgeIntact(archive)) problems.push(archive.problem);
+  if (problems.length) return makeResult(problems, [], null);
+  const previous = selectBlock(archive, section);
+  if (previous?.sectionDigest.equals(hashBytes(sectionBytes))) {
+    return makeResult([`same section digest as the last block for ${section}`], [], null);
+  }
+  const block = frameBlock({ date: options.date, section, queuePath: options.queuePath, sectionBytes, indexEntries: rows });
+  return makeResult(problems, notes, block);
+};
+
+export const checkPurge = (options) => {
+  const { rows, problems, archive, section, sectionBytes } = readInputs(options);
+  for (const row of rows.filter(({ id }) => !id)) {
+    problems.push(`key defect: no id at current file line ${row.line}: ${renderTitle(row.title)}`);
+  }
+  if (!judgeIntact(archive)) return makeResult([...problems, archive.problem]);
+  const block = selectBlock(archive, section);
+  if (!block) {
+    const recorded = [...new Set(archive.blocks.map(({ section: heading }) => heading))];
+    throw fail(EXIT.usage, `no archive block for ${section}; recorded headings: ${recorded.join(', ') || '(none)'}`);
+  }
+  if (block.sectionDigest.equals(hashBytes(sectionBytes))) problems.push(`section not moved: ${section}`);
+  const recordedKeys = new Set(block.indexEntries.filter(({ id }) => id).map(({ id }) => id));
+  const currentKeys = new Set(rows.filter(({ id }) => id).map(({ id }) => id));
+  for (const row of rows) {
+    if (row.id && !recordedKeys.has(row.id)) {
+      problems.push(`addition: ${row.id} at current file line ${row.line}: ${renderTitle(row.title)}`);
+    }
+  }
+  for (const entry of block.indexEntries) {
+    if (!entry.id) problems.push(`keyless entry at archived line ${entry.line}: ${entry.title}`);
+    else if (!currentKeys.has(entry.id) && !authorisesRemoval(entry.klass)) {
+      problems.push(`unauthorised absence: ${entry.id} at archived line ${entry.line}: ${entry.title} (recorded class ${entry.klass})`);
+    }
+  }
+  return makeResult(problems);
+};