@sabaiway/agent-workflow-kit 7.6.0 → 9.0.0

package/CHANGELOG.md

@@ -4,6 +4,63 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 9.0.0 — the archiver's cap table ships, and the migration seeds it behind its importer (AD-118)
+
+Memory **6.0.0** replaces the changelog archiver's fixed cap literals with a stamp it can honour,
+and this kit ships those bytes. One kit-owned behaviour moved with them, and it is the interesting
+half: a new import by a refreshed archiver reopens a hole the companion seed exists to close.
+
+> ### ⚠ BREAKING — inherited from memory 6.0.0
+>
+> The archiver REFUSES once a tier's line count goes past its ceiling, in every mode including
+> `--check`, and META's floor rises 300 → 1500.
+>
+> **When it bites.** The new bytes reach a project's `scripts/` on a FRESH bootstrap, a
+> `migrate-adr-store` refresh, or a hand copy — installing this kit does NOT overwrite an existing
+> deployed `archive-changelog.mjs`. Once they land, a project whose archive has already outgrown a
+> ceiling sees its `changelog-rotation` gate turn red with no edit of its own.
+
+- **`references/scripts/archive-caps{,.test}.mjs`** — new, mirrored byte-identical from the memory
+  canon; `references/scripts/archive-changelog{,.test}.mjs` refreshed to the 6.0.0 bodies.
+  `sync-mirrors --check` green over all three copies.
+- **`tools/migrate-adr-store.mjs` — `COMPANION_SEEDS` gains a per-entry condition.** The list exists
+  so a refreshed archiver never crashes on a missing runtime import, and it was flat: every entry
+  seeded on every migration. That was correct for what it held — the ONE runtime dependency
+  `markdown-blocks.mjs`, which all three archivers import, plus its deploy-payload test riding along
+  with it. `archive-caps.mjs` is imported by `archive-changelog.mjs` ALONE, so seeding it
+  unconditionally would write a file with no importer during a plain ADR migration — the directional
+  "never ADD a basename the consumer lacks" rule broken, and a log line saying something untrue. An
+  entry may now NAME the importer it rides: the markdown pair stays unconditional, the `archive-caps`
+  pair rides `archive-changelog.mjs`, and two arms pin both cases — importer present, importer absent.
+- **`tools/known-footprint.mjs`** — `KIT_OWN_PATHS` gains both new script paths (30 → 32), so a
+  HIDDEN deployment does not leave them visible in `git status`.
+- Tarball sentinels move with the payload on their documented ladders: kit 250 → 252, memory 59 → 61.
+
+## 8.0.0 — the bundled reader gets the scenario floor, and the refresh lane carries it out (AD-117)
+
+Memory **5.0.0** gives the spec reader one new refusal — a `## Scenarios` section carrying no
+scenario line — and this kit ships those bytes. Nothing in the kit's own logic changed shape; what
+changed is what the deployed reader says about a document, and therefore what a project's spec gate
+says about its store.
+
+> ### ⚠ BREAKING — inherited from memory 5.0.0
+>
+> `spec-check` (both lanes) and the `spec-check` gate row relay the reader's verdict, so a spec that
+> pins NOTHING now turns a deployment red with no edit of its own. The remedy is one line per
+> scenario — `- S<N> <name> :: unbound` while no test pins it. The refusal is the migration signal:
+> a contract that pins nothing is the one shape the layer exists to refuse.
+
+- **`references/scripts/spec-schema{,.test}.mjs`** — refreshed to the 5.0.0 bodies; the four mirrored
+  copies stay byte-identical, `sync-mirrors --check` green.
+- **`tools/script-priors.mjs`** — the catalog gains the two OUTGOING `4.7.0..4.7.0` reader rows
+  (`spec-schema.mjs`, `spec-schema.test.mjs`), read from the released bytes, so an unmodified 4.7.0
+  deployment is recognised as unmodified and converges on the next kit touch instead of stranding as
+  `custom`. The independent `FROZEN_PRIORS` pin in the test moves with it — 8 catalog rows, none
+  equal to the bundled body.
+- **Obligation discharged: KIT-SUBTREE-CHANGED-WITHOUT-A-BUMP.** Slice 4 wrote 19 spec-binding
+  markers into this package's subtree and shipped no bump. This release carries them.
+
+
 ## 7.6.0 — `spec-check`: the spec store judged against what the session SAYS it changed (AD-115)
 
 The feature-spec layer gets its structural checker. The change source is EXPLICIT and never git — a

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '7.6.0'
+  version: '9.0.0'
 ---
 
 # agent-workflow-kit

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "7.6.0",
+  "version": "9.0.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/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');

