@sabaiway/agent-workflow-memory 1.11.0 → 1.12.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to the memory substrate. Versions are this **package's** npm
 they are distinct from the **deployment-lineage** stamp written into a project's
 `docs/ai/.memory-version` (which tracks the shared `agent-workflow` lineage, head `1.3.0`).
 
+## 1.12.0 — Verification-profile template + the docs-index-on-rotation regen (BUGFREE-3, AD-049)
+
+A **minor** release (deployment-lineage head stays `1.3.0` — no migration; co-released with the
+workflow kit 1.40.0). The memory substrate gains the optional verification-profile config and closes
+the docs-index-goes-stale-on-rotation cost (economics item (h)).
+
+- **Verification-profile template** — a new seeded `references/templates/verification-profile.json`
+  (`schema:1`; the kit reads it, kit 1.40.0) is created on bootstrap and ensured-if-missing on
+  upgrade (the `gates.json` / `orchestration.json` twin); `SKILL.md`'s bootstrap/ensure prose now
+  names it. An **absent profile reproduces today's V8 + node:test behaviour exactly** — it only ADDS
+  an opt-in default a consumer edits for its own language/runner.
+- **(h) a rotation regenerates `docs/ai/index.md`** — `references/scripts/archive-decisions.mjs`
+  regenerates the docs index after a successful rotation write (moves OR a normalize-only rewrite) by
+  reusing the now **root-parameterized** `check-docs-size.mjs --write-index --report` (the `--report`
+  isolates the index-write outcome from the docs-cap-check, so a benign over-cap sibling never reads
+  as a regeneration failure), with a loud instruct on absence/failure. An ADR rotation no longer
+  leaves the index stale to trip the `--check-index` gate mid-release-matrix.
+- **§2.2 minimal-comments** — the `agent_rules` template states comments as minimal / only-vital,
+  a BASELINE a consumer project may tighten (e.g. comments forbidden entirely).
+
+## 1.11.1 — One batched setup prompt (the F11 ask reword; AD-042)
+
+A **patch** release (prose reword only; deployment-lineage head stays `1.3.0` — no migration).
+The three bootstrap setup questions (visibility / conversational language / attribution) are now
+asked as **ONE structured multi-question prompt where supported** (`AskUserQuestion`, up to 4
+questions per call), each answer recorded individually, nothing written until ALL are answered —
+first contact interrupts once, not three times (`SKILL.md` bootstrap preamble + steps 2–4). The
+upgrade path batches its two migration asks the same way ONLY when both `AGENTS.md` blocks are
+missing (a pre-1.1.0 deployment), collecting them in step 4 BEFORE the migrations apply and never
+re-asking a collected answer (a migration's own "Ask the user" step stays the standalone
+fallback). The `references/contracts.md` ask paragraph is reworded byte-identical with the kit's
+copy — pinned cross-package by the kit's new `ask-contract` test.
+
 ## 1.11.0 — The template lens block becomes a render of the engine canon (AD-041)
 
 A **feature** release (template text only; deployment-lineage head stays `1.3.0` — no migration).

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-memory
 description: Deploy or upgrade a portable AI-agent memory substrate in any project — an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) and a structured `docs/ai/` context store with cap/archive/index enforcement. Use when the user wants to bootstrap `docs/ai/`, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-memory` / `/agent-workflow-memory upgrade`. Triggers on "set up the memory system", "deploy the AI memory here", "bootstrap docs/ai", "upgrade the memory substrate". This is the substrate only — the workflow methodology (plan→execute→review, queue, Cleanup) is owned elsewhere and injected into AGENTS.md by the family composition root.
 disable-model-invocation: true
 metadata:
-  version: '1.11.0'
+  version: '1.12.0'
 ---
 
 # agent-workflow-memory
@@ -49,6 +49,7 @@ What this substrate owns vs what it only points at. The methodology + orchestrat
 | Orchestration recipes (Solo / Reviewed / Council / Delegated) | **methodology engine** (not this skill) | the empty `workflow:orchestration` slot — filled by the composition root |
 | Per-project recipe **CONFIG** (which recipe each activity/slot uses) | **memory** seeds an *editable default* | `docs/ai/orchestration.json` (agent-writable via the composition root's `set-recipe` writer, or hand-edited; the recipe **canon** + the slot **vocabulary** live in the engine / composition root, never here) |
 | Per-project **gate declaration** (which verification commands must be green) | **memory** seeds an *editable default* | `docs/ai/gates.json` (hand-editable; an empty list as shipped — the project declares its own commands; the **runner** lives in the composition root, never here) |
+| Per-project **verification profile** (optional; the fold-completeness language-independence contract) | **memory** seeds an *editable default* | `docs/ai/verification-profile.json` (hand-editable; the seeded default reproduces the composition root's default V8 + node:test behaviour — delete it for exactly that; declares coverage source / single-test format / optional SARIF path; the **runner** lives in the composition root, never here) |
 
 ---
 
@@ -68,24 +69,26 @@ bootstrapping over a live system, but the user makes the final call.
 > Use that as the copy/read source; the working directory is the **target project**.
 
 > The three setup questions (steps 2–4) are decisions only the user can make and are hard to
-> reverse after a commit. Ask each as a **structured multiple-choice prompt where supported**
-> (`AskUserQuestion` in Claude Code, recommended option first), otherwise in prose — and
-> **wait for the answer before writing anything**.
+> reverse after a commit. Ask them as **ONE structured multi-question prompt where supported**
+> (`AskUserQuestion` in Claude Code, up to 4 questions per call, recommended option first),
+> otherwise in prose; **record each answer individually** — and **write nothing until ALL are
+> answered**.
 
 1. **Recon (read-only).** Before writing anything: `package.json` / `pyproject.toml` / `go.mod`
    / `Cargo.toml` → stack, package manager, scripts; `ls -la` root → README, existing
    `AGENTS.md`/`CLAUDE.md`, CI / linter configs; `git log --oneline -30` + `git status`; `src/`
    2–3 levels deep; tests + linter rules. Record stack, package manager, daily commands, layers.
-2. **Choose visibility — ASK explicitly and wait.** `visible` (committed — canonical,
+2. **Choose visibility — ask the batched prompt NOW (all three questions, per the preamble
+   above) and wait until every answer is in.** `visible` (committed — canonical,
    recommended) or `hidden` (in-tree, git-ignored via the **project-local** `.git/info/exclude` —
    never the machine-global excludes). See
    [Visibility contract](references/contracts.md#visibility-contract).
-3. **Choose conversational language — ASK explicitly and wait.** Which language the agent
+3. **Choose conversational language — answered in the step-2 batch.** Which language the agent
    *talks to them* in. Offer the language they're already writing in as the default. Carry it
    into the `{{COMM_LANGUAGE}}` slot of the *Communication language* block (step 5). See
    [Communication contract](references/contracts.md#communication-contract). Dialogue only —
    never the files.
-4. **Choose agent attribution — ASK explicitly and wait.** May the agent attribute work to
+4. **Choose agent attribution — answered in the step-2 batch.** May the agent attribute work to
    itself / AI — `Co-Authored-By` trailers, "Generated with …" footers, AI/agent/model mentions?
    **Default `off`.** Carry it into `{{AGENT_ATTRIBUTION}}` (step 5). **If `off` and the project
    uses Claude Code**, also set `"includeCoAuthoredBy": false` in the project's
@@ -97,11 +100,14 @@ bootstrapping over a live system, but the user makes the final call.
    (`ln -s AGENTS.md CLAUDE.md`). **Leave BOTH pointer slots (`workflow:methodology` +
    `workflow:orchestration`) exactly as shipped — empty.** Filling them is the composition root's job.
 6. **Deploy `docs/ai/`.** Create the files + `pages/` from
-   `${CLAUDE_SKILL_DIR}/references/templates/` (every non-`AGENTS.md` template, including the two
+   `${CLAUDE_SKILL_DIR}/references/templates/` (every non-`AGENTS.md` template, including the three
    seeded, **user-editable** strict-JSON configs: `docs/ai/orchestration.json` — the per-project
-   recipe defaults the composition root's `procedures` advisor reads — and `docs/ai/gates.json` —
+   recipe defaults the composition root's `procedures` advisor reads — `docs/ai/gates.json` —
    the project's gate declaration, an empty list to fill with its own verification commands,
-   consumed by the composition root's gate runner). Keep each `.md` file's frontmatter.
+   consumed by the composition root's gate runner — and `docs/ai/verification-profile.json` — the
+   OPTIONAL fold-completeness verification profile (the language-independence contract; the seeded
+   default reproduces the composition root's default V8 + node:test behaviour, delete it for exactly
+   that)). Keep each `.md` file's frontmatter.
 7. **Fill templates** per the table below.
 8. **Install enforcement (Node projects).** Copy `${CLAUDE_SKILL_DIR}/references/scripts/*.mjs`
    (+ `*.test.mjs`) into the project's `scripts/`. **No Node runtime** → skip this + the hook;
@@ -169,13 +175,16 @@ Fill strategy:
    **untracked AND not ignored** → **AMBIGUOUS** → **ASK** the user before writing. This visibility check
    runs on **every** in-range upgrade, even at head — it is not gated by the stamp delta, but it is gated
    **behind** the never-downgrade STOP above. **Also stamp-independent (same gate, before the equal-head
-   short-circuit): ensure BOTH seeded `.json` configs** — for `docs/ai/orchestration.json` AND
-   `docs/ai/gates.json`, **create the file from its
+   short-circuit): ensure the THREE seeded `.json` configs** — for `docs/ai/orchestration.json`,
+   `docs/ai/gates.json`, AND `docs/ai/verification-profile.json`, **create the file from its
    `${CLAUDE_SKILL_DIR}/references/templates/` template if missing**, **preserve it byte-for-byte
    if it already exists** (a user may have edited it; never clobber it). The shipped
    `orchestration.json` template's `_README` already frames that config as agent-writable (set it
    with the `set-recipe` writer) and still hand-editable; `gates.json` is the project's own gate
-   declaration (what to verify — consumed by the composition root's gate runner). (Refreshing the
+   declaration (what to verify — consumed by the composition root's gate runner);
+   `verification-profile.json` is the OPTIONAL fold-completeness verification profile — the seeded
+   default reproduces the composition root's default V8 + node:test behaviour, so a project deletes
+   it to fall back to exactly that, or edits it for another language/runner. (Refreshing the
    orchestration `_README` note in place on an existing file is the **composition root's** job on
    its own reconcile — this substrate is standalone and only seeds-or-preserves; it owns no
    cross-package refresh helper. The gates declaration gets no note-refresh at all — authored
@@ -196,13 +205,20 @@ Fill strategy:
    structure number, stamp filename, or internal versioning vocabulary on this happy-path exit — the
    number is inert here and belongs to *Version disclosure* (below).
 3. Show the relevant `${CLAUDE_SKILL_DIR}/CHANGELOG.md` context (entries newer than the stamp).
-4. Apply `${CLAUDE_SKILL_DIR}/migrations/<version>-<slug>.md` in **semver order**, only those
-   newer than the stamp. Migrations are **idempotent**.
+4. **Collect the migration answers FIRST, then apply.** If `AGENTS.md` is missing BOTH the
+   *Communication language* and *Attribution* blocks — i.e. both blocks are missing (a pre-1.1.0
+   deployment) — ask the two questions as ONE structured multi-question prompt; record each
+   answer individually, write nothing until ALL are answered, and carry the answers into the
+   migrations below: a migration whose answer was already collected never re-asks (its own
+   "Ask the user" step is the standalone fallback); a single missing block keeps its single ask
+   (step 5). Then apply `${CLAUDE_SKILL_DIR}/migrations/<version>-<slug>.md` in **semver order**,
+   only those newer than the stamp. Migrations are **idempotent**.
 5. Reconcile drift: add any substrate files/scripts the project is missing; **never clobber
    project-authored content** (their `decisions.md`, `known_issues.md`, page specs stay). For a
    pre-1.1.0 deployment with no *Communication language* block, ask + insert
    (`migrations/1.1.0-communication-language.md`); pre-1.2.0 with no *Attribution* block, ask +
-   insert defaulting to `off` (`migrations/1.2.0-agent-attribution.md`).
+   insert defaulting to `off` (`migrations/1.2.0-agent-attribution.md`). (An answer already
+   collected by the step-4 batched prompt is carried in — never re-asked here.)
 6. **Preserve BOTH pointer slots.** If `AGENTS.md` has the `workflow:methodology` and/or
    `workflow:orchestration` markers, **never regenerate the file wholesale** — extract any bytes
    between each pair and reinsert them unchanged. If a pair is absent (a legacy `AGENTS.md`),

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-memory",
   "kind": "memory-substrate",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "provides": ["context"],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Portable, cross-agent memory substrate for AI coding agents — an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement, deployable standalone or as part of the agent-workflow family. The memory layer of the agent-workflow family.",
   "keywords": [
     "ai-agents",

package/references/contracts.md

@@ -5,8 +5,9 @@ language**, and **agent attribution** — each have a contract below. `SKILL.md`
 main procedure stays lean; load this file when you need the full rule for a contract (e.g. while
 filling the matching `AGENTS.md` block, or when an `upgrade` migration touches it).
 
-Ask each as a **structured multiple-choice prompt where your agent supports it** (`AskUserQuestion`
-in Claude Code), otherwise in prose — and always wait for the answer before writing.
+Ask the three as **ONE structured multi-question prompt where your agent supports it**
+(`AskUserQuestion` in Claude Code, up to 4 questions per call), otherwise in prose; record each
+answer individually — and write nothing until ALL are answered.
 
 ---
 

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

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