@sabaiway/agent-workflow-memory 2.3.0 → 3.0.1

package/CHANGELOG.md

@@ -2,7 +2,47 @@
 
 All notable changes to the memory substrate. Versions are this **package's** npm versions;
 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 `2.0.0`).
+`docs/ai/.memory-version` (which tracks the shared `agent-workflow` lineage, head `3.0.0`).
+
+## 3.0.1 — bundled reference scripts refreshed (no behavior change)
+
+PATCH rider on the kit 3.1.0 release — the publish workflow's changed-but-unbumped tooth caught
+that two bundled reference scripts had moved since 3.0.0 without a version bump. No CLI surface,
+output, or exit-code change:
+
+- `references/scripts/check-docs-size.mjs` — reworked to an in-process CLI shape (pure argv
+  parser, injectable log, exported `runCli`) so suites drive it without a spawn; same flags, same
+  behavior; a colocated CLI test pins it.
+- `references/scripts/archive-decisions.mjs` — comment-only cleanup (reviewer-round identity
+  references removed as part of the family-wide neutral-review-ID sweep).
+
+## 3.0.0 — strip-the-kit: the substrate follows the hardened computed core (AD-059)
+
+> ### ⚠ BREAKING — retired loop surfaces + Node >= 22
+>
+> The verification-profile template is gone; the gates.json seed and the loop docs describe the
+> `run-gates --final` / commit-guard loop; pre-commit hooks from `install-git-hooks.mjs` may gain
+> the consented `--commit-guard <path>` line. Node floor **>= 22**. Deployment-lineage head is
+> **3.0.0** — init/upgrade re-stamps and applies `migrations/3.0.0-hardened-core-loop.md`.
+
+Shipped in lockstep with kit 3.0.0 / engine 2.0.0 (the lineage owner carries the consumer
+migration surfaces):
+
+- **`migrate-gates.mjs` (+ its deploy-payload spec, NEW):** the consented D8 legacy gates.json
+  migration — preview default, atomic apply; canonical legacy entries removed by their documented
+  single-invocation forms; the canonical `unit-tests` cmd gains the full lcov reporter flag set;
+  the canonical `coverage-check` gate lands LAST (realpath-anchored, move/collision semantics);
+  retired git-dir ledger stores cleaned; CUSTOMIZED entries reported with paste-ready recoveries;
+  symlinked-parent and control-byte STOPs, all fail-closed.
+- **`install-git-hooks.mjs`:** the hooks path comes from `git rev-parse --git-path hooks` (a
+  linked worktree installs at ITS OWN hooks dir); the optional `--commit-guard <path>` arm writes
+  the resolved quoted guard line; an armed line survives flagless re-runs (strict single-line
+  carry-forward; `--no-commit-guard` is the one consented disable; duplicates fail closed). New
+  colocated specs incl. the in-place GIT_DIR-pinned execution suite.
+- **`stamp-takeover.mjs`:** LINEAGE_HEAD 3.0.0; the takeover/migration selection mechanics are
+  unchanged — new deployments stamp 3.0.0, older ones pick up the 3.0.0 migration.
+- **Templates/docs:** the gates seed + agent-rules/§4 consent line follow the D13 loop (staging
+  is reversible loop-work; COMMIT is the ask); SKILL sweeps for the three seeded configs.
 
 ## 2.3.0 — agent_rules template: a report-facts Communication bullet + the writer-batch lens re-render (REPORT-FACTS train, AD-054)
 

package/README.md

@@ -45,7 +45,7 @@ Open your agent inside a project and run the skill:
 
 Two independent axes: this package's **npm version** vs the **deployment-lineage** stamp the
 substrate writes into a project. They are not the same number. `.memory-version` tracks the
-shared `agent-workflow` deployment lineage (head `2.0.0` today), **not** this package's
+shared `agent-workflow` deployment lineage (head `3.0.0` today), **not** this package's
 version. A project bootstrapped by the kit's fallback carries a `.workflow-version`; when this
 substrate is later installed, `migrations/legacy-stamp-takeover.md` copies that value verbatim
 into `.memory-version` and never deletes the legacy stamp. See `migrations/README.md`.

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: '2.3.0'
+  version: '3.0.1'
 ---
 
 # agent-workflow-memory
