@sabaiway/agent-workflow-memory 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -4,6 +4,57 @@ All notable changes to the memory substrate. Versions are this **package's** npm
 they are distinct from the **deployment-lineage** stamp written into a project's
 `docs/ai/.memory-version` (which tracks the shared `agent-workflow` lineage, head `1.3.0`).
 
+## 1.8.0 — ADR-cascade rotation script + the seeded per-project gate declaration
+
+A **feature** release (deployment-lineage head stays `1.3.0`; the new surfaces reach existing
+deployments via stamp-independent ensures, no migration file). The last hand-rolled docs
+rotation — the `decisions.md` ADR cascade — is now a script, and every project gains a
+hand-editable gate declaration:
+
+- **`references/scripts/archive-decisions.mjs` (+ test)** — the `archive-changelog.mjs` sibling:
+  a chained three-tier cascade (HOT `decisions.md` → WARM `history/decisions-archive.md` → COLD
+  `history/decisions-archive-early.md`), caps read from each file's own frontmatter `maxLines`.
+  Whole entries move, oldest first; the id multiset and every entry's line count are
+  conservation-checked before any write. **Fail-LOUD**: a non-canonical `## AD-0NN — <title>`
+  heading, disordered ids, a cross-tier duplicate, or a roll that would not fit COLD's remaining
+  headroom all refuse **before any write** (a cap raise is a maintainer decision — the script
+  only moves entries). `--check` reports per-tier `lines/cap`; on a project **without**
+  `decisions.md` it exits 0 with a **stated skip** — a deliberate divergence from
+  `archive-changelog.mjs` (the deployed pre-commit hook must never block a commit over an absent
+  ADR substrate).
+- **The pre-commit hook runs it** — `install-git-hooks.mjs` adds `archive-decisions.mjs --check`
+  to the installed gate line-up.
+- **`references/templates/gates.json`** — the seeded, user-editable per-project **gate
+  declaration** (`{ id, title, cmd }`, strict JSON, an empty list as shipped; `cmd` is ONE bash
+  command line). Bootstrap seeds it; upgrade **ensures-if-missing and preserves an existing file
+  byte-for-byte**. It declares WHAT to check — the runner lives in the composition root, never
+  here.
+- **Stamp-independent ensures (equal-head deployments self-heal)** — the upgrade procedure now
+  ensures BOTH seeded `.json` configs **and** the `archive-decisions` script pair
+  (copy-if-missing into `scripts/`, never overwriting an existing file); an old hook without the
+  decisions line stays consistent-safe until the next hook refresh.
+- **Tests** — 22 cascade tests (fixtures for the chained roll, the COLD-exhaustion refusal, the
+  absent-file `--check` skip, determinism, range-token maintenance); bootstrap/ensure coverage
+  extended in `standalone-bootstrap.test.mjs`; tarball content re-pinned (40 files, reverse pins
+  for every new asset).
+
+## 1.7.0 — Humanize the deploy/version report (memory)
+
+A **feature** release (report-prose only — the atomic stamp-WRITE mechanics and the *Stamp = lineage
+head, not package version* gotcha are unchanged; deployment-lineage head stays `1.3.0`, no migration).
+
+The substrate's upgrade report no longer surfaces the internal `docs/ai` **structure version**
+(`.memory-version`) on the happy path:
+
+- A zero-diff equal-head upgrade says **settings already current — no update needed**; a writeful
+  reconcile (a footprint move / config seed) instead reports **what changed** and asks before commit.
+  A fresh bootstrap keeps its deploy-success framing. Neither shows the structure number.
+- The number surfaces only at the never-downgrade **STOP** gate and on an **explicit user ask** (a
+  read-only answer that writes nothing) — named "the `docs/ai` structure version", never "lineage
+  head", with a plain two-axes note (*Version disclosure*). Memory adds **no status mode** (the one
+  intended kit↔memory asymmetry).
+- Pinned by a new static contract test (`scripts/skill-report-contract.test.mjs`).
+
 ## 1.6.0 — §2.6 carries the review-loop economics disciplines (memory)
 
 A **feature** release. The `agent_rules.md` substrate **§2.6** lens gains the review-loop economics

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-memory
 description: Deploy or upgrade a portable AI-agent memory substrate in any project — an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) and a structured `docs/ai/` context store with cap/archive/index enforcement. Use when the user wants to bootstrap `docs/ai/`, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-memory` / `/agent-workflow-memory upgrade`. Triggers on "set up the memory system", "deploy the AI memory here", "bootstrap docs/ai", "upgrade the memory substrate". This is the substrate only — the workflow methodology (plan→execute→review, queue, Cleanup) is owned elsewhere and injected into AGENTS.md by the family composition root.
 disable-model-invocation: true
 metadata:
-  version: '1.6.0'
+  version: '1.8.0'
 ---
 
 # agent-workflow-memory
@@ -48,6 +48,7 @@ What this substrate owns vs what it only points at. The methodology + orchestrat
 | Plan→Phase→Step vocabulary, lifecycle, `queue.md`, mandatory Cleanup | **methodology** (not this skill) | the empty `workflow:methodology` slot — filled by the composition root |
 | Orchestration recipes (Solo / Reviewed / Council / Delegated) | **methodology engine** (not this skill) | the empty `workflow:orchestration` slot — filled by the composition root |
 | Per-project recipe **CONFIG** (which recipe each activity/slot uses) | **memory** seeds an *editable default* | `docs/ai/orchestration.json` (agent-writable via the composition root's `set-recipe` writer, or hand-edited; the recipe **canon** + the slot **vocabulary** live in the engine / composition root, never here) |
+| Per-project **gate declaration** (which verification commands must be green) | **memory** seeds an *editable default* | `docs/ai/gates.json` (hand-editable; an empty list as shipped — the project declares its own commands; the **runner** lives in the composition root, never here) |
 
 ---
 
@@ -96,9 +97,11 @@ bootstrapping over a live system, but the user makes the final call.
    (`ln -s AGENTS.md CLAUDE.md`). **Leave BOTH pointer slots (`workflow:methodology` +
    `workflow:orchestration`) exactly as shipped — empty.** Filling them is the composition root's job.
 6. **Deploy `docs/ai/`.** Create the files + `pages/` from
-   `${CLAUDE_SKILL_DIR}/references/templates/` (every non-`AGENTS.md` template, including the seeded,
-   **user-editable** `docs/ai/orchestration.json` config — strict JSON, the per-project recipe defaults
-   the composition root's `procedures` advisor reads). Keep each file's frontmatter.
+   `${CLAUDE_SKILL_DIR}/references/templates/` (every non-`AGENTS.md` template, including the two
+   seeded, **user-editable** strict-JSON configs: `docs/ai/orchestration.json` — the per-project
+   recipe defaults the composition root's `procedures` advisor reads — and `docs/ai/gates.json` —
+   the project's gate declaration, an empty list to fill with its own verification commands,
+   consumed by the composition root's gate runner). Keep each `.md` file's frontmatter.
 7. **Fill templates** per the table below.
 8. **Install enforcement (Node projects).** Copy `${CLAUDE_SKILL_DIR}/references/scripts/*.mjs`
    (+ `*.test.mjs`) into the project's `scripts/`. **No Node runtime** → skip this + the hook;
@@ -116,7 +119,8 @@ bootstrapping over a live system, but the user makes the final call.
     lineage, a **separate axis** from this package's npm version (the two may even coincide by
     accident; see *Stamp = lineage head, not package version*). Use the atomic writer in
     `scripts/stamp-takeover.mjs` (write-temp + rename).
-11. **Report & ask.** Show `tree docs/ai/`, 2–3 lines on filled-vs-TODO, then **ask before
+11. **Report & ask.** Show `tree docs/ai/`, 2–3 lines on filled-vs-TODO — its normal deploy-success
+    framing, with **no `docs/ai` structure number** (see *Version disclosure*) — then **ask before
     committing** — never auto-commit. **Exception — delegated mode (below): skip this gate.**
 
 > **Delegated mode (invoked by the composition root) — applies to BOTH bootstrap and upgrade.**
@@ -150,7 +154,10 @@ Fill strategy:
 2. **Never-downgrade gate FIRST, then the stamp-independent hidden-mode reconcile (D14).** Compare the
    stamp to the **deployment-lineage head** (`LINEAGE_HEAD`, `1.3.0`). **Greater than the head, or
    unparseable → STOP and report immediately, before ANY write** (never downgrade or guess, and never
-   touch `.git/info/exclude`). Otherwise (stamp **≤ head**) reconcile the hidden-mode footprint — but
+   touch `.git/info/exclude`). This STOP is one of the only two places the number is shown (see
+   *Version disclosure* below): tell the user **the `docs/ai` structure version** their deployment
+   carries versus the one this substrate expects, plus the plain one-line two-axes note — naming it the
+   structure version, **never** "lineage head". Otherwise (stamp **≤ head**) reconcile the hidden-mode footprint — but
    first **infer this deployment's OWN visibility from its git state** (NOT from whether the machine-global
    excludes list these paths — another repo on the host may have added them): if `AGENTS.md` (or
    `docs/ai/`) is **tracked / committed** → **VISIBLE** → do nothing (never write `.git/info/exclude`);
@@ -162,16 +169,32 @@ Fill strategy:
    **untracked AND not ignored** → **AMBIGUOUS** → **ASK** the user before writing. This visibility check
    runs on **every** in-range upgrade, even at head — it is not gated by the stamp delta, but it is gated
    **behind** the never-downgrade STOP above. **Also stamp-independent (same gate, before the equal-head
-   short-circuit): ensure `docs/ai/orchestration.json`** — **create it from
-   `${CLAUDE_SKILL_DIR}/references/templates/orchestration.json` if missing**, **preserve it byte-for-byte
-   if it already exists** (a user may have edited it; never clobber it). The shipped template's `_README`
-   already frames the config as agent-writable (set it with the `set-recipe` writer) and still
-   hand-editable. (Refreshing that note in place on an existing file is the **composition root's** job on
-   its own reconcile — this substrate is standalone and only seeds-or-preserves; it owns no cross-package
-   refresh helper.) This is why an equal-head (`1.3.0`) deployment still gains the config seed **without a
-   lineage-head bump or a migration file** (the stamp-independent-reconcile precedent — like the pointer
-   slots + the hidden-mode footprint). **Then**, if the stamp **equals** the head → report "up to date"
-   (plus any footprint move / config seed just made) and stop.
+   short-circuit): ensure BOTH seeded `.json` configs** — for `docs/ai/orchestration.json` AND
+   `docs/ai/gates.json`, **create the file from its
+   `${CLAUDE_SKILL_DIR}/references/templates/` template if missing**, **preserve it byte-for-byte
+   if it already exists** (a user may have edited it; never clobber it). The shipped
+   `orchestration.json` template's `_README` already frames that config as agent-writable (set it
+   with the `set-recipe` writer) and still hand-editable; `gates.json` is the project's own gate
+   declaration (what to verify — consumed by the composition root's gate runner). (Refreshing the
+   orchestration `_README` note in place on an existing file is the **composition root's** job on
+   its own reconcile — this substrate is standalone and only seeds-or-preserves; it owns no
+   cross-package refresh helper. The gates declaration gets no note-refresh at all — authored
+   content, seed-or-preserve only.) This is why an equal-head (`1.3.0`) deployment still gains the
+   config seeds **without a lineage-head bump or a migration file** (the
+   stamp-independent-reconcile precedent — like the pointer slots + the hidden-mode footprint).
+   **Same gate, also stamp-independent: ensure the ADR-cascade enforcement pair** — copy
+   `archive-decisions.mjs` + `archive-decisions.test.mjs` from
+   `${CLAUDE_SKILL_DIR}/references/scripts/` into the project's `scripts/` **if missing**
+   (preserve an existing file byte-for-byte; skip on a No-Node project). The deployed pre-commit
+   hook gains its `archive-decisions.mjs --check` line only when the hook is next refreshed via
+   `node scripts/install-git-hooks.mjs`; an old hook without the line stays consistent-safe (the
+   decisions gate is simply not enforced yet — never a broken hook). **Then**, if the stamp **equals** the head → the substrate is
+   current (no structure migration is due), and stop after reporting. Report **in the user's
+   conversational language**: if step 2's reconcile just **changed something** (a footprint move /
+   config seed), say **what changed** in plain terms and ask before committing; if **nothing changed at
+   all**, say their **settings are already current — no update is required**. Either way, show **no**
+   structure number, stamp filename, or internal versioning vocabulary on this happy-path exit — the
+   number is inert here and belongs to *Version disclosure* (below).
 3. Show the relevant `${CLAUDE_SKILL_DIR}/CHANGELOG.md` context (entries newer than the stamp).
 4. Apply `${CLAUDE_SKILL_DIR}/migrations/<version>-<slug>.md` in **semver order**, only those
    newer than the stamp. Migrations are **idempotent**.
@@ -186,9 +209,37 @@ Fill strategy:
    gracefully **no-op** on that slot (adding a slot to already-deployed files is the composition
    root's reconcile, not this substrate's job). On any malformed marker state (single, reversed,
    nested, or duplicate pair), **no-op with an error** — never edit.
-7. **Re-stamp** `docs/ai/.memory-version` to the lineage head (atomic write). Report changes;
-   **ask before committing** — **except in delegated mode** (see the *Delegated mode* note above),
-   where the composition root owns the single gate and this step raises none.
+7. **Re-stamp** `docs/ai/.memory-version` to the lineage head (atomic write — mechanics unchanged).
+   Report changes **in plain human terms** (which parts of the deployment are now different);
+   **omit the raw structure number**, and do not recite the two-axes note here (it belongs to
+   *Version disclosure*). **Ask before committing** — **except in delegated mode** (see the *Delegated
+   mode* note above), where the composition root owns the single gate and this step raises none.
+
+---
+
+## Version disclosure — the `docs/ai` structure version, on demand only
+
+The deployment carries an internal **`docs/ai` structure version** in `.memory-version` (the
+`LINEAGE_HEAD` — the number `upgrade` compares the stamp against to decide whether a migration is due).
+It is un-actionable in the happy path and reads as smaller than this package's npm version, so the
+happy path **hides** it. This substrate has **no status mode** (unlike the family composition root), so
+the number surfaces in exactly **two** places, and nowhere else:
+1. the **never-downgrade STOP** (*Mode: upgrade* step 2) — the stamp is ahead of what this substrate
+   knows, so the number IS the message;
+2. when the **user explicitly asks** about versions — a **read-only** answer: read `.memory-version`
+   and state it plainly (with the two-axes note). This adds **no mode** and **writes nothing**.
+
+When you show it, **name what it versions — "the `docs/ai` structure version"** (render that meaning in
+the user's conversational language) — **never** "lineage head" or any raw internal token. Pair it with
+**one plain-language line** telling the two axes apart, on demand only:
+
+> the number your project carries versions its `docs/ai` **structure**; the (usually larger) number on
+> npm is this package's **own version** — the two advance independently, so a bigger package number is
+> **not** a newer deployment.
+
+**Never** print this two-axes line on a successful equal-head exit — only at the STOP or on an explicit
+ask. (This is the one intended kit↔memory asymmetry: the kit hosts the number in its `status` mode; the
+memory substrate has none, so it relies on the STOP + the explicit ask — never invent a status mode.)
 
 ---
 

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-memory",
   "kind": "memory-substrate",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "provides": ["context"],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Portable, cross-agent memory substrate for AI coding agents — an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement, deployable standalone or as part of the agent-workflow family. The memory layer of the agent-workflow family.",
   "keywords": [
     "ai-agents",

package/references/scripts/archive-decisions.mjs

@@ -0,0 +1,424 @@
+#!/usr/bin/env node
+// Three-tier cascade archive for docs/ai/decisions.md (ADRs) — the archive-changelog.mjs sibling.
+//
+// HOT  (docs/ai/decisions.md)                      — the active ADR set (newest at the bottom)
+// WARM (docs/ai/history/decisions-archive.md)      — stable/superseded ADRs rotated out of HOT
+// COLD (docs/ai/history/decisions-archive-early.md) — the earliest ADRs, rolled out of WARM
+//
+// Caps are read from each file's OWN frontmatter `maxLines`. The cascade is CHAINED: rolling
+// HOT→WARM when WARM is near its cap first rolls WARM→COLD to make headroom. Whole entries move,
+// oldest (lowest AD id, top of file) first; an entry's lines move verbatim.
+//
+// Modes:
+//   (default)   rotate, mutate files in place (only when something is over cap)
+//   --dry-run   print the planned move-set, change nothing
+//   --check     report per-tier lines/cap; exit 1 if any tier is over its cap
+//   --today=YYYY-MM-DD  pin the lastUpdated stamp (tests / reproducible runs)
+//
+// FAIL-LOUD invariants (the Issue-009 lesson — never silently glue an entry to the previous body):
+//   • every `## ` heading in every tier MUST parse canonically as `## AD-0NN — <title>` — a
+//     malformed heading is exit 1 naming the file + line, never a silent merge;
+//   • ADR ids must be strictly ascending within a tier and unique across tiers;
+//   • a COLD tier at its cap — or a roll that would not fit COLD's remaining headroom — fails
+//     LOUD **before any write** (a cap raise / a new COLD file is a maintainer/agent decision;
+//     this script only moves entries);
+//   • conservation is self-verified before writing: the multiset of AD ids across all three
+//     tiers and every entry's line count are unchanged by the plan.
+//
+// DELIBERATE divergence from the siblings: on a project WITHOUT docs/ai/decisions.md, `--check`
+// reports the absence and exits 0 — the deployed pre-commit hook must never block a commit over
+// an absent ADR substrate. (archive-changelog.mjs reads its source unconditionally and crashes
+// ENOENT on an absent file; this script states the skip instead.)
+//
+// Cap accounting is on the REAL on-disk line count (what the docs cap-validator counts), never
+// on a normalized render — a template-shaped file with `---` separators between entries must not
+// false-green near its cap. A write NORMALIZES formatting (entries joined by one blank line;
+// separators dropped), so when a tier is over cap on raw lines but already fits after
+// normalization, the rotation performs a NORMALIZE-ONLY rewrite (zero entry moves, stated).
+//
+// Dependency-free, Node >= 18. Deployed into a consumer's scripts/ like its siblings.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_ROOT = resolve(__dirname, '..');
+
+export const HOT_REL = 'docs/ai/decisions.md';
+export const WARM_REL = 'docs/ai/history/decisions-archive.md';
+export const COLD_REL = 'docs/ai/history/decisions-archive-early.md';
+
+const DEFAULT_WARM_CAP = 500;
+const DEFAULT_COLD_CAP = 400;
+
+export const HEADING_RE = /^## AD-(\d{3}) — (.+)$/;
+const ANY_H2_RE = /^## /;
+const FRONTMATTER_RE = /^(---\n[\s\S]*?\n---\n)/;
+
+export const fail = (exitCode, message) => Object.assign(new Error(message), { exitCode });
+
+// ── parsing (strict; malformed headings are LOUD) ─────────────────────────────────────
+
+const stripTrailingSeparators = (blockLines) => {
+  const lines = [...blockLines];
+  while (lines.length > 0 && (lines[lines.length - 1].trim() === '' || lines[lines.length - 1].trim() === '---')) {
+    lines.pop();
+  }
+  return lines;
+};
+
+// Parse one tier's text → { frontmatter, cap, preamble, entries }. Every `## ` line must be a
+// canonical AD heading — anything else in any tier is exit 1 naming file:line (Issue-009).
+export const parseDecisionsText = (text, label) => {
+  const fmMatch = text.match(FRONTMATTER_RE);
+  const frontmatter = fmMatch ? fmMatch[1] : '';
+  const fmLines = frontmatter === '' ? 0 : frontmatter.split('\n').length - 1;
+  const rest = text.slice(frontmatter.length);
+  const lines = rest.split('\n');
+
+  const startIdxs = [];
+  lines.forEach((line, i) => {
+    if (!ANY_H2_RE.test(line)) return;
+    if (!HEADING_RE.test(line)) {
+      throw fail(
+        1,
+        `${label}:${fmLines + i + 1}: non-canonical H2 heading "${line}" — every "## " heading must be \`## AD-0NN — <title>\` (never silently glued to the previous entry; fix the heading, then re-run)`,
+      );
+    }
+    startIdxs.push(i);
+  });
+
+  const preambleEnd = startIdxs.length > 0 ? startIdxs[0] : lines.length;
+  const preamble = lines.slice(0, preambleEnd).join('\n').trim();
+
+  const entries = startIdxs.map((idx, i) => {
+    const end = i + 1 < startIdxs.length ? startIdxs[i + 1] : lines.length;
+    const blockLines = stripTrailingSeparators(lines.slice(idx, end));
+    const m = HEADING_RE.exec(lines[idx]);
+    return {
+      id: m[1],
+      idNum: Number(m[1]),
+      title: m[2],
+      block: blockLines.join('\n'),
+      lineCount: blockLines.length,
+    };
+  });
+
+  for (let i = 1; i < entries.length; i += 1) {
+    if (entries[i].idNum <= entries[i - 1].idNum) {
+      throw fail(
+        1,
+        `${label}: AD-${entries[i].id} appears after AD-${entries[i - 1].id} — ids must be strictly ascending within a tier (oldest at the top); refusing to rotate a disordered file`,
+      );
+    }
+  }
+
+  const capMatch = frontmatter.match(/^maxLines:\s*(\d+)\s*$/m);
+  return { frontmatter, cap: capMatch ? Number(capMatch[1]) : null, preamble, entries };
+};
+
+// ── tier IO ───────────────────────────────────────────────────────────────────────────
+
+const CREATED_FRONTMATTER = (cap, today) =>
+  `---\ntype: history\nlastUpdated: ${today}\nscope: permanent\nstaleAfter: never\nowner: none\nmaxLines: ${cap}\n---\n`;
+
+const CREATED_WARM_PREAMBLE = [
+  '# Architecture Decision Records — Archive (AD-000 … AD-000)',
+  '',
+  '> Stable ADRs rotated out of the active [`decisions.md`](../decisions.md) per the 3-tier archive',
+  '> discipline. The earliest entries roll further to the COLD',
+  '> [`decisions-archive-early.md`](./decisions-archive-early.md). Cross-links (`[[AD-XXX]]`) resolve',
+  '> by id across all three decision files.',
+].join('\n');
+
+const CREATED_COLD_PREAMBLE = [
+  '# Architecture Decision Records — Early Archive (AD-000 … AD-000)',
+  '',
+  '> The earliest foundational ADRs, rolled out of [`decisions-archive.md`](./decisions-archive.md) (WARM)',
+  '> into this COLD tier when the WARM archive neared its cap. Cross-links (`[[AD-XXX]]`) still resolve',
+  '> by id across all three decision files.',
+].join('\n');
+
+export const loadTiers = (root, today) => {
+  const load = (rel, { createdCap, createdPreamble }) => {
+    const path = resolve(root, rel);
+    if (existsSync(path)) {
+      const raw = readFileSync(path, 'utf8');
+      const parsed = parseDecisionsText(raw, rel);
+      if (parsed.cap === null) throw fail(1, `${rel}: frontmatter carries no maxLines cap — refusing to rotate against an unknown budget`);
+      return { rel, path, exists: true, rawLines: lineCountOf(raw), ...parsed };
+    }
+    return {
+      rel,
+      path,
+      exists: false,
+      rawLines: 0,
+      frontmatter: CREATED_FRONTMATTER(createdCap, today),
+      cap: createdCap,
+      preamble: createdPreamble,
+      entries: [],
+    };
+  };
+  const hot = load(HOT_REL, { createdCap: 0, createdPreamble: '' }); // HOT is never created here
+  const warm = load(WARM_REL, { createdCap: DEFAULT_WARM_CAP, createdPreamble: CREATED_WARM_PREAMBLE });
+  const cold = load(COLD_REL, { createdCap: DEFAULT_COLD_CAP, createdPreamble: CREATED_COLD_PREAMBLE });
+
+  const seen = new Map();
+  for (const tier of [hot, warm, cold]) {
+    for (const entry of tier.entries) {
+      if (seen.has(entry.id)) throw fail(1, `AD-${entry.id} appears in both ${seen.get(entry.id)} and ${tier.rel} — duplicate id across tiers; refusing to rotate`);
+      seen.set(entry.id, tier.rel);
+    }
+  }
+  return { hot, warm, cold };
+};
+
+// ── rendering ─────────────────────────────────────────────────────────────────────────
+
+export const renderTier = (tier, entries) => {
+  const blocks = entries.map((entry) => entry.block).join('\n\n');
+  const body = [tier.preamble, blocks].filter((part) => part !== '').join('\n\n');
+  return `${tier.frontmatter}\n${body}\n`;
+};
+
+export const lineCountOf = (text) => text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
+
+// ── the deterministic move plan (same input → same move-set; nothing written here) ────
+
+export const planRotation = ({ hot, warm, cold }) => {
+  const hotEntries = [...hot.entries];
+  const warmEntries = [...warm.entries];
+  const coldEntries = [...cold.entries];
+  const moves = { hotToWarm: [], warmToCold: [] };
+
+  const linesOf = (tier, entries) => lineCountOf(renderTier(tier, entries));
+
+  const rollWarmToCold = () => {
+    if (warmEntries.length === 0) {
+      throw fail(1, `${WARM_REL} exceeds its cap with no entries left to roll — its preamble alone is over budget; fix the file by hand`);
+    }
+    const moved = warmEntries[0];
+    const next = [...coldEntries, moved];
+    if (linesOf(cold, next) > cold.cap) {
+      throw fail(
+        1,
+        `refusing BEFORE any write: rolling AD-${moved.id} (${moved.lineCount} lines) into ${COLD_REL} would exceed its cap ` +
+          `(${linesOf(cold, coldEntries)}/${cold.cap} now, ${linesOf(cold, next)} after) — the COLD tier is exhausted; ` +
+          'a cap raise or a new COLD file is a maintainer/agent decision, this script only moves entries',
+      );
+    }
+    warmEntries.shift();
+    coldEntries.push(moved);
+    moves.warmToCold.push(moved.id);
+  };
+
+  const ensureWarmFits = () => {
+    while (linesOf(warm, warmEntries) > warm.cap) rollWarmToCold();
+  };
+
+  ensureWarmFits(); // a pre-existing WARM overflow chains down first
+  while (linesOf(hot, hotEntries) > hot.cap) {
+    if (hotEntries.length <= 1) {
+      throw fail(1, `${HOT_REL} exceeds its cap but only one entry remains — the newest entry alone is over budget; trim it or raise the cap (maintainer decision)`);
+    }
+    const moved = hotEntries.shift();
+    warmEntries.push(moved);
+    moves.hotToWarm.push(moved.id);
+    ensureWarmFits();
+  }
+
+  return { moves, hotEntries, warmEntries, coldEntries };
+};
+
+// Conservation self-verify: the multiset of (id → lineCount) across all tiers is unchanged.
+export const verifyConservation = (before, after) => {
+  const snapshot = (tiers) =>
+    tiers
+      .flat()
+      .map((entry) => `${entry.id}:${entry.lineCount}`)
+      .sort()
+      .join('|');
+  const beforeKey = snapshot(before);
+  const afterKey = snapshot(after);
+  if (beforeKey !== afterKey) {
+    throw fail(1, `internal conservation violation — the planned move-set would change the ADR set (before ${beforeKey.slice(0, 120)}… vs after ${afterKey.slice(0, 120)}…); refusing to write`);
+  }
+};
+
+// ── preamble range-token maintenance ──────────────────────────────────────────────────
+// The hand-authored preambles carry range tokens ("AD-014 … AD-023", "(AD-024 onward)",
+// "from **AD-024**"). After a rotation those would silently lie, so the recognizable tokens are
+// updated in place; a preamble without them (a consumer's own wording) is left untouched.
+
+const RANGE_TOKEN_RE = /AD-\d{3} … AD-\d{3}/g;
+
+const formatRange = (entries) => `AD-${entries[0].id} … AD-${entries[entries.length - 1].id}`;
+
+export const updateRangeTokens = (preamble, kind, { hotEntries, warmEntries, coldEntries }) => {
+  // Token order per tier file: HOT + WARM preambles mention the WARM range then the COLD range;
+  // COLD mentions only its own. This ASSUMES the hand-authored order (WARM before COLD) — the
+  // shape all three files here carry. A maintainer who rewrites a preamble with the ranges
+  // swapped would get the bounds injected into the wrong slots; if you reorder the ranges,
+  // update this sequence too (a preamble WITHOUT the tokens is simply left untouched).
+  const sequence = kind === 'cold' ? [coldEntries] : [warmEntries, coldEntries];
+  let occurrence = 0;
+  let out = preamble.replace(RANGE_TOKEN_RE, (token) => {
+    const tierEntries = sequence[Math.min(occurrence, sequence.length - 1)];
+    occurrence += 1;
+    return tierEntries.length > 0 ? formatRange(tierEntries) : token;
+  });
+  if (hotEntries.length > 0) {
+    out = out.replace(/\(AD-\d{3} onward\)/, `(AD-${hotEntries[0].id} onward)`);
+    out = out.replace(/from \*\*AD-\d{3}\*\*/, `from **AD-${hotEntries[0].id}**`);
+  }
+  return out;
+};
+
+const stampLastUpdated = (frontmatter, today) => frontmatter.replace(/^lastUpdated: .*$/m, `lastUpdated: ${today}`);
+
+// ── CLI ───────────────────────────────────────────────────────────────────────────────
+
+const USAGE = 'Usage: archive-decisions.mjs [--dry-run|--check] [--today=YYYY-MM-DD]';
+
+const parseArgs = (argv) => {
+  const flags = { dryRun: false, check: false, help: false };
+  let today = null;
+  for (const arg of argv) {
+    if (arg === '--dry-run') flags.dryRun = true;
+    else if (arg === '--check') flags.check = true;
+    else if (arg === '--help' || arg === '-h') flags.help = true;
+    else if (arg.startsWith('--today=')) today = arg.slice('--today='.length);
+    else throw fail(2, `Unknown argument: ${arg}\n${USAGE}`);
+  }
+  return { flags, today };
+};
+
+export const runCli = (argv, deps = {}) => {
+  const { root = DEFAULT_ROOT, log = console.log, logError = console.error } = deps;
+  try {
+    const { flags, today: todayOpt } = parseArgs(argv);
+    if (flags.help) {
+      log(USAGE);
+      return 0;
+    }
+    const today = todayOpt ?? new Date().toISOString().slice(0, 10);
+
+    // DELIBERATE divergence from archive-changelog.mjs (which crashes ENOENT): an absent ADR
+    // substrate is a STATED SKIP on --check — the deployed pre-commit hook must never block a
+    // commit over a decisions.md the project simply does not keep.
+    if (!existsSync(resolve(root, HOT_REL))) {
+      if (flags.check) {
+        log(`[archive-decisions] SKIP — ${HOT_REL} not found (this project keeps no ADR file); nothing to check.`);
+        return 0;
+      }
+      logError(`[archive-decisions] ${HOT_REL} not found — nothing to rotate.`);
+      return 1;
+    }
+
+    const tiers = loadTiers(root, today);
+    const usage = (tier, entries = tier.entries) => `${lineCountOf(renderTier(tier, entries))}/${tier.cap}`;
+    // Cap checks count the REAL on-disk lines (what the docs cap-validator counts) — a normalized
+    // render undercounts a template-shaped file with `---` separators and would false-green.
+    const rawUsage = (tier) => (tier.exists ? tier.rawLines : lineCountOf(renderTier(tier, tier.entries)));
+
+    if (flags.check) {
+      const over = [];
+      for (const tier of [tiers.hot, tiers.warm, tiers.cold]) {
+        const lines = rawUsage(tier);
+        log(`[archive-decisions] ${tier.rel}: ${lines}/${tier.cap}${tier.exists ? '' : ' (absent — would be created on rotation)'}`);
+        if (lines > tier.cap) over.push(tier);
+      }
+      if (over.length > 0) {
+        for (const tier of over) {
+          const recovery =
+            tier.rel === COLD_REL
+              ? 'the COLD tier is exhausted — a cap raise or a new COLD file is a maintainer/agent decision'
+              : 'run `node scripts/archive-decisions.mjs` to rotate';
+          logError(`[archive-decisions] FAIL: ${tier.rel} is over its cap — ${recovery}.`);
+        }
+        return 1;
+      }
+      log('[archive-decisions] OK — every tier is within its cap.');
+      return 0;
+    }
+
+    const plan = planRotation(tiers);
+    // A tier over its cap on RAW lines needs a write even with zero entry moves — normalization
+    // (the canonical rendered form) alone brings it back under (the moves loop already ensured
+    // the RENDERED result fits; if it did not, moves would be non-empty).
+    const normalizeOnly = [tiers.hot, tiers.warm, tiers.cold].filter((tier) => tier.exists && tier.rawLines > tier.cap);
+    if (plan.moves.hotToWarm.length === 0 && plan.moves.warmToCold.length === 0 && normalizeOnly.length === 0) {
+      log(`[archive-decisions] nothing to rotate — HOT ${usage(tiers.hot)}, WARM ${usage(tiers.warm)}, COLD ${usage(tiers.cold)}.`);
+      return 0;
+    }
+    verifyConservation(
+      [tiers.hot.entries, tiers.warm.entries, tiers.cold.entries],
+      [plan.hotEntries, plan.warmEntries, plan.coldEntries],
+    );
+
+    const summary = {
+      hotToWarm: plan.moves.hotToWarm.map((id) => `AD-${id}`),
+      warmToCold: plan.moves.warmToCold.map((id) => `AD-${id}`),
+      normalizeOnly: normalizeOnly.map((tier) => tier.rel),
+      after: {
+        hot: usage(tiers.hot, plan.hotEntries),
+        warm: usage(tiers.warm, plan.warmEntries),
+        cold: usage(tiers.cold, plan.coldEntries),
+      },
+    };
+
+    if (flags.dryRun) {
+      log('[archive-decisions] DRY-RUN — no files will be changed.');
+      log(JSON.stringify(summary, null, 2));
+      return 0;
+    }
+
+    const ranges = { hotEntries: plan.hotEntries, warmEntries: plan.warmEntries, coldEntries: plan.coldEntries };
+    const writes = [
+      { tier: tiers.hot, entries: plan.hotEntries, kind: 'hot' },
+      { tier: tiers.warm, entries: plan.warmEntries, kind: 'warm' },
+      { tier: tiers.cold, entries: plan.coldEntries, kind: 'cold' },
+    ];
+    // A rewrite must never claim success while a tier is STILL over its cap — normalization is
+    // not a licence: if the planned rendered result exceeds the budget (a genuinely exhausted
+    // COLD is the reachable case — the move loops already bound HOT and WARM), fail LOUD before
+    // any write.
+    for (const { tier, entries } of writes) {
+      const plannedLines = lineCountOf(renderTier(tier, entries));
+      if (plannedLines > tier.cap) {
+        const recovery =
+          tier.rel === COLD_REL
+            ? 'the COLD tier is exhausted — a cap raise or a new COLD file is a maintainer/agent decision'
+            : 'raise the cap or trim the offending entries (maintainer decision)';
+        throw fail(1, `refusing BEFORE any write: ${tier.rel} would still be over its cap after rotation (${plannedLines}/${tier.cap}) — ${recovery}`);
+      }
+    }
+    for (const { tier, entries, kind } of writes) {
+      // Never materialize an ABSENT tier that still has nothing to hold — a normalize-only
+      // rewrite of HOT must not seed empty WARM/COLD files into a project that never rotated.
+      if (!tier.exists && entries.length === 0) continue;
+      const updated = {
+        ...tier,
+        frontmatter: stampLastUpdated(tier.frontmatter, today),
+        preamble: updateRangeTokens(tier.preamble, kind, ranges),
+      };
+      mkdirSync(dirname(tier.path), { recursive: true });
+      writeFileSync(tier.path, renderTier(updated, entries), 'utf8');
+    }
+    log('[archive-decisions] rotated:');
+    log(`  HOT→WARM: ${summary.hotToWarm.join(', ') || '(none)'}`);
+    log(`  WARM→COLD: ${summary.warmToCold.join(', ') || '(none)'}`);
+    if (summary.normalizeOnly.length > 0 && summary.hotToWarm.length === 0 && summary.warmToCold.length === 0) {
+      log(`  normalize-only rewrite (over cap on raw lines, no entry moves): ${summary.normalizeOnly.join(', ')}`);
+    }
+    log(`  now: HOT ${summary.after.hot} · WARM ${summary.after.warm} · COLD ${summary.after.cold}`);
+    return 0;
+  } catch (err) {
+    logError(`[archive-decisions] ${err.message}`);
+    return err.exitCode ?? 1;
+  }
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) process.exitCode = runCli(process.argv.slice(2));

