@sabaiway/agent-workflow-kit 5.7.0 → 5.9.0

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/shared/composition-handoff.md

@@ -59,3 +59,13 @@ a body matching the current canon is reported *already current*; a body matching
 is refreshed; a custom body is preserved + noted; an absent section is a stated note (never an
 insert); an over-cap refresh is refused; and an unreadable bundled template canon is its own
 loud STOP naming the kit reinstall command.
+
+**Navigator finalizer (runs in BOTH paths, AFTER the lens reconcile above).** `docs/ai/index.md` is
+a GENERATED artifact the entry point declares always-loaded, and the reconcile above may have just
+rewritten a `docs/ai` file — so the finalizer runs at the LAST `docs/ai` mutation of the deploy,
+before the stamp and the report. ONE command:
+`node ${CLAUDE_SKILL_DIR}/references/scripts/check-docs-size.mjs --ensure-index --root=<project>`.
+Relay its one outcome line (*regenerated* / *already current*); a `write-refused` (the write) or
+`probe-failed` (the tree could not be read) line names the offending path and is a loud STOP,
+never a note. It is idempotent, so an earlier run in the
+delegated path (the substrate's own fill step) is never a reason to skip it here.

package/tools/doc-parity.mjs

@@ -56,7 +56,7 @@ import { COVERAGE_PRODUCER_BODY } from './coverage-producer.mjs';
 // tool renames or drops must fail here rather than leave the doc teaching a vocabulary nobody emits.
 // Imported from the VOCABULARY leaf, never from the ops: a read-only lint must not pull the ensure
 // implementation — and through it the orchestration writer — into its import graph.
-import { RELAYED_ENSURE_TOKENS } from './ensure-vocabulary.mjs';
+import { RELAYED_ENSURE_TOKENS, RELAYED_FAILURE_CAUSES } from './ensure-vocabulary.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -138,6 +138,10 @@ export const BINDINGS = Object.freeze([
   // free. Now one command performs them and the doc enumerates its tokens — backticked, so a bare
   // word in a sentence cannot pass for the pinned outcome.
   ...RELAYED_ENSURE_TOKENS.map((token) => valueBinding(`ensure-outcome:${token}`, token, `\`${token}\``, [UPGRADE_DOC])),
+  // And the CAUSE half of the same promise (index-navigator hotfix / D9): the doc says a `failed`
+  // line OPENS with its cause, so every word that can open one is pinned into the doc that relays it
+  // — otherwise a new cause ships with no doc anyone could have read. Backticked, same reason.
+  ...RELAYED_FAILURE_CAUSES.map((cause) => valueBinding(`ensure-cause:${cause}`, cause, `\`${cause}\``, [UPGRADE_DOC])),
   // The "the tool knows and does not say" contract: a clean-tree PASS must still name a latent arm.
   // It was a prose-only bar a doc could silently drop, so it is pinned to the live string the tool
   // actually emits — a reworded doc dropping the notice fails this pin plus the gate.

package/tools/ensure-configs.mjs

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
-// ensure-configs.mjs — ONE runnable command for the four stamp-independent upgrade ensures:
+// ensure-configs.mjs — ONE runnable command for the five stamp-independent upgrade ensures:
 //
 //   orchestration  docs/ai/orchestration.json  seed, or refresh a still-canonical onboarding note
 //   gates          docs/ai/gates.json          seed-if-missing (an existing declaration is authored content)
 //   autonomy       docs/ai/autonomy.json       seed-if-missing (same)
 //   scripts        scripts/<ADR enforcement>   seed-if-missing, ADR-layout detect FIRST
+//   index          docs/ai/index.md            regenerate-if-missing-or-stale (a GENERATED artifact)
 //
 // Each was prose in references/modes/upgrade.md that an agent performed by hand. One command instead
 // of four is deliberate: four independent runs would be four chances to skip one, and the mode doc now
@@ -39,20 +40,25 @@ const EXIT_USAGE = 2;
 const fail = (exitCode, message) => Object.assign(new Error(message), { exitCode });
 
 const EMPTY_CWD = '--cwd needs a path argument (an empty value would silently mean the current directory)';
+const EMPTY_ONLY = `--only needs one operation name (${ENSURE_OPS.join(' | ')}) — an empty value would silently widen the run`;
+const REPEATED_ONLY = '--only was passed more than once — this selector names exactly ONE operation';
+const unknownOp = (value) => `--only ${value}: no such operation (${ENSURE_OPS.join(' | ')}) — nothing was run`;
 
-const HELP = `ensure-configs — the four stamp-independent upgrade ensures, as ONE command.
+const HELP = `ensure-configs — the five stamp-independent upgrade ensures, as ONE command.
 
 Usage:
-  node ensure-configs.mjs --reconcile [--dry-run] [--cwd <project>]
+  node ensure-configs.mjs --reconcile [--dry-run] [--only <op>] [--cwd <project>]
 
-  --reconcile   required — run the four ensures (orchestration, gates, autonomy, scripts)
+  --reconcile   required — run the five ensures (${ENSURE_OPS.join(', ')})
   --dry-run     report what each ensure WOULD do; write nothing
+  --only <op>   run EXACTLY ONE of them (an unknown, missing or repeated value is a usage error)
   --cwd <dir>   the target project (default: the current directory)
   --help, -h    this help
 
-Every seed is CREATE-ONLY: an existing file is preserved byte-for-byte, never clobbered and never
-refreshed in place. The one refresh is the orchestration onboarding note, and only while it still
-matches a canonical the kit shipped — your own wording is preserved verbatim. The enforcement-script
+Every SEED is CREATE-ONLY: an existing file is preserved byte-for-byte, never clobbered and never
+refreshed in place. Two ops refresh instead: the orchestration onboarding note, only while it still
+matches a canonical the kit shipped (your own wording is preserved verbatim), and the navigator
+index — a GENERATED artifact, regenerated whenever it is missing or stale. The enforcement-script
 ensure detects an older ADR-store layout FIRST and instructs the opt-in migration instead of seeding.
 
 Exit codes: 0 every op fine; 1 an op failed (its line says so) or there is no deployment here; 2 usage.`;
@@ -60,13 +66,24 @@ Exit codes: 0 every op fine; 1 an op failed (its line says so) or there is no de
 // argv → { reconcile, dryRun, cwd, help }. Order-independent; an unknown flag or a missing --cwd
 // value is a usage error, never a silently-ignored argument.
 export const parseArgs = (argv) => {
-  const out = { reconcile: false, dryRun: false, cwd: undefined, help: false };
+  const out = { reconcile: false, dryRun: false, cwd: undefined, only: undefined, help: false };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === '--help' || a === '-h') out.help = true;
     else if (a === '--reconcile') out.reconcile = true;
     else if (a === '--dry-run') out.dryRun = true;
-    else if (a === '--cwd') {
+    else if (a === '--only' || a.startsWith('--only=')) {
+      // A selector that cannot be honoured EXACTLY as asked is a usage error, never a wider run:
+      // narrowing is the whole point, so a missing value, a repeat, or an op that does not exist
+      // must stop the run before any op writes.
+      if (out.only !== undefined) throw fail(EXIT_USAGE, REPEATED_ONLY);
+      const inline = a.startsWith('--only=');
+      const value = inline ? a.slice('--only='.length) : argv[i + 1];
+      if (value === undefined || value === '' || (!inline && value.startsWith('-'))) throw fail(EXIT_USAGE, EMPTY_ONLY);
+      if (!ENSURE_OPS.includes(value)) throw fail(EXIT_USAGE, unknownOp(value));
+      out.only = value;
+      if (!inline) i += 1;
+    } else if (a === '--cwd') {
       // An EMPTY value resolves to the ambient cwd — a writing CLI would then act on a different
       // project than the caller named, silently. Both spellings refuse it.
       const next = argv[i + 1];
@@ -88,8 +105,8 @@ export const parseArgs = (argv) => {
 // Run every op in ENSURE_OPS order. A throw from one op becomes THAT op's failed outcome — the
 // remaining ops still run, because a project missing its gate declaration should not also be left
 // without its autonomy seed just because the first ensure hit an unreadable file.
-export const runEnsures = ({ cwd, kitRoot, dryRun, deps }) =>
-  ENSURE_OPS.map((op) => {
+export const runEnsures = ({ cwd, kitRoot, dryRun, deps, only }) =>
+  (only ? [only] : ENSURE_OPS).map((op) => {
     try {
       return ENSURE_IMPLEMENTATIONS[op]({ cwd, kitRoot, dryRun, deps });
     } catch (err) {
@@ -97,10 +114,11 @@ export const runEnsures = ({ cwd, kitRoot, dryRun, deps }) =>
     }
   });
 
-const render = (outcomes, dryRun) => {
+const render = (outcomes, dryRun, only) => {
   // The banner names the tool + the flag it ran under (both machine tokens the L2 rule exempts);
   // the failure footer is a user-grade sentence — the composed-lines guard scans both.
-  const lines = [dryRun ? 'ensure-configs (--reconcile, dry run — nothing written)' : 'ensure-configs (--reconcile)'];
+  const scope = only ? `, --only ${only}` : '';
+  const lines = [dryRun ? `ensure-configs (--reconcile${scope}, dry run — nothing written)` : `ensure-configs (--reconcile${scope})`];
   for (const o of outcomes) {
     lines.push(`  ${o.op}: ${o.token}`);
     for (const detail of o.lines) lines.push(`      ${detail}`);
@@ -122,10 +140,10 @@ export const main = (argv = [], ctx = {}) => {
     // ONE deployment gate for the whole run (see the header): with no docs/ai there is nothing to
     // reconcile, and four identical STOPs would read as four separate problems.
     assertDocsAiDeployment(cwd, deps, { noun: 'the project configuration', rel: 'under docs/ai' });
-    const outcomes = runEnsures({ cwd, kitRoot: ctx.kitRoot ?? KIT_ROOT, dryRun: args.dryRun, deps });
+    const outcomes = runEnsures({ cwd, kitRoot: ctx.kitRoot ?? KIT_ROOT, dryRun: args.dryRun, deps, only: args.only });
     return {
       code: outcomes.some((o) => o.failed) ? EXIT_FAILED : EXIT_OK,
-      stdout: render(outcomes, args.dryRun),
+      stdout: render(outcomes, args.dryRun, args.only),
       stderr: '',
     };
   } catch (err) {

package/tools/ensure-ops.mjs

@@ -1,4 +1,4 @@
-// ensure-ops.mjs — the FOUR upgrade ensure operations, one function each, behind one shared outcome
+// ensure-ops.mjs — the FIVE upgrade ensure operations, one function each, behind one shared outcome
 // shape. The CLI that orders and runs them is ensure-configs.mjs; this module owns what each ensure
 // DOES and, more importantly, what it is allowed to CLAIM.
 //
@@ -23,6 +23,7 @@
 // Dependency-free, Node >= 22. Every fs primitive is injectable (deps.*). No side effects on import.
 
 import { readFileSync, lstatSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import { join } from 'node:path';
 import { CANON_README, CONFIG_REL, SEED_CONFIG, loadConfig, normalizeCanonical, refreshReadme } from './orchestration-config.mjs';
 import { seedConfig, writeConfig } from './orchestration-write.mjs';
@@ -41,6 +42,7 @@ export {
   DRY_RUN_TOKENS,
   FAILURE_CAUSES,
   RELAYED_ENSURE_TOKENS,
+  RELAYED_FAILURE_CAUSES,
   SEED_SCRIPTS,
   WRITE_TOKENS,
 } from './ensure-vocabulary.mjs';
@@ -275,10 +277,86 @@ export const ensureScripts = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
   return outcome('scripts', anyCreated ? 'seeded' : 'already-present', lines, false);
 };
 
+// ── 5. docs/ai/index.md — the GENERATED navigator, regenerated when missing or stale ───────────────
+
+// The only ensure whose target is generated rather than authored: there is nothing to preserve, and
+// nothing to seed from either — the bundled generator IS the writer, driven through its idempotent
+// finalizer mode. Sync-over-async by the same precedent the ADR rotator uses (spawnSync the CLI):
+// the ensure framework is synchronous, and a second index implementation here would be the drift
+// the one-generator rule exists to prevent.
+const INDEX_REL = 'docs/ai/index.md';
+const GENERATOR_PATH = ['references', 'scripts', 'check-docs-size.mjs'];
+const ENSURE_INDEX_OUTCOME = /^ensure-index: (regenerated|already-current)\b/m;
+const ENSURE_INDEX_REFUSAL = /^ensure-index: (write-refused|probe-failed)\b/m;
+// The probe has no machine line, so its two ANSWERS are matched against the canonical sentences it
+// composes — anchored, not a loose substring: a failure that merely CONTAINS "is stale" (a path, an
+// error quoting the checker's own advice) would otherwise pass for a stale verdict and fail OPEN.
+const PROBE_FRESH = /^\[check-docs-size\] OK — .+ is in sync with source frontmatter\./m;
+const PROBE_STALE = /^\[check-docs-size\] FAIL: .+ is stale \(out of sync with source frontmatter\)\./m;
+// Only the LAUNCH and the pre-write probe are provably zero-write. Once the generator has run, a
+// failure must say that a write may already have landed — the reader's next step depends on it.
+const MAY_HAVE_WRITTEN = 'the navigator may already have been written — re-read it before re-running';
+
+const describeExit = (result) => (result.signal ? `on signal ${result.signal}` : `with code ${result.status}`);
+const bothStreams = (result) => `${String(result.stdout ?? '')}${String(result.stderr ?? '')}`.trim();
+
+export const ensureIndex = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const spawn = deps.spawnSync ?? spawnSync;
+  const generator = join(kitRoot, ...GENERATOR_PATH);
+  const drive = (mode) => spawn(process.execPath, [generator, mode, `--root=${cwd}`], { encoding: 'utf8' });
+  const unlaunchable = (result) =>
+    loud('index', 'generator-unlaunchable', `${INDEX_REL}: the bundled generator could not be started, so nothing was probed or written — reinstall the kit. ${causeOf(result.error)}`);
+
+  const probe = probeSeedTarget(join(cwd, INDEX_REL), lstat);
+  if (probe.wrongKind) {
+    return loud('index', 'wrong-node-kind', `${INDEX_REL}: exists but is ${probe.wrongKind} — the navigator is a generated file and this is not one; nothing was read or written, resolve it by hand and re-run`);
+  }
+
+  if (dryRun) {
+    const check = drive('--check-index');
+    if (check.error) return unlaunchable(check);
+    const out = bothStreams(check);
+    if (check.status === 0 && PROBE_FRESH.test(out)) return ok('index', 'already-current', `${INDEX_REL}: in sync with the source frontmatter — nothing would be written`);
+    if (check.status === 1 && PROBE_STALE.test(out)) return ok('index', 'would-regenerate', `${INDEX_REL}: missing or stale — would be written from the source frontmatter`);
+    return loud('index', 'index-probe-failed', `${INDEX_REL}: the freshness probe answered neither fresh nor stale (exited ${describeExit(check)}), so nothing was written. ${out}`);
+  }
+
+  const run = drive('--ensure-index');
+  if (run.error) return unlaunchable(run);
+  const outcome = String(run.stdout ?? '').match(ENSURE_INDEX_OUTCOME);
+  const refusal = String(run.stderr ?? '').match(ENSURE_INDEX_REFUSAL);
+  if (run.status === 2 && refusal) {
+    // The generator's OWN closed refusals: a write it would not publish, and a probe that could not
+    // answer. Each keeps its identity here rather than collapsing into "the generator failed".
+    const cause = refusal[1] === 'write-refused' ? 'write-refused' : 'index-probe-failed';
+    return loud('index', cause, `${INDEX_REL}: ${bothStreams(run)}`);
+  }
+  if (run.status !== 0 || !outcome) {
+    return loud('index', 'generator-failed', `${INDEX_REL}: the generator exited ${describeExit(run)} without a recognized outcome line — ${MAY_HAVE_WRITTEN}. ${bothStreams(run)}`);
+  }
+  if (outcome[1] === 'already-current') return ok('index', 'already-current', `${INDEX_REL}: in sync with the source frontmatter — nothing written`);
+
+  // A claimed regeneration is not a verified one: re-probe, so `regenerated` names a state this run
+  // PROVED rather than a line the generator printed. The verdict is read from the probe's own two
+  // ANSWERS — an exit code alone would turn a probe that merely FAILED (exit 1 on an unreadable
+  // tree) into a false "still stale after the write".
+  const verify = drive('--check-index');
+  const verdict = verify.error ? '' : bothStreams(verify);
+  if (!verify.error && verify.status === 0 && PROBE_FRESH.test(verdict)) {
+    return ok('index', 'regenerated', `${INDEX_REL}: written from the source frontmatter — the navigator is in sync again`);
+  }
+  if (!verify.error && verify.status === 1 && PROBE_STALE.test(verdict)) {
+    return loud('index', 'index-stale-after-write', `${INDEX_REL}: the generator reported a regeneration, but the re-probe still reads the navigator as missing or stale — ${MAY_HAVE_WRITTEN}. ${verdict}`);
+  }
+  return loud('index', 'index-probe-failed', `${INDEX_REL}: the generator reported a regeneration, but the verifying probe answered neither fresh nor stale — ${MAY_HAVE_WRITTEN}. ${verify.error ? causeOf(verify.error) : verdict}`);
+};
+
 // The op table the CLI walks — name → implementation, in ENSURE_OPS order.
 export const ENSURE_IMPLEMENTATIONS = Object.freeze({
   orchestration: ensureOrchestration,
   gates: ensureGates,
   autonomy: ensureAutonomy,
   scripts: ensureScripts,
+  index: ensureIndex,
 });

package/tools/ensure-vocabulary.mjs

@@ -8,12 +8,12 @@
 // read-only tool's import graph. Vocabulary here, behaviour in ensure-ops.mjs.
 
 // The FIXED order the CLI runs them in — the order references/modes/upgrade.md already prescribed.
-export const ENSURE_OPS = Object.freeze(['orchestration', 'gates', 'autonomy', 'scripts']);
+export const ENSURE_OPS = Object.freeze(['orchestration', 'gates', 'autonomy', 'scripts', 'index']);
 
 // Tokens that assert a WRITE happened. --dry-run may never emit one of these (the CLI's contract test
 // walks this set), and each has exactly one `would-` counterpart below.
-export const WRITE_TOKENS = Object.freeze(['seeded', 'note-refreshed']);
-export const DRY_RUN_TOKENS = Object.freeze(['would-seed', 'would-refresh-note']);
+export const WRITE_TOKENS = Object.freeze(['seeded', 'note-refreshed', 'regenerated']);
+export const DRY_RUN_TOKENS = Object.freeze(['would-seed', 'would-refresh-note', 'would-regenerate']);
 
 // The CLOSED outcome vocabulary. Closed at RUNTIME, not by convention: composing an outcome with a
 // token outside this list throws, so an op cannot quietly invent a word the mode doc has never heard
@@ -43,8 +43,21 @@ export const FAILURE_CAUSES = Object.freeze([
   'wrong-node-kind',
   'write-refused',
   'unexpected-error',
+  // The navigator ensure drives a SEPARATE PROCESS (the bundled generator), so its failures split by
+  // how far that process got: it never launched · it launched and did not succeed · the freshness
+  // probe itself could not answer · it claimed a regeneration the re-probe still finds stale. Only
+  // the first and third are provably pre-mutation; the other two DISCLOSE a possible partial write.
+  'generator-unlaunchable',
+  'generator-failed',
+  'index-probe-failed',
+  'index-stale-after-write',
 ]);
 
+// The causes the mode doc must TEACH, so an agent relaying a `failed` line knows every word that can
+// open one. Bound into references/modes/upgrade.md by doc-parity — the executable half of "a failed
+// line names its cause": a cause the tool can print but the doc never named fails the lint.
+export const RELAYED_FAILURE_CAUSES = FAILURE_CAUSES;
+
 // The subset references/modes/upgrade.md enumerates, so the agent relaying an upgrade knows every
 // outcome by name. doc-parity binds each of these into that doc: a reworded doc that drops one fails
 // the check instead of silently teaching an outcome set the tool no longer has. The dry-run pair is
@@ -52,6 +65,7 @@ export const FAILURE_CAUSES = Object.freeze([
 export const RELAYED_ENSURE_TOKENS = Object.freeze([
   'seeded',
   'note-refreshed',
+  'regenerated',
   'already-current',
   'customized-preserved',
   'malformed-preserved',