@sabaiway/agent-workflow-kit 12.1.0 → 12.3.0

package/CHANGELOG.md

@@ -4,6 +4,61 @@ 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
+this release; no kit tool changed behaviour.
+
+- **`Gemini 3.8 Flash (High)` is the bridge default for both roles** — `agy-run` and `agy-review` — and joins the review
+  wrapper's frontier set. The string is what `agy models` on the installed CLI (1.1.28, probed 2026-09-09) prints; a model
+  display string is matched exactly, so a stale default is a dispatch that refuses before it spends anything (AD-095).
+  `Gemini 3.7 Flash (High)` stays in the frontier set: a host that pins it explicitly keeps an advisory-silent council
+  review. Any model remains selectable through `AGY_MODEL`; the sub-frontier advisory is still a warning, never a gate.
+- **The catalog tables gain the three 3.8 rows**, enumerated individually, in the skill, the model reference and the
+  driving playbook; the wrapper's header inventory names the 3.8 family. No row is removed.
+- **The posture render follows the pin.** The status line and the D5 posture footer read the bundled manifest, so they
+  now print `agy model=Gemini 3.8 Flash (High)`; the posture-parity test pins the pair.
+
 ## 12.1.0 — a queue row carries a plain name a person can read, and `now` renders where the work stands from the evidence, never from the plan's own text (AD-134)
 
 **MINOR: two additive surfaces, one series, one new refusal.** The name judge is advisory until a gate line opts in, and `now` is

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.1.0'
+  version: '12.3.0'
 ---
 
 # agent-workflow-kit

package/bridges/antigravity-cli-bridge/SKILL.md

@@ -2,7 +2,7 @@
 name: antigravity-cli-bridge
 description: Delegate work to Google's Antigravity CLI (`agy`) — the successor to Gemini CLI — to reach Gemini, Claude, and GPT-OSS models under a Google AI Pro/Ultra subscription from the terminal. Use when the user wants to run a headless `agy` prompt, hand a focused task or second-opinion review to `agy`, install or authenticate Antigravity CLI, check or economise its quota/models, bridge project context into `agy`, set up a second delegated-execution backend beside Codex, or troubleshoot `agy` flags, models, auth, conversations, or its headless behaviour.
 metadata:
-  version: '5.6.0'
+  version: '5.7.0'
 ---
 
 # antigravity-cli-bridge
@@ -53,20 +53,23 @@ keep probes short (see *How the main agent drives agy*).
 ## Models
 
 Pass the **exact display string** to `--model` (or set `AGY_MODEL`). The wrapper defaults to
-`Gemini 3.7 Flash (High)`. Run `agy models` for the live list — if it differs from this table, the
+`Gemini 3.8 Flash (High)`. Run `agy models` for the live list — if it differs from this table, the
 live list wins.
 
 | Model string | Use it for |
 |---|---|
-| `Gemini 3.7 Flash (Low)` | cheapest; reachability checks, smoke tests, simple transforms |
-| `Gemini 3.7 Flash (Medium)` | cheap probes, context-reachability checks, quick summaries |
-| `Gemini 3.7 Flash (High)` | wrapper + review default; asserted frontier-grade (fork (a)) |
-| `Gemini 3.6 Flash (Low)` | previous Flash generation, still served — prefer 3.7 |
-| `Gemini 3.6 Flash (Medium)` | previous Flash generation, still served — prefer 3.7 |
-| `Gemini 3.6 Flash (High)` | previous Flash generation, still served — prefer 3.7 |
-| `Gemini 3.5 Flash (Low)` | older Flash generation, still served — prefer 3.7 |
-| `Gemini 3.5 Flash (Medium)` | older Flash generation, still served — prefer 3.7 |
-| `Gemini 3.5 Flash (High)` | older Flash generation, still served — prefer 3.7 |
+| `Gemini 3.8 Flash (Low)` | cheapest; reachability checks, smoke tests, simple transforms |
+| `Gemini 3.8 Flash (Medium)` | cheap probes, context-reachability checks, quick summaries |
+| `Gemini 3.8 Flash (High)` | wrapper + review default; asserted frontier-grade (AD-136) |
+| `Gemini 3.7 Flash (Low)` | previous Flash generation, still served — prefer 3.8 |
+| `Gemini 3.7 Flash (Medium)` | previous Flash generation, still served — prefer 3.8 |
+| `Gemini 3.7 Flash (High)` | previous Flash generation, still frontier-grade for review (fork (a)) |
+| `Gemini 3.6 Flash (Low)` | older Flash generation, still served — prefer 3.8 |
+| `Gemini 3.6 Flash (Medium)` | older Flash generation, still served — prefer 3.8 |
+| `Gemini 3.6 Flash (High)` | older Flash generation, still served — prefer 3.8 |
+| `Gemini 3.5 Flash (Low)` | older Flash generation, still served — prefer 3.8 |
+| `Gemini 3.5 Flash (Medium)` | older Flash generation, still served — prefer 3.8 |
+| `Gemini 3.5 Flash (High)` | older Flash generation, still served — prefer 3.8 |
 | `Gemini 3.1 Pro (Low)` | cheaper Pro pass for medium reasoning |
 | `Gemini 3.1 Pro (High)` | hard reasoning, plan critique, architecture review (slower, deeper) |
 | `Claude Sonnet 4.6 (Thinking)` | a Claude second opinion through the same subscription |