package/references/scripts/archive-decisions.test.mjs

@@ -0,0 +1,365 @@
+import { describe, it, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  HOT_REL,
+  WARM_REL,
+  COLD_REL,
+  parseDecisionsText,
+  loadTiers,
+  renderTier,
+  lineCountOf,
+  planRotation,
+  updateRangeTokens,
+  runCli,
+} from './archive-decisions.mjs';
+
+// Hermetic by design: this test ships as deploy payload and runs inside CONSUMER repos via the
+// pre-commit `node --test scripts/*.test.mjs` — it must never read the host repo's docs/ai.
+
+const tempDirs = [];
+const makeRoot = () => {
+  const dir = mkdtempSync(join(tmpdir(), 'archive-decisions-'));
+  tempDirs.push(dir);
+  return dir;
+};
+afterEach(() => {
+  while (tempDirs.length) rmSync(tempDirs.pop(), { recursive: true, force: true });
+});
+
+const fm = (cap) =>
+  `---\ntype: reference\nlastUpdated: 2026-01-01\nscope: permanent\nstaleAfter: never\nowner: none\nmaxLines: ${cap}\n---\n`;
+
+// One canonical entry block: 3 fixed lines + extraLines body lines.
+const entryBlock = (id, extraLines = 2) =>
+  [`## AD-${id} — Decision ${id}`, '', '**Date:** 2026-01-01', ...Array.from({ length: extraLines }, (_, i) => `body ${i + 1} of AD-${id}`)].join('\n');
+
+const tierText = (cap, preamble, blocks) => `${fm(cap)}\n${preamble}\n\n${blocks.join('\n\n')}\n`;
+
+const HOT_PREAMBLE = [
+  '# Architecture Decision Records (ADRs)',
+  '',
+  '> Newest at the bottom.',
+  '>',
+  '> **Archive:** the stable ADRs **AD-003 … AD-004** now live in [`history/decisions-archive.md`](./history/decisions-archive.md) (the earliest **AD-001 … AD-002** rolled further to the COLD [`history/decisions-archive-early.md`](./history/decisions-archive-early.md)); this file carries the active set (AD-005 onward).',
+].join('\n');
+
+const WARM_PREAMBLE = '# ADR Archive (AD-003 … AD-004)\n\n> WARM tier. The earliest (AD-001 … AD-002) are COLD.';
+const COLD_PREAMBLE = '# ADR Early Archive (AD-001 … AD-002)\n\n> COLD tier.';
+
+// Seed a project: HOT with `hotIds`, WARM with `warmIds`, COLD with `coldIds`; caps computed
+// from the measured rendered size + a delta (so fixtures stay robust to formatting arithmetic).
+const seedProject = (root, { hotIds, warmIds, coldIds, hotCapDelta = 100, warmCapDelta = 100, coldCapDelta = 100 }) => {
+  mkdirSync(join(root, 'docs', 'ai', 'history'), { recursive: true });
+  const write = (rel, preamble, ids, capDelta) => {
+    const blocks = ids.map((id) => entryBlock(id));
+    const probe = tierText(999, preamble, blocks);
+    const cap = lineCountOf(probe) + capDelta;
+    writeFileSync(join(root, rel), tierText(cap, preamble, blocks));
+    return cap;
+  };
+  return {
+    hotCap: write(HOT_REL, HOT_PREAMBLE, hotIds, hotCapDelta),
+    warmCap: write(WARM_REL, WARM_PREAMBLE, warmIds, warmCapDelta),
+    coldCap: write(COLD_REL, COLD_PREAMBLE, coldIds, coldCapDelta),
+  };
+};
+
+const run = (argv, root) => {
+  const out = [];
+  const err = [];
+  const code = runCli(argv, { root, log: (l) => out.push(l), logError: (l) => err.push(l) });
+  return { code, out, err, text: out.join('\n'), errText: err.join('\n') };
+};
+
+const idsIn = (root, rel) => parseDecisionsText(readFileSync(join(root, rel), 'utf8'), rel).entries.map((e) => e.id);
+
+// ── parsing: strict canonical headings (the Issue-009 lesson) ─────────────────────────
+
+describe('parseDecisionsText — fail-loud on non-canonical headings', () => {
+  it('parses canonical entries with ids, titles, and per-entry line counts', () => {
+    const parsed = parseDecisionsText(tierText(500, HOT_PREAMBLE, [entryBlock('005'), entryBlock('006', 4)]), 'x');
+    assert.deepEqual(parsed.entries.map((e) => e.id), ['005', '006']);
+    assert.equal(parsed.entries[0].lineCount, 5);
+    assert.equal(parsed.entries[1].lineCount, 7);
+    assert.equal(parsed.cap, 500);
+  });
+
+  const badHeadings = [
+    ['a hyphen instead of the em-dash', '## AD-024 - Title'],
+    ['a 2-digit id', '## AD-24 — Title'],
+    ['a missing title', '## AD-024 — '],
+    ['an unrelated H2', '## Notes'],
+  ];
+  for (const [name, heading] of badHeadings) {
+    it(`rejects ${name} naming file:line — never a silent merge`, () => {
+      const text = `${fm(500)}\n# T\n\n${entryBlock('001')}\n\n${heading}\nbody\n`;
+      assert.throws(() => parseDecisionsText(text, 'docs/ai/decisions.md'), (e) => {
+        assert.equal(e.exitCode, 1);
+        assert.match(e.message, /docs\/ai\/decisions\.md:\d+/);
+        assert.match(e.message, /non-canonical H2/);
+        return true;
+      });
+    });
+  }
+
+  it('rejects disordered ids (oldest must be at the top)', () => {
+    const text = tierText(500, '# T', [entryBlock('007'), entryBlock('005')]);
+    assert.throws(() => parseDecisionsText(text, 'x'), /strictly ascending/);
+  });
+});
+
+describe('loadTiers — cross-tier integrity', () => {
+  it('rejects a duplicate id across tiers', () => {
+    const root = makeRoot();
+    seedProject(root, { hotIds: ['005'], warmIds: ['005'], coldIds: [] });
+    assert.throws(() => loadTiers(root, '2026-01-02'), /duplicate id across tiers/);
+  });
+});
+
+// ── the cascade ───────────────────────────────────────────────────────────────────────
+
+describe('rotation — simple HOT→WARM roll', () => {
+  it('rolls the OLDEST whole entries until HOT fits; ids + line counts conserved', () => {
+    const root = makeRoot();
+    seedProject(root, { hotIds: ['005', '006', '007', '008'], warmIds: ['003', '004'], coldIds: ['001', '002'], hotCapDelta: -1 });
+    const before = loadTiers(root, '2026-01-02');
+    const allBefore = [before.hot, before.warm, before.cold].flatMap((t) => t.entries.map((e) => `${e.id}:${e.lineCount}`)).sort();
+
+    const { code, text } = run(['--today=2026-01-02'], root);
+    assert.equal(code, 0, text);
+    assert.deepEqual(idsIn(root, HOT_REL), ['006', '007', '008'], 'the oldest HOT entry rolled');
+    assert.deepEqual(idsIn(root, WARM_REL), ['003', '004', '005'], 'appended to the WARM end');
+    assert.deepEqual(idsIn(root, COLD_REL), ['001', '002'], 'COLD untouched');
+
+    const after = loadTiers(root, '2026-01-02');
+    const allAfter = [after.hot, after.warm, after.cold].flatMap((t) => t.entries.map((e) => `${e.id}:${e.lineCount}`)).sort();
+    assert.deepEqual(allAfter, allBefore, 'id multiset + per-entry line counts conserved');
+    assert.ok(lineCountOf(renderTier(after.hot, after.hot.entries)) <= after.hot.cap, 'HOT now fits its cap');
+  });
+
+  it('a tree already under cap is a no-op (nothing written)', () => {
+    const root = makeRoot();
+    seedProject(root, { hotIds: ['005'], warmIds: ['003'], coldIds: ['001'] });
+    const bytesBefore = readFileSync(join(root, HOT_REL), 'utf8');
+    const { code, text } = run([], root);
+    assert.equal(code, 0);
+    assert.match(text, /nothing to rotate/);
+    assert.equal(readFileSync(join(root, HOT_REL), 'utf8'), bytesBefore);
+  });
+});
+
+describe('rotation — the CHAINED roll (WARM near cap rolls WARM→COLD first)', () => {
+  it('an incoming HOT entry that would overflow WARM pushes the oldest WARM entry to COLD', () => {
+    const root = makeRoot();
+    seedProject(root, {
+      hotIds: ['005', '006', '007'],
+      warmIds: ['003', '004'],
+      coldIds: ['001', '002'],
+      hotCapDelta: -1, // force one HOT roll
+      warmCapDelta: 3, // the incoming 6-line append does NOT fit → chain
+    });
+    const { code } = run(['--today=2026-01-02'], root);
+    assert.equal(code, 0);
+    assert.deepEqual(idsIn(root, HOT_REL), ['006', '007']);
+    assert.deepEqual(idsIn(root, WARM_REL), ['004', '005'], 'AD-003 chained out, AD-005 appended');
+    assert.deepEqual(idsIn(root, COLD_REL), ['001', '002', '003'], 'the chained entry landed in COLD');
+  });
+});
+
+describe('rotation — COLD exhaustion fails LOUD before ANY write', () => {
+  it('a roll that does not fit COLD headroom leaves all three files byte-identical', () => {
+    const root = makeRoot();
+    seedProject(root, {
+      hotIds: ['005', '006', '007'],
+      warmIds: ['003', '004'],
+      coldIds: ['001', '002'],
+      hotCapDelta: -1, // force a HOT roll
+      warmCapDelta: 3, // force the chain into COLD
+      coldCapDelta: 3, // the chained 6-line entry does NOT fit COLD
+    });
+    const snapshot = () => [HOT_REL, WARM_REL, COLD_REL].map((rel) => readFileSync(join(root, rel), 'utf8'));
+    const before = snapshot();
+    const { code, errText } = run(['--today=2026-01-02'], root);
+    assert.equal(code, 1);
+    assert.match(errText, /refusing BEFORE any write/);
+    assert.match(errText, /maintainer\/agent decision/);
+    assert.deepEqual(snapshot(), before, 'no file changed on the refused plan');
+  });
+});
+
+describe('rotation — determinism + dry-run', () => {
+  it('the same input yields the same move-set (planRotation is pure)', () => {
+    const root = makeRoot();
+    seedProject(root, { hotIds: ['005', '006', '007', '008'], warmIds: ['003'], coldIds: ['001'], hotCapDelta: -1 });
+    const tiers = loadTiers(root, '2026-01-02');
+    const planA = planRotation(tiers);
+    const planB = planRotation(loadTiers(root, '2026-01-02'));
+    assert.deepEqual(planA.moves, planB.moves);
+  });
+
+  it('--dry-run prints the move-set and writes nothing', () => {
+    const root = makeRoot();
+    seedProject(root, { hotIds: ['005', '006'], warmIds: [], coldIds: [], hotCapDelta: -1 });
+    const before = readFileSync(join(root, HOT_REL), 'utf8');
+    const { code, text } = run(['--dry-run'], root);
+    assert.equal(code, 0);
+    assert.match(text, /DRY-RUN/);
+    assert.match(text, /AD-005/);
+    assert.equal(readFileSync(join(root, HOT_REL), 'utf8'), before);
+  });
+});
+
+describe('preamble range tokens', () => {
+  it('updates the recognizable range/onward tokens after a rotation', () => {
+    const root = makeRoot();
+    seedProject(root, { hotIds: ['005', '006', '007'], warmIds: ['003', '004'], coldIds: ['001', '002'], hotCapDelta: -1 });
+    const { code } = run(['--today=2026-01-02'], root);
+    assert.equal(code, 0);
+    const hotText = readFileSync(join(root, HOT_REL), 'utf8');
+    assert.match(hotText, /\*\*AD-003 … AD-005\*\*/, 'WARM range token updated in HOT');
+    assert.match(hotText, /\(AD-006 onward\)/, 'active-set token updated');
+    const warmText = readFileSync(join(root, WARM_REL), 'utf8');
+    assert.match(warmText, /AD-003 … AD-005/, 'WARM file H1 range updated');
+  });
+
+  it('a preamble without tokens is left untouched (consumer wording preserved)', () => {
+    const updated = updateRangeTokens('# My own ADR file\n\n> no tokens here', 'hot', {
+      hotEntries: [{ id: '010' }],
+      warmEntries: [{ id: '001' }, { id: '002' }],
+      coldEntries: [],
+    });
+    assert.equal(updated, '# My own ADR file\n\n> no tokens here');
+  });
+});
+
+// ── --check + the absent-substrate divergence ─────────────────────────────────────────
+
+describe('--check', () => {
+  it('all tiers within caps → exit 0 with a per-tier usage report', () => {
+    const root = makeRoot();
+    seedProject(root, { hotIds: ['005'], warmIds: ['003'], coldIds: ['001'] });
+    const { code, text } = run(['--check'], root);
+    assert.equal(code, 0);
+    assert.match(text, /decisions\.md: \d+\/\d+/);
+    assert.match(text, /OK — every tier is within its cap/);
+  });
+
+  it('an over-cap HOT → exit 1 naming the rotation recovery', () => {
+    const root = makeRoot();
+    seedProject(root, { hotIds: ['005', '006'], warmIds: [], coldIds: [], hotCapDelta: -1 });
+    const { code, errText } = run(['--check'], root);
+    assert.equal(code, 1);
+    assert.match(errText, /decisions\.md is over its cap/);
+    assert.match(errText, /archive-decisions\.mjs` to rotate/);
+  });
+
+  it('an over-cap COLD → exit 1 naming the maintainer decision (rotation cannot fix it)', () => {
+    const root = makeRoot();
+    seedProject(root, { hotIds: ['005'], warmIds: ['003'], coldIds: ['001', '002'], coldCapDelta: -1 });
+    const { code, errText } = run(['--check'], root);
+    assert.equal(code, 1);
+    assert.match(errText, /maintainer\/agent decision/);
+  });
+
+  it('ABSENT decisions.md → --check exits 0 with a STATED skip (deliberate divergence from archive-changelog)', () => {
+    const root = makeRoot();
+    mkdirSync(join(root, 'docs', 'ai'), { recursive: true });
+    const { code, text } = run(['--check'], root);
+    assert.equal(code, 0);
+    assert.match(text, /SKIP — docs\/ai\/decisions\.md not found/);
+  });
+
+  it('an absent decisions.md WITHOUT --check is still a loud non-zero (rotation has nothing to do)', () => {
+    const root = makeRoot();
+    mkdirSync(join(root, 'docs', 'ai'), { recursive: true });
+    const { code, errText } = run([], root);
+    assert.equal(code, 1);
+    assert.match(errText, /not found/);
+  });
+});
+
+describe('cap accounting is on RAW file lines (the template-shaped `---` separator case)', () => {
+  // A consumer file born from the shipped template joins entries with `\n\n---\n\n`. Normalized
+  // rendering drops those separator lines, so a render-based count would false-green a file the
+  // docs cap-validator (raw lines) fails. --check and the write trigger must count RAW lines.
+  const seedSeparatorShaped = (root, { capDelta }) => {
+    mkdirSync(join(root, 'docs', 'ai', 'history'), { recursive: true });
+    const blocks = [entryBlock('001'), entryBlock('002'), entryBlock('003')];
+    const body = blocks.join('\n\n---\n\n'); // the template separator shape
+    const probe = `${fm(999)}\n# ADRs\n\n${body}\n`;
+    const cap = lineCountOf(probe) + capDelta;
+    writeFileSync(join(root, HOT_REL), `${fm(cap)}\n# ADRs\n\n${body}\n`);
+    return { cap, rawLines: lineCountOf(probe) };
+  };
+
+  it('--check fails on raw-over-cap even when the normalized render would fit', () => {
+    const root = makeRoot();
+    // 3 separators × 2 lines = 6 lines the render drops; cap sits 2 under raw → render fits, raw does not.
+    seedSeparatorShaped(root, { capDelta: -2 });
+    const { code, errText } = run(['--check'], root);
+    assert.equal(code, 1, 'raw lines are what the docs cap-validator counts — never false-green');
+    assert.match(errText, /decisions\.md is over its cap/);
+  });
+
+  it('rotation performs a NORMALIZE-ONLY rewrite when raw is over cap but the render fits (no moves)', () => {
+    const root = makeRoot();
+    seedSeparatorShaped(root, { capDelta: -2 });
+    const { code, text } = run(['--today=2026-01-02'], root);
+    assert.equal(code, 0, text);
+    assert.match(text, /normalize-only rewrite/);
+    assert.match(text, /HOT→WARM: \(none\)/);
+    const after = parseDecisionsText(readFileSync(join(root, HOT_REL), 'utf8'), HOT_REL);
+    assert.deepEqual(after.entries.map((e) => e.id), ['001', '002', '003'], 'ids conserved, nothing moved');
+    const { code: recheck } = run(['--check'], root);
+    assert.equal(recheck, 0, 'the normalized file now fits its cap on raw lines');
+  });
+
+  it('a tier STILL over cap after the planned rewrite refuses BEFORE any write (a normalized rewrite is not a licence)', () => {
+    const root = makeRoot();
+    // COLD legitimately exceeds its cap (entries, not formatting): no move can fix it and a
+    // normalize-only rewrite would still be over budget — the run must refuse with files untouched.
+    seedProject(root, { hotIds: ['005'], warmIds: ['003'], coldIds: ['001', '002'], coldCapDelta: -3 });
+    const snapshot = () => [HOT_REL, WARM_REL, COLD_REL].map((rel) => readFileSync(join(root, rel), 'utf8'));
+    const before = snapshot();
+    const { code, errText } = run(['--today=2026-01-02'], root);
+    assert.equal(code, 1);
+    assert.match(errText, /would still be over its cap after rotation/);
+    assert.match(errText, /maintainer\/agent decision/);
+    assert.deepEqual(snapshot(), before, 'no file changed on the refused plan');
+  });
+
+  it('a normalize-only rewrite NEVER materializes absent WARM/COLD files (no premature archives)', () => {
+    const root = makeRoot();
+    seedSeparatorShaped(root, { capDelta: -2 }); // HOT only — no history files exist
+    const { code } = run(['--today=2026-01-02'], root);
+    assert.equal(code, 0);
+    assert.ok(!existsSync(join(root, WARM_REL)), 'an absent WARM with zero entries is not created');
+    assert.ok(!existsSync(join(root, COLD_REL)), 'an absent COLD with zero entries is not created');
+  });
+});
+
+describe('created tiers (a consumer with no history files yet)', () => {
+  it('rolling into an absent WARM creates it with frontmatter + preamble', () => {
+    const root = makeRoot();
+    mkdirSync(join(root, 'docs', 'ai'), { recursive: true });
+    const blocks = [entryBlock('001'), entryBlock('002')];
+    const probe = tierText(999, '# ADRs', blocks);
+    writeFileSync(join(root, HOT_REL), tierText(lineCountOf(probe) - 1, '# ADRs', blocks));
+    const { code } = run(['--today=2026-01-02'], root);
+    assert.equal(code, 0);
+    assert.ok(existsSync(join(root, WARM_REL)), 'WARM created');
+    const warm = parseDecisionsText(readFileSync(join(root, WARM_REL), 'utf8'), WARM_REL);
+    assert.deepEqual(warm.entries.map((e) => e.id), ['001']);
+    assert.equal(warm.cap, 500, 'created WARM carries the default cap');
+    assert.match(warm.preamble, /AD-001 … AD-001/, 'created preamble range filled');
+  });
+
+  it('usage errors are loud (exit 2)', () => {
+    const { code, errText } = run(['--frobnicate'], makeRoot());
+    assert.equal(code, 2);
+    assert.match(errText, /Unknown argument/);
+  });
+});

package/references/scripts/install-git-hooks.mjs

@@ -48,6 +48,7 @@ node scripts/check-docs-size.mjs
 node scripts/check-docs-size.mjs --check-index
 node scripts/archive-changelog.mjs --check
 node scripts/archive-issues.mjs --check
+node scripts/archive-decisions.mjs --check
 node --test scripts/*.test.mjs
 `;
 

package/references/templates/agent_rules.md

@@ -83,6 +83,7 @@ Apply these when authoring a plan, reviewing, folding a finding, or editing code
 - **Per-round emission.** Every review round emits **{round N · finding-origin tally · per-backend verdict}** so the crossover is a computed, visible signal, not a remembered rule.
 - **Recipe fidelity.** Council runs every backend the recipe names, **every round**; silently dropping a ready backend for quota/convenience is a forbidden downgrade — an unavailable backend is a LOUD, stated degrade, never a quiet drop.
 - **ExitPlanMode ≠ execute.** A harness "approved — start coding" prompt authorizes the PLAN only; this methodology overrides it. Continue into execution only as a DELIBERATE transition after the plan + cold-start prompt exist, never an implicit slide.
+- **Cost lanes.** Route every step to the **cheapest adequate executor** — L0 deterministic script (the batched gate matrix over `gates.json`, the rotation `--check`s) · L1 cheap subagent (extraction/drafting only; the orchestrator verifies) · L2 subscription bridge · L3 frontier judgment. A step with **no named guardrail does not move down** a lane, and the **red lines never move down** (council review models · real code · ADR/handover/changelog-entry wording · persuasive copy · go/no-go · the approval asks). Own-error repair: salvage recorded state first (L0/L1, batched), never frontier re-derivation.
 
 ---
 

package/references/templates/gates.json

@@ -0,0 +1,4 @@
+{
+  "_README": "Per-project gate declaration: the ordered list of verification commands (tests, validators, scanners, docs checks) that must be green before a commit. Run them all in one batch with the family gate runner (the composition root's `gates` command); re-run one with `--only <id>`. Each entry is { id, title, cmd }: `id` = a unique kebab-case handle, `title` = a short human label, `cmd` = ONE bash command line — gates are spawned via bash (brace/glob expansion works; a host without bash gets a loud preflight error, never a silent reinterpretation under another shell). This file declares WHAT to check, never who executes it — the schema has no lane/model/routing fields and rejects unknown keys loudly. Trust posture: the runner executes this project's OWN declared commands with the caller's privileges — a batching convenience over commands the project already runs by hand, not a sandbox. Strict JSON — no comments.",
+  "gates": []
+}