@sabaiway/agent-workflow-memory 5.0.0 → 7.0.0

package/CHANGELOG.md

@@ -4,6 +4,104 @@ 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`).
 
+## 7.0.0 — a symlinked docs file gets named instead of skipped (AD-119)
+
+The docs cap-validator discovered files through `readdir(dir, { withFileTypes: true })` and kept an
+entry only when `entry.isFile()`. For a symlink that predicate is FALSE — and so is `isDirectory()`
+— so a symlinked `*.md` under `docs/ai` fell through BOTH arms of the walk and left it entirely.
+Probed: a temp tree holding a 14-line `real.md` under `maxLines: 3`, a `linked.md` pointing at it and
+an `escaped.md` pointing outside `docs/ai` reported `1 files inspected  —  1 error(s)`. No cap check,
+no missing-frontmatter error, no staleness check, no navigator row — and not counted in the file
+total either, which is what made it a lie rather than a gap.
+
+> ### ⚠ BREAKING — a docs tree that was green can now go RED
+>
+> A symlink under `docs/ai` named `*.md`, or resolving to a directory, is now a NAMED error row and
+> is never read.
+>
+> `--check-index` additionally runs the navigator's containment guard BEFORE it reads. On a chain
+> the walk can TRAVERSE, that guard rejects a symlink at the project root, `docs`, `docs/ai` or
+> `docs/ai/index.md` and exits 2 — where the mode used to compare and pass. It is the same guard
+> `--write-index` and `--ensure-index` already applied. (A chain the walk cannot traverse at all —
+> a dangling or unreadable `docs/ai` — still ends the run as it always did, before any guard; only
+> `--ensure-index` promises one named line there. That is unchanged by this release.)
+> Reading through a link matters because `buildIndex` drops the navigator's own row, so a symlinked
+> `index.md` whose target held the current bytes compared EQUAL and reported it fresh (measured:
+> exit 0 before, exit 2 after).
+>
+> **When it bites.** Only a deployment that actually has such a symlink — and only once these bytes
+> reach its `scripts/`, which happens on a fresh bootstrap, a `migrate-adr-store` refresh, a
+> prior-matched `specs` ensure, or a hand copy; installing this package does not overwrite an
+> existing deployed `check-docs-size.mjs`. Such a project sees `docs-caps` turn red with no edit of
+> its own. For a symlinked docs FILE, `docs-index` reds until the navigator is regenerated with that
+> link's row. For a symlink on the navigator's own chain the regeneration is itself REFUSED, so
+> `--write-index` cannot clear it — only replacing the link can.
+>
+> **Remedy.** Replace it with a real file or a real directory, whichever it stands for, or move it out
+> of `docs/ai`. The gate names the path and which case it is.
+
+**What is deliberately preserved.** A symlinked NON-`.md` regular file is still skipped, so the
+pinned `orchestration.json` skip is unchanged; a tree with no symlink under `docs/ai` writes a
+byte-identical navigator; and an over-cap REAL `adr/` record still collapses into the aggregate row,
+because the collapse guard keys on the refusal and never on `errors.length`. Each is pinned by its
+own arm.
+
+**Only `ENOENT` and `ENOTDIR` mean "nothing is there".** The name decides first — a link named `*.md`
+is refused with no `stat` at all — and only a differently named one is stat'ed, to learn whether it
+stands where a directory would and would hide a whole subtree. Every other code (`EACCES`, `EIO`,
+`ELOOP` from a symlink cycle) yields a named refusal carrying the code, because treating an
+unclassifiable link as a skip is how the subtree behind it escapes all over again.
+
+`walkMarkdownFiles` keeps its exact historical one-argument signature and contract: the `*.md` files
+a run may READ. A refused symlink is not one of them — it is a row, not a file.
+
+## 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`

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

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "5.0.0",
+  "version": "7.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/check-docs-size-cli.test.mjs

@@ -1,17 +1,62 @@
 // check-docs-size-cli.test.mjs — runCli branch pins the subprocess smokes cannot reach
 // in-process (Phase-5 coverage fill; the main spec file is parity-frozen, so these ride a
-// colocated file): the unknown-argument refusal and the pre-write symlink refusal on the index path.
+// colocated file): the unknown-argument refusal, the pre-write symlink refusal on the index path,
+// and the symlink refusals the WALK itself emits.
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, symlinkSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { runCli } from './check-docs-size.mjs';
 