@@ -100,7 +103,7 @@ can ride passthrough (`-- --output-format json`) but this wrapper adds no parsin
 you need structure, ask for Markdown with explicit headings and validate it yourself. (The `review`
 role is the one that adopted the JSON envelope — see below.) Wrapper inputs: first argument is the
 prompt (`text`, `-` for stdin, or `@file`);
-`AGY_MODEL` (default `Gemini 3.7 Flash (High)`); `AGY_TIMEOUT` → `--print-timeout` (default `5m`);
+`AGY_MODEL` (default `Gemini 3.8 Flash (High)`); `AGY_TIMEOUT` → `--print-timeout` (default `5m`);
 `AGY_HARD_TIMEOUT` → hard `timeout(1)` wall-clock cap (default = `AGY_TIMEOUT`); extra `agy` flags
 after `--`. Full detail: [`references/models-and-flags.md`](references/models-and-flags.md).
 
@@ -189,7 +192,7 @@ release). `agy-review … --nonce <n>` is the plain-argument equivalent
 (one seam; flag and a non-empty env must agree, a disagreeing pair refuses pre-spend) — the lane
 for hosts whose dispatch policy has no env-prefix form.
 
-Frontier default `Gemini 3.7 Flash (High)`; **any** model is allowed (a sub-frontier one earns a
+Frontier default `Gemini 3.8 Flash (High)`; **any** model is allowed (a sub-frontier one earns a
 silenceable `AGY_PROBE=1` advisory). An oversized `code` review is **DELIVERED, not refused**: the
 change set is cut into under-cap parts, fed over continuation turns and reviewed in a final turn, and
 the answer must reproduce a line the wrapper picked from each part — a missing or wrong echo is a

package/bridges/antigravity-cli-bridge/bin/agy-review.sh

@@ -35,7 +35,7 @@
 #   agy-review --conversation <id> [--decided @f] [--focus "…"]   # resume a specific conversation
 #
 # Environment (every optional var has an explicit default so a no-env run is safe under set -u):
-#   AGY_MODEL                default "Gemini 3.7 Flash (High)"; ANY model allowed (advisory warn off-frontier).
+#   AGY_MODEL                default "Gemini 3.8 Flash (High)"; ANY model allowed (advisory warn off-frontier).
 #                            Set empty (AGY_MODEL=) to drop --model and use agy's settings.json.
 #   AGY_HARD_TIMEOUT         default 30m  (duration string; the timeout(1) hard cap via agy-run)
 #   AGY_TIMEOUT              default = AGY_HARD_TIMEOUT (agy's soft --print-timeout)
@@ -339,11 +339,11 @@ aw_resolve_timeout_bin() {
   printf '%s' "$bin"
 }
 
-DEFAULT_AGY_REVIEW_MODEL="Gemini 3.7 Flash (High)"
+DEFAULT_AGY_REVIEW_MODEL="Gemini 3.8 Flash (High)"
 # Review-receipt identity (AD-038). AW_BRIDGE_VERSION mirrors this bridge's SKILL.md/capability.json
 # version (drift-guarded by agy-review.test.mjs against capability.json).
 AW_RECEIPT_BACKEND="agy"
-AW_BRIDGE_VERSION="5.6.0"  # aw-version-anchor
+AW_BRIDGE_VERSION="5.7.0"  # aw-version-anchor
 # `-` not `:-` so an EXPLICIT empty AGY_MODEL= survives (drop --model, use settings.json — agy.sh:52).
 AGY_MODEL="${AGY_MODEL-$DEFAULT_AGY_REVIEW_MODEL}"
 # D5 control-byte screen — IMMEDIATELY after resolution, BEFORE the off-frontier advisory (or any
@@ -353,8 +353,9 @@ if [[ "$AGY_MODEL" == *[$'\x01'-$'\x1f'$'\x7f']* ]]; then
   exit 2
 fi
 # Frontier review models. ANY model is allowed; a sub-frontier one only earns a soft, silenceable
-# warning. Gemini 3.7 Flash (High) is asserted frontier-grade (fork (a), maintainer 2026-08-14).
-FRONTIER_SET=("Gemini 3.7 Flash (High)" "Gemini 3.1 Pro (High)" "Claude Opus 4.6 (Thinking)" "Claude Sonnet 4.6 (Thinking)")
+# warning. Gemini 3.8 Flash (High) is asserted frontier-grade (AD-136, maintainer 2026-09-09); 3.7 Flash
+# (High) stays in the set (fork (a), maintainer 2026-08-14).
+FRONTIER_SET=("Gemini 3.8 Flash (High)" "Gemini 3.7 Flash (High)" "Gemini 3.1 Pro (High)" "Claude Opus 4.6 (Thinking)" "Claude Sonnet 4.6 (Thinking)")
 
 # Duration-string timeouts (NOT codex's bare seconds): agy-run forwards a duration to --print-timeout,
 # and the timeout(1) hard cap is a duration too — never numerically compared, so 30m vs 2h is fine.

package/bridges/antigravity-cli-bridge/bin/agy-review.test.mjs

@@ -42,10 +42,10 @@ describe('agy-review.sh — model policy advisory (1)', { concurrency: 2 }, () =
     rmSync(sb.home, { recursive: true, force: true });
     assert.equal(r.status, 0, r.stderr);
     assert.doesNotMatch(r.stderr, /non-frontier model/);
-    assert.match(r.argv, /Gemini 3\.7 Flash \(High\)/, 'the frontier default reaches agy');
+    assert.match(r.argv, /Gemini 3\.8 Flash \(High\)/, 'the frontier default reaches agy');
   });
 