package/tools/known-footprint.mjs

@@ -49,6 +49,8 @@ export const KIT_OWN_PATHS = [
   '/CLAUDE.md',
   '/docs/ai/',
   '/scripts/_expect-shim.mjs',
+  '/scripts/archive-caps.mjs',
+  '/scripts/archive-caps.test.mjs',
   '/scripts/archive-changelog.mjs',
   '/scripts/archive-changelog.test.mjs',
   '/scripts/archive-conservation.test.mjs',

package/tools/migrate-adr-store.mjs

@@ -125,14 +125,29 @@ export const planScriptRefresh = (cwd, deps = {}) => {
 // archivers to this kit's canon without their runtime dependency would leave every refreshed
 // script crashing on a missing `./markdown-blocks.mjs` import until a separate upgrade run — so
 // the dependency rides the SAME apply, atomically, written before its importers.
-const COMPANION_SEEDS = ['markdown-blocks.mjs', 'markdown-blocks.test.mjs'];
+// `archive-caps.mjs` joined the list the moment `archive-changelog.mjs` began importing it: a new
+// import by a refreshed archiver reopens this exact hole, so the list moves with the imports.
+//
+// A seed is UNCONDITIONAL only when every refreshable archiver imports it. `markdown-blocks.mjs` is
+// imported by all three (changelog, decisions, issues), so any refresh needs it. `archive-caps.mjs`
+// is imported by `archive-changelog.mjs` ALONE — seeding it on a plain ADR migration that never
+// refreshed the changelog archiver would write a file with no importer, which is the directional
+// "never ADD a basename the consumer lacks" rule broken and a log line that says something untrue.
+const COMPANION_SEEDS = [
+  { name: 'markdown-blocks.mjs', requiredBy: null },
+  { name: 'markdown-blocks.test.mjs', requiredBy: null },
+  { name: 'archive-caps.mjs', requiredBy: 'archive-changelog.mjs' },
+  { name: 'archive-caps.test.mjs', requiredBy: 'archive-changelog.mjs' },
+];
 export const planCompanionSeeds = (cwd, refresh, deps = {}) => {
   if (refresh.length === 0) return [];
   const exists = deps.exists ?? existsSync;
   const kitScripts = deps.kitScripts ?? KIT_SCRIPTS;
   const consumerScripts = join(cwd, CONSUMER_SCRIPTS_REL);
+  const refreshed = new Set(refresh.map((entry) => entry.name));
   const out = [];
-  for (const name of COMPANION_SEEDS) {
+  for (const { name, requiredBy } of COMPANION_SEEDS) {
+    if (requiredBy !== null && !refreshed.has(requiredBy)) continue;
     const canon = join(kitScripts, name);
     const dst = join(consumerScripts, name);
     if (exists(canon) && !exists(dst)) out.push({ name, canon, dst });

package/tools/script-priors.mjs

@@ -31,6 +31,8 @@ export const SCRIPT_PRIORS = Object.freeze([
   prior('check-docs-size.test.mjs', '4.0.0', '4.5.4', '88fbb3d7f097d74771b7c5d9ad99fcd58b274ae33f391e1ff01f4b138b9236cd'),
   prior('spec-schema.mjs', '4.6.0', '4.6.1', 'f8ee23d81e90fd4225ca4ece288cba41982c4430290bc6d033f5ca18d2d283f4'),
   prior('spec-schema.test.mjs', '4.6.0', '4.6.1', 'a12d6d3f5d32c6dabdee7e15af7d2ab15a0ced37515d1844fe0951f60cddbc99'),
+  prior('spec-schema.mjs', '4.7.0', '4.7.0', '40b5b038d5ec5ed53c327c6d269d22fe5fa2bed99ae711fbf84306ad047be452'),
+  prior('spec-schema.test.mjs', '4.7.0', '4.7.0', 'fde896419924223e54cfcabfdb1ef5807df5386fac700ed7c1463b6e7f81501b'),
 ]);
 
 export const digestOf = (bytes) => createHash('sha256').update(bytes).digest('hex');