@sabaiway/agent-workflow-kit 1.40.0 → 1.42.0

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

@@ -270,6 +270,31 @@ const formatIndexRow = (row) => {
   return `| ${link} | ${fm.type ?? '—'} | ${row.lineCount}/${fm.maxLines ?? '—'} | ${fm.lastUpdated ?? '—'} | ${fm.staleAfter ?? '—'} |`;
 };
 
+// The one-file-per-ADR store (docs/ai/adr/) grows O(n) forever, so its rows would blow the index's
+// own 80-line cap. It COLLAPSES to a single aggregate row (link → the navigator adr/log.md, record
+// count + numeric id range) — while walkMarkdownFiles still finds + cap-checks every individual body
+// (a body over its own cap still fails in the main flow; only the index RENDERING is collapsed).
+const ADR_DIR_PREFIX = 'docs/ai/adr/';
+const ADR_RECORD_RE = /\/AD-(\d{3,})-[^/]*\.md$/;
+const ADR_NAV_PATH = 'docs/ai/adr/log.md';
+
+// Only genuine records + the navigator collapse into the aggregate row; an UNEXPECTED file under
+// adr/ (a stray README.md, AD-foo.md) renders as its OWN visible index row — never silently hidden
+// by the collapse (it also fails archive-decisions' own store-integrity check).
+const isCollapsibleAdr = (path) => path.startsWith(ADR_DIR_PREFIX) && (ADR_RECORD_RE.test(path) || path === ADR_NAV_PATH);
+
+const formatAdrCollapseRow = (adrRows) => {
+  const recs = adrRows
+    .map((r) => {
+      const m = r.path.match(ADR_RECORD_RE);
+      return m ? { idStr: m[1], idNum: Number(m[1]) } : null;
+    })
+    .filter(Boolean)
+    .sort((a, b) => a.idNum - b.idNum); // NUMERIC id ordering (AD-200 before AD-1000), never lexical
+  const range = recs.length > 0 ? `AD-${recs[0].idStr} … AD-${recs[recs.length - 1].idStr}` : '—';
+  return `| [\`adr/\`](./adr/log.md) | adr | ${recs.length} records | ${range} | — |`;
+};
+
 // Pure index renderer — given inspected rows + the date to stamp in the header,
 // returns the exact bytes `docs/ai/index.md` should contain. Shared by
 // `--write-index` (writes it) and `--check-index` (diffs against on-disk).
