@sabaiway/agent-workflow-memory 2.3.0 → 3.0.0

package/CHANGELOG.md

@@ -2,7 +2,35 @@
 
 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.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.0'
 ---
 
 # 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.0",
   "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.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",
@@ -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';

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 });
+  });
+});

package/references/scripts/install-git-hooks.mjs

@@ -1,12 +1,25 @@
 #!/usr/bin/env node
 // Idempotent installer for the project's git hooks.
 //
-// Installs `.git/hooks/pre-commit` running the docs cap-validator + index-freshness
+// Installs the `pre-commit` hook running the docs cap-validator + index-freshness
 // gate + changelog/issues rotation-freshness checks + the `scripts/` test
 // suite, so docs files cannot drift over their declared `maxLines`, the auto-generated
 // `index.md` navigator cannot silently fall out of sync, stale archive entries never
 // reach a commit, and regressions to the scripts themselves are caught at commit time.
 //
+// The hooks location comes from git's OWN answer (`git rev-parse --git-path hooks`) — a linked
+// worktree resolves ITS OWN hooks path (its `.git` is a FILE; a hardcoded `.git/hooks` would
+// miss or mis-write).
+//
+// COMMIT GUARD (D10, optional): `--commit-guard <path>` names the composition root's read-only
+// commit-guard tool explicitly — the hook then gains its `--check` line with the RESOLVED,
+// quoted path written at install time (a portable contract: no runtime guessing; this substrate
+// knows no sibling by name, so the path always arrives from the caller). The guard binds the
+// latest final-run receipt to the exact commit tree. An armed guard line SURVIVES flagless
+// re-runs (carried forward from the managed hook — exactly ONE strictly-parsed line; an
+// ambiguous duplicate fails closed); `--no-commit-guard` is the one consented disable; passing
+// both flags together is a usage error.
+//
 // Package-manager-agnostic: the hook calls the scripts via `node` directly (no pnpm/npm
 // assumption). Re-running is safe — the script detects a previously installed hook via
 // the MAGIC_MARKER comment and rewrites only that file.
