@sabaiway/agent-workflow-kit 12.2.0 → 12.3.0

package/CHANGELOG.md

@@ -4,6 +4,46 @@ 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.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.3.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.3.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "12.2.0",
+  "version": "12.3.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/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);
+};