@@ -51,7 +51,6 @@ pointers are the **three empty slots** the composition root fills — never auth
 | Autonomy-policy read contract (`docs/ai/autonomy.json`) | **methodology engine** (not this skill) | the empty `workflow:autonomy` 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) |
 | Per-project **autonomy policy** (red-lines + per-activity autonomy level) | **memory** seeds an *editable default* | `docs/ai/autonomy.json` (hand-editable, or agent-writable via the composition root's `set-autonomy` writer; the seed is SPARSE — the onboarding note only, defaults-equivalent, so deploying it never changes behavior; the policy **canon** + the render live in the engine / composition root, never here) |
 
 ---
@@ -107,15 +106,13 @@ bootstrapping over a live system, but the user makes the final call.
    `${CLAUDE_SKILL_DIR}/references/templates/` (every non-`AGENTS.md`, non-`adr-record.md` template —
    the latter is a skill-home authoring reference, never deployed). This deploys the HOT ADR window
    `docs/ai/decisions.md` **and** the seed navigator `docs/ai/adr/log.md` (its `adr/` subdir copies
-   in wholesale), plus the four seeded, **user-editable** strict-JSON configs:
+   in wholesale), plus the three seeded, **user-editable** strict-JSON configs:
    `docs/ai/orchestration.json` — the per-project 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 —
