@sabaiway/agent-workflow-memory 1.11.1 → 2.0.0

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

@@ -15,6 +15,8 @@
 //
 // CLI overrides:
 //   --today=YYYY-MM-DD (default today UTC) — useful for tests / reproducible runs
+//   --root=<dir>       run against another project root (default this deployment) — the ADR-rotation
+//                      hook passes it so a rotation regenerates the right project's index
 //   --quiet            print only failures (and final summary)
 
 import { readFile, writeFile, readdir, stat } from 'node:fs/promises';
@@ -28,6 +30,12 @@ const ROOT = resolve(__dirname, '..');
 const DOCS_DIR = resolve(ROOT, 'docs/ai');
 const INDEX_PATH = resolve(DOCS_DIR, 'index.md');
 
+// Root-parameterized (BUGFREE-3 / AD-049, item (h)): the module ROOT constants are the CLI DEFAULT
+// (this deployment's own root); `--root=<dir>` and the exported `regenerateIndex(root, today)`
+// override them so the ADR-rotation hook (archive-decisions.mjs) and hermetic tests can regenerate
+// an arbitrary root's index without ever touching the real repo tree.
+const pathsFor = (root) => ({ root, docsDir: resolve(root, 'docs/ai'), indexPath: resolve(root, 'docs/ai/index.md') });
+
 const MS_PER_DAY = 24 * 60 * 60 * 1000;
 
 // Project-name + footer links for the index are auto-discovered (no hardcoding):
@@ -56,18 +64,18 @@ const walkForName = async (dir, name, acc = [], depth = 0) => {
   return acc;
 };
 
