@sabaiway/agent-workflow-kit 9.0.0 → 10.1.0

package/CHANGELOG.md

@@ -4,6 +4,75 @@ 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.
 
+## 10.1.0 — no work without a specification, and a ratchet that does not trust its own file (AD-121)
+
+A shipped tool that no LIVE contract claims is now a REFUSAL, not a preference. `tools/spec-coverage.mjs`
+(the rule) and `tools/spec-coverage-cli.mjs` (argv, fs and the one write) read each contract's own
+`## Module` list as the coverage map — coverage is never declared twice — and a project declares the
+check as a gate. Measured at adoption in this repo: 122 tool modules, 14 governed by a contract.
+
+The other 108 are owed, and what is owed is never STORED — it is a subtraction. `adopted` is the set
+measured once at adoption and never rewritten; `settled` names the adopted paths whose contract has
+since been written; the debt is the difference. So there is no list a hand can edit into a lie: the
+only editable claim is "this one was paid", and every run checks that claim against the contracts
+themselves — a settled path no live contract covers refuses, and refuses twice, because the tool is
+uncovered again. A stored debt list was the first design and a review killed it: `--write-debt`
+refusing to add a path guaranteed nothing while nobody was obliged to use it.
+
+The scope file is validated before it is used: a wrong schema, an empty `roots` or `extensions`, a
+non-string entry, or a census of ZERO files all refuse — a gate that passes because it looked at
+nothing is not a pass. Exclusions are path-component boundaries, so excluding `x/fixtures` never also
+hides `x/fixtures-escape.mjs`. `draft` and `retired` contracts cover nothing.
+
+Also in this release: `tools/spec-check.mjs` counts a scenario marker as a WHOLE ordinal, so a store
+reaching ten scenarios no longer refuses a correct binding while naming the wrong scenario
+(`spec:x/S1` used to occur twice the moment `spec:x/S11` was written beside it).
+
+## 10.0.0 — a symlinked docs file gets named instead of skipped (AD-119)
+
+Mirrors the memory canon: `references/scripts/check-docs-size.mjs` no longer lets a symlinked docs
+file leave the walk in silence. The predicate `entry.isFile()` is FALSE for a symlink and so is
+`isDirectory()`, so a symlinked `*.md` under `docs/ai` fell through both arms of the walk and was not
+even counted in the report's file total.
+
+> ### ⚠ BREAKING — a docs tree that was green can now go RED
+>
+> A symlink under `docs/ai` named `*.md`, or resolving to a directory, is 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
+> still ends the run as it always did, before any guard — unchanged by this release.) It 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.
+>
+> **When it bites.** Only a deployment that actually has such a symlink, and only once these bytes
+> reach its `scripts/`. `init` does NOT overwrite an existing deployed `check-docs-size.mjs`; the
+> paths that do land it are a fresh bootstrap, a `migrate-adr-store` refresh, and the `specs` ensure's
+> prior-matched refresh lane — which is what the catalog row below is for.
+>
+> **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. For a symlink on the NAVIGATOR's own
+> chain, note that regeneration is itself refused — `--write-index` cannot clear it, only replacing
+> the link can.
+
+**Deployments on the previous body stay upgradeable.** The prior catalog gains
+`check-docs-size.mjs` `4.6.0..6.0.0`, so a project still carrying that body classifies `prior`
+and remains inside the refresh lane instead of stranding as `custom` — which is what would otherwise
+withhold every write that lane gates.
+
+**Preserved, each pinned by its own arm.** A symlinked NON-`.md` regular file is still skipped; a
+tree with no symlink under `docs/ai` writes a byte-identical navigator; an over-cap REAL `adr/`
+record still collapses into the aggregate row, because the guard keys on the refusal and never on
+`errors.length`; and `walkMarkdownFiles` keeps its exact historical one-argument signature, which is
+why the parity-frozen spec file needed no edit.
+
+**Only `ENOENT` and `ENOTDIR` mean absence.** Every other `stat` code — `EACCES`, `EIO`, `ELOOP` from
+a symlink cycle — leaves the kind UNKNOWN and yields a named refusal carrying the code. Treating an
+unclassifiable link as a skip is exactly how the subtree behind it escapes again.
+
 ## 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,

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: '9.0.0'
+  version: '10.1.0'
 ---
 
 # agent-workflow-kit

package/capability.json

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

package/package.json

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