@sabaiway/agent-workflow-memory 4.7.0 → 6.0.0

package/CHANGELOG.md

@@ -4,6 +4,80 @@ 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 `3.0.0`).
 
+## 6.0.0 — a rolling archive stamps a cap it can honour, and refuses past a ceiling (AD-118)
+
+The changelog archiver wrote each tier's frontmatter `maxLines` as a LITERAL in the builder that
+emitted it: WARM 3500, COLD 1500, META 300. A literal is a promise about a corpus nobody has seen
+yet, so the day a tier outgrew its number the archiver emitted a file the docs gate refuses — its
+own output failing its own gate, and the repair was a hand edit that the next run stamped straight
+back over.
+
+> ### ⚠ BREAKING — the archiver now exits non-zero on input it used to accept
+>
+> New module `references/scripts/archive-caps.mjs` exports `capFor({tier, count})` over a frozen
+> floor/ceiling table — COLD 1500/3000, WARM 3500/7000, META 1500/3000. Once a tier's line count
+> goes PAST its ceiling the run REFUSES rather than stamp a cap it cannot honour, and it refuses
+> identically in every mode: the default run, `--dry-run` and `--check` alike. META's floor also
+> RISES 300 → 1500.
+>
+> **When it bites.** These bytes reach a project's `scripts/` only on a FRESH bootstrap, a
+> `migrate-adr-store` refresh, or a hand copy — installing this package does NOT overwrite an
+> existing deployed `archive-changelog.mjs`, and delivery to existing deployments is deliberately
+> out of scope here (a filed row). Once the bytes do land, a project whose archive has already
+> outgrown a ceiling sees its `changelog-rotation` gate turn red with no edit of its own, and an
+> existing `condensed-index.md` is re-stamped on the next run.
+
+- **The stamp is now a function of the file.** Below the floor a tier stamps the floor; inside the
+  band it stamps its OWN final line count; the ceiling itself is still stamped. `count` is the count
+  the docs gate computes (`check-docs-size.mjs` — a trailing newline ends a line, it never opens
+  one), restated as `countLines` so the stamp and the judge cannot disagree. Each builder renders
+  twice: once with a placeholder to learn its length, once with what `capFor` returns. The stamped
+  integer is one line whatever its value, so the first render's count IS the final count and the
+  stamp is a fixed point.
+- **Every cap-bearing output is BUILT before the mode branch.** WARM/COLD/META used to be built only
+  on the write path, so `--check` and `--dry-run` could never have seen a ceiling breach. A `--check`
+  that went green on a corpus the next real run cannot write is the same fail-open the parse already
+  refuses to be. Building is pure, so a refusal still leaves the tree byte-unchanged.
+- **The ceiling is 2x the floor, FIXED here, never measured from a corpus.** The refusal rides a
+  standing `--check` gate, so a ceiling derived from whatever happened to be on disk the day someone
+  wrote the test would brick every commit as soon as the corpus grew past it. Raising one is a
+  reviewed edit to the table, never something a run decides for itself.
+- **A sharding tripwire warns at the FLOOR.** META grows O(total archived entries) and never sheds,
+  so it reaches its ceiling first; warning while there is still room puts the remedy in front of
+  whoever runs the archiver. Both the COLD and META remedies state their sharding as NOT
+  IMPLEMENTED and say why — COLD discovery matches `YYYY-MM.md` only, so a hand-split file would
+  drop out of the corpus, and META is always regenerated whole. A remedy must never instruct a
+  layout the archiver cannot read back.
+- Deliberately out of scope, each a filed row: the HOT changelog's own fallback stamp, the sibling
+  `archive-issues` / `archive-decisions` stampers, and per-year META sharding.
+
+## 5.0.0 — the scenario floor: a contract can no longer pin NOTHING (AD-117)
+
+The reader enforced a minimum on `## Out of scope` and none on `## Scenarios`. A `kind: spec`
+document could therefore carry an EMPTY scenario section and pass everything — the reader, both
+`spec-check` lanes, the gate row. Measured cost, from writing the layer's first real specs: three
+stub specs would have satisfied every mechanical check of that slice and delivered nothing.
+
+> ### ⚠ BREAKING — the reader refuses a document it used to accept
+>
+> `SPEC_SCHEMA.rules` gains ONE frozen rule, **`scenarios-empty`**, in table position between
+> `scenario-path` and `out-of-scope`: a `## Scenarios` section carrying no scenario line is now an
+> error. The rule list is a frozen ordered contract, so a consumer that deep-equals it sees a 34th
+> id, and a deployment's spec gate can turn red with no edit of its own. The remedy is one line per
+> scenario — `- S<N> <name> :: unbound` while no test pins it.
+
+- **`*(empty)*` is deliberately NOT an escape here.** Written under `## Scenarios` it still refuses,
+  as `scenario-line`, and a fixture now pins that. The asymmetry with `## Out of scope` (where the
+  marker IS the decision) is the point: an empty exclusion list is a claim, an empty scenario list is
+  an absence, and the grammar already carries the honest form for the absence.
+- **`unbound` accepts on every status** — `draft`, `live` and `retired` alike — so the floor costs a
+  spec nothing but the statement that a scenario exists.
+- Measured before shipping: no document in the fixture corpus, the live store or the shipped
+  templates carries an empty section, so the floor refuses nothing that already exists.
+- The other 33 rule ids, every existing refusal and the whole `structure` extraction stay
+  behaviour-identical. The new arm was red-proofed against the pre-change reader.
+
+
 ## 4.7.0 — the reader's verdict gains the additive `structure` extraction (AD-114)
 
 The slice-2 checker (`spec-check`, next release) must read a document's structure through the SAME

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: '4.7.0'
+  version: '6.0.0'
 ---
 
 # agent-workflow-memory

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "4.7.0",
+  "version": "6.0.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-caps.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// The ONE cap table the rolling changelog archive stamps from.
+//
+// Each tier's frontmatter `maxLines` used to be a LITERAL inside the builder that wrote it: COLD
+// 1500, WARM 3500, META 300. A literal is a promise about a corpus nobody has seen yet, so the day a
+// tier outgrew its number the archiver emitted a file the docs gate refuses — its own output failing
+// its own gate — and the repair was to hand-raise the number in the emitted file until the next run
+// stamped the literal straight back over it.
+//
+// capFor stamps a cap the file HONOURS: the tier FLOOR while the file fits under it, the file's OWN
+// line count once it does not, and a REFUSAL once that count passes the tier CEILING. A growing
+// archive therefore stays green with no hand edit, and an archive that has grown past what its tier
+// was ever meant to hold STOPS the run instead of stamping a number nobody chose.
+//
+// The ceiling is 2x the floor, FIXED here and never measured from a corpus. The refusal rides the
+// standing `--check` gate, so a ceiling derived from whatever happened to be on disk the day someone
+// wrote the test would brick every commit as soon as the corpus grew past it.
+//
+// Dependency-free (one sibling import for the shared failure shape), Node >= 22. No side effects on
+// import.
+
+import { fail } from './markdown-blocks.mjs';
+
+// Each tier carries its OWN remedy, because the three run out of room for different reasons and one
+// piece of advice is wrong for two of them: COLD is already sharded per month, and WARM is a window
+// whose size is a flag, not a file layout.
+//
+// A remedy must never instruct a layout this archiver cannot READ BACK. COLD files are discovered by
+// `/^\d{4}-\d{2}\.md$/` alone, so a hand-split `2026-03-a.md` would silently drop out of the corpus
+// on the next run — conservation lost by following our own advice. META is always regenerated as a
+// single `condensed-index.md`, so a per-year file would be orphaned the moment it was written. Both
+// therefore name the work as UNIMPLEMENTED rather than telling anyone to do it. Only WARM's remedy
+// is something a run supports today: `--warm-days` is a flag, not a file layout.
+export const CAP_TABLE = Object.freeze({
+  // COLD — docs/ai/history/YYYY-MM.md: one CLOSED month of compressed entries. A closed month never
+  // grows again, so its stamp is a fact about that month, not a forecast.
+  cold: Object.freeze({
+    floor: 1500,
+    ceiling: 3000,
+    remedy: 'compress that month harder — it is already one file per month, and sub-month sharding is NOT implemented (discovery matches YYYY-MM.md only, so a hand-split file would drop out of the corpus)',
+  }),
+  // WARM — docs/ai/history/recent.md: a rolling window of full-text entries, the widest tier.
+  warm: Object.freeze({
+    floor: 3500,
+    ceiling: 7000,
+    remedy: 'shorten the WARM window with --warm-days so the oldest entries move on to COLD',
+  }),
+  // META — docs/ai/history/condensed-index.md: one line per archived entry, so it grows O(total) and
+  // never sheds. Its floor rose 300 -> 1500 because 300 never fit the ~1159-at-2y growth the
+  // archiver's own header documents; the ceiling is where per-year sharding stops being optional.
+  meta: Object.freeze({
+    floor: 1500,
+    ceiling: 3000,
+    remedy: 'shard it per-year (condensed-index-YYYY.md) — NOT implemented yet: this file is always regenerated whole, so the split needs discovery and generation before anyone splits it by hand',
+  }),
+});
+
+export const TIERS = Object.freeze(Object.keys(CAP_TABLE));
+
+// The docs gate's OWN line count (check-docs-size.mjs): a trailing newline terminates the last line,
+// it does not open a new one. Counting any other way would stamp a cap the gate disagrees with —
+// precisely the failure this module exists to end.
+export const countLines = (text) => text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
+
+// Object.hasOwn, never a bare lookup: `CAP_TABLE['toString']` finds an INHERITED function, which is
+// truthy, and the stamp then reads `undefined` off it and writes `maxLines: undefined`. An unknown
+// tier has to refuse, and "unknown" includes every name Object.prototype happens to carry.
+const bandFor = (tier) => {
+  if (!Object.hasOwn(CAP_TABLE, tier)) {
+    throw fail(1, `unknown archive tier: ${String(tier)} (known: ${TIERS.join(', ')})`);
+  }
+  return CAP_TABLE[tier];
+};
+
+const assertCount = (tier, count) => {
+  if (!Number.isInteger(count) || count < 0) {
+    throw fail(1, `${tier}: line count must be a non-negative integer, got ${JSON.stringify(count)}`);
+  }
+};
+
+// The stamp. `count` is the FINAL line count of the file being written, frontmatter included — the
+// caller renders the whole file once with a placeholder cap, counts it, and renders again with what
+// this returns. The stamped integer occupies one line either way, so the second render has the same
+// count as the first and the value is a fixed point.
+export const capFor = ({ tier, count }) => {
+  const band = bandFor(tier);
+  assertCount(tier, count);
+  if (count > band.ceiling) {
+    throw fail(
+      1,
+      `${tier} archive is ${count} lines, past its ${band.ceiling}-line ceiling — there is no cap it ` +
+        `can both stamp and honour. Remedy: ${band.remedy}. Raising the ceiling is a reviewed edit to ` +
+        `archive-caps.mjs, never something a run decides for itself.`,
+    );
+  }
+  return count > band.floor ? count : band.floor;
+};
+
+// The sharding tripwire. A tier past its FLOOR still stamps and still passes — it is simply growing
+// on room the floor was not sized for. Warning here puts the remedy in front of whoever runs the
+// archiver while there is still headroom, instead of at the ceiling where the run refuses.
+export const shardingWarning = ({ tier, count }) => {
+  const band = bandFor(tier);
+  assertCount(tier, count);
+  if (count <= band.floor) return null;
+  return (
+    `${tier} archive is ${count} lines, past its ${band.floor}-line floor (ceiling ${band.ceiling}) — ` +
+    `it is stamping its own count. Remedy before the count goes PAST the ceiling and the run refuses: ${band.remedy}.`
+  );
+};

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

