@sabaiway/agent-workflow-memory 8.2.1 → 8.4.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to the memory substrate. Versions are this **package's** npm
 they are distinct from the **deployment-lineage** stamp written into a project's
 `docs/ai/.memory-version` (which tracks the shared `agent-workflow` lineage, head `4.0.0`).
 
+## 8.4.0 — the commit hook runs your own scripts/pre-commit.local first (AD-195)
+
+**Your own commit checks now have a place of their own: `scripts/pre-commit.local`.** Every hook that
+`references/scripts/install-git-hooks.mjs` writes carries, right after `set -e`, a comment line naming that file and
+`if [ -f scripts/pre-commit.local ]; then bash scripts/pre-commit.local; fi`, so the file runs with bash before the
+docs and scripts lines.
+
+- A non-zero exit of the file stops the commit; with no such file the hook runs as before.
+- The installer never writes, reads or ships the file, and no flag turns the line off.
+- A hook this installer wrote gains the line the next time the installer runs (`prepare`, or by hand); a hook it
+  did not write is refused as before.
+- `install-git-hooks-repo-exec.test.mjs` proves it through real commits: the file runs before the docs check, an exit
+  1 stops the commit, and an absent file lets it through.
+
+MINOR: two new lines in every written hook.
+
+## 8.3.0 — the hook installer arms the project-rules check and the layout check (AD-193)
+
+**`references/scripts/install-git-hooks.mjs` gains `--rules-check <path>` and `--layout-check <path>`.** Each writes
+`node "<absolute path>" --check` followed by its role comment, `# rules-check` or `# layout-check`, after the docs and
+scripts lines and before the commit-guard line.
+
+- A flagless run keeps each armed line by its role; two lines of one role exit 1 naming the role. No flag removes
+  them.
+- `--rules-check` takes only a path to `rules-cli.mjs` and `--layout-check` only one to `source-size-check.mjs`; a path
+  holding `"`, `$`, a backtick, a backslash, CR or LF exits 2 (on Windows the path's `\` become `/` first). A missing
+  file exits 1, a flag without a value exits 2; each writes nothing.
+- Over a hook with neither line, a flagless or `--commit-guard` run writes exactly the hook 4.0.0 to 8.2.1 wrote.
+- Its two test suites strip every inherited git variable before they run git, so they also pass inside the
+  pre-commit hook.
+
+MINOR: two new flags. The paths arrive from the caller; the kit's `hook-checks` item passes its own tools.
+
 ## 8.2.1 — the architecture template points to the layout rules instead of a fixed set of layers (AD-191)
 
 `references/templates/architecture.md`: the lead line drops "Layers", and the Layers and Module Boundaries sections

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: '8.2.1'
+  version: '8.4.0'
 ---
 
 # agent-workflow-memory

package/capability.json

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

package/package.json

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

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

@@ -3,11 +3,14 @@
 // 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.
+// lanes, the rules-check and layout-check arm/carry/duplicate/refusal lanes (win32 included), the
+// unmanaged refusal, the up-to-date short-circuit, the not-a-git-checkout skip, and the S71
+// real-commit lane (real `git commit` through the written hook over stand-in scripts). Every child
+// runs with each inherited GIT_* variable stripped, so a hook's environment never leaks in.
 
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, writeFileSync, readFileSync, rmSync, existsSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, existsSync, realpathSync, chmodSync, statSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -15,20 +18,38 @@ import { spawnSync } from 'node:child_process';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const INSTALLER = join(HERE, 'install-git-hooks.mjs');
+const WIN32 = ['--import', 'data:text/javascript,Object.defineProperty(process,"platform",{value:"win32"})'];
+const BACKSLASH = String.fromCharCode(92);
+const shown = (path) => (process.platform === 'win32' ? path.replaceAll(BACKSLASH, '/') : path);
+
+const BASE_ENV = Object.fromEntries(Object.entries(process.env).filter(([key]) => !/^[Gg][Ii][Tt]_/.test(key)));
+const envAt = (home, extra = {}) => ({
+  ...BASE_ENV, HOME: home, XDG_CONFIG_HOME: join(home, '.config'), LC_ALL: 'C', GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_SYSTEM: '/dev/null',
+  GIT_CONFIG_NOSYSTEM: '1', GIT_ATTR_NOSYSTEM: '1', ...extra,
+});
+
+// A child that never started or was killed has no exit status to judge — it fails the cell outright.
+const spawnChecked = (command, args, options) => {
+  const r = spawnSync(command, args, { encoding: 'utf8', ...options });
+  if (r.error) throw r.error;
+  if (r.signal !== null) throw new Error(`${command} was killed by ${r.signal}`);
+  return r;
+};
 
 const mkRepo = () => {
-  const root = mkdtempSync(join(tmpdir(), 'hooks-repo-exec-'));
-  spawnSync('git', ['init', '-q'], { cwd: root, encoding: 'utf8' });
+  const root = realpathSync(mkdtempSync(join(tmpdir(), 'hooks-repo-exec-')));
+  assert.equal(spawnChecked('git', ['init', '-q'], { cwd: root, env: envAt(root) }).status, 0);
   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 runAt = (gitDir, args = [], pre = []) =>
+  spawnChecked(process.execPath, [...pre, INSTALLER, ...args], { env: envAt(dirname(gitDir), { GIT_DIR: gitDir }) });
 
 const hookOf = ({ gitDir }) => readFileSync(join(gitDir, 'hooks', 'pre-commit'), 'utf8');
+const stub = (root, rel) => (mkdirSync(dirname(join(root, rel)), { recursive: true }), writeFileSync(join(root, rel), '// a stand-in tool\n'), join(root, rel));
 
 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', () => {
@@ -71,6 +92,36 @@ describe('install-git-hooks — the in-place installer under a GIT_DIR-pinned fi
     rmSync(fx.root, { recursive: true, force: true });
   });
 
+  it('the role lanes: arm both beside the guard in order → carry → duplicate fails closed; each refusal writes nothing', () => {
+    const fx = mkRepo();
+    const [rules, layout, guard] = ['t/rules-cli.mjs', 't/source-size-check.mjs', 'guard.mjs'].map((rel) => stub(fx.root, rel));
+    const ok = (args, pre) => { const r = runAt(fx.gitDir, args, pre); assert.equal(r.status, 0, r.stderr); return r; };
+    ok(['--commit-guard', guard, '--layout-check', layout, '--rules-check', rules]);
+    const tail = `node "${shown(rules)}" --check # rules-check\nnode "${shown(layout)}" --check # layout-check\nnode "${guard}" --check\n`;
+    assert.ok(hookOf(fx).endsWith(`node --test scripts/*.test.mjs\n${tail}`), hookOf(fx));
+    assert.match(ok([]).stdout, /already up to date/, 'the flagless re-run carries all three');
+    const before = hookOf(fx);
+    const cases = [
+      [['--rules-check', layout], 2], [['--layout-check', rules], 2], [['--rules-check'], 2], [['--layout-check'], 2],
+      [['--layout-check', join(fx.root, 'a$b', 'source-size-check.mjs')], 2], [['--rules-check', join(fx.root, 'no', 'rules-cli.mjs')], 1],
+      ...(process.platform === 'win32' ? [] : [[['--rules-check', `${fx.root}/w${BACKSLASH}x/rules-cli.mjs`], 2]]),
+    ];
+    for (const [args, status] of cases) {
+      const r = runAt(fx.gitDir, args);
+      assert.equal(r.status, status, `${JSON.stringify(args)}: ${r.stderr}`);
+      assert.equal(hookOf(fx), before, `${JSON.stringify(args)} wrote nothing`);
+    }
+    const winArmed = stub(fx.root, 'w/x/rules-cli.mjs');
+    ok(['--rules-check', `${fx.root}/w${BACKSLASH}x/rules-cli.mjs`], WIN32);
+    assert.ok(hookOf(fx).includes(`node "${shown(winArmed)}" --check # rules-check\n`), 'the win32 path arms with / separators');
+    const winHook = hookOf(fx);
+    writeFileSync(join(fx.gitDir, 'hooks', 'pre-commit'), `${winHook}node "${layout}" --check # layout-check\n`);
+    const dup = runAt(fx.gitDir);
+    assert.equal(dup.status, 1, dup.stderr);
+    assert.match(dup.stderr, /carries 2 layout-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'));
@@ -80,3 +131,55 @@ describe('install-git-hooks — the in-place installer under a GIT_DIR-pinned fi
     rmSync(nowhere, { recursive: true, force: true });
   });
 });
+
+// The commit lane also drops NODE_TEST_CONTEXT: an inherited one makes the hook's nested `node --test` skip every file.
+const IDENTITY = { GIT_AUTHOR_NAME: 'p', GIT_AUTHOR_EMAIL: 'p@e', GIT_COMMITTER_NAME: 'p', GIT_COMMITTER_EMAIL: 'p@e' };
+const bareAt = (home, extra = {}) => { const { NODE_TEST_CONTEXT: _, ...env } = envAt(home, { ...IDENTITY, ...extra }); return env; };
+const passes = (r) => (assert.equal(r.status, 0, r.stderr), r);
+
+// Passing stand-ins for every script the hook runs; check-docs-size.mjs, run right after the local line, records
+// whether the marker existed. The marker and the record live in a sibling dir, outside the work tree.
+const commitRepo = (root, side) => {
+  const [marker, record, local] = [join(side, 'marker'), join(side, 'record'), join(root, 'scripts', 'pre-commit.local')];
+  const git = (...args) => spawnChecked('git', args, { cwd: root, env: bareAt(root) });
+  mkdirSync(join(root, 'scripts'));
+  writeFileSync(join(root, 'scripts', 'check-docs-size.mjs'), `import { existsSync, writeFileSync } from 'node:fs';
+if (!process.argv.includes('--check-index')) writeFileSync(${JSON.stringify(record)}, String(existsSync(${JSON.stringify(marker)})));\n`);
+  for (const name of ['archive-changelog', 'archive-issues', 'archive-decisions']) writeFileSync(join(root, 'scripts', `${name}.mjs`), 'process.exit(0);\n');
+  writeFileSync(join(root, 'scripts', 'stand-in.test.mjs'), "import { test } from 'node:test';\ntest('a passing stand-in', () => {});\n");
+  for (const args of [['init', '-q'], ['add', '-A'], ['commit', '-qm', 'base']]) passes(git(...args));
+  passes(spawnChecked(process.execPath, [INSTALLER], { env: bareAt(root, { GIT_DIR: join(root, '.git') }) }));
+  const head = () => git('rev-parse', 'HEAD').stdout.trim();
+  const commit = (body) => {
+    if (body !== undefined) { writeFileSync(local, body); chmodSync(local, 0o644); assert.equal(statSync(local).mode & 0o111, 0, 'the local file is not executable'); }
+    writeFileSync(join(root, 'change.txt'), 'change\n');
+    passes(git('add', 'change.txt'));
+    return git('commit', '-qm', 'change');
+  };
+  return { marker, record, head, commit };
+};
+const inCommitRepo = (cell) => () => {
+  const dirs = ['hooks-commit-', 'hooks-commit-side-'].map((prefix) => realpathSync(mkdtempSync(join(tmpdir(), prefix))));
+  try { cell(commitRepo(...dirs)); } finally { for (const dir of dirs) rmSync(dir, { recursive: true, force: true }); }
+};
+
+describe('spec:init-project/S71 the local hook file through real commits over stand-ins', () => {
+  it('a local file that writes a marker runs before the docs check, and the commit exits 0', { timeout: 120_000 }, inCommitRepo((fx) => {
+    passes(fx.commit(`printf made > "${fx.marker}"\n`));
+    assert.ok(existsSync(fx.marker), 'the local file ran: its marker appeared');
+    assert.equal(readFileSync(fx.record, 'utf8'), 'true', 'the marker existed when check-docs-size.mjs ran');
+  }));
+
+  it('a local file that exits 1 stops the commit: non-zero, no new commit', { timeout: 120_000 }, inCommitRepo((fx) => {
+    const before = fx.head();
+    assert.notEqual(fx.commit('exit 1\n').status, 0, 'a local file exiting 1 stops the commit');
+    assert.equal(fx.head(), before, 'no new commit');
+  }));
+
+  it('with no local file the commit exits 0', { timeout: 120_000 }, inCommitRepo((fx) => {
+    const before = fx.head();
+    passes(fx.commit());
+    assert.notEqual(fx.head(), before, 'the commit landed');
+    assert.equal(readFileSync(fx.record, 'utf8'), 'false', 'the hook ran its stand-ins, with no marker');
+  }));
+});

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

@@ -6,6 +6,7 @@
 // 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.
+// First after `set -e` it runs the project's own `scripts/pre-commit.local` with bash when present.
 //
 // 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
@@ -20,6 +21,13 @@
 // ambiguous duplicate fails closed); `--no-commit-guard` is the one consented disable; passing
 // both flags together is a usage error.
 //
+// RULES AND LAYOUT CHECKS (optional): `--rules-check <path>` and `--layout-check <path>` arm one line
+// each, `node "<abs>" --check # rules-check` and `node "<abs>" --check # layout-check`, ahead of the
+// guard. The role comment is what a line's role is read by, so the guard rule above never matches
+// either line and a legacy guard line keeps its role whatever its file name. Each takes only its own
+// tool's file name and a path in one safe shell representation (on win32 its separators made `/`),
+// and is carried forward by flagless re-runs exactly as the guard is; no flag disarms either.
+//
 // 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.
@@ -59,6 +67,15 @@ const gitHooksDir = () => {
 // (quoted path + a bare ` --check` tail; nothing else in the managed hook matches).
 const GUARD_LINE_RE = /^node "([^"]+)" --check$/;
 