-export const discoverMeta = async () => {
-  let projectName = basename(ROOT);
+export const discoverMeta = async (root = ROOT) => {
+  let projectName = basename(root);
   try {
-    const pkg = JSON.parse(await readFile(resolve(ROOT, 'package.json'), 'utf8'));
+    const pkg = JSON.parse(await readFile(resolve(root, 'package.json'), 'utf8'));
     if (pkg.name) projectName = pkg.name;
   } catch {
     /* no package.json — keep dir basename */
   }
-  const agentsFiles = await walkForName(ROOT, 'AGENTS.md');
-  const claudeFiles = await walkForName(ROOT, 'CLAUDE.md');
-  const rootAgents = resolve(ROOT, 'AGENTS.md');
-  const rootClaude = resolve(ROOT, 'CLAUDE.md');
+  const agentsFiles = await walkForName(root, 'AGENTS.md');
+  const claudeFiles = await walkForName(root, 'CLAUDE.md');
+  const rootAgents = resolve(root, 'AGENTS.md');
+  const rootClaude = resolve(root, 'CLAUDE.md');
   // A subdir typically holds AGENTS.md plus a CLAUDE.md symlink to it — list each
   // dir once (prefer AGENTS.md, drop its sibling CLAUDE.md alias).
   const agentsDirs = new Set(agentsFiles.map((file) => dirname(resolve(file))));
@@ -78,12 +86,12 @@ export const discoverMeta = async () => {
     ),
   ];
   const hierarchicalLinks = nestedFiles
-    .map((file) => relative(ROOT, file))
+    .map((file) => relative(root, file))
     .sort()
     .map((rel) => `[\`${rel}\`](../../${rel})`);
   let onDemandLinks = [];
   try {
-    const skillDirs = await readdir(resolve(ROOT, '.agents/skills'), { withFileTypes: true });
+    const skillDirs = await readdir(resolve(root, '.agents/skills'), { withFileTypes: true });
     onDemandLinks = skillDirs
       .filter((dirent) => dirent.isDirectory() && /-(patterns|commands)$/.test(dirent.name))
       .map((dirent) => dirent.name)
@@ -97,16 +105,17 @@ export const discoverMeta = async () => {
 
 const parseArgs = (argv) => {
   const flags = { report: false, writeIndex: false, checkIndex: false, quiet: false };
-  const opts = { today: null };
+  const opts = { today: null, root: null };
   for (const arg of argv.slice(2)) {
     if (arg === '--report') flags.report = true;
     else if (arg === '--write-index') flags.writeIndex = true;
     else if (arg === '--check-index') flags.checkIndex = true;
     else if (arg === '--quiet') flags.quiet = true;
     else if (arg.startsWith('--today=')) opts.today = arg.slice('--today='.length);
+    else if (arg.startsWith('--root=')) opts.root = arg.slice('--root='.length);
     else if (arg === '--help' || arg === '-h') {
       console.log(
-        'Usage: check-docs-size.mjs [--report|--write-index|--check-index] [--today=YYYY-MM-DD] [--quiet]',
+        'Usage: check-docs-size.mjs [--report|--write-index|--check-index] [--today=YYYY-MM-DD] [--root=<dir>] [--quiet]',
       );
       process.exit(0);
     } else {
@@ -161,11 +170,11 @@ export const computeToday = (todayStr) =>
     ? new Date(`${todayStr}T00:00:00Z`)
     : new Date(new Date().toISOString().slice(0, 10) + 'T00:00:00Z');
 
-export const inspectFile = async (filePath, today) => {
+export const inspectFile = async (filePath, today, root = ROOT) => {
   const text = await readFile(filePath, 'utf8');
   const lineCount = text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
   const fm = parseFrontmatter(text);
-  const rel = relative(ROOT, filePath);
+  const rel = relative(root, filePath);
 
   if (!fm) {
     return {
@@ -261,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).
@@ -268,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')}`
@@ -301,24 +340,41 @@ export const checkIndexFreshness = (rows, onDiskText, meta = {}) => {
   return { fresh: expected === onDiskText, expected };
 };
 
-const writeIndex = async (rows, today, meta) => {
+const writeIndex = async (rows, today, meta, indexPath = INDEX_PATH) => {
   const body = buildIndex(rows, today.toISOString().slice(0, 10), meta);
-  await writeFile(INDEX_PATH, body, 'utf8');
+  await writeFile(indexPath, body, 'utf8');
+};
+
+// regenerateIndex(root, todayStr) — the ONE reused generator, root-parameterized (item (h)). It runs
+// the SAME walk → inspect → discoverMeta → writeIndex pipeline as `--write-index`, against `root`
+// (default this deployment). The ADR-rotation hook reaches it via the CLI (`--write-index --root=…`);
+// hermetic tests call it directly. `todayStr` is 'YYYY-MM-DD' (null → today). Returns the written
+// index path + row count. No second index implementation exists.
+export const regenerateIndex = async (root, todayStr = null) => {
+  const { docsDir, indexPath } = pathsFor(root);
+  const today = computeToday(todayStr);
+  const files = (await walkMarkdownFiles(docsDir)).sort();
+  const inspected = await Promise.all(files.map((f) => inspectFile(f, today, root)));
+  const rows = inspected.map(formatRow);
+  const meta = await discoverMeta(root);
+  await writeIndex(rows, today, meta, indexPath);
+  return { indexPath, files: rows.length };
 };
 
 const main = async () => {
   const { flags, opts } = parseArgs(process.argv);
+  const { root, docsDir, indexPath } = pathsFor(opts.root ? resolve(opts.root) : ROOT);
   const today = computeToday(opts.today);
-  const files = (await walkMarkdownFiles(DOCS_DIR)).sort();
-  const inspected = await Promise.all(files.map((f) => inspectFile(f, today)));
+  const files = (await walkMarkdownFiles(docsDir)).sort();
+  const inspected = await Promise.all(files.map((f) => inspectFile(f, today, root)));
   const rows = inspected.map(formatRow);
 
-  const meta = flags.writeIndex || flags.checkIndex ? await discoverMeta() : null;
+  const meta = flags.writeIndex || flags.checkIndex ? await discoverMeta(root) : null;
 
   if (flags.writeIndex) {
-    await writeIndex(rows, today, meta);
-    console.log(`Wrote ${relative(ROOT, INDEX_PATH)}`);
-    const after = await stat(INDEX_PATH);
+    await writeIndex(rows, today, meta, indexPath);
+    console.log(`Wrote ${relative(root, indexPath)}`);
+    const after = await stat(indexPath);
     if (after.size === 0) {
       console.error('index.md was written empty');
       process.exit(2);
@@ -326,16 +382,16 @@ const main = async () => {
   }
 
   if (flags.checkIndex) {
-    const onDisk = existsSync(INDEX_PATH) ? await readFile(INDEX_PATH, 'utf8') : null;
+    const onDisk = existsSync(indexPath) ? await readFile(indexPath, 'utf8') : null;
     const { fresh } = checkIndexFreshness(rows, onDisk, meta);
     if (!fresh) {
       console.error(
-        `[check-docs-size] FAIL: ${relative(ROOT, INDEX_PATH)} is stale (out of sync with source frontmatter). Regenerate the index (--write-index) and commit the regenerated file.`,
+        `[check-docs-size] FAIL: ${relative(root, indexPath)} is stale (out of sync with source frontmatter). Regenerate the index (--write-index) and commit the regenerated file.`,
       );
       process.exit(1);
     }
     console.log(
-      `[check-docs-size] OK — ${relative(ROOT, INDEX_PATH)} is in sync with source frontmatter.`,
+      `[check-docs-size] OK — ${relative(root, indexPath)} is in sync with source frontmatter.`,
     );
     return;
   }

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

@@ -1,8 +1,11 @@
 import { describe, it, beforeEach, afterEach } from 'node:test';
 import { expect } from './_expect-shim.mjs';
-import { mkdtemp, writeFile, rm } from 'node:fs/promises';
+import { mkdtemp, writeFile, mkdir, readFile, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import {
   parseFrontmatter,
   parseStaleAfter,
@@ -11,6 +14,7 @@ import {
   buildIndex,
   checkIndexFreshness,
   walkMarkdownFiles,
+  regenerateIndex,
 } from './check-docs-size.mjs';
 
 describe('parseFrontmatter', () => {
@@ -160,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 = [
@@ -202,3 +261,71 @@ describe('checkIndexFreshness', () => {
     expect(checkIndexFreshness(rows, onDisk).fresh).toBe(true);
   });
 });
+
+// ── (h) — root-parameterization: the ADR-rotation hook regenerates ANOTHER root's index ────
+// The generator's module ROOT is the CLI default only; --root / regenerateIndex(root) target an
+// arbitrary tree so the rotation hook (and hermetic tests) never touch the real repo.
+describe('root parameterization (item (h))', () => {
+  let root;
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'check-docs-root-'));
+    await mkdir(join(root, 'docs', 'ai'), { recursive: true });
+  });
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  const seedDoc = (name, extra = '') =>
+    writeFile(join(root, 'docs', 'ai', name), `---\ntype: reference\nlastUpdated: 2026-07-08\nscope: permanent\nstaleAfter: 30d\nowner: none\nmaxLines: 100\n---\n\n# ${name}\n${extra}`);
+
+  it('inspectFile computes the file path RELATIVE to the passed root (not the module ROOT)', async () => {
+    await seedDoc('handover.md');
+    const result = await inspectFile(join(root, 'docs', 'ai', 'handover.md'), computeToday('2026-07-08'), root);
+    expect(result.path).toBe('docs/ai/handover.md');
+  });
+
+  it('regenerateIndex(root, today) writes THAT root\'s docs/ai/index.md from its frontmatter', async () => {
+    await seedDoc('a.md');
+    await seedDoc('b.md');
+    const res = await regenerateIndex(root, '2026-07-08');
+    expect(res.indexPath).toBe(join(root, 'docs', 'ai', 'index.md'));
+    expect(existsSync(res.indexPath)).toBe(true);
+    const index = await readFile(res.indexPath, 'utf8');
+    expect(index).toMatch(/lastUpdated: 2026-07-08/); // header date is the argument
+    expect(index).toMatch(/a\.md/);
+    expect(index).toMatch(/b\.md/);
+    expect(index).not.toMatch(/\[`index\.md`\]/); // the index never lists itself
+  });
+
+  it('a re-run with unchanged sources is byte-identical (deterministic, --check-index safe)', async () => {
+    await seedDoc('a.md');
+    const first = await regenerateIndex(root, '2026-07-08');
+    const bytesA = await readFile(first.indexPath, 'utf8');
+    await regenerateIndex(root, '2026-07-08');
+    const bytesB = await readFile(first.indexPath, 'utf8');
+    expect(bytesB).toBe(bytesA);
+  });
+
+  // The CLI entry (main) over --root — a subprocess smoke so the --help usage + the --check-index
+  // fresh/stale branches (root-parameterized) are exercised end-to-end.
+  const SCRIPT = fileURLToPath(new URL('./check-docs-size.mjs', import.meta.url));
+  const runCli = (args) => spawnSync(process.execPath, [SCRIPT, ...args], { encoding: 'utf8' });
+
+  it('--help prints the usage (naming --root) and exits 0', () => {
+    const r = runCli(['--help']);
+    expect(r.status).toBe(0);
+    expect(r.stdout).toMatch(/--root=/);
+  });
+
+  it('--check-index --root: a fresh index is OK (exit 0); a drifted one is stale (exit 1)', async () => {
+    await seedDoc('a.md');
+    expect(runCli(['--write-index', `--root=${root}`]).status).toBe(0);
+    const fresh = runCli(['--check-index', `--root=${root}`]);
+    expect(fresh.status).toBe(0);
+    expect(fresh.stdout).toMatch(/in sync/);
+    await seedDoc('b.md'); // a new source row drifts the on-disk index
+    const stale = runCli(['--check-index', `--root=${root}`]);
+    expect(stale.status).toBe(1);
+    expect(stale.stderr).toMatch(/stale/);
+  });
+});

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/agent_rules.md

@@ -55,6 +55,7 @@ Before proposing changes or committing, review against:
 ### 2.2. Clean Code
 - **No magic literals** — extract string/numeric constants to named consts at module level.
 - **DRY** — no duplicated logic.
+- **Minimal comments (a BASELINE this project may tighten)** — if this project sets a stricter rule (e.g. comments forbidden entirely), that stricter rule ALWAYS wins; this is only a floor. Otherwise comment only where vitally necessary (a non-obvious invariant, a fail-closed rationale, a subtle edge). Make the code self-explaining first — clear variable/function names and compact-but-unambiguous test descriptions replace most comments; never restate what the code already says.
 
 ### 2.3. Strict Compliance
 - Only `const` (no `let`); no classes — pure functions, closures, modules.

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-memory` substrate (standalone, or as part of the agent-workflow family).
+**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-memory` substrate (standalone, or as part of the agent-workflow family).
 
-**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/references/templates/verification-profile.json

@@ -0,0 +1,10 @@
+{
+  "_README": "Optional per-project VERIFICATION PROFILE for the fold-completeness gate (the language-independence contract). DELETE this file to reproduce the exact default behaviour (V8 line coverage + node:test TAP on stdout) — an absent profile is fully supported. Present, it GENERALIZES three inputs so a consumer on another language/runner can drive the same gate: (1) coverage.kind is \"v8\" (default) or \"lcov\" — with lcov, set coverage.lcovPath to where your suite leaves an LCOV file; (2) singleTest.argv is the shell-free command template for probing ONE test (placeholders {file} and {pattern} are required; a file-based resultFormat also requires {resultPath}), and singleTest.resultFormat is \"tap-stdout\" (default), \"tap-file\", or \"junit-xml\"; (3) findings.sarifPath (optional) points at a SARIF file for advisory-only findings (never gate-blocking). The suite COMMAND is NOT declared here — it stays your docs/ai/gates.json unit-tests gate (so the fold run and the gate share command-identity). Every DECLARED path (coverage.lcovPath, findings.sarifPath) MUST be gitignored or outside the repo (a symlink is refused): an in-tree, non-ignored file the suite writes would move the review fingerprint. Env knobs still override (AW_FOLD_SUITE_CMD / AW_FOLD_BOUND_CMD / AW_FOLD_RESULTS). Strict JSON — no comments.",
+  "schema": 1,
+  "coverage": { "kind": "v8" },
+  "singleTest": {
+    "argv": ["node", "--test", "--test-reporter", "tap", "--test-name-pattern={pattern}", "{file}"],
+    "resultFormat": "tap-stdout"
+  },
+  "findings": {}
+}

package/scripts/stamp-takeover.mjs

@@ -6,7 +6,7 @@
 // The deployment lineage is a SINGLE shared sequence; its current head is LINEAGE_HEAD.
 // Both `.memory-version` and the kit-fallback `.workflow-version` track THAT sequence —
 // never their package versions. So this substrate's package may be 1.0.0 while the stamp
-// it writes is the lineage head (1.3.0 today).
+// it writes is the lineage head (2.0.0 today).
 //
 // `decideTakeover` is a PURE function (stamp state in → action out) so the state machine is
 // unit-testable per row. `applyTakeover` is the thin fs wrapper; stamp writes are ATOMIC
@@ -22,7 +22,7 @@ import { pathToFileURL } from 'node:url';
 
 // The shared agent-workflow deployment-lineage head. Bumped only when a project-migration
 // changes the deployed docs/ai structure — NOT on a packaging-only release.
-export const LINEAGE_HEAD = '1.3.0';
+export const LINEAGE_HEAD = '2.0.0';
 
 const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)$/;