simt-dev 0.7.0 → 0.8.0

package/src/hooks/dispatcher.mjs

@@ -18,22 +18,129 @@
 //   Report what did not run. The summary names every gate, its disposition and
 //   its reason, so "passed" can never be mistaken for "only some of it passed".
 
-import { execFile } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import { mkdtemp, readFile, rm, stat, symlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, join, matchesGlob, resolve, sep } from 'node:path';
-import { promisify } from 'node:util';
 
-import { GATES } from './gates.mjs';
+import { GATES, getGate } from './gates.mjs';
 import { resolveGate } from './resolve.mjs';
 import { resolveNodeRunner } from '../ecosystem/node-runner.mjs';
 import { CLI } from '../name.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
 import { assertVersionPin } from '../package-version.mjs';
-import { recordRun } from '../ledger/index.mjs';
+import { hasTestEvidence, readLedger, recordRun } from '../ledger/index.mjs';
 import { renderFindings, scanStaged } from '../secrets.mjs';
+import { git, gitPaths, gitText } from '../sys/git.mjs';
 
-const exec = promisify(execFile);
+/**
+ * The default bound on one gate, in seconds, and the grace a killed gate gets before
+ * SIGKILL. A hook that runs on every commit needs a ceiling: a test runner waiting on
+ * a socket that never closes blocks the commit with no output and no way to tell a
+ * hang from slow work. `gates.timeout` raises or removes it per repository.
+ */
+const DEFAULT_GATE_TIMEOUT_SECONDS = 600;
+const KILL_GRACE_MS = 5000;
+
+/**
+ * How much of a gate's output a report can carry. This is a bound on what is KEPT, not
+ * on what the process may write: a gate whose output exceeded execFile's buffer used to
+ * be reported `failed` although it exited 0.
+ */
+const GATE_OUTPUT_TAIL_BYTES = 64 * 1024;
+
+function tailCollector() {
+  let kept = Buffer.alloc(0);
+  let dropped = 0;
+  return {
+    push(chunk) {
+      kept = Buffer.concat([kept, chunk]);
+      if (kept.length > GATE_OUTPUT_TAIL_BYTES) {
+        dropped += kept.length - GATE_OUTPUT_TAIL_BYTES;
+        kept = kept.subarray(kept.length - GATE_OUTPUT_TAIL_BYTES);
+      }
+    },
+    text: () => kept.toString('utf8'),
+    dropped: () => dropped,
+  };
+}
+
+/**
+ * Signal the gate's whole process group. A test runner spawns workers of its own, and
+ * signalling only the leader leaves them holding the pipes this function is waiting on.
+ * `detached` in the spawn below is what makes the group exist.
+ */
+function signalTree(child, signal) {
+  try {
+    process.kill(-child.pid, signal);
+  } catch {
+    try {
+      child.kill(signal);
+    } catch {
+      // Already gone: a second signal has nothing to reach.
+    }
+  }
+}
+
+/**
+ * Run one gate to completion, keeping its exit code and the tail of what it printed.
+ *
+ * `timeoutMs` of 0 means no bound, which is what `gates.timeout: 0` asks for and what
+ * the manifest does not have to say. Output is collected in full while the process
+ * runs and only the tail is retained, so a noisy passing gate passes.
+ */
+async function runBounded(argv, { cwd, env, timeoutMs }) {
+  return await new Promise((settle) => {
+    let child;
+    try {
+      child = spawn(argv[0], argv.slice(1), { cwd, env, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (error) {
+      settle({ code: 1, stdout: '', stderr: String(error.message ?? error), timedOut: false, dropped: 0 });
+      return;
+    }
+    const out = tailCollector();
+    const err = tailCollector();
+    let timedOut = false;
+    let timer = null;
+    let killer = null;
+    let done = false;
+    const finish = (code) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      clearTimeout(killer);
+      settle({ code, stdout: out.text(), stderr: err.text(), timedOut, dropped: out.dropped() + err.dropped() });
+    };
+    child.stdout?.on('data', (chunk) => out.push(chunk));
+    child.stderr?.on('data', (chunk) => err.push(chunk));
+    // A missing binary emits `error` and no `close`; the message is the only evidence.
+    child.on('error', (error) => {
+      err.push(Buffer.from(String(error.message ?? error)));
+      finish(1);
+    });
+    child.on('close', (code, signal) => finish(typeof code === 'number' ? code : signal === null ? 0 : 1));
+    if (timeoutMs > 0) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        signalTree(child, 'SIGTERM');
+        killer = setTimeout(() => signalTree(child, 'SIGKILL'), KILL_GRACE_MS);
+      }, timeoutMs);
+    }
+  });
+}
+
+/**
+ * The bound for one gate, in milliseconds. A number applies to every gate; a map applies
+ * per name, the shape `gates.cwd` already has. A value that is neither a positive whole
+ * number of seconds nor 0 falls back to the default rather than removing the bound: an
+ * unreadable declaration must not be the quiet way to disable the ceiling.
+ */
+function gateTimeoutMs(declared, name) {
+  const value = declared !== null && typeof declared === 'object' ? declared[name] : declared;
+  if (value === 0) return 0;
+  if (Number.isInteger(value) && value > 0) return value * 1000;
+  return DEFAULT_GATE_TIMEOUT_SECONDS * 1000;
+}
 
 /** Gates that are known but not required for the event to pass. */
 const DEFAULT_EVENTS = { 'pre-commit': 'preCommit', 'pre-push': 'prePush' };
