@sabaiway/agent-workflow-kit 4.3.0 → 4.5.0

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