@sabaiway/agent-workflow-memory 4.3.0 → 4.5.0

package/CHANGELOG.md

@@ -4,6 +4,60 @@ 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`).
 
+## 4.5.0 — the closing state block gets a canon rule, and its slot labels are declared English (AD-098; ships with kit 5.10.0)
+
+**Three slots that answer three different questions, or one restatement written three times.** The
+deployed rules template already asked for a closing state block; what it never said was what belongs
+in each slot — so *now* drifted into a report of finished work, and the block collapsed into a
+summary the reader had already read.
+
+- **`agent_rules.md` gains the rule, in §2.5.** *Now* is the state at this instant — what is running
+  or what the work is stopped on, never a report of what was completed (that belongs in the message
+  body, above the block). *From you* is the real unblocker, named; a turn that is ending always has
+  one. *Next* is what follows.
+- **The slot LABELS stay English; the values take the dialogue language.** 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 own language, and the checker's English phrase sets do not judge those values.
+  This is the substrate half of the same decision the kit's guard ships.
+- **One test point renamed to describe the check it actually runs** — the `--write-index` refusal is
+  a pre-write symlink refusal on the index path, which is what the body has pinned since 4.4.0.
+
+## 4.4.0 — the deploy finishes by writing the navigator its entry point declares (AD-096; ships with kit 5.9.0)
+
+**The substrate deployed an `AGENTS.md` that calls `docs/ai/index.md` always-loaded, and no step
+ever wrote it.** The navigator is generated — `check-docs-size.mjs` is its only writer — and neither
+bootstrap nor upgrade ran the generator, so a fresh Node deployment started life with a pre-commit
+hook failing its own index check, and a project without Node stayed silently broken. Fixed at the
+source: the generator gains an idempotent finalizer, and every documented path now runs it.
+
+- **`check-docs-size.mjs --ensure-index [--root=<dir>]`** — probe first, write only when the
+  navigator is missing or stale, and close with exactly ONE outcome line: `ensure-index:
+  regenerated` / `already-current` on stdout, or `write-refused` / `probe-failed` on stderr with
+  exit 2. It reuses the existing generator and freshness check — there is no second index
+  implementation, and no seed template that could drift from it.
+- **The bootstrap and upgrade prose run it at the LAST `docs/ai` mutation of each path:** after the
+  template fill (which covers a No-Node target — the generator runs from the skill home, so the
+  step-8 script copy is not a precondition), stamp-independently BEFORE the equal-head short-circuit
+  on upgrade, and again after the migrations before the re-stamp. Either refusal is a STOP.
+- **The write is contained and atomic.** Every component of `<root>/docs/ai/index.md` is lstat'ed
+  no-follow — a symlinked root, `docs`, `docs/ai` or leaf refuses by name — the body is published
+  through an exclusive-create temp renamed into place with the chain re-checked immediately before
+  the rename, and a failure ATTEMPTS the temp discard — never a name this run did not create, and a
+  cleanup that itself fails names the temp it could not remove instead of swallowing it. The
+  containment guard runs BEFORE the freshness read, so a symlink whose target happens to hold
+  current bytes is refused rather than reported "already current".
+- **"Could not read" never passes for "nothing there".** Under the finalizer, only a genuine
+  `ENOENT` counts as an absence; any other read failure refuses instead of publishing an index
+  missing whatever the run could not see. A malformed `package.json` stays the documented
+  project-name fallback.
+- **A closure guard** asserts every `docs/ai` reference in the entry-point template's Memory Map
+  resolves to a shipped template, a generated artifact whose finalizer the prose documents, or an
+  exact exception list — and the deploy fixture EXTRACTS the documented command from `SKILL.md` and
+  runs it, so a step that loses its finalizer line fails as a broken deployment.
+
+Known residual: a project that already carries `scripts/check-docs-size.mjs` keeps its un-hardened
+copy (the scripts ensure is create-only by contract) — repair rides the next lineage migration.
+
 ## 4.3.0 — the migration emits a destination that refuses by name, accepts the producer marker, and preserves a vendored core check (AD-092 + AD-093 + AD-094; ships with kit 5.7.0)
 
 The `migrate-gates.mjs` canon moves in lockstep with the kit it is byte-twinned to. Three changes,

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-memory
 description: Deploy or upgrade a portable AI-agent memory substrate in any project — an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) and a structured `docs/ai/` context store with cap/archive/index enforcement. Use when the user wants to bootstrap `docs/ai/`, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-memory` / `/agent-workflow-memory upgrade`. Triggers on "set up the memory system", "deploy the AI memory here", "bootstrap docs/ai", "upgrade the memory substrate". This is the substrate only — the workflow methodology (plan→execute→review, queue, Cleanup) is owned elsewhere and injected into AGENTS.md by the family composition root.
 disable-model-invocation: true
 metadata:
-  version: '4.3.0'
+  version: '4.5.0'
 ---
 
 # agent-workflow-memory
@@ -113,7 +113,15 @@ bootstrapping over a live system, but the user makes the final call.
    `docs/ai/autonomy.json` — the per-project autonomy policy, seeded SPARSE (the onboarding note
    only, defaults-equivalent — behavior changes only when the user declares levels). Keep each
    `.md` file's frontmatter.
