@sabaiway/agent-workflow-kit 2.0.0 → 3.0.0

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

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

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

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

package/references/scripts/migrate-gates-branches.test.mjs

@@ -0,0 +1,157 @@
+// migrate-gates-branches.test.mjs — the refusal/no-op branch pins the main spec file leaves
+// unexercised (colocated so the D3(d) changed-line check reads real executions, not intentions):
+// the --help arm, the missing-declaration no-op, the invalid-shape STOP, the honest no-op split
+// on final-run-capability, the mid-write parent-verification failure (fail closed + tmp cleanup),
+// and the loud-but-non-fatal retired-store cleanup error.
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, readdirSync, lstatSync, rmSync, symlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { UNIT_TESTS_COVERAGE_FLAGS, RETIRED_STORE_BASENAMES, main } from './migrate-gates.mjs';
+
+const KIT_TOOLS = mkdtempSync(join(tmpdir(), 'migrate-branches-kit-'));
+writeFileSync(join(KIT_TOOLS, 'coverage-check.mjs'), '// the installed checker the migration points at\n');
+
+const mkProject = (gates) => {
+  const root = mkdtempSync(join(tmpdir(), 'migrate-branches-'));
+  mkdirSync(join(root, 'docs', 'ai'), { recursive: true });
+  if (gates !== undefined) {
+    writeFileSync(join(root, 'docs', 'ai', 'gates.json'), typeof gates === 'string' ? gates : `${JSON.stringify({ gates }, null, 2)}\n`);
+  }
+  return root;
+};
+const quiet = () => {
+  const out = [];
+  const err = [];
+  return { log: (l) => out.push(String(l)), error: (l) => err.push(String(l)), out, err };
+};
+
+const UNIT_DONE = { id: 'unit-tests', title: 'U', cmd: `node --test ${UNIT_TESTS_COVERAGE_FLAGS} tools/*.test.mjs` };
+const CHECKER = { id: 'coverage-check', title: 'CC', cmd: `node "${join(KIT_TOOLS, 'coverage-check.mjs')}" --check` };
+const REVIEW_STATE = { id: 'review-state', title: 'RS', cmd: `node "${join(KIT_TOOLS, 'review-state.mjs')}" --check` };
+const LEGACY = { id: 'review-ledger', title: 'L', cmd: 'node "/kit/tools/review-ledger.mjs" --check' };
+const UNIT = { id: 'unit-tests', title: 'U', cmd: 'node --test tools/*.test.mjs' };
+
+describe('migrate-gates — refusal and no-op branches', () => {
+  it('--help prints the contract and exits 0', () => {
+    const io = quiet();
+    assert.equal(main(['--help'], io), 0);
+    assert.match(io.out.join('\n'), /Usage:/);
+  });
+
+  it('the no-op split is HONEST about final-run-capability (capable names it; incapable never does)', () => {
+    const capable = mkProject([UNIT_DONE, REVIEW_STATE, CHECKER]);
+    const io = quiet();
+    assert.equal(main(['--cwd', capable, '--kit-tools', KIT_TOOLS], io), 0);
+    assert.match(io.out.join('\n'), /already final-run-capable/);
+    rmSync(capable, { recursive: true, force: true });
+
+    const incapable = mkProject([UNIT_DONE, CHECKER]);
+    const io2 = quiet();
+    assert.equal(main(['--cwd', incapable, '--kit-tools', KIT_TOOLS], io2), 0);
+    const text = io2.out.join('\n');
+    assert.match(text, /nothing to migrate mechanically/);
+    assert.match(text, /NOT final-run-capable/);
+    assert.doesNotMatch(text, /already final-run-capable/);
+    rmSync(incapable, { recursive: true, force: true });
+  });
+
+  it('docs/ai WITHOUT a gates.json (and no stores) is a stated no-op, never a crash', () => {
+    const root = mkProject(undefined);
+    const io = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS], io), 0);
+    assert.match(io.out.join('\n'), /nothing to migrate/);
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('a parseable-but-invalid declaration ({ gates: <non-array> }) is a loud STOP', () => {
+    const root = mkProject('{ "gates": 5 }\n');
+    const io = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS, '--apply'], io), 1);
+    assert.match(io.err.join('\n'), /not a \{ gates/);
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('an lstat failure DURING the write fails CLOSED — nothing written, the tmp cleaned', () => {
+    const root = mkProject([LEGACY, UNIT]);
+    const before = readFileSync(join(root, 'docs', 'ai', 'gates.json'), 'utf8');
+    const tmpExists = () => readdirSync(join(root, 'docs', 'ai')).some((f) => f.endsWith('.tmp'));
+    const io = {
+      ...quiet(),
+      // Fail the parent verification the moment the tmp file exists — that is exactly the
+      // PRE-RENAME re-check, whatever the lstat call count is (count-anchored injection went
+      // silently stale once loadDeclaration became an lstat consumer too).
+      lstat: (p) => {
+        if (tmpExists()) throw Object.assign(new Error('injected EACCES'), { code: 'EACCES' });
+        return lstatSync(p);
+      },
+    };
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS, '--apply'], io), 1);
+    assert.match(io.err.join('\n'), /cannot verify the declaration parent/);
+    assert.equal(readFileSync(join(root, 'docs', 'ai', 'gates.json'), 'utf8'), before, 'the declaration is untouched');
+    assert.deepEqual(readdirSync(join(root, 'docs', 'ai')).filter((f) => f.endsWith('.tmp')), [], 'no tmp litter survives (the writer catch cleaned it)');
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('a NON-canonical entry squatting the checker id is a loud STOP on preview AND apply (never a duplicate row)', () => {
+    const squatter = { id: 'coverage-check', title: 'C', cmd: 'node scripts/coverage-check.mjs --check' };
+    const root = mkProject([squatter, UNIT]);
+    for (const argv of [['--cwd', root, '--kit-tools', KIT_TOOLS], ['--cwd', root, '--kit-tools', KIT_TOOLS, '--apply']]) {
+      const io = quiet();
+      assert.equal(main(argv, io), 1, `must STOP: ${argv.join(' ')}`);
+      assert.match(io.err.join('\n'), /id collision/);
+    }
+    const after = JSON.parse(readFileSync(join(root, 'docs', 'ai', 'gates.json'), 'utf8')).gates;
+    assert.equal(after.filter((g) => g.id === 'coverage-check').length, 1, 'nothing was written');
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('a canonical checker addressed THROUGH A SYMLINKED kit dir is recognized (realpath, never lexical)', () => {
+    const linked = join(tmpdir(), `migrate-branches-link-${process.pid}`);
+    rmSync(linked, { force: true });
+    symlinkSync(KIT_TOOLS, linked);
+    const throughLink = { id: 'coverage-check', title: 'CC', cmd: `node "${join(linked, 'coverage-check.mjs')}" --check` };
+    const root = mkProject([throughLink, UNIT]);
+    const io = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS], io), 0, io.err.join('\n'));
+    const text = io.out.join('\n');
+    assert.doesNotMatch(text, /id collision/, 'the symlinked canonical checker is never a collision');
+    assert.doesNotMatch(text, /ADD coverage-check/, 'no duplicate checker is added');
+    rmSync(linked, { force: true });
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('a NON-ENOENT lstat failure on the gates.json LEAF is a loud STOP — never read as "missing"', () => {
+    const root = mkProject([LEGACY, UNIT]);
+    spawnSync('git', ['init', '-q'], { cwd: root, encoding: 'utf8' });
+    writeFileSync(join(root, '.git', RETIRED_STORE_BASENAMES[0]), '{"dead":1}\n');
+    const io = {
+      ...quiet(),
+      lstat: (p) => {
+        if (p.endsWith('gates.json')) throw Object.assign(new Error('injected EACCES'), { code: 'EACCES' });
+        return lstatSync(p);
+      },
+    };
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS, '--apply'], io), 1, 'an unreadable declaration must STOP the apply');
+    assert.match(io.err.join('\n'), /EACCES/);
+    assert.ok(lstatSync(join(root, '.git', RETIRED_STORE_BASENAMES[0])).isFile(), 'the retired store is untouched on the STOP');
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('an un-unlinkable retired store is reported LOUDLY and never fails the migration', () => {
+    const root = mkProject([LEGACY, UNIT]);
+    spawnSync('git', ['init', '-q'], { cwd: root, encoding: 'utf8' });
+    // A DIRECTORY at the store path: existsSync sees it, unlink refuses (EISDIR/EPERM) — the
+    // deterministic un-unlinkable shape (permission bits vary by runner; a dir does not).
+    mkdirSync(join(root, '.git', RETIRED_STORE_BASENAMES[0]), { recursive: true });
+    const io = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS, '--apply'], io), 0);
+    const text = io.out.join('\n');
+    assert.match(text, /could not clean .*review-ledger\.jsonl/, 'the cleanup failure is named');
+    assert.match(text, /migrated .*gates\.json/, 'the migration itself still landed');
+    rmSync(root, { recursive: true, force: true });
+  });
+});