@sabaiway/agent-workflow-kit 4.4.0 → 4.5.0

package/CHANGELOG.md

@@ -4,6 +4,37 @@ 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.
 
+## 4.5.0 — the ADR-store migration finds the projects that could never hear about it (AD-083)
+
+**If your project still keeps its decisions in one big archive file, this release is the first thing
+that will actually tell you so.** A whole class of projects was invisible to the old check.
+
+**1. The old-layout check stopped guessing from filenames.** It used to say «old layout» only when a
+retired `docs/ai/history/decisions-archive*.md` file was on disk. A project that never grew one — its
+decisions file simply never got big enough to roll over — was reported as having nothing to do, and
+running the migration greeted it with *«a fresh new-scheme tree»*. Its own pre-commit check agreed:
+«OK — every tier is within its cap», forever, describing a retired layout as healthy. The check now
+looks at the rotation script your project actually deploys: the current one knows about the
+`docs/ai/adr/` store, the older one does not. That is a fact about your tree, not a guess — and it
+deliberately stays quiet for two groups it would otherwise nag wrongly: projects whose current script
+already reds their own commit with an actionable fix, and projects that run no Node at all.
+
+**2. `migrate-adr-store` now finishes the job on those projects, and can always be re-run.** On a
+project with no archive file to explode it snapshots, refreshes the enforcement scripts and seeds the
+store (`docs/ai/adr/` + the navigator + a regenerated `docs/ai/index.md`). Interrupt it anywhere and
+run it again: a store folder alone is no longer mistaken for «done» (the navigator has to exist and
+your own check has to pass), the script refresh is re-planned in full each run, and a failed index
+regeneration now fails the run loudly instead of reporting success. The preview earns its go-ahead —
+it runs exactly the checks the real run does and writes nothing.
+
+**3. `upgrade` stops saying «flow optimal» to a project on the old layout.** The recommendations
+section now carries the migration as an item. It is HAND-APPLY on purpose: the one-liner it hands you
+is the **preview**, and the real migration is a separate step you run only after seeing the plan and
+agreeing to it — this crossing overwrites and deletes files your project already has, which is why it
+never rides the ordinary one-click apply. Honest limit, stated plainly:
+this reaches you through `status` and `upgrade`, so it mechanizes a door you already walk through — it
+is not a new one for someone who never runs either.
+
 ## 4.4.0 — the guard stops charging you for answers it already has (AD-082)
 
 **If the agent keeps asking you to approve its own `2>/dev/null`, this release is for you.** Two

package/SKILL.md

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

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "4.4.0",
+  "version": "4.5.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/migrate-adr-store.md

@@ -1,10 +1,12 @@
 ### Mode: migrate-adr-store
 
-<!-- opt-in-capability: none — the old-layout condition is already reported by status and upgrade; the advisor does not duplicate a report the same run prints -->
+<!-- opt-in-capability: adr-store-migration -->
 
 The **guarded ADR-store migration** — a one-time, opt-in move of an existing project's `docs/ai` from the retired 3-tier ADR cascade (HOT `decisions.md` → the WARM/COLD `decisions-archive*.md` monoliths) to the durable **one-file-per-ADR store** (HOT `decisions.md` + `docs/ai/adr/AD-NNN-slug.md` records + the `docs/ai/adr/log.md` navigator). **In-agent, opt-in**, and reached ONLY here: a normal `upgrade` never installs the new-scheme rotator into an un-migrated project — the new rotator arrives ONLY through this mode, which migrates in the same step (AD-051). Run **`--dry-run` first, always**, show the user the plan in plain language, get explicit consent, then re-run with `--apply`. It **never commits**.
 