-  it('an explicit Gemini 3.7 Flash (High) is FRONTIER — no advisory (fork (a), maintainer 2026-08-14)', async () => {
+  it('an explicit Gemini 3.7 Flash (High) stays FRONTIER after the 3.8 pin move — no advisory (AD-136)', async () => {
     const sb = makeSandbox();
     const r = await run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_MODEL: 'Gemini 3.7 Flash (High)' } });
     rmSync(sb.home, { recursive: true, force: true });
@@ -2776,8 +2776,8 @@ describe('agy-review.sh — dispatch-posture labeling (D5)', { concurrency: 2 },
     const receipts = readReceipts(sb.repo);
     rmSync(sb.home, { recursive: true, force: true });
     assert.equal(r.status, 0, r.stderr);
-    assert.match(r.stderr, /review posture: model=Gemini 3\.7 Flash \(High\)/, 'the banner states the actual run posture');
-    assert.deepEqual(receipts[0].posture, { model: 'Gemini 3.7 Flash (High)' }, 'banner ↔ receipt parity');
+    assert.match(r.stderr, /review posture: model=Gemini 3\.8 Flash \(High\)/, 'the banner states the actual run posture');
+    assert.deepEqual(receipts[0].posture, { model: 'Gemini 3.8 Flash (High)' }, 'banner ↔ receipt parity');
     assert.deepEqual(Object.keys(receipts[0]), Object.keys(RECEIPT_FIXTURE), 'fixture key set + order');
   });
 
@@ -2830,7 +2830,7 @@ describe('agy-review.sh — dispatch-posture labeling (D5)', { concurrency: 2 },
     const receipts = readReceipts(sb.repo);
     rmSync(sb.home, { recursive: true, force: true });
     assert.equal(r.status, 0, r.stderr);
-    assert.match(r.stderr, /^review posture: model=Gemini 3\.7 Flash \(High\) timeout=30m$/m);
+    assert.match(r.stderr, /^review posture: model=Gemini 3\.8 Flash \(High\) timeout=30m$/m);
     assert.deepEqual(Object.keys(receipts[0].posture), ['model'], 'timeout never enters the receipt posture');
   });
 

