@sabaiway/agent-workflow-kit 5.8.0 → 5.9.0

package/CHANGELOG.md

@@ -4,6 +4,41 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 5.9.0 — the always-loaded navigator becomes something every deploy path actually creates (AD-096; memory 4.4.0)
+
+**A fresh deployment's entry point declared `docs/ai/index.md` always-loaded, and no step ever
+created it.** The navigator is generated, not templated, and nothing in bootstrap ran the generator:
+a Node project was born with a pre-commit hook failing its own index check, and a project without
+Node stayed quietly broken, its entry point pointing at a file nothing writes. The kit's own
+fallback bootstrap carried the same gap. Every deploy and upgrade path now finishes by materializing
+it, and two new guards make "the entry point only points at things a deploy creates" a test rather
+than an intention.
+
+- **A fifth project-configuration ensure: `index`.** `ensure-configs --reconcile` now regenerates
+  `docs/ai/index.md` whenever it is missing or stale, so an existing deployment gains its navigator
+  without a lineage bump — exactly like the config seeds. It never skips a No-Node project: the
+  generator runs from the kit's own bundled copy, not the project's `scripts/`.
+- **The LATE run is the authoritative one.** The agent-rules lens rewrites `docs/ai` after the
+  step-3 reconcile, so `upgrade.md` documents a late `--reconcile --only index` rung at BOTH exits —
+  after the lens block on the equal-head exit, at the end of step 7 on the migrated one — and the
+  step-4/8 reports relay THAT line.
+- **`ensure-configs --only <op>`** runs exactly one ensure. An unknown, missing or repeated
+  selector is a usage error with zero writes: a run that cannot be narrowed as asked must not widen.
+- **Failure says how far it got.** The index op classifies `generator-unlaunchable` (nothing ran),
+  `generator-failed`, `index-probe-failed` and `index-stale-after-write`; every cause that can only
+  arise after the generator ran DISCLOSES that a write may already have landed, and a claimed
+  regeneration is verified by a re-probe that must ANSWER — an exit code alone would turn a failed
+  probe into a false "still stale". Every relayed cause is now doc-parity-bound into `upgrade.md`.
+- **The bundled generator's write is contained and atomic** (mirrored from the memory canon): a
+  symlink at any level of `docs/ai/index.md` refuses, the body is published through an
+  exclusive-create temp + rename, and the containment guard runs BEFORE the freshness read — a
+  symlink whose target happens to hold current bytes is refused, not reported "already current".
+- **Hidden mode now names the whole payload.** `KIT_OWN_PATHS` listed 14 of the 21 files a deploy
+  copies into `scripts/`, so six shipped scripts besides the new one stayed visible in a hidden
+  project's `git status`. The registry is complete (20 → 27) and a new test derives the expected set
+  from the deploy payload itself. Known residual: a registered path is still hidden by NAME rather
+  than proven ownership (`known_issues.md` → Issue-018).
+
 ## 5.8.0 — the bundled agy bridge speaks the catalog the installed CLI actually serves, and grounding stops needing a shell (AD-095; antigravity-cli-bridge 5.2.0)
 
 **A model display string is matched exactly, so a stale one is not a documentation bug — it is a

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '5.8.0'
+  version: '5.9.0'
 ---
 
 # agent-workflow-kit

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "5.8.0",
+  "version": "5.9.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "5.8.0",
+  "version": "5.9.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/modes/bootstrap.md

@@ -22,7 +22,7 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
 4. **Choose agent attribution — answered in the step-2 batch.** May the agent attribute work to itself / to AI — `Co-Authored-By` trailers, "Generated with …" footers, "AI"/agent/model mentions in code, comments, commit messages, PR titles/bodies, or docs? **Default to `off`** (no agent/AI mention anywhere) unless they opt in — people are routinely surprised to find an AI listed as a repo contributor. Carry the answer into the `{{AGENT_ATTRIBUTION}}` slot of the *Attribution* block when `AGENTS.md` is created (step 5). **If `off` and the project uses Claude Code**, also set `"includeCoAuthoredBy": false` in the project's `.claude/settings.json` (create it if absent) — the trailer is added by the harness, so a doc directive alone won't stop it. See [Attribution contract](${CLAUDE_SKILL_DIR}/references/contracts.md#attribution-contract).
 5. **Entry-point doc.** If `AGENTS.md` / `CLAUDE.md` already exist (step-1 recon), do **not** overwrite — show the user and ask whether to merge or replace. Otherwise create `AGENTS.md` (the cross-agent standard — Codex / Cursor / Devin Desktop / Copilot read it natively) from `${CLAUDE_SKILL_DIR}/references/templates/AGENTS.md`, and symlink `CLAUDE.md -> AGENTS.md` (`ln -s AGENTS.md CLAUDE.md`) for Claude Code — single source, no duplication. For nested context, add a subdir `AGENTS.md` (+ a `CLAUDE.md` symlink beside it for Claude Code).
 6. **Deploy `docs/ai/`.** Create every `docs/ai/` file + `pages/` + the seed `adr/` store from `${CLAUDE_SKILL_DIR}/references/templates/` (the template loop deploys each non-`AGENTS.md`, non-`adr-record.md` template — `adr-record.md` is a skill-home ADR authoring reference, never deployed). This deploys the HOT ADR window **`docs/ai/decisions.md`** and the seed navigator **`docs/ai/adr/log.md`** (its `adr/` subdir copies in wholesale), the `.md` docs, **and** the three seeded, user-editable strict-JSON configs: **`docs/ai/orchestration.json`** (the per-project recipe defaults the `procedures` advisor reads), **`docs/ai/gates.json`** (the project's gate declaration — seeded as the no-consent EMPTY list; FILLING it is the consented `gates-init` preview, `${CLAUDE_SKILL_DIR}/references/modes/gates.md`), and **`docs/ai/autonomy.json`** (the per-project autonomy policy — seeded SPARSE with the onboarding note only, so it is exactly the computed defaults until the user declares levels via `/agent-workflow-kit set-autonomy` or by hand). Keep each `.md` file's frontmatter (`type / lastUpdated / scope / staleAfter / owner / maxLines`); the `.json` seeds carry no frontmatter (the docs cap-validator globs `*.md` only, so they are inherently skipped).
-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=<project>` 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 **this skill's own directory**, so a project with **no Node runtime** is covered too: the agent 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/`. They self-configure (project name from `package.json`, hierarchical/on-demand sections auto-discovered). **If the project has no Node runtime** (step-1 recon), skip this step and the hook in step 9 — follow the cap/archive/index policy manually, or port the scripts to the project's language.
 9. **Wire / hide** per visibility (see [Visibility contract](${CLAUDE_SKILL_DIR}/references/contracts.md#visibility-contract)). Install the pre-commit hook (Node projects): `node scripts/install-git-hooks.mjs`. If the installer reports a pre-existing non-marker hook, stop and ask the user to merge it manually rather than overwriting. Once the gate declaration is final-run-capable, the installer's optional consented `--commit-guard <kit commit-guard.mjs path>` arm binds commits to the green `run-gates --final` receipt (the Recommendations advisor surfaces the exact one-liner).
    - **visible** — wire the `package.json` scripts + add the minimal `.gitignore`. **Do not run the hide tool.**
@@ -32,7 +32,11 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
      - If it reports a **leftover machine-wide ignore block** from an older deployment, **ask before removing it** — it could affect another of the user's repos that relies on the same machine-wide rules; on a yes, re-run with `--remove-global` (prints a restorable backup). Otherwise it is kept (harmless — the project-local rules win).
      - Report the result plainly (what is now hidden). **No Node on the agent host** → write the one managed block into `.git/info/exclude` by hand from the contract's path list, and report the manual step. **Windows is supported.**
    - **Do not edit `package.json`** in hidden mode — a tracked change leaks the whole system.
-10. **Stamp the deployment lineage.** Write the **deployment-lineage head** into
+10. **Stamp the deployment lineage.** **First re-run the step-7 navigator finalizer**
+    (`--ensure-index`) whenever a later step touched `docs/ai` — the reconciles that follow the
+    template copy do (the agent-rules lens,
+    `${CLAUDE_SKILL_DIR}/references/shared/composition-handoff.md`); it is idempotent, so an
+    untouched tree simply reports `already-current`. Then write the **deployment-lineage head** into
     `docs/ai/.workflow-version` (one semver line). The lineage head is **`3.0.0`** — the shared
     `agent-workflow` deployment lineage, **NOT** this kit's npm package version (see
     `package.json` / `CHANGELOG.md`). The two are

package/references/modes/upgrade.md

@@ -10,7 +10,7 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
 
    1. `pointers` — `node ${CLAUDE_SKILL_DIR}/tools/inject-methodology.mjs reconcile <project>/AGENTS.md` → per pointer: added · already present · skipped (reported) · a hard STOP.
    2. `footprint` — `node ${CLAUDE_SKILL_DIR}/tools/hide-footprint.mjs --dir <project> --reconcile --dry-run` → visibility: visible · ambiguous · hidden — consent (conditional): ambiguous → ask which it is BEFORE anything; hidden → the conditional re-run without `--dry-run` (its surfaced paths ask per bootstrap step 9).
-   3. `configs` — `node ${CLAUDE_SKILL_DIR}/tools/ensure-configs.mjs --reconcile --cwd <project>` → one line per ensure: `seeded` / `note-refreshed` / `already-current` / `customized-preserved` / `malformed-preserved` / `already-present` / `skipped-no-node` / `old-adr-layout-migration-instructed` / `failed`.
+   3. `configs` — `node ${CLAUDE_SKILL_DIR}/tools/ensure-configs.mjs --reconcile --cwd <project>` → one line per ensure: `seeded` / `note-refreshed` / `regenerated` / `already-current` / `customized-preserved` / `malformed-preserved` / `already-present` / `skipped-no-node` / `old-adr-layout-migration-instructed` / `failed`.
    4. `gates-migration` — `node ${CLAUDE_SKILL_DIR}/references/scripts/migrate-gates.mjs --kit-tools ${CLAUDE_SKILL_DIR}/tools --cwd <project>` → the preview plan · INERT checker · CUSTOMIZED entries, each named — consent: apply only on an explicit yes, re-run with `--apply`.
    5. `bridges` — `node ${CLAUDE_SKILL_DIR}/tools/setup-backends.mjs --refresh-placed` → per-bridge lines: refreshed · already current · skipped — with its stated reason (not placed / newer than the bundle / unsupported host) · `skipped-readonly` · could not refresh.
    6. `lens` — `node ${CLAUDE_SKILL_DIR}/tools/lens-region.mjs reconcile <project>/docs/ai/agent_rules.md` → per section: refreshed · already current · custom edit preserved · file absent / engine too old — skipped · over the line cap — refused · section absent — noted · a fully absent/invalid engine → hard STOP.
@@ -30,7 +30,7 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
 
    **`footprint` — hidden-mode footprint reconcile (D9 / AD-014).** A deployment does not record whether it chose `hidden`, so first **infer visibility** — the dry-run writes **zero bytes** and reports one of — **visible** (the entry point is tracked) → nothing to do; **ambiguous** (untracked but not ignored — could be a fresh uncommitted repo, or a hide that broke) → **ASK** the user which it is, never guess; **hidden** → re-run without `--dry-run` to migrate any older **machine-global** hide to the **project-local** `.git/info/exclude` (one managed block; folds in the legacy `.claude/skills/` line), idempotently (a clean re-run is zero-diff). Handle its surfaced paths exactly as bootstrap step 9 (`${CLAUDE_SKILL_DIR}/references/modes/bootstrap.md`) (already-committed → show `git rm --cached`, ask before `--include`; generic-name present file → ask; **leftover machine-wide ignore block → ASK before `--remove-global`**, default keep + report). No Node on the agent host / Windows → as bootstrap step 9 (`${CLAUDE_SKILL_DIR}/references/modes/bootstrap.md`). This runs on **every** hidden upgrade, like the methodology slot — no lineage-head bump, no migration file.
 
-   **`configs` — the project-configuration ensures, ONE run.** The ONE command performs **all four** ensures described below — orchestration config · gate declaration · autonomy declaration · enforcement scripts — in a fixed order, and prints **one outcome line per ensure**: paste those lines into the step 4 / step 8 success report. Every seed is **create-only** (an existing file is preserved byte-for-byte), the ONE refresh is the orchestration onboarding note while it still matches a canonical this kit shipped, and one ensure failing **never** skips the others: each reports its own outcome and the run exits non-zero when any of them `failed`. The outcome tokens, by ensure: orchestration → `seeded` / `note-refreshed` / `already-current` / `customized-preserved` / `malformed-preserved`; gates and autonomy → `seeded` / `already-present`; scripts → `seeded` / `already-present` / `old-adr-layout-migration-instructed` / `skipped-no-node`; and any ensure may report `failed`, whose line OPENS with the cause (relay it with that cause — never soften it into a skip; an op that copies file by file also states when it stopped partway). **A non-zero exit STOPs this upgrade** — report the failed line and stop there, before the equal-head exit, the migrations and the re-stamp. Add `--dry-run` to preview without writing a byte. Like the pointer slots + the footprint reconcile, all four reach an equal-head deployment **without a lineage-head bump or a migration file** (they are `.json` / `scripts/`, inherently outside the docs cap-validator).
+   **`configs` — the project-configuration ensures, ONE run.** The ONE command performs **all five** ensures described below — orchestration config · gate declaration · autonomy declaration · enforcement scripts · navigator index — in a fixed order, and prints **one outcome line per ensure**: paste those lines into the step 4 / step 8 success report. Every SEED is **create-only** (an existing file is preserved byte-for-byte); the two refresh-class ops are named apart — the orchestration onboarding note (refreshed only while it still matches a canonical this kit shipped) and the **navigator index**, a GENERATED artifact regenerated whenever it is missing or stale (never authored content, so there is nothing to preserve). One ensure failing **never** skips the others: each reports its own outcome and the run exits non-zero when any of them `failed`. The outcome tokens, by ensure: orchestration → `seeded` / `note-refreshed` / `already-current` / `customized-preserved` / `malformed-preserved`; gates and autonomy → `seeded` / `already-present`; scripts → `seeded` / `already-present` / `old-adr-layout-migration-instructed` / `skipped-no-node`; index → `regenerated` / `already-current`; and any ensure may report `failed`, whose line OPENS with the cause (relay it with that cause — never soften it into a skip; an op that copies file by file also states when it stopped partway). The cause vocabulary is CLOSED — one of `race-unresolved`, `template-unreadable`, `bundle-unreadable`, `adr-layout-unverifiable`, `wrong-node-kind`, `write-refused`, `unexpected-error`, `generator-unlaunchable`, `generator-failed`, `index-probe-failed`, `index-stale-after-write` — and every cause that can only arise AFTER the generator ran (`generator-failed`, and `index-probe-failed` / `index-stale-after-write` when they follow a reported regeneration) DISCLOSES in its own line that a write may already have landed. **A non-zero exit STOPs this upgrade** — report the failed line and stop there, before the equal-head exit, the migrations and the re-stamp. Add `--dry-run` to preview without writing a byte. Like the pointer slots + the footprint reconcile, all five reach an equal-head deployment **without a lineage-head bump or a migration file** (they are `.json` / `scripts/` / a generated artifact, inherently outside the docs cap-validator).
 
    **What the orchestration-config ensure does.** `docs/ai/orchestration.json` must exist **and its onboarding note must be current**: created from the canonical seed if missing; if it already exists, **every activity/slot the user set is preserved** and ONLY the `_README` note is refreshed, and only when the existing one still matches a known prior canonical — the tested `refreshIfCanonical` / `refreshReadme` in `tools/orchestration-config.mjs` is the source of truth for that decision (it normalizes CRLF/whitespace before comparing; a *customized* `_README` is preserved verbatim → `customized-preserved`; a *malformed* existing config is **preserved untouched + LOUD** → `malformed-preserved`, never clobbered and never silently skipped). The current note points at `/agent-workflow-kit set-recipe`. **Kit-owned:** in the **delegated** path memory only seeds/preserves the file (memory upgrade step 2) and this ensure applies the `_README` refresh; in the **fallback** path it does both. (Memory stays standalone.)
 
@@ -40,6 +40,8 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
 
    **What the enforcement-script ensure does.** A deployment older than the ADR-cascade feature has no `scripts/archive-decisions.mjs`, and an equal-head exit would otherwise never deliver it. The pairs must exist in the project's `scripts/`: `archive-decisions.mjs` + `archive-decisions.test.mjs` and `markdown-blocks.mjs` + `markdown-blocks.test.mjs`, copied from `${CLAUDE_SKILL_DIR}/references/scripts/` if missing; **an existing file is preserved, never overwritten** (drift repair belongs to a lineage migration). Nothing else is seeded — the other tokenizer-era tests red beside OLD archivers. **OLD ADR-store layout — DETECTED FIRST, never auto-migrated (AD-051, Decision 13):** on a `docs/ai/history/decisions-archive*.md` monolith (`old`), or no monolith but a deployed rotator predating the store (`old-unrotated`), the project is on the RETIRED 3-tier cascade, so the ensure writes NOTHING and reports `old-adr-layout-migration-instructed` (the new `archive-decisions.mjs` beside un-migrated monoliths would red their ADR gate). Relay it as the LOUD instruct it is: the fix is the opt-in **`/agent-workflow-kit migrate-adr-store`** (consent-gated; previews first, never commits), and the seed lands on the next upgrade. A layout the ensure cannot READ is `failed`, not a seed — it never writes on an unverifiable tree. The seed applies ONLY to a clean layout (neither signal), and a project with no `package.json` at its root reports `skipped-no-node` (these are Node enforcement scripts) while the three config ensures still run. The deployed pre-commit hook gains the `archive-decisions.mjs --check` line only when the hook itself is next refreshed (re-run `node scripts/install-git-hooks.mjs` after the ensure and it will refuse a non-marker hook as always); an OLD hook without the line stays consistent-safe — the decisions gate is simply not enforced yet, never a broken hook.
 
+   **What the navigator ensure does.** `docs/ai/index.md` is the always-loaded navigator the entry point declares, and it is GENERATED — no template ships it, so a deployment that never ran the generator boots from a broken entry point (and, on a Node project, carries a pre-commit hook that fails its own index check). The ensure runs the bundled generator's finalizer and reports `regenerated` (it was missing or stale — it was written) or `already-current` (nothing written). It never skips a No-Node project: the generator runs from `${CLAUDE_SKILL_DIR}/references/scripts/` on the agent host, not from the project's `scripts/`. **Its position in the run-list is EARLY and therefore NOT authoritative** — `lens` (and, on the migrated path, steps 6–7) still change `docs/ai` afterwards — so the authoritative run is the LATE `--only index` rung documented at both exits; the early one is idempotent and costs at most an `already-current` line.
+
    **`gates-migration` — legacy gates.json migration (consented preview — D8).** An EXISTING declaration may still carry the retired review-ledger / fold-completeness checks. Run the preview (dry-run — writes NOTHING), show the user the exact plan, and only on an explicit yes re-run it with `--apply`: canonical legacy entries (matched by their documented single-invocation cmd forms) are REMOVED, the canonical `unit-tests` cmd gains the built-in lcov reporters, and the coverage-check gate is ADDED last — atomic and COMPLETE, so the migrated declaration satisfies `run-gates --final`. **The checker rides a PRODUCER or is not declared at all** (`${CLAUDE_SKILL_DIR}/references/modes/gates.md`): with no gate producing the lcov it reads, the migration does NOT add it, an already-declared one is reported INERT, the result is not called final-run-capable, and the preview prints the paste-ready suite cmd to declare by hand — nothing is ever removed for you. CUSTOMIZED entries are NEVER auto-touched: the preview names each with a paste-ready recovery, and the commit guard must NOT be installed until they are resolved. This is the ONLY gates.json writer at upgrade (the consented FILL preview runs at init).
 
    **`bridges` — placed-bridge refresh — stamp-independent, same gate, BEFORE the equal-head short-circuit.** Run
@@ -82,8 +84,9 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
    verbatim**: it validates the deployed host settings file's keys against the bundled manifests and
    **NEVER writes** it (the file lives outside every kit tree — D2), so an unknown/retired key is
    flagged + preserved, never edited. Runs on **every** upgrade; exit 0 covers every outcome.
+   **The LATE navigator finalizer — the AUTHORITATIVE run, after the last `docs/ai` mutation.** `lens` above rewrites `docs/ai/agent_rules.md`, so the step-3 index ensure is already behind by the time the run-list ends. Re-run that ONE op here, before the step-4 report: `node ${CLAUDE_SKILL_DIR}/tools/ensure-configs.mjs --reconcile --only index --cwd <project>`. Relay **this** line in the report (it supersedes the early one; an untouched tree reports `already-current`, a failure STOPs the upgrade like any other ensure). On the migrated path the same rung runs again at the END of step 7 — after the migrations, before the step-8 re-stamp.
 4. **Equal-head exit — a real successful-exit report, not a bare stop.** If the stamp **equals** the head, the lineage is up to date — but step 3 (the stamp-independent reconciles) ran first and may have changed things, so this is a proper exit report, not a no-op:
-   - **Report step 3's outcome in plain language** — for **each** `pointers` slot (workflow-methodology, orchestration-recipes and autonomy-policy) whether it was *added*, was *already present* (nothing changed), or was *skipped* (the soft-skip from step 3, with its reason — over the line limit / engine too old / the autonomy pointer's anchor absent); the **four project-configuration ensure** (`configs`) lines exactly as the one ensure run composed them (orchestration config, gate declaration, autonomy declaration, enforcement scripts — their outcome tokens are enumerated in step 3), each rendered in plain language: what was created, what was left exactly as the user wrote it, and — for a `failed` line — what stopped it; the **`gates-migration`** result — *nothing to migrate*, the shown plan *applied* on your explicit yes, or the plan *left unapplied* (consent not given), with any INERT checker or CUSTOMIZED entries named; the **placed-bridge refresh** (`bridges`) outcome — paste the tool's per-bridge lines verbatim (they are already plain: *refreshed* / *already current* / *skipped — not placed* / `skipped-readonly` with its re-scan verdict / *could not refresh* + recovery); the **agent-rules lens** (`lens`) outcome (*refreshed* / *already current* / *custom edit preserved + note* / *file absent* / *engine too old* / *over the line cap*) and the **Communication-section** outcome (its own set: refreshed / already current / custom preserved + note / section absent — noted / over the cap — refused); the **bridge-settings reconcile** (`bridge-settings`) outcome (paste the tool's line(s) verbatim); and, for a hidden deployment, whether the hidden-mode footprint (`footprint`) was *moved to project-local*, was *already project-local* (nothing changed), or needed a question (ambiguous visibility / a leftover machine-wide block). Plain wording only — never the reconcile/slot/anchor/marker terms (the never-leak-kit-internals Gotcha — `${CLAUDE_SKILL_DIR}/references/shared/deploy-tail.md`).
+   - **Report step 3's outcome in plain language** — for **each** `pointers` slot (workflow-methodology, orchestration-recipes and autonomy-policy) whether it was *added*, was *already present* (nothing changed), or was *skipped* (the soft-skip from step 3, with its reason — over the line limit / engine too old / the autonomy pointer's anchor absent); the **five project-configuration ensure** (`configs`) lines exactly as the one ensure run composed them (orchestration config, gate declaration, autonomy declaration, enforcement scripts, navigator index — their outcome tokens are enumerated in step 3), each rendered in plain language: what was created, what was left exactly as the user wrote it, and — for a `failed` line — what stopped it; for the navigator, relay the **late** `--only index` line, not the early one; the **`gates-migration`** result — *nothing to migrate*, the shown plan *applied* on your explicit yes, or the plan *left unapplied* (consent not given), with any INERT checker or CUSTOMIZED entries named; the **placed-bridge refresh** (`bridges`) outcome — paste the tool's per-bridge lines verbatim (they are already plain: *refreshed* / *already current* / *skipped — not placed* / `skipped-readonly` with its re-scan verdict / *could not refresh* + recovery); the **agent-rules lens** (`lens`) outcome (*refreshed* / *already current* / *custom edit preserved + note* / *file absent* / *engine too old* / *over the line cap*) and the **Communication-section** outcome (its own set: refreshed / already current / custom preserved + note / section absent — noted / over the cap — refused); the **bridge-settings reconcile** (`bridge-settings`) outcome (paste the tool's line(s) verbatim); and, for a hidden deployment, whether the hidden-mode footprint (`footprint`) was *moved to project-local*, was *already project-local* (nothing changed), or needed a question (ambiguous visibility / a leftover machine-wide block). Plain wording only — never the reconcile/slot/anchor/marker terms (the never-leak-kit-internals Gotcha — `${CLAUDE_SKILL_DIR}/references/shared/deploy-tail.md`).
    - **Never surface the structure number on this exit.** Whatever step 3 did, do **not** recite the `docs/ai` structure version, the internal versioning vocabulary, or the two-axes note here — the number is inert on an equal-head exit; it belongs to *Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md` (shown at the never-downgrade STOP, the explicit status view, or on an explicit ask). Frame the success itself per the final bullet: if step 3 changed anything, say **what changed** in plain human terms; only a pure zero-diff no-op is *settings already current — no update needed*.
    - **Render the mandatory Recommendations section — on this exit too, BEFORE the footer.** Run `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd <project-root>` and PRESENT its output — from the `## Recommendations (agent-workflow)` header — in the user's conversational language: every fact, count and item from the tool, nothing added or dropped; commands, paths, hosts and rule strings byte-exact; show the raw tool block on request. The section is present-even-when-empty (with everything optimal the body is exactly `no recommendations — flow optimal.`) and VERDICT-FIRST — the composed verdict line renders from the frozen templates `{K} item(s) need attention` / `nothing is broken` / `{N} optional recommendation(s), apply any you want` / `optimality NOT attested — {M} probe check(s) skipped`. Then OFFER the consent-gated applies: the user picks items in plain language; surface each picked item's posture note, get the explicit confirm, then run EXACTLY the rendered one-liners (a HAND-APPLY item is never run by you) — the full lane in `${CLAUDE_SKILL_DIR}/references/modes/recommendations.md`. Pinned order on this exit: Recommendations block → optional applies → report footer → the commit ask (the advisor/apply lane never lands after the commit ask).
    - **Live host/session facts are tool-composed only.** Any claim this report makes 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** (the lines you just composed, or a probe you ran this run); 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. Full clause: *Live host/session facts* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`.
@@ -91,5 +94,5 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
    - **Then ask before committing — never auto-commit.** If step 3 added the slot (or anything else changed), report it and ask. If step 3 was a pure zero-diff no-op and nothing else changed, give the plain **settings already current — no update needed** message (the *Success state* contract in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`) and still print the read-only version block (installed package versions) + backend line — but **no `docs/ai` structure version and no two-axes note** (nothing changed, so the number is inert here).
 5. Show the relevant `${CLAUDE_SKILL_DIR}/CHANGELOG.md` diff (entries newer than the project's stamp).
 6. **Collect the migration answers FIRST, then apply.** If `AGENTS.md` is missing BOTH the *Communication language* and *Attribution* blocks — i.e. both blocks are missing (a pre-1.1.0 deployment) — ask the two questions as ONE structured multi-question prompt; record each answer individually, write nothing until ALL are answered, and carry the answers into the migrations below: a migration whose answer was already collected never re-asks (its own "Ask the user" step is the standalone fallback); a single missing block keeps its single ask (step 7). Then apply `${CLAUDE_SKILL_DIR}/migrations/<version>-<slug>.md` in **semver order**, only those newer than the project's stamp. Migrations are **idempotent** — safe to re-run.
-7. Reconcile drift: add any kernel files/scripts the project is missing; never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs stay). Any user question a migration raises follows the same rule as bootstrap — **structured multiple-choice where supported** (`AskUserQuestion` in Claude Code), otherwise prose. If `AGENTS.md` has no *Communication language* block (pre-1.1.0 deployment), **ask the user their conversational language** and insert the block — see `migrations/1.1.0-communication-language.md`. If it has no *Attribution* block (pre-1.2.0 deployment), **ask whether the agent may attribute work to itself / AI** and insert the block (defaulting to `off`) — see `migrations/1.2.0-agent-attribution.md`. (An answer already collected by the step-6 batched prompt is carried in — never re-asked here.)
-8. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`3.0.0`, not the package version — mechanics unchanged: the atomic write to the stamp file). In the report, **describe what the upgrade changed in plain human terms** — which parts of their `docs/ai` are now different (the migrations that ran), plus the step-3 run-list outcomes, each as step 4 words it: the `pointers` slots, the `footprint` visibility verdict (and what a consented re-run migrated), the **four project-configuration ensure** (`configs`) lines, the **`gates-migration`** result, the **placed-bridge refresh** (`bridges`) lines (pasted verbatim), the **agent-rules lens** (`lens`) + **Communication-section** outcomes (same outcome sets as step 4), and the **bridge-settings reconcile** (`bridge-settings`) outcome (line(s) pasted verbatim) — rather than reciting a version number; **omit the raw structure number**, and do **not** print the two-axes note here (it belongs to *Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`, on demand only). Then **render the mandatory Recommendations section**: run `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd <project-root>` and PRESENT its output — from the `## Recommendations (agent-workflow)` header — in the user's conversational language (every fact, count and item, nothing added or dropped; commands, paths, hosts and rule strings byte-exact; raw tool block on request; present-even-when-empty: `no recommendations — flow optimal.`), then OFFER the consent-gated applies (per picked item: posture note → explicit confirm → run EXACTLY the rendered one-liner; a HAND-APPLY item is never run by you — `${CLAUDE_SKILL_DIR}/references/modes/recommendations.md`). **Every current host/session claim in this report is tool-composed only** — prompts fired, sandbox scope, whether a bypass was needed, network reachability and approval counts must trace to **live tool output** from **this session**, a memory/handover snapshot is **context, never report facts**, and an unbacked claim is **omitted or explicitly marked unverified** (full clause: *Live host/session facts* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`). Then **print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`; rendered from the helpers, same host-can't-run skip-with-reason; the welcome mat closes on one caveat-aware next step). Then **ask before committing** — the pinned order on this exit is: Recommendations block → optional applies → report footer → the commit ask.
+7. Reconcile drift: add any kernel files/scripts the project is missing; never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs stay). Any user question a migration raises follows the same rule as bootstrap — **structured multiple-choice where supported** (`AskUserQuestion` in Claude Code), otherwise prose. If `AGENTS.md` has no *Communication language* block (pre-1.1.0 deployment), **ask the user their conversational language** and insert the block — see `migrations/1.1.0-communication-language.md`. If it has no *Attribution* block (pre-1.2.0 deployment), **ask whether the agent may attribute work to itself / AI** and insert the block (defaulting to `off`) — see `migrations/1.2.0-agent-attribution.md`. (An answer already collected by the step-6 batched prompt is carried in — never re-asked here.) **Then, before the stamp, re-run the LATE navigator finalizer:** the migrations of steps 6–7 may have added or changed `docs/ai` files, so run the one op again — `node ${CLAUDE_SKILL_DIR}/tools/ensure-configs.mjs --reconcile --only index --cwd <project>` — and relay THAT line in the step-8 report (idempotent: an untouched tree reports `already-current`; a failure STOPs this upgrade like any other ensure).
+8. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`3.0.0`, not the package version — mechanics unchanged: the atomic write to the stamp file). In the report, **describe what the upgrade changed in plain human terms** — which parts of their `docs/ai` are now different (the migrations that ran), plus the step-3 run-list outcomes, each as step 4 words it: the `pointers` slots, the `footprint` visibility verdict (and what a consented re-run migrated), the **five project-configuration ensure** (`configs`) lines — the navigator one being the late `--only index` run at the end of step 7, the **`gates-migration`** result, the **placed-bridge refresh** (`bridges`) lines (pasted verbatim), the **agent-rules lens** (`lens`) + **Communication-section** outcomes (same outcome sets as step 4), and the **bridge-settings reconcile** (`bridge-settings`) outcome (line(s) pasted verbatim) — rather than reciting a version number; **omit the raw structure number**, and do **not** print the two-axes note here (it belongs to *Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`, on demand only). Then **render the mandatory Recommendations section**: run `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd <project-root>` and PRESENT its output — from the `## Recommendations (agent-workflow)` header — in the user's conversational language (every fact, count and item, nothing added or dropped; commands, paths, hosts and rule strings byte-exact; raw tool block on request; present-even-when-empty: `no recommendations — flow optimal.`), then OFFER the consent-gated applies (per picked item: posture note → explicit confirm → run EXACTLY the rendered one-liner; a HAND-APPLY item is never run by you — `${CLAUDE_SKILL_DIR}/references/modes/recommendations.md`). **Every current host/session claim in this report is tool-composed only** — prompts fired, sandbox scope, whether a bypass was needed, network reachability and approval counts must trace to **live tool output** from **this session**, a memory/handover snapshot is **context, never report facts**, and an unbacked claim is **omitted or explicitly marked unverified** (full clause: *Live host/session facts* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`). Then **print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`; rendered from the helpers, same host-can't-run skip-with-reason; the welcome mat closes on one caveat-aware next step). Then **ask before committing** — the pinned order on this exit is: Recommendations block → optional applies → report footer → the commit ask.

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

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',

package/tools/known-footprint.mjs

@@ -36,6 +36,9 @@ export const stop = (message, fields = {}) =>
 // never a silent un-track. `/docs/plans/` + both `.claude/settings*.json` are listed because a pure
 // hidden deploy has no tracked `.gitignore`; the classifier drops any candidate a tracked `.gitignore`
 // already covers, so in a repo that DOES track those ignores they are never re-written.
+// The enumeration must cover EVERY file the deploy copies into `scripts/` (bootstrap step 8 copies
+// `references/scripts/*.mjs` + `*.test.mjs` wholesale): a name missing here is a file a hidden
+// deployment leaves visible in `git status` — the exact leak this registry exists to prevent.
 export const KIT_OWN_PATHS = [
   '/AGENTS.md',
   '/CLAUDE.md',
@@ -49,11 +52,18 @@ export const KIT_OWN_PATHS = [
   '/scripts/archive-issues.mjs',
   '/scripts/archive-issues.test.mjs',
   '/scripts/archiver-structure.test.mjs',
+  '/scripts/check-docs-size-cli.test.mjs',
+  '/scripts/check-docs-size-ensure.test.mjs',
   '/scripts/check-docs-size.mjs',
   '/scripts/check-docs-size.test.mjs',
+  '/scripts/install-git-hooks-repo-exec.test.mjs',
   '/scripts/install-git-hooks.mjs',
+  '/scripts/install-git-hooks.test.mjs',
   '/scripts/markdown-blocks.mjs',
   '/scripts/markdown-blocks.test.mjs',
+  '/scripts/migrate-gates-branches.test.mjs',
+  '/scripts/migrate-gates.mjs',
+  '/scripts/migrate-gates.test.mjs',
   '/docs/plans/',
   '/.claude/settings.local.json',
   '/.claude/settings.json',

package/tools/upgrade-runlist.mjs

@@ -38,6 +38,7 @@ export const UPGRADE_RUNLIST = Object.freeze([
     [
       'seeded',
       'note-refreshed',
+      'regenerated',
       'already-current',
       'customized-preserved',
       'malformed-preserved',