@@ -17,12 +30,11 @@ import { writeFile, readFile, mkdir, chmod } from 'node:fs/promises';
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const ROOT = resolve(__dirname, '..');
-const HOOKS_DIR = resolve(ROOT, '.git/hooks');
-const PRE_COMMIT_PATH = resolve(HOOKS_DIR, 'pre-commit');
 
 const readProjectName = () => {
   try {
@@ -36,7 +48,58 @@ const readProjectName = () => {
 
 const MAGIC_MARKER = `# ${readProjectName()}:install-git-hooks.mjs`;
 
-const PRE_COMMIT_CONTENT = `#!/usr/bin/env bash
+// git's own hooks location (worktree-correct), or null outside a git checkout.
+const gitHooksDir = () => {
+  const r = spawnSync('git', ['rev-parse', '--git-path', 'hooks'], { cwd: ROOT, encoding: 'utf8', windowsHide: true });
+  if (r.error || r.status !== 0) return null;
+  return resolve(ROOT, r.stdout.replace(/\r?\n$/, ''));
+};
+
+// The exact shape this installer writes — the strict carry-forward parse anchors on it
+// (quoted path + a bare ` --check` tail; nothing else in the managed hook matches).
+const GUARD_LINE_RE = /^node "([^"]+)" --check$/;
+
+const ARGV = process.argv.slice(2);
+
+// The optional commit-guard line: an explicit --commit-guard <path> arms it (resolved at install
+// time); --no-commit-guard is the one consented disable; both together are a usage error —
+// never an order-dependent pick.
+const resolveGuardFlags = (argv) => {
+  const at = argv.indexOf('--commit-guard');
+  const noGuard = argv.includes('--no-commit-guard');
+  if (at !== -1 && noGuard) {
+    console.error('[install-git-hooks] --commit-guard and --no-commit-guard contradict each other — pass exactly one');
+    process.exit(2);
+  }
+  if (noGuard) return { mode: 'disable' };
+  if (at === -1) return { mode: 'carry' };
+  const given = argv[at + 1];
+  if (!given) {
+    console.error('[install-git-hooks] --commit-guard needs a path');
+    process.exit(2);
+  }
+  const abs = resolve(ROOT, given);
+  if (!existsSync(abs)) {
+    console.error(`[install-git-hooks] --commit-guard ${abs} does not exist`);
+    process.exit(1);
+  }
+  return { mode: 'arm', path: abs };
+};
+
+// Flagless re-runs carry the armed guard forward from the MANAGED hook — strictly parsed:
+// exactly one guard-shaped line keeps its path; none keeps the hook plain; more than one is
+// ambiguous and fails CLOSED (an installer must never guess which line was the real guard).
+const carriedGuardPath = (existingHook) => {
+  if (existingHook === null) return null;
+  const matches = existingHook.split('\n').map((l) => GUARD_LINE_RE.exec(l)).filter(Boolean);
+  if (matches.length > 1) {
+    console.error(`[install-git-hooks] the managed pre-commit hook carries ${matches.length} commit-guard --check lines — ambiguous; remove the duplicates by hand and re-run (refusing to guess)`);
+    process.exit(1);
+  }
+  return matches.length === 1 ? matches[0][1] : null;
+};
+
+const preCommitContent = (guardPath) => `#!/usr/bin/env bash
 ${MAGIC_MARKER}
 # Auto-installed by scripts/install-git-hooks.mjs (run it from "prepare" or by hand).
 # Runs the docs cap-validator + index-freshness gate + rotation-freshness checks
@@ -50,32 +113,41 @@ node scripts/archive-changelog.mjs --check
 node scripts/archive-issues.mjs --check
 node scripts/archive-decisions.mjs --check
 node --test scripts/*.test.mjs
-`;
+${guardPath ? `node "${guardPath}" --check\n` : ''}`;
 
 const main = async () => {
-  if (!existsSync(resolve(ROOT, '.git'))) {
-    console.log('[install-git-hooks] .git directory not found — skipping (not a git checkout).');
+  const flags = resolveGuardFlags(ARGV);
+  const hooksDir = gitHooksDir();
+  if (hooksDir === null) {
+    console.log('[install-git-hooks] git cannot resolve a hooks path here — skipping (not a git checkout).');
     return;
   }
-  await mkdir(HOOKS_DIR, { recursive: true });
+  const preCommitPath = resolve(hooksDir, 'pre-commit');
 
-  if (existsSync(PRE_COMMIT_PATH)) {
-    const existing = await readFile(PRE_COMMIT_PATH, 'utf8');
-    if (existing.includes(MAGIC_MARKER) && existing === PRE_COMMIT_CONTENT) {
-      console.log('[install-git-hooks] pre-commit already up to date.');
-      return;
-    }
+  let existing = null;
+  if (existsSync(preCommitPath)) {
+    existing = await readFile(preCommitPath, 'utf8');
     if (!existing.includes(MAGIC_MARKER)) {
       console.warn(
-        '[install-git-hooks] WARNING: .git/hooks/pre-commit exists and was not installed by this script. Refusing to overwrite — remove or merge it manually.',
+        `[install-git-hooks] WARNING: ${preCommitPath} exists and was not installed by this script. Refusing to overwrite — remove or merge it manually.`,
       );
       process.exit(1);
     }
   }
 
-  await writeFile(PRE_COMMIT_PATH, PRE_COMMIT_CONTENT, 'utf8');
-  await chmod(PRE_COMMIT_PATH, 0o755);
-  console.log('[install-git-hooks] installed .git/hooks/pre-commit (docs caps + index freshness + archive checks + scripts/ tests).');
+  const guardPath = flags.mode === 'arm' ? flags.path : flags.mode === 'disable' ? null : carriedGuardPath(existing);
+  const content = preCommitContent(guardPath);
+  if (existing === content) {
+    console.log('[install-git-hooks] pre-commit already up to date.');
+    return;
+  }
+
+  await mkdir(hooksDir, { recursive: true });
+  await writeFile(preCommitPath, content, 'utf8');
+  await chmod(preCommitPath, 0o755);
+  console.log(
+    `[install-git-hooks] installed ${preCommitPath} (docs caps + index freshness + archive checks + scripts/ tests${guardPath ? ' + commit guard' : ''}).`,
+  );
 };
 
 main().catch((err) => {

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

@@ -0,0 +1,102 @@
+// install-git-hooks.test.mjs — spec for the pre-commit installer (strip-the-kit round-1 folds):
+// the hooks path comes from git plumbing (a linked worktree resolves ITS OWN hooks path, never a
+// hardcoded `.git/hooks`), and an armed commit-guard line SURVIVES a flagless re-run (exactly one
+// strictly-parsed canonical guard line carries forward; --no-commit-guard is the only consented
+// disable; both flags together are a usage error; a duplicated guard line fails closed).
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, cpSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const INSTALLER_SRC = join(HERE, 'install-git-hooks.mjs');
+
+// The installer anchors ROOT at <its dir>/.. — deploy it into a fixture's scripts/ like a consumer.
+const mkProject = () => {
+  const root = mkdtempSync(join(tmpdir(), 'install-hooks-'));
+  const g = (...a) => spawnSync('git', a, { cwd: root, encoding: 'utf8' });
+  g('init', '-q');
+  g('config', 'user.email', 'p@e');
+  g('config', 'user.name', 'p');
+  mkdirSync(join(root, 'scripts'), { recursive: true });
+  cpSync(INSTALLER_SRC, join(root, 'scripts', 'install-git-hooks.mjs'));
+  writeFileSync(join(root, 'guard.mjs'), '// a stand-in commit-guard tool\n');
+  writeFileSync(join(root, 'base.txt'), 'base\n');
+  g('add', '-A');
+  g('commit', '-qm', 'base');
+  return { root, g };
+};
+
+const runInstaller = (root, args = []) =>
+  spawnSync('node', [join(root, 'scripts', 'install-git-hooks.mjs'), ...args], { cwd: root, encoding: 'utf8' });
+
+const hooksPathOf = (root) => {
+  const r = spawnSync('git', ['rev-parse', '--git-path', 'hooks'], { cwd: root, encoding: 'utf8' });
+  return resolve(root, r.stdout.trim());
+};
+
+describe('install-git-hooks — the hooks path comes from git plumbing (C7)', () => {
+  it('a normal repo installs at the git-path hooks location', () => {
+    const { root } = mkProject();
+    const r = runInstaller(root);
+    assert.equal(r.status, 0, r.stderr);
+    assert.ok(existsSync(join(hooksPathOf(root), 'pre-commit')), 'the hook lands where git says hooks live');
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('a LINKED WORKTREE installs at ITS OWN git-path hooks (never a hardcoded <worktree>/.git/hooks)', () => {
+    const { root, g } = mkProject();
+    const wt = join(root, '..', `wt-${Date.now() % 1e6}`);
+    g('worktree', 'add', '-q', wt);
+    mkdirSync(join(wt, 'scripts'), { recursive: true });
+    cpSync(INSTALLER_SRC, join(wt, 'scripts', 'install-git-hooks.mjs'));
+    const r = runInstaller(wt);
+    assert.equal(r.status, 0, r.stderr);
+    const expected = join(hooksPathOf(wt), 'pre-commit');
+    assert.ok(existsSync(expected), `the worktree hook lands at git's own answer (${expected})`);
+    assert.ok(!existsSync(join(wt, '.git', 'hooks', 'pre-commit')), 'never a literal <worktree>/.git/hooks (a worktree .git is a FILE)');
+    rmSync(wt, { recursive: true, force: true });
+    rmSync(root, { recursive: true, force: true });
+  });
+});
+
+describe('install-git-hooks — the commit-guard arm persists (C8)', () => {
+  it('an armed guard SURVIVES a later flagless re-run (carried forward from the managed hook)', () => {
+    const { root } = mkProject();
+    assert.equal(runInstaller(root, ['--commit-guard', 'guard.mjs']).status, 0);
+    const armed = readFileSync(join(hooksPathOf(root), 'pre-commit'), 'utf8');
+    assert.match(armed, /guard\.mjs" --check/, 'the guard line is written armed');
+    assert.equal(runInstaller(root).status, 0, 'the flagless canonical re-run succeeds');
+    const after = readFileSync(join(hooksPathOf(root), 'pre-commit'), 'utf8');
+    assert.match(after, /guard\.mjs" --check/, 'the armed guard line survives a flagless re-run');
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('--no-commit-guard is the ONLY consented disable; combining both flags is a usage error', () => {
+    const { root } = mkProject();
+    assert.equal(runInstaller(root, ['--commit-guard', 'guard.mjs']).status, 0);
+    assert.equal(runInstaller(root, ['--no-commit-guard']).status, 0);
+    const after = readFileSync(join(hooksPathOf(root), 'pre-commit'), 'utf8');
+    assert.doesNotMatch(after, /" --check$/m, 'the guard line is removed on the explicit disable');
+    const both = runInstaller(root, ['--commit-guard', 'guard.mjs', '--no-commit-guard']);
+    assert.equal(both.status, 2, 'both flags together are a usage error, never an order-dependent pick');
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('a DUPLICATED/malformed guard line in the managed hook fails CLOSED on a flagless re-run', () => {
+    const { root } = mkProject();
+    assert.equal(runInstaller(root, ['--commit-guard', 'guard.mjs']).status, 0);
+    const hookPath = join(hooksPathOf(root), 'pre-commit');
+    const armed = readFileSync(hookPath, 'utf8');
+    const guardLine = armed.split('\n').find((l) => /" --check$/.test(l));
+    writeFileSync(hookPath, `${armed}${guardLine}\n`); // duplicate the guard line
+    const r = runInstaller(root);
+    assert.equal(r.status, 1, 'two guard lines are ambiguous — fail closed, never guess');
+    assert.match(r.stderr, /guard/i);
+    rmSync(root, { recursive: true, force: true });
+  });
+});