@sabaiway/agent-workflow-memory 4.2.0 → 4.4.0

package/CHANGELOG.md

@@ -4,6 +4,68 @@ 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.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,
+all in the drift-guarded shared block or the branches around it:
+
+- **The emitted coverage destination becomes `"${AW_GIT_DIR:?exported by run-gates}/…lcov.info"`.**
+  Where the runner injects the variable, behaviour is byte-identical; where a human pastes the cmd
+  into a bare shell, bash refuses loudly by name — the old form expanded to empty and wrote the
+  lcov to the filesystem root. Recognition stays APPEND-ONLY: every previously emitted form is
+  still recognised, so an old-form declaration migrates as `keep` with zero diff.
+- **The migration recognises the `lcovProducer` marker.** An optional gate-level boolean; only the
+  literal `true` is a producer claim, and producer-ness stays POSITIONAL — a marker on the coverage
+  checker itself never self-pairs. Strict schema validation of the key lives in the kit
+  (`gates-declaration.mjs`), which accepts it in lockstep with this release; the published 5.6.0
+  kit rejects a marker-carrying `gates.json` at exit 5 by design (forward-only; the kit's
+  Issue-016 note owns the cross-version statement).
+- **A vendored copy of a core check is PRESERVED instead of stopping the upgrade.** The
+  three-outcome claim classifier (`canonical` / `tool-elsewhere` / `not-the-tool`) routes a
+  shape-matching copy at a non-canonical realpath into a `keep` row plus separately rendered
+  verify metadata — exit 0, nothing auto-added, a zero-diff apply, with the preview stating the
+  verification instead of
+  claiming final-run-capability the runner would refuse. A genuine id-squatter still hard-stops.
+
+This package stays standalone — it imports nothing from the kit; the shared block is held equal by
+the text drift guard, never by an import.
+
 ## 4.2.0 — the gates migration stops handing you a coverage checker with nothing to read (AD-089)
 
 `migrate-gates.mjs` added the canonical `coverage-check` gate to any legacy declaration that lacked

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.2.0'
+  version: '4.4.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.2.0",
+  "version": "4.4.0",
   "provides": ["context"],
   "roles": {},
   "detect": {

package/package.json

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

@@ -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);
+    }
+  });
+});