-When to run it: `status` (or `upgrade`) reports an *old ADR layout* (a `decisions-archive*.md` monolith is still on disk). A project already on the one-file-per-ADR store — or a fresh deployment seeded with it — needs nothing here (the mode is a stated no-op).
+When to run it: `status` (or `upgrade`) reports an *old ADR layout*. That covers **two** shapes, and the remedy is the same for both — (1) a `decisions-archive*.md` monolith is still on disk, and (2) **no monolith was ever produced**: the project's deployed `scripts/archive-decisions.mjs` simply predates the store, so its own gate reports the retired three-tier world as healthy and would never mention the store. The second shape is detected by that deployed script's own provenance — never by "has `decisions.md`, lacks `adr/`", which would falsely accuse a project whose NEW rotator already reds its gate with an actionable fix, and every project that runs no Node. A project already on the one-file-per-ADR store with a fresh navigator — or a fresh deployment seeded with it — needs nothing here (the mode is a stated no-op).
+
+On the no-monolith shape `--apply` does the same work minus the explosion: snapshot → refresh the deployed enforcement scripts → **seed** the store (`docs/ai/adr/` + the navigator + a regenerated `docs/ai/index.md`) → verify. It is **re-runnable to completion from any interruption**: a store directory alone never counts as finished (the navigator must exist and the project's own `--check` must pass), the whole script refresh is re-planned on every run with the rotation script written last, and a failed index regeneration fails the run **closed** rather than reporting success.
 
 Run `node ${CLAUDE_SKILL_DIR}/tools/migrate-adr-store.mjs [--dry-run | --apply] [--cwd <project>]`:
 

package/references/modes/recommendations.md

@@ -27,6 +27,8 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd <project-root> [--
 - `read-lane` — enabling the opt-in read-only compound lane auto-approves *compounds* (and singles) of the seeded read-only core that carry ZERO shell metaprogramming: an UNATTENDED trust extension, bounded by the audited read-only core (never a command outside it; prompt-bypass only, never a sandbox bypass) and applied regardless of which of those core commands you seeded as individual settings rules. It is a PROJECT-PERSISTENT declaration in `docs/ai/lanes.json` — every future session, subagents' Bash too where the host fires hooks on subagent Bash, and (committed) every checkout. The apply depends on state: when the lane is OFF, it is the `gate-hook --read-lane` preview (whose own currency check refuses a stale hook — a pre-1.48 hook never reads `lanes.json`); when the placed hook is STALE (an enabled lane over an old hook) or MISSING, the item instead surfaces a **delete-to-reseed** / re-place recovery (a destructive `rm` + `--apply`, an attention item — never the safe preview). Risk profile: a bounded read-only trust-posture extension — no write/exec exposure beyond the audited core.
 - `worktrees-dir` — on a settings-native host that honors the key, the HAND-APPLY line widens the OS-sandbox WRITE surface to the whole worktrees parent dir: every sibling path under it (other repositories included) becomes agent-writable, and the widening persists for every later session. A harness-managed host may ignore that project setting; grant the narrow parent through host/session controls or use the provision terminal fallback instead. When that scope is wider than you want, narrow it FIRST: create a dedicated dir yourself (outside the agent's write surface), point `docs/ai/worktrees.json` `parentDir` at it, then re-run recommendations — the item re-renders with the narrowed dir. The kit never writes sandbox filesystem allowances itself; the line is always yours to paste. **Convergence** is two-path: a declared `sandbox.filesystem.allowWrite` entry covering the probed dir (either settings scope — `~` and `~/…` resolve against home, and coverage is path-segment-aware, so a grant on a sibling or on a child never counts), or — for a host that ignores that key — the neutral dir-bound acknowledgement recorded by this item's consent-gated apply one-liner (`ack-write --lane worktrees-dir` — a dry-run preview that prints the exact `--apply`; recorded as `worktreesDirAck` in the family-owned `docs/ai/acks.json`, never a security key), while the grant advice itself rides the `recipe:` line as the labeled FIRST step; against a trusted host NO the apply stays the HAND-APPLY grant advice and no ack is offered. Neither is proof of write CAPABILITY: the provision preflight's real create+delete probe stays the runtime truth, and the fingerprint is bound to the **resolved probe dir**, so the item re-fires only when that resolved dir changes (two absent `parentDir` values sharing an existing ancestor resolve to the same dir and keep the same ack). Risk profile: a real write-surface widening where honored — scope it deliberately.
 
+- `adr-store-migration` — other items write project files too; what is unique here is that the crossing **overwrites and deletes files the project already has**: it replaces the deployed enforcement scripts in `scripts/` (the directional subset — only basenames the project already has; a locally-edited copy is snapshotted first, never silently clobbered) and, where a retired archive file exists, DELETES it once conservation has been proven. That is why it is **HAND-APPLY** and why the command shown in the apply slot is a **`--dry-run`** — it writes nothing and prints the whole plan. `--apply` is a SEPARATE step, run only after that plan has been shown and **fresh consent** obtained for it; the consent flow executes only the apply slot, so an item that needs consent AFTER its preview cannot use that lane at all. Every write is idempotent and the run is re-runnable to completion after any interruption, so a re-run repairs rather than double-applies. It never commits. Risk profile: overwrite + delete of existing project files, gated on a preview you have actually read.
+
 **Sandbox lanes (what to DO with the `sandbox-lane` recipe, per host class):**
 
 - **Settings-native sandbox** (the harness reads the `.claude/settings.json` sandbox keys): nothing beyond the `--bridge-tier` wiring — the tier's `excludedCommands` already routes the wrappers OUTSIDE the sandbox, so they never consult `allowedDomains`/`allowWrite`. Record the ack (the ack-write one-liner) once the tier is confirmed.

package/references/modes/status.md

@@ -11,7 +11,7 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/family-registry.mjs --json [--dir <project>]
 1. **Versions — a status-only render from `installed[]` + `deploymentHead`** (this is **NOT** the shared notes-based version block — see the separation note below): the **`docs/ai` structure version** (named as such, never "lineage head"), then each member by its `display` showing its `version` (or, when there is no version, the plain phrase for its `state`, mapped above), plus the two-axes disambiguation. **Freshness comes from `installed[].refresh`, not from `notes`:** for each member whose **`refresh.behind`** is `true`, show a **localized "needs refresh"** label and the **verbatim `refresh.recommend`** command **exactly once** (the command/package name stays source-language; **do not also paste the English `notes` caveats** — `refresh.recommend` is the single source of the recovery step, so the command is never duplicated on this surface). A member whose **`refresh.freshness`** is **`unknown`** is surfaced too — a localized *"couldn't be checked"* label; it is **never counted as current and never as behind** (its `notes` caveat carries the detail on the notes-based surfaces; here the label is enough). Lead with a one-line **headline count** derived from `installed[].state` + `refresh.behind` + `refresh.freshness` (e.g. *"5 members installed · 1 needs a refresh · 1 couldn't be checked"* — omit a zero count).
 
 > **Status reads `refresh`; the shared version block + the bootstrap/upgrade footers stay `notes`-based (unchanged this release).** `${CLAUDE_SKILL_DIR}/references/modes/status.md` has its OWN status-only render (above), keyed on `installed[].refresh.behind` / `refresh.recommend`. The shared **version block** (under *The version block + welcome mat* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`) and the bootstrap (step 11) + every upgrade (steps 4 / 8) report footer still consume `installed[].notes` verbatim — that wiring is deliberately **untouched** here (their migration onto `refresh` is deferred). Do not rewrite those footers onto `refresh`.
-2. **Deployment (`--dir`)** (from `project`): whether `docs/ai/` is deployed + the deploy stamps by `display`; and **visibility** — render `project.visibility.state` in **user-safe words only**: *visible (tracked)* / *hidden (git-ignored, local-only)* / *unclear (uncommitted or partially set up)* — **never** the words "hidden fence" or any marker term. A `visibility.error` → surface it plainly. When `project.adrLayout` is **`old`**, add a plain-language note that the project still uses an **older ADR layout** and should run the opt-in **`/agent-workflow-kit migrate-adr-store`** to move to the one-file-per-ADR store (preview first; it never commits); `migrated` / `none` need no note.
+2. **Deployment (`--dir`)** (from `project`): whether `docs/ai/` is deployed + the deploy stamps by `display`; and **visibility** — render `project.visibility.state` in **user-safe words only**: *visible (tracked)* / *hidden (git-ignored, local-only)* / *unclear (uncommitted or partially set up)* — **never** the words "hidden fence" or any marker term. A `visibility.error` → surface it plainly. When `project.adrLayout` is **`old`** or **`old-unrotated`**, add a plain-language note that the project still uses an **older ADR layout** and should run the opt-in **`/agent-workflow-kit migrate-adr-store`** to move to the one-file-per-ADR store (preview first; it never commits) — the note is the SAME for both, they differ only in how the older layout was detected (`old` = a retired archive file is still on disk; `old-unrotated` = the project's deployed rotation script predates the store); `migrated` / `none` need no note.
 3. **Settings (`--dir`, one line each)** (from `project.settings`):
    - **recipes** — the effective recipe per slot (detail → `/agent-workflow-kit procedures` / `recipes`); a `recipes.detectError` → say the backends couldn't be checked, so recipes floored at solo.
    - **attribution** — `includeCoAuthoredBy` effective; call out a **local override** only when `local` is non-null **and** differs from `project` (a `null` `local` means the key is absent there, so the project value stands — that is not an override).

package/references/modes/upgrade.md

@@ -28,7 +28,7 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
 
    **Autonomy-declaration ensure (seed-if-missing) — stamp-independent, same gate, BEFORE the equal-head short-circuit.** Ensure `docs/ai/autonomy.json` exists: **create it from `${CLAUDE_SKILL_DIR}/references/templates/autonomy.json` if missing** (the kit's OWN template twin, mirrored from memory — so a stale memory never silently loses the seed); **an existing file is preserved byte-for-byte** (a declared policy is authored content — never clobbered, never refreshed in place). The seed is SPARSE (the onboarding note only) and **defaults-equivalent** — deploying it never changes behavior (the computed defaults stay the policy until the user declares levels with `/agent-workflow-kit set-autonomy` or by hand). Report it in the step 4 / step 8 success report (*seeded* / *already present, preserved*). Like the other config ensures, no lineage-head bump or migration file (a `.json`, outside the docs cap-validator).
 
-   **Enforcement-script ensure (seed-if-missing) — stamp-independent, same gate, BEFORE the equal-head short-circuit.** A deployment older than the ADR-cascade feature has no `scripts/archive-decisions.mjs`, and an equal-head exit would otherwise never deliver it. Ensure the pair exists in the project's `scripts/`: **copy `archive-decisions.mjs` + `archive-decisions.test.mjs` from `${CLAUDE_SKILL_DIR}/references/scripts/` if missing** (the kit's own fallback copies — byte-identical to the memory canon by the mirror guard); **an existing file is preserved, never overwritten** (drift repair belongs to a lineage migration, not this ensure). **OLD ADR-store layout — DETECT FIRST, never auto-migrate (AD-051, Decision 13):** if the project still carries a `docs/ai/history/decisions-archive*.md` monolith (the `adrLayout: "old"` signal `status` surfaces), it is on the RETIRED 3-tier cascade — **do NOT seed or refresh the now one-file-per-ADR rotator here** (the new `archive-decisions.mjs` beside un-migrated monoliths would red their ADR gate). Instead surface a LOUD instruct: run the opt-in **`/agent-workflow-kit migrate-adr-store`** (it snapshots, refreshes the scripts, and migrates in one consent-gated step; previews first, never commits). The seed-if-missing above applies ONLY to a clean layout (no monolith). 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. Skip this ensure on a No-Node project (the scripts are Node enforcement). Report it in the step 4 / step 8 success report (*added* / *already present* / *old ADR layout — migration instructed*).
+   **Enforcement-script ensure (seed-if-missing) — stamp-independent, same gate, BEFORE the equal-head short-circuit.** A deployment older than the ADR-cascade feature has no `scripts/archive-decisions.mjs`, and an equal-head exit would otherwise never deliver it. Ensure the pair exists in the project's `scripts/`: **copy `archive-decisions.mjs` + `archive-decisions.test.mjs` from `${CLAUDE_SKILL_DIR}/references/scripts/` if missing** (the kit's own fallback copies — byte-identical to the memory canon by the mirror guard); **an existing file is preserved, never overwritten** (drift repair belongs to a lineage migration, not this ensure). **OLD ADR-store layout — DETECT FIRST, never auto-migrate (AD-051, Decision 13):** if `status` surfaces `adrLayout: "old"` (a `docs/ai/history/decisions-archive*.md` monolith) or `"old-unrotated"` (no monolith, but the deployed rotator predates the store), it is on the RETIRED 3-tier cascade — **do NOT seed or refresh the now one-file-per-ADR rotator here** (the new `archive-decisions.mjs` beside un-migrated monoliths would red their ADR gate). Instead surface a LOUD instruct: run the opt-in **`/agent-workflow-kit migrate-adr-store`** (consent-gated; previews first, never commits). The seed-if-missing above applies ONLY to a clean layout (neither signal). 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. Skip this ensure on a No-Node project (the scripts are Node enforcement). Report it in the step 4 / step 8 success report (*added* / *already present* / *old ADR layout — migration instructed*).
 
    **Placed-bridge refresh — stamp-independent, same gate, BEFORE the equal-head short-circuit.** Run
    `node ${CLAUDE_SKILL_DIR}/tools/setup-backends.mjs --refresh-placed` and **paste its per-bridge
@@ -63,7 +63,7 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
    **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.
 4. **Equal-head exit — a real successful-exit report, not a bare stop.** If the stamp **equals** the head, the lineage is up to date — but step 3 (the stamp-independent reconciles) ran first and may have changed things, so this is a proper exit report, not a no-op:
-   - **Report step 3's outcome in plain language** — for **each** pointer (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); whether the `docs/ai/orchestration.json` config was *seeded* (created from the template), had its onboarding note *refreshed*, was *already current*, or carried a *customized note that was preserved* (a user edit is never clobbered); whether the `docs/ai/gates.json` gate declaration was *seeded* or was *already present* (preserved byte-for-byte); whether the `docs/ai/autonomy.json` declaration was *seeded* (the sparse defaults-equivalent note) or was *already present* (preserved byte-for-byte); whether the enforcement-script ensure *added* the `archive-decisions` pair to `scripts/`, found it *already present*, or found an *old ADR layout — migration instructed*; the **placed-bridge refresh** outcome — paste the tool's per-bridge lines verbatim (they are already plain: *refreshed* / *already current* / *skipped — not placed* / `skipped-readonly` / *could not refresh* + recovery); the **agent-rules lens** outcome (*refreshed* / *already current* / *custom edit preserved + note* / *file absent* / *engine too old* / *over the line cap*) and the **Communication-section** outcome (its own set: refreshed / already current / custom preserved + note / section absent — noted / over the cap — refused); the **bridge-settings reconcile** outcome (paste the tool's line verbatim); and, for a hidden deployment, whether the hidden-mode footprint was *moved to project-local*, was *already project-local* (nothing changed), or needed a question (ambiguous visibility / a leftover machine-wide block). Plain wording only — never the reconcile/slot/anchor/marker terms (the never-leak-kit-internals Gotcha — `${CLAUDE_SKILL_DIR}/references/shared/deploy-tail.md`).
+   - **Report step 3's outcome in plain language** — for **each** pointer (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); whether the `docs/ai/orchestration.json` config was *seeded* (created from the template), had its onboarding note *refreshed*, was *already current*, or carried a *customized note that was preserved* (a user edit is never clobbered); whether the `docs/ai/gates.json` gate declaration was *seeded* or was *already present* (preserved byte-for-byte); whether the `docs/ai/autonomy.json` declaration was *seeded* (the sparse defaults-equivalent note) or was *already present* (preserved byte-for-byte); whether the enforcement-script ensure *added* the `archive-decisions` pair to `scripts/`, found it *already present*, or found an *old ADR layout — migration instructed* (either shape); the **placed-bridge refresh** outcome — paste the tool's per-bridge lines verbatim (they are already plain: *refreshed* / *already current* / *skipped — not placed* / `skipped-readonly` / *could not refresh* + recovery); the **agent-rules lens** outcome (*refreshed* / *already current* / *custom edit preserved + note* / *file absent* / *engine too old* / *over the line cap*) and the **Communication-section** outcome (its own set: refreshed / already current / custom preserved + note / section absent — noted / over the cap — refused); the **bridge-settings reconcile** outcome (paste the tool's line verbatim); and, for a hidden deployment, whether the hidden-mode footprint was *moved to project-local*, was *already project-local* (nothing changed), or needed a question (ambiguous visibility / a leftover machine-wide block). Plain wording only — never the reconcile/slot/anchor/marker terms (the never-leak-kit-internals Gotcha — `${CLAUDE_SKILL_DIR}/references/shared/deploy-tail.md`).
    - **Never surface the structure number on this exit.** Whatever step 3 did, do **not** recite the `docs/ai` structure version, the internal versioning vocabulary, or the two-axes note here — the number is inert on an equal-head exit; it belongs to *Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md` (shown at the never-downgrade STOP, the explicit status view, or on an explicit ask). Frame the success itself per the final bullet: if step 3 changed anything, say **what changed** in plain human terms; only a pure zero-diff no-op is *settings already current — no update needed*.
    - **Render the mandatory Recommendations section — on this exit too, BEFORE the footer.** Run `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd <project-root>` and PRESENT its output — from the `## Recommendations (agent-workflow)` header — in the user's conversational language: every fact, count and item from the tool, nothing added or dropped; commands, paths, hosts and rule strings byte-exact; show the raw tool block on request. The section is present-even-when-empty (with everything optimal the body is exactly `no recommendations — flow optimal.`) and VERDICT-FIRST — the composed verdict line renders from the frozen templates `{K} item(s) need attention` / `nothing is broken` / `{N} optional recommendation(s), apply any you want` / `optimality NOT attested — {M} probe check(s) skipped`. Then OFFER the consent-gated applies: the user picks items in plain language; surface each picked item's posture note, get the explicit confirm, then run EXACTLY the rendered one-liners (a HAND-APPLY item is never run by you) — the full lane in `${CLAUDE_SKILL_DIR}/references/modes/recommendations.md`. Pinned order on this exit: Recommendations block → optional applies → report footer → the commit ask (the advisor/apply lane never lands after the commit ask).
    - **Live host/session facts are tool-composed only.** Any claim this report makes about the current host or session state — prompts fired, sandbox scope, whether a bypass was needed, network reachability, approval counts — must trace to **live tool output** from **this session** (the lines you just composed, or a probe you ran this run); a memory/handover snapshot is **context, never report facts**, and a claim with no live signal is **omitted or explicitly marked unverified** — never asserted from recollection. Full clause: *Live host/session facts* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`.

package/references/scripts/archive-decisions.mjs

@@ -29,7 +29,10 @@
 //                      HOT preamble, and only THEN removes the monoliths — gated on conservation AND
 //                      the snapshot. Re-run skips byte-identical records (crash-resumable).
 //   --write-navigator  regenerate docs/ai/adr/log.md AND re-trigger the index regen (the authoring /
-//                      supersession write-side; the --write-index analog).
+//                      supersession write-side; the --write-index analog). With --dry-run it runs
+//                      EXACTLY the same validation (parse, half-migrated guard, store integrity) and
+//                      stops before every write — the read-only preflight a guarded caller needs to
+//                      earn a go-ahead without risking a partial write.
 //   --dry-run          print the planned rotation move-set, change nothing.
 //   --today=YYYY-MM-DD pin the lastUpdated stamp (tests / reproducible runs).
 //
@@ -693,7 +696,7 @@ const runMigrate = (root, flags, today, deps, log, logError) => {
   return 0;
 };
 
-const runWriteNavigator = (root, today, deps, log, logError) => {
+const runWriteNavigator = (root, flags, today, deps, log, logError) => {
   if (!existsSync(resolve(root, HOT_REL)) && !existsSync(resolve(root, ADR_DIR_REL))) {
     log(`[archive-decisions] SKIP — no ADR substrate (neither ${HOT_REL} nor ${ADR_DIR_REL}); nothing to write.`);
     return 0;
@@ -704,6 +707,14 @@ const runWriteNavigator = (root, today, deps, log, logError) => {
   const adrEntries = loadAdrStore(root);
   assertStoreIntegrity(hotEntries, adrEntries); // never emit a duplicate-row / corrupt navigator
   const corpus = [...hotEntries, ...adrEntries];
+  // --dry-run runs EXACTLY the validation above and stops before every write: the parse, the
+  // half-migrated guard and the store-integrity check are the same code the write path uses, so a
+  // caller (the guarded ADR-store crossing) can earn a go-ahead without a partial write. A separate
+  // re-implementation of these checks would be an approximation that can disagree with the writer.
+  if (flags.dryRun) {
+    log(`[archive-decisions] --write-navigator DRY-RUN — no files will be changed; ${corpus.length} ADR(s) validated.`);
+    return 0;
+  }
   writeNavigatorFile(root, corpus, today);
   const regen = (deps.regenerateIndex ?? defaultRegenerateIndex)(root, today);
   log(`[archive-decisions] wrote ${NAV_REL} (${corpus.length} ADRs in the corpus).`);
@@ -828,7 +839,7 @@ export const runCli = (argv, deps = {}) => {
     const today = todayOpt ?? new Date().toISOString().slice(0, 10);
 
     if (flags.migrate) return runMigrate(root, flags, today, deps, log, logError);
-    if (flags.writeNavigator) return runWriteNavigator(root, today, deps, log, logError);
+    if (flags.writeNavigator) return runWriteNavigator(root, flags, today, deps, log, logError);
     if (flags.check) return runCheck(root, today, log, logError);
 
     if (!existsSync(resolve(root, HOT_REL))) {

package/references/scripts/archive-decisions.test.mjs

@@ -643,6 +643,33 @@ describe('1.5 navigator — governing heads (computed), superseded drop out but
     assert.doesNotMatch(gov, /\| AD-002 \|/, 'the Proposed ADR is NOT a governing head (accepted & not-superseded only)');
   });
 
+  // The read-only preflight a guarded caller needs: the SAME parse / half-migrated guard / store
+  // integrity the writer runs, stopping before every write. Without it a caller can only learn that
+  // seeding is safe by seeding.
+  it('--write-navigator --dry-run validates and writes NOTHING', () => {
+    const root = makeRoot();
+    seedMigrated(root, { hotIds: ['005', '006'], storeIds: ['001'] });
+    const navBefore = readFileSync(join(root, NAV_REL), 'utf8');
+    rmSync(join(root, NAV_REL));
+    const r = run(['--write-navigator', '--dry-run', '--today=2026-07-09'], root);
+    assert.equal(r.code, 0);
+    assert.match(r.out.join('\n'), /DRY-RUN/, 'the run states it changed nothing');
+    assert.equal(existsSync(join(root, NAV_REL)), false, 'the navigator was NOT written by the dry-run');
+    // and the real run still produces exactly what the dry-run validated
+    assert.equal(run(['--write-navigator', '--today=2026-07-09'], root).code, 0);
+    assert.equal(readFileSync(join(root, NAV_REL), 'utf8'), navBefore);
+  });
+
+  it('--write-navigator --dry-run REFUSES a corrupt store instead of green-lighting it', () => {
+    const root = makeRoot();
+    seedMigrated(root, { hotIds: ['005', '006'], storeIds: ['001'] });
+    // a record whose id also lives in the HOT window — the store would hold the ADR twice
+    writeFileSync(join(root, ADR_DIR_REL, 'AD-005-dup.md'), '---\n---\n\n## AD-005 — Dup\n\nBody.\n');
+    const r = run(['--write-navigator', '--dry-run', '--today=2026-07-09'], root);
+    assert.notEqual(r.code, 0, 'a corrupt store fails the preflight');
+    assert.doesNotMatch(r.out.join('\n'), /DRY-RUN/, 'no go-ahead is printed for a tree that cannot converge');
+  });
+
   it('authoring a new HOT ADR then --write-navigator keeps --check green; a stale nav with NO write → exit 1, then --write-navigator fixes it', () => {
     const root = makeRoot();
     seedMigrated(root, { hotIds: ['005', '006'], storeIds: ['001'] });

package/tools/family-registry.mjs

@@ -342,23 +342,89 @@ const hasHiddenFence = (projectDir, deps = {}) => {
 // The retired 3-tier ADR monoliths (AD-051): their presence is the old-layout signal a consumer must
 // migrate away from via the opt-in `migrate-adr-store` mode. Stable relative paths (a status probe
 // never imports the rotator).
-const DECISIONS_MONOLITHS = ['docs/ai/history/decisions-archive.md', 'docs/ai/history/decisions-archive-early.md'];
-const ADR_STORE_DIR = 'docs/ai/adr';
+// The ADR-layout probe's paths. LOCAL literals, not an import: this module backs the read-only
+// `status` view and importing the rotator would drag child_process + crypto into a status read. A
+// drift guard in family-registry.test.mjs pins each literal to the rotator's exported constant —
+// the same baked-frozen-copy shape the gate hook uses for its velocity constants.
+export const ADR_LAYOUT_PATHS = Object.freeze({
+  hot: 'docs/ai/decisions.md',
+  monoliths: Object.freeze(['docs/ai/history/decisions-archive.md', 'docs/ai/history/decisions-archive-early.md']),
+  store: 'docs/ai/adr',
+  // The DEPLOYED rotator is the discriminator: the new-scheme file names the store path, the
+  // pre-migration one does not. Never "has decisions.md, lacks adr/" — that shape false-positives a
+  // tree whose NEW rotator already reds its own gate, and every No-Node project.
+  rotator: 'scripts/archive-decisions.mjs',
+  storeMarker: 'docs/ai/adr',
+});
+const ENOENT = 'ENOENT';
 
 // The ADR-store layout axis: 'old' (a retired decisions-archive monolith is still on disk — needs
 // the opt-in migration), 'migrated' (the one-file-per-ADR adr/ store is in place), or 'none' (no ADR
 // substrate at all). Keys on the monolith presence, NOT on the stamp/head (Decision 6/13).
-const surveyAdrLayout = (dir, exists) => {
-  const safe = (rel) => {
+// The STRICT core. Absence is ENOENT and nothing else: existsSync collapses EVERY failure to false
+// (EACCES included), so a strict policy layered on it would be vacuous in production and observable
+// only through injected deps — and ENOTDIR means a file where a directory belongs, i.e. corruption,
+// not "not there". Everything else propagates, so the advisor can degrade to a STATED SKIP instead
+// of printing "flow optimal" over a layout it could not read.
+export const PATH_DIR = 'dir';
+export const PATH_FILE = 'file';
+export const PATH_OTHER = 'other';
+const probeStat = (path) => {
+  const st = statSync(path);
+  return st.isDirectory() ? PATH_DIR : st.isFile() ? PATH_FILE : PATH_OTHER;
+};
+
+export const surveyAdrLayoutStrict = (dir, deps = {}) => {
+  const stat = deps.statPath ?? probeStat;
+  const read = deps.readFile ?? readFileSync;
+  const absent = (err) => err && err.code === ENOENT;
+  // The TYPE is part of the question: a regular file named `docs/ai/adr` is not a store, and a
+  // directory named `archive-decisions.mjs` is not a rotator. Answering `migrated` off a name alone
+  // is the same fail-open this survey exists to avoid.
+  const typeAt = (rel) => {
     try {
-      return exists(join(dir, rel));
-    } catch {
-      return false;
+      return stat(join(dir, rel));
+    } catch (err) {
+      if (absent(err)) return null;
+      throw err;
     }
   };
-  if (DECISIONS_MONOLITHS.some(safe)) return 'old';
-  if (safe(ADR_STORE_DIR)) return 'migrated';
-  return 'none';
+  const isA = (rel, kind) => typeAt(rel) === kind;
+
+  if (ADR_LAYOUT_PATHS.monoliths.some((rel) => isA(rel, PATH_FILE))) return 'old';
+
+  // Rotator provenance is resolved BEFORE any verdict, because it also disambiguates a tree that
+  // HAS a store: an old-scheme rotator beside a store is not finished — `upgrade` preserves that
+  // script and it will write a monolith again the next time it rotates.
+  const rotatorScheme = (() => {
+    if (!isA(ADR_LAYOUT_PATHS.rotator, PATH_FILE)) return null;
+    try {
+      return String(read(join(dir, ADR_LAYOUT_PATHS.rotator), 'utf8')).includes(ADR_LAYOUT_PATHS.storeMarker) ? 'new' : 'old';
+    } catch (err) {
+      if (absent(err)) return null;
+      throw err;
+    }
+  })();
+
+  if (isA(ADR_LAYOUT_PATHS.store, PATH_DIR)) return rotatorScheme === 'old' ? 'old-unrotated' : 'migrated';
+  // No substrate at all: the crossing cannot seed a store with nothing to put in it, so the
+  // detector must not ask for one (this is also what the rotator's own no-substrate skip does).
+  if (!isA(ADR_LAYOUT_PATHS.hot, PATH_FILE)) return 'none';
+  // No deployed rotator: no evidence of scheme, and nothing actionable — upgrade's seed-if-missing
+  // owns that path, and on a No-Node project a Node tool would be a permanent unactionable nag.
+  // A NEW-scheme rotator with no store is cohort A: its own --check already reds on every commit
+  // naming --write-navigator, so it is never nagged twice.
+  return rotatorScheme === 'old' ? 'old-unrotated' : 'none';
+};
+
+// The LENIENT wrapper — the read-only status view must never crash, so any failure reads `none`.
+// One implementation, two stated policies; the advisor uses the strict core deliberately.
+const surveyAdrLayout = (dir, deps) => {
+  try {
+    return surveyAdrLayoutStrict(dir, deps);
+  } catch {
+    return 'none';
+  }
 };
 
 // surveyProject → the deploy axis for a target project dir: the per-member deployment stamps, whether
@@ -378,7 +444,7 @@ export const surveyProject = (projectDir, deps = {}) => {
     }
   })();
   const deployed = stamps.some((s) => s.version != null) || docsAiPresent;
-  return { dir, deployed, docsAiPresent, adrLayout: surveyAdrLayout(dir, exists), hiddenFence: hasHiddenFence(dir, deps), stamps };
+  return { dir, deployed, docsAiPresent, adrLayout: surveyAdrLayout(dir, deps), hiddenFence: hasHiddenFence(dir, deps), stamps };
 };
 
 // ── report ───────────────────────────────────────────────────────────────────────
@@ -615,7 +681,7 @@ export const buildEnvelope = (family, project = null, extras = {}) => {
       dir: project.dir,
       deployed: project.deployed,
       docsAi: project.docsAiPresent,
-      adrLayout: project.adrLayout, // 'old' | 'migrated' | 'none' — a user-safe token, never a raw path
+      adrLayout: project.adrLayout, // 'old' | 'old-unrotated' | 'migrated' | 'none' — a user-safe token, never a raw path
       // member + display + version only — never the internal stamp FILENAME (s.file).
       deployStamps: project.stamps.map((s) => ({ member: s.name, display: displayOf(s.name), version: s.version ?? null })),
     };

package/tools/migrate-adr-store.mjs

@@ -7,8 +7,13 @@
 // which migrates in the same step (AD-051, Decision 13).
 //
 // What it does (in order, on --apply):
-//   1. GATE  — docs/ai must be deployed; the OLD layout must be present (a decisions-archive monolith
-//              on disk). No monolith → a stated no-op (already migrated, or a fresh new-scheme tree).
+//   1. GATE  — docs/ai must be deployed, and the tree must be on the OLD layout. That is TWO shapes:
+//              a decisions-archive monolith on disk, OR no monolith at all but a deployed
+//              scripts/archive-decisions.mjs that predates the store (the project simply never
+//              rotated). The no-monolith shape runs the crossing WITHOUT an explosion — snapshot,
+//              script refresh, then SEED the store — and is re-runnable to completion from any crash
+//              point, because a store directory alone never counts as finished. A tree with no ADR
+//              substrate at all, or one already finalised, is a stated no-op.
 //   2. SNAPSHOT — write a durable pre-migration snapshot (decisions.md + both monoliths + the
 //              pre-refresh consumer scripts/ copies) to the project's git dir (uncommittable), with a
 //              stated out-of-tree fallback off git; fail LOUD if neither base is writable (Decision 5).
@@ -38,8 +43,11 @@ import {
   WARM_REL,
   COLD_REL,
   ADR_DIR_REL,
+  NAV_REL,
+  defaultRegenerateIndex,
   runCli as runArchiveDecisions,
 } from '../references/scripts/archive-decisions.mjs';
+import { surveyAdrLayoutStrict, ADR_LAYOUT_PATHS } from './family-registry.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const KIT_ROOT = resolve(HERE, '..');
@@ -183,16 +191,181 @@ export const writeSnapshot = (cwd, refresh, stamp, deps = {}) => {
 };
 
 // Overwrite each refresh target with the kit canon, atomically, preserving the canon's exec bit.
+//
+// ORDER MATTERS: the rotation script is what the layout discriminator reads, so it is written LAST.
+// A crash partway through a refresh that had already flipped it would otherwise leave a tree that
+// LOOKS refreshed while other scripts are still the old copies — and a resume, keying on that same
+// script, would skip them forever. Written last, an interrupted refresh always re-plans in full.
+const DISCRIMINATOR_SCRIPT = ADR_LAYOUT_PATHS.rotator.split('/').pop();
+const refreshOrder = (refresh) => [
+  ...refresh.filter((r) => r.name !== DISCRIMINATOR_SCRIPT),
+  ...refresh.filter((r) => r.name === DISCRIMINATOR_SCRIPT),
+];
+
 const applyScriptRefresh = (cwd, refresh, deps = {}) => {
   const read = deps.read ?? readFileSync;
   const chmod = deps.chmod ?? chmodSync;
   const stat = deps.stat ?? statSync;
-  for (const { canon, dst, name } of refresh) {
+  for (const { canon, dst, name } of refreshOrder(refresh)) {
     writeContainedFileAtomic(cwd, dst, read(canon, 'utf8'), deps, { stop, label: `${CONSUMER_SCRIPTS_REL}/${name}` });
     chmod(dst, stat(canon).mode & 0o777); // the exec bit is the git-tracked axis the mirror guard pins
   }
 };
 
+// ── the no-monolith crossing ─────────────────────────────────────────────────────
+//
+// A consumer on the RETIRED scheme that never rotated far enough to produce a monolith used to read
+// "a fresh new-scheme tree" here and be sent away. The discriminator is the deployed rotation
+// script's own provenance (family-registry.mjs), never "has decisions.md, lacks adr/".
+//
+// Re-entry is decided by what is FINISHED, never by one existence bit: the store directory existing
+// does not prove the navigator was written or the index regenerated, so a crash there must not turn
+// the next --apply into a no-op. Every write below is individually idempotent, which is why this
+// needs no resume ledger.
+
+// The crossing is COMPLETE when the navigator exists, the tree's own gate passes, AND the index the
+// crossing regenerates is fresh. The index is part of the criterion because it is a real output of
+// the crossing that `--check` never looks at: a crash (or a failed regeneration) between the
+// navigator write and the index left a tree that reported "already migrated" on the retry and never
+// repaired the index. An unreachable index generator is NOT treated as fresh — the crossing re-runs
+// and fails loudly again, which is the honest outcome for a broken generator.
+const INDEX_GENERATOR = join(KIT_SCRIPTS, 'check-docs-size.mjs');
+const isIndexFresh = (cwd, deps = {}) => {
+  const spawn = deps.spawnSync ?? spawnSync;
+  const r = spawn(process.execPath, [INDEX_GENERATOR, '--check-index', `--root=${cwd}`], { encoding: 'utf8' });
+  return !r.error && r.status === 0;
+};
+
+// The layout verdict leads, and it is the SAME verdict the status line and the advisor read: an
+// old-scheme rotator beside a finished store still answers `old-unrotated`, so treating that tree as
+// done would leave the signal permanently lit with nothing able to clear it.
+const isFinalised = (cwd, runMigrate, deps = {}) =>
+  surveyAdrLayoutStrict(cwd, deps) === 'migrated' &&
+  substratePresent(join(cwd, NAV_REL), deps) &&
+  runMigrate(['--check'], { root: cwd, log: () => {}, logError: () => {} }) === EXIT_OK &&
+  isIndexFresh(cwd, deps);
+
+// `existsSync` answers false for EVERY failure, EACCES included — so asking it whether the substrate
+// is there would turn an UNREADABLE tree into a confident "nothing to migrate", exit 0. Absence is
+// ENOENT and nothing else; anything else is surfaced, never swallowed. Same policy the layout survey
+// already enforces, now applied where the tool acts on it.
+const substratePresent = (path, deps = {}) => {
+  const stat = deps.statSync ?? statSync;
+  try {
+    stat(path);
+    return true;
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return false;
+    throw stop(`cannot read ${path} (${err && err.message}) — refusing to report on a tree it could not inspect`);
+  }
+};
+
+const crossWithoutMonolith = (cwd, args, stamp, { log, error, runMigrate, deps }) => {
+  const hasStore = substratePresent(join(cwd, ADR_DIR_REL), deps);
+  const hasHot = substratePresent(join(cwd, HOT_REL), deps);
+
+  if (!hasHot && !hasStore) {
+    // NOT "a fresh new-scheme tree" — this tree may well be old-scheme; it simply has no ADR
+    // substrate for the crossing to carry across, which is exactly the rotator's own skip.
+    log(`[migrate-adr-store] nothing to migrate — no ADR substrate (neither ${HOT_REL} nor ${ADR_DIR_REL}/) and no legacy monolith.`);
+    return EXIT_OK;
+  }
+  if (hasStore && isFinalised(cwd, runMigrate, deps)) {
+    log('[migrate-adr-store] already migrated — the one-file-per-ADR store is in place and its gate is green; nothing to do.');
+    return EXIT_OK;
+  }
+  if (!hasStore && surveyAdrLayoutStrict(cwd, deps) === 'none' && !substratePresent(join(cwd, ADR_LAYOUT_PATHS.rotator), deps)) {
+    // Nothing to refresh (the refresh is directional — it never ADDS a script) and nothing to
+    // maintain a store we might seed. The normal upgrade owns seeding the pair.
+    log('[migrate-adr-store] nothing to migrate — no deployed rotation script; run the normal upgrade first (it seeds the ADR enforcement pair).');
+    return EXIT_OK;
+  }
+
+  const refresh = planScriptRefresh(cwd, deps);
+  const drifted = refresh.filter((r) => r.differs);
+  // The read-only preflight: the SAME parse / half-migrated guard / store-integrity check the seed
+  // itself runs, stopping before every write. Without it a dry-run could green-light an apply that
+  // writes the store and only then discovers it cannot converge.
+  const preflight = (logError) => runMigrate(['--write-navigator', '--dry-run'], { root: cwd, log: () => {}, logError });
+
+  if (!args.apply) {
+    const preview = resolveSnapshotDir(cwd, stamp, deps);
+    // Three attempts to SUMMARISE why this tree needs the crossing produced three wrong sentences —
+    // each true of the common case and false of a state this arm deliberately supports. So the
+    // summary is gone: the preview states the two facts it actually knows, one per line, and the
+    // reader draws the conclusion. Nothing here can drift out of step with the tree, because nothing
+    // here is an inference. (Which scripts are stale is already reported by the refresh line below —
+    // never re-asserted here.)
+    const layout = surveyAdrLayoutStrict(cwd, deps);
+    const rotatorFact = layout === 'old-unrotated'
+      ? `predates the one-file-per-ADR store`
+      : substratePresent(join(cwd, ADR_LAYOUT_PATHS.rotator), deps)
+        ? `already names the store`
+        : `not deployed`; // and NOT "nothing to refresh" — a sibling script may still need one
+    log('[migrate-adr-store] --dry-run — no files will be changed. Planned crossing (no legacy monolith to retire):');
+    log(`  deployed ${ADR_LAYOUT_PATHS.rotator}: ${rotatorFact}`);
+    log(`  ${ADR_DIR_REL}/: ${hasStore ? 'present, but the crossing has not been completed' : 'absent'}`);
+    log(`  snapshot → ${preview.dir ? `${preview.dir} (${preview.viaGitDir ? 'git dir' : 'out-of-tree fallback'})` : 'NONE — no out-of-tree location; run inside a git repo (apply would refuse otherwise)'}`);
+    log(`  refresh ${refresh.length} enforcement script(s) to this kit's version${drifted.length ? ` (${drifted.length} locally differ: ${drifted.map((r) => r.name).join(', ')})` : ''}`);
+    log(`  then seed the store: create ${ADR_DIR_REL}/, write ${NAV_REL} and regenerate docs/ai/index.md`);
+    const code = preflight((m) => error(`    ${m}`));
+    if (code !== EXIT_OK) {
+      throw stop(`the tree cannot be seeded as it stands (exit ${code}) — NOT safe to --apply; fix the reported problem, then re-run.`);
+    }
+    if (preview.dir === null) {
+      throw stop('no out-of-tree snapshot location — --apply would refuse; run inside a git repo (or point the fallback outside the project), then re-run.');
+    }
+    log('  index regeneration is verified at --apply time (a dry-run cannot observe it without writing).');
+    log('Run `/agent-workflow-kit migrate-adr-store` again with --apply to perform it (it never commits).');
+    return EXIT_OK;
+  }
+
+  const pre = preflight(error);
+  if (pre !== EXIT_OK) {
+    throw stop(`the tree cannot be seeded as it stands (preflight exit ${pre}) — refusing to touch the tree; fix the reported problem, then re-run.`);
+  }
+
+  const snapshot = writeSnapshot(cwd, refresh, stamp, deps);
+  // The FULL refresh is re-planned and re-applied on every entry, so an interrupted one always
+  // completes; the discriminator script is written last (see refreshOrder).
+  applyScriptRefresh(cwd, refresh, deps);
+
+  // Capture the index-regeneration verdict instead of matching log prose: the rotator logs a failed
+  // regeneration and still returns 0, so "the gates are green" would not mean the index is fresh.
+  const regen = { ok: true, detail: '' };
+  const seed = runMigrate(['--write-navigator'], {
+    root: cwd,
+    log,
+    logError: error,
+    regenerateIndex: (root, today, d) => {
+      const r = (deps.regenerateIndex ?? defaultRegenerateIndex)(root, today, d);
+      regen.ok = r.ok;
+      regen.detail = r.detail;
+      return r;
+    },
+  });
+  if (seed !== EXIT_OK) {
+    throw stop(`seeding the ADR store failed (exit ${seed}) — the pre-crossing snapshot is at ${snapshot.dir}; resolve the reported problem and re-run (the crossing is idempotent).`);
+  }
+  if (!regen.ok) {
+    throw stop(`the ADR store was seeded but docs/ai/index.md was NOT regenerated (${regen.detail}) — the pre-crossing snapshot is at ${snapshot.dir}; fix the index generator and re-run (the crossing is idempotent).`);
+  }
+  const verify = runMigrate(['--check'], { root: cwd, log: () => {}, logError: error });
+  if (verify !== EXIT_OK) {
+    throw stop(`the ADR store was seeded but its own gate does not pass (exit ${verify}) — the pre-crossing snapshot is at ${snapshot.dir}; resolve the reported problem and re-run (the crossing is idempotent).`);
+  }
+
+  // States what this run DID, never what the tree was before it: the same arm completes an
+  // interrupted crossing whose scripts were already current, which no "old-scheme" claim covers.
+  log('[migrate-adr-store] crossing complete — the one-file-per-ADR store is in place (no legacy monolith was present):');
+  log(`  snapshot: ${snapshot.dir} (${snapshot.viaGitDir ? 'git dir' : 'out-of-tree fallback'}, ${snapshot.fileCount} file(s))`);
+  log(`  refreshed ${refresh.length} enforcement script(s) to this kit's version`);
+  log(`  seeded ${ADR_DIR_REL}/ with ${NAV_REL} and regenerated docs/ai/index.md`);
+  log('  next: run the normal upgrade (it re-stamps the deployment lineage to the current head),');
+  log('  then review the migrated docs/ai/ tree and the re-stamp together and commit them yourself — this command never commits.');
+  return EXIT_OK;
+};
+
 export const main = (argv = process.argv.slice(2), deps = {}) => {
   const log = deps.log ?? console.log;
   const error = deps.error ?? console.error;
@@ -209,11 +382,7 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
 
     const monoliths = monolithsPresent(cwd);
     if (monoliths.length === 0) {
-      const migrated = existsSync(join(cwd, ADR_DIR_REL));
-      log(migrated
-        ? '[migrate-adr-store] already migrated — the one-file-per-ADR store is in place (no legacy monolith); nothing to do.'
-        : '[migrate-adr-store] nothing to migrate — no legacy decisions-archive monolith found (a fresh new-scheme tree).');
-      return EXIT_OK;
+      return crossWithoutMonolith(cwd, args, stamp, { log, error, runMigrate, deps });
     }
 
     const refresh = planScriptRefresh(cwd, deps);

package/tools/recommendations.mjs

@@ -51,7 +51,7 @@ import { loadAutonomy, isSparseSeedConfig, AUTONOMY_REL } from './autonomy-confi
 import { deriveDoctorPlan } from './autonomy-doctor.mjs';
 import { detectBackends, findOnPath } from './detect-backends.mjs';
 import { ACTIVITIES, resolveActivityRecipe } from './recipes.mjs';
-import { surveyFamily, surveyGateHook } from './family-registry.mjs';
+import { surveyFamily, surveyGateHook, surveyAdrLayoutStrict } from './family-registry.mjs';
 import { probeSandboxMasks, needsMasksApply } from './sandbox-masks.mjs';
 import { shellQuoteArg } from './review-state.mjs';
 import { isFinalCapableDeclaration } from './run-gates.mjs';
@@ -108,6 +108,7 @@ export const SEVERITIES = Object.freeze({
   'state-block': SEVERITY_OPTIONAL,
   agents: SEVERITY_OPTIONAL,
   'family-freshness': SEVERITY_ATTENTION,
+  'adr-store-migration': SEVERITY_ATTENTION,
   'sandbox-masks': SEVERITY_OPTIONAL,
   'sandbox-lane': SEVERITY_OPTIONAL,
   'worktrees-dir': SEVERITY_OPTIONAL,
@@ -165,6 +166,7 @@ export const WHATS = Object.freeze({
   'state-block': 'nothing checks the closing state block — a turn that ends on «nothing needed from you», or on a promise it never started, passes unseen',
   agents: '{n} read-only subagent(s) not placed (Claude Code) — no shell-free vehicle for that work; the apply PREVIEWS first',
   'family-freshness': '{parts}',
+  'adr-store-migration': 'still on the retired 3-tier ADR layout — {shape}',
   'sandbox-masks': '{n} sandbox device mask(s) clutter git status — the managed exclude block is absent or stale',
   'sandbox-masks.stale-real': '{n} sandbox device mask(s) clutter git status — the exclude block is stale; {m} fenced entr(ies) are REAL paths (a fresh apply drops them)',
   'sandbox-lane': 'the wired review wrappers declare a session-sandbox recipe (egress hosts + writable state dirs) not yet acknowledged for this project',
@@ -218,6 +220,7 @@ export const BENEFITS = Object.freeze({
   'state-block': 'no silent stalls — a turn ending on «you are not needed», or on work it never started, warns at once instead of waiting to be spotted',
   agents: 'cost and quiet — mechanical work runs on a cheap model, and no vehicle has a shell, so a read-only fan-out cannot flood you with prompts',
   'family-freshness': 'currency — placed family members carry the latest shipped fixes and features',
+  'adr-store-migration': 'durability — every decision becomes its own file with a generated navigator, instead of one hand-rotated pile',
   'sandbox-masks': 'zero clutter — git status shows only your changes (the review domain already ignores the masks by construction)',
   'sandbox-lane': 'discoverability — the manifest-declared observed sandbox recipe for bridge runs surfaces itself instead of waiting to be asked',
   'worktrees-dir': 'parallel features — the host-specific write allowance or terminal fallback is surfaced before provision',
@@ -254,6 +257,7 @@ export const OPT_IN_CAPABILITIES = Object.freeze([
   { id: 'sandbox-masks', mode: 'sandbox-masks', advisorKey: 'sandbox-masks' },
   { id: 'worktrees-dir', mode: 'worktrees', advisorKey: 'worktrees-dir' },
   { id: 'family-freshness', mode: 'upgrade', advisorKey: 'family-freshness' },
+  { id: 'adr-store-migration', mode: 'migrate-adr-store', advisorKey: 'adr-store-migration' },
   { id: 'review-recipe', mode: 'set-recipe', advisorKey: 'review-recipe' },
   // The execute slot is a DISTINCT opt-in from the review slot, and the same probe reports both —
   // which is why the review-recipe benefit is worded for either slot rather than for review alone.
@@ -788,7 +792,7 @@ const readReadLaneToggle = (root, deps) => {
 // D3: the risk-marked keys — every key here has a per-item posture note in the mode doc, surfaced
 // at the consent moment; the static contract test asserts EXACT bidirectional coverage
 // (risk-marked keys == mode-doc note keys — a dropped note goes red, not silent).
-export const RISK_NOTED_KEYS = Object.freeze(['sandbox-lane', 'read-lane', 'worktrees-dir']);
+export const RISK_NOTED_KEYS = Object.freeze(['sandbox-lane', 'read-lane', 'worktrees-dir', 'adr-store-migration']);
 
 const probeSandboxLane = ({ root, deps, add, skip }) => {
   try {
@@ -965,6 +969,40 @@ const probeWorktreesDir = ({ root, deps, add, skip }) => {
   }
 };
 
+// The ADR-store crossing. Until now this mode declared it had NO advisor capability, on the argument
+// that status and upgrade already report the old layout — but they only reported the MONOLITH shape,
+// so a project whose deployed rotator merely predates the store was told nothing by anything.
+//
+// Honest scope: the advisor is the deterministic section every `upgrade` run ends with, so this is
+// NOT a new door for someone who never runs status or upgrade — it MECHANIZES the upgrade door.
+//
+// It reads the STRICT layout survey deliberately: the lenient one turns every fs failure into
+// "no ADR layout here", which would print «flow optimal» over a layout the probe could not read. A
+// failure must become a STATED SKIP, never an absence.
+// Each shape states a fact about THIS tree that holds whether or not a store directory exists —
+// `old-unrotated` also covers a tree whose store is already there but whose rotation script is not,
+// and saying "the store is not in place" there would be false.
+const ADR_LAYOUT_SHAPES = Object.freeze({
+  old: 'a legacy archive file is still on disk and must be exploded into the per-file store',
+  'old-unrotated': 'the deployed rotation script predates the store and keeps writing the retired layout',
+});
+export const probeAdrStore = ({ root, deps, add, skip }) => {
+  try {
+    const shape = ADR_LAYOUT_SHAPES[surveyAdrLayoutStrict(root, deps)];
+    if (!shape) return; // migrated, or no ADR substrate at all — nothing to offer
+    // HAND-APPLY, not the standard lane: the consent flow executes the apply slot against the
+    // confirmation given BEFORE the preview, and this crossing requires informed consent AFTER its
+    // dry-run. A runnable one-liner here would auto-run a tree-mutating migration on stale consent.
+    add(
+      'adr-store-migration',
+      fillTemplate(WHATS['adr-store-migration'], { shape }),
+      `HAND-APPLY: node ${q(toolPath('migrate-adr-store.mjs'))} --dry-run --cwd ${q(root)} — then re-run with --apply ONLY after showing the plan and getting fresh consent`,
+    );
+  } catch (err) {
+    skip('adr-store-migration', err);
+  }
+};
+
 // ── assembly (frozen presentation order) ─────────────────────────────────────────────────────────
 const PROBES = Object.freeze([
   probeVelocityItems,
@@ -977,6 +1015,7 @@ const PROBES = Object.freeze([
   probeStateBlockHook,
   probeCheapAgents,
   probeFamilyFreshness,
+  probeAdrStore,
   probeMasksItem,
   probeSandboxLane,
   probeWorktreesDir,

package/tools/renderers.mjs

@@ -15,6 +15,10 @@ const READINESS_COL = 14;
 const STAMP_COL = 26;
 const SETTINGS_COL = 14;
 
+// The ADR-layout tokens that carry an action for the user. Kept as a list, not a chain of equality
+// checks, so a future token joins the render by joining this line.
+const ACTIONABLE_ADR_LAYOUTS = Object.freeze(['old', 'old-unrotated']);
+
 const SGR = Object.freeze({ bold: '\x1b[1m', reset: '\x1b[0m' });
 const ANSI_RE = /\x1b\[[0-9;]*m/g;
 export const visibleLength = (s) => s.replace(ANSI_RE, '').length;
@@ -86,8 +90,10 @@ const renderProject = (vm, { color }) => {
   }
   for (const s of p.deployStamps) lines.push(`  ${pad(s.display, STAMP_COL)}${s.version ?? '—'}`);
   lines.push(`  ${pad('docs/ai present', STAMP_COL)}${p.docsAi ? 'yes' : 'no'}`);
-  // Only the actionable 'old' layout renders a line — a migrated/none store needs no note (AD-051).
-  if (p.adrLayout === 'old') {
+  // Only an ACTIONABLE layout renders a line — a migrated/none store needs no note (AD-051). Both
+  // actionable tokens render the SAME line: 'old' (a monolith on disk) and 'old-unrotated' (an
+  // old-scheme rotator that never rotated) differ only in the discriminator, never in the remedy.
+  if (ACTIONABLE_ADR_LAYOUTS.includes(p.adrLayout)) {
     lines.push(`  ${pad('ADR store', STAMP_COL)}old layout — run /agent-workflow-kit migrate-adr-store`);
   }
   if (p.visibility) {