package/bridges/antigravity-cli-bridge/bin/agy.sh

@@ -19,8 +19,8 @@
 #
 # Model families (compact inventory only; run `agy models` for exact display strings, then pass
 # one via AGY_MODEL):
-#   Gemini 3.7 Flash (Low|Medium|High), Gemini 3.6 Flash (Low|Medium|High),
-#   Gemini 3.5 Flash (Low|Medium|High), Gemini 3.1 Pro (Low|High),
+#   Gemini 3.8 Flash (Low|Medium|High), Gemini 3.7 Flash (Low|Medium|High),
+#   Gemini 3.6 Flash (Low|Medium|High), Gemini 3.5 Flash (Low|Medium|High), Gemini 3.1 Pro (Low|High),
 #   Claude Sonnet 4.6 (Thinking), Claude Opus 4.6 (Thinking), GPT-OSS 120B (Medium)
 #
 # Usage (installed on PATH as `agy-run`):
@@ -240,8 +240,8 @@ if ! command -v agy >/dev/null 2>&1; then
 fi
 
 # `-` (empty) => skip --model and let agy use settings.json; default to Flash (High) — asserted
-# frontier-grade (fork (a), maintainer 2026-08-14).
-AGY_MODEL="${AGY_MODEL-Gemini 3.7 Flash (High)}"
+# frontier-grade (fork (a), maintainer 2026-08-14; the 3.8 pin AD-136, 2026-09-09).
+AGY_MODEL="${AGY_MODEL-Gemini 3.8 Flash (High)}"
 AGY_TIMEOUT="${AGY_TIMEOUT:-5m}"
 AGY_TIMEOUT="$(aw_effective_timeout AGY_TIMEOUT 5m)"
 # Hard wall-clock cap (defaults to AGY_TIMEOUT). agy's own --print-timeout is NOT a reliable

package/bridges/antigravity-cli-bridge/bin/agy.test.mjs