@@ -277,13 +302,18 @@ export const buildIndex = (rows, todayStr, meta = {}) => {
   const projectName = meta.projectName ?? DEFAULT_PROJECT_NAME;
   const onDemandLinks = meta.onDemandLinks ?? [];
   const hierarchicalLinks = meta.hierarchicalLinks ?? [];
-  const sorted = [...rows].sort((a, b) => a.path.localeCompare(b.path));
   const header = INDEX_HEADER.replace('__TODAY__', todayStr).replace('__PROJECT__', projectName);
   const tableHeader = `| File | Type | Lines/Max | Updated | Stale after |\n|------|------|-----------|---------|-------------|`;
-  const tableRows = sorted
-    .filter((r) => r.path !== 'docs/ai/index.md')
-    .map(formatIndexRow)
-    .join('\n');
+  const nonAdr = [];
+  const adrRows = [];
+  for (const r of rows) {
+    if (r.path === 'docs/ai/index.md') continue;
+    (isCollapsibleAdr(r.path) ? adrRows : nonAdr).push(r);
+  }
+  const tableEntries = nonAdr.map((r) => ({ sortPath: r.path, md: formatIndexRow(r) }));
+  if (adrRows.length > 0) tableEntries.push({ sortPath: ADR_DIR_PREFIX, md: formatAdrCollapseRow(adrRows) });
+  tableEntries.sort((a, b) => a.sortPath.localeCompare(b.sortPath));
+  const tableRows = tableEntries.map((e) => e.md).join('\n');
   const onDemandSection =
     onDemandLinks.length > 0
       ? `\n\n## Skills (on-demand)\n\n${onDemandLinks.map((link) => `- ${link}`).join('\n')}`

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

@@ -164,6 +164,61 @@ const makeRow = (path, overrides = {}) => ({
   ...overrides,
 });
 
+// The one-file-per-ADR store collapses to a SINGLE aggregate index row so the index stays under its
+// own 80-line cap no matter how many records accumulate — while every body is still cap-checked.
+describe('buildIndex — docs/ai/adr/ directory collapse (Decision 11)', () => {
+  it('200 synthetic AD-*.md records collapse to ONE aggregate row; the index stays ≤ 80 lines', () => {
+    const adr = Array.from({ length: 200 }, (_, i) => makeRow(`docs/ai/adr/AD-${String(i + 1).padStart(3, '0')}-record-${i}.md`, { frontmatter: { type: 'adr', maxLines: '400', lastUpdated: '2026-07-09', staleAfter: 'never' } }));
+    const rows = [makeRow('docs/ai/handover.md'), makeRow('docs/ai/adr/log.md', { frontmatter: { type: 'reference', maxLines: '200' } }), ...adr];
+    const out = buildIndex(rows, '2026-07-09');
+    const adrRowLines = out.split('\n').filter((l) => l.includes('](./adr/log.md)'));
+    expect(adrRowLines.length).toBe(1); // exactly one row references the whole adr/ tree
+    expect(out).not.toMatch(/AD-001-record-0\.md/); // individual records are NOT listed
+    expect(out.split('\n').length <= 80).toBe(true);
+  });
+
+  it('a stray adr/ markdown file renders as its OWN visible row (never collapsed/hidden)', () => {
+    const rows = [
+      makeRow('docs/ai/adr/AD-001-a.md', { frontmatter: { type: 'adr', maxLines: '400' } }),
+      makeRow('docs/ai/adr/log.md', { frontmatter: { type: 'reference', maxLines: '200' } }),
+      makeRow('docs/ai/adr/notes.md', { frontmatter: { type: 'reference', maxLines: '100' } }),
+    ];
+    const out = buildIndex(rows, '2026-07-09');
+    expect(out).toMatch(/adr\/notes\.md/); // the stray is a visible row, not swallowed by the collapse
+    const aggregateRows = out.split('\n').filter((l) => l.includes('](./adr/log.md)'));
+    expect(aggregateRows.length).toBe(1); // exactly one aggregate row for the real record(s)
+  });
+
+  it('the aggregate row shows the record count and a NUMERIC id range (AD-200 … AD-1000)', () => {
+    const rows = [
+      makeRow('docs/ai/adr/AD-200-a.md', { frontmatter: { type: 'adr', maxLines: '400' } }),
+      makeRow('docs/ai/adr/AD-1000-b.md', { frontmatter: { type: 'adr', maxLines: '400' } }),
+      makeRow('docs/ai/adr/log.md', { frontmatter: { type: 'reference', maxLines: '200' } }),
+    ];
+    const out = buildIndex(rows, '2026-07-09');
+    expect(out).toMatch(/\[`adr\/`\]\(\.\/adr\/log\.md\) \| adr \| 2 records \| AD-200 … AD-1000/);
+  });
+
+  it('adding a record drifts the collapse row → checkIndexFreshness flags it stale', () => {
+    const base = [makeRow('docs/ai/adr/AD-001-a.md', { frontmatter: { type: 'adr', maxLines: '400' } }), makeRow('docs/ai/adr/log.md', { frontmatter: { type: 'reference', maxLines: '200' } })];
+    const onDisk = buildIndex(base, '2026-07-09');
+    const grown = [...base, makeRow('docs/ai/adr/AD-002-b.md', { frontmatter: { type: 'adr', maxLines: '400' } })];
+    expect(checkIndexFreshness(grown, onDisk).fresh).toBe(false);
+  });
+
+  it('a single adr record OVER its own cap still fails inspectFile (the collapse never hides a fat body)', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'adr-cap-'));
+    try {
+      const path = join(dir, 'AD-001-huge.md');
+      await writeFile(path, `---\ntype: adr\nlastUpdated: 2026-07-09\nscope: permanent\nstaleAfter: never\nowner: none\nmaxLines: 5\n---\n\n## AD-001 — Huge\n${'x\n'.repeat(20)}`);
+      const result = await inspectFile(path, computeToday('2026-07-09'));
+      expect(result.errors.some((e) => /lines > maxLines/.test(e))).toBe(true);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});
+
 describe('buildIndex', () => {
   it('is deterministic, sorts rows by path, and excludes index.md itself', () => {
     const rows = [

package/references/templates/adr/log.md

@@ -0,0 +1,25 @@
+---
+type: reference
+lastUpdated: {{DATE}}
+scope: permanent
+staleAfter: never
+owner: none
+maxLines: 200
+---
+
+# ADR Navigator — active set (AD-001 … AD-001)
+
+> **Auto-generated** (`archive-decisions.mjs --write-navigator`). The governing heads only —
+> an ADR superseded/amended by another drops OUT (still reachable by filename, grep, or the
+> `[[AD-NNN]]` chain). The HOT window lives in [`../decisions.md`](../decisions.md); every
+> archived record is one file in this directory. This is a navigator, never a full ledger.
+
+## Governing (1) — accepted & not superseded
+
+| ADR | Title | Record |
+|-----|-------|--------|
+| AD-001 | Adopt AI-agent memory system (`docs/ai/`) | [`../decisions.md`](../decisions.md) |
+
+## Recent (1)
+
+- **AD-001** — governing — `decisions.md (HOT)`

package/references/templates/adr-record.md

@@ -0,0 +1,72 @@
+# ADR record format — authoring & lifecycle reference
+
+> How an Architecture Decision Record is authored, archived, and retrieved in this project's
+> **one-file-per-ADR** store. Read this when you author a new ADR or change an existing one's
+> lifecycle. This file is a reference — it is **not** deployed into `docs/ai/` (it never becomes a
+> record itself).
+
+## Where ADRs live
+
+- **HOT window — `docs/ai/decisions.md`.** The active ADR window. You **author here**, newest at the
+  bottom. It is self-bounding under its frontmatter `maxLines`.
+- **Store — `docs/ai/adr/AD-NNN-slug.md`.** One immutable record per archived ADR (full frontmatter +
+  the verbatim `## AD-NNN — title` block). You **never hand-write** these — `archive-decisions.mjs`
+  produces them by exploding the oldest HOT entries beyond the cap.
+- **Navigator — `docs/ai/adr/log.md`.** The one generated map: the currently-governing heads
+  (accepted ∧ not superseded) + a recent window. Superseded ADRs drop OUT (still reachable by
+  filename, grep, or the `[[AD-NNN]]` chain). It is a navigator, never a full ledger.
+
+## Authoring a new ADR (in the HOT window)
+
+Append a block at the **bottom** of `docs/ai/decisions.md`:
+
+```
+## AD-NNN — <concise title>
+
+**Date:** YYYY-MM-DD
+**Status:** Accepted
+
+**Context.** Why this decision is needed; the forces at play.
+**Decision.** What was chosen (imperative, unambiguous).
+**Consequences.** ➕ benefits · ➖ costs. Note any ADR this supersedes.
+```
+
+- **ID grammar: `AD-\d{3,}`.** Three digits minimum; `AD-1000+` is valid. Allocate the next integer
+  after the highest id across HOT ∪ `adr/`. Ordering is always **numeric**, never lexical.
+- **The `## AD-NNN — <title>` heading is strict.** Use the em dash ` — `. A non-canonical `## ` heading
+  is a loud parse failure — the store never silently glues an entry to the previous body.
+- **`slug` is cosmetic and frozen at creation** (`slugify(title)`); the `AD-NNN` prefix is the key. A
+  retitle never renames the file.
+- The block is preserved **verbatim** when it is archived, so write it as you want it to persist.
+
+## Lifecycle (the only mutable part after acceptance)
+
+The **body is immutable** once accepted — only lifecycle changes. Express supersession in the body of
+the **new** ADR; governance is then computed automatically (no predecessor-file edit is required):
+
+| Body form (in the newer ADR)     | Effect                                                            |
+|----------------------------------|------------------------------------------------------------------|
+| `Supersedes [[AD-NNN]]`          | retires AD-NNN (when the citing ADR is `accepted`)               |
+| `Superseded by [[AD-NNN]]`       | marks this ADR retired by AD-NNN                                  |
+| `Amended by [[AD-NNN]]`          | marks this ADR amended (also drops it from the governing heads)  |
+
+- **`status`** is the leading word of `**Status:**`, lowercased (`accepted` / `superseded` /
+  `amended` / `deprecated`). A **missing** `**Status:**` line defaults to `accepted` (the in-force
+  default). Only `accepted` ADRs govern.
+- When an ADR is archived, its record frontmatter backfills `status`, `date`, `supersedes`, and
+  `supersededBy` from these body forms — you do not maintain the frontmatter by hand.
+
+## Retrieval (never through an O(n) artifact)
+
+- **by id** → the deterministic filename `docs/ai/adr/AD-NNN-*.md` (glob).
+- **by topic** → `grep` the flat `docs/ai/adr/` tree.
+- **by lifecycle** → the two-way `supersedes` / `supersededBy` frontmatter + the `[[AD-NNN]]` chain;
+  `ls docs/ai/adr/` IS the log.
+
+## Commands
+
+- `node scripts/archive-decisions.mjs` — rotate: explode the oldest HOT entries beyond the cap into
+  `adr/` records, then regenerate the navigator + `docs/ai/index.md`.
+- `node scripts/archive-decisions.mjs --write-navigator` — regenerate `docs/ai/adr/log.md` (and the
+  index) after authoring an ADR or editing a supersession, so `--check` stays green.
+- `node scripts/archive-decisions.mjs --check` — verify HOT cap + store integrity + navigator freshness.

package/references/templates/decisions.md

@@ -9,7 +9,11 @@ maxLines: 500
 
 # Architecture Decision Records (ADRs)
 
-> Every significant choice that has long-term consequences. Newest at the bottom. Link related ADRs with `[[AD-XXX]]`.
+> The **HOT window** of Architecture Decision Records — every significant choice with long-term
+> consequences, newest at the bottom. Link related ADRs with `[[AD-XXX]]`; retrieval is by the
+> `AD-NNN` id (filename), grep over the flat store, or the `[[AD-NNN]]` supersession chain.
+
+> **Archive:** older ADRs are stored one immutable file per record under [`adr/`](./adr/) — see the active-set navigator [`adr/log.md`](./adr/log.md). `archive-decisions.mjs` explodes the oldest entries beyond this window automatically; no cap is ever raised and there is no monolithic ledger.
 
 ## AD-001 — Adopt AI-agent memory system (`docs/ai/`)
 
@@ -18,27 +22,12 @@ maxLines: 500
 
 **Context.** Multi-session AI work loses context between runs. Without a structured handover, each new session re-reads code, re-discovers decisions, and repeats past mistakes.
 
-**Decision.** Adopt a Memory Map in `AGENTS.md` (entry point — the cross-agent standard; tool aliases like `CLAUDE.md` symlink to it) + structured files under `docs/ai/`. Define three protocols (Start / During / Complete). Enforce frontmatter caps + index freshness + 3-tier archive via a pre-commit hook. Deployed via the `agent-workflow-kit` skill.
+**Decision.** Adopt a Memory Map in `AGENTS.md` (entry point — the cross-agent standard; tool aliases like `CLAUDE.md` symlink to it) + structured files under `docs/ai/`. Define three protocols (Start / During / Complete). Enforce frontmatter caps + index freshness + a one-file-per-ADR archive via a pre-commit hook. Deployed via the `agent-workflow-kit` skill.
 
-**Rationale.** Single entry + structured spec files = constant boot-up cost regardless of project size. ADRs prevent litigating the same decision twice. `pages/<page>.md` keeps behaviour canonical (docs > assumptions). Caps + archive keep files scannable as history grows.
+**Rationale.** Single entry + structured spec files = constant boot-up cost regardless of project size. ADRs prevent litigating the same decision twice. `pages/<page>.md` keeps behaviour canonical (docs > assumptions). Caps + one-file-per-ADR archival keep every record scannable as the decision history grows without bound.
 
 **Consequences.**
 - ➕ Faster session start, less drift between agents.
 - ➕ ADRs as institutional memory; honest `known_issues.md`.
 - ➖ Discipline cost: docs updated alongside code.
 - ➖ A set of markdown files + scripts to maintain.
-
----
-
-## AD-002 — {{Next decision}}
-
-**Date:** {{DATE}}
-**Status:** Proposed / Accepted / Superseded
-
-**Context.** {{...}}
-**Decision.** {{...}}
-**Consequences.** {{...}}
-
----
-
-> When this file nears ~90% of its cap, move the oldest Accepted/Superseded ADRs to `decisions-archive.md` (keep the IDs + a one-line pointer here) and record the split. Bumping the cap instead of splitting is a conscious exception, justified in an ADR.

package/tools/cheap-agents.mjs

@@ -34,7 +34,7 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 export const AGENTS_DIR = '.claude/agents';
 export const CLAUDE_DIR = '.claude';
 export const WORKFLOW_STAMP = 'docs/ai/.workflow-version';
-export const EXPECTED_WORKFLOW_VERSION = '1.3.0';
+export const EXPECTED_WORKFLOW_VERSION = '2.0.0';
 export const BUNDLED_AGENTS_DIR = resolve(HERE, '..', 'references', 'agents');
 
 const EXIT_OK = 0;

package/tools/commands.mjs

@@ -70,6 +70,13 @@ const CATALOG = [
     kind: GUARDED,
     oneLine: 'Remove only what setup placed; it never deletes your notes and always previews before changing anything.',
   },
+  {
+    key: 'migrate-adr-store',
+    invocation: invocationOf('migrate-adr-store'),
+    group: 'Lifecycle',
+    kind: GUARDED,
+    oneLine: 'Migrate an older project’s ADR store to the one-file-per-ADR layout; it previews first, snapshots, and never commits.',
+  },
   {
     key: 'status',
     invocation: invocationOf('status'),
@@ -221,7 +228,7 @@ export const kindOf = (key) => byKey.get(key)?.kind ?? null;
 // and trailing args are ignored. Precise semantics:
 //   undefined / null / '' / whitespace-only / the exact bare invocation → 'bootstrap'
 //   a known first token (upgrade/status/setup/backends/recipes/procedures/velocity/agents/hook/
-//     gates/set-recipe/uninstall/help) → that mode
+//     gates/set-recipe/uninstall/migrate-adr-store/help) → that mode
 //   anything else (unrecognized / ambiguous) → 'help'  (read-only — NEVER a writer/guarded mode)
 export const routeInvocation = (token) => {
   if (token == null) return BARE_INVOCATION_MODE;

package/tools/family-registry.mjs

@@ -325,9 +325,31 @@ 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-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) => {
+    try {
+      return exists(join(dir, rel));
+    } catch {
+      return false;
+    }
+  };
+  if (DECISIONS_MONOLITHS.some(safe)) return 'old';
+  if (safe(ADR_STORE_DIR)) return 'migrated';
+  return 'none';
+};
+
 // surveyProject → the deploy axis for a target project dir: the per-member deployment stamps, whether
-// docs/ai/ exists, and whether the hidden-mode fence is present. Pure (fs reads only, all injectable),
-// no git subprocess — the read-only `status` view must never mutate or spawn anything.
+// docs/ai/ exists, the ADR-store layout, and whether the hidden-mode fence is present. Pure (fs reads
+// only, all injectable), no git subprocess — the read-only `status` view must never mutate or spawn.
 export const surveyProject = (projectDir, deps = {}) => {
   const exists = deps.exists ?? existsSync;
   const dir = resolve(projectDir);
@@ -342,7 +364,7 @@ export const surveyProject = (projectDir, deps = {}) => {
     }
   })();
   const deployed = stamps.some((s) => s.version != null) || docsAiPresent;
-  return { dir, deployed, docsAiPresent, hiddenFence: hasHiddenFence(dir, deps), stamps };
+  return { dir, deployed, docsAiPresent, adrLayout: surveyAdrLayout(dir, exists), hiddenFence: hasHiddenFence(dir, deps), stamps };
 };
 
 // ── report ───────────────────────────────────────────────────────────────────────
@@ -579,6 +601,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
       // 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

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+// migrate-adr-store.mjs — the consent-gated, opt-in migration of an EXISTING consumer's docs/ai from
+// the retired 3-tier ADR cascade (HOT decisions.md → WARM/COLD monoliths) to the one-file-per-ADR
+// store (HOT decisions.md + docs/ai/adr/AD-NNN-slug.md records + the docs/ai/adr/log.md navigator).
+// Reached ONLY through the `migrate-adr-store` mode (SKILL.md), NEVER auto: a normal upgrade never
+// installs the new-scheme rotator into an un-migrated consumer — the new rotator arrives ONLY here,
+// 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).
+//   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).
+//   3. FORCE-REFRESH — overwrite the consumer's deployed enforcement scripts (the DIRECTIONAL subset:
+//              only kit-canon basenames the consumer's scripts/ already has) with this kit's bundled
+//              copies, so their ongoing pre-commit gates run the NEW rotator + the NEW collapse rule.
+//              A locally-edited script is snapshotted (step 2) before it is overwritten — never
+//              silently clobbered — and the dry-run preview names every script that differs.
+//   4. MIGRATE — run the (new-scheme) rotator's conservation-checked --migrate --apply against the
+//              project root: explode the monoliths into adr/ records, retire them, regenerate the
+//              navigator + docs/ai/index.md. Idempotent / crash-resumable.
+//
+// Write discipline: preview (--dry-run) is the DEFAULT and writes NOTHING; --apply performs the
+// migration. It NEVER commits. Exit codes: 0 done / dry-run / no-op; 1 precondition STOP (no
+// deployment, no writable snapshot base, a failed migration); 2 usage. Dependency-free, Node >= 18.
+// No side effects on import.
+
+import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, writeFileSync, chmodSync } from 'node:fs';
+import { join, resolve, dirname, relative, isAbsolute } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { writeContainedFileAtomic, assertDocsAiDeployment } from './atomic-write.mjs';
+import {
+  monolithsPresent,
+  HOT_REL,
+  WARM_REL,
+  COLD_REL,
+  ADR_DIR_REL,
+  runCli as runArchiveDecisions,
+} from '../references/scripts/archive-decisions.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const KIT_ROOT = resolve(HERE, '..');
+const KIT_SCRIPTS = join(KIT_ROOT, 'references', 'scripts');
+const CONSUMER_SCRIPTS_REL = 'scripts';
+const SNAPSHOT_PREFIX = 'agent-workflow-adr-migration-snapshot';
+
+const EXIT_OK = 0;
+const EXIT_PRECONDITION = 1;
+const EXIT_USAGE = 2;
+
+export const MIGRATE_ADR_STORE_STOP = 'MIGRATE_ADR_STORE_STOP';
+const stop = (message) =>
+  Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'MigrateAdrStoreStop', code: MIGRATE_ADR_STORE_STOP, exitCode: EXIT_PRECONDITION });
+const usageFail = (message) =>
+  Object.assign(new Error(`[agent-workflow-kit] ${message}`), { exitCode: EXIT_USAGE });
+
+const USAGE = `usage: migrate-adr-store [--dry-run | --apply] [--cwd <dir>] [--help]
+
+Opt-in migration of a project's docs/ai from the retired 3-tier ADR cascade to the one-file-per-ADR
+store. Default is --dry-run: prints the migration plan (monoliths to retire, scripts to refresh, the
+conservation proof) and writes NOTHING. --apply snapshots, force-refreshes the enforcement scripts,
+then runs the conservation-checked migration. It NEVER commits — review the tree and commit yourself.`;
+
+// The mutually-exclusive dry-run/apply parse (a consent-gated writer never lets a later flag silently
+// decide whether it mutates) + --cwd, cloned from the seed-gates writer contract.
+export const parseArgs = (argv) => {
+  const parsed = argv.reduce(
+    (acc, a, i) => {
+      if (acc.skip) return { ...acc, skip: false };
+      if (a === '--help' || a === '-h') return { ...acc, help: true };
+      if (a === '--dry-run') {
+        if (acc.apply === true) throw usageFail('--dry-run and --apply are mutually exclusive — pick one');
+        return { ...acc, apply: false, dryRunExplicit: true };
+      }
+      if (a === '--apply') {
+        if (acc.dryRunExplicit) throw usageFail('--dry-run and --apply are mutually exclusive — pick one');
+        return { ...acc, apply: true };
+      }
+      if (a === '--cwd') {
+        const value = argv[i + 1];
+        if (value === undefined || value.startsWith('-')) throw usageFail('--cwd needs a value: --cwd <dir>');
+        return { ...acc, cwd: value, skip: true };
+      }
+      throw usageFail(`unknown argument "${a}"\n${USAGE}`);
+    },
+    { apply: false, dryRunExplicit: false, cwd: undefined, help: false, skip: false },
+  );
+  return { apply: parsed.apply === true, cwd: parsed.cwd, help: parsed.help };
+};
+
+// The DIRECTIONAL force-refresh set (Decision 12/13): a kit-canon enforcement script whose basename is
+// ALSO present in the consumer's scripts/ — never ADD a script the consumer lacks, never touch a
+// root-only/non-canon file. Returns [{ name, canon, dst, differs }] for every refresh candidate.
+export const planScriptRefresh = (cwd, deps = {}) => {
+  const exists = deps.exists ?? existsSync;
+  const read = deps.read ?? readFileSync;
+  const kitScripts = deps.kitScripts ?? KIT_SCRIPTS;
+  const consumerScripts = join(cwd, CONSUMER_SCRIPTS_REL);
+  const out = [];
+  for (const name of readdirSync(kitScripts).sort()) {
+    const canon = join(kitScripts, name);
+    if (!statSync(canon).isFile()) continue;
+    const dst = join(consumerScripts, name);
+    if (!exists(dst)) continue; // directional: the consumer does not deploy this script — never add it
+    const differs = read(canon, 'utf8') !== read(dst, 'utf8');
+    out.push({ name, canon, dst, differs });
+  }
+  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;
+};
+
+// A path is INSIDE the work tree (stageable) when cwd contains it. The git dir is EXEMPT — it lives
+// under cwd but git never stages its own contents (uncommittable by construction, the Decision-5 basis).
+const isUnder = (child, parent) => {
+  const rel = relative(parent, child);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+};
+
+// The ordered snapshot bases that are provably NOT stageable: the git dir first (always safe), then the
+// fallback base ONLY when its snapshot dir lands OUTSIDE cwd (else it is in the work tree and could be
+// committed — reject it; codex R1 minor). Returns [{ base, dir, viaGitDir }] (possibly empty).
+const snapshotBases = (cwd, stamp, gitDir, fallbackBase) => {
+  const bases = [];
+  if (gitDir) bases.push({ base: gitDir, dir: resolve(gitDir, `${SNAPSHOT_PREFIX}-${stamp}`), viaGitDir: true });
+  const fallbackDir = resolve(fallbackBase, `${SNAPSHOT_PREFIX}-${stamp}`);
+  if (!isUnder(fallbackDir, resolve(cwd))) bases.push({ base: fallbackBase, dir: fallbackDir, viaGitDir: false });
+  return bases;
+};
+
+// The pre-migration snapshot dir chosen for the preview: the first out-of-tree base (git dir, else a
+// fallback proven outside cwd), or { dir: null } when none is available. Pure — creates nothing.
+export const resolveSnapshotDir = (cwd, stamp, deps = {}) => {
+  const spawn = deps.spawnSync ?? spawnSync;
+  const fallbackBase = deps.snapshotFallbackBase ?? tmpdir();
+  const gitDir = gitDirOf(cwd, spawn);
+  const chosen = snapshotBases(cwd, stamp, gitDir, fallbackBase)[0] ?? null;
+  return chosen ? { base: chosen.base, gitDir, dir: chosen.dir, viaGitDir: chosen.viaGitDir } : { base: null, gitDir, dir: null, viaGitDir: false };
+};
+
+// Write the durable snapshot (decisions.md + both monoliths + the pre-refresh consumer scripts). Tries
+// the git dir first, then an out-of-tree fallback; fails LOUD if none is available/writable (Decision 5).
+// Paths are flattened (/ → __) exactly like the rotator's own snapshot.
+export const writeSnapshot = (cwd, refresh, stamp, deps = {}) => {
+  const spawn = deps.spawnSync ?? spawnSync;
+  const read = deps.read ?? readFileSync;
+  const exists = deps.exists ?? existsSync;
+  const mkdir = deps.mkdir ?? ((p) => mkdirSync(p, { recursive: true }));
+  const write = deps.write ?? ((p, b) => writeFileSync(p, b, 'utf8'));
+  const fallbackBase = deps.snapshotFallbackBase ?? tmpdir();
+  const gitDir = gitDirOf(cwd, spawn);
+  const bases = snapshotBases(cwd, stamp, gitDir, fallbackBase);
+  if (bases.length === 0) {
+    throw stop(`refusing to migrate: no out-of-tree snapshot location (not a git repo, and the fallback would land inside the work tree ${cwd}) — a durable, non-stageable pre-migration snapshot is mandatory`);
+  }
+
+  const files = [];
+  for (const rel of [HOT_REL, WARM_REL, COLD_REL]) {
+    const abs = join(cwd, rel);
+    if (exists(abs)) files.push({ rel, content: read(abs, 'utf8') });
+  }
+  for (const { name, dst } of refresh) {
+    if (exists(dst)) files.push({ rel: `${CONSUMER_SCRIPTS_REL}/${name}`, content: read(dst, 'utf8') });
+  }
+
+  let lastErr = null;
+  for (const { dir, viaGitDir } of bases) {
+    try {
+      mkdir(dir);
+      for (const { rel, content } of files) write(resolve(dir, rel.replace(/[/\\]/g, '__')), content);
+      return { dir, viaGitDir, fileCount: files.length };
+    } catch (err) {
+      lastErr = err;
+    }
+  }
+  throw stop(`refusing to migrate: no writable snapshot location (${lastErr && lastErr.message}) — a durable pre-migration snapshot is mandatory`);
+};
+
+// Overwrite each refresh target with the kit canon, atomically, preserving the canon's exec bit.
+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) {
+    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
+  }
+};
+
+export const main = (argv = process.argv.slice(2), deps = {}) => {
+  const log = deps.log ?? console.log;
+  const error = deps.error ?? console.error;
+  const runMigrate = deps.runArchiveDecisions ?? runArchiveDecisions;
+  const stamp = deps.stamp ?? new Date().toISOString().replace(/[:.]/g, '-');
+  try {
+    const args = parseArgs(argv);
+    if (args.help) {
+      log(USAGE);
+      return EXIT_OK;
+    }
+    const cwd = resolve(args.cwd ?? process.cwd());
+    assertDocsAiDeployment(cwd, deps, { stop, noun: 'the ADR store', rel: 'the docs/ai ADR store' });
+
+    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;
+    }
+
+    const refresh = planScriptRefresh(cwd, deps);
+    const drifted = refresh.filter((r) => r.differs);
+
+    if (!args.apply) {
+      const preview = resolveSnapshotDir(cwd, stamp, deps);
+      log('[migrate-adr-store] --dry-run — no files will be changed. Planned migration:');
+      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(', ')})` : ''}`);
+      log('  then the conservation-checked rotation:');
+      // Surface the rotation's own exit code (codex R1 major): 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.
+      const code = runMigrate(['--migrate'], { root: cwd, log: (m) => log(`    ${m}`), logError: (m) => error(`    ${m}`) });
+      if (code !== EXIT_OK) {
+        throw stop(`the dry-run rotation would not conserve every ADR (exit ${code}) — NOT safe to --apply; fix the reported problem, then re-run.`);
+      }
+      // A null preview means --apply would refuse (no out-of-tree snapshot base) — never green-light it
+      // (codex R2 minor: a dry-run go-ahead must not send the user to an apply that will STOP).
+      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('Run `/agent-workflow-kit migrate-adr-store` again with --apply to perform it (it never commits).');
+      return EXIT_OK;
+    }
+
+    // Pre-flight: validate the rotation on a dry-run (conservation + store integrity) BEFORE any
+    // mutation, so a failure aborts having touched nothing — no snapshot, no refreshed scripts, no
+    // half-migrated tree. The error surfaces on logError; the plan itself is suppressed (already shown).
+    const preflight = runMigrate(['--migrate'], { root: cwd, log: () => {}, logError: error });
+    if (preflight !== EXIT_OK) {
+      throw stop(`the migration would not conserve every ADR (dry-run exit ${preflight}) — refusing to touch the tree; fix the reported problem, then re-run.`);
+    }
+
+    const snapshot = writeSnapshot(cwd, refresh, stamp, deps);
+    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('  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;
+  } catch (err) {
+    error(err.message);
+    return err.exitCode ?? EXIT_PRECONDITION;
+  }
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) process.exitCode = main();

package/tools/renderers.mjs

@@ -77,6 +77,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') {
+    lines.push(`  ${pad('ADR store', STAMP_COL)}old layout — run /agent-workflow-kit migrate-adr-store`);
+  }
   if (p.visibility) {
     const v = p.visibility.error ? `error: ${p.visibility.error}` : p.visibility.phrase;
     lines.push(`  ${pad('visibility', STAMP_COL)}${v}`);