@sabaiway/agent-workflow-kit 1.38.0 → 1.40.0

package/references/scripts/archive-decisions.mjs

@@ -10,7 +10,8 @@
 // oldest (lowest AD id, top of file) first; an entry's lines move verbatim.
 //
 // Modes:
-//   (default)   rotate, mutate files in place (only when something is over cap)
+//   (default)   rotate, mutate files in place (only when something is over cap), then regenerate
+//               docs/ai/index.md so the rotation never leaves the index stale (item (h))
 //   --dry-run   print the planned move-set, change nothing
 //   --check     report per-tier lines/cap; exit 1 if any tier is over its cap
 //   --today=YYYY-MM-DD  pin the lastUpdated stamp (tests / reproducible runs)
@@ -41,10 +42,40 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { spawnSync } from 'node:child_process';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_ROOT = resolve(__dirname, '..');
 
+// (h) — after a rotation write, docs/ai/index.md would silently go stale (a moved ADR, or just the
+// bumped lastUpdated), tripping the SEPARATE `--check-index` gate mid-release-matrix. So the
+// rotation regenerates the index by REUSING the ONE generator in the sibling check-docs-size.mjs
+// (spawned with --write-index --root=<root>). The subprocess bridges that script's ASYNC generator,
+// so this runCli stays SYNCHRONOUS (spawnSync) — the existing sync callers/tests never ripple. It
+// DEGRADES LOUDLY to an instruct (never a silent failure) when the sibling is absent or the
+// regeneration fails; the --check-index gate still catches a stale index. Injectable for tests.
+const CHECK_DOCS_SIBLING = resolve(__dirname, 'check-docs-size.mjs');
+const INDEX_INSTRUCT = 'run `node scripts/check-docs-size.mjs --write-index` to refresh docs/ai/index.md';
+// Exported + its filesystem edges injectable (deps) so BOTH degrade branches are unit-testable.
+export const defaultRegenerateIndex = (root, today, deps = {}) => {
+  const exists = deps.existsSync ?? existsSync;
+  const spawn = deps.spawnSync ?? spawnSync;
+  const sibling = deps.sibling ?? CHECK_DOCS_SIBLING;
+  if (!exists(sibling)) {
+    return { ok: false, detail: `the index generator is not beside this script — ${INDEX_INSTRUCT}` };
+  }
+  // `--report` ISOLATES the index-WRITE outcome from the docs-cap-CHECK outcome: check-docs-size
+  // --write-index still WRITES the index (and still exits 2 on an empty write / rejects a genuine
+  // throw), but --report suppresses its exit-1 on an unrelated over-cap co-located doc — otherwise a
+  // benign over-cap sibling would read as an index-regeneration FAILURE (a cry-wolf on this very
+  // loud-degrade channel).
+  const r = spawn(process.execPath, [sibling, '--write-index', '--report', `--root=${root}`, `--today=${today}`], { encoding: 'utf8' });
+  if (r.error || r.status !== 0) {
+    return { ok: false, detail: `index regeneration failed (${(r.error && r.error.message) || `exit ${r.status}`}) — ${INDEX_INSTRUCT}` };
+  }
+  return { ok: true, detail: (r.stdout || '').trim() };
+};
+
 export const HOT_REL = 'docs/ai/decisions.md';
 export const WARM_REL = 'docs/ai/history/decisions-archive.md';
 export const COLD_REL = 'docs/ai/history/decisions-archive-early.md';