@@ -449,7 +449,7 @@ describe('agy.sh — bridge settings file (bridges 2.3.0)', { concurrency: true
 
 // ── the wrapper's OWN default model (fork (a), round-1 council F3) ────────────────
 describe('agy.sh — default model pin', () => {
-  it('absent AGY_MODEL → the stub argv carries --model Gemini 3.7 Flash (High)', () => {
+  it('absent AGY_MODEL → the stub argv carries --model Gemini 3.8 Flash (High)', () => {
     const home = makeSandbox(ARGV_STUB);
     const argvFile = join(home, 'argv.txt');
     const r = runWrapper(home, { AGY_STUB_ARGV: argvFile });
@@ -457,7 +457,7 @@ describe('agy.sh — default model pin', () => {
     rmSync(home, { recursive: true, force: true });
     assert.equal(r.status, 0, r.stderr);
     assert.match(argv, /^--model$/m, 'the default run passes --model');
-    assert.match(argv, /^Gemini 3\.7 Flash \(High\)$/m, 'the wrapper default is the probed display string');
+    assert.match(argv, /^Gemini 3\.8 Flash \(High\)$/m, 'the wrapper default is the probed display string');
   });
 
   it("explicit AGY_MODEL='' drops --model entirely (settings.json takes over)", () => {

package/bridges/antigravity-cli-bridge/capability.json

@@ -3,9 +3,9 @@
   "schema": 1,
   "name": "antigravity-cli-bridge",
   "kind": "execution-backend",
-  "version": "5.6.0",
+  "version": "5.7.0",
   "provides": ["review", "probe"],
-  "posture": { "model": "Gemini 3.7 Flash (High)" },
+  "posture": { "model": "Gemini 3.8 Flash (High)" },
   "roles": {
     "review": {
       "cmd": "agy-review",
@@ -181,7 +181,7 @@
       ],
       "guardrails": [
         { "value": "subscription-only — every *_API_KEY env var is unset before the run", "enforcement": "enforced", "source": "bin/agy.sh" },
-        { "value": "any model is selectable via AGY_MODEL; the default is Gemini 3.7 Flash (High)", "enforcement": "advisory", "source": "bin/agy.sh" },
+        { "value": "any model is selectable via AGY_MODEL; the default is Gemini 3.8 Flash (High)", "enforcement": "advisory", "source": "bin/agy.sh" },
         { "value": "hard wall-clock cap AGY_HARD_TIMEOUT (built-in default 5m)", "enforcement": "enforced", "condition": "only while timeout(1)/gtimeout is on PATH — otherwise the wrapper warns and runs uncapped", "source": "capability.json settings.AGY_HARD_TIMEOUT" },
         { "value": "the prompt rides a single argv — over AGY_MAX_PROMPT_BYTES (120000) the run refuses", "enforcement": "enforced", "source": "bin/agy.sh" },
         { "value": "no review posture, no grounding, no receipt — the reply is raw model output", "enforcement": "advisory", "source": "bin/agy.sh" }

package/bridges/antigravity-cli-bridge/references/driving-agy.md

@@ -18,14 +18,15 @@ edits, verification, and final judgment.
 
 | Task | Model |
 |---|---|
-| Reachability / smoke / "is it wired?" | `Gemini 3.7 Flash (Low)` |
-| Cheap probes, summaries | `Gemini 3.7 Flash (Medium)` |
-| Review, reasoning, careful drafting | `Gemini 3.7 Flash (High)` (wrapper default; asserted frontier-grade) |
+| Reachability / smoke / "is it wired?" | `Gemini 3.8 Flash (Low)` |
+| Cheap probes, summaries | `Gemini 3.8 Flash (Medium)` |
+| Review, reasoning, careful drafting | `Gemini 3.8 Flash (High)` (wrapper default; asserted frontier-grade, AD-136) |
+| The previous Flash generation, still frontier-grade for review | `Gemini 3.7 Flash (High)` (fork (a)) |
 | Slower, deeper reasoning pass | `Gemini 3.1 Pro (High)` |
 | Same Pro reasoning, lower quota cost | `Gemini 3.1 Pro (Low)` |
 | A different engine's opinion | `Claude Sonnet 4.6 (Thinking)`, `Claude Opus 4.6 (Thinking)`, or `GPT-OSS 120B (Medium)` |
 
-The 3.6 / 3.5 Flash families remain served — prefer 3.7 (newest generation at the same tiers).
+The 3.7 / 3.6 / 3.5 Flash families remain served — prefer 3.8 (newest generation at the same tiers).
 Don't reach for Pro by reflex — Flash answers most reachability/probe questions for a fraction of the
 quota.
 
@@ -95,7 +96,7 @@ What it does for you, and what YOU must supply:
   `AGY_REVIEW_ALLOW_ADDDIR` is **RETIRED** (recognized, arms nothing): headless `agy` auto-denies its
   own `read_file`, so the offload it armed could return a confident fabrication with no way to tell.
   The kit never grants that permission — the feed exists so none is needed.
-- **Model:** frontier default `Gemini 3.7 Flash (High)`; any model is allowed (a sub-frontier one earns a
+- **Model:** frontier default `Gemini 3.8 Flash (High)`; any model is allowed (a sub-frontier one earns a
   silenceable `AGY_PROBE=1` advisory). The service can still **stall on large/substantive prompts**
   (Issue-001) — keep reviews **focused**; the hard timeout is the guard.
 - **Posture banner — quote it verbatim.** Every review states its ACTUAL posture on ONE stderr line

package/bridges/antigravity-cli-bridge/references/models-and-flags.md

@@ -46,7 +46,7 @@ Environment:
 
 | Var | Default | Effect |
 |---|---|---|
-| `AGY_MODEL` | `Gemini 3.7 Flash (High)` | model display string; set empty (`AGY_MODEL=`) to drop `--model` and let `agy` use `settings.json` |
+| `AGY_MODEL` | `Gemini 3.8 Flash (High)` | model display string; set empty (`AGY_MODEL=`) to drop `--model` and let `agy` use `settings.json` |
 | `AGY_TIMEOUT` | `5m` | value passed to `--print-timeout` |
 | `AGY_HARD_TIMEOUT` | `= AGY_TIMEOUT` | hard `timeout(1)` wall-clock cap (a duration string) |
 | `AGY_MAX_PROMPT_BYTES` | `120000` | single-argv byte ceiling. `agy` takes the prompt as ONE `-p` argv; past `MAX_ARG_STRLEN` (~131072) `execve` fails with a cryptic `Argument list too long`. The wrapper measures the resolved `-`/`@file` prompt and fails loud over the ceiling. A huge **literal** `agy-run "<huge>"` fails at the wrapper's own `exec`, so route large prompts via `-`/`@file`. |
@@ -71,7 +71,7 @@ agy-review --continue | --conversation <id>   [--decided @f] [--focus "…"]   #
 
 | Var | Default | Effect |
 |---|---|---|
-| `AGY_MODEL` | `Gemini 3.7 Flash (High)` | frontier default (fork (a), 2026-08-14); **any** model is allowed — a sub-frontier one earns a silenceable advisory (quality-first, not a gate) |
+| `AGY_MODEL` | `Gemini 3.8 Flash (High)` | frontier default (AD-136, 2026-09-09; 3.7 Flash (High) stays frontier, fork (a)); **any** model is allowed — a sub-frontier one earns a silenceable advisory (quality-first, not a gate) |
 | `AGY_PROBE` | `0` | `1` silences the off-frontier model advisory AND lets `code` run without `--facts` (an ungrounded probe never attests — its receipt is probe-marked) |
 | `AGY_REVIEW_MAX_TOTAL_BYTES` | `240000` | the ceiling on the SUM of all outgoing prompt bytes an oversized `code` review's chunked feed may send; checked BEFORE the first turn is spent |
 | `AGY_REVIEW_ALLOW_ADDDIR` | `0` | **RETIRED** — recognized so an existing settings line never warns as unknown, but it arms nothing. An oversized `code` review is a chunked feed with a per-part delivery proof; the `--add-dir` offload it armed could not be verified (headless `agy` auto-denies `read_file`) |
@@ -97,15 +97,18 @@ Pass the **exact display string** from `agy models`, or set `AGY_MODEL`.
 
 | Model string | Practical use |
 |---|---|
-| `Gemini 3.7 Flash (Low)` | lowest-cost smoke tests, cheap probes, simple rewrites (newest Flash) |
-| `Gemini 3.7 Flash (Medium)` | fast summaries, context-reachability checks |
-| `Gemini 3.7 Flash (High)` | wrapper + review default — asserted frontier-grade (fork (a)) |
-| `Gemini 3.6 Flash (Low)` | previous Flash generation, still served — prefer 3.7 |
-| `Gemini 3.6 Flash (Medium)` | previous Flash generation, still served — prefer 3.7 |
-| `Gemini 3.6 Flash (High)` | previous Flash generation, still served — prefer 3.7 |
-| `Gemini 3.5 Flash (Low)` | older Flash generation, still served — prefer 3.7 |
-| `Gemini 3.5 Flash (Medium)` | older Flash generation, still served — prefer 3.7 |
-| `Gemini 3.5 Flash (High)` | older Flash generation, still served — prefer 3.7 |
+| `Gemini 3.8 Flash (Low)` | lowest-cost smoke tests, cheap probes, simple rewrites (newest Flash) |
+| `Gemini 3.8 Flash (Medium)` | fast summaries, context-reachability checks |
+| `Gemini 3.8 Flash (High)` | wrapper + review default — asserted frontier-grade (AD-136) |
+| `Gemini 3.7 Flash (Low)` | previous Flash generation, still served — prefer 3.8 |
+| `Gemini 3.7 Flash (Medium)` | previous Flash generation, still served — prefer 3.8 |
+| `Gemini 3.7 Flash (High)` | previous Flash generation, still frontier-grade for review (fork (a)) |
+| `Gemini 3.6 Flash (Low)` | older Flash generation, still served — prefer 3.8 |
+| `Gemini 3.6 Flash (Medium)` | older Flash generation, still served — prefer 3.8 |
+| `Gemini 3.6 Flash (High)` | older Flash generation, still served — prefer 3.8 |
+| `Gemini 3.5 Flash (Low)` | older Flash generation, still served — prefer 3.8 |
+| `Gemini 3.5 Flash (Medium)` | older Flash generation, still served — prefer 3.8 |
+| `Gemini 3.5 Flash (High)` | older Flash generation, still served — prefer 3.8 |
 | `Gemini 3.1 Pro (Low)` | cheaper Pro pass for medium reasoning |
 | `Gemini 3.1 Pro (High)` | hard reasoning, plan critique, architecture review (slower, deeper) |
 | `Claude Sonnet 4.6 (Thinking)` | cross-vendor reasoning comparison |

package/capability.json

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

package/package.json

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