-7. **Fill templates** per the table below.
+7. **Fill templates** per the table below. **Then materialize the navigator, as the last `docs/ai`
+   step:** the entry point declares `docs/ai/index.md` always-loaded and it is a GENERATED artifact
+   with no template, so run
+   `node ${CLAUDE_SKILL_DIR}/references/scripts/check-docs-size.mjs --ensure-index --root=<target>`
+   and relay its one outcome line (`ensure-index: regenerated` / `already-current`, or a
+   `write-refused` / `probe-failed` line naming the offending path — either is a STOP: resolve it
+   before reporting the deploy, since the navigator the entry point declares does not exist yet). The
+   generator runs from the **skill home**, so a **No-Node target** is covered too: the operator's own
+   host runs it, and step 8's copy is not a precondition.
 8. **Install enforcement (Node projects).** Copy `${CLAUDE_SKILL_DIR}/references/scripts/*.mjs`
    (+ `*.test.mjs`) into the project's `scripts/`. **No Node runtime** → skip this + the hook;
    follow the cap/archive/index policy manually.
@@ -214,7 +222,14 @@ Fill strategy:
    the tree untouched and report the pending migration. The deployed pre-commit
    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). **Then**, if the stamp **equals** the head → the substrate is
+   decisions gate is simply not enforced yet — never a broken hook). **Same gate, also
+   stamp-independent — ensure the NAVIGATOR:** `docs/ai/index.md` is a GENERATED artifact the entry
+   point declares always-loaded, so a deployment that never had one must gain it even at head — run
+   `node ${CLAUDE_SKILL_DIR}/references/scripts/check-docs-size.mjs --ensure-index --root=<target>`
+   and relay its outcome line. It writes only when the navigator is missing or stale
+   (`already-current` otherwise), so a re-run changes nothing; a `write-refused` (the write) or
+   `probe-failed` (the tree could not be read) line names the offending path and STOPs this
+   reconcile like any other failed ensure. **Then**, if the stamp **equals** the head → the substrate is
    current (no structure migration is due), and stop after reporting. Report **in the user's
    conversational language**: if step 2's reconcile just **changed something** (a footprint move /
    config seed), say **what changed** in plain terms and ask before committing; if **nothing changed at
@@ -242,7 +257,10 @@ Fill strategy:
    absent (a legacy `AGENTS.md`), gracefully **no-op** on that slot (adding a slot to
    already-deployed files is the composition root's reconcile, not this substrate's job). On any
    malformed marker state (single, reversed, nested, or duplicate pair), **no-op with an error** —