@@ -0,0 +1,321 @@
+import { describe, it } from 'node:test';
+import { readFileSync, writeFileSync, mkdirSync, mkdtempSync, rmSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { expect } from './_expect-shim.mjs';
+import { runCli } from './archive-changelog.mjs';
+
+// RED-FIRST, and deliberately a DYNAMIC import: `archive-caps.mjs` does not exist when these arms
+// are first recorded, and a STATIC import of an absent module makes the WHOLE file unloadable — every
+// arm would then be recorded as "unresolvable" rather than as failing, which proves nothing about the
+// behaviour it pins. Imported this way the file still loads and each arm fails on its own missing
+// symbol.
+const caps = await import('./archive-caps.mjs').catch(() => ({}));
+
+// The tier table, restated here on purpose. A test that imports the table it is checking agrees with
+// the source by construction and pins nothing; these three rows are the frozen contract, and moving a
+// number in the module must break this file.
+const TABLE = [
+  ['cold', 1500, 3000],
+  ['warm', 3500, 7000],
+  ['meta', 1500, 3000],
+];
+
+// Every arm builds its own corpus under a temp root and passes a fixed `--today`, so nothing here
+// reads the project's own `docs/ai` — these pass in a clean checkout where that tree is absent.
+const TODAY = '2026-06-15';
+const FM = '---\ntype: history\nlastUpdated: 2026-06-15\nscope: permanent\nstaleAfter: never\nowner: none\nmaxLines: 700\n---\n';
+
+const makeRoot = () => {
+  const root = mkdtempSync(join(tmpdir(), 'archive-caps-'));
+  mkdirSync(join(root, 'docs', 'ai', 'history'), { recursive: true });
+  return root;
+};
+
+// TALL entries carry a files block and a metric, so compression keeps eight lines of them; MINIMAL
+// entries keep three. The difference is how a tier is driven to a chosen size: COLD/WARM need height,
+// META needs COUNT (one line per archived entry) with every month's own COLD file left small.
+const entryBlock = (dateStr, n, tall) =>
+  tall
+    ? `## ${dateStr} — synthetic ${n}\n\n**Goal:** synthetic session ${n}.\n\n**Files:**\n- \`src/f${n}.mjs\`\n\n**Result:** ${n} tests\n`
+    : `## ${dateStr} — synthetic ${n}\n\n**Goal:** synthetic session ${n}.\n`;
+
+const seed = (root, dates, tall = true) => {
+  const body = dates.map((d, i) => entryBlock(d, i + 1, tall)).join('\n');
+  writeFileSync(join(root, 'docs', 'ai', 'changelog.md'), `${FM}\n# Changelog\n\n${body}`, 'utf8');
+};
+
+const day = (i) => String((i % 28) + 1).padStart(2, '0');
+
+// One month, well behind the WARM cutoff — everything lands in that month's COLD file.
+const oneMonth = (count) => Array.from({ length: count }, (_, i) => `2026.03.${day(i)}`);
+
+// Inside the WARM window (older than today-3, newer than today-30 = 2026-05-16).
+const warmWindow = (count) =>
+  Array.from({ length: count }, (_, i) => `2026.05.${String(17 + (i % 14)).padStart(2, '0')}`);
+
+// Spread across many CLOSED months so META grows by count while no single COLD file gets near its
+// own ceiling — the only shape in which META can be the tier that refuses.
+const manyMonths = (months, perMonth) => {
+  const dates = [];
+  for (let m = 0; m < months; m += 1) {
+    const year = 2019 + Math.floor(m / 12);
+    const month = String((m % 12) + 1).padStart(2, '0');
+    for (let i = 0; i < perMonth; i += 1) dates.push(`${year}.${month}.${day(i)}`);
+  }
+  return dates;
+};
+
+const run = (root, argv) => {
+  const out = [];
+  const err = [];
+  const code = runCli([...argv, `--today=${TODAY}`], {
+    root,
+    log: (m) => out.push(String(m)),
+    logError: (m) => err.push(String(m)),
+  });
+  return { code, out: out.join('\n'), err: err.join('\n') };
+};
+
+const historyDir = (root) => join(root, 'docs', 'ai', 'history');
+const emitted = (root, name) => readFileSync(join(historyDir(root), name), 'utf8');
+
+// A refusal must leave the tree BYTE-unchanged, and "the history dir is still empty" does not say
+// that: it would miss a rewritten changelog.md. Snapshot every file under docs/ai instead.
+// Built with fromCharCode, not an escape literal: the separator only has to be deterministic, and
+// spelling it in code points keeps a stray byte out of a file the NUL guard scans.
+const SEP = String.fromCharCode(10, 64, 64, 10);
+const snapshot = (root) => {
+  const base = join(root, 'docs', 'ai');
+  const walk = (dir, prefix) =>
+    readdirSync(dir, { withFileTypes: true })
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .flatMap((entry) =>
+        entry.isDirectory()
+          ? walk(join(dir, entry.name), `${prefix}${entry.name}/`)
+          : [`${prefix}${entry.name}:${readFileSync(join(dir, entry.name), 'utf8')}`],
+      );
+  return walk(base, '').join(SEP);
+};
+const stampOf = (text) => Number(/^maxLines: (\d+)$/m.exec(text)[1]);
+const countOf = (text) => text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
+
+const refusal = (fn) => {
+  try {
+    fn();
+    return null;
+  } catch (err) {
+    return err;
+  }
+};
+
+const withRoot = (body) => {
+  const root = makeRoot();
+  try {
+    body(root);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+};
+
+describe('capFor — the frozen tier table', () => {
+  for (const [tier, floor, ceiling] of TABLE) {
+    it(`capFor: ${tier} stamps the floor below it, its own count inside the band, and the ceiling itself`, () => {
+      expect(caps.capFor({ tier, count: 0 })).toBe(floor);
+      expect(caps.capFor({ tier, count: floor - 1 })).toBe(floor);
+      expect(caps.capFor({ tier, count: floor })).toBe(floor);
+      expect(caps.capFor({ tier, count: floor + 1 })).toBe(floor + 1);
+      expect(caps.capFor({ tier, count: ceiling - 1 })).toBe(ceiling - 1);
+      // The boundary ACCEPTS. A cap equal to the count is a cap the file honours, so the ceiling is
+      // the LAST count that can be stamped, never the first that refuses — and stamping the count
+      // (not the ceiling) here is what separates this from a `Math.min(count, ceiling)` that would
+      // pass the boundary arm while getting the whole band wrong.
+      expect(caps.capFor({ tier, count: ceiling })).toBe(ceiling);
+    });
+
+    it(`capFor: ${tier} refuses one line past its ceiling`, () => {
+      const err = refusal(() => caps.capFor({ tier, count: ceiling + 1 }));
+      expect(err).not.toBeNull();
+      expect(err.message).toContain(`${ceiling}-line ceiling`);
+      expect(err.exitCode).toBe(1);
+    });
+  }
+
+  it('capFor: an unknown tier and a nonsense count both refuse rather than stamp a default', () => {
+    expect(refusal(() => caps.capFor({ tier: 'lukewarm', count: 10 })).message).toContain('unknown archive tier');
+    expect(refusal(() => caps.capFor({ tier: 'cold', count: -1 })).message).toContain('non-negative integer');
+    expect(refusal(() => caps.capFor({ tier: 'cold', count: 1.5 })).message).toContain('non-negative integer');
+  });
+
+  it('countLines: counts the docs gate its own way — a trailing newline ends a line, it never opens one', () => {
+    expect(caps.countLines('a\nb\n')).toBe(2);
+    expect(caps.countLines('a\nb')).toBe(2);
+    expect(caps.countLines('a\n')).toBe(1);
+    expect(caps.countLines('a\n\n')).toBe(2);
+  });
+
+  it('shardingWarning: silent under the floor, and past it names the tier, the count and the remedy', () => {
+    expect(caps.shardingWarning({ tier: 'meta', count: 1500 })).toBeNull();
+    const warning = caps.shardingWarning({ tier: 'meta', count: 1501 });
+    expect(warning).toContain('1501');
+    expect(warning).toContain('1500-line floor');
+    expect(warning).toContain('condensed-index-YYYY.md');
+  });
+});
+
+describe('the archiver stamps a cap it can honour', () => {
+  it('cold: a band-sized month stamps its own count and round-trips byte-identically', () => {
+    withRoot((root) => {
+      seed(root, oneMonth(160));
+      expect(run(root, []).code).toBe(0);
+
+      const first = emitted(root, '2026-03.md');
+      const count = countOf(first);
+      // Strictly inside the band: below the floor the tier would stamp the floor and this arm would
+      // pin nothing; at or above the ceiling it would refuse.
+      expect(count).toBeGreaterThan(1500);
+      expect(count).toBeLessThan(3001);
+      expect(stampOf(first)).toBe(count);
+
+      // The byte fixed point, under the new stamp: run two re-reads what run one wrote — including
+      // the cap it stamped — and must reproduce it exactly.
+      expect(run(root, []).code).toBe(0);
+      expect(emitted(root, '2026-03.md')).toBe(first);
+    });
+  });
+
+  it('warm: a band-sized window stamps its own count and round-trips byte-identically', () => {
+    withRoot((root) => {
+      seed(root, warmWindow(400));
+      expect(run(root, []).code).toBe(0);
+
+      const first = emitted(root, 'recent.md');
+      const count = countOf(first);
+      expect(count).toBeGreaterThan(3500);
+      expect(count).toBeLessThan(7001);
+      expect(stampOf(first)).toBe(count);
+
+      expect(run(root, []).code).toBe(0);
+      expect(emitted(root, 'recent.md')).toBe(first);
+    });
+  });
+
+  it('meta: a band-sized corpus stamps its own count and round-trips byte-identically', () => {
+    withRoot((root) => {
+      seed(root, manyMonths(32, 50), false);
+      expect(run(root, []).code).toBe(0);
+
+      const first = emitted(root, 'condensed-index.md');
+      const count = countOf(first);
+      expect(count).toBeGreaterThan(1500);
+      expect(count).toBeLessThan(3001);
+      expect(stampOf(first)).toBe(count);
+
+      expect(run(root, []).code).toBe(0);
+      expect(emitted(root, 'condensed-index.md')).toBe(first);
+    });
+  });
+
+  it('a tier under its floor still stamps the floor — the cap never shrinks to the corpus', () => {
+    withRoot((root) => {
+      seed(root, oneMonth(4));
+      expect(run(root, []).code).toBe(0);
+      const cold = emitted(root, '2026-03.md');
+      expect(countOf(cold)).toBeLessThan(1500);
+      expect(stampOf(cold)).toBe(1500);
+    });
+  });
+});
+
+describe('the archiver refuses past a ceiling, identically in every mode', () => {
+  // The refusal has to fire in --check and --dry-run as well as the default run, or the standing
+  // `--check` gate would go green on a corpus the next real run cannot write. That is only true if
+  // every output is BUILT before the mode branch — which is what these three arms pin.
+  const modes = [[], ['--dry-run'], ['--check']];
+
+  // Each mode gets its OWN fixture: sharing one root lets an earlier mode's write hide inside a
+  // later mode's assertion. And the tree is compared WHOLE before and after, so a rewritten
+  // changelog.md is caught as well as a written archive.
+  const refusesInEveryMode = (dates, tall, ceiling) => {
+    for (const argv of modes) {
+      withRoot((root) => {
+        seed(root, dates, tall);
+        const before = snapshot(root);
+        const result = run(root, argv);
+        expect(result.code).toBe(1);
+        expect(result.err).toContain(`${ceiling}-line ceiling`);
+        expect(snapshot(root)).toBe(before);
+      });
+    }
+  };
+
+  it('cold: a month past the ceiling refuses in all three modes', () => {
+    refusesInEveryMode(oneMonth(400), true, 3000);
+  });
+
+  it('warm: a window past the ceiling refuses in all three modes', () => {
+    refusesInEveryMode(warmWindow(700), true, 7000);
+  });
+
+  it('meta: a corpus past the ceiling refuses in all three modes', () => {
+    refusesInEveryMode(manyMonths(62, 50), false, 3000);
+  });
+
+  // Two arms, deliberately separate: this one pins that a refusal is ACTIONABLE at all — it names
+  // the tier, the measured size and a remedy clause, rather than a bare number the reader has to
+  // interpret.
+  it('the refusal names the tier and the remedy, not just the number', () => {
+    withRoot((root) => {
+      seed(root, oneMonth(400));
+      const cold = run(root, ['--check']);
+      expect(cold.err).toContain('cold archive is');
+      expect(cold.err).toContain('-line ceiling');
+      expect(cold.err).toContain('Remedy:');
+    });
+  });
+
+  // And this one pins that the remedy is RIGHT for the tier it is printed for. One piece of advice
+  // would be wrong for two of the three: COLD is already one file per month, and WARM's size is a
+  // flag rather than a layout. A remedy must also never name a layout the archiver cannot read back.
+  it('the refusal names the tier and a remedy that fits THAT tier', () => {
+    withRoot((root) => {
+      seed(root, oneMonth(400));
+      const cold = run(root, ['--check']);
+      expect(cold.err).toContain('already one file per month');
+      expect(cold.err).toContain('NOT implemented');
+    });
+    withRoot((root) => {
+      seed(root, warmWindow(700));
+      const warm = run(root, ['--check']);
+      expect(warm.err).toContain('warm archive is');
+      expect(warm.err).toContain('--warm-days');
+    });
+    withRoot((root) => {
+      seed(root, manyMonths(62, 50), false);
+      const meta = run(root, ['--check']);
+      expect(meta.err).toContain('meta archive is');
+      expect(meta.err).toContain('condensed-index-YYYY.md');
+    });
+  });
+});
+
+describe('the sharding tripwire', () => {
+  it('meta past its floor warns while still passing, so the remedy lands before the ceiling', () => {
+    withRoot((root) => {
+      seed(root, manyMonths(32, 50), false);
+      const result = run(root, []);
+      expect(result.code).toBe(0);
+      expect(result.err).toContain('past its 1500-line floor');
+      expect(result.err).toContain('condensed-index-YYYY.md');
+    });
+  });
+
+  it('meta under its floor says nothing at all', () => {
+    withRoot((root) => {
+      seed(root, oneMonth(4));
+      const result = run(root, []);
+      expect(result.code).toBe(0);
+      expect(result.err).not.toMatch(/floor/);
+    });
+  });
+});

package/references/scripts/archive-changelog.mjs

@@ -13,19 +13,25 @@
 // does not parse as an entry refuses with file:line — it is never glued into the previous entry,
 // never duplicated into the footer, never normalised into a different calendar date.
 //
-// NOTE (multi-year scaling): condensed-index.md grows O(total archived entries),
-// so on a multi-year horizon it approaches its cap (~1159 lines over 2y in a stress
-// test). When it nears the cap, shard it per-year (condensed-index-YYYY.md) or switch
-// to an append-only cap. Stress-test rotation via the exported pure functions against
-// a /tmp copy seeded with a synthetic multi-year dataset (include burst periods).
+// NOTE (multi-year scaling): condensed-index.md grows O(total archived entries) and never sheds, so
+// on a multi-year horizon it is the tier that runs out of room first (~1159 lines over 2y in a
+// stress test). Its floor is 1500 and its ceiling 3000 (archive-caps.mjs): past the FLOOR every run
+// prints a sharding warning, and once the count goes PAST the ceiling the run refuses outright
+// rather than stamp a cap it cannot honour — the ceiling itself is still stamped. The remedy is per-year sharding (condensed-index-YYYY.md) — a queued row, never
+// something a run decides for itself. Stress-test rotation via the exported pure functions against
+// a temp copy seeded with a synthetic multi-year dataset (include burst periods).
 //
 // Modes:
 //   (default)   run rotation, mutate files in place
 //   --dry-run   print planned distribution, do not change files
 //   --check     exit 1 if changelog.md still holds entries that should be archived
 //
-// Every mode parses every source BEFORE any write, so a refusal fires identically for the
-// default run, --dry-run and --check, and nothing is written on a refused input.
+// Every mode parses every source AND builds every tier-STAMPED output (WARM, COLD, META) BEFORE any
+// write, so a refusal — an unparsable source, or a tier that has outgrown its ceiling — fires
+// identically for the default run, --dry-run and --check, and nothing is written on a refused input.
+// The HOT changelog is deliberately NOT in that set: buildChangelog passes the file's OWN
+// frontmatter through and reaches a literal only when the file carries none. That fallback is
+// unguarded, and it is a filed queue row rather than an oversight.
 //
 // CLI overrides:
 //   --hot-days=N  (default 3)
@@ -36,6 +42,7 @@ import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync, realpa
 import { dirname, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { tokenizeMarkdown, findParagraphBreak, fail } from './markdown-blocks.mjs';
+import { capFor, countLines, shardingWarning } from './archive-caps.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -347,22 +354,25 @@ export const buildChangelog = ({ frontmatter, preamble, hot, footer, hasArchive
   return parts.filter((p) => p !== null && p !== undefined).join('\n').replace(/\n{3,}/g, '\n\n').trim() + '\n';
 };
 
+// Each tier renders TWICE and stamps what the second render can honour. The cap is one line of
+// frontmatter whatever integer it holds, so the first render's line count IS the final file's line
+// count — which makes the stamp a fixed point rather than a promise about a corpus nobody has seen.
+// capFor refuses outright past the tier's ceiling; see archive-caps.mjs.
+const stamped = (tier, render) => render(capFor({ tier, count: countLines(render(0)) }));
+
 export const buildRecent = (entries, todayStr) => {
-  const frontmatter = FRONTMATTER('history', 3500, todayStr);
   const preamble = `# Changelog WARM Archive — ${PROJECT_NAME}\n\n> Entries aged **7–30 days** from today. Newer → [\`../changelog.md\`](../changelog.md). Older → [\`condensed-index.md\`](./condensed-index.md) plus per-month \`YYYY-MM.md\` files.`;
   const body = renderEntries(entries);
-  return `${frontmatter}\n${preamble}\n\n---\n\n${body}\n`;
+  return stamped('warm', (cap) => `${FRONTMATTER('history', cap, todayStr)}\n${preamble}\n\n---\n\n${body}\n`);
 };
 
 export const buildCold = (year, month, entries, todayStr) => {
-  const frontmatter = FRONTMATTER('history', 1500, todayStr);
   const preamble = `# Changelog COLD Archive — ${year}-${month}\n\n> Compressed entries from ${year}-${month} (older than 30 days). Cross-month one-liners → [\`condensed-index.md\`](./condensed-index.md). Full commit history: \`git log --since=${year}-${month}-01 --until=${year}-${month}-31\`.`;
   const compressed = entries.map(compressEntry).join('\n\n---\n\n');
-  return `${frontmatter}\n${preamble}\n\n---\n\n${compressed}\n`;
+  return stamped('cold', (cap) => `${FRONTMATTER('history', cap, todayStr)}\n${preamble}\n\n---\n\n${compressed}\n`);
 };
 
 export const buildCondensedIndex = (warmEntries, coldByMonth, todayStr) => {
-  const frontmatter = FRONTMATTER('history', 300, todayStr);
   const intro = `# Condensed Index — ${PROJECT_NAME} Changelog\n\n> One-line TL;DR for every archived entry. Each line links to the file holding the full text.`;
 
   const lines = [];
@@ -378,7 +388,7 @@ export const buildCondensedIndex = (warmEntries, coldByMonth, todayStr) => {
     for (const e of coldByMonth.get(key)) lines.push(summarizeEntry(e, `${year}-${month}.md`));
     lines.push('');
   }
-  return `${frontmatter}\n${intro}\n\n${lines.join('\n').trim()}\n`;
+  return stamped('meta', (cap) => `${FRONTMATTER('history', cap, todayStr)}\n${intro}\n\n${lines.join('\n').trim()}\n`);
 };
 
 export const groupByMonth = (entries) => {
@@ -471,6 +481,27 @@ export const runCli = (argv, deps = {}) => {
       coldFiles: [...coldByMonth.keys()].sort(),
     };
 
+    // EVERY cap-bearing output is BUILT here, before the mode branch, and capFor refuses a tier that
+    // has outgrown its ceiling. That refusal has to fire identically in all three modes: a `--check`
+    // that went green on a corpus the next real run cannot write would be exactly the fail-open the
+    // parse above already refuses to be. Building is pure — nothing reaches disk until the writes
+    // below, so a refusal still leaves the tree untouched.
+    const archives = [];
+    if (warm.length > 0) archives.push({ path: recentPath, text: buildRecent(warm, todayStr) });
+    for (const [key, entries] of coldByMonth) {
+      const [year, month] = key.split('-');
+      archives.push({ path: resolve(historyDir, `${year}-${month}.md`), text: buildCold(year, month, entries, todayStr) });
+    }
+    if (warm.length > 0 || cold.length > 0) {
+      const index = buildCondensedIndex(warm, coldByMonth, todayStr);
+      // The sharding tripwire. META grows O(total) and never sheds, so it is the tier that reaches
+      // its ceiling first; warning at the floor puts the remedy in front of whoever runs the
+      // archiver while there is still room, instead of at the ceiling where the run refuses.
+      const warning = shardingWarning({ tier: 'meta', count: countLines(index) });
+      if (warning) logError(`[archive-changelog] WARNING: ${warning}`);
+      archives.push({ path: indexPath, text: index });
+    }
+
     if (flags.check) {
       const tooOldInHot = parsed.entries.filter((e) => e.dateObj < cutoffs.hotCutoff);
       if (tooOldInHot.length > 0) {
@@ -516,18 +547,7 @@ export const runCli = (argv, deps = {}) => {
     });
     writeFileSync(changelogPath, newChangelog, 'utf8');
 
-    if (warm.length > 0) {
-      writeFileSync(recentPath, buildRecent(warm, todayStr), 'utf8');
-    }
-
-    for (const [key, entries] of coldByMonth) {
-      const [year, month] = key.split('-');
-      writeFileSync(resolve(historyDir, `${year}-${month}.md`), buildCold(year, month, entries, todayStr), 'utf8');
-    }
-
-    if (warm.length > 0 || cold.length > 0) {
-      writeFileSync(indexPath, buildCondensedIndex(warm, coldByMonth, todayStr), 'utf8');
-    }
+    for (const archive of archives) writeFileSync(archive.path, archive.text, 'utf8');
 
     log('[archive-changelog] migrated:');
     log(`  HOT (${CHANGELOG_REL}): ${hot.length}`);

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

@@ -158,12 +158,19 @@ describe('buildChangelog', () => {
 });
 
 describe('buildRecent', () => {
-  it('emits frontmatter with maxLines 3500 for WARM archive', () => {
+  it('emits frontmatter at the WARM floor for a corpus that fits under it', () => {
     const result = buildRecent([makeEntry('2026.05.10', 'warm')], '2026-05-24');
     expect(result).toMatch(/maxLines: 3500/);
     expect(result).toMatch(/Changelog WARM Archive/);
     expect(result).toMatch(/## 2026\.05\.10/);
   });
+
+  // 3500/1500/1500 are tier FLOORS reached through capFor (archive-caps.mjs), not literals a builder
+  // still carries — this pins all three onto that path; band/ceiling/fixed point: archive-caps.test.mjs.
+  it('every builder stamps its own tier floor on a corpus that fits under it', () => {
+    expect(buildCold('2026', '03', [makeEntry('2026.03.10', 'c')], '2026-05-24')).toMatch(/maxLines: 1500/);
+    expect(buildCondensedIndex([makeEntry('2026.05.10', 'w')], new Map(), '2026-05-24')).toMatch(/maxLines: 1500/);
+  });
 });
 
 describe('buildCold', () => {

package/references/scripts/spec-schema.mjs

@@ -38,7 +38,7 @@ export const SPEC_SCHEMA = Object.freeze({
     'frontmatter', 'frontmatter-key', 'substrate-key', 'type', 'kind', 'maxlines', 'status', 'revision',
     'root-owns', 'slug', 'kind-path', 'root-uplink', 'title', 'section-missing', 'section-order',
     'section-forbidden', 'fence', 'children-link', 'children-duplicate', 'fan-out', 'scenario-line',
-    'scenario-number', 'scenario-marker', 'scenario-path', 'out-of-scope', 'module-line', 'module-empty',
+    'scenario-number', 'scenario-marker', 'scenario-path', 'scenarios-empty', 'out-of-scope', 'module-line', 'module-empty',
     'module-traversal', 'module-absolute', 'module-backslash', 'module-glob', 'module-mix', 'parts',
   ]),
 });
@@ -238,6 +238,10 @@ const checkScenarios = (parsed, slug, status, errors, warnings) => {
     }
     scenarios.push(scenario);
   }
+  if (scenarios.length === 0) {
+    errors.push({ rule: 'scenarios-empty', message: `at least one scenario line (\`${SPEC_SCHEMA.unboundMarker}\` while no test pins it)` });
+    return;
+  }
   const gap = scenarios.findIndex((scenario, i) => scenario.n !== i + 1);
   if (gap !== -1) errors.push({ rule: 'scenario-number', message: `scenario ${gap + 1} is numbered S${scenarios[gap].n} — N runs contiguously from 1` });
   for (const scenario of scenarios) {

package/references/scripts/spec-schema.test.mjs

@@ -131,6 +131,14 @@ describe('readSpecDocument — refuse, exactly one rule per defect', () => {
     refuses(specDoc({ scenarios: ['- S1 a :: /abs/login.test.mjs :: spec:login/S1'] }), 'login.md', 'scenario-path');
   });
 
+  it('scenarios-empty / no empty-marker escape', () => {
+    refuses(specDoc({ scenarios: [] }), 'login.md', 'scenarios-empty');
+    refuses(specDoc({ scenarios: ['*(empty)*'] }), 'login.md', 'scenario-line');
+    for (const status of SPEC_SCHEMA.statuses) {
+      expect(readSpecDocument(specDoc({ scenarios: ['- S1 x :: unbound'], fields: { status } }), 'login.md').errors).toEqual([]);
+    }
+  });
+
   it('out-of-scope / module-empty / module-* path refusals / module-mix / parts', () => {
     refuses(specDoc({ outOfScope: '' }), 'login.md', 'out-of-scope');
     refuses(specDoc({ outOfScope: 'nothing excluded' }), 'login.md', 'out-of-scope');