@sabaiway/agent-workflow-kit 4.4.0 → 5.0.0

package/tools/known-footprint.mjs

@@ -29,7 +29,7 @@ export const stop = (message, fields = {}) =>
 // ── registries ────────────────────────────────────────────────────────────────
 
 // The kit's OWN footprint — canonical anchored patterns. `/docs/ai/` subsumes the deployment stamp
-// (`.workflow-version`); the 8 enforcement scripts are enumerated (no bare `/scripts/` — a host repo
+// (`.workflow-version`); the enforcement scripts are enumerated (no bare `/scripts/` — a host repo
 // may have unrelated scripts). `/.claude/settings.json` is carried HIDDEN-ONLY: in hidden mode the
 // kit's own attribution file is a footprint; in visible mode the kit commits it and never runs this
 // tool. It passes the same tracked→ASK classifier, so a project that already commits it gets an ASK,
@@ -43,13 +43,17 @@ export const KIT_OWN_PATHS = [
   '/scripts/_expect-shim.mjs',
   '/scripts/archive-changelog.mjs',
   '/scripts/archive-changelog.test.mjs',
+  '/scripts/archive-conservation.test.mjs',
   '/scripts/archive-decisions.mjs',
   '/scripts/archive-decisions.test.mjs',
   '/scripts/archive-issues.mjs',
   '/scripts/archive-issues.test.mjs',
+  '/scripts/archiver-structure.test.mjs',
   '/scripts/check-docs-size.mjs',
   '/scripts/check-docs-size.test.mjs',
   '/scripts/install-git-hooks.mjs',
+  '/scripts/markdown-blocks.mjs',
+  '/scripts/markdown-blocks.test.mjs',
   '/docs/plans/',
   '/.claude/settings.local.json',
   '/.claude/settings.json',

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, '..');
@@ -111,6 +119,26 @@ export const planScriptRefresh = (cwd, deps = {}) => {
   return out;
 };
 
+// COMPANION seeds: modules the refreshed archivers IMPORT. The refresh above is deliberately
+// directional (never ADDS a basename the consumer lacks), but refreshing an OLD deployment's
+// archivers to this kit's canon without their runtime dependency would leave every refreshed
+// script crashing on a missing `./markdown-blocks.mjs` import until a separate upgrade run — so
+// the dependency rides the SAME apply, atomically, written before its importers.
+const COMPANION_SEEDS = ['markdown-blocks.mjs', 'markdown-blocks.test.mjs'];
+export const planCompanionSeeds = (cwd, refresh, deps = {}) => {
+  if (refresh.length === 0) return [];
+  const exists = deps.exists ?? existsSync;
+  const kitScripts = deps.kitScripts ?? KIT_SCRIPTS;
+  const consumerScripts = join(cwd, CONSUMER_SCRIPTS_REL);
+  const out = [];
+  for (const name of COMPANION_SEEDS) {
+    const canon = join(kitScripts, name);
+    const dst = join(consumerScripts, name);
+    if (exists(canon) && !exists(dst)) out.push({ name, canon, dst });
+  }
+  return out;
+};
+
 const gitDirOf = (cwd, spawn) => {
   const r = spawn('git', ['rev-parse', '--absolute-git-dir'], { cwd, encoding: 'utf8' });
   return r && r.status === 0 && r.stdout ? r.stdout.trim() : null;
@@ -183,14 +211,185 @@ 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) {
+  // Companion modules FIRST (a dependency must land before its importers), refresh order after —
+  // the discriminator still last, so an interrupted apply always re-plans in full. Returns the
+  // seeded names (computed pre-write; recomputing after would see them present and report none).
+  const seeds = planCompanionSeeds(cwd, refresh, deps);
+  for (const { canon, dst, name } of [...seeds, ...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
   }
+  return seeds.map((s) => s.name);
+};
+
+// ── 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(', ')})` : ''}`);
+    for (const s of planCompanionSeeds(cwd, refresh, deps)) log(`  seed companion module ${CONSUMER_SCRIPTS_REL}/${s.name} (imported by the refreshed archivers; absent at the consumer)`);
+    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).
+  const seededNames = 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${seededNames.length ? ` + seeded ${seededNames.join(', ')}` : ''}`);
+  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 = {}) => {
@@ -209,11 +408,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);
@@ -225,6 +420,7 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
       log(`  old layout: ${monoliths.join(', ')} (will be exploded into ${ADR_DIR_REL}/ then retired)`);
       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(', ')})` : ''}`);
+    for (const s of planCompanionSeeds(cwd, refresh, deps)) log(`  seed companion module ${CONSUMER_SCRIPTS_REL}/${s.name} (imported by the refreshed archivers; absent at the consumer)`);
       log('  then the conservation-checked rotation:');
       // Surface the rotation's own exit code: a failed dry-run must NOT print the
       // "run with --apply" go-ahead nor exit 0 — it would send the user to --apply on an unsafe tree.
@@ -250,14 +446,14 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
     }
 
     const snapshot = writeSnapshot(cwd, refresh, stamp, deps);
-    applyScriptRefresh(cwd, refresh, deps);
+    const seededNames = applyScriptRefresh(cwd, refresh, deps);
     const code = runMigrate(['--migrate', '--apply'], { root: cwd, log, logError: error });
     if (code !== EXIT_OK) {
       throw stop(`the rotation failed (exit ${code}) — the pre-migration snapshot is at ${snapshot.dir}; resolve the reported problem and re-run (the migration is idempotent).`);
     }
     log('[migrate-adr-store] migrated the 3-tier ADR cascade → one-file-per-ADR store:');
     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(`  refreshed ${refresh.length} enforcement script(s) to this kit's version${seededNames.length ? ` + seeded ${seededNames.join(', ')}` : ''}`);
     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;

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) {