@sabaiway/agent-workflow-memory 6.0.0 → 7.1.0

package/CHANGELOG.md

@@ -4,6 +4,71 @@ 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.1.0 — the rules template names the adoption state a zero relies on, and the upgrade skips only on no Node evidence (AD-123)
+
+`references/templates/agent_rules.md`: §1.2 no longer says "zero is legal during adoption" — a zero
+names the adoption state it relies on (not adopted, adopting, or nothing spec-covered touched); §2.5
+Communication gains its last bullet — a tool-composed `skipped-*` line whose stated reason the observed
+tree disproves is raised as a FINDING, never pasted as neutral, and a tool may not emit a skip it could
+itself disprove; §2.6 is the re-rendered engine 4.2.0 lens (the Spec-first bullet with the state
+clause). The kit's template twin moves byte-identically.
+
+`SKILL.md` upgrade step 2: the ADR enforcement pair and the spec layer skip ONLY when no Node evidence
+exists — no regular `package.json` at the root and none of the kit-seeded `scripts/*.mjs` present; a
+probe that cannot be read is a stated failure, never a skip. A deployment the kit itself made is
+therefore always recognized, whatever its stack.
+
+## 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

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: '6.0.0'
+  version: '7.1.0'
 ---
 
 # agent-workflow-memory
@@ -211,7 +211,9 @@ Fill strategy:
    **Same gate, also stamp-independent: ensure the ADR-store enforcement pair** — copy
    `archive-decisions.mjs` + `archive-decisions.test.mjs` from
    `${CLAUDE_SKILL_DIR}/references/scripts/` into the project's `scripts/` **if missing**
-   (preserve an existing file byte-for-byte; skip on a No-Node project). **Legacy-monolith
+   (preserve an existing file byte-for-byte; skip ONLY when no Node evidence exists — no
+   regular `package.json` at the root and none of the kit-seeded `scripts/*.mjs` present; a
+   probe that cannot be read is a stated failure, never a skip). **Legacy-monolith
    gate:** if a retired `docs/ai/history/decisions-archive*.md` monolith is still on disk, do
    **NOT** copy the pair as a silent ensure — the new-scheme rotator must **never sit beside
    un-migrated monoliths** (its default/`--check` runs refuse such a tree). Instead ASK the
@@ -225,8 +227,9 @@ Fill strategy:
    hook gains its `archive-decisions.mjs --check` line only when the hook is next refreshed via
    `node scripts/install-git-hooks.mjs`; an old hook without the line stays consistent-safe (the
    decisions gate is simply not enforced yet — never a broken hook). **Same gate, also