@@ -295,7 +326,7 @@ const parseArgs = (argv) => {
 };
 
 export const runCli = (argv, deps = {}) => {
-  const { root = DEFAULT_ROOT, log = console.log, logError = console.error } = deps;
+  const { root = DEFAULT_ROOT, log = console.log, logError = console.error, regenerateIndex = defaultRegenerateIndex } = deps;
   try {
     const { flags, today: todayOpt } = parseArgs(argv);
     if (flags.help) {
@@ -406,6 +437,10 @@ export const runCli = (argv, deps = {}) => {
       mkdirSync(dirname(tier.path), { recursive: true });
       writeFileSync(tier.path, renderTier(updated, entries), 'utf8');
     }
+    // (h) — the write loop completed (a full successful rotation OR a normalize-only rewrite): the
+    // docs index is now stale, so regenerate it here (never on --check / --dry-run / the
+    // nothing-to-rotate no-op / a pre-write refusal — those return before this point).
+    const regen = regenerateIndex(root, today);
     log('[archive-decisions] rotated:');
     log(`  HOT→WARM: ${summary.hotToWarm.join(', ') || '(none)'}`);
     log(`  WARM→COLD: ${summary.warmToCold.join(', ') || '(none)'}`);
@@ -413,6 +448,8 @@ export const runCli = (argv, deps = {}) => {
       log(`  normalize-only rewrite (over cap on raw lines, no entry moves): ${summary.normalizeOnly.join(', ')}`);
     }
     log(`  now: HOT ${summary.after.hot} · WARM ${summary.after.warm} · COLD ${summary.after.cold}`);
+    if (regen.ok) log('  regenerated docs/ai/index.md (the rotation kept the index fresh)');
+    else logError(`[archive-decisions] docs/ai/index.md NOT regenerated — ${regen.detail}`);
     return 0;
   } catch (err) {
     logError(`[archive-decisions] ${err.message}`);

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

@@ -14,6 +14,7 @@ import {
   planRotation,
   updateRangeTokens,
   runCli,
+  defaultRegenerateIndex,
 } from './archive-decisions.mjs';
 
 // Hermetic by design: this test ships as deploy payload and runs inside CONSUMER repos via the
@@ -67,10 +68,14 @@ const seedProject = (root, { hotIds, warmIds, coldIds, hotCapDelta = 100, warmCa
   };
 };
 
+// The existing rotation tests are about ROTATION, not the index-regen hook (item (h)) — inject a
+// no-op regenerator so they stay hermetic + fast (no real check-docs-size subprocess). The hook's
+// own firing/degrade behavior is pinned by the dedicated (h) describe below; the real end-to-end
+// spawn is isolated to one integration test there.
 const run = (argv, root) => {
   const out = [];
   const err = [];
-  const code = runCli(argv, { root, log: (l) => out.push(l), logError: (l) => err.push(l) });
+  const code = runCli(argv, { root, log: (l) => out.push(l), logError: (l) => err.push(l), regenerateIndex: () => ({ ok: true, detail: '' }) });
   return { code, out, err, text: out.join('\n'), errText: err.join('\n') };
 };
 
@@ -363,3 +368,115 @@ describe('created tiers (a consumer with no history files yet)', () => {
     assert.match(errText, /Unknown argument/);
   });
 });
+
+// ── (h) — a rotation regenerates docs/ai/index.md (BUGFREE-3 / AD-049) ─────────────────
+describe('(h) index regeneration after rotation', () => {
+  const spyRun = (argv, root, regen) => {
+    const out = [];
+    const err = [];
+    const code = runCli(argv, { root, log: (l) => out.push(l), logError: (l) => err.push(l), regenerateIndex: regen });
+    return { code, out, err, text: out.join('\n'), errText: err.join('\n') };
+  };
+
+  it('calls the regenerator once with (root, today) AFTER a successful rotation write', () => {
+    const root = makeRoot();
+    seedProject(root, { hotIds: ['005', '006', '007', '008'], warmIds: ['003', '004'], coldIds: ['001', '002'], hotCapDelta: -1 });
+    const calls = [];
+    const { code } = spyRun(['--today=2026-01-02'], root, (r, t) => { calls.push([r, t]); return { ok: true, detail: '' }; });
+    assert.equal(code, 0);
+    assert.deepEqual(calls, [[root, '2026-01-02']], 'exactly one regen, with the rotation root + today');
+  });
+
+  it('does NOT regenerate on a no-op, --check, --dry-run, or a pre-write refusal', () => {
+    let called = 0;
+    const spy = () => { called += 1; return { ok: true, detail: '' }; };
+    // no-op (under cap)
+    const r1 = makeRoot(); seedProject(r1, { hotIds: ['005'], warmIds: ['003'], coldIds: ['001'] });
+    spyRun([], r1, spy);
+    // --check
+    spyRun(['--check'], r1, spy);
+    // --dry-run over a real rotation plan
+    const r2 = makeRoot(); seedProject(r2, { hotIds: ['005', '006'], warmIds: [], coldIds: [], hotCapDelta: -1 });
+    spyRun(['--dry-run'], r2, spy);
+    // a pre-write refusal (COLD exhausted)
+    const r3 = makeRoot(); seedProject(r3, { hotIds: ['005', '006', '007'], warmIds: ['003', '004'], coldIds: ['001', '002'], hotCapDelta: -1, warmCapDelta: 3, coldCapDelta: 3 });
+    spyRun(['--today=2026-01-02'], r3, spy);
+    assert.equal(called, 0, 'the hook fires only AFTER a real write — never on no-op/check/dry-run/refusal');
+  });
+
+  it('a NORMALIZE-ONLY rewrite (stampLastUpdated bumps lastUpdated, zero moves) still triggers regeneration', () => {
+    const root = makeRoot();
+    mkdirSync(join(root, 'docs', 'ai', 'history'), { recursive: true });
+    const blocks = [entryBlock('001'), entryBlock('002'), entryBlock('003')];
+    const body = blocks.join('\n\n---\n\n'); // the template separator shape: raw > cap, normalized fits
+    const probe = `${fm(999)}\n# ADRs\n\n${body}\n`;
+    writeFileSync(join(root, HOT_REL), `${fm(lineCountOf(probe) - 2)}\n# ADRs\n\n${body}\n`);
+    let called = 0;
+    const { code, text } = spyRun(['--today=2026-01-02'], root, () => { called += 1; return { ok: true, detail: '' }; });
+    assert.equal(code, 0, text);
+    assert.match(text, /normalize-only rewrite/);
+    assert.equal(called, 1, 'a normalize-only rewrite still leaves the index stale → regenerate');
+  });
+
+  it('degrades LOUDLY to an instruct when regeneration fails — the rotation still succeeds (exit 0)', () => {
+    const root = makeRoot();
+    seedProject(root, { hotIds: ['005', '006'], warmIds: [], coldIds: [], hotCapDelta: -1 });
+    const { code, errText } = spyRun(['--today=2026-01-02'], root, () => ({ ok: false, detail: 'the index generator is not beside this script — run `node scripts/check-docs-size.mjs --write-index` to refresh docs/ai/index.md' }));
+    assert.equal(code, 0, 'the rotation itself succeeded — regen is best-effort');
+    assert.match(errText, /NOT regenerated/);
+    assert.match(errText, /check-docs-size\.mjs --write-index/, 'the loud instruct names the recovery command');
+  });
+
+  it('the REAL default regenerator writes docs/ai/index.md end-to-end (no injection)', () => {
+    const root = makeRoot();
+    seedProject(root, { hotIds: ['005', '006', '007', '008'], warmIds: ['003', '004'], coldIds: ['001', '002'], hotCapDelta: -1 });
+    const out = [];
+    const code = runCli(['--today=2026-01-02'], { root, log: (l) => out.push(l), logError: (l) => out.push(l) });
+    assert.equal(code, 0, out.join('\n'));
+    assert.ok(existsSync(join(root, 'docs', 'ai', 'index.md')), 'the index was regenerated by the sibling check-docs-size.mjs');
+    const idx = readFileSync(join(root, 'docs', 'ai', 'index.md'), 'utf8');
+    assert.match(idx, /decisions\.md/, 'the regenerated index lists the rotated ADR file');
+    assert.match(out.join('\n'), /regenerated docs\/ai\/index\.md/, 'the success log line fires');
+  });
+
+  // The index-write outcome must be ISOLATED from the docs-cap-CHECK outcome: check-docs-size
+  // --write-index exits 1 on ANY over-cap co-located doc even after writing the index correctly, so
+  // a benign over-cap sibling must NEVER read as an index-regeneration failure (cry-wolf on the very
+  // loud-degrade channel item (h) is built around). The regen spawns --write-index --report.
+  it('the REAL regenerator succeeds even when an UNRELATED co-located doc is over its cap (no cry-wolf)', () => {
+    const root = makeRoot();
+    seedProject(root, { hotIds: ['005', '006', '007', '008'], warmIds: ['003', '004'], coldIds: ['001', '002'], hotCapDelta: -1 });
+    // An unrelated doc over its OWN maxLines cap: --write-index writes the index fine, but without
+    // --report it would exit 1 on this file → a false "NOT regenerated" instruct.
+    writeFileSync(join(root, 'docs', 'ai', 'handover.md'), `---\ntype: state\nlastUpdated: 2026-01-02\nscope: session\nstaleAfter: 7d\nowner: none\nmaxLines: 3\n---\n\n# H\nl1\nl2\nl3\nl4\nl5\n`);
+    const out = [];
+    const err = [];
+    const code = runCli(['--today=2026-01-02'], { root, log: (l) => out.push(l), logError: (l) => err.push(l) });
+    assert.equal(code, 0);
+    assert.match(out.join('\n'), /regenerated docs\/ai\/index\.md/, 'a benign over-cap sibling must NOT read as a regen failure');
+    assert.ok(!err.join('\n').includes('NOT regenerated'), 'no false cry-wolf on the loud-degrade channel');
+    assert.ok(existsSync(join(root, 'docs', 'ai', 'index.md')), 'the index was actually written');
+  });
+
+  describe('defaultRegenerateIndex — the loud-degrade branches', () => {
+    it('an absent index generator sibling → a loud instruct (ok:false)', () => {
+      const r = defaultRegenerateIndex('/tmp/anyroot', '2026-01-02', { sibling: '/nonexistent/check-docs-size.mjs' });
+      assert.equal(r.ok, false);
+      assert.match(r.detail, /not beside this script/);
+      assert.match(r.detail, /check-docs-size\.mjs --write-index/);
+    });
+
+    it('a regeneration subprocess that exits nonzero → a loud instruct (ok:false)', () => {
+      const r = defaultRegenerateIndex('/tmp/anyroot', '2026-01-02', { existsSync: () => true, spawnSync: () => ({ status: 1 }) });
+      assert.equal(r.ok, false);
+      assert.match(r.detail, /index regeneration failed/);
+      assert.match(r.detail, /check-docs-size\.mjs --write-index/);
+    });
+
+    it('a successful subprocess (status 0) → ok:true with the trimmed stdout', () => {
+      const r = defaultRegenerateIndex('/tmp/anyroot', '2026-01-02', { existsSync: () => true, spawnSync: () => ({ status: 0, stdout: 'Wrote docs/ai/index.md\n' }) });
+      assert.equal(r.ok, true);
+      assert.match(r.detail, /Wrote docs\/ai\/index\.md/);
+    });
+  });
+});

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 {
@@ -301,24 +310,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 +352,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', () => {
@@ -202,3 +206,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/agent_rules.md

@@ -53,6 +53,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/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": {}
+}