-   never edit.
+   never edit. **Then, before the stamp, re-run the navigator finalizer:** steps 4–6 may have added
+   or changed `docs/ai` files, so run
+   `node ${CLAUDE_SKILL_DIR}/references/scripts/check-docs-size.mjs --ensure-index --root=<target>`
+   once more (idempotent — an untouched tree reports `already-current`) and relay its outcome line.
 7. **Re-stamp** `docs/ai/.memory-version` to the lineage head (atomic write — mechanics unchanged).
    Report changes **in plain human terms** (which parts of the deployment are now different);
    **omit the raw structure number**, and do not recite the two-axes note here (it belongs to

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "4.3.0",
+  "version": "4.5.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,6 +1,6 @@
 // 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 written-empty-index guard.
+// colocated file): the unknown-argument refusal and the pre-write symlink refusal on the index path.
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from 'node:fs';
@@ -20,7 +20,7 @@ describe('check-docs-size runCli — refusal branches', () => {
     assert.match(stderr, /Unknown argument: --bogus/);
   });
 
-  it('--write-index landing on a sink path (index stat size 0) is the loud written-empty refusal', async () => {
+  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 });
@@ -28,12 +28,13 @@ describe('check-docs-size runCli — refusal branches', () => {
         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',
       );
-      // The index path is a symlink into /dev/null: the write lands, the stat reads size 0 —
-      // the guard must refuse loudly instead of reporting a written index.
-      symlinkSync('/dev/null', join(root, 'docs', 'ai', 'index.md'));
+      // 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, /index\.md was written empty/);
+      assert.match(stderr, new RegExp(`${indexPath} is a symlink`));
     } finally {
       rmSync(root, { recursive: true, force: true });
     }

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

@@ -0,0 +1,332 @@
+// check-docs-size-ensure.test.mjs — the navigator WRITE contract (containment + atomic publication)
+// and the idempotent `--ensure-index` finalizer mode. A separate file because the main spec pair is
+// suite-parity-frozen; single responsibility: what the write refuses, and what the mode reports.
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, readdirSync, symlinkSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runCli } from './check-docs-size.mjs';
+
+const DOC = (title) =>
+  `---\ntype: state\nlastUpdated: 2026-08-15\nscope: session\nstaleAfter: never\nowner: none\nmaxLines: 10\n---\n\n# ${title}\n`;
+
+const makeTree = (prefix) => {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  mkdirSync(join(dir, 'docs', 'ai'), { recursive: true });
+  writeFileSync(join(dir, 'docs', 'ai', 'a.md'), DOC('a'));
+  return dir;
+};
+
+const drop = (...dirs) => {
+  for (const dir of dirs) rmSync(dir, { recursive: true, force: true });
+};
+
+const tempFiles = (docsAi) => readdirSync(docsAi).filter((name) => name.endsWith('.tmp'));
+
+describe('check-docs-size navigator write — containment', () => {
+  it('refuses a symlinked index.md, exit 2, naming the path', async () => {
+    const root = makeTree('cds-leaf-');
+    const target = mkdtempSync(join(tmpdir(), 'cds-leaf-target-'));
+    try {
+      const indexPath = join(root, 'docs', 'ai', 'index.md');
+      symlinkSync(join(target, 'sink.md'), indexPath);
+      const { code, stderr } = await runCli(['--write-index', `--root=${root}`]);
+      assert.equal(code, 2);
+      assert.match(stderr, /symlink/);
+      assert.ok(stderr.includes(indexPath), `refusal must name ${indexPath}, got: ${stderr}`);
+    } finally {
+      drop(root, target);
+    }
+  });
+
+  it('refuses a symlinked docs/ai, exit 2, naming the path', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'cds-docsai-'));
+    const real = mkdtempSync(join(tmpdir(), 'cds-docsai-real-'));
+    try {
+      mkdirSync(join(root, 'docs'), { recursive: true });
+      writeFileSync(join(real, 'a.md'), DOC('a'));
+      symlinkSync(real, join(root, 'docs', 'ai'));
+      const { code, stderr } = await runCli(['--write-index', `--root=${root}`]);
+      assert.equal(code, 2);
+      assert.ok(stderr.includes(join(root, 'docs', 'ai')), `refusal must name the symlinked dir, got: ${stderr}`);
+    } finally {
+      drop(root, real);
+    }
+  });
+
+  it('refuses a symlinked docs, exit 2, naming the path', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'cds-docs-'));
+    const real = mkdtempSync(join(tmpdir(), 'cds-docs-real-'));
+    try {
+      mkdirSync(join(real, 'ai'), { recursive: true });
+      writeFileSync(join(real, 'ai', 'a.md'), DOC('a'));
+      symlinkSync(real, join(root, 'docs'));
+      const { code, stderr } = await runCli(['--write-index', `--root=${root}`]);
+      assert.equal(code, 2);
+      assert.ok(stderr.includes(join(root, 'docs')), `refusal must name the symlinked dir, got: ${stderr}`);
+    } finally {
+      drop(root, real);
+    }
+  });
+
+  it('refuses a symlinked project root, exit 2, naming the path', async () => {
+    const real = makeTree('cds-root-real-');
+    const host = mkdtempSync(join(tmpdir(), 'cds-root-host-'));
+    const link = join(host, 'project');
+    try {
+      symlinkSync(real, link);
+      const { code, stderr } = await runCli(['--write-index', `--root=${link}`]);
+      assert.equal(code, 2);
+      assert.ok(stderr.includes(link), `refusal must name the symlinked root, got: ${stderr}`);
+    } finally {
+      drop(real, host);
+    }
+  });
+
+  it('writes an absent index rather than refusing it', async () => {
+    const root = makeTree('cds-absent-');
+    try {
+      const { code } = await runCli(['--write-index', `--root=${root}`]);
+      assert.equal(code, 0);
+      assert.ok(existsSync(join(root, 'docs', 'ai', 'index.md')));
+    } finally {
+      drop(root);
+    }
+  });
+
+  // The temp name is exclusive-create for a reason: a collision means the name is SOMEONE ELSE's
+  // file, which this run never wrote and must never delete.
+  it('never removes a temp name it lost the exclusive-create race for', async () => {
+    const root = makeTree('cds-collision-');
+    const removed = [];
+    try {
+      const { code, stderr } = await runCli(['--write-index', `--root=${root}`], {
+        writeFile: () => {
+          throw Object.assign(new Error('EEXIST: file already exists'), { code: 'EEXIST' });
+        },
+        rm: (target) => { removed.push(target); },
+      });
+      assert.equal(code, 2);
+      assert.match(stderr, /EEXIST/);
+      assert.deepEqual(removed, [], 'a collision is not this run\'s file to discard');
+    } finally {
+      drop(root);
+    }
+  });
+
+  it('discards the temp when the write itself dies mid-flight', async () => {
+    const root = makeTree('cds-partial-');
+    const removed = [];
+    try {
+      const { code } = await runCli(['--write-index', `--root=${root}`], {
+        writeFile: () => {
+          throw Object.assign(new Error('EIO: i/o error'), { code: 'EIO' });
+        },
+        rm: (target) => { removed.push(target); },
+      });
+      assert.equal(code, 2);
+      assert.equal(removed.length, 1, 'the partially-created temp is the run\'s own to discard');
+      assert.match(removed[0], /\.tmp$/);
+    } finally {
+      drop(root);
+    }
+  });
+
+  it('names the temp it could not remove instead of swallowing the cleanup failure', async () => {
+    const root = makeTree('cds-cleanup-');
+    try {
+      const { code, stderr } = await runCli(['--write-index', `--root=${root}`], {
+        rename: () => {
+          throw Object.assign(new Error('EXDEV: cross-device link'), { code: 'EXDEV' });
+        },
+        rm: () => {
+          throw Object.assign(new Error('EPERM: operation not permitted'), { code: 'EPERM' });
+        },
+      });
+      assert.equal(code, 2);
+      assert.match(stderr, /could not be removed/);
+      assert.match(stderr, /\.tmp/);
+    } finally {
+      drop(root);
+    }
+  });
+
+  it('leaves no temp file and no index behind when the publication fails', async () => {
+    const root = makeTree('cds-tmp-');
+    try {
+      const { code } = await runCli(['--write-index', `--root=${root}`], {
+        rename: () => {
+          throw Object.assign(new Error('injected publication failure'), { code: 'EIO' });
+        },
+      });
+      assert.equal(code, 2);
+      assert.deepEqual(tempFiles(join(root, 'docs', 'ai')), []);
+      assert.equal(existsSync(join(root, 'docs', 'ai', 'index.md')), false);
+    } finally {
+      drop(root);
+    }
+  });
+});
+
+describe('check-docs-size --ensure-index', () => {
+  it('reports regenerated and materializes the navigator on a fresh tree', async () => {
+    const root = makeTree('cds-ensure-fresh-');
+    try {
+      const { code, stdout } = await runCli(['--ensure-index', `--root=${root}`]);
+      assert.equal(code, 0);
+      assert.match(stdout, /ensure-index: regenerated/);
+      const { code: checkCode } = await runCli(['--check-index', `--root=${root}`]);
+      assert.equal(checkCode, 0);
+    } finally {
+      drop(root);
+    }
+  });
+
+  it('reports already-current on a second run and leaves the bytes identical', async () => {
+    const root = makeTree('cds-ensure-idem-');
+    try {
+      await runCli(['--ensure-index', `--root=${root}`]);
+      const first = readFileSync(join(root, 'docs', 'ai', 'index.md'), 'utf8');
+      const { code, stdout } = await runCli(['--ensure-index', `--root=${root}`, '--today=2027-01-01']);
+      assert.equal(code, 0);
+      assert.match(stdout, /ensure-index: already-current/);
+      assert.equal(readFileSync(join(root, 'docs', 'ai', 'index.md'), 'utf8'), first);
+    } finally {
+      drop(root);
+    }
+  });
+
+  // A symlink whose TARGET happens to hold the current bytes reads as fresh through the link — so a
+  // freshness-first finalizer would report `already-current` over a file it would never write
+  // through: an exit 0 that proves nothing about the deployment's own navigator.
+  it('refuses a symlinked navigator even when its target holds the CURRENT bytes', async () => {
+    const root = makeTree('cds-ensure-symlink-fresh-');
+    try {
+      const indexPath = join(root, 'docs', 'ai', 'index.md');
+      await runCli(['--ensure-index', `--root=${root}`]);
+      const current = readFileSync(indexPath, 'utf8');
+      rmSync(indexPath);
+      const target = join(root, 'elsewhere-index.md');
+      writeFileSync(target, current);
+      symlinkSync(target, indexPath);
+
+      const { code, stdout, stderr } = await runCli(['--ensure-index', `--root=${root}`]);
+      assert.equal(code, 2, `a symlinked navigator must be refused, got: ${stdout}${stderr}`);
+      assert.match(stderr, /ensure-index: write-refused/);
+      assert.equal(readFileSync(target, 'utf8'), current, 'the link target is untouched');
+    } finally {
+      drop(root);
+    }
+  });
+
+  // The two refusals name STAGES: a reader told the PROBE failed will go looking at the tree, while
+  // a write that died may have left the navigator half-published.
+  it('reports a WRITE failure as write-refused, never as a failed probe', async () => {
+    const root = makeTree('cds-write-stage-');
+    try {
+      const { code, stderr } = await runCli(['--ensure-index', `--root=${root}`], {
+        writeFile: () => {
+          throw Object.assign(new Error('EIO: i/o error'), { code: 'EIO' });
+        },
+        rm: () => {},
+      });
+      assert.equal(code, 2);
+      assert.match(stderr, /ensure-index: write-refused/);
+      assert.match(stderr, /EIO/);
+    } finally {
+      drop(root);
+    }
+  });
+
+  // "Could not read" is not "nothing there": a finalizer that swallowed the difference would publish
+  // a navigator missing whatever it failed to see, and report success over it.
+  it('refuses a tree it cannot fully read instead of writing an incomplete navigator', async () => {
+    const root = makeTree('cds-strict-meta-');
+    try {
+      const { code, stderr } = await runCli(['--ensure-index', `--root=${root}`], {
+        readdir: () => {
+          throw Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' });
+        },
+      });
+      assert.equal(code, 2);
+      assert.match(stderr, /ensure-index: probe-failed/);
+      assert.match(stderr, /EACCES/);
+      assert.equal(existsSync(join(root, 'docs', 'ai', 'index.md')), false, 'nothing written over a tree it could not read');
+    } finally {
+      drop(root);
+    }
+  });
+
+  // "Unknown" must not read as "empty" either: a reader that throws WITHOUT an fs code is still not
+  // evidence that the tree is absent, so the finalizer refuses rather than publishing a short index.
+  it('refuses a code-less read failure too, instead of treating it as an absence', async () => {
+    const root = makeTree('cds-codeless-');
+    try {
+      const { code, stderr } = await runCli(['--ensure-index', `--root=${root}`], {
+        readdir: () => {
+          throw new Error('the injected reader failed without an fs code');
+        },
+      });
+      assert.equal(code, 2);
+      assert.match(stderr, /ensure-index: probe-failed/);
+      assert.equal(existsSync(join(root, 'docs', 'ai', 'index.md')), false);
+    } finally {
+      drop(root);
+    }
+  });
+
+  it('a MALFORMED package.json stays the documented basename fallback, never a refusal', async () => {
+    const root = makeTree('cds-badpkg-');
+    try {
+      writeFileSync(join(root, 'package.json'), '{ not json');
+      const { code, stdout } = await runCli(['--ensure-index', `--root=${root}`]);
+      assert.equal(code, 0, 'authored content that is malformed is not an unreadable tree');
+      assert.match(stdout, /ensure-index: regenerated/);
+    } finally {
+      drop(root);
+    }
+  });
+
+  it('closes with ONE named probe-failed line when the tree cannot be read', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'cds-ensure-nodocs-'));
+    try {
+      const { code, stderr } = await runCli(['--ensure-index', `--root=${root}`]);
+      assert.equal(code, 2);
+      assert.match(stderr, /ensure-index: probe-failed/);
+      assert.equal(/at .*check-docs-size/.test(stderr), false, 'a named refusal, never a stack trace');
+    } finally {
+      drop(root);
+    }
+  });
+
+  it('reports a named write-refused, exit 2, when the write cannot be published', async () => {
+    const root = makeTree('cds-ensure-refused-');
+    const target = mkdtempSync(join(tmpdir(), 'cds-ensure-refused-target-'));
+    try {
+      const indexPath = join(root, 'docs', 'ai', 'index.md');
+      symlinkSync(join(target, 'sink.md'), indexPath);
+      const { code, stderr } = await runCli(['--ensure-index', `--root=${root}`]);
+      assert.equal(code, 2);
+      assert.match(stderr, /ensure-index: write-refused/);
+      assert.ok(stderr.includes(indexPath), `the refusal must name ${indexPath}, got: ${stderr}`);
+    } finally {
+      drop(root, target);
+    }
+  });
+
+  it('reports regenerated when the on-disk navigator went stale', async () => {
+    const root = makeTree('cds-ensure-stale-');
+    try {
+      await runCli(['--ensure-index', `--root=${root}`]);
+      writeFileSync(join(root, 'docs', 'ai', 'b.md'), DOC('b'));
+      const { code, stdout } = await runCli(['--ensure-index', `--root=${root}`]);
+      assert.equal(code, 0);
+      assert.match(stdout, /ensure-index: regenerated/);
+      const { code: checkCode } = await runCli(['--check-index', `--root=${root}`]);
+      assert.equal(checkCode, 0);
+    } finally {
+      drop(root);
+    }
+  });
+});

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