-   `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) — and `docs/ai/autonomy.json` — the per-project
-   autonomy policy, seeded SPARSE (the onboarding note only, defaults-equivalent — behavior changes
-   only when the user declares levels). Keep each `.md` file's frontmatter.
+   its own verification commands, consumed by the composition root's gate runner — and
+   `docs/ai/autonomy.json` — the per-project autonomy policy, seeded SPARSE (the onboarding note
+   only, defaults-equivalent — behavior changes only when the user declares levels). 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;
@@ -128,7 +125,7 @@ bootstrapping over a live system, but the user makes the final call.
    append-only (never duplicate an existing line), then **verify `git status` shows them ignored**.
    Never the machine-global excludes; never edit `package.json`.
 10. **Stamp the deployment lineage.** Write the **deployment-lineage head** into
-    `docs/ai/.memory-version` (one semver line). The lineage head is **`2.0.0`** (the
+    `docs/ai/.memory-version` (one semver line). The lineage head is **`3.0.0`** (the
     `LINEAGE_HEAD` constant in `scripts/stamp-takeover.mjs`) — the shared `agent-workflow`
     lineage, a **separate axis** from this package's npm version (the two may even coincide by
     accident; see *Stamp = lineage head, not package version*). Use the atomic writer in
@@ -167,7 +164,7 @@ Fill strategy:
    `scripts/stamp-takeover.mjs` decides the action per state; the Markdown migration is the
    no-Node manual fallback. If **no** stamp exists at all, offer a conservative re-bootstrap.
 2. **Never-downgrade gate FIRST, then the stamp-independent hidden-mode reconcile (D14).** Compare the
-   stamp to the **deployment-lineage head** (`LINEAGE_HEAD`, `2.0.0`). **Greater than the head, or
+   stamp to the **deployment-lineage head** (`LINEAGE_HEAD`, `3.0.0`). **Greater than the head, or
    unparseable → STOP and report immediately, before ANY write** (never downgrade or guess, and never
    touch `.git/info/exclude`). This STOP is one of the only two places the number is shown (see
    *Version disclosure* below): tell the user **the `docs/ai` structure version** their deployment
@@ -184,23 +181,21 @@ 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 the FOUR seeded `.json` configs** — for `docs/ai/orchestration.json`,
-   `docs/ai/gates.json`, `docs/ai/verification-profile.json`, AND `docs/ai/autonomy.json`,
+   short-circuit): ensure the THREE seeded `.json` configs** — for `docs/ai/orchestration.json`,
+   `docs/ai/gates.json`, AND `docs/ai/autonomy.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);
-   `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; `autonomy.json` is the
+   `autonomy.json` is the
    per-project autonomy policy, seeded SPARSE (the onboarding note only, defaults-equivalent —
    agent-writable via the composition root's `set-autonomy` writer, hand-editing supported). (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
-   content, seed-or-preserve only.) This is why an equal-head (`2.0.0`) deployment still gains the
+   content, seed-or-preserve only.) This is why an equal-head (`3.0.0`) deployment still gains the
    config seeds **without a lineage-head bump or a migration file** (the
    stamp-independent-reconcile precedent — like the pointer slots + the hidden-mode footprint).
    **Same gate, also stamp-independent: ensure the ADR-store enforcement pair** — copy
@@ -287,7 +282,7 @@ memory substrate has none, so it relies on the STOP + the explicit ask — never
 - **Source vs target directory.** Templates/scripts are read from the skill's own dir; the
   **working directory is the target project** — never write substrate files back into the skill.
 - **Stamp = lineage head, not package version.** `.memory-version` carries the **deployment-lineage
-  head** (`2.0.0`, the shared `agent-workflow` lineage) — a **separate axis** from this package's npm
+  head** (`3.0.0`, the shared `agent-workflow` lineage) — a **separate axis** from this package's npm
   version (the two may even coincide by accident). They move independently.
 - **All three pointer slots ship empty and stay the user's.** Never author methodology,
   orchestration or autonomy text into them; on upgrade, preserve their content byte-for-byte. The

package/bin/install.mjs

@@ -13,7 +13,7 @@
 // That is distinct from `/agent-workflow-memory upgrade`, which migrates a
 // *project's* docs/ai deployment — see README "Use".
 //
-// No telemetry, no phone-home. Dependency-free, Node >= 18.
+// No telemetry, no phone-home. Dependency-free, Node >= 22.
 
 import { readFile, mkdir, readdir, copyFile, lstat, readlink, symlink } from 'node:fs/promises';
 import { existsSync, lstatSync, realpathSync } from 'node:fs';

package/capability.json

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

package/migrations/3.0.0-hardened-core-loop.md

@@ -0,0 +1,29 @@
+# Migration 3.0.0-hardened-core-loop
+
+**From:** versions < 3.0.0   **To:** 3.0.0
+
+## Why
+
+3.0.0 aligns the substrate with the hardened computed review loop: the verification-profile
+template is retired, the gates seed and the loop docs describe the `run-gates --final` /
+commit-guard loop, and the hook installer gains the consented `--commit-guard <path>` arm.
+
+## Steps
+
+1. **Node floor:** ensure Node **>= 22**.
+2. **Composition-root-present deployment — one handoff, never a loop:** invoked FROM the
+   composition root's upgrade (the delegated path), do nothing here — control returns to the
+   OUTER composition-root upgrade, which owns the gates/bridge/guard steps of its OWN `3.0.0`
+   migration. Running the memory upgrade STANDALONE with a composition root installed: hand off
+   ONCE to the installed composition root's upgrade and do not re-enter.
+3. **Memory-only deployment:** nothing to migrate by hand — the upgrade's seed-or-preserve pass
+   applies (templates and loop docs arrive for NEW files; existing user-authored files are
+   PRESERVED, never rewritten); the composition-root-owned gates/bridge/guard operations simply
+   do not run without one.
+4. **Re-stamp:** the upgrade re-stamps `docs/ai/.memory-version` to 3.0.0 (the memory axis).
+
+## Verification
+
+`docs/ai/.memory-version` reads `3.0.0`. Memory-only branch: user-authored `docs/ai` files are
+byte-unchanged. Composition-root-present branch: that root's own migration verification applies
+(it owns the consented `docs/ai/gates.json` change — byte-preservation is NOT claimed there).

package/migrations/README.md

@@ -13,7 +13,7 @@ releases add files/templates, which `upgrade` reconciles without a migration.
    `.memory-version` verbatim — see that migration.
 2. Select every migration whose `<version>` is **strictly newer** than the stamp.
 3. Apply them in **ascending semver order**.
-4. Re-stamp `docs/ai/.memory-version` to the deployment-lineage head (`2.0.0` today — the shared
+4. Re-stamp `docs/ai/.memory-version` to the deployment-lineage head (`3.0.0` today — the shared
    lineage sequence, **not** this package's npm version). The legacy `.workflow-version`, if present,
    is never deleted.
 

package/migrations/legacy-stamp-takeover.md

@@ -13,13 +13,13 @@ any other migration.
 
 The deployment stamp moved from `.workflow-version` (owned by the kit) to `.memory-version`
 (owned by this substrate). They track the **same** shared deployment-lineage sequence — never
-their package versions. The current lineage head is **`2.0.0`** (`LINEAGE_HEAD`). This migration
+their package versions. The current lineage head is **`3.0.0`** (`LINEAGE_HEAD`). This migration
 adopts an existing legacy stamp into the new file **without** changing the lineage value and
 **without** deleting the legacy stamp (both may coexist; each tool migrates from its own stamp).
 
 ## State table (idempotent)
 
-Look at `docs/ai/` and act by row. `V` is the legacy stamp's value; `head` = `2.0.0`.
+Look at `docs/ai/` and act by row. `V` is the legacy stamp's value; `head` = `3.0.0`.
 
 | `docs/ai/` state | Action |
 |---|---|
@@ -42,7 +42,7 @@ Look at `docs/ai/` and act by row. `V` is the legacy stamp's value; `head` = `2.
    done
    ```
 2. **Validate** each value that exists: it must be `MAJOR.MINOR.PATCH`, non-empty, and **not** greater
-   than `2.0.0`. If any present stamp is empty, unparseable, or in the future → **STOP and report**;
+   than `3.0.0`. If any present stamp is empty, unparseable, or in the future → **STOP and report**;
    do nothing else.
 3. **Apply** the matching row above. For the "only `.workflow-version=V`" row, copy verbatim and
    write **atomically** — create an exclusive randomized temp in `docs/ai/` (so a planted temp-name

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "2.3.0",
+  "version": "3.0.1",
   "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",
@@ -47,7 +47,7 @@
     "!scripts/*.test.mjs"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "publishConfig": {
     "access": "public"

package/references/scripts/archive-decisions.mjs

@@ -46,7 +46,7 @@
 // destructive --migrate --apply writes a durable snapshot to the git dir (uncommittable, the
 // review-receipts precedent) BEFORE any delete, with a stated out-of-tree fallback off git.
 //
-// Dependency-free, Node >= 18. Deployed into a consumer's scripts/ like its siblings.
+// Dependency-free, Node >= 22. Deployed into a consumer's scripts/ like its siblings.
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
 import { dirname, resolve, join } from 'node:path';
@@ -649,7 +649,7 @@ const runMigrate = (root, flags, today, deps, log, logError) => {
   verifyConservation(oldItems, newItems);
   // Integrity over the FULL final store — existing records ∪ freshly-exploded — not just the new
   // writes: a pre-existing adr/ record whose id also stays RETAINED in HOT would otherwise leave the
-  // ADR in two places (codex R4). Same full-store pattern as runRotate.
+  // ADR in two places. Same full-store pattern as runRotate.
   const finalStoreById = new Map(existingStore.map((e) => [e.id, { id: e.id, idNum: e.idNum, fileName: e.fileName }]));
   for (const r of records) finalStoreById.set(r.id, { id: r.id, idNum: r.idNum, fileName: r.fileName });
   assertStoreIntegrity(retained, [...finalStoreById.values()]);
@@ -783,7 +783,7 @@ const runRotate = (root, flags, today, deps, log, logError) => {
   }
 
   const records = explode(toExplode, today);
-  // Crash-resume (fold-induced, codex R2): a record from a prior crashed rotate may already be on
+  // Crash-resume (fold-induced): a record from a prior crashed rotate may already be on
   // disk. A byte-identical one is done (deduped, not a duplicate-id error); a divergent-body one is
   // corrupt → FAIL. The FINAL store = existing ∪ freshly-exploded, deduped by id.
   const existingById = new Map(existingStore.map((e) => [e.id, e]));

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

@@ -341,7 +341,7 @@ describe('1.3 --migrate --apply — records + snapshot + retire monoliths + HOT
     assert.equal(run(['--check', '--today=2026-07-09'], root).code, 0, 'the resumed tree passes --check');
   });
 
-  it('refuses when a pre-existing adr/ record duplicates an ADR that stays in HOT (never two places — codex R4)', () => {
+  it('refuses when a pre-existing adr/ record duplicates an ADR that stays in HOT (never two places — review-adr-archive-r04-major-01)', () => {
     const root = makeRoot();
     seedLegacy(root, { hot: ['005', '006'], warm: ['003'], cold: ['001'] });
     mkdirSync(join(root, ADR_DIR_REL), { recursive: true });
@@ -452,7 +452,7 @@ describe('1.4 --check', () => {
     assert.match(errText, /duplicate ADR id AD-002/);
   });
 
-  it('a decisions.md with NO maxLines cap fails loud (never operates against an unknown budget — codex R4)', () => {
+  it('a decisions.md with NO maxLines cap fails loud (never operates against an unknown budget — review-adr-archive-r04-major-02)', () => {
     const root = makeRoot();
     mkdirSync(join(root, 'docs', 'ai'), { recursive: true });
     const noCapFm = '---\ntype: reference\nlastUpdated: 2026-01-01\nscope: permanent\nstaleAfter: never\nowner: none\n---\n';
@@ -514,7 +514,7 @@ describe('1.4 --check', () => {
     assert.match(errText, /two records for AD-001/);
   });
 
-  it('a NESTED subdirectory in adr/ fails loud (the store is a flat directory — codex R2)', () => {
+  it('a NESTED subdirectory in adr/ fails loud (the store is a flat directory — review-adr-archive-r02-major-01)', () => {
     const root = makeRoot();
     seedMigrated(root, { hotIds: ['005'], storeIds: ['001'] });
     mkdirSync(join(root, ADR_DIR_REL, 'nested'), { recursive: true });
@@ -561,7 +561,7 @@ describe('1.4 default rotate — explode the oldest beyond cap + regenerate the
     assert.equal(regenCalls.length, 0, 'a no-op never regenerates the index');
   });
 
-  it('is crash-resumable: a byte-identical record from a crashed prior rotate is deduped, not a fatal duplicate (codex R2)', () => {
+  it('is crash-resumable: a byte-identical record from a crashed prior rotate is deduped, not a fatal duplicate (review-adr-archive-r02-major-02)', () => {
     const root = makeRoot();
     mkdirSync(join(root, ADR_DIR_REL), { recursive: true });
     const blocks = ['005', '006', '007', '008'].map((id) => adrBlock(id));
@@ -579,7 +579,7 @@ describe('1.4 default rotate — explode the oldest beyond cap + regenerate the
     assert.equal(run(['--check', '--today=2026-07-09'], root).code, 0);
   });
 
-  it('a no-op rotate still REFUSES a corrupt store (partition) — never a silent green no-op (codex R2)', () => {
+  it('a no-op rotate still REFUSES a corrupt store (partition) — never a silent green no-op (review-adr-archive-r02-major-03)', () => {
     const root = makeRoot();
     seedMigrated(root, { hotIds: ['005'], storeIds: ['001'] }); // under cap
     const rec = explode(parseDecisionsText(tierText(999, '# T', [adrBlock('010')]), 'x').entries, '2026-07-09')[0];

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

@@ -0,0 +1,41 @@
+// check-docs-size-cli.test.mjs — runCli branch pins the subprocess smokes cannot reach
+// in-process (Phase-5 coverage fill; the main spec file is parity-frozen, so these ride a
+// colocated file): the unknown-argument refusal and the written-empty-index guard.
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runCli } from './check-docs-size.mjs';
+
+const cli = async (argv) => {
+  const { code, stdout, stderr } = await runCli(argv);
+  return { code, stdout, stderr };
+};
+
+describe('check-docs-size runCli — refusal branches', () => {
+  it('an unknown argument exits 2 naming it', async () => {
+    const { code, stderr } = await cli(['--bogus']);
+    assert.equal(code, 2);
+    assert.match(stderr, /Unknown argument: --bogus/);
+  });
+
+  it('--write-index landing on a sink path (index stat size 0) is the loud written-empty refusal', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'cds-cli-'));
+    try {
+      mkdirSync(join(root, 'docs', 'ai'), { recursive: true });
+      writeFileSync(
+        join(root, 'docs', 'ai', 'a.md'),
+        '---\ntype: state\nlastUpdated: 2026-07-18\nscope: session\nstaleAfter: never\nowner: none\nmaxLines: 10\n---\n\n# a\n',
+      );
+      // The index path is a symlink into /dev/null: the write lands, the stat reads size 0 —
+      // the guard must refuse loudly instead of reporting a written index.
+      symlinkSync('/dev/null', join(root, 'docs', 'ai', 'index.md'));
+      const { code, stderr } = await cli(['--write-index', `--root=${root}`]);
+      assert.equal(code, 2);
+      assert.match(stderr, /index\.md was written empty/);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

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

@@ -103,25 +103,19 @@ export const discoverMeta = async (root = ROOT) => {
   return { projectName, hierarchicalLinks, onDemandLinks };
 };
 
+// Pure argv parser (no I/O, no exit): `help` / `error` ride out as data for runCli to render.
 const parseArgs = (argv) => {
   const flags = { report: false, writeIndex: false, checkIndex: false, quiet: false };
   const opts = { today: null, root: null };
-  for (const arg of argv.slice(2)) {
+  for (const arg of argv) {
     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] [--root=<dir>] [--quiet]',
-      );
-      process.exit(0);
-    } else {
-      console.error(`Unknown argument: ${arg}`);
-      process.exit(2);
-    }
+    else if (arg === '--help' || arg === '-h') return { flags, opts, help: true };
+    else return { flags, opts, error: `Unknown argument: ${arg}` };
   }
   return { flags, opts };
 };
@@ -218,7 +212,7 @@ const formatRow = (row) => {
   return { status, sizeCell, ...row };
 };
 
-const printReport = (rows, quiet) => {
+const printReport = (rows, quiet, log = console.log) => {
   const widths = {
     status: 2,
     path: Math.max(4, ...rows.map((r) => r.path.length)),
@@ -228,15 +222,15 @@ const printReport = (rows, quiet) => {
   };
   const printable = quiet ? rows.filter((r) => r.errors.length || r.warnings.length) : rows;
   if (printable.length > 0) {
-    console.log(
+    log(
       `${'S'.padEnd(widths.status)}  ${'PATH'.padEnd(widths.path)}  ${'SIZE/MAX'.padEnd(widths.size)}  ${'TYPE'.padEnd(widths.type)}  ${'UPDATED'.padEnd(widths.updated)}`,
     );
     for (const row of printable) {
-      console.log(
+      log(
         `${row.status.padEnd(widths.status)}  ${row.path.padEnd(widths.path)}  ${row.sizeCell.padEnd(widths.size)}  ${(row.frontmatter?.type ?? '').padEnd(widths.type)}  ${(row.frontmatter?.lastUpdated ?? '').padEnd(widths.updated)}`,
       );
-      for (const err of row.errors) console.log(`     - ERROR  ${err}`);
-      for (const warn of row.warnings) console.log(`     - WARN   ${warn}`);
+      for (const err of row.errors) log(`     - ERROR  ${err}`);
+      for (const warn of row.warnings) log(`     - WARN   ${warn}`);
     }
   }
 };
@@ -361,9 +355,29 @@ export const regenerateIndex = async (root, todayStr = null) => {
   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);
+// The return-code entry point (no process.argv / process.exit / console inside): argv[] →
+// { code, stdout, stderr }. The thin shell at the bottom is the only process-coupled code.
+export const runCli = async (argv, deps = {}) => {
+  const stdoutLines = [];
+  const stderrLines = [];
+  const log = (line) => stdoutLines.push(line);
+  const logError = (line) => stderrLines.push(line);
+  const result = (code) => ({
+    code,
+    stdout: stdoutLines.length > 0 ? `${stdoutLines.join('\n')}\n` : '',
+    stderr: stderrLines.length > 0 ? `${stderrLines.join('\n')}\n` : '',
+  });
+
+  const { flags, opts, help, error } = parseArgs(argv);
+  if (help) {
+    log('Usage: check-docs-size.mjs [--report|--write-index|--check-index] [--today=YYYY-MM-DD] [--root=<dir>] [--quiet]');
+    return result(0);
+  }
+  if (error) {
+    logError(error);
+    return result(2);
+  }
+  const { root, docsDir, indexPath } = pathsFor(opts.root ? resolve(opts.root) : (deps.root ?? ROOT));
   const today = computeToday(opts.today);
   const files = (await walkMarkdownFiles(docsDir)).sort();
   const inspected = await Promise.all(files.map((f) => inspectFile(f, today, root)));
@@ -373,11 +387,11 @@ const main = async () => {
 
   if (flags.writeIndex) {
     await writeIndex(rows, today, meta, indexPath);
-    console.log(`Wrote ${relative(root, indexPath)}`);
+    log(`Wrote ${relative(root, indexPath)}`);
     const after = await stat(indexPath);
     if (after.size === 0) {
-      console.error('index.md was written empty');
-      process.exit(2);
+      logError('index.md was written empty');
+      return result(2);
     }
   }
 
@@ -385,28 +399,31 @@ const main = async () => {
     const onDisk = existsSync(indexPath) ? await readFile(indexPath, 'utf8') : null;
     const { fresh } = checkIndexFreshness(rows, onDisk, meta);
     if (!fresh) {
-      console.error(
+      logError(
         `[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);
