@sabaiway/agent-workflow-kit 5.8.0 → 5.10.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/references/shared/report-footer.md

@@ -51,8 +51,8 @@ the project's internal `docs/ai` structure version, the stamp filename, or the i
 vocabulary — that number is inert here and only confuses; it belongs to *Version disclosure* (below).
 Frame the success itself plainly, in the **user's conversational language** (never hardcode a phrase):
 - a **zero-diff no-op `upgrade`** (step 4) → **settings already current — no update is required**
-  (illustrative tone for a Russian-speaking user, an example of the meaning, not a literal string to
-  embed: *«Настройки уже актуальны — обновление не требуется»*);
+  (that is the MEANING to convey, not a literal string to embed — say it in the user's conversational
+  language, in your own words);
 - a **fresh `bootstrap`** → its normal "deployed and ready" success, minus the number.
 
 **Version block — the installed package versions, fed from `--json`** (the `docs/ai` structure version

package/references/templates/agent_rules.md

@@ -71,6 +71,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.)

package/tools/detect-backends.mjs

@@ -141,6 +141,7 @@ const RAW_BACKENDS = [
         ],
         receipt: "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan/diff mode; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (code mode refuses pre-spend without one — no run, no receipt — unless --ungrounded/AGY_PROBE=1; in plan/diff an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); probe = whether the run relaxed the quality guards (AGY_PROBE=1), written on EVERY receipt so it self-declares — the kit's review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); posture = the ACTUAL run posture {model} (agy has no tier), written on EVERY receipt (D5) — the gate rejects a receipt with an absent/invalid posture (a pre-D5 wrapper minted it; re-run the review), one stderr banner line states the same posture, an ATTESTING review with AGY_MODEL explicitly emptied refuses pre-spend, and a model string carrying control bytes refuses pre-spend in every mode; delivery = how the change set REACHED the model, currently emitted as 'inline' (the whole set rode one prompt — proven by construction) or 'fed' (a chunked feed whose per-part echo proof verified); REQUIRED on every agy code receipt and its ABSENCE is what stops a pre-fed-lane receipt attesting, while the gate accepts any well-formed declaration rather than a particular value; absent by construction on plan/diff/continuation receipts, which carry no change set; a run whose output carries NO recognized '### Verdict' section — empty output included — exits 4 with NO receipt (D4: a FAILED review to RE-RUN, never a fatal session error); when the dispatch nonce seam is supplied — the AW_REVIEW_NONCE environment value or its plain-argument equivalent --nonce <n> (one seam: the flag assigns the same value; supplying both with different values refuses pre-spend) — under the safe grammar [A-Za-z0-9._-]{1,64} (anything else refuses pre-spend), the wrapper first mints the finding MANIFEST {schema, backend, nonce, fingerprint, findings} beside the receipts file (agent-workflow-finding-manifest-<backend>-<nonce>.json; atomic, no-clobber — a byte-identical rewrite is an idempotent no-op, different bytes refuse loudly) ORDERED before the receipt append — a failed manifest write EXCLUDES the receipt append, so a nonce-supplied dispatch can never land a receipt without its readable manifest; a nonce-less invocation adds NO nonce field and mints NO finding manifest (the existing wrapperVersion field still changes with each bridge release); a write failure warns, never fails the review",
         notes: [
+          'transport: every review dispatch drives the CLI in --output-format json (plus --disable-slash-commands) and the returned envelope is parsed in node (bin/agy-envelope.mjs) — the operator-facing invocations and flags above do NOT change, and on a ZERO exit the wrapper still PRINTS the review text, never JSON. A missing or unreadable envelope on a zero exit is a loud failure with NO receipt, never a downgraded verdict and never a fallback to raw-stdout parsing; a non-zero CLI exit keeps its own code and message, and publishes the captured stdout unchanged from the SINGLE dispatch or the FINAL fed turn (which may therefore be a JSON or partial payload — the envelope is parsed only on a zero exit); an INTERMEDIATE feed turn is the exception, its output stays private (Invariant E) and its failure prints only a named error. Enforced by a PRE-SPEND capability probe, not a version floor: agy --help must advertise --output-format and --disable-slash-commands, node must be >= 22, and bin/agy-envelope.mjs must be present — otherwise the review refuses before any run is spent and names the missing capability',
           'pre-dispatch host-diff: before the FIRST dispatch of this bridge, diff its declared networkHosts against the live sandbox allow-list — a missing host is surfaced to the maintainer BEFORE dispatching, never fired into a known prompt',
           'the review posture banner appends a banner-only timeout=<duration> field — exactly the duration agy-run hands to timeout(1); the hard-timeout preflight fails CLOSED when no timeout/gtimeout binary exists (the wrapper refuses by name before any CLI run, so an uncapped review run can no longer happen), and the field never enters the receipt posture or the D5 banner↔receipt parity',
           'quote the posture banner verbatim when labeling this dispatch — the banner is the machine-stated posture; a prose re-type drifts',

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,14 +1,15 @@
 #!/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
-// has a single invocation point whose four outcome lines it relays.
+// of five is deliberate: five independent runs would be five chances to skip one, and the mode doc now
+// has a single invocation point whose five outcome lines it relays.
 //
 // The contract (pinned by this module's tests):
 //   • --reconcile is REQUIRED. A bare run is a usage error, so nothing writes by accident.
@@ -16,7 +17,7 @@
 //   • The ops run in a FIXED order and one op's failure NEVER skips the rest: every op reports its own
 //     token, and the exit is non-zero when any of them failed.
 //   • The deployment gate runs ONCE, before any op: an absent/symlinked docs/ai stops the whole run
-//     with the gate's own message rather than four copies of it.
+//     with the gate's own message rather than five copies of it.
 //
 // Output is ENGLISH/structured (repo-artifact Hard Constraint); the agent localizes when narrating.
 // Exit codes: 0 every op fine · 1 an op failed, or the deployment gate stopped the run · 2 usage.
@@ -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}`);
@@ -120,12 +138,12 @@ export const main = (argv = [], ctx = {}) => {
     const cwd = resolve(args.cwd ?? ctx.cwd ?? process.cwd());
     const deps = ctx.deps ?? {};
     // 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.
+    // reconcile, and five identical STOPs would read as five 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,
 });