+// The two role-tagged lines, in hook order, each bound to its own tool's file name.
+const ROLES = [
+  { flag: '--rules-check', role: 'rules-check', file: 'rules-cli.mjs' },
+  { flag: '--layout-check', role: 'layout-check', file: 'source-size-check.mjs' },
+].map((entry) => ({ ...entry, re: new RegExp(`^node "([^"]+)" --check # ${entry.role}$`) }));
+
+// A path the shell would read as anything but itself inside double quotes is refused.
+const SHELL_ACTIVE = /["$`\\\r\n]/;
+
 const ARGV = process.argv.slice(2);
 
 // The optional commit-guard line: an explicit --commit-guard <path> arms it (resolved at install
@@ -86,6 +103,44 @@ const resolveGuardFlags = (argv) => {
   return { mode: 'arm', path: abs };
 };
 
+// A role flag arms its line with the resolved path in its one safe shell representation, or refuses.
+const resolveRoleFlag = (argv, { flag, file }) => {
+  const at = argv.indexOf(flag);
+  if (at === -1) return null;
+  const given = argv[at + 1];
+  if (!given) {
+    console.error(`[install-git-hooks] ${flag} needs a path`);
+    process.exit(2);
+  }
+  const resolved = resolve(ROOT, given);
+  const abs = process.platform === 'win32' ? resolved.replaceAll('\\', '/') : resolved;
+  if (basename(abs) !== file) {
+    console.error(`[install-git-hooks] ${flag} takes a path to ${file}, got ${abs}`);
+    process.exit(2);
+  }
+  if (SHELL_ACTIVE.test(abs)) {
+    console.error(`[install-git-hooks] ${flag} ${JSON.stringify(abs)} carries ", $, a backtick, a backslash, CR or LF — inside the hook's quotes it would not name that file; refusing to arm it`);
+    process.exit(2);
+  }
+  if (!existsSync(abs)) {
+    console.error(`[install-git-hooks] ${flag} ${abs} does not exist`);
+    process.exit(1);
+  }
+  return abs;
+};
+
+// Flagless re-runs carry each armed role line forward by the guard's rule: one keeps its path, none
+// leaves it out, more than one fails CLOSED naming the role.
+const carriedRolePath = (existingHook, { role, re }) => {
+  if (existingHook === null) return null;
+  const matches = existingHook.split('\n').map((l) => re.exec(l)).filter(Boolean);
+  if (matches.length > 1) {
+    console.error(`[install-git-hooks] the managed pre-commit hook carries ${matches.length} ${role} lines — ambiguous; remove the duplicates by hand and re-run (refusing to guess)`);
+    process.exit(1);
+  }
+  return matches.length === 1 ? matches[0][1] : null;
+};
+
 // 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).
@@ -99,7 +154,7 @@ const carriedGuardPath = (existingHook) => {
   return matches.length === 1 ? matches[0][1] : null;
 };
 
-const preCommitContent = (guardPath) => `#!/usr/bin/env bash
+const preCommitContent = (guardPath, rolePaths = []) => `#!/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
@@ -107,16 +162,19 @@ ${MAGIC_MARKER}
 # declared maxLines, the auto-generated index.md cannot silently go stale, stale
 # archive entries never reach a commit, and regressions to the scripts are caught.
 set -e
+# Your own commit checks go in scripts/pre-commit.local; it runs first, with bash, when present.
+if [ -f scripts/pre-commit.local ]; then bash scripts/pre-commit.local; fi
 node scripts/check-docs-size.mjs
 node scripts/check-docs-size.mjs --check-index
 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` : ''}`;
+${rolePaths.map((path, at) => (path ? `node "${path}" --check # ${ROLES[at].role}\n` : '')).join('')}${guardPath ? `node "${guardPath}" --check\n` : ''}`;
 
 const main = async () => {
   const flags = resolveGuardFlags(ARGV);
+  const roleFlags = ROLES.map((role) => resolveRoleFlag(ARGV, role));
   const hooksDir = gitHooksDir();
   if (hooksDir === null) {
     console.log('[install-git-hooks] git cannot resolve a hooks path here — skipping (not a git checkout).');
@@ -136,7 +194,8 @@ const main = async () => {
   }
 
   const guardPath = flags.mode === 'arm' ? flags.path : flags.mode === 'disable' ? null : carriedGuardPath(existing);
-  const content = preCommitContent(guardPath);
+  const rolePaths = ROLES.map((role, at) => roleFlags[at] ?? carriedRolePath(existing, role));
+  const content = preCommitContent(guardPath, rolePaths);
   if (existing === content) {
     console.log('[install-git-hooks] pre-commit already up to date.');
     return;
@@ -146,7 +205,7 @@ const main = async () => {
   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' : ''}).`,
+    `[install-git-hooks] installed ${preCommitPath} (docs caps + index freshness + archive checks + scripts/ tests${rolePaths.map((path, at) => (path ? ` + ${ROLES[at].role}` : '')).join('')}${guardPath ? ' + commit guard' : ''}).`,
   );
 };
 

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