-const cli = async (argv) => {
-  const { code, stdout, stderr } = await runCli(argv);
-  return { code, stdout, stderr };
+const cli = (argv) => runCli(argv);
+const DOC = (name, maxLines = 10) =>
+  `---\ntype: state\nlastUpdated: 2026-07-18\nscope: session\nstaleAfter: never\nowner: none\nmaxLines: ${maxLines}\n---\n\n# ${name}\n`;
+
+// One temp root per arm, always torn down: docs/ai holds one real `a.md`, and `build` adds
+// whatever the arm needs before the CLI runs.
+const withRoot = async (build, run) => {
+  const root = mkdtempSync(join(tmpdir(), 'cds-cli-'));
+  const docs = join(root, 'docs', 'ai');
+  try {
+    mkdirSync(docs, { recursive: true });
+    // A fixed package.json name, so the navigator's own bytes are deterministic across temp roots.
+    writeFileSync(join(root, 'package.json'), '{ "name": "probe-project" }\n');
+    writeFileSync(join(docs, 'a.md'), DOC('a'));
+    build({ root, docs });
+    await run({ root, docs });
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
 };
+const indexOf = (root) => readFileSync(join(root, 'docs', 'ai', 'index.md'), 'utf8');
+
+// The exact navigator a symlink-free probe tree writes. A characterization literal: the symlink
+// refusal must leave every byte of it — header, preamble, table, footer — untouched.
+const EXPECTED_INDEX = `---
+type: reference
+lastUpdated: 2026-07-18
+scope: permanent
+staleAfter: 30d
+owner: none
+maxLines: 80
+---
+
+# Memory Map — probe-project \`docs/ai/\`
+
+> **Auto-generated** — edit the source files' frontmatter, not this file. Regenerate after changes.
+> Layered context architecture:
+> **Always-loaded** — root \`AGENTS.md\` + this index.
+> **On-demand** — read a specific \`docs/ai/\` file when its "Read When" applies.
+> **Hierarchical** — subdirectory \`AGENTS.md\` files load when working in that folder.
+> **Archive** — \`history/recent.md\` (WARM) + \`history/condensed-index.md\` + per-month files.
+
+## Files
+
+| File | Type | Lines/Max | Updated | Stale after |
+|------|------|-----------|---------|-------------|
+| [\`a.md\`](./a.md) | state | 10/10 | 2026-07-18 | never |
+`;
 
 describe('check-docs-size runCli — refusal branches', () => {
   it('an unknown argument exits 2 naming it', async () => {
@@ -20,23 +65,216 @@ describe('check-docs-size runCli — refusal branches', () => {
     assert.match(stderr, /Unknown argument: --bogus/);
   });
 
-  it('--write-index refuses a symlinked index path BEFORE writing, naming the path', async () => {
-    const root = mkdtempSync(join(tmpdir(), 'cds-cli-'));
-    try {
-      mkdirSync(join(root, 'docs', 'ai'), { recursive: true });
-      writeFileSync(
-        join(root, 'docs', 'ai', 'a.md'),
-        '---\ntype: state\nlastUpdated: 2026-07-18\nscope: session\nstaleAfter: never\nowner: none\nmaxLines: 10\n---\n\n# a\n',
+  it('every mode refuses a symlinked navigator whose target holds the CURRENT bytes', async () => {
+    await withRoot(
+      () => {},
+      async ({ root, docs }) => {
+        // Write the real navigator, move its bytes to a target OUTSIDE docs/ai, and point index.md
+        // at them. Freshness now MATCHES, so an implementation that reads through the link and only
+        // complains when the comparison differs would pass: the refusal has to fire by NAME, before
+        // the read. A `/dev/null` target would have proved nothing but a mismatch.
+        const indexPath = join(docs, 'index.md');
+        const target = join(root, 'elsewhere-index.md');
+        await cli(['--write-index', `--root=${root}`, '--today=2026-07-18']);
+        writeFileSync(target, readFileSync(indexPath, 'utf8'));
+        rmSync(indexPath);
+        symlinkSync(target, indexPath);
+        const linked = new RegExp(`${indexPath} is a symlink`);
+        const c = await cli(['--check-index', `--root=${root}`, '--today=2026-07-18']);
+        assert.equal(c.code, 2, 'a symlinked navigator is REFUSED, never compared');
+        assert.match(c.stderr, linked);
+        const w = await cli(['--write-index', `--root=${root}`]);
+        assert.equal(w.code, 2);
+        assert.match(w.stderr, linked);
+        const d = await cli([`--root=${root}`]);
+        assert.equal(d.code, 1);
+        assert.match(d.stdout, /docs\/ai\/index\.md[\s\S]*?ERROR\s+is a symlink/);
+      },
+    );
+  });
+});
+
+describe('check-docs-size — a symlink under docs/ai is NAMED, never read', () => {
+  it('a link to a READABLE in-tree doc errors, its target is inspected once, and --report still exits 0', async () => {
+    await withRoot(
+      ({ docs }) => symlinkSync(join(docs, 'a.md'), join(docs, 'link.md')),
+      async ({ root }) => {
+        const { code, stdout } = await cli([`--root=${root}`]);
+        assert.equal(code, 1);
+        assert.match(stdout, /docs\/ai\/link\.md[\s\S]*?ERROR\s+is a symlink/);
+        assert.equal(stdout.match(/docs\/ai\/a\.md/g).length, 1, 'the target is inspected exactly once');
+        assert.match(stdout, /2 files inspected {2}— {2}1 error/, 'the refused link is counted');
+        const r = await cli(['--report', `--root=${root}`]);
+        assert.equal(r.code, 0);
+        assert.match(r.stdout, /ERROR\s+is a symlink/);
+      },
+    );
+  });
+
+  it('a symlinked DIRECTORY errors instead of hiding its subtree', async () => {
+    await withRoot(
+      ({ root, docs }) => {
+        mkdirSync(join(root, 'elsewhere'));
+        writeFileSync(join(root, 'elsewhere', 'hidden.md'), 'no frontmatter at all\n');
+        symlinkSync(join(root, 'elsewhere'), join(docs, 'history'));
+      },
+      async ({ root }) => {
+        const { code, stdout } = await cli([`--root=${root}`]);
+        assert.equal(code, 1);
+        assert.match(stdout, /docs\/ai\/history[\s\S]*?ERROR\s+is a symlink to a directory/);
+        assert.doesNotMatch(stdout, /hidden\.md/, 'the subtree behind the link is never walked');
+      },
+    );
+  });
+
+  // The name carries no regex metacharacter on purpose: a red-proof testId is matched as a pattern,
+  // and a literal star makes the arm unselectable (measured — the mint refused it as unresolvable).
+  it('a DANGLING doc link errors by NAME, never as an ENOENT stack trace', async () => {
+    await withRoot(
+      ({ docs }) => symlinkSync(join(docs, 'gone.md'), join(docs, 'dangling.md')),
+      async ({ root }) => {
+        const { code, stdout } = await cli([`--root=${root}`]);
+        assert.equal(code, 1);
+        assert.match(stdout, /docs\/ai\/dangling\.md[\s\S]*?ERROR\s+is a symlink/);
+        assert.doesNotMatch(stdout, /ENOENT/);
+      },
+    );
+  });
+
+  it('a link under adr/ gets its OWN index row and joins neither the collapse count nor its range', async () => {
+    await withRoot(
+      ({ docs }) => {
+        mkdirSync(join(docs, 'adr'));
+        writeFileSync(join(docs, 'adr', 'AD-001-real.md'), DOC('AD-001', 400));
+        writeFileSync(join(docs, 'adr', 'log.md'), DOC('log', 200));
+        symlinkSync(join(docs, 'adr', 'AD-001-real.md'), join(docs, 'adr', 'AD-999-link.md'));
+      },
+      async ({ root }) => {
+        assert.equal((await cli(['--write-index', `--root=${root}`])).code, 1);
+        assert.match(indexOf(root), /\| 1 records \|/, 'the real record is the only one counted');
+        assert.doesNotMatch(indexOf(root), /AD-999 \|/, 'the link never enters the id range');
+        assert.match(indexOf(root), /adr\/AD-999-link\.md/, 'the link renders its own row');
+      },
+    );
+  });
+
+  it('--check-index reds until the regenerated navigator carries the LINK row', async () => {
+    await withRoot(
+      () => {},
+      async ({ root, docs }) => {
+        // The BASELINE navigator is written first, with no link present, so the red below can only
+        // come from the added row — not from a missing index.md, which would let an implementation
+        // that merely checks the navigator EXISTS pass this arm.
+        await cli(['--write-index', `--root=${root}`, '--today=2026-07-18']);
+        assert.equal((await cli(['--check-index', `--root=${root}`])).code, 0, 'the baseline is fresh');
+        symlinkSync(join(docs, 'a.md'), join(docs, 'link.md'));
+        assert.equal((await cli(['--check-index', `--root=${root}`])).code, 1, 'the link makes it stale');
+        await cli(['--write-index', `--root=${root}`]);
+        assert.equal((await cli(['--check-index', `--root=${root}`])).code, 0);
+        assert.match(indexOf(root), /link\.md/);
+      },
+    );
+  });
+
+  // The PARTITION itself, both sides of it — not one example. ENOENT and ENOTDIR are the only codes
+  // that mean "nothing is there"; every other one leaves the kind UNKNOWN, and unknown must never
+  // read as skip, because that is how a link standing where a directory would, with a whole .md
+  // subtree behind it, escapes the gate again. An implementation that skipped EACCES, or that
+  // refused on ENOTDIR, passes a single-code arm and fails this one.
+  const STAT_CASES = [
+    { code: 'ELOOP', named: true },
+    { code: 'EACCES', named: true },
+    { code: 'EIO', named: true },
+    { code: 'ENOENT', named: false },
+    { code: 'ENOTDIR', named: false },
+  ];
+
+  it('a link whose kind cannot be determined is NAMED, never skipped', async () => {
+    for (const { code, named } of STAT_CASES) {
+      await withRoot(
+        ({ root, docs }) => {
+          mkdirSync(join(root, 'elsewhere'));
+          writeFileSync(join(root, 'elsewhere', 'hidden.md'), 'no frontmatter at all\n');
+          symlinkSync(join(root, 'elsewhere'), join(docs, 'history'));
+        },
+        async ({ root }) => {
+          const stat = async () => {
+            throw Object.assign(new Error(`${code}: injected`), { code });
+          };
+          const { code: exit, stdout } = await runCli([`--root=${root}`], { stat });
+          if (named) {
+            assert.equal(exit, 1, code);
+            assert.match(stdout, new RegExp(`docs/ai/history[\\s\\S]*?ERROR\\s+is a symlink this run could not classify \\(${code}\\)`), code);
+          } else {
+            assert.equal(exit, 0, code);
+            assert.doesNotMatch(stdout, /docs\/ai\/history/, code);
+          }
+          assert.doesNotMatch(stdout, /hidden\.md/, code);
+        },
       );
-      // The index path is a symlink into /dev/null: the contained write refuses to publish THROUGH
-      // the link (it would clobber the link target), names the path, and writes nothing.
-      const indexPath = join(root, 'docs', 'ai', 'index.md');
-      symlinkSync('/dev/null', indexPath);
-      const { code, stderr } = await cli(['--write-index', `--root=${root}`]);
-      assert.equal(code, 2);
-      assert.match(stderr, new RegExp(`${indexPath} is a symlink`));
-    } finally {
-      rmSync(root, { recursive: true, force: true });
     }
   });
 });
+
+// Characterization, GREEN before the refusal landed as well as after — these two pin what the
+// change must NOT move, so neither carries a red-proof record.
+describe('check-docs-size — what the symlink refusal preserves', () => {
+  it('a symlinked NON-.md regular file is still skipped', async () => {
+    await withRoot(
+      ({ root, docs }) => {
+        writeFileSync(join(root, 'orchestration.json'), '{ "plan-authoring": { "review": "reviewed" } }\n');
+        symlinkSync(join(root, 'orchestration.json'), join(docs, 'orchestration.json'));
+      },
+      async ({ root }) => {
+        const { code, stdout } = await cli([`--root=${root}`]);
+        assert.equal(code, 0);
+        assert.doesNotMatch(stdout, /orchestration\.json/);
+        assert.match(stdout, /1 files inspected {2}— {2}0 error/);
+      },
+    );
+  });
+
+  it('a DANGLING link that is not named .md is skipped — an unclassifiable link is not in scope', async () => {
+    await withRoot(
+      ({ root, docs }) => symlinkSync(join(root, 'never-existed.json'), join(docs, 'orchestration.json')),
+      async ({ root }) => {
+        // stat throws here, so the kind is unknowable — and the NAME never put it in scope, so it
+        // stays as skipped as a real non-.md file. Only a name-based refusal survives a failed stat.
+        const { code, stdout } = await cli([`--root=${root}`]);
+        assert.equal(code, 0);
+        assert.doesNotMatch(stdout, /orchestration\.json/);
+        assert.match(stdout, /1 files inspected {2}— {2}0 error/);
+      },
+    );
+  });
+
+  it('an OVER-CAP real adr/ record still collapses — the guard keys on the refusal, not on errors', async () => {
+    await withRoot(
+      ({ docs }) => {
+        mkdirSync(join(docs, 'adr'));
+        // 12 body lines under a maxLines of 5: a genuine cap ERROR on a genuine record.
+        writeFileSync(join(docs, 'adr', 'AD-001-fat.md'), DOC('AD-001', 5) + 'x\n'.repeat(12));
+        writeFileSync(join(docs, 'adr', 'log.md'), DOC('log', 200));
+      },
+      async ({ root }) => {
+        assert.equal((await cli(['--write-index', `--root=${root}`])).code, 1, 'the cap error still reds the run');
+        assert.match(indexOf(root), /\| 1 records \|/);
+        assert.doesNotMatch(indexOf(root), /AD-001-fat\.md/, 'an errored REAL record stays inside the collapse');
+      },
+    );
+  });
+
+  it('a tree with NO symlink under docs/ai writes a BYTE-IDENTICAL navigator', async () => {
+    await withRoot(
+      () => {},
+      async ({ root }) => {
+        const { code, stdout } = await cli([`--root=${root}`, '--today=2026-07-18', '--write-index']);
+        assert.equal(code, 0);
+        assert.match(stdout, /1 files inspected {2}— {2}0 error\(s\), 0 warning\(s\)/);
+        // The WHOLE file, not a filtered row: header, preamble, table and footer alike are what a
+        // symlink-free tree must keep producing.
+        assert.equal(indexOf(root), EXPECTED_INDEX);
+      },
+    );
+  });
+});

package/references/scripts/check-docs-size.mjs

@@ -178,23 +178,69 @@ export const parseStaleAfter = (value) => {
   return Number(m[1]);
 };
 
-// Discover the docs to validate: ONLY `*.md` files (recursively). Non-`.md` files — e.g. a hand-edited
-// `docs/ai/orchestration.json` config — are inherently skipped, so they are never subject to the
-// frontmatter / maxLines caps. Exported so that skip is pinned by a regression test.
-export const walkMarkdownFiles = async (dir) => {
-  const entries = await readdir(dir, { withFileTypes: true });
-  const files = [];
+// A symlink is neither `isFile()` nor `isDirectory()`, so it used to fall through BOTH arms of the
+// walk and leave it entirely — silently, not even counted in the report's file total. It is REFUSED
+// instead, and the NAME decides first: a link named `*.md` is refused with no stat at all, and only
+// a differently named one is stat'ed, to learn whether it stands where a directory would and would
+// therefore hide a whole subtree. A stat that throws leaves a link this run cannot classify, which
+// is a refusal only when the name already put it in scope — so a dangling `notes.txt` link stays as
+// out of scope as a real one. Refusing rather than FOLLOWING is deliberate: following would need
+// realpath, a containment test and a cycle guard, while the write side of this very module already
+// refuses to publish through a link (assertContainedNoSymlink).
+// The ONLY stat failures that mean "there is nothing there": the target is absent, or a path
+// component is not a directory. Every other code — EACCES, EIO, and ELOOP from a symlink cycle —
+// means the kind is UNKNOWN, and "unknown" must never read as "skip": that is how a link standing
+// where a directory would, with a whole `.md` subtree behind it, would silently escape again.
+const ABSENT_STAT_CODES = new Set(['ENOENT', 'ENOTDIR']);
+
+const symlinkRefusal = async (full, name, statPath) => {
+  if (name.endsWith('.md')) {
+    return 'is a symlink — the caps gate reads only real files it owns; replace it or move it out of docs/ai';
+  }
+  try {
+    if (!(await statPath(full)).isDirectory()) return null;
+  } catch (err) {
+    if (ABSENT_STAT_CODES.has(err?.code)) return null;
+    return `is a symlink this run could not classify (${err?.code ?? 'unknown'}) — it may stand where a directory would and hide a whole subtree; resolve it or move it out of docs/ai`;
+  }
+  return 'is a symlink to a directory — its whole subtree would escape the caps gate; replace it or move it out of docs/ai';
+};
+
+// Discover what the docs walk found: ONLY `*.md` files (recursively) plus the symlinks it refuses.
+// Non-`.md` files — e.g. a hand-edited `docs/ai/orchestration.json` config — are inherently skipped,
+// so they are never subject to the frontmatter / maxLines caps. Each entry is `{ path, refusal }`:
+// a refusal rides out as a row nobody reads, never as a file nobody sees.
+const walkDocsEntries = async (dir, deps = {}) => {
+  const readDir = deps.readdir ?? readdir;
+  const statPath = deps.stat ?? stat;
+  const entries = await readDir(dir, { withFileTypes: true });
+  const found = [];
   for (const entry of entries) {
     const full = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      files.push(...(await walkMarkdownFiles(full)));
+    if (entry.isSymbolicLink()) {
+      const refusal = await symlinkRefusal(full, entry.name, statPath);
+      if (refusal !== null) found.push({ path: full, refusal });
+    } else if (entry.isDirectory()) {
+      found.push(...(await walkDocsEntries(full, deps)));
     } else if (entry.isFile() && entry.name.endsWith('.md')) {
-      files.push(full);
+      found.push({ path: full, refusal: null });
     }
   }
-  return files;
+  return found;
 };
 
+// The historical export, signature and contract BOTH unchanged: the `*.md` files this run may READ,
+// as paths, from one argument. A refused symlink is not one of them — it is a row, not a file — so
+// the pinned non-`.md` skip still reads exactly as it always did. The entry walk above and the
+// comparator below stay private: they are this module's internals, and the injectable they carry has
+// no business in a deployed script's public surface.
+export const walkMarkdownFiles = async (dir) =>
+  (await walkDocsEntries(dir)).filter((entry) => entry.refusal === null).map((entry) => entry.path);
+
+// The walk's ORDER is unchanged: a bare `.sort()` over the old string list compared UTF-16 code
+// units, and `<`/`>` on strings compares them the same way.
+const byPath = (a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+
 export const computeToday = (todayStr) =>
   todayStr
     ? new Date(`${todayStr}T00:00:00Z`)
@@ -206,11 +252,19 @@ export const computeToday = (todayStr) =>
 const readSpecVerdict = (rel, text) =>
   rel.startsWith(SPECS_COLLAPSE.prefix) ? readSpecDocument(text, rel.slice(SPECS_COLLAPSE.prefix.length)) : null;
 
-export const inspectFile = async (filePath, today, root = ROOT) => {
+// Takes a walk entry; a bare path string still works, so a caller holding one file keeps its call.
+export const inspectFile = async (found, today, root = ROOT) => {
+  const filePath = typeof found === 'string' ? found : found.path;
+  const refusal = typeof found === 'string' ? null : found.refusal;
+  const rel = relative(root, filePath);
+  // A refused entry is REPORTED, never read — reading through the link is the whole thing being
+  // refused. `refused` rides the row so the navigator's collapse can keep it visible.
+  if (refusal) {
+    return { path: rel, lineCount: 0, frontmatter: null, spec: null, refused: true, errors: [refusal], warnings: [] };
+  }
   const text = await readFile(filePath, 'utf8');
   const lineCount = text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
   const fm = parseFrontmatter(text);
-  const rel = relative(root, filePath);
   const spec = readSpecVerdict(rel, text);
 
   if (!fm) {
@@ -330,8 +384,11 @@ const formatSpecsCollapseRow = (specRows) => {
   return `| ${link} | ${SPECS_COLLAPSE.type} | ${count('spec')} specs | ${count('part')} parts · ${count('index')} indexes | — |`;
 };
 
+// Membership keys on the REFUSAL, never on `errors.length`: a refused symlink is exactly the row
+// this gate exists to make visible, so it must not be absorbed into a count — while an over-cap or
+// frontmatter-less REAL record keeps collapsing as it always did, so no deployment's navigator moves.
 const COLLAPSE_GROUPS = [
-  { sortPath: ADR_DIR_PREFIX, isMember: (r) => r.path.startsWith(ADR_DIR_PREFIX) && (ADR_RECORD_RE.test(r.path) || r.path === ADR_NAV_PATH), format: formatAdrCollapseRow },
+  { sortPath: ADR_DIR_PREFIX, isMember: (r) => !r.refused && r.path.startsWith(ADR_DIR_PREFIX) && (ADR_RECORD_RE.test(r.path) || r.path === ADR_NAV_PATH), format: formatAdrCollapseRow },
   { sortPath: SPECS_COLLAPSE.prefix, isMember: (r) => Boolean(r.spec) && r.spec.errors.length === 0, format: formatSpecsCollapseRow },
 ];
 
@@ -398,15 +455,18 @@ const lstatNoFollow = (target, lstat) => {
 
 // The target is always DERIVED from `root` here (the navigator and its temp sibling), never handed
 // in by a caller, so there is no escape arm to guard: what remains is the no-follow walk.
-const assertContainedNoSymlink = (root, target, lstat) => {
+// `verb` names what the CALLER was about to do, because the refusal is now shared with a read-only
+// mode: `--check-index` compares the navigator's bytes, and a comparison that followed a link would
+// judge a file this deployment does not own.
+const assertContainedNoSymlink = (root, target, lstat, verb = 'write') => {
   const rel = relative(root, target);
   if (lstatNoFollow(root, lstat)?.isSymbolicLink()) {
-    throw refuse(`${root} is a symlink — refusing to write the navigator through it`);
+    throw refuse(`${root} is a symlink — refusing to ${verb} the navigator through it`);
   }
   rel.split(sep).filter(Boolean).reduce((walked, part) => {
     const current = join(walked, part);
     if (lstatNoFollow(current, lstat)?.isSymbolicLink()) {
-      throw refuse(`${current} is a symlink — refusing to write the navigator through it`);
+      throw refuse(`${current} is a symlink — refusing to ${verb} the navigator through it`);
     }
     return current;
   }, root);
@@ -452,7 +512,7 @@ const writeIndex = async (rows, today, meta, { root = ROOT, indexPath = INDEX_PA
 export const regenerateIndex = async (root, todayStr = null, deps = {}) => {
   const paths = pathsFor(root);
   const today = computeToday(todayStr);
-  const files = (await walkMarkdownFiles(paths.docsDir)).sort();
+  const files = (await walkDocsEntries(paths.docsDir, deps)).sort(byPath);
   const inspected = await Promise.all(files.map((f) => inspectFile(f, today, paths.root)));
   const rows = inspected.map(formatRow);
   const meta = await discoverMeta(paths.root);
@@ -474,7 +534,7 @@ const runEnsureIndex = async ({ root, docsDir, indexPath, today, deps }) => {
   let writing = false;
   try {
     assertContainedNoSymlink(root, indexPath, lstat);
-    const files = (await walkMarkdownFiles(docsDir)).sort();
+    const files = (await walkDocsEntries(docsDir, deps)).sort(byPath);
     const inspected = await Promise.all(files.map((file) => inspectFile(file, today, root)));
     const rows = inspected.map(formatRow);
     const meta = await discoverMeta(root, { strict: true, deps });
@@ -523,7 +583,7 @@ export const runCli = async (argv, deps = {}) => {
     return result(code);
   }
 
-  const files = (await walkMarkdownFiles(docsDir)).sort();
+  const files = (await walkDocsEntries(docsDir, deps)).sort(byPath);
   const inspected = await Promise.all(files.map((f) => inspectFile(f, today, root)));
   const rows = inspected.map(formatRow);
 
@@ -545,6 +605,16 @@ export const runCli = async (argv, deps = {}) => {
   }
 
   if (flags.checkIndex) {
+    // BEFORE the read, and by NAME: `buildIndex` drops the navigator's own row, so a symlinked
+    // index.md contributes nothing to compare against — and a link whose target happened to hold
+    // the current bytes would compare EQUAL and report the navigator fresh. Freshness can never
+    // see this one; only the containment walk can.
+    try {
+      assertContainedNoSymlink(root, indexPath, deps.lstat ?? lstatSync, 'read');
+    } catch (err) {
+      logError(`[check-docs-size] FAIL: ${indexPath}: ${err.message}`);
+      return result(2);
+    }
     const onDisk = existsSync(indexPath) ? await readFile(indexPath, 'utf8') : null;
     const { fresh } = checkIndexFreshness(rows, onDisk, meta);
     if (!fresh) {