-   stamp-independent — ensure the SPEC LAYER (Node projects; skip on a No-Node project like the
-   pair above):** copy `spec-schema.mjs` + `spec-schema.test.mjs` from
+   stamp-independent — ensure the SPEC LAYER (skip only on the same absence of Node evidence as
+   the pair above — a deployed kit script is evidence enough):** copy `spec-schema.mjs` +
+   `spec-schema.test.mjs` from
    `${CLAUDE_SKILL_DIR}/references/scripts/` into the project's `scripts/` **if missing** (preserve
    an existing file byte-for-byte). Then seed `docs/ai/specs/index.md` **if missing** from
    `${CLAUDE_SKILL_DIR}/references/templates/specs/` (date filled; an existing root is preserved

package/capability.json

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

package/package.json

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

package/references/templates/agent_rules.md

@@ -23,7 +23,7 @@ Read in order, then confirm before starting:
 4. Confirm with the user: *"I'm taking task X. Confirm?"*
 
 ### 1.2. During Work
-**Before any feature:** name its governing spec(s) — the feature spec under `docs/ai/specs/` for every touched spec-covered slice (zero is legal during adoption; each cited spec's Out of scope bounds that slice's work). Where only a page spec (`docs/ai/pages/<page>.md`) exists it governs as an ADOPTION SHIM: state Out of scope + Revision inline in the plan. If the contract changes, the spec revision is authored WITH the plan (visible at review) and lands with the code, so docs and code never diverge.
+**Before any feature:** name its governing spec(s) — the feature spec under `docs/ai/specs/` for every touched spec-covered slice (a zero names the adoption state it relies on — not adopted, adopting, or nothing spec-covered touched; each cited spec's Out of scope bounds that slice's work). Where only a page spec (`docs/ai/pages/<page>.md`) exists it governs as an ADOPTION SHIM: state Out of scope + Revision inline in the plan. If the contract changes, the spec revision is authored WITH the plan (visible at review) and lands with the code, so docs and code never diverge.
 
 **For every code change:**
 1. Grep for similar implementations — reuse existing patterns.
@@ -74,13 +74,14 @@ Apply this as part of §2 before any user-facing summary:
 - **Large artifact (≈>100 lines):** deliver a real summary or the key excerpt inline **and** link the file — never flood the reader with a 2000-line paste, never hide the answer behind a bare pointer.
 - **Live host/session facts are tool-composed only.** Any claim about the current host or session state (prompts fired, sandbox scope, whether a bypass was needed, network reachability, approval counts) must trace to **live tool output** from **this session**; a memory/handover snapshot is **context, never report facts**, and a claim with no live signal is **omitted or explicitly marked unverified** — never asserted from recollection.
 - **The closing state block answers three DIFFERENT questions.** Close a user-facing message with three labelled slots — *now* · *what I need from you* · *what's next*. The slot LABELS stay ENGLISH — an English label is what lets a state-block checker FIND the block and its slots at all; everything written INTO a slot is in the project's dialogue language; when that language is not English, the checker's English phrase sets do not judge those values. **Now** = the state at this instant: what is RUNNING, or what the work is stopped on. It is **never a report of finished work** — what you completed goes in the message BODY, above the block. **From you** = the real unblocker, named; a turn that is ENDING always has one. **Next** = what follows. A *now* slot that opens with what was completed buries the one fact the reader opened the message for, and the three slots collapse into one restatement.
+- **A skip that contradicts the tree is a finding.** A tool-composed `skipped-*` line whose stated reason the observed tree disproves (a "no Node" skip beside deployed Node scripts) is raised as a FINDING in the report, never pasted as a neutral outcome — and a tool may not emit a skip whose reason it could itself disprove.
 
 ### 2.6. Planning, review & process-fidelity invariants
 Apply these when authoring a plan, reviewing, folding a finding, or editing code — the layer read **before any code change**. (Full canon: the project's planning / workflow-methodology + orchestration canon. This section is rendered from that canon and refreshed on upgrade; a custom edit is preserved verbatim, but flagged.)
 - **Fold by code, not prose.** Before folding a code-touching finding into a plan or change, read the cited `file:line` and cite it — a prose fold drifts from the code and seeds the next bug.
 - **Finding scope (plan-execution) — name the invariant BEFORE the edit.** During EXECUTION only — a plan under authoring has no shipped behaviour to call a live defect in, so plan-review carries none of this. Every finding names the invariant its fix would enforce, and where that invariant already lives decides the disposition: already an acceptance criterion of the phase → **fold here**; it would have to be ADDED → ship the **narrow fix** for the found site (red first, then green) and queue ONLY the generalization — a deferral row carries the invariant, the origin `file:line`, the narrow fix, its proof and a residual exposure declared NOT live; no correct narrow fix → **blocking**: the phase does not close, and it is **never queued**. Two bars declared before each round: a finding counts only if it changes a **WRITE/REMOVE decision** or is a false statement in shipped text; a repeat finding in one subarea **routes to SUBTRACTION**, not a fourth patch.
 - **Right altitude.** Pin intent + invariants + acceptance criteria (named tests); leave fine code-mechanics to Execute, where prose cannot diverge from reality.
-- **Spec-first.** A plan names its GOVERNING spec(s) — zero, one or many, one per touched spec-covered slice (the feature spec under `docs/ai/specs/`; page-only coverage governs as an ADOPTION SHIM, with Out of scope + Revision stated inline in the plan). Each cited spec's Out of scope bounds that slice's work and the plan's non-goals restate it per slice — no global union; a cross-spec conflict is resolved by a spec revision BEFORE approval, never by silent precedence. A NEW feature's draft spec exists AT plan review (a `create` row); a change to a governed contract rides the plan as its proposed revision (a `modify` row); approval confirms plan and contract atomically, and the revision lands with the code. Scenario bindings are per scenario: a new scenario is `unbound` until its test lands in the same plan, and a status never regresses for an extension.
+- **Spec-first.** A plan names its GOVERNING spec(s) — zero, one or many, one per touched spec-covered slice (the feature spec under `docs/ai/specs/`; page-only coverage governs as an ADOPTION SHIM, with Out of scope + Revision stated inline in the plan). A ZERO names the adoption state it relies on — `not adopted` (no store) or `adopting` (a store with no live contract), either with a recorded decline, or `nothing spec-covered touched` (a store with live contracts) — a bare zero is never a licence; the store's own state is what `status` and the upgrade advisor report. Each cited spec's Out of scope bounds that slice's work and the plan's non-goals restate it per slice — no global union; a cross-spec conflict is resolved by a spec revision BEFORE approval, never by silent precedence. A NEW feature's draft spec exists AT plan review (a `create` row); a change to a governed contract rides the plan as its proposed revision (a `modify` row); approval confirms plan and contract atomically, and the revision lands with the code. Scenario bindings are per scenario: a new scenario is `unbound` until its test lands in the same plan, and a status never regresses for an extension.
 - **No code-mechanics in the plan.** A ledger row carries its path and anchor, and Verification carries the exact commands (the plan-shape canon) — checked syntax: the plan's own Verification runs them against an explicit expected outcome or gate; the only other syntax a plan may carry is a literal fixture/schema fragment a named test copies or validates. Un-run, logic-bearing syntax — control-flow, a regex, a glob, a grammar, an algorithm body, a mini-DSL — never lives in plan prose, however plausible or shell-verified it looks: a fold or draft that wants one is the trigger to write the test instead.
 - **Test-as-spec.** Fold a code-touching finding into a red→green TEST, not a prose paragraph — the gate is the only deterministic checker; a paragraph cannot self-check.
 - **Characterize-first.** Before editing UNCOVERED code, pin its current behavior in a green test, then edit — any unintended change goes red. Never edit what has no checker; first give it one. Keep edits atomic/reversible; prefer SUBTRACTIVE folds.