@@ -12,6 +12,11 @@
 //   --check-index     verify docs/ai/index.md is in sync with source frontmatter;
 //                     exit 1 (and print how to fix) if stale. Catches the silent
 //                     drift `--write-index` is supposed to prevent.
+//   --ensure-index    the idempotent finalizer every deploy/upgrade path runs after its last
+//                     docs/ai mutation: probe, write only when the navigator is missing or stale,
+//                     print ONE outcome line (`ensure-index: regenerated|already-current` on
+//                     stdout; `ensure-index: write-refused|probe-failed — <path>: …` on stderr).
+//                     Exit 0 on either written state, 2 on a named refusal — never a stack trace.
 //
 // CLI overrides:
 //   --today=YYYY-MM-DD (default today UTC) — useful for tests / reproducible runs
@@ -19,10 +24,11 @@
 //                      hook passes it so a rotation regenerates the right project's index
 //   --quiet            print only failures (and final summary)
 
-import { readFile, writeFile, readdir, stat } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { dirname, resolve, relative, join, basename } from 'node:path';
+import { readFile, writeFile, readdir, stat, rename, rm } from 'node:fs/promises';
+import { existsSync, lstatSync } from 'node:fs';
+import { dirname, resolve, relative, join, basename, sep } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { randomBytes } from 'node:crypto';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -34,10 +40,17 @@ const INDEX_PATH = resolve(DOCS_DIR, 'index.md');
 // (this deployment's own root); `--root=<dir>` and the exported `regenerateIndex(root, today)`
 // override them so the ADR-rotation hook (archive-decisions.mjs) and hermetic tests can regenerate
 // an arbitrary root's index without ever touching the real repo tree.