@@ -1,12 +1,11 @@
-// 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).
+// install-git-hooks.test.mjs — the pre-commit installer on a deployed copy: the hooks path comes from git
+// plumbing (a linked worktree resolves ITS OWN hooks path); the guard, rules-check and layout-check lines
+// are carried by role, fail closed on a duplicate and refuse a bad flag value, writing nothing. Every child
+// runs with each inherited GIT_* variable stripped, so a hook's environment never leaks in.
 
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, cpSync, existsSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, cpSync, existsSync, realpathSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -15,118 +14,228 @@ import { spawnSync } from 'node:child_process';
 const HERE = dirname(fileURLToPath(import.meta.url));
 const INSTALLER_SRC = join(HERE, 'install-git-hooks.mjs');
 const MALFORMED_PACKAGE_JSON = '{ not json';
-const NAMED_PACKAGE_JSON = '{"name":"named-fixture"}';
-const NAMED_FIXTURE = 'named-fixture';
+const [NAMED_PACKAGE_JSON, NAMED_FIXTURE] = ['{"name":"named-fixture"}', 'named-fixture'];
+const WIN32 = ['--import', 'data:text/javascript,Object.defineProperty(process,"platform",{value:"win32"})'];
+const BACKSLASH = String.fromCharCode(92);
+const SHELL_ACTIVE = [34, 36, 96, 92, 13, 10].map((code) => String.fromCharCode(code)).filter((ch) => process.platform !== 'win32' || ch !== BACKSLASH);
+const shown = (path) => (process.platform === 'win32' ? path.replaceAll(BACKSLASH, '/') : path);
+
+const BASE_ENV = Object.fromEntries(Object.entries(process.env).filter(([key]) => !/^[Gg][Ii][Tt]_/.test(key)));
+const envAt = (home) => ({
+  ...BASE_ENV, HOME: home, XDG_CONFIG_HOME: join(home, '.config'), LC_ALL: 'C', GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_SYSTEM: '/dev/null',
+  GIT_CONFIG_NOSYSTEM: '1', GIT_ATTR_NOSYSTEM: '1', GIT_AUTHOR_NAME: 'p', GIT_AUTHOR_EMAIL: 'p@e', GIT_COMMITTER_NAME: 'p', GIT_COMMITTER_EMAIL: 'p@e',
+});
+
+// A child that never started or was killed has no exit status to judge — it fails the cell outright.
+const spawnChecked = (command, args, cwd) => {
+  const r = spawnSync(command, args, { cwd, env: envAt(cwd), encoding: 'utf8' });
+  if (r.error) throw r.error;
+  if (r.signal !== null) throw new Error(`${command} was killed by ${r.signal}`);
+  return r;
+};
+const succeeds = (r) => { assert.equal(r.status, 0, r.stderr); return r; };
+const git = (cwd, ...args) => succeeds(spawnChecked('git', args, cwd));
 
 // 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' });
