@sabaiway/agent-workflow-kit 14.29.1 → 14.30.0

package/CHANGELOG.md

@@ -4,6 +4,52 @@ 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.
 
+## 14.30.0 — the upgrade brings the docs navigator back to green past 80 lines: one yes replaces every edited spec-layer script, and a navigator write the project's own checker rejects is put back (AD-182)
+
+**`/agent-workflow-kit upgrade` now leaves a project with more docs than the navigator's old cap on a navigator its
+own docs check accepts — behind an edited spec-layer file, once the user says yes to replacing it.** Before, the bundled checker stamped `maxLines: 80` into `docs/ai/index.md` whatever its
+length, the navigator step wrote it whatever checker the project's hook runs, and the spec-layer step told the user to
+copy the scripts by hand when one was edited.
+
+- **The bundled checker stamps a cap it honours.** `references/scripts/check-docs-size.mjs` is byte-identical to memory
+  8.2.0's: `maxLines: 80` while the navigator fits, its own line count past that.
+- **An unedited older checker refreshes.** The prior catalog gains the memory 7.0.0–8.1.5 checker body, so the
+  spec-layer step refreshes a deployed checker still on it (`refreshed`, or `seeded` when the run also seeds), unless
+  an edited file of either pair holds it back until the replace run.
+- **One yes replaces every edited file.** While a file of the reader or checker pair carries a body this kit did not
+  ship, the spec-layer step names each such file, the store-root line names them as the reason it waits, and ONE line
+  states its condition and prints the command: `node <kit>/tools/ensure-configs.mjs --reconcile --replace-custom
+  <digest> --cwd <project>`, both paths shell-quoted. The digest binds the set of edited files and their bytes. The
+  upgrade asks one yes naming those files and saying their edits are overwritten, even on a non-zero exit.
+- **The replace run overwrites no edited file the yes did not name.** `--replace-custom <digest>` re-surveys first:
+  while an edited file remains, another set or other bytes is `failed` / `race-unresolved` with nothing written and a
+  fresh replace line; with no edited file left it runs the ordinary step, so a second run of the same line changes
+  nothing. On a match it rewrites each
+  edited file to the bundled body (`carried an edited body — replaced by the bundled one on the user's yes`), refreshes
+  and seeds as the step always does, then runs the navigator step, only after a spec-layer step that did not fail;
+  otherwise its line ends `the navigator step did not run: …`. It is a usage error (exit 2, nothing run) with `--only`,
+  with `--dry-run`, with an empty value or passed twice. No backup copy is written.
+- **The project's own checker judges the navigator.** Where the project deploys `scripts/check-docs-size.mjs` and it,
+  or the `scripts/spec-schema.mjs` it imports, is not the bundled body, the navigator step runs that checker's
+  `--check-index` (30 s, then killed): accepted means exit 0 and a navigator within the `maxLines` it stamps. A
+  navigator accepted as found is `already-current` with nothing written. Otherwise the bundled generator writes and the
+  checker judges again: accepted is `regenerated`; rejected puts the navigator back byte for byte (removed again if it
+  was absent) and reports `customized-preserved`, the run still exiting 0, its line naming the checker's exit and
+  output and the route. A later failure puts back first and keeps its own cause; a put-back that fails is `failed` /
+  `write-refused`, saying a navigator the project's checker rejects may stand; a checker that cannot start or does not
+  answer in time is `failed` / `index-probe-failed`. The dry run runs no project code and says that, unless the
+  spec-layer step first refreshes every such module, the real run judges by the project's checker. With no
+  `scripts/check-docs-size.mjs`, or both modules on the bundled body, the step is unchanged; where it exists, a hook
+  module that is not a regular file is `failed` / `wrong-node-kind` and one that cannot be read `failed` /
+  `unexpected-error`, nothing written.
+- **No shipped instruction says to copy an edited spec-layer script over by hand; past CHANGELOG entries are history.**
+  `upgrade.md` row 3 carries the consent sentence and the `configs` block's STOP waits for that ask; the navigator
+  token list gains `customized-preserved`; the `spec-adoption` example names the replace line's own yes, and its risk
+  text the prior refresh and that yes; the help and header of `ensure-configs.mjs` and
+  the comments of the ensure modules say the same. No outcome token or failure cause is added.
+- Known limits: rules a custom checker's default run adds beyond the cap are outside the judgement; after the yes the
+  upgrade report still relays the first spec-layer line (queued as `UPGRADE-REPORT-RELAYS-THE-PRE-REPLACE-SPECS-LINE`).
+
 ## 14.29.1 — an upgrade keeps the sandbox-masks block byte for byte and names every non-blank line it takes out (AD-181)
 
 **On a hidden deployment, the footprint step of `/agent-workflow-kit upgrade` (`hide-footprint --reconcile`) now leaves

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". New to the epic, story and task tier? Run `/agent-workflow-kit tier`. A typed decision with a confidence from Jev? Run `/agent-workflow-kit jev`.
 disable-model-invocation: true
 metadata:
-  version: '14.29.1'
+  version: '14.30.0'
 ---
 
 # agent-workflow-kit

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "14.29.1",
+  "version": "14.30.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/recommendations.md