-const pathsFor = (root) => ({ root, docsDir: resolve(root, 'docs/ai'), indexPath: resolve(root, 'docs/ai/index.md') });
+const pathsFor = (root) => {
+  const base = resolve(root);
+  return { root: base, docsDir: resolve(base, 'docs/ai'), indexPath: resolve(base, 'docs/ai/index.md') };
+};
 
 const MS_PER_DAY = 24 * 60 * 60 * 1000;
 
+// The one token every `--ensure-index` outcome line opens with — deploy/upgrade prose relays it
+// verbatim and the kit's ensure op reads it, so it is a contract, not a message.
+const ENSURE_INDEX_PREFIX = 'ensure-index:';
+
 // Project-name + footer links for the index are auto-discovered (no hardcoding):
 //   project name  ← package.json "name" (fallback: repo dir basename)
 //   hierarchical  ← every AGENTS.md / CLAUDE.md below the repo root
@@ -45,18 +58,30 @@ const MS_PER_DAY = 24 * 60 * 60 * 1000;
 const DEFAULT_PROJECT_NAME = 'this project';
 const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'dist-ssr', 'coverage', 'build', '.next']);
 
-const walkForName = async (dir, name, acc = [], depth = 0) => {
+// `strict` is the finalizer's lens on the SAME walk: for a report, an unreadable subtree is fairly
+// skipped, but a run that WRITES the navigator may not silently treat "could not read" as "nothing
+// there" — it would publish an index missing whatever it could not see and call that success. Only
+// a genuine ENOENT stays an absence; every other fs error propagates.
+// Only a genuine ENOENT is an absence. A code-LESS throw (an injected reader, a wrapped client) is
+// not evidence of absence either, so it propagates too — "unknown" must never read as "empty".
+const rethrowUnlessAbsent = (err, strict) => {
+  if (strict && err?.code !== 'ENOENT') throw err;
+};
+
+const walkForName = async (dir, name, acc = [], depth = 0, strict = false, deps = {}) => {
   if (depth > 6) return acc;
+  const readDir = deps.readdir ?? readdir;
   let entries;
   try {
-    entries = await readdir(dir, { withFileTypes: true });
-  } catch {
+    entries = await readDir(dir, { withFileTypes: true });
+  } catch (err) {
+    rethrowUnlessAbsent(err, strict);
     return acc;
   }
   for (const entry of entries) {
     if (entry.isDirectory()) {
       if (SKIP_DIRS.has(entry.name)) continue;
-      await walkForName(join(dir, entry.name), name, acc, depth + 1);
+      await walkForName(join(dir, entry.name), name, acc, depth + 1, strict, deps);
     } else if (entry.isFile() && entry.name === name) {
       acc.push(join(dir, entry.name));
     }
@@ -64,16 +89,29 @@ const walkForName = async (dir, name, acc = [], depth = 0) => {
   return acc;
 };
 
-export const discoverMeta = async (root = ROOT) => {
+export const discoverMeta = async (root = ROOT, { strict = false, deps = {} } = {}) => {
+  const read = deps.readFile ?? readFile;
+  const readDir = deps.readdir ?? readdir;
   let projectName = basename(root);
+  // The READ and the PARSE are separate on purpose: an unreadable package.json is a tree this run
+  // could not see (strict propagates it), while a MALFORMED one is authored content — the basename
+  // fallback, under strict too.
+  let manifest = null;
   try {
-    const pkg = JSON.parse(await readFile(resolve(root, 'package.json'), 'utf8'));
-    if (pkg.name) projectName = pkg.name;
-  } catch {
-    /* no package.json — keep dir basename */
+    manifest = await read(resolve(root, 'package.json'), 'utf8');
+  } catch (err) {
+    rethrowUnlessAbsent(err, strict);
   }
-  const agentsFiles = await walkForName(root, 'AGENTS.md');
-  const claudeFiles = await walkForName(root, 'CLAUDE.md');
+  if (manifest !== null) {
+    try {
+      const pkg = JSON.parse(manifest);
+      if (pkg.name) projectName = pkg.name;
+    } catch {
+      /* malformed package.json — keep the dir basename */
+    }
+  }
+  const agentsFiles = await walkForName(root, 'AGENTS.md', [], 0, strict, deps);
+  const claudeFiles = await walkForName(root, 'CLAUDE.md', [], 0, strict, deps);
   const rootAgents = resolve(root, 'AGENTS.md');
   const rootClaude = resolve(root, 'CLAUDE.md');
   // A subdir typically holds AGENTS.md plus a CLAUDE.md symlink to it — list each
@@ -91,26 +129,28 @@ export const discoverMeta = async (root = ROOT) => {
     .map((rel) => `[\`${rel}\`](../../${rel})`);
   let onDemandLinks = [];
   try {
-    const skillDirs = await readdir(resolve(root, '.agents/skills'), { withFileTypes: true });
+    const skillDirs = await readDir(resolve(root, '.agents/skills'), { withFileTypes: true });
     onDemandLinks = skillDirs
       .filter((dirent) => dirent.isDirectory() && /-(patterns|commands)$/.test(dirent.name))
       .map((dirent) => dirent.name)
       .sort()
       .map((name) => `[\`${name}\`](../../.agents/skills/${name}/SKILL.md)`);
-  } catch {
-    /* no .agents/skills — omit the section */
+  } catch (err) {
+    // No .agents/skills — omit the section (under strict, only a real absence may omit it).
+    rethrowUnlessAbsent(err, strict);
   }
   return { projectName, hierarchicalLinks, onDemandLinks };
 };
 
 // Pure argv parser (no I/O, no exit): `help` / `error` ride out as data for runCli to render.
 const parseArgs = (argv) => {
-  const flags = { report: false, writeIndex: false, checkIndex: false, quiet: false };
+  const flags = { report: false, writeIndex: false, checkIndex: false, ensureIndex: false, quiet: false };
   const opts = { today: null, root: null };
   for (const arg of argv) {
     if (arg === '--report') flags.report = true;
     else if (arg === '--write-index') flags.writeIndex = true;
     else if (arg === '--check-index') flags.checkIndex = true;
+    else if (arg === '--ensure-index') flags.ensureIndex = true;
     else if (arg === '--quiet') flags.quiet = true;
     else if (arg.startsWith('--today=')) opts.today = arg.slice('--today='.length);
     else if (arg.startsWith('--root=')) opts.root = arg.slice('--root='.length);
@@ -334,9 +374,74 @@ export const checkIndexFreshness = (rows, onDiskText, meta = {}) => {
   return { fresh: expected === onDiskText, expected };
 };
 
-const writeIndex = async (rows, today, meta, indexPath = INDEX_PATH) => {
+// The navigator is a GENERATED artifact, so its write must land on the deployment's own file and
+// nowhere else: every component of <root>/docs/ai/index.md is lstat'ed no-follow (a symlinked root,
+// `docs`, `docs/ai` or leaf REFUSES — publishing through one would clobber whatever it points at),
+// the body goes out through a unique exclusive-create temp renamed into place with the chain
+// re-checked immediately before the rename, and the temp never survives a failure. The kit runs the
+// same discipline in atomic-write.mjs; this deployment script ships dependency-free, so the
+// semantics are REIMPLEMENTED here rather than imported.
+export const INDEX_WRITE_REFUSED = 'INDEX_WRITE_REFUSED';
+const refuse = (message) => Object.assign(new Error(message), { code: INDEX_WRITE_REFUSED });
+
+const lstatNoFollow = (target, lstat) => {
+  try {
+    return lstat(target);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+};
+
+// 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) => {
+  const rel = relative(root, target);
+  if (lstatNoFollow(root, lstat)?.isSymbolicLink()) {
+    throw refuse(`${root} is a symlink — refusing to write 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`);
+    }
+    return current;
+  }, root);
+};
+
+const writeIndex = async (rows, today, meta, { root = ROOT, indexPath = INDEX_PATH, deps = {} } = {}) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const write = deps.writeFile ?? writeFile;
+  const publish = deps.rename ?? rename;
+  const remove = deps.rm ?? rm;
+  const uniqueSuffix = deps.rand ?? (() => randomBytes(6).toString('hex'));
   const body = buildIndex(rows, today.toISOString().slice(0, 10), meta);
-  await writeFile(indexPath, body, 'utf8');
+  assertContainedNoSymlink(root, indexPath, lstat);
+  const tmp = `${indexPath}.${uniqueSuffix()}.tmp`;
+  assertContainedNoSymlink(root, tmp, lstat);
+  const discardTemp = async (err) => {
+    try {
+      await remove(tmp, { force: true });
+    } catch (cleanupErr) {
+      throw refuse(`${err.message} — and its temp file could not be removed, delete it by hand: ${tmp} (${cleanupErr.message})`);
+    }
+    throw err;
+  };
+  try {
+    await write(tmp, body, { encoding: 'utf8', flag: 'wx' });
+  } catch (err) {
+    // EEXIST means the name is SOMEONE ELSE's file: exclusive-create refused, this run wrote
+    // nothing, and removing it would delete a file we never made. Every other failure can leave a
+    // partial temp behind, and that one is ours to discard.
+    if (err && err.code === 'EEXIST') throw err;
+    await discardTemp(err);
+  }
+  try {
+    assertContainedNoSymlink(root, indexPath, lstat);
+    await publish(tmp, indexPath);
+  } catch (err) {
+    await discardTemp(err);
+  }
 };
 
 // regenerateIndex(root, todayStr) — the ONE reused generator, root-parameterized (item (h)). It runs
@@ -344,15 +449,46 @@ const writeIndex = async (rows, today, meta, indexPath = INDEX_PATH) => {
 // (default this deployment). The ADR-rotation hook reaches it via the CLI (`--write-index --root=…`);
 // hermetic tests call it directly. `todayStr` is 'YYYY-MM-DD' (null → today). Returns the written
 // index path + row count. No second index implementation exists.
-export const regenerateIndex = async (root, todayStr = null) => {
-  const { docsDir, indexPath } = pathsFor(root);
+export const regenerateIndex = async (root, todayStr = null, deps = {}) => {
+  const paths = pathsFor(root);
   const today = computeToday(todayStr);
-  const files = (await walkMarkdownFiles(docsDir)).sort();
-  const inspected = await Promise.all(files.map((f) => inspectFile(f, today, root)));
+  const files = (await walkMarkdownFiles(paths.docsDir)).sort();
+  const inspected = await Promise.all(files.map((f) => inspectFile(f, today, paths.root)));
   const rows = inspected.map(formatRow);
-  const meta = await discoverMeta(root);
-  await writeIndex(rows, today, meta, indexPath);
-  return { indexPath, files: rows.length };
+  const meta = await discoverMeta(paths.root);
+  await writeIndex(rows, today, meta, { root: paths.root, indexPath: paths.indexPath, deps });
+  return { indexPath: paths.indexPath, files: rows.length };
+};
+
+// The finalizer promises its caller EXACTLY ONE outcome line, so every step it owns — the walk, the
+// metadata discovery, the freshness read and the write — runs inside one classified error path: an
+// unreadable docs/ai is a NAMED refusal, never a stack trace. The containment guard runs BEFORE the
+// freshness read for the same reason `already-present` needs a kind probe: a symlinked navigator
+// whose target happens to hold current bytes would otherwise report `already-current` over a file
+// this mode refuses to write through — an exit 0 proving nothing about the deployment's own file.
+const runEnsureIndex = async ({ root, docsDir, indexPath, today, deps }) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const read = deps.readFile ?? readFile;
+  const line = (token) => `${ENSURE_INDEX_PREFIX} ${token} — ${relative(root, indexPath)}`;
+  // The two refusals name STAGES, not error codes: once the write has been entered, ANY failure —
+  // a containment refusal, EIO, EACCES — is a write refusal, because that is what the reader has to
+  // act on. A raw fs error reported as a failed PROBE would send them to the wrong half of the run.
+  let writing = false;
+  try {
+    assertContainedNoSymlink(root, indexPath, lstat);
+    const files = (await walkMarkdownFiles(docsDir)).sort();
+    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 });
+    const onDisk = existsSync(indexPath) ? await read(indexPath, 'utf8') : null;
+    if (checkIndexFreshness(rows, onDisk, meta).fresh) return { code: 0, out: line('already-current') };
+    writing = true;
+    await writeIndex(rows, today, meta, { root, indexPath, deps });
+    return { code: 0, out: line('regenerated') };
+  } catch (err) {
+    const cause = writing || err?.code === INDEX_WRITE_REFUSED ? 'write-refused' : 'probe-failed';
+    return { code: 2, err: `${ENSURE_INDEX_PREFIX} ${cause} — ${indexPath}: ${err.message}` };
+  }
 };
 
 // The return-code entry point (no process.argv / process.exit / console inside): argv[] →
@@ -370,7 +506,7 @@ export const runCli = async (argv, deps = {}) => {
 
   const { flags, opts, help, error } = parseArgs(argv);
   if (help) {
-    log('Usage: check-docs-size.mjs [--report|--write-index|--check-index] [--today=YYYY-MM-DD] [--root=<dir>] [--quiet]');
+    log('Usage: check-docs-size.mjs [--report|--write-index|--check-index|--ensure-index] [--today=YYYY-MM-DD] [--root=<dir>] [--quiet]');
     return result(0);
   }
   if (error) {
@@ -379,6 +515,16 @@ export const runCli = async (argv, deps = {}) => {
   }
   const { root, docsDir, indexPath } = pathsFor(opts.root ? resolve(opts.root) : (deps.root ?? ROOT));
   const today = computeToday(opts.today);
+
+  // The finalizer owns its whole pipeline (above), so it returns BEFORE the shared walk: a tree the
+  // walk would throw on must still close with one outcome line.
+  if (flags.ensureIndex) {
+    const { code, out, err } = await runEnsureIndex({ root, docsDir, indexPath, today, deps });
+    if (out) log(out);
+    if (err) logError(err);
+    return result(code);
+  }
+
   const files = (await walkMarkdownFiles(docsDir)).sort();
   const inspected = await Promise.all(files.map((f) => inspectFile(f, today, root)));
   const rows = inspected.map(formatRow);
@@ -386,7 +532,12 @@ export const runCli = async (argv, deps = {}) => {
   const meta = flags.writeIndex || flags.checkIndex ? await discoverMeta(root) : null;
 
   if (flags.writeIndex) {
-    await writeIndex(rows, today, meta, indexPath);
+    try {
+      await writeIndex(rows, today, meta, { root, indexPath, deps });
+    } catch (err) {
+      logError(`[check-docs-size] FAIL: ${indexPath}: ${err.message}`);
+      return result(2);
+    }
     log(`Wrote ${relative(root, indexPath)}`);
     const after = await stat(indexPath);
     if (after.size === 0) {

package/references/templates/agent_rules.md

@@ -73,6 +73,7 @@ Apply this as part of §2 before any user-facing summary:
 - **No condescension, no filler.** Own a miss plainly and fix it in the same message.
 - **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.
 
 ### 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.)