@sabaiway/agent-workflow-memory 8.2.1 → 8.3.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ 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.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.3.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.3.0",
   "provides": ["context"],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "8.2.1",
+  "version": "8.3.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,13 @@
 // 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, and the not-a-git-checkout skip. 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 } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -15,20 +17,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 +91,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'));

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

@@ -20,6 +20,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 +66,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 +102,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 +153,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
@@ -113,10 +167,11 @@ 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 +191,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 +202,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,217 @@ 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));
 
-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();
+// The hook the 4.0.0-8.2.1 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 line = (path, role) => `node "${role ? shown(path) : path}" --check${role ? ` # ${role}` : ''}\n`;
+
+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']);
+    installs(root, ['--rules-check', rules]);
+    const armed = plainHook(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 = plainHook(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 4.0.0-8.2.1 bytes', inProject(({ root }) => {
+    installs(root);
+    assert.equal(readHook(root), plainHook(root));
+    installs(root, ['--commit-guard', 'guard.mjs']);
+    assert.equal(readHook(root), plainHook(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, plainHook(root)], posix.stderr);
+    }
+    installs(root, ['--rules-check', given], WIN32);
+    assert.equal(readHook(root), plainHook(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), plainHook(root) + line(armedAt, 'rules-check'));
+  }));
 });