+      return result(1);
     }
-    console.log(
+    log(
       `[check-docs-size] OK — ${relative(root, indexPath)} is in sync with source frontmatter.`,
     );
-    return;
+    return result(0);
   }
 
-  printReport(rows, flags.quiet);
+  printReport(rows, flags.quiet, log);
   const errorCount = rows.reduce((n, r) => n + r.errors.length, 0);
   const warnCount = rows.reduce((n, r) => n + r.warnings.length, 0);
-  console.log(
+  log(
     `\n${rows.length} files inspected  —  ${errorCount} error(s), ${warnCount} warning(s)`,
   );
 
-  if (errorCount > 0 && !flags.report) process.exit(1);
+  return result(errorCount > 0 && !flags.report ? 1 : 0);
 };
 
 const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (isDirectRun) {
-  await main();
+  const { code, stdout, stderr } = await runCli(process.argv.slice(2));
+  if (stdout) process.stdout.write(stdout);
+  if (stderr) process.stderr.write(stderr);
+  process.exitCode = code;
 }

package/references/scripts/install-git-hooks-repo-exec.test.mjs

@@ -0,0 +1,82 @@
+// install-git-hooks-repo-exec.test.mjs — the SIBLING installer executed IN PLACE (no deploy
+// copy): GIT_DIR pins every git answer to a fixture repo, so the run exercises this tree's own
+// file — the D3(d) changed-line check reads real executions of the shipped bytes, while the
+// deploy-copy suite (install-git-hooks.test.mjs) keeps the consumer-shaped behavior pins. Every
+// branch of the installer runs from here: fresh install, the guard arm/carry/disable/conflict
+// lanes, the unmanaged refusal, the up-to-date short-circuit, and the not-a-git-checkout skip.
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, readFileSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const INSTALLER = join(HERE, 'install-git-hooks.mjs');
+
+const mkRepo = () => {
+  const root = mkdtempSync(join(tmpdir(), 'hooks-repo-exec-'));
+  spawnSync('git', ['init', '-q'], { cwd: root, encoding: 'utf8' });
+  writeFileSync(join(root, 'guard.mjs'), '// a stand-in commit-guard tool\n');
+  return { root, gitDir: join(root, '.git') };
+};
+
+// The installer anchors its git queries at its OWN parent dir — GIT_DIR overrides that anchor to
+// the fixture repo, so running the in-place file NEVER touches this tree's hooks.
+const runAt = (gitDir, args = []) =>
+  spawnSync('node', [INSTALLER, ...args], { encoding: 'utf8', env: { ...process.env, GIT_DIR: gitDir } });
+
+const hookOf = ({ gitDir }) => readFileSync(join(gitDir, 'hooks', 'pre-commit'), 'utf8');
+
+describe('install-git-hooks — the in-place installer under a GIT_DIR-pinned fixture', () => {
+  it('installs the managed hook, is idempotent, and refuses an UNMANAGED hook', () => {
+    const fx = mkRepo();
+    assert.equal(runAt(fx.gitDir).status, 0);
+    assert.match(hookOf(fx), /:install-git-hooks\.mjs/, 'the managed marker is written');
+    const again = runAt(fx.gitDir);
+    assert.equal(again.status, 0);
+    assert.match(again.stdout, /already up to date/);
+    writeFileSync(join(fx.gitDir, 'hooks', 'pre-commit'), '#!/bin/sh\nexit 0\n');
+    const refused = runAt(fx.gitDir);
+    assert.equal(refused.status, 1, 'an unmanaged hook is never overwritten');
+    assert.match(refused.stderr, /Refusing to overwrite/);
+    rmSync(fx.root, { recursive: true, force: true });
+  });
+
+  it('the guard lanes: arm (absolute path) → carry on flagless re-run → consented disable', () => {
+    const fx = mkRepo();
+    assert.equal(runAt(fx.gitDir, ['--commit-guard', join(fx.root, 'guard.mjs')]).status, 0);
+    assert.match(hookOf(fx), /guard\.mjs" --check/);
+    assert.equal(runAt(fx.gitDir).status, 0, 'the flagless re-run keeps the armed line');
+    assert.match(hookOf(fx), /guard\.mjs" --check/);
+    assert.equal(runAt(fx.gitDir, ['--no-commit-guard']).status, 0);
+    assert.doesNotMatch(hookOf(fx), /" --check$/m);
+    rmSync(fx.root, { recursive: true, force: true });
+  });
+
+  it('the guard refusals: both flags (usage), a bare flag (usage), a missing path, a duplicated line', () => {
+    const fx = mkRepo();
+    assert.equal(runAt(fx.gitDir, ['--commit-guard', join(fx.root, 'guard.mjs'), '--no-commit-guard']).status, 2);
+    assert.equal(runAt(fx.gitDir, ['--commit-guard']).status, 2, '--commit-guard without a path is a usage error');
+    assert.equal(runAt(fx.gitDir, ['--commit-guard', join(fx.root, 'no-such.mjs')]).status, 1, 'a nonexistent guard path refuses');
+    assert.equal(runAt(fx.gitDir, ['--commit-guard', join(fx.root, 'guard.mjs')]).status, 0);
+    const armed = hookOf(fx);
+    const guardLine = armed.split('\n').find((l) => /" --check$/.test(l));
+    writeFileSync(join(fx.gitDir, 'hooks', 'pre-commit'), `${armed}${guardLine}\n`);
+    const dup = runAt(fx.gitDir);
+    assert.equal(dup.status, 1, 'two guard lines are ambiguous — fail closed');
+    assert.match(dup.stderr, /commit-guard --check lines/);
+    rmSync(fx.root, { recursive: true, force: true });
+  });
+
+  it('outside a git checkout the installer SKIPS loudly and writes nothing', () => {
+    const nowhere = mkdtempSync(join(tmpdir(), 'hooks-repo-exec-nogit-'));
+    const r = runAt(join(nowhere, 'absent-git-dir'));
+    assert.equal(r.status, 0);
+    assert.match(r.stdout, /skipping \(not a git checkout\)/);
+    assert.equal(existsSync(join(nowhere, 'absent-git-dir')), false, 'nothing was created');
+    rmSync(nowhere, { recursive: true, force: true });
+  });
+});