@sabaiway/agent-workflow-kit 2.1.0 → 3.1.0

package/references/modes/worktrees.md

@@ -0,0 +1,120 @@
+### Mode: worktrees
+
+Parallel feature worktrees (v1) — several features implemented simultaneously in DIFFERENT agent
+sessions on one machine/repo, zero interference on working-tree files (the ONE exception: the
+default `node_modules` symlink is a shared MUTABLE dependency cache — see below), unambiguous
+ownership. One thin tool over git; every verification datum is recomputed live from git, never
+read from stored metadata.
+The ONE stored-metadata exception is the PREPARED OID recorded in the handoff: land and cleanup read it back only for recovery.
+
+**Run** — `node ${CLAUDE_SKILL_DIR}/tools/worktrees.mjs <subcommand> …`:
+
+Git ≥ 2.36 is required for NUL-terminated worktree porcelain; an older Git fails closed with its
+own verbatim error through the existing Git-error surface.
+
+- `provision <slug> --plan <path> [--as <name>.md] [--dir <path>] [--branch <name>] [--include <path>]... [--install] [--resume]`
+  — create a feature worktree (default: the visible sibling `<repoParent>/<repoName>--<slug>`,
+  branch `aw/<slug>`) and populate it: the registry-derived footprint copy-if-missing (a tracked
+  file is NEVER overwritten), EXACTLY ONE seeded feature plan, the `handoff-<slug>.md` stub
+  (written at provision — the tool's own record; `list` and `cleanup` read it), a
+  `node_modules` symlink when main has one and the link stays ignored — a SHARED MUTABLE cache:
+  writes through it hit MAIN's node_modules; for isolation RUN the printed isolated-install
+  command (`--install` only prints it), and on `--resume` an existing symlink is kept — run the
+  printed unlink-first recovery first. Absolute root-pinned gate commands are rebased on UNTRACKED copies only — and only
+  while their bytes still equal the MAIN source (or its rebased form); user-modified copies stay
+  byte-untouched. `--install` only PRINTS the install command — zero spawn, zero write.
+  `--resume <slug>` completes a half-done provision (identity fail-closed; handoff user sections,
+  the seeded plan, and edited copies are preserved byte-exact; the provision-record section is
+  refreshed atomically; copy-if-missing everywhere).
+  Resume identity also binds the EXISTING handoff: at most one `handoff-<slug>.md` may exist and
+  its recorded slug AND branch must match the live invocation — a second handoff, a name/record
+  mismatch, or a handoff that is not a regular file is a typed STOP before anything is written
+  (the writability probe itself runs only after these checks on a resume). The provision record
+  is read from exactly one REQUIRED `## Provision record` section (a decoy field elsewhere cannot
+  hijack identity); a missing or repeated section, or a duplicated single-valued field, is a typed
+  STOP, never last-wins.
+- `list` — read-only: every worktree of this repo with slug (from the handoff file; none →
+  "unknown (foreign)"), path, branch, base OID (the worktree HEAD — under the v1 no-commit bar
+  that IS the provision base; a manual satellite commit moves it, and land derives its own base
+  live), dirty flag, handoff presence, opener suggestion. Honest read errors: only a genuinely
+  ABSENT docs/plans under a symlink-free, present worktree dir reads as `handoff: no`; a
+  symlinked docs/plans (or ancestor), a handoff-named entry that is not a regular file, a
+  vanished worktree dir, or any other read failure renders `handoff: (unreadable)` — never a
+  silent "no".
+- `land <slug> --prepare` — stage the satellite's finished diff onto a CLEAN main; the commit is
+  NEVER run by the tool — it stays a dialogue ask at the primary session. Land takes the transient
+  common-git-dir lock, refuses a dirty main, graph divergence, visible `docs/ai` drift, excluded
+  staged paths, unstaged/untracked leftovers, an empty diff, or a red satellite review-state. The
+  complete satellite working-tree diff versus its base is inspected (staged and unstaged); every
+  unstaged/untracked path is listed and refused, so an accepted transfer cannot silently omit it.
+  The binary/no-ext-diff/no-textconv transfer excludes exactly `docs/ai` and `docs/plans`, applies
+  into the index, optionally runs the porcelain-visible sync adapter, then runs the main gate
+  matrix. It reports main HEAD, TRANSFER, PREPARED, and sync delta OIDs/data; the primary re-attests
+  that prepared tree and confirms main HEAD still equals the printed OID before the commit ask.
+- `cleanup <slug> [--branch <name>] [--abandon]` — take the same transient lock and remove a LANDED
+  worktree fail-closed after live landed-verification against main HEAD. Verification uses exactly
+  the land exclusions (`docs/ai`, `docs/plans`), then checks untracked and ignored content before a
+  plain worktree remove, branch `-d`, and prune. Provision-derived ignored containers are ephemeral;
+  `node_modules` of any kind is provision-derivable because provision explicitly advises installs.
+  Foreign content stops cleanup. `--abandon` is the ONE destructive arm: it DESTROYS unlanded work,
+  requires the handoff identity, and is the only path where `--force` may appear.
+
+**Honesty:** there is NO preview step on the writers — over-warned by design. The tool never
+commits, never pushes, never runs a subscription CLI. Every content read and regular-file copy
+goes through its one no-follow descriptor door (identity-bound source, exclusive destination,
+descriptor mode update), and tripwire tests keep them the only paths.
+
+**Settings:** the parent dir for new worktrees is the `docs/ai/worktrees.json` `{"parentDir": …}`
+project setting (hand-editable strict JSON; absent file → the sibling default; malformed → a
+typed STOP, never a guess). The file must be a REGULAR, non-symlink file reached through a
+symlink-free path — anything else is a typed STOP (the advisor renders the same shape as a
+stated skip), and the ancestor chain is verified even when the leaf is ABSENT (a symlinked
+`docs/` or `docs/ai` never reads as plain absence). `--dir` overrides per invocation.
+
+**Host-specific consent (zero-prompt only where the host honors it):** every sibling-dir mutation
+runs a REAL create+delete writability probe first. An unwritable parent prints both the
+settings-native line (`sandbox.filesystem.allowWrite` in `.claude/settings.json`) and the full
+terminal command. On a settings-native host that honors the key, adding the parent can make later
+provision/cleanup promptless. On a harness-managed host that ignores project settings, grant the
+narrow parent through the host/session controls; if that is unavailable, use the printed terminal
+command for each operation. The `recommendations` mode surfaces this lane but treats write access
+as unverified without a trusted host-capability signal.
+
+**Landing flow:** provision → work → handoff → land → re-attest → commit → cleanup. Satellite
+commits are outside v1: graph divergence stops land and prints cherry-pick/rebase recovery. A gate
+failure keeps the prepared main tree and names both recovery lanes. A second prepare is reset-only:
+the STOP prints the current staged write-tree, compares it with the PREPARED OID recorded in the
+handoff, distinguishes a converged re-run from foreign staged work, and lists removal commands for
+untracked crash residue before the reset-and-re-run lane. A killed process may leave
+`aw-prepare-lock`; after confirming no land/cleanup process owns it, remove that directory by hand.
+
+The optional `scripts/sync-mirrors.mjs` adapter runs as a child. Its contract is porcelain-visible
+output: tracked modifications/deletions or untracked-not-ignored creations. Ignored writes and
+changes inside an already-untracked file are outside observation and therefore out of contract.
+Cleanup reports EBUSY as likely lingering processes/open file descriptors (including a sandbox
+mount); close them and retry, outside the sandbox when needed. Hidden satellite `docs/ai` state is
+ephemeral by design; durable content belongs in the handoff before landing — the handoff carries a
+free-form session-records digest slot (every section outside `## Provision record` is user-owned
+and byte-preserved by the tool).
+
+**Ownership:** MAIN owns MAIN-tree files, commits, pushes, releases, the gate matrix, every
+docs/ai record, `docs/plans/queue.md`, and all shared git state — stash, hooks, repo config,
+`.git/info/exclude`, and every ref except the satellite's configured branch. The SATELLITE owns
+that one branch (`aw/<slug>` or the `--branch` override), its feature edits, its seeded plan, and
+the user-owned handoff sections; `## Provision record` remains tool-owned. Satellite forbidden
+verbs (the v1 docs-only bar): no `git commit`/`push`/`tag`/`git stash`/history rewrite — the ONE
+legal rewrite is the tool-printed `git reset --hard` recovery of the satellite's OWN configured
+branch (`aw/<slug>` or the `--branch` override) — no kit lifecycle writers
+(`init`/`upgrade`/`setup`/`hide-footprint`/`install-git-hooks`/`sandbox-masks`/`ack-write`), no
+queue.md writes, no version bumps or publishes, no edits to MAIN's files from the satellite
+session — divergence and the landed verification enforce the observable half; the rest is the
+stated contract. A symlinked `node_modules` under npm workspaces resolves
+workspace self-links to MAIN-tree sources — use the printed isolated install when that matters.
+
+**Other harnesses:** PROVEN — the host-installed codex/agy review wrappers run with a provisioned
+worktree as their cwd; the footprint carries the root `AGENTS.md` required by the codex wrappers
+and available to agy as its fallback project context. The host-level `bridge-settings.conf` under
+`${XDG_CONFIG_HOME:-~/.config}/agent-workflow/` is per-host, shared by every worktree, and is not
+copied into the worktree. ASSUMED until probed per harness — each target harness's project-local
+settings and context pickup in a fresh worktree session; treat that as unverified until the target
+harness demonstrates it.

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

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) => {