@@ -17,7 +17,7 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd <project-root> [--
 
 1. **`--cwd` is REQUIRED** — the target project is explicit, never inferred from the shell's current directory (a subdirectory invocation still advises on the named root).
 2. **Verdict first (present-even-when-empty, opening at the `## Recommendations (agent-workflow)` header).** With everything optimal the body is exactly `no recommendations — flow optimal.` — the empty-state line ALONE is the verdict, zero added lines. Every other state opens the body with ONE verdict line composed from the frozen templates: `{K} item(s) need attention` leads when any item's severity is `attention` (a CONFIGURED declaration that is broken, drifted, degrading or invalid — the deployment needs review); `{N} optional recommendation(s), apply any you want` covers the `optional` class (offers to enable an unconfigured capability), led by `nothing is broken` ONLY when no item needs attention AND no probe check was skipped (a skipped probe could hide an attention-class problem — the claim never overreaches); `optimality NOT attested — {M} probe check(s) skipped` is appended last whenever probe checks were skipped. (The `(s)` invariant form IS the pinned pluralization — no singular/plural branching.) Items render attention-first, each tagged `needs attention:` / `optional:`. A failed probe renders as a stated `⚠ skipped item …` line — never a crash, never a fabricated item.
-3. **The apply-through-agent lane — an explicit informed-consent checkpoint:** the agent applies chat and harness items on the chat yes, harness items by the consent route below. A chat item is never retried outside the sandbox and every failure of a chat step is a STOP. A user item, and any apply slot that opens with HAND-APPLY whatever its lane, is the user's own step, handed over as worded. After presenting, OFFER to apply; the user selects items in plain language; for each selected item you **surface its posture note inline** where one exists (the per-item notes below cover exactly the risk-marked keys). For a chat item: the user **explicitly confirms**, and **only then** — **no command runs before confirmation** — do you run the rendered command. Do NOT infer safety from the presence or absence of an `--apply` flag: most chat items' rendered command IS the mutation and completes on that one run, **including a no-`--apply` mutation** such as `spec-adoption`'s `ensure-configs --reconcile --only specs`. Some items instead render a **dry-run preview** that changes nothing and prints an explicit follow-up `--apply`/mutating command to run NEXT (e.g. the `gates-declaration` seeder): after the SAME confirmation you run that printed follow-up command — no second ask, no improvisation (each writer keeps its own consent semantics: previews, `--apply` flags, refusals). An item marked **HAND-APPLY** (e.g. `enforcement` or `read-lane.stale`) is **the user's own step** — hand the user its rendered line together with its posture note; HAND-APPLY is **maintainer territory wherever it renders** — the apply slot or the `recipe:` line. For `worktrees-dir` the two classes COMPOSE in one item and the ORDER is part of the contract: its `recipe:` line is the HAND-APPLY grant advice, its apply one-liner is the dry-run ack preview, and you **wait for the maintainer to confirm the grant is applied (or the terminal fallback chosen)** before running that preview and the exact `--apply` command it prints — the ack RECORDS a choice that must already have been made, and against a trusted host NO the item renders no ack at all.
+3. **The apply-through-agent lane — an explicit informed-consent checkpoint:** the agent applies chat and harness items on the chat yes, harness items by the consent route below. A chat item is never retried outside the sandbox and every failure of a chat step is a STOP. A user item, and any apply slot that opens with HAND-APPLY whatever its lane, is the user's own step, handed over as worded. After presenting, OFFER to apply; the user selects items in plain language; for each selected item you **surface its posture note inline** where one exists (the per-item notes below cover exactly the risk-marked keys). For a chat item: the user **explicitly confirms**, and **only then** — **no command runs before confirmation** — do you run the rendered command. Do NOT infer safety from the presence or absence of an `--apply` flag: most chat items' rendered command IS the mutation and completes on that one run, **including a no-`--apply` mutation** such as `spec-adoption`'s `ensure-configs --reconcile --only specs` (behind an edited file it prints a replace line that takes its own yes). Some items instead render a **dry-run preview** that changes nothing and prints an explicit follow-up `--apply`/mutating command to run NEXT (e.g. the `gates-declaration` seeder): after the SAME confirmation you run that printed follow-up command — no second ask, no improvisation (each writer keeps its own consent semantics: previews, `--apply` flags, refusals). An item marked **HAND-APPLY** (e.g. `enforcement` or `read-lane.stale`) is **the user's own step** — hand the user its rendered line together with its posture note; HAND-APPLY is **maintainer territory wherever it renders** — the apply slot or the `recipe:` line. For `worktrees-dir` the two classes COMPOSE in one item and the ORDER is part of the contract: its `recipe:` line is the HAND-APPLY grant advice, its apply one-liner is the dry-run ack preview, and you **wait for the maintainer to confirm the grant is applied (or the terminal fallback chosen)** before running that preview and the exact `--apply` command it prints — the ack RECORDS a choice that must already have been made, and against a trusted host NO the item renders no ack at all.
 4. Registry strings (benefits + item texts) are frozen tool data, fact-true, ONE line under the pinned shape cap — posture/risk detail lives in the notes below at the consent moment, never inline in the overview. The dual velocity+security wording (`safer — blast radius bounded by the OS sandbox, not human attention`) rides ONLY the items with a real security delta (the autonomy render, the sandbox provisioning); the bridge-wrappers item claims **velocity only**.
 
 The **consent route** for a harness item: run its `check:` line in the sandbox and show its result. On the check's `masked:` line, say so and run that same check line once more outside the sandbox, so it re-judges in the apply's own environment; the yes is taken on the outside result. Take the user's yes on that result and run its `apply:` line with that result's digest once, outside the sandbox at once, so the harness asks at the point of action (with the apply ask rule seeded, its own dialog); never another line, never unseen. When velocity-core, kit-tools-tier or bridge-tier is among the user's picks (velocity-core preferred), check, confirm and apply it, or leave it pending, before any other pick's check runs, so its apply seeds the ask rule before the other harness applies. When the harness's auto mode refuses the check or the apply, say so and give the one plain step: leave auto mode for this one action (Shift+Tab in the terminal, the mode indicator in an editor) and say yes, or run `npx @sabaiway/agent-workflow-kit@latest init` in a terminal of your own. On the user's word, run the same line once more when they left auto mode, never another, never unseen; when they ran `init` instead, run the advisor again and offer only what is still pending, each through this route from its check (after a restart `init` asked for, the next session's upgrade does it). When that refusal hits the velocity-core, kit-tools-tier or bridge-tier pick taken first, run no other pick's check until the user answers the plain step. A check that refuses (exit 1) leaves the item unapplied and pending, its result shown; a changed digest (exit 5) applies nothing, shows the new result and asks a new yes. A no, a harness refusal and any other failure of a harness apply leave the item pending with its output shown, and the agent continues. `init`, run in a console from the project's folder, is the route the user may take instead.
@@ -40,7 +40,7 @@ A variant's posture note, where its key has one, is printed by `init` from this
 - `enforcement` — copies the bundled `references/scripts/*.mjs` runnable scripts and their tests, then installs the pre-commit hook. It is HAND-APPLY, the user's own step; the offer renders only when `scripts/` is absent or a plain directory contains no bundled basename, so the copy never clobbers an existing file and never follows a link. The hook invokes `node` directly, so a committer without it on PATH gets a loud failure. The installer refuses to overwrite a pre-commit hook it did not write — on that refusal stop and merge the hook by hand (bootstrap step 9); the copied scripts stay in place. Risk profile: local tooling and a Git hook are added only when the maintainer applies the shown command.
 - `mcp-channel` — the offer is to REGISTER the kit's read-only stdio MCP server in this project on the harness lane: a registration is a command your MCP client will RUN. The agent applies it on the chat yes after the check; `init` previews the exact entry and applies it on the terminal y as the route the user may take instead. What the registration buys: path questions and literal searches become typed tool calls whose arguments are named JSON fields instead of a string handed to a shell, so a pipe, a redirect or a quote inside a pattern or a path stays DATA and is never interpreted — they are perfectly legal bytes to search for, there is simply no shell to read them as operators. Posture: the server is a **read-only child of your client** (path/type/size/line facts and literal search over this project root; no write and no exec API), and like the client itself it runs **outside the Bash sandbox** — the sandbox is not what bounds it, the server's own root containment is. The two allow rules it adds make those two tools promptless and nothing else. The **`.differing`** arm is also a harness item: an `agent-workflow` entry already stands in `.mcp.json` and **structurally differs** from what this kit copy would write (another kit copy, a hand-edited path, an added `env`; the comparison ignores key order, so re-serialized identical bytes are the same registration). The check shows the entry standing in `.mcp.json` and the entry it would write; the chat yes confirms the replacement. `init` previews `mcp --replace` and replaces only on the terminal y. Stated limit: this item does **not** detect a `disabledMcpjsonServers` veto, so a converged `mcp-channel` means *what the mode writes is in place*, not *the client will load it* — see `${CLAUDE_SKILL_DIR}/references/modes/mcp.md` for why that check was subtracted rather than half-built. Risk profile: a new read-only channel your client will launch; no write or exec exposure; a differing registration is replaced only on the checked chat yes or the terminal y and every other declaration is kept.
 - ADDITIONAL `gates-inert` arms (the third outcomes) — two further arms, and they differ in whether anything is BROKEN. **`producer-unrecognized`** — a checker with no producer anywhere in the declaration, on a tracked tree the changed-line coverage domain cannot reach (`.ts`/`.tsx`/`.jsx`/`.mts`/`.cts` strictly outnumber `.mjs`/`.cjs`/`.js`): the dead pair is real, so this arm is **HAND-APPLY** and the two remedies are marking the real producer with `"lcovProducer": true` or dropping the checker. Never a `node --test` prescription over a project that has no such suite, never the fill preview, and never an acknowledgement — a dead pair is broken, not narrow, and removing a producer after an acknowledgement lands right back in this arm. **`coverage-domain-narrow`** — the producer/checker pair IS live and the tree is still dominated by what the domain excludes: nothing is broken, and the honest sentence is that certification covers the assessable minority. Its apply is the consent-gated **ack writer** preview (a NEUTRAL fingerprint into `docs/ai/acks.json` as `coverageDomainAck`, never a security key); after the SAME confirmation you run the `--apply` it prints. The fingerprint binds the FACT — the verdict plus the unsupported extensions present, never the file counts — so an acknowledged project stays quiet as it grows and re-fires when a new unsupported language arrives or the verdict flips. The census reads the TRACKED tree with a read-only `git ls-files`; a tree it cannot read (a non-git deployment) becomes a stated skip, so optimality is withheld rather than assumed. Risk profile: no enforcement change of any kind — one acknowledgement recorded in a family-owned file, and one hand edit that stays the maintainer's.
-- `spec-adoption` — the feature-spec layer's ADOPTION STATE, judged from `docs/ai/specs/` alone through the same census `spec-check --all` runs, so a store the checker would refuse to observe is never counted here either. Both arms are OFFERS (`optional`) — the layer is opt-in, and `attention` stays reserved for a configured declaration that is broken. **`not-adopted`** (no store): every plan then cites zero governing specs by default and nothing says adoption never started; its apply is the spec-layer ensure one-liner (`ensure-configs --reconcile --only specs`, the same seed `upgrade` runs — it writes the reader/checker pairs and the store root, create-only, and skips with a stated reason where no Node evidence exists), and its `recipe:` line carries a NAMED **HAND-APPLY alternative** — the DECLINE preview (`ack-write --lane spec-adoption`, a dry-run that prints the exact `--apply`), which records `specAdoptionAck` in the family-owned `docs/ai/acks.json`. **The two are exclusive, and the order is part of the contract:** ask which the maintainer wants BEFORE the confirmation; on "seed" run the apply; on "decline" run NOTHING — hand over the preview line and let them run it and its printed `--apply`; never run the seed after a decline was chosen, and never run the decline preview for them. **`adopting`** (a store with no live contract): an optional item naming the draft count; its apply is that same decline preview (a dry-run; after the SAME confirmation you run the `--apply` it prints), and the honest remedy is authoring a contract from the skill's `SPEC_TEMPLATE.md`. A recorded decline silences BOTH arms and shows on `status` as ` — declined`; one live contract makes the decline moot. An unreadable store is a stated skip, never `flow optimal`. Risk profile: the seed writes only create-only files under `scripts/` and `docs/ai/specs/`; the decline writes one key into the ack store; nothing here authors a spec or blocks a plan.
+- `spec-adoption` — the feature-spec layer's ADOPTION STATE, judged from `docs/ai/specs/` alone through the same census `spec-check --all` runs, so a store the checker would refuse to observe is never counted here either. Both arms are OFFERS (`optional`) — the layer is opt-in, and `attention` stays reserved for a configured declaration that is broken. **`not-adopted`** (no store): every plan then cites zero governing specs by default and nothing says adoption never started; its apply is the spec-layer ensure one-liner (`ensure-configs --reconcile --only specs`, the same seed `upgrade` runs — it seeds the reader/checker pairs and the store root, and skips with a stated reason where no Node evidence exists), and its `recipe:` line carries a NAMED **HAND-APPLY alternative** — the DECLINE preview (`ack-write --lane spec-adoption`, a dry-run that prints the exact `--apply`), which records `specAdoptionAck` in the family-owned `docs/ai/acks.json`. **The two are exclusive, and the order is part of the contract:** ask which the maintainer wants BEFORE the confirmation; on "seed" run the apply; on "decline" run NOTHING — hand over the preview line and let them run it and its printed `--apply`; never run the seed after a decline was chosen, and never run the decline preview for them. **`adopting`** (a store with no live contract): an optional item naming the draft count; its apply is that same decline preview (a dry-run; after the SAME confirmation you run the `--apply` it prints), and the honest remedy is authoring a contract from the skill's `SPEC_TEMPLATE.md`. A recorded decline silences BOTH arms and shows on `status` as ` — declined`; one live contract makes the decline moot. An unreadable store is a stated skip, never `flow optimal`. Risk profile: the seed writes create-only files under `scripts/` and `docs/ai/specs/` and refreshes a script body a release shipped; behind an edited file it prints a replace line that takes its own yes; the decline writes one key into the ack store; nothing here authors a spec or blocks a plan.
 - `profile-gap` — each item's apply is a PREVIEW that writes nothing, and consent takes two steps: the confirmed pick runs the preview and you relay every line it prints (the environment-resolved slot values, each checker `entry:` line with its trust-chain disclosure, a Communication region the insert plans in the same run); the same line with ` --apply` appended runs only on a SECOND yes over those lines, never carried by the first. Items whose apply lines are byte-equal are one writer and take one answer: the tier preview's `--apply` writes the absent slots, the store seed and the queue seed together; the checker verb writes only its own entries; the insert writes every region it plans, all or nothing, so a `communication-absent` skip beside a declined `story-sessions-section` gets its own ask after the insert's full preview. A no records nothing and the item stays on the screen. A DECLINE is asked apart from later, before anything runs, and runs `node ${CLAUDE_SKILL_DIR}/tools/tier-preview.mjs --decline --cwd <project-root>` only when the user refuses EVERY item the tier preview then reports offered: it records each of them at the shipped lineage, and a declined item leaves the screen until a lineage step changes the profile. An undecidable entry is a stated skip naming its reason, the remedy by reason: a prior → the upgrade's `lens` reconcile; an absent region → the insert; a customized region → a hand edit only (the lens preserves it), so that skip stands and withholds `flow optimal`. Risk profile: the tier preview's `--apply` rewrites `docs/ai/orchestration.json` in canonical form with the `_README` note and creates `docs/ai/epics/.gitkeep` and `docs/plans/queue.md` create-only; the insert adds regions to `docs/ai/agent_rules.md`; the checker verb adds entries to the PRIVILEGED `docs/ai/gates.json`; the decline writes `docs/ai/profile-declines.json`; nothing here commits.
 - `jev-connect` — the lane is user and env-dependent: the connect command is the user's own step in a terminal of their own, where it asks for the key; the key never reaches the agent or the chat (the command refuses without a terminal, and a terminal is not consent). When the recipe line opens with `run the apply in <place>`, that place is the terminal to run it in; `init`, run there, offers the command on its own consent line. The command reads the key with no echo, makes one network call to api.typesafe.ai with the vendor's sample text only on the user's own run, and writes the key in plain text — as managed export lines in the shell's startup files (bash: ~/.bashrc and the login file, created as ~/.bash_profile when none exists; zsh: ~/.zshrc), as the kit's own file ~/.config/fish/conf.d/typesafe-api-key.fish for fish, or on Windows as the user environment variable TYPESAFE_API_KEY, stored in the Windows user environment; a process already running at the save can keep its old environment and hand it to what it starts — the guide's key mark confirms the agent sees it (a file is readable by any process running as that user, and by other local accounts when one is world-readable in a traversable home); the vendor keeps data under its processing agreement and offers zero retention only to enterprise accounts. The item reads the environment the agent's commands run in: a host setting that filters it shows the item while the key is set in the user's shell. The decline is the HAND-APPLY alternative on the recipe line, asked apart BEFORE the confirmation (the `spec-adoption` order): on "connect" hand over the apply line, on "decline" run nothing and hand over the recipe line; the decline is recorded per project as `jevConnectAck` in `docs/ai/acks.json`. Risk profile: a plain-text key in the user's startup files or the Windows user environment, written by a command the user runs; one network call from that run.
 - `jev-skill` — the lane is harness; both `jev-skill` and `jev-skill.earlier` are env-dependent: the agent applies the item on the chat yes after the check, showing the files it would write; it changes no harness setting. `init` applies it on the batch terminal yes as the route the user may take instead. When the recipe line opens with `run the apply in <place>`, that place is where a user who prefers their own terminal runs it. The skill is third-party text — the vendor's, MIT — that the kit ships pinned and installs as a verified copy into three agent skill roots: `~/.agents/skills`, the Claude Code skills dir (`CLAUDE_CONFIG_DIR` or `~/.claude`) and `~/.gemini/config/skills`. It is never updated silently: a copy at an earlier pin is replaced only by that command, and a foreign copy is left untouched and named on the recipe line. A copy the vendor's `skills` CLI wrote with the same bytes reads current, and a later pin move replaces it like a kit copy; a vendor plugin install is invisible to the file check, so the Claude Code root may read absent while the plugin serves it. Only when the user asks to see the plan does the agent run the command without `--apply` (a read-only dry run). The decline is the HAND-APPLY alternative on the recipe line, asked apart BEFORE the confirmation: on "install" run the check line and, on the yes given on its result, the apply line by the consent route, on "decline" run nothing and hand over the recipe line; the decline is recorded per project as `jevSkillAck` in `docs/ai/acks.json`. Risk profile: third-party text written into the user's agent skill roots by the kit's skill command; no network.

package/references/modes/upgrade.md

@@ -12,7 +12,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` / `refreshed` / `regenerated` / `re-derived` / `already-current` / `customized-preserved` / `malformed-preserved` / `already-present` / `not-placed` / `skipped-no-node-evidence` / `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` / `refreshed` / `regenerated` / `re-derived` / `already-current` / `customized-preserved` / `malformed-preserved` / `already-present` / `not-placed` / `skipped-no-node-evidence` / `old-adr-layout-migration-instructed` / `failed` — consent (conditional): a specs replace line → ONE yes naming every file the custom lines name and saying their edits are overwritten, asked even on a non-zero exit; on the yes run the printed line, then STOP if that run fails or an op it does not re-run failed; on a no STOP on any failed op.
    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.
@@ -33,7 +33,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 eight** ensures — orchestration config · gate declaration · autonomy declaration · vehicles declaration · executor re-derivation · enforcement scripts · spec layer · 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); a refresh-class op rewrites only what it owns — the outcome tokens by ensure, below, name each arm, the executor's re-derivation among them. 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, autonomy and vehicles → `seeded` / `already-present`; executor → `not-placed` / `already-current` / `re-derived`; scripts → `seeded` / `already-present` / `old-adr-layout-migration-instructed` / `skipped-no-node-evidence`; specs → `seeded` / `refreshed` / `already-present` / `customized-preserved` / `skipped-no-node-evidence`; 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`, `node-evidence-unverifiable`, `wrong-node-kind`, `vehicle-settings-unreadable`, `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 eight reach an equal-head deployment **without a lineage-head bump or a migration file** (all inherently outside the docs cap-validator).
+   **`configs` — the project-configuration ensures, ONE run.** The ONE command performs **all eight** ensures — orchestration config · gate declaration · autonomy declaration · vehicles declaration · executor re-derivation · enforcement scripts · spec layer · 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); a refresh-class op rewrites only what it owns — the outcome tokens by ensure, below, name each arm, the executor's re-derivation among them. 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, autonomy and vehicles → `seeded` / `already-present`; executor → `not-placed` / `already-current` / `re-derived`; scripts → `seeded` / `already-present` / `old-adr-layout-migration-instructed` / `skipped-no-node-evidence`; specs → `seeded` / `refreshed` / `already-present` / `customized-preserved` / `skipped-no-node-evidence`; index → `regenerated` / `already-current` / `customized-preserved`; 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`, `node-evidence-unverifiable`, `wrong-node-kind`, `vehicle-settings-unreadable`, `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 — once row 3's replace ask is answered when a specs replace line printed, then as that ask says** — 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 eight reach an equal-head deployment **without a lineage-head bump or a migration file** (all 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.)
 
@@ -45,9 +45,9 @@ 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). **Whether Node runs here is PROVEN, never proxied:** the ensure seeds on a regular `package.json` at the root OR on any kit-seeded `scripts/*.mjs` already deployed (a bootstrap places them into projects that never carry a `package.json`); only when every probe answers absent does it report `skipped-no-node-evidence`, a line naming every probe it checked, while the config ensures still run; a probe that cannot be read is `failed` with the cause `node-evidence-unverifiable`, nothing written. **A `skipped-*` outcome whose stated reason this tool could itself disprove may not exist** — the retired `skipped-no-node` was exactly that, printed beside twenty deployed Node scripts. 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.
+   **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); under a hook module that is not the bundled one, a write the project's own checker rejects is put back → `customized-preserved`. 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: an untouched tree changes nothing.
 
-   **What the spec-layer ensure does.** A deployment older than the feature-spec layer lacks `scripts/spec-schema.mjs` and `docs/ai/specs/index.md`, and its deployed `check-docs-size.mjs` predates the store collapse. In ONE order: the reader pair, then the checker pair — each seeded when absent and REFRESHED only while a file's bytes are a body a release shipped (an append-only digest catalog → `refreshed`; an edited body is preserved verbatim and withholds the writes that depend on it, the checker lane waiting on a byte-current reader pair); the store root is seeded from the bundled template, date rendered, ONLY behind a checker pair current after the run — an older or edited checker renders the store row by row and reds the hook's `--check-index`, so behind a custom checker the store root is NOT seeded and the line names the remedy (copy the pair from `${CLAUDE_SKILL_DIR}/references/scripts/` by hand, re-run). One token by precedence: `seeded` > `refreshed` > `customized-preserved` (an edited pair, and this run wrote nothing) > `already-present`; `skipped-no-node-evidence` only when neither a root `package.json` nor any kit-seeded `scripts/*.mjs` is present (the same Node-evidence probe the enforcement-script ensure uses; an unreadable probe is `failed` / `node-evidence-unverifiable`); every line states what this run did, and a write that stops partway names what landed. The legacy-ADR instruct never withholds it. **The adoption state this seed leaves behind is reported, never assumed:** the Recommendations section (step 4 / 8) carries the `spec-adoption` item — `not adopted` (the store is absent: the seed offered, the decline a named hand-apply alternative), `adopting` (a store with no live contract: the decline offered), silenced by a recorded decline (`ack-write --lane spec-adoption`), and a store the probe cannot read is a stated skip — and `status` prints the same state on its own line.
+   **What the spec-layer ensure does.** A deployment older than the feature-spec layer lacks `scripts/spec-schema.mjs` and `docs/ai/specs/index.md`, and its deployed `check-docs-size.mjs` predates the store collapse. In ONE order: the reader pair, then the checker pair — each seeded when absent and REFRESHED only while a file's bytes are a body a release shipped (an append-only digest catalog → `refreshed`; an edited body is preserved verbatim and withholds the writes that depend on it, the checker lane waiting on a byte-current reader pair); the store root is seeded from the bundled template, date rendered, ONLY behind a checker pair current after the run — an older or edited checker renders the store row by row and reds the hook's `--check-index`; edited files are replaced only on row 3's yes. One token by precedence: `seeded` > `refreshed` > `customized-preserved` (an edited pair, and this run wrote nothing) > `already-present`; `skipped-no-node-evidence` only when neither a root `package.json` nor any kit-seeded `scripts/*.mjs` is present (the same Node-evidence probe the enforcement-script ensure uses; an unreadable probe is `failed` / `node-evidence-unverifiable`); every line states what this run did, and a write that stops partway names what landed. The legacy-ADR instruct never withholds it. **The adoption state this seed leaves behind is reported, never assumed:** the Recommendations section (step 4 / 8) carries the `spec-adoption` item — `not adopted` (the store is absent: the seed offered, the decline a named hand-apply alternative), `adopting` (a store with no live contract: the decline offered), silenced by a recorded decline (`ack-write --lane spec-adoption`), and a store the probe cannot read is a stated skip — and `status` prints the same state on its own 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. Of step 3's run-list, only this migration and `tools/checker-gates.mjs` under the `tier` ask change an existing gates.json (the FILL preview runs at init).
 
@@ -108,7 +108,7 @@ 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.
+   **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 changes nothing, 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:
    - **A skip line that contradicts the observed tree is a FINDING, never pasted as neutral.** Every ensure skip names the fact it proved (the probes that answered absent, the layout it read); if the tree you can see disproves that reason — a "no Node" skip beside deployed Node scripts, a "not deployed" skip beside a stamped `docs/ai` — do not relay the line as an outcome: raise it in the report as a defect of the tool, with the contradicting fact named, and stop short of any step that would build on the skip.
    - **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 **eight project-configuration ensure** (`configs`) lines exactly as the one ensure run composed them (the ensures and 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) and the **story-sessions section** outcome (its own set: refreshed / already current / custom edit preserved + note / section absent — noted / over the file's line cap — refused); the **full-flow offer** (`tier`) lines; 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`).
@@ -120,5 +120,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.** Run `node ${CLAUDE_SKILL_DIR}/tools/migration-notes.mjs --cwd <project>` and relay its stdout lines verbatim, in order; a non-zero exit relays its one named line and STOPs, except `stamp-absent`, which routes back to step 1. Then run the preview `node ${CLAUDE_SKILL_DIR}/tools/migration-blocks.mjs --cwd <project>`. If its lines say both blocks are missing (pre-1.1.0), 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; a single missing block keeps its single ask (step 7). Then apply exactly the notes the tool listed, in its order ("only those newer than the project's stamp" is why, never a second selection). 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. For a block the preview names as needing its answer, **ask the user their conversational language** (`--language`) or **whether the agent may attribute work to itself / AI** (`--attribution`, defaulting to `off`), never re-asking a step-6 answer; then re-run the preview with `--apply` and the answers, relaying its lines. Exit 1 `answer-missing`: ask exactly what its lines name and re-run `--apply` once; a second one STOPs. Any other exit 1 is a named refusal: relay it with its recovery (`cap`: trim `AGENTS.md`, re-run) and STOP before the finalizer and the stamp. **Then, before the stamp, re-run the LATE navigator finalizer:** the migrations of steps 6–7 may have 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).
+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. For a block the preview names as needing its answer, **ask the user their conversational language** (`--language`) or **whether the agent may attribute work to itself / AI** (`--attribution`, defaulting to `off`), never re-asking a step-6 answer; then re-run the preview with `--apply` and the answers, relaying its lines. Exit 1 `answer-missing`: ask exactly what its lines name and re-run `--apply` once; a second one STOPs. Any other exit 1 is a named refusal: relay it with its recovery (`cap`: trim `AGENTS.md`, re-run) and STOP before the finalizer and the stamp. **Then, before the stamp, re-run the LATE navigator finalizer:** the migrations of steps 6–7 may have 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 changes nothing; a failure STOPs this upgrade like any other ensure).
 8. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`4.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 **eight project-configuration ensure** (`configs`) lines (enumerated in step 3) — 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** + **story-sessions section** outcomes (same outcome sets as step 4), the **full-flow offer** (`tier`) outcome, 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 route (per picked item: posture note → explicit confirm → chat: the one-liner; harness: the check line, then on the yes to its result the apply line; user: the user's own step — `${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

@@ -58,6 +58,51 @@ maxLines: 80
 | [\`a.md\`](./a.md) | state | 10/10 | 2026-07-18 | never |
 `;
 
+describe('spec:docs-navigator/S1 the navigator stamps a cap it honours', () => {
+  const createNames = (count) => Array.from({ length: count }, (_, index) => `n${String(index + 1).padStart(2, '0')}`);
+  const buildDocs = (names) => ({ docs }) => {
+    for (const name of names) writeFileSync(join(docs, `${name}.md`), DOC(name));
+  };
+  const countLines = (text) => text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
+
+  it("a tree whose navigator renders exactly 80 lines stamps maxLines 80, byte-identical to today's render", async () => {
+    const names = createNames(57);
+    await withRoot(buildDocs(names), async ({ root }) => {
+      assert.equal((await cli(['--write-index', `--root=${root}`, '--today=2026-07-18'])).code, 0);
+      const index = indexOf(root);
+      const rows = names.map((name) => `| [\`${name}.md\`](./${name}.md) | state | 10/10 | 2026-07-18 | never |\n`);
+      assert.equal(countLines(index), 80);
+      assert.equal(index, EXPECTED_INDEX + rows.join(''));
+    });
+  });
+
+  it('a tree of 81 lines stamps maxLines 81 and both checker runs exit 0', async () => {
+    await withRoot(buildDocs(createNames(58)), async ({ root }) => {
+      assert.equal((await cli(['--write-index', `--root=${root}`, '--today=2026-07-18'])).code, 0);
+      const index = indexOf(root);
+      const checked = await runCli([`--root=${root}`]);
+      const fresh = await runCli(['--check-index', `--root=${root}`]);
+      assert.equal(countLines(index), 81);
+      assert.equal(index.match(/^maxLines: \d+$/m)?.[0], 'maxLines: 81', `default: ${checked.code}, --check-index: ${fresh.code}`);
+      assert.equal(checked.code, 0, checked.stdout + checked.stderr);
+      assert.equal(fresh.code, 0, fresh.stdout + fresh.stderr);
+    });
+  });
+
+  it('a hand-edited cap line is stale under --check-index', async () => {
+    await withRoot(buildDocs(createNames(58)), async ({ root, docs }) => {
+      assert.equal((await cli(['--write-index', `--root=${root}`, '--today=2026-07-18'])).code, 0);
+      const index = indexOf(root);
+      const edited = index.replace(/^maxLines: \d+$/m, 'maxLines: 90');
+      assert.notEqual(edited, index);
+      writeFileSync(join(docs, 'index.md'), edited);
+      const { code, stdout, stderr } = await runCli(['--check-index', `--root=${root}`]);
+      assert.equal(code, 1);
+      assert.match(stdout + stderr, /is stale/);
+    });
+  });
+});
+
 describe('check-docs-size runCli — refusal branches', () => {
   it('an unknown argument exits 2 naming it', async () => {
     const { code, stderr } = await cli(['--bogus']);

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

@@ -11,6 +11,9 @@ 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 NAVIGATOR_LINE_FLOOR = 80;
+const EXTRA_DOC_COUNT = 85;
+
 const makeTree = (prefix) => {
   const dir = mkdtempSync(join(tmpdir(), prefix));
   mkdirSync(join(dir, 'docs', 'ai'), { recursive: true });
@@ -330,3 +333,28 @@ describe('check-docs-size --ensure-index', () => {
     }
   });
 });
+
+describe('spec:docs-navigator/S2 --ensure-index past the 80-line floor', () => {
+  it('writes a navigator past 80 lines that the default run and --check-index accept', async () => {
+    const root = makeTree('cds-ensure-past-floor-');
+    try {
+      for (const number of Array.from({ length: EXTRA_DOC_COUNT }, (_, index) => index)) {
+        writeFileSync(join(root, 'docs', 'ai', `z-extra-${number}.md`), DOC(`extra ${number}`));
+      }
+      const { code, stdout } = await runCli(['--ensure-index', `--root=${root}`]);
+      assert.equal(code, 0);
+      assert.match(stdout, /ensure-index: regenerated/);
+      const navigator = readFileSync(join(root, 'docs', 'ai', 'index.md'), 'utf8');
+      const lineCount = navigator.split('\n').length - (navigator.endsWith('\n') ? 1 : 0);
+      const maxLines = Number(navigator.match(/^maxLines: (\d+)$/m)?.[1]);
+      assert.ok(lineCount > NAVIGATOR_LINE_FLOOR);
+      const defaultRun = await runCli([`--root=${root}`]);
+      const indexCheck = await runCli(['--check-index', `--root=${root}`]);
+      assert.equal(defaultRun.code, 0, defaultRun.stdout);
+      assert.equal(maxLines, lineCount);
+      assert.equal(indexCheck.code, 0, indexCheck.stdout);
+    } finally {
+      drop(root);
+    }
+  });
+});

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

@@ -45,6 +45,8 @@ const pathsFor = (root) => {
 };
 
 const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const NAVIGATOR_CAP_FLOOR = 80;
+const countLines = (text) => text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
 
 // 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.
@@ -263,7 +265,7 @@ export const inspectFile = async (found, today, root = ROOT) => {
     return { path: rel, lineCount: 0, frontmatter: null, spec: null, refused: true, errors: [refusal], warnings: [] };
   }
   const text = await readFile(filePath, 'utf8');
-  const lineCount = text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
+  const lineCount = countLines(text);
   const fm = parseFrontmatter(text);
   const spec = readSpecVerdict(rel, text);
 
@@ -332,7 +334,7 @@ lastUpdated: __TODAY__
 scope: permanent
 staleAfter: 30d
 owner: none
-maxLines: 80
+maxLines: __CAP__
 ---
 
 # Memory Map — __PROJECT__ \`docs/ai/\`
@@ -398,7 +400,6 @@ export const buildIndex = (rows, todayStr, meta = {}) => {
   const projectName = meta.projectName ?? DEFAULT_PROJECT_NAME;
   const onDemandLinks = meta.onDemandLinks ?? [];
   const hierarchicalLinks = meta.hierarchicalLinks ?? [];
-  const header = INDEX_HEADER.replace('__TODAY__', todayStr).replace('__PROJECT__', projectName);
   const tableHeader = `| File | Type | Lines/Max | Updated | Stale after |\n|------|------|-----------|---------|-------------|`;
   const singles = [];
   const grouped = COLLAPSE_GROUPS.map(() => []);
@@ -421,7 +422,8 @@ export const buildIndex = (rows, todayStr, meta = {}) => {
     hierarchicalLinks.length > 0
       ? `\n\n## Subdirectory \`AGENTS.md\` (hierarchical)\n\n${hierarchicalLinks.map((link) => `- ${link}`).join('\n')}`
       : '';
-  return `${header}${tableHeader}\n${tableRows}${onDemandSection}${hierarchicalSection}\n`;
+  const render = (cap) => `${INDEX_HEADER.replace('__CAP__', cap).replace('__TODAY__', todayStr).replace('__PROJECT__', projectName)}${tableHeader}\n${tableRows}${onDemandSection}${hierarchicalSection}\n`;
+  return render(Math.max(NAVIGATOR_CAP_FLOOR, countLines(render(NAVIGATOR_CAP_FLOOR))));
 };
 
 // Freshness regenerates the index with the on-disk header's OWN `lastUpdated`, so a mere day-rollover

package/tools/ensure-configs.mjs

@@ -8,8 +8,11 @@
 //   executor       .claude/agents/executor.md  re-derived from docs/ai/vehicles.json when its bytes differ; absent stays absent
 //   scripts        scripts/<ADR enforcement>   seed-if-missing, ADR-layout detect FIRST
 //   specs          scripts/<spec layer>        reader + checker pairs seeded when absent, refreshed only on
-//                  + docs/ai/specs/index.md    a shipped prior body, store root seeded behind a current checker
-//   index          docs/ai/index.md            regenerate-if-missing-or-stale (a GENERATED artifact)
+//                  + docs/ai/specs/index.md    a shipped prior body, an edited one replaced only on the
+//                                              user's yes; store root seeded behind a current checker
+//   index          docs/ai/index.md            regenerate-if-missing-or-stale (a GENERATED artifact); under
+//                                              a project hook module that is not the bundled one, a write
+//                                              the project's own checker rejects is put back
 //
 // Each was prose in references/modes/upgrade.md that an agent performed by hand. One command instead
 // of one per ensure is deliberate: independent runs would be as many chances to skip one, and the mode
@@ -19,7 +22,8 @@
 //   • --reconcile is REQUIRED. A bare run is a usage error, so nothing writes by accident.
 //   • --dry-run reports `would-*` tokens and writes nothing — never a write token.
 //   • The ops run in a FIXED order and one op's failure NEVER skips the rest: every op reports its own
-//     token, and the exit is non-zero when any of them failed.
+//     token, and the exit is non-zero when any of them failed. The one exception is the replace run
+//     (--replace-custom <digest>): specs, then index only when specs did not fail.
 //   • The deployment gate runs ONCE, before any op: an absent/symlinked docs/ai stops the whole run
 //     with the gate's own message rather than one copy of it per op.
 //
@@ -53,15 +57,25 @@ const EMPTY_CWD = '--cwd needs a path argument (an empty value would silently me
 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 EMPTY_REPLACE = '--replace-custom needs the digest its replace line printed — an empty value names no file to replace';
+const REPEATED_REPLACE = '--replace-custom was passed more than once — a replace run carries exactly ONE digest';
+const REPLACE_WITH_ONLY = '--replace-custom runs the spec layer and then the navigator, so it cannot be combined with --only — nothing was run';
+const REPLACE_WITH_DRY_RUN = "--replace-custom writes on the user's yes, so it cannot be combined with --dry-run — nothing was run";
+const INDEX_NOT_RUN = 'the navigator step did not run: a replace run runs it only after the spec layer succeeds';
 
 const HELP = `ensure-configs — the eight stamp-independent upgrade ensures, as ONE command.
 
 Usage:
   node ensure-configs.mjs --reconcile [--dry-run] [--only <op>] [--cwd <project>]
+  node ensure-configs.mjs --reconcile --replace-custom <digest> [--cwd <project>]
 
   --reconcile   required — run the eight 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)
+  --replace-custom <digest>
+                the replace run the specs ensure prints behind an edited spec-layer file, run only on
+                the user's yes: specs replaces every file its digest names, then index runs when
+                specs did not fail (not with --only or --dry-run; an empty value is a usage error)
   --cwd <dir>   the target project (default: the current directory)
   --help, -h    this help
 
@@ -69,19 +83,22 @@ Every SEED is CREATE-ONLY: an existing file is preserved byte-for-byte, never cl
 refreshed in place. Four ops refresh instead: the orchestration onboarding note, only while it still
 matches a canonical the kit shipped (your own wording is preserved verbatim); the spec-layer reader
 and checker pairs, only while a file's bytes are a body a release shipped (an edited file is
-preserved, and the writes that depend on it — the spec store root included — are withheld behind
-it); the placed executor vehicle (.claude/agents/executor.md), re-derived from docs/ai/vehicles.json
+preserved, the writes that depend on it — the spec store root included — are withheld behind it,
+and ONE printed replace line replaces every edited file only on the user's yes); the placed executor
+vehicle (.claude/agents/executor.md), re-derived from docs/ai/vehicles.json
 whenever its bytes differ from the derived body (a hand edit is replaced, never preserved; an absent
 file is never placed here); 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.
+whenever it is missing or stale; where a module the project's hook loads is not the bundled one,
+the project's own checker judges the navigator and a write it rejects is put back byte for byte.
+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.`;
 
 // 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, only: undefined, help: false };
+  const out = { reconcile: false, dryRun: false, cwd: undefined, only: undefined, replaceCustom: undefined, help: false };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === '--help' || a === '-h') out.help = true;
@@ -98,6 +115,13 @@ export const parseArgs = (argv) => {
       if (!ENSURE_OPS.includes(value)) throw fail(EXIT_USAGE, unknownOp(value));
       out.only = value;
       if (!inline) i += 1;
+    } else if (a === '--replace-custom' || a.startsWith('--replace-custom=')) {
+      if (out.replaceCustom !== undefined) throw fail(EXIT_USAGE, REPEATED_REPLACE);
+      const inline = a.startsWith('--replace-custom=');
+      const value = inline ? a.slice('--replace-custom='.length) : argv[i + 1];
+      if (value === undefined || value === '' || (!inline && value.startsWith('-'))) throw fail(EXIT_USAGE, EMPTY_REPLACE);
+      out.replaceCustom = 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.
@@ -114,25 +138,34 @@ export const parseArgs = (argv) => {
   if (!out.help && !out.reconcile) {
     throw fail(EXIT_USAGE, 'nothing to do — pass --reconcile (see --help). This tool never writes without it.');
   }
+  if (out.replaceCustom !== undefined && out.only !== undefined) throw fail(EXIT_USAGE, REPLACE_WITH_ONLY);
+  if (out.replaceCustom !== undefined && out.dryRun) throw fail(EXIT_USAGE, REPLACE_WITH_DRY_RUN);
   return out;
 };
 
+const runOne = (op, args) => {
+  try {
+    return ENSURE_IMPLEMENTATIONS[op](args);
+  } catch (err) {
+    return failedOutcome(op, err);
+  }
+};
+
 // 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, only }) =>
-  (only ? [only] : ENSURE_OPS).map((op) => {
-    try {
-      return ENSURE_IMPLEMENTATIONS[op]({ cwd, kitRoot, dryRun, deps });
-    } catch (err) {
-      return failedOutcome(op, err);
-    }
-  });
-
-const render = (outcomes, dryRun, only) => {
+// without its autonomy seed just because the first ensure hit an unreadable file. The replace run is
+// the one exception: index runs only after a specs op that did not fail, and otherwise says so.
+export const runEnsures = ({ cwd, kitRoot, dryRun, deps, only, replaceCustom }) => {
+  if (replaceCustom === undefined) return (only ? [only] : ENSURE_OPS).map((op) => runOne(op, { cwd, kitRoot, dryRun, deps }));
+  const specs = runOne('specs', { cwd, kitRoot, dryRun: false, deps, replaceCustom });
+  if (specs.failed) return [{ ...specs, lines: [...specs.lines, INDEX_NOT_RUN] }];
+  return [specs, runOne('index', { cwd, kitRoot, dryRun: false, deps })];
+};
+
+const render = (outcomes, dryRun, only, replace) => {
   // 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 scope = only ? `, --only ${only}` : '';
+  const scope = only ? `, --only ${only}` : replace ? ', --replace-custom' : '';
   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}`);
@@ -155,10 +188,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 one identical STOP per op would read as that many 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, only: args.only });
+    const outcomes = runEnsures({ cwd, kitRoot: ctx.kitRoot ?? KIT_ROOT, dryRun: args.dryRun, deps, only: args.only, replaceCustom: args.replaceCustom });
     return {
       code: outcomes.some((o) => o.failed) ? EXIT_FAILED : EXIT_OK,
-      stdout: render(outcomes, args.dryRun, args.only),
+      stdout: render(outcomes, args.dryRun, args.only, args.replaceCustom !== undefined),
       stderr: '',
     };
   } catch (err) {

package/tools/ensure-ops.mjs

@@ -24,7 +24,7 @@
 //
 // Dependency-free, Node >= 22. Every fs primitive is injectable (deps.*). No side effects on import.
 
-import { readFileSync, lstatSync } from 'node:fs';
+import { readFileSync, lstatSync, unlinkSync } 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';
@@ -36,6 +36,8 @@ import { VEHICLES_REL } from './vehicle-settings.mjs';
 import { surveyAdrLayoutStrict } from './family-registry.mjs';
 import { ENSURE_TOKENS, FAILURE_CAUSES, SEED_SCRIPTS } from './ensure-vocabulary.mjs';
 import { NODE_EVIDENCE, describeNodeProbes, probeNodeEvidence } from './node-evidence.mjs';
+import { classifyDeployedScript } from './script-priors.mjs';
+import { parseFrontmatter } from '../references/scripts/check-docs-size.mjs';
 
 // The closed vocabulary lives in its own PURE leaf so the read-only doc-parity lint can bind the
 // relayed token set without importing this module's writer graph. Re-exported here because every
@@ -297,11 +299,12 @@ export const ensureScripts = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
 
 // ── 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
+// The only ensure whose target is generated rather than authored: nothing to seed from, and on the
+// bundled path nothing to preserve — 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.
+// the one-generator rule exists to prevent. Under a hook module that is not the bundled one, the
+// project's own checker judges the navigator and a write it rejects is put back (spec docs-navigator).
 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;
@@ -317,9 +320,90 @@ const MAY_HAVE_WRITTEN = 'the navigator may already have been written — re-rea
 
 const describeExit = (result) => (result.signal ? `on signal ${result.signal}` : `with code ${result.status}`);
 const bothStreams = (result) => `${String(result.stdout ?? '')}${String(result.stderr ?? '')}`.trim();
+const describeExitWithOutput = (result, subject = 'it') => `${subject} exited ${describeExit(result)}${bothStreams(result) ? `: ${bothStreams(result)}` : ''}`;
+
+const HOOK_MODULES = ['check-docs-size.mjs', 'spec-schema.mjs'];
+const KEPT_JUDGE = `the project's own checker (${SCRIPTS_DIR}/check-docs-size.mjs --check-index)`;
+const KEPT_FITS = `in sync under ${KEPT_JUDGE} and within the maxLines it stamps`;
+const KEPT_PROBE_TIMEOUT_MS = 30_000;
+const countLines = (text) => text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
+const readStampedCap = (text) => { const value = parseFrontmatter(text)?.maxLines; const cap = value ? Number(value) : NaN; return Number.isNaN(cap) ? undefined : cap; };
+
+const surveyHookModule = (cwd, kitRoot, name, read, lstat) => {
+  const rel = `${SCRIPTS_DIR}/${name}`;
+  const probe = (() => { try { return probeSeedTarget(join(cwd, rel), lstat); } catch (err) { if (err?.code === 'ENOTDIR') return { present: false }; throw err; } })();
+  if (probe.wrongKind || !probe.present) return { rel, state: probe.wrongKind ? 'wrong-kind' : 'absent', wrongKind: probe.wrongKind };
+  const deployed = read(join(cwd, rel));
+  try {
+    return { rel, state: classifyDeployedScript(deployed, name, read(join(kitRoot, ...GENERATOR_PATH.slice(0, 2), name))) };
+  } catch (err) {
+    return { rel, state: 'bundle-unreadable', error: causeOf(err) };
+  }
+};
+
+const judgeKept = ({ cwd, spawn, read, lstat, deps }) => {
+  const result = spawn(process.execPath, [join(cwd, SCRIPTS_DIR, 'check-docs-size.mjs'), '--check-index'], { cwd, encoding: 'utf8', timeout: deps.keptProbeTimeoutMs ?? KEPT_PROBE_TIMEOUT_MS, killSignal: 'SIGKILL' });
+  if (result.error) return { error: `${causeOf(result.error)}${result.signal ? `, killed on signal ${result.signal}` : ''}` };
+  if (result.status !== 0) return { accepted: false, said: describeExitWithOutput(result), half: 'its index check' };
+  const text = lstatNoFollow(join(cwd, INDEX_REL), lstat)?.isFile() ? String(read(join(cwd, INDEX_REL), 'utf8')) : null;
+  const cap = text === null ? undefined : readStampedCap(text);
+  if (cap !== undefined && countLines(text) <= Number(cap)) return { accepted: true };
+  const why = text === null ? 'no navigator file stands' : cap === undefined ? 'the navigator stamps no maxLines' : `${countLines(text)} lines against the maxLines ${cap} it stamps`;
+  return { accepted: false, said: describeExitWithOutput(result), half: `the cap it stamps (${why})` };
+};
+
+const removeIndexIfPresent = (cwd, deps) => {
+  try {
+    (deps.unlink ?? unlinkSync)(join(cwd, INDEX_REL));
+  } catch (err) {
+    if (err?.code !== 'ENOENT') throw err;
+  }
+};
+
+const putBackIndex = (cwd, found, deps) => {
+  try {
+    if (found !== null) writeDocsAiFileAtomic(cwd, INDEX_REL, found, deps, { noun: 'the navigator' });
+    else removeIndexIfPresent(cwd, deps);
+  } catch (err) {
+    return causeOf(err);
+  }
+  return null;
+};
+
+const ensureKeptIndex = ({ cwd, kitRoot, drive, spawn, read, lstat, deps, hook }) => {
+  const judge = () => judgeKept({ cwd, spawn, read, lstat, deps });
+  const reportUnanswered = (verdict, after) => loud('index', 'index-probe-failed', `${INDEX_REL}: ${KEPT_JUDGE} could not be launched or did not answer in time (${verdict.error}) — ${after}`);
+  const first = judge();
+  if (first.error) return reportUnanswered(first, 'nothing was written');
+  if (first.accepted) return ok('index', 'already-current', `${INDEX_REL}: ${KEPT_FITS} — nothing written`);
+  const custom = [...hook, ...['check-docs-size.test.mjs', 'spec-schema.test.mjs'].map((name) => surveyHookModule(cwd, kitRoot, name, read, lstat))].filter((entry) => entry.state === 'custom').map((entry) => entry.rel).sort();
+  const route = custom.length > 0 ? `the replace line printed for the spec layer (${custom.join(', ')}), run on the user's yes` : "the spec layer's refresh of the modules the project's hook loads, then this step again";
+  const found = lstatNoFollow(join(cwd, INDEX_REL), lstat) === null ? null : read(join(cwd, INDEX_REL));
+  const restored = found === null ? 'the navigator was put back: found absent, it was removed again' : 'the navigator was put back byte for byte';
+  const restoreThen = (failure, compose) => {
+    const refused = putBackIndex(cwd, found, deps);
+    return refused === null ? compose() : loud('index', 'write-refused', `${INDEX_REL}: putting the navigator back failed (${refused})${failure ? ` after ${failure}` : ''} — a navigator ${KEPT_JUDGE} rejects may stand; re-read it before re-running`);
+  };
+  const run = drive('--ensure-index');
+  const refusal = String(run.stderr ?? '').match(ENSURE_INDEX_REFUSAL);
+  if (run.error || run.status !== 0 || !String(run.stdout ?? '').match(ENSURE_INDEX_OUTCOME)) {
+    const cause = run.error ? 'generator-unlaunchable' : run.status === 2 && refusal ? (refusal[1] === 'write-refused' ? 'write-refused' : 'index-probe-failed') : 'generator-failed';
+    const what = run.error ? `the bundled generator could not be started (${causeOf(run.error)})` : describeExitWithOutput(run, 'the bundled generator');
+    return restoreThen(what, () => loud('index', cause, `${INDEX_REL}: ${what} — ${restored}`));
+  }
+  let second;
+  try { second = judge(); } catch (err) { return restoreThen(`the navigator could not be read back (${causeOf(err)})`, () => loud('index', 'unexpected-error', `${INDEX_REL}: the navigator could not be read back after the bundled write (${causeOf(err)}) — ${restored}`)); }
+  if (second.error) return restoreThen(`${KEPT_JUDGE} could not answer (${second.error})`, () => reportUnanswered(second, restored));
+  if (second.accepted) return ok('index', 'regenerated', `${INDEX_REL}: written by the bundled generator — ${KEPT_FITS}`);
+  return restoreThen(null, () => ok('index', 'customized-preserved', `${INDEX_REL}: ${KEPT_JUDGE} rejected the bundled render on ${second.half} (${second.said}), and the navigator as found did not pass it either (${first.half}) — ${restored}. The route: ${route}`));
+};
+
+const buildKeptDryRunNote = (hook) =>
+  `a module the project's hook loads (${hook.filter((entry) => entry.state !== 'current').map((entry) => entry.rel).join(', ')}) is not the bundled one: unless the spec-layer step of this run first refreshes every such module, the real run judges the navigator by ${KEPT_JUDGE} and puts back a write it rejects`;
 
 export const ensureIndex = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
   const lstat = deps.lstat ?? lstatSync;
+  const read = deps.readFile ?? readFileSync;
   const spawn = deps.spawnSync ?? spawnSync;
   const generator = join(kitRoot, ...GENERATOR_PATH);
   const drive = (mode) => spawn(process.execPath, [generator, mode, `--root=${cwd}`], { encoding: 'utf8' });
@@ -330,14 +414,21 @@ export const ensureIndex = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
   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`);
   }
-
+  const hook = HOOK_MODULES.reduce((acc, name) => (acc[0]?.state === 'absent' || acc[0]?.wrongKind ? acc : [...acc, surveyHookModule(cwd, kitRoot, name, read, lstat)]), []);
+  const wrong = hook.find((entry) => entry.state === 'wrong-kind');
+  if (wrong) return loud('index', 'wrong-node-kind', `${wrong.rel}: exists but is ${wrong.wrongKind} — the project's hook loads it, so nothing was read or written; resolve it by hand and re-run`);
+  const kept = hook[0].state !== 'absent' && !hook.every((entry) => entry.state === 'current');
+  const unreadable = kept && hook.find((entry) => entry.state === 'bundle-unreadable');
+  if (unreadable) return loud('index', 'bundle-unreadable', `${unreadable.rel}: the bundled module could not be read, so nothing was written — reinstall the kit. ${unreadable.error}`);
+  if (kept && !dryRun) return ensureKeptIndex({ cwd, kitRoot, drive, spawn, read, lstat, deps, hook });
+  const dryNote = kept ? [buildKeptDryRunNote(hook)] : [];
   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}`);
+    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`, ...dryNote);
+    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`, ...dryNote);
+    return loud('index', 'index-probe-failed', `${INDEX_REL}: the freshness probe answered neither fresh nor stale (exited ${describeExit(check)}), so nothing was written. ${out}`, ...dryNote);
   }
 
   const run = drive('--ensure-index');

package/tools/ensure-specs.mjs

@@ -3,8 +3,8 @@
 // a FIXED order the measured coupling dictates:
 //   1. the reader pair   scripts/spec-schema.mjs + .test.mjs      — created when absent; since 2a
 //      also REFRESHED when the deployed bytes are a body a release shipped (script-priors.mjs), a
-//      custom body preserved verbatim (brief D1 shipped it create-only; the 4.6.x bodies joining the
-//      catalog is what keeps those deployments out of the stranded-custom cell);
+//      custom body preserved verbatim until the user's yes runs the printed replace line
+//      (--replace-custom <digest>, spec docs-navigator);
 //   2. the checker pair  scripts/check-docs-size.mjs + .test.mjs  — the same prior-refresh lane, and
 //      only behind a reader pair this run leaves byte-current;
 //   3. the store root    docs/ai/specs/index.md                   — seeded (placeholders rendered)
@@ -17,16 +17,18 @@
 // The state table (enumerate by PROOF, never by exclusion): every file is classified into exactly one
 // of current | prior | custom | absent | wrong-kind before anything is written, each write admits
 // through ONE conjunction of those facts (decideWrites), and every other cell is a stated refusal —
-// a custom file of either pair preserves itself AND withholds every write that depends on it. Writes
-// run in order and each is idempotent, so a run that stopped partway converges on the next run.
+// a custom file of either pair preserves itself AND withholds every write that depends on it, and the
+// ONE replace line names every custom file; on the yes, a replace run whose digest still matches
+// rewrites them. Writes run in order and each is idempotent, so a stopped run converges on the next.
 //
 // Dependency-free, Node >= 22. Every fs primitive is injectable (deps.*). No side effects on import.
 
 import { readFileSync, lstatSync } from 'node:fs';
 import { join } from 'node:path';
 import { writeContainedFileAtomic, writeProjectFileCreateOnly } from './atomic-write.mjs';
-import { classifyDeployedScript } from './script-priors.mjs';
+import { classifyDeployedScript, digestOf } from './script-priors.mjs';
 import { composeFailure, composeOutcome, nodeEvidenceRefusal, probeSeedTarget, tmpNote } from './ensure-ops.mjs';
+import { shellQuoteArg } from './repo-lex.mjs';
 
 const OP = 'specs';
 const SCRIPTS_DIR = 'scripts';
@@ -59,9 +61,14 @@ const surveyScript = ({ cwd, kitRoot, name, read, lstat }) => {
   const probe = probeSeedTarget(join(cwd, SCRIPTS_DIR, name), lstat);
   if (probe.wrongKind) return { rel, name, state: 'wrong-kind', wrongKind: probe.wrongKind, bundle };
   if (!probe.present) return { rel, name, state: 'absent', bundle };
-  return { rel, name, state: classifyDeployedScript(read(join(cwd, SCRIPTS_DIR, name)), name, bundle), bundle };
+  const bytes = read(join(cwd, SCRIPTS_DIR, name));
+  return { rel, name, state: classifyDeployedScript(bytes, name, bundle), bundle, bytes };
 };
 
+// The custom set's digest binds the set AND the bytes: the rel-sorted `<rel> <sha256>` lines, LF-joined.
+export const customSetDigest = (files) =>
+  digestOf([...files].sort((a, b) => (a.rel < b.rel ? -1 : 1)).map((f) => `${f.rel} ${digestOf(f.bytes)}`).join('\n'));
+
 const surveyStoreRoot = (cwd, lstat) => {
   const probe = probeSeedTarget(join(cwd, STORE_ROOT_REL), lstat);
   if (probe.wrongKind) return { rel: STORE_ROOT_REL, state: 'wrong-kind', wrongKind: probe.wrongKind };
@@ -73,21 +80,25 @@ const surveyStoreRoot = (cwd, lstat) => {
 // Reader seeds are create-only and always admitted. A REFRESH overwrites bytes, so it runs only
 // inside a pair whose every file is proven refreshable (current | prior | absent) — one custom file
 // withholds its whole pair; the checker lane (its seeds included) and the store additionally wait
-// for a reader pair this run leaves byte-current (seeded + refreshed = current).
+// for a reader pair this run leaves byte-current (seeded + refreshed = current). Under the user's
+// replace yes a custom file is refreshable too: it is rewritten to the bundled body.
 const PAIR_ELIGIBLE = new Set(['current', 'prior', 'absent']);
+const REPLACE_ELIGIBLE = new Set([...PAIR_ELIGIBLE, 'custom']);
 
-export const decideWrites = ({ reader, checker, store }) => {
-  const readerEligible = reader.every((f) => PAIR_ELIGIBLE.has(f.state));
-  const checkerEligible = readerEligible && checker.every((f) => PAIR_ELIGIBLE.has(f.state));
+export const decideWrites = ({ reader, checker, store }, replace = false) => {
+  const eligible = replace ? REPLACE_ELIGIBLE : PAIR_ELIGIBLE;
+  const refreshable = replace ? ['prior', 'custom'] : ['prior'];
+  const readerEligible = reader.every((f) => eligible.has(f.state));
+  const checkerEligible = readerEligible && checker.every((f) => eligible.has(f.state));
   const writes = [];
   for (const f of reader) {
     if (f.state === 'absent') writes.push({ kind: 'seed', file: f });
-    if (readerEligible && f.state === 'prior') writes.push({ kind: 'refresh', file: f });
+    if (readerEligible && refreshable.includes(f.state)) writes.push({ kind: 'refresh', file: f });
   }
   if (checkerEligible) {
     for (const f of checker) {
       if (f.state === 'absent') writes.push({ kind: 'seed', file: f });
-      if (f.state === 'prior') writes.push({ kind: 'refresh', file: f });
+      if (refreshable.includes(f.state)) writes.push({ kind: 'refresh', file: f });
     }
   }
   if (checkerEligible && store.state === 'absent') writes.push({ kind: 'store' });
@@ -103,7 +114,10 @@ export const decideWrites = ({ reader, checker, store }) => {
 const LEFT_FOR = { withheld: 'it waits on the pair named above', stopped: 'the run stopped before it' };
 const SCRIPT_LINES = {
   current: () => 'already the bundled body — nothing written',
-  custom: () => "carries a body this kit did not ship as current — preserved verbatim; the writes that depend on it wait until the pair matches the bundled scripts (copy them by hand from the kit's references/scripts/ when convenient, then re-run the upgrade)",
+  custom: (fate) => ({
+    written: "carried an edited body — replaced by the bundled one on the user's yes",
+    stopped: 'carries an edited body — not replaced; the run stopped before it',
+  })[fate] ?? "carries a body this kit did not ship as current — preserved verbatim; the writes that depend on it wait until it is replaced on the user's yes (the replace line below)",
   absent: (fate) => ({
     written: 'copied from the bundled scripts',
     stood: 'appeared while this run was seeding it — the bundled body stands',
@@ -120,10 +134,13 @@ const STORE_LINES = {
   written: "created from the bundled template (today's date rendered)",
   stood: 'appeared while this run was seeding it — the existing file stands',
   would: 'absent — would be created from the bundled template',
-  withheld: "not seeded — an older or edited checker renders the spec store row by row and reds the hook's index check, so the store root waits for a current checker pair",
+  withheld: (custom) => `not seeded — it waits on the edited ${custom.join(', ')} (a body this kit did not ship): an older or edited checker renders the spec store row by row and reds the hook's index check, so the store root waits for a current checker pair`,
   stopped: 'absent — not created; the run stopped before it',
 };
-const storeLine = (store, fate) => `${STORE_ROOT_REL}: ${STORE_LINES[store.state === 'present' ? 'present' : fate]}`;
+const storeLine = (store, fate, custom) => {
+  const line = STORE_LINES[store.state === 'present' ? 'present' : fate];
+  return `${STORE_ROOT_REL}: ${typeof line === 'function' ? line(custom) : line}`;
+};
 const relOf = (write) => (write.kind === 'store' ? STORE_ROOT_REL : write.file.rel);
 
 // The fate of every path for the lines: a write that ran carries its result, an admitted write the
@@ -138,10 +155,17 @@ const composeLines = ({ reader, checker, store, writes, fates, withheld, stopped
   const fate = (rel) => fateOf(rel, { writes, fates, withheld, stopped });
   const lines = [...reader, ...checker].map((f) => scriptLine(f, fate(f.rel)));
   const storeFate = fate(STORE_ROOT_REL);
-  if (store.state === 'present' || storeFate !== 'none') lines.push(storeLine(store, storeFate));
+  const custom = [...reader, ...checker].filter((f) => f.state === 'custom').map((f) => f.rel);
+  if (store.state === 'present' || storeFate !== 'none') lines.push(storeLine(store, storeFate, custom));
   return lines;
 };
 
+// The ONE replace line: the exact command, its condition first, both paths shell-quoted.
+const replaceLineFor = (custom, kitRoot, cwd) => (custom.length === 0 ? [] : [
+  `to replace the edited files named above, run this only on the user's yes — the bundled bodies overwrite their edits: node ${shellQuoteArg(join(kitRoot, 'tools', 'ensure-configs.mjs'))} --reconcile --replace-custom ${customSetDigest(custom)} --cwd ${shellQuoteArg(cwd)}`,
+]);
+const RACE_LINE = 'the edited files changed since the replace line was printed (another set or other bytes), so nothing was written — ask the user again with the fresh replace line below';
+
 // A per-file loop can stop partway; the run says which files already landed — never "nothing happened".
 const partialNote = (count) =>
   (count > 0 ? [`the writes stopped PARTWAY — the ${count} file(s) named above were already written and are NOT rolled back`] : []);
@@ -156,7 +180,7 @@ const renderStoreRoot = (kitRoot, read, today) => {
   return body;
 };
 
-export const ensureSpecs = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
+export const ensureSpecs = ({ cwd, kitRoot, dryRun = false, deps = {}, replaceCustom }) => {
   const lstat = deps.lstat ?? lstatSync;
   const read = deps.readFile ?? readFileSync;
   const refusal = nodeEvidenceRefusal(OP, cwd, lstat);
@@ -172,7 +196,15 @@ export const ensureSpecs = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
     if (f.state === 'wrong-kind') return loud('wrong-node-kind', `${f.rel}: exists but is ${f.wrongKind} — nothing was read or written; resolve it by hand, then re-run`);
   }
 
-  const { writes, withheld } = decideWrites({ reader, checker, store });
+  const custom = [...reader, ...checker].filter((f) => f.state === 'custom');
+  const replace = replaceCustom !== undefined && custom.length > 0;
+  const replaceLine = replaceLineFor(custom, kitRoot, cwd);
+  if (replace && replaceCustom !== customSetDigest(custom)) {
+    const asFound = decideWrites({ reader, checker, store });
+    return loud('race-unresolved', RACE_LINE, ...composeLines({ reader, checker, store, ...asFound, fates: new Map(), stopped: true }), ...replaceLine);
+  }
+  const { writes, withheld } = decideWrites({ reader, checker, store }, replace);
+  const tail = replace ? [] : replaceLine;
   const kinds = new Set(writes.map((w) => w.kind));
   // ONE token by precedence — a write that happened (or, dry, would happen) always outranks the
   // preserved-custom report, which names a run that wrote nothing behind an edited pair.
@@ -184,14 +216,14 @@ export const ensureSpecs = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
   const fates = new Map();
   const linesNow = (stopped) => composeLines({ reader, checker, store, writes, fates, withheld, stopped });
   const writtenCount = () => [...fates.values()].filter((fate) => fate === 'written').length;
-  if (dryRun) return ok(tokenFor(kinds.has('seed') || kinds.has('store'), kinds.has('refresh')), linesNow(false));
+  if (dryRun) return ok(tokenFor(kinds.has('seed') || kinds.has('store'), kinds.has('refresh')), [...linesNow(false), ...tail]);
 
   let storeBody = null;
   if (kinds.has('store')) {
     try {
       storeBody = renderStoreRoot(kitRoot, read, deps.today ?? todayIso());
     } catch (err) {
-      return loud('template-unreadable', `${STORE_ROOT_REL}: ${causeOf(err)}`, ...linesNow(true));
+      return loud('template-unreadable', `${STORE_ROOT_REL}: ${causeOf(err)}`, ...linesNow(true), ...tail);
     }
   }
   const writeOne = ({ kind, file }) => {
@@ -209,14 +241,14 @@ export const ensureSpecs = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
     try {
       result = writeOne(write);
     } catch (err) {
-      return loud('write-refused', `${rel}: ${causeOf(err)}`, ...linesNow(true), ...notes, ...partialNote(writtenCount()));
+      return loud('write-refused', `${rel}: ${causeOf(err)}`, ...linesNow(true), ...notes, ...partialNote(writtenCount()), ...tail);
     }
     if (write.kind !== 'refresh' && !result.created && !stoodCurrent(write)) {
-      return loud('race-unresolved', `${rel}: appeared while this run was seeding it and does not carry the bundled body — something is writing there underneath this run; nothing further written, re-run when the tree is settled`, ...linesNow(true), ...notes, ...partialNote(writtenCount()));
+      return loud('race-unresolved', `${rel}: appeared while this run was seeding it and does not carry the bundled body — something is writing there underneath this run; nothing further written, re-run when the tree is settled`, ...linesNow(true), ...notes, ...partialNote(writtenCount()), ...tail);
     }
     fates.set(rel, write.kind !== 'refresh' && !result.created ? 'stood' : 'written');
     notes.push(...tmpNote(rel, result.tmpLeftBehind));
   }
   const landed = (kind) => writes.some((w) => w.kind === kind && fates.get(relOf(w)) === 'written');
-  return ok(tokenFor(landed('seed') || landed('store'), landed('refresh')), [...linesNow(false), ...notes]);
+  return ok(tokenFor(landed('seed') || landed('store'), landed('refresh')), [...linesNow(false), ...notes, ...tail]);
 };

package/tools/ensure-vocabulary.mjs

@@ -16,7 +16,8 @@ export const ENSURE_OPS = Object.freeze(['orchestration', 'gates', 'autonomy', '
 // 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. `refreshed` is the spec-layer
 // ensure's pair refresh (reader or checker) — a deployed script on a body a release shipped,
-// rewritten to the bundled one (a custom body is never refreshed).
+// rewritten to the bundled one; a custom body is rewritten only by the replace run the user's yes
+// starts (--replace-custom), never by a plain run.
 // `re-derived` is the executor ensure rewriting a placed executor whose bytes differ from the body derived from docs/ai/vehicles.json.
 export const WRITE_TOKENS = Object.freeze(['seeded', 'note-refreshed', 'refreshed', 'regenerated', 're-derived']);
 export const DRY_RUN_TOKENS = Object.freeze(['would-seed', 'would-refresh-note', 'would-refresh', 'would-regenerate', 'would-re-derive']);

package/tools/script-priors.mjs

@@ -1,8 +1,8 @@
 // script-priors.mjs — the APPEND-ONLY catalog of every enforcement-script body this family has shipped
 // into a project's `scripts/`, as sha256 digests, and the ONE classifier the spec-layer ensure asks
 // before it refreshes a deployed script: `current` (byte-equal to the bundled copy) · `prior` (a body
-// a release shipped, never edited since) · `custom` (anything else — preserved verbatim, never
-// overwritten). The lens-region idiom (AD-041) over whole script bodies.
+// a release shipped, never edited since) · `custom` (anything else — preserved verbatim, replaced only by
+// the replace run the user's yes starts). The lens-region idiom (AD-041) over whole script bodies.
 //
 // Append discipline: when a release changes one of PRIOR_FILES, append the OUTGOING body's row here
 // in the same release and copy its bytes to test/fixtures/script-priors/<firstShipped>/<file>.txt —
@@ -36,6 +36,7 @@ export const SCRIPT_PRIORS = Object.freeze([
   prior('check-docs-size.mjs', '4.6.0', '6.0.0', '22d020c3668cdbfb4cbc1f67a8a85b2baa2d0c4956808a50626d37409e81ab38'),
   prior('spec-schema.mjs', '5.0.0', '7.2.1', '6a7d1e836c158baab5a412a1ad76d34891934dc28c88486c264a4b5d46f5892a'),
   prior('spec-schema.test.mjs', '5.0.0', '7.2.1', '698564d7283281be1826019d214df475bb876687915de086818d8f5ece0e0336'),
+  prior('check-docs-size.mjs', '7.0.0', '8.1.5', '0cf90ae2cbfc809847574a8c71a6b1322c783359740b08e0ff179f0d9d04dffc'),
 ]);
 
 export const digestOf = (bytes) => createHash('sha256').update(bytes).digest('hex');

package/tools/upgrade-runlist.mjs

@@ -34,7 +34,7 @@ export const UPGRADE_RUNLIST = Object.freeze([
   entry(
     'configs',
     'node ${CLAUDE_SKILL_DIR}/tools/ensure-configs.mjs --reconcile --cwd <project>',
-    null,
+    'a specs replace line → ONE yes naming every file the custom lines name and saying their edits are overwritten, asked even on a non-zero exit; on the yes run the printed line, then STOP if that run fails or an op it does not re-run failed; on a no STOP on any failed op. The printed line: node ${CLAUDE_SKILL_DIR}/tools/ensure-configs.mjs --reconcile --replace-custom <digest> --cwd <project>',
     [
       'seeded',
       'note-refreshed',