+  const root = realpathSync(mkdtempSync(join(tmpdir(), 'install-hooks-')));
+  const g = (...a) => git(root, ...a);
   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');
+  for (const args of [['add', '-A'], ['commit', '-qm', 'base']]) g(...args);
   return { root, g };
 };
+const inProject = (cell) => () => { const fx = mkProject(); try { cell(fx); } finally { rmSync(fx.root, { recursive: true, force: true }); } };
 
-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());
-};
+const runInstaller = (root, args = [], pre = []) =>
+  spawnChecked(process.execPath, [...pre, join(root, 'scripts', 'install-git-hooks.mjs'), ...args], root);
+const installs = (...a) => succeeds(runInstaller(...a));
 
+const hooksPathOf = (root) => resolve(root, git(root, 'rev-parse', '--git-path', 'hooks').stdout.trim());
 const markerFor = (name) => `# ${name}:install-git-hooks.mjs`;
 const readHook = (root) => readFileSync(join(hooksPathOf(root), 'pre-commit'), 'utf8');
+const stub = (root, rel) => (mkdirSync(dirname(join(root, rel)), { recursive: true }), writeFileSync(join(root, rel), '// a stand-in tool\n'), join(root, rel));
+
+// The hook the 8.3.0 installer body writes with no guard: the six docs and scripts lines.
+const plainHook = (root) => `#!/usr/bin/env bash
+${markerFor(basename(root))}
+# 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
+# + the scripts/ test suite before every commit, so files cannot drift over their
+# declared maxLines, the auto-generated index.md cannot silently go stale, stale
+# archive entries never reach a commit, and regressions to the scripts are caught.
+set -e
+node scripts/check-docs-size.mjs
+node scripts/check-docs-size.mjs --check-index
+node scripts/archive-changelog.mjs --check
+node scripts/archive-issues.mjs --check
+node scripts/archive-decisions.mjs --check
+node --test scripts/*.test.mjs
+`;
+const LOCAL_LINE = 'if [ -f scripts/pre-commit.local ]; then bash scripts/pre-commit.local; fi';
+// The plain hook every write carries: the 8.3.0 hook with, right after set -e, one `# ` comment naming
+// scripts/pre-commit.local (its wording is free, so it is read from the written hook) and the exact local line.
+const localHook = (root) => {
+  const lines = readHook(root).split('\n');
+  const comment = lines[lines.indexOf('set -e') + 1];
+  assert.ok(comment?.startsWith('# ') && comment.includes('scripts/pre-commit.local'), `right after set -e a # comment names scripts/pre-commit.local, got ${JSON.stringify(comment)}`);
+  assert.deepEqual(lines.filter((l) => l.includes('scripts/pre-commit.local')), [comment, LOCAL_LINE], 'the comment and the local line are the only lines naming scripts/pre-commit.local');
+  return plainHook(root).replace('set -e\n', `set -e\n${comment}\n${LOCAL_LINE}\n`);
+};
+const line = (path, role) => `node "${role ? shown(path) : path}" --check${role ? ` # ${role}` : ''}\n`;
 
-describe('install-git-hooks \u2014 beside no package.json, or a malformed one, the marker names the directory basename', () => {
-  it('no package.json, then a MALFORMED one \u2014 the marker names the directory basename', () => {
-    const { root } = mkProject();
+describe('install-git-hooks — beside no package.json, or a malformed one, the marker names the directory basename', () => {
+  it('no package.json, then a MALFORMED one — the marker names the directory basename', inProject(({ root }) => {
     const expected = markerFor(basename(root));
-    const absent = runInstaller(root);
-    assert.equal(absent.status, 0, absent.stderr);
+    installs(root);
     assert.ok(readHook(root).split('\n').includes(expected));
     writeFileSync(join(root, 'package.json'), MALFORMED_PACKAGE_JSON);
-    const malformed = runInstaller(root);
-    assert.equal(malformed.status, 0, malformed.stderr);
+    installs(root);
     assert.ok(readHook(root).split('\n').includes(expected));
-    rmSync(root, { recursive: true, force: true });
-  });
+  }));
 
-  it('a named package.json wins \u2014 the marker carries its name', () => {
-    const { root } = mkProject();
+  it('a named package.json wins — the marker carries its name', inProject(({ root }) => {
     writeFileSync(join(root, 'package.json'), NAMED_PACKAGE_JSON);
-    const result = runInstaller(root);
-    assert.equal(result.status, 0, result.stderr);
+    installs(root);
     assert.ok(readHook(root).split('\n').includes(markerFor(NAMED_FIXTURE)));
-    rmSync(root, { recursive: true, force: true });
-  });
+  }));
 });
 
 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);
+  it('a normal repo installs at the git-path hooks location', inProject(({ root }) => {
+    installs(root);
     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();
+  it('a LINKED WORKTREE installs at ITS OWN git-path hooks (never a hardcoded <worktree>/.git/hooks)', inProject(({ root, g }) => {
     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 });
-  });
+    try {
+      mkdirSync(join(wt, 'scripts'), { recursive: true });
+      cpSync(INSTALLER_SRC, join(wt, 'scripts', 'install-git-hooks.mjs'));
+      installs(wt);
+      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)');
+    } finally {
+      rmSync(wt, { 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();
+  it('an armed guard SURVIVES a later flagless re-run (carried forward from the managed hook)', inProject(({ root }) => {
     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.match(readHook(root), /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 });
-  });
+    assert.match(readHook(root), /guard\.mjs" --check/, 'the armed guard line survives a flagless re-run');
+  }));
 
-  it('--no-commit-guard is the ONLY consented disable; combining both flags is a usage error', () => {
-    const { root } = mkProject();
+  it('--no-commit-guard is the ONLY consented disable; combining both flags is a usage error', inProject(({ root }) => {
     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');
+    assert.doesNotMatch(readHook(root), /" --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();
+  it('a DUPLICATED/malformed guard line in the managed hook fails CLOSED on a flagless re-run', inProject(({ root }) => {
     assert.equal(runInstaller(root, ['--commit-guard', 'guard.mjs']).status, 0);
-    const hookPath = join(hooksPathOf(root), 'pre-commit');
-    const armed = readFileSync(hookPath, 'utf8');
+    const armed = readHook(root);
     const guardLine = armed.split('\n').find((l) => /" --check$/.test(l));
-    writeFileSync(hookPath, `${armed}${guardLine}\n`); // duplicate the guard line
+    writeFileSync(join(hooksPathOf(root), 'pre-commit'), `${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 });
-  });
+  }));
+});
+
+describe('spec:init-project/S58 install-git-hooks — the rules-check and layout-check lines on a deployed copy', () => {
+  it('each flag writes its resolved path and role comment, ordered docs, rules, layout, guard; a flagless re-run keeps all three; --commit-guard replaces and --no-commit-guard drops the guard alone', inProject(({ root }) => {
+    const [rules, layout, guard, guard2] = ['tools/rules-cli.mjs', 'tools/source-size-check.mjs', 'guard.mjs', 'g2/guard.mjs'].map((rel) => stub(root, rel));
+    installs(root, ['--commit-guard', 'guard.mjs']);
+    installs(root, ['--layout-check', 'tools/source-size-check.mjs']);
+    assert.equal(readHook(root), localHook(root) + line(layout, 'layout-check') + line(guard), 'the --layout-check run carried the guard line');
+    installs(root, ['--rules-check', rules]);
+    const armed = localHook(root) + line(rules, 'rules-check') + line(layout, 'layout-check');
+    assert.equal(readHook(root), armed + line(guard), 'each arming run carried the other armed lines');
+    assert.match(installs(root).stdout, /already up to date/, 'a flagless re-run keeps all three');
+    assert.equal(readHook(root), armed + line(guard));
+    installs(root, ['--commit-guard', guard2]);
+    assert.equal(readHook(root), armed + line(guard2), '--commit-guard replaces the guard line alone');
+    installs(root, ['--no-commit-guard']);
+    assert.equal(readHook(root), armed, '--no-commit-guard drops the guard line alone');
+  }));
+
+  it('a legacy guard line whose file name is rules-cli.mjs keeps the guard role beside a rules line', inProject(({ root }) => {
+    const [legacy, rules] = ['legacy/rules-cli.mjs', 'tools/rules-cli.mjs'].map((rel) => stub(root, rel));
+    installs(root, ['--commit-guard', legacy]);
+    installs(root, ['--rules-check', rules]);
+    const expected = localHook(root) + line(rules, 'rules-check') + line(legacy);
+    assert.equal(readHook(root), expected);
+    installs(root);
+    assert.equal(readHook(root), expected, 'the flagless re-run keeps the legacy line as the guard');
+  }));
+
+  it('two lines of one role exit 1 naming that role, the hook unchanged', inProject(({ root }) => {
+    installs(root, ['--rules-check', stub(root, 'tools/rules-cli.mjs'), '--layout-check', stub(root, 'tools/source-size-check.mjs')]);
+    const armed = readHook(root);
+    for (const role of ['rules-check', 'layout-check']) {
+      const roleLine = armed.split('\n').find((l) => l.endsWith(` --check # ${role}`));
+      assert.ok(roleLine, `the ${role} line is armed`);
+      writeFileSync(join(hooksPathOf(root), 'pre-commit'), `${armed}${roleLine}\n`);
+      const r = runInstaller(root);
+      assert.equal(r.status, 1, r.stderr);
+      assert.match(r.stderr, new RegExp(`carries 2 ${role} lines`));
+      assert.equal(readHook(root), `${armed}${roleLine}\n`);
+    }
+  }));
+
+  it('over a hook with no rules or layout line, a flagless and a --commit-guard run write the plain hook with the comment line and the local line right after set -e', inProject(({ root }) => {
+    installs(root);
+    assert.equal(readHook(root), localHook(root));
+    installs(root, ['--commit-guard', 'guard.mjs']);
+    assert.equal(readHook(root), localHook(root) + line(join(root, 'guard.mjs')));
+  }));
+
+  it('a wrong file name, a shell-active path or a missing value exits 2, a missing file exits 1, each writing nothing', inProject(({ root }) => {
+    const [rules, layout] = ['tools/rules-cli.mjs', 'tools/source-size-check.mjs'].map((rel) => stub(root, rel));
+    installs(root, ['--commit-guard', 'guard.mjs']);
+    const before = readHook(root);
+    const cases = [
+      [['--rules-check', layout], 2, /--rules-check takes a path to rules-cli\.mjs/],
+      [['--layout-check', rules], 2, /--layout-check takes a path to source-size-check\.mjs/],
+      ...SHELL_ACTIVE.flatMap((ch, at) => [
+        [['--rules-check', join(root, `r${at}${ch}x`, 'rules-cli.mjs')], 2, /a backslash, CR or LF/],
+        [['--layout-check', join(root, `l${at}${ch}x`, 'source-size-check.mjs')], 2, /a backslash, CR or LF/],
+      ]),
+      [['--rules-check', join(root, 'nowhere', 'rules-cli.mjs')], 1, /does not exist/],
+      [['--layout-check', join(root, 'nowhere', 'source-size-check.mjs')], 1, /does not exist/],
+      [['--rules-check'], 2, /--rules-check needs a path/],
+      [['--layout-check'], 2, /--layout-check needs a path/],
+    ];
+    for (const [args, status, message] of cases) {
+      const r = runInstaller(root, args);
+      assert.equal(r.status, status, `${JSON.stringify(args)}: ${r.stderr}`);
+      assert.match(r.stderr, message);
+      assert.equal(readHook(root), before, `${JSON.stringify(args)} wrote nothing`);
+    }
+  }));
+
+  it('an ordinary win32 path, its separators made /, arms and a flagless re-run carries it; on posix it is the backslash refusal', inProject(({ root }) => {
+    installs(root);
+    const given = `${root}/a${BACKSLASH}b/rules-cli.mjs`;
+    const armedAt = stub(root, 'a/b/rules-cli.mjs');
+    if (process.platform !== 'win32') { // there the backslash is refused, writing nothing
+      const posix = runInstaller(root, ['--rules-check', given]);
+      assert.deepEqual([posix.status, /a backslash, CR or LF/.test(posix.stderr), readHook(root)], [2, true, localHook(root)], posix.stderr);
+    }
+    installs(root, ['--rules-check', given], WIN32);
+    assert.equal(readHook(root), localHook(root) + line(armedAt, 'rules-check'));
+    assert.match(installs(root).stdout, /already up to date/, 'the flagless re-run recognises the win32-armed line');
+    assert.equal(readHook(root), localHook(root) + line(armedAt, 'rules-check'));
+  }));
 });