@sabaiway/agent-workflow-kit 5.8.0 → 5.10.0

package/references/modes/state-block-guard.md

@@ -19,12 +19,12 @@ this as preventing the defect is describing it wrongly.
 - **The «what I need from you» slot answering "nothing".** A turn that ends is by definition idle, so
   a resume from the reader IS required; a slot saying otherwise states something untrue. Judged over
   the slot's **first clause only** — a slot that names a real ask and then, after a `;` or a full
-  stop, adds «ничего другого не нужно» is honest and passes. A COMMA does not open a new clause, so
-  the comma-joined version of that sentence is flagged; see the residuals. Hedged forms count: «не
-  требуется», «ваше присутствие не требуется прямо сейчас», «nothing right now», «n/a».
-- **Announce-and-stop.** The «what next» slot promising first-person imminent work («беру…»,
-  «начинаю…», «I'll start…») while the turn ends. A promise **gated on something named** («после
-  вашего да — беру…», «once CI finishes…») states a dependency instead of a false start, and passes.
+  stop, adds «nothing else is needed» is honest and passes. A COMMA does not open a new clause, so
+  the comma-joined version of that sentence is flagged; see the residuals. Hedged forms count: «not
+  required», «your presence is not required right now», «nothing right now», «n/a».
+- **Announce-and-stop.** The «what next» slot promising first-person imminent work («I take the
+  class…», «I'll start…») while the turn ends. A promise **gated on something named** («after your
+  yes — I publish», «once CI finishes…») states a dependency instead of a false start, and passes.
 
 **A message with no recognisable block at all is SILENT by default.** This kit does not mandate the
 three-part closing block — it is a per-project dialogue contract — so warning whenever a block is
@@ -75,10 +75,13 @@ gets no detection at all**, silently — not a warning on every turn, which is w
 condition would produce. An EMPTY delivered message is different: it is text, so a turn that ended
 with no prose is judged as having no block, which `--require-block` will report.
 
-**Language.** The slot labels and both banned sets carry Russian and English twins, because the
-contract this enforces was written for a Russian-dialogue deployment. A deployment in another
-dialogue language gets no detection until its labels are added — that is a real limit, not a
-configuration you can set today.
+**Language — one vocabulary, English, and no list of others.** The slot labels and every phrase set
+are English. The kit enumerates no second language: a shipped language list is a guess about somebody
+else's dialogue, and it never stops growing. A deployment whose dialogue language is not English
+extends the arrays **in its own placed copy** — the runtime is copied into the project and
+self-contained, so that edit is local and survives an uninstalled kit. Until it is made, such a
+deployment gets **no detection**, silently. That is a real limit, stated rather than hidden, and it is
+not a configuration you can set today.
 
 **No writer yet — and why, plainly.** Every other placed thing in this kit arrives through a
 consent-gated writer. This one does not, deliberately:
@@ -162,28 +165,33 @@ the warning text. It is not a sandbox and not a permission control.
 
 - **Detection, not prevention** — restated because it is the one thing that must not blur.
 - **The judgement is LEXICAL, and that is a layer with limits, not a temporary weakness.** It matches
-  slot labels and phrase sets on Unicode-aware word boundaries, so an honest «мне нужно ваше
-  подтверждение» is not read as «не нужно» and an interrogative «не нужно ли…» is not read as a
-  refusal. It cannot parse a sentence, and it cannot recognise a wording it has never been told
-  about. Two rules that tried to close an edge here were **deleted rather than tightened a third
-  time**, because each next version needed a second classifier — the residuals below are what
-  replaced them. A named specimen of the cost: «подтвердите, что ничего не упущено» is a real ask
-  and is FLAGGED, because the banned word sits inside it. Phrase the ask without the word.
-- **A comma-joined qualifier is flagged.** «одно да, ничего другого не нужно» warns; the same
-  sentence with a `;` or a full stop passes. The rule that tried to exempt the comma form kept
-  letting a real "nothing" through behind a harmless prefix, so it was removed and the false flag is
-  accepted instead. It costs one line and names its own fix.
+  slot labels and phrase sets on **Unicode-aware** word boundaries — the markers are English but the
+  message is the project's dialogue language, which need not be ASCII, and JavaScript's `\b` would
+  read every non-ASCII letter as a word break and match a marker sitting inside a longer word. On the
+  English side the same class is what stops «none» matching inside «nonexistent». It cannot parse a
+  sentence, and it cannot recognise a wording it has never been told about. Two rules that tried to
+  close an edge here were **deleted rather than tightened a third time**, because each next version
+  needed a second classifier — the residuals below are what replaced them. A named specimen of the
+  cost: «confirm that nothing was missed» is a real ask and is FLAGGED, because the banned word sits
+  inside it. Phrase the ask without the word.
+- **A comma-joined qualifier is flagged.** «one yes, nothing else is needed» warns; the same sentence
+  with a `;` or a full stop passes. The rule that tried to exempt the comma form kept letting a real
+  "nothing" through behind a harmless prefix, so it was removed and the false flag is accepted
+  instead. It costs one line and names its own fix.
 - **A condition is bound to a promise by TOKEN ORDER inside one segment, which is an approximation.**
-  «после вашего да — беру класс» passes; «беру класс, а если тест упадёт, сообщу» is flagged. Two
-  known misreadings follow from the approximation, both accepted: an honest TRAILING gate («беру,
-  когда вы скажете») is flagged, and a gate belonging to an earlier comma-clause («если тест упадёт,
-  сообщу, а сейчас начинаю…») wrongly excuses the promise after it. Leading with the gate avoids the
-  first; the second is a miss this layer cannot close without parsing.
-- **The English side is weaker than the Russian side, structurally.** Russian promises are action
-  verbs («беру», «начинаю»); English ones are pronoun+modal («I'll», «I will»), which cannot tell
-  starting from waiting. Waiting is explicitly excluded — «I'll wait for your approval» passes,
-  because waiting is what a turn that ends actually does — but the exclusion is a list, and an
-  unusual way of saying "I am waiting" will be flagged.
+  «after your yes — I take the class» passes; «I take the class, and if the test fails I'll report»
+  is flagged. Two known misreadings follow from the approximation, both accepted: an honest TRAILING
+  gate («I take it when you say so») is flagged, and a gate belonging to an earlier comma-clause («if
+  the test fails I'll report, and now I start the next class») wrongly excuses the promise after it.
+  Leading with the gate avoids the first; the second is a miss this layer cannot close without
+  parsing.
+- **The promise markers are a MIXED set, and each half misses differently.** Some are pronoun+modal
+  («I'll», «I will», «I'm going to»), which name no verb of their own and so cannot tell starting
+  from waiting; waiting is therefore excluded by an explicit list — «I'll wait for your approval»
+  passes, because waiting is what a turn that ends actually does — and an unusual way of saying "I am
+  waiting" is flagged. The others are pronoun+verb («I take», «I start», «I begin», «I move on»),
+  which name the action but only in the exact wording listed: a synonym nobody wrote down is missed
+  entirely, and a stative use of a listed verb («I take that as settled») is a false flag.
 - **A host that does not deliver `last_assistant_message` gets no detection**, silently. There is no
   transcript fallback, on purpose — see above.
 - **Without `--require-block`, a turn that drops the block entirely is not detected.** That is the

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

@@ -1,6 +1,6 @@
 // check-docs-size-cli.test.mjs — runCli branch pins the subprocess smokes cannot reach
 // in-process (Phase-5 coverage fill; the main spec file is parity-frozen, so these ride a
-// colocated file): the unknown-argument refusal and the written-empty-index guard.
+// colocated file): the unknown-argument refusal and the pre-write symlink refusal on the index path.
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from 'node:fs';
@@ -20,7 +20,7 @@ describe('check-docs-size runCli — refusal branches', () => {
     assert.match(stderr, /Unknown argument: --bogus/);
   });
 
-  it('--write-index landing on a sink path (index stat size 0) is the loud written-empty refusal', async () => {
+  it('--write-index refuses a symlinked index path BEFORE writing, naming the path', async () => {
     const root = mkdtempSync(join(tmpdir(), 'cds-cli-'));
     try {
       mkdirSync(join(root, 'docs', 'ai'), { recursive: true });
@@ -28,12 +28,13 @@ describe('check-docs-size runCli — refusal branches', () => {
         join(root, 'docs', 'ai', 'a.md'),
         '---\ntype: state\nlastUpdated: 2026-07-18\nscope: session\nstaleAfter: never\nowner: none\nmaxLines: 10\n---\n\n# a\n',
       );
-      // The index path is a symlink into /dev/null: the write lands, the stat reads size 0 —
-      // the guard must refuse loudly instead of reporting a written index.
-      symlinkSync('/dev/null', join(root, 'docs', 'ai', 'index.md'));
+      // The index path is a symlink into /dev/null: the contained write refuses to publish THROUGH
+      // the link (it would clobber the link target), names the path, and writes nothing.
+      const indexPath = join(root, 'docs', 'ai', 'index.md');
+      symlinkSync('/dev/null', indexPath);
       const { code, stderr } = await cli(['--write-index', `--root=${root}`]);
       assert.equal(code, 2);
-      assert.match(stderr, /index\.md was written empty/);
+      assert.match(stderr, new RegExp(`${indexPath} is a symlink`));
     } finally {
       rmSync(root, { recursive: true, force: true });
     }

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

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