@@ -85,15 +192,14 @@ export function parsePushedRefs(text) {
 async function tagCommitAccountedFor(root, tagSha, pushingTips) {
   let commit;
   try {
-    ({ stdout: commit } = await exec('git', ['rev-parse', `${tagSha}^{commit}`], { cwd: root }));
+    commit = await gitText(root, ['rev-parse', `${tagSha}^{commit}`]);
   } catch (error) {
     return { ok: false, reason: `the tag could not be resolved to a commit: ${String(error.stderr ?? error.message).trim()}` };
   }
-  commit = commit.trim();
 
   let remoteRefs;
   try {
-    ({ stdout: remoteRefs } = await exec('git', ['for-each-ref', 'refs/remotes/', '--format=%(refname)'], { cwd: root }));
+    remoteRefs = await gitText(root, ['for-each-ref', 'refs/remotes/', '--format=%(refname)']);
   } catch (error) {
     return { ok: false, reason: `the remote refs could not be listed: ${String(error.stderr ?? error.message).trim()}` };
   }
@@ -106,7 +212,7 @@ async function tagCommitAccountedFor(root, tagSha, pushingTips) {
   }
   for (const candidate of candidates) {
     try {
-      await exec('git', ['merge-base', '--is-ancestor', commit, candidate], { cwd: root });
+      await git(root, ['merge-base', '--is-ancestor', commit, candidate]);
       return { ok: true, reason: null };
     } catch {
       // not reachable from this ref; try the next candidate
@@ -148,15 +254,17 @@ export async function classifyPush(root, refs, { maxCommits, paths }) {
     }
     let count, names;
     try {
-      ({ stdout: count } = await exec('git', ['rev-list', '--count', `${remoteSha}..${localSha}`], { cwd: root }));
-      ({ stdout: names } = await exec('git', ['diff', '--name-only', `${remoteSha}..${localSha}`], { cwd: root }));
+      count = await gitText(root, ['rev-list', '--count', `${remoteSha}..${localSha}`]);
+      names = await gitPaths(root, ['diff', '--name-only', `${remoteSha}..${localSha}`]);
     } catch (error) {
       return { docsOnly: false, reason: `the push could not be diffed: ${String(error.stderr ?? error.message).trim()}` };
     }
-    commits += Number(count.trim());
-    for (const f of names.split('\n')) {
-      const name = f.trim();
-      if (name !== '') files.add(name);
+    commits += Number(count);
+    // NUL-separated paths because a path can contain a newline, and git quotes such a
+    // name in the line-terminated form, so splitting on newlines compares a quoted path
+    // against an unquoted glob and never matches.
+    for (const name of names) {
+      files.add(name);
     }
   }
 
@@ -178,7 +286,11 @@ export async function classifyPush(root, refs, { maxCommits, paths }) {
   if (commits > 0) parts.push(`${commits} commit(s) touching ${files.size} file(s), all inside the docs-only paths`);
   if (tags.length > 0) parts.push(`${tags.length} tag(s) already delivered`);
   if (deletions > 0) parts.push(`${deletions} ref deletion(s)`);
-  return { docsOnly: true, reason: parts.length > 0 ? parts.join('; ') : 'no commits carried' };
+  if (parts.length === 0) return { docsOnly: true, reason: 'no commits carried' };
+  // The report prints this as-is (ADR-113). The label names what is being pushed:
+  // a push that carries only tags is a tag push, not a docs-only push.
+  const kind = commits > 0 ? 'docs-only push' : tags.length > 0 ? 'tag push' : 'deletion push';
+  return { docsOnly: true, reason: `${kind}: ${parts.join('; ')}` };
 }
 
 /**
@@ -189,7 +301,7 @@ export async function classifyPush(root, refs, { maxCommits, paths }) {
  * review. A misdeclaration (missing fields) also runs the suite - a skip the
  * manifest cannot state precisely is a skip a reviewer cannot see.
  *
- * @returns {Promise<{reason: string} | null>} null runs the suite; a reason skips the `test` gate
+ * @returns {Promise<{reason: string, adr: string} | null>} null runs the suite; a reason skips the `test` gate
  */
 async function resolveDocsOnlySkip(root, manifest, pushed) {
   if (pushed === undefined) return null;
@@ -200,7 +312,43 @@ async function resolveDocsOnlySkip(root, manifest, pushed) {
     return null; // the caller cannot be sure what is being pushed; the suite runs
   }
   const verdict = await classifyPush(root, refs, { maxCommits: config.maxCommits, paths: config.paths });
-  return verdict.docsOnly ? { reason: verdict.reason } : null;
+  return verdict.docsOnly ? { reason: verdict.reason, adr: 'ADR-113' } : null;
+}
+
+/**
+ * The pre-push skip for a suite the author already ran on this exact tree (ADR-120).
+ *
+ * The dispatcher records every gate run against the tree it ran on (ADR-087). If a passing
+ * `test` run is recorded for the committed tree about to be pushed, and nothing has changed
+ * since, re-running the full suite at push time buys nothing: it is the same tree, already
+ * proven. This reads that evidence and earns the same reported skip the docs-only path does.
+ *
+ * It matches the COMMITTED tree (`HEAD^{tree}`), not the working tree: the pre-push gate runs
+ * at HEAD, so the evidence that matters is a pass on exactly that tree. A file edited after
+ * the green pass changes the tree id, so the match fails and the suite runs - the "no changes
+ * since" condition is enforced by the digest, not by trusting the author. Every uncertainty -
+ * an unborn HEAD, an unreadable ledger, no entry for this tree, a later failure - fails closed
+ * to the suite.
+ *
+ * @param {string} root the real repository root
+ * @returns {Promise<{reason: string} | null>} null runs the suite; a reason skips the `test` gate
+ */
+async function resolveAlreadyPassedSkip(root) {
+  let headTree;
+  try {
+    headTree = await gitText(root, ['rev-parse', 'HEAD^{tree}']);
+  } catch {
+    return null;
+  }
+  if (!/^[0-9a-f]{40}$/.test(headTree)) return null;
+  const { entries, errors } = await readLedger(root);
+  if (errors.length > 0) return null;
+  if (!hasTestEvidence(entries, headTree)) return null;
+  return {
+    reason:
+      'already passing on current state: the test gate ran green on this tree and nothing has changed since',
+    adr: 'ADR-120',
+  };
 }
 
 /**
@@ -263,10 +411,12 @@ export async function runGates(event, { root, manifest, pushed }) {
   let headWorktree = null;
   let skipTest = null;
   if (event === 'pre-push') {
-    // Decided before the worktree exists: a push that carries only documentation
-    // skips the `test` gate (ADR-113), and a push that earns the skip needs no
-    // tree for a gate that will not run.
-    skipTest = await resolveDocsOnlySkip(root, manifest, pushed);
+    // Decided before the worktree exists: a push that carries only documentation skips the
+    // `test` gate (ADR-113), and a push whose tree the author already proved green skips it
+    // on that evidence (ADR-120). A push that earns either skip needs no tree for a gate
+    // that will not run.
+    skipTest = (await resolveDocsOnlySkip(root, manifest, pushed)) ??
+      (await resolveAlreadyPassedSkip(root));
     if (skipTest === null) {
       const materialized = await materializeHeadWorktree(root);
       if (materialized.path === null) {
@@ -312,8 +462,9 @@ export async function runGates(event, { root, manifest, pushed }) {
  * @param {object} ctx.manifest
  * @param {string[]} ctx.declared the gate names for this event
  * @param {string} ctx.key the manifest key for this event
- * @param {{reason: string} | null} [ctx.skipTest] set when a docs-only push skips the
- *   `test` gate (ADR-113); the reason is what the report prints in its place
+ * @param {{reason: string, adr: string} | null} [ctx.skipTest] set when a push skips the
+ *   `test` gate (ADR-113 for docs-only, ADR-120 for an already-green tree); the reason is
+ *   what the report prints in its place, and the adr is the record that earned it
  * @returns {Promise<{event: string, gates: object[], failed: boolean}>}
  */
 async function runGatesAt(event, { root, ledgerRoot, manifest, declared, key, skipTest = null }) {
@@ -345,13 +496,16 @@ async function runGatesAt(event, { root, ledgerRoot, manifest, declared, key, sk
   // mean re-reading the command string to find out where anything runs, and a manifest
   // written by an older release would have to be rewritten to gain the capability.
   const cwds = manifest?.gates?.cwd ?? {};
+  // `gates.timeout` bounds one gate, in seconds: a number for every gate, or a map by
+  // name like `gates.cwd`. Absent means the default; 0 means no bound, declared.
+  const timeouts = manifest?.gates?.timeout;
   const results = [];
   // What the format gate rewrote, so restage touches those files and nothing else.
   let formatted = [];
 
   for (const name of declared) {
-    const gate = GATES[name];
-    if (gate === undefined) {
+    const gate = getGate(name, commands);
+    if (gate === null) {
       results.push({
         name,
         status: 'failed',
@@ -362,11 +516,12 @@ async function runGatesAt(event, { root, ledgerRoot, manifest, declared, key, sk
       continue;
     }
 
-    // The one gate a docs-only push does not run (ADR-113). It is reported, not
-    // dropped: a skip without a printed reason would let "passed" mean "the suite
-    // never ran", which is the exact confusion the report exists to prevent.
+    // The one gate a push may not run (ADR-113 for a docs-only push, ADR-120 for a tree
+    // already proven green). It is reported, not dropped: a skip without a printed reason
+    // would let "passed" mean "the suite never ran", which is the exact confusion the report
+    // exists to prevent.
     if (skipTest !== null && name === 'test') {
-      results.push({ name, status: 'skipped', detail: `docs-only push: ${skipTest.reason}`, adr: 'ADR-113', exitCode: null });
+      results.push({ name, status: 'skipped', detail: skipTest.reason, adr: skipTest.adr, exitCode: null });
       continue;
     }
 
@@ -476,8 +631,9 @@ async function runGatesAt(event, { root, ledgerRoot, manifest, declared, key, sk
       cwd = resolved;
     }
 
+    const timeoutMs = gateTimeoutMs(timeouts, name);
     const started = Date.now();
-    const outcome = await runGate(resolution, cwd);
+    const outcome = await runGate(resolution, cwd, timeoutMs);
     // The ledger is not the gate. A tree that cannot be named leaves no line, and the
     // claim check then finds nothing, which is the direction that cannot invent a run.
     try {
@@ -498,11 +654,18 @@ async function runGatesAt(event, { root, ledgerRoot, manifest, declared, key, sk
     } catch {
       // Recorded by absence: the next evidence read for this tree has no line.
     }
+    // A killed gate has no exit code of its own (`signal` instead), so the reason is
+    // stated rather than left to `exit 1`, and the remedy says how to change the bound.
     results.push({
       name,
       status: outcome.code === 0 ? 'passed' : 'failed',
-      detail: `${resolution.detail}${outcome.code === 0 ? '' : `: exit ${outcome.code}`}`,
+      detail: outcome.timedOut
+        ? `${resolution.detail}: timed out after ${Math.round(timeoutMs / 1000)} s`
+        : `${resolution.detail}${outcome.code === 0 ? '' : `: exit ${outcome.code}`}`,
       output: outcome.code === 0 ? '' : tail(outcome.stderr || outcome.stdout),
+      ...(outcome.timedOut
+        ? { remedy: `fix the hang, raise gates.timeout to give it longer, or set gates.timeout to 0 to remove the bound` }
+        : {}),
       adr: gate.adr,
       exitCode: outcome.code,
     });
@@ -560,7 +723,7 @@ async function runGatesAt(event, { root, ledgerRoot, manifest, declared, key, sk
 async function materializeHeadWorktree(root) {
   const path = await mkdtemp(join(tmpdir(), 'head-gate-'));
   try {
-    await exec('git', ['worktree', 'add', '--detach', path, 'HEAD'], { cwd: root });
+    await git(root, ['worktree', 'add', '--detach', path, 'HEAD']);
   } catch (error) {
     await rm(path, { recursive: true, force: true }).catch(() => {});
     return { path: null, error: `git worktree add failed: ${String(error.stderr ?? error.message).trim()}` };
@@ -585,9 +748,9 @@ async function materializeHeadWorktree(root) {
  * @param {string} path the worktree to remove
  */
 async function removeHeadWorktree(root, path) {
-  await exec('git', ['worktree', 'remove', '--force', path], { cwd: root }).catch(async () => {
+  await git(root, ['worktree', 'remove', '--force', path]).catch(async () => {
     await rm(path, { recursive: true, force: true }).catch(() => {});
-    await exec('git', ['worktree', 'prune'], { cwd: root }).catch(() => {});
+    await git(root, ['worktree', 'prune']).catch(() => {});
   });
 }
 
@@ -616,13 +779,8 @@ export function renderGateReport(event, declared, result) {
   return lines;
 }
 
-async function run(argv, cwd, env) {
-  try {
-    const { stdout, stderr } = await exec(argv[0], argv.slice(1), { cwd, env, maxBuffer: 8 * 1024 * 1024 });
-    return { code: 0, stdout, stderr };
-  } catch (error) {
-    return { code: typeof error.code === 'number' ? error.code : 1, stdout: error.stdout ?? '', stderr: error.stderr ?? String(error.message ?? error) };
-  }
+async function run(argv, cwd, env, timeoutMs) {
+  return await runBounded(argv, { cwd, env, timeoutMs });
 }
 
 /** The built-in gates this dispatcher can run, by name. */
@@ -693,24 +851,15 @@ async function runBuiltinGate(name, { root, staged, options }) {
  * that the two sources stay distinguishable, which is why this is a separate branch
  * rather than a flag on `run`.
  */
-async function runGate(resolution, cwd) {
+async function runGate(resolution, cwd, timeoutMs) {
   // The push override is for the push itself, not for the gates the hook runs.
   // A test that asserts a push is denied sees the override and fails.
   const env = { ...process.env };
   delete env.SIMT_ALLOW;
   if (resolution.shell === true && typeof resolution.command === 'string') {
-    try {
-      const { stdout, stderr } = await exec('sh', ['-c', resolution.command], { cwd, env, maxBuffer: 8 * 1024 * 1024 });
-      return { code: 0, stdout, stderr };
-    } catch (error) {
-      return {
-        code: typeof error.code === 'number' ? error.code : 1,
-        stdout: error.stdout ?? '',
-        stderr: error.stderr ?? String(error.message ?? error),
-      };
-    }
+    return await run(['sh', '-c', resolution.command], cwd, env, timeoutMs);
   }
-  return run(resolution.argv, cwd, env);
+  return await run(resolution.argv, cwd, env, timeoutMs);
 }
 
 async function readPkg(root) {
@@ -724,8 +873,9 @@ async function readPkg(root) {
 /** Staged paths, or [] when git cannot answer (an unborn branch, for instance). */
 export async function stagedFiles(root) {
   try {
-    const { stdout } = await exec('git', ['diff', '--cached', '--name-only', '--diff-filter=ACMR'], { cwd: root });
-    return stdout.split('\n').map((s) => s.trim()).filter(Boolean);
+    // NUL-separated: git quotes a path containing a newline or a quote in the line form,
+    // and a quoted name is not the path the index holds, so it never matches a staged blob.
+    return await gitPaths(root, ['diff', '--cached', '--name-only', '--diff-filter=ACMR']);
   } catch {
     return [];
   }
@@ -741,8 +891,7 @@ export async function stagedFiles(root) {
  */
 async function unstagedFiles(root) {
   try {
-    const { stdout } = await exec('git', ['diff', '--name-only'], { cwd: root });
-    return new Set(stdout.split('\n').map((s) => s.trim()).filter(Boolean));
+    return new Set(await gitPaths(root, ['diff', '--name-only']));
   } catch {
     return new Set();
   }
@@ -752,7 +901,7 @@ async function unstagedFiles(root) {
 async function stagedBlobs(root, files) {
   if (files.length === 0) return new Map();
   try {
-    const { stdout } = await exec('git', ['ls-files', '-s', '--', ...files], { cwd: root });
+    const stdout = await git(root, ['ls-files', '-s', '--', ...files]);
     const blobs = new Map();
     for (const line of stdout.split('\n')) {
       const [meta, ...rest] = line.split('\t');
@@ -777,7 +926,7 @@ async function restage(root, files) {
   if (files.length === 0) return { restaged: [], error: null };
   const before = await stagedBlobs(root, files);
   try {
-    await exec('git', ['add', '--', ...files], { cwd: root });
+    await git(root, ['add', '--', ...files]);
   } catch (error) {
     return { restaged: [], error: String(error.stderr ?? error.message ?? error).trim() };
   }

package/src/hooks/gates.mjs

@@ -101,49 +101,16 @@ export const GATES = {
   },
 };
 
-export function getGate(name) {
-  return GATES[name] ?? null;
-}
-
-/**
- * A gate a repo cannot run is a FAILURE, never a skip.
- *
- * This is the load-bearing decision of the whole dispatcher. A gate that
- * silently does nothing is indistinguishable from a gate that passed, and the
- * documented consequence in this estate is an agent reaching for
- * `--no-verify` - a repository removed its tests from pre-commit precisely
- * because they were slow, and slow-plus-silent is what teaches everyone that
- * hooks are advisory.
- */
-export function unresolved(name, { hasScript, binary, command, stack }) {
-  const gate = getGate(name);
-  if (gate === null) {
-    return {
-      gate: name,
-      reason: `unknown gate; the shared dispatcher knows: ${Object.keys(GATES).sort().join(', ')}`,
-      remedy: `remove "${name}" from ${MANIFEST_FILE} gates`,
-    };
-  }
-  if (gate.kind === 'script' && !hasScript(gate.script)) {
-    return {
-      gate: name,
-      reason: `no "${gate.script}" script in package.json`,
-      remedy: `add the script, or remove "${name}" from ${MANIFEST_FILE} gates`,
-    };
-  }
-  if (gate.kind === 'command' && !command) {
-    return {
-      gate: name,
-      reason: `no command declared for this gate in ${MANIFEST_FILE}`,
-      remedy: `set gates.commands["${name}"] to the command that proves it, or remove "${name}" from ${MANIFEST_FILE} gates`,
-    };
-  }
-  if (gate.kind === 'staged' && !binary) {
-    return {
-      gate: name,
-      reason: `${gate.tools.join('/')} is not installed in node_modules/.bin`,
-      remedy: `run the repo install command, or remove "format" from ${MANIFEST_FILE} gates`,
-    };
+export function getGate(name, commands = {}) {
+  const declared = GATES[name];
+  if (declared) return declared;
+  // Q70: a command the repository declared under gates.commands is a valid gate even when
+  // no central row knows it. The manifest is the source of truth for a repo's gates, and
+  // a name that resolves to a declared command must not read as unknown. Synthesized, not
+  // added to GATES: the central table stays the estate's gates, the record supplies the rest.
+  const cmd = commands?.[name];
+  if (typeof cmd === 'string' && cmd.trim() !== '') {
+    return { name, kind: 'command', adr: 'ADR-010', why: 'declared by the repository under gates.commands' };
   }
   return null;
 }

package/src/hooks/resolve.mjs

@@ -12,16 +12,11 @@
 
 import { access } from 'node:fs/promises';
 import { constants } from 'node:fs';
-import { join } from 'node:path';
+import { extname, join } from 'node:path';
 
-import { FORMATTABLE, GATES } from './gates.mjs';
+import { FORMATTABLE, GATES, gateNames } from './gates.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
 
-/** Gate names the shared dispatcher knows, sorted. */
-export function knownGates() {
-  return Object.keys(GATES).sort();
-}
-
 /** Is this path an executable file? */
 async function isExecutable(path) {
   try {
@@ -144,7 +139,7 @@ export async function resolveGate(gate, { root, pkg, staged, commands, runner =
         remedy: `run the repo install command, or remove "format" from ${MANIFEST_FILE} gates`,
       };
     }
-    const files = staged.filter((f) => FORMATTABLE.has(extname(f)));
+    const files = staged.filter((f) => FORMATTABLE.has(extname(f).toLowerCase()));
     if (files.length === 0) {
       return {
         ok: true,
@@ -203,11 +198,6 @@ export async function resolveGate(gate, { root, pkg, staged, commands, runner =
     gate: name,
     kind: 'unknown',
     reason: `unknown gate kind "${gate.kind}"`,
-    remedy: `this is a bug in simt-dev; known gates: ${knownGates().join(', ')}`,
+    remedy: `this is a bug in simt-dev; )}', ')}`,
   };
-}
-
-function extname(path) {
-  const dot = path.lastIndexOf('.');
-  return dot > 0 ? path.slice(dot).toLowerCase() : '';
 }

package/src/hooks/shim.mjs

@@ -36,8 +36,11 @@ export const SHIM_MARKER = '# Generated by simt-dev. Do not edit.';
 /** Events the shared dispatcher knows how to run. */
 export const EVENTS = ['pre-commit', 'pre-push'];
 
-/** Directory the shims are written to inside a repo. */
-export const HOOKS_DIR = '.simt-hooks';
+/** Directory the shims are written to inside a repo, inside the state directory (ADR-122). */
+export const HOOKS_DIR = '.simt/hooks';
+
+/** The top-level shim directory that preceded the move into the state directory (ADR-122). */
+export const HOOKS_DIR_LEGACY = '.simt-hooks';
 
 /** Name of the git config key that points at the shim directory. */
 export const HOOKS_PATH_KEY = 'core.hooksPath';

package/src/hooks/where.mjs

@@ -19,17 +19,12 @@
 // ADR-012 dropped Windows, but nothing here is POSIX-specific; the worktree
 // handling is the only subtlety and it is the same on every platform.
 
-import { execFile } from 'node:child_process';
 import { readdir, stat } from 'node:fs/promises';
 import { isAbsolute, join, resolve } from 'node:path';
-import { promisify } from 'node:util';
 
-const exec = promisify(execFile);
+import { gitText } from '../sys/git.mjs';
 
-async function git(root, args) {
-  const { stdout } = await exec('git', args, { cwd: root });
-  return stdout.trim();
-}
+const git = (root, args) => gitText(root, args);
 
 /**
  * The directory git runs hooks from, and which of the two rules produced it.

package/src/identity.mjs

@@ -24,14 +24,12 @@
 // one; a repository that already tracks it is left that way, because removing a
 // tracked file is not something an adopting command should do silently.
 
-import { execFile } from 'node:child_process';
 import { readFile, stat, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { promisify } from 'node:util';
 
 import { journaledGitConfig, journaledWriteFile } from './journal.mjs';
+import { gitText } from './sys/git.mjs';
 
-const exec = promisify(execFile);
 
 /** The file, at the repository root. Named for what it is: a git config fragment. */
 export const IDENTITY_FILE = 'git.config';
@@ -50,14 +48,7 @@ export const INCLUDE_KEY = 'include.path';
  * @param {string[]} args
  * @returns {Promise<string|null>}
  */
-async function git(cwd, args) {
-  try {
-    const { stdout } = await exec('git', args, { cwd });
-    return stdout.trim();
-  } catch {
-    return null;
-  }
-}
+const git = (cwd, args) => gitText(cwd, args, { allowFailure: true });
 
 /**
  * Who last committed here.
@@ -257,4 +248,32 @@ export async function ignoreIdentity(root, journal = null) {
   if (journal) await journaledWriteFile(root, journal, path, next);
   else await writeFile(path, next);
   return true;
-}
+}
+/**
+ * The `user.*` keys the repository's own config sets, which is the one place an
+ * identity can be overridden without a trace in the tracked tree.
+ *
+ * A repo-local `[user]` block wins over both the `git.config` include and the
+ * machine's own identity, so every commit made here inherits it silently - including
+ * the commits this tool makes on the reader's behalf (`slice finish`, `plan done`).
+ * That is not a hypothetical: 34 commits in this repository were authored as
+ * `t <t@t.t>` because `.git/config` carried that block and nothing reported it. The
+ * helper exists so `test/repo-identity.test.mjs` can fail loudly instead.
+ *
+ * `--local` rather than `--get`: the question is what THIS config adds, not what the
+ * resolved identity happens to be.
+ *
+ * @param {string} root
+ * @returns {Promise<{key: string, value: string}[]>}
+ */
+export async function localIdentityOverrides(root) {
+  const out = await git(root, ['config', '--local', '--get-regexp', '^user\\.']);
+  if (!out) return [];
+  return out
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      const space = line.indexOf(' ');
+      return { key: line.slice(0, space), value: line.slice(space + 1) };
+    });
+}