heyspex 0.1.0 → 0.2.1

package/spexharness/src/gates/git-identity-guard.decide.mjs

@@ -0,0 +1,436 @@
+// spexharness/src/gates/git-identity-guard.decide.mjs
+//
+// Pure decision logic for ./git-identity-guard.mjs — the always-on PreToolUse
+// guard that keeps an agent from WRITING a git author identity through a
+// Bash / PowerShell tool call. No stdin/stdout/process.exit anywhere in this
+// file; ./git-identity-guard.mjs maps `classify()` onto the engine's decision
+// vocabulary and the generated scripts/claude-hooks/git-identity-guard.mjs
+// shell wires it to Claude Code.
+//
+// THE INCIDENT (2026-09-19): agents that hit "Author identity unknown" ran
+// `git config user.email <the owner's Claude-account address>` in four repos'
+// `.git/config`. Repo-local beats global, so ten days of commits carried a
+// non-team address and Vercel refused two production deploys. Vault lesson:
+// `when-git-says-author-identity-unknown`. Owner ruling: identity is written
+// by a HUMAN through `hs source identity set` — in their own terminal or with
+// Claude Code's `!` prefix — and never by an agent, in any spelling.
+//
+// DENY (any of these in the command text):
+//   - `git config` naming user.email / user.name WITH a value, in any scope
+//     (bare, --local, --global, --system, --worktree, --file/-f <path>), incl.
+//     `git -C <dir> config …`; `--unset`/`--unset-all`/`--replace-all`/`--add`
+//     on those keys; `--remove-section user` / `--rename-section user`;
+//     `git config --edit` / `-e` (an editor over the file the guard protects);
+//   - `-c user.email=…` / `-c user.name=…` on ANY git invocation;
+//   - `--author=…` / `--author …` on `git commit` (and am / cherry-pick / rebase);
+//   - assignments / exports of GIT_AUTHOR_EMAIL, GIT_AUTHOR_NAME,
+//     GIT_COMMITTER_EMAIL, GIT_COMMITTER_NAME and HS_HUMAN_IDENTITY in
+//     command position — bash `VAR=… cmd`, `export VAR=`, `env VAR=`,
+//     `declare -x VAR=`, cmd `set VAR=` / `setx VAR` — and the PowerShell /
+//     .NET forms anywhere: `$env:VAR =`, `${env:VAR} =`, `Set-Item env:VAR`,
+//     `[Environment]::SetEnvironmentVariable('VAR'`;
+//   - `hs source identity set|clear` in command position, any spelling (`hs`,
+//     `npx hs`, `node bin/hs.mjs`, `hs.cmd`, the script path, `--human`);
+//   - a write to a git config FILE path (`.git/config`, `config.worktree`,
+//     `~/.gitconfig`, `.config/git/config`): redirects, `sed -i`, `perl -i`,
+//     `tee`, `Set-Content`, `Add-Content`, `Out-File`, cp/mv/rm and their
+//     PowerShell forms, or any leading command not on the read allowlist.
+// ALLOW: `git config user.email` (no value), `--get`, `--get-all`,
+//   `--get-regexp`, `--show-origin`, `--show-scope`, `--list` / `-l`,
+//   `hs source identity` / `show` / `--json`, `git log --format=%ae`, reads of
+//   $GIT_AUTHOR_EMAIL, `cat .git/config`, non-identity `git config` keys, a
+//   quoted MENTION of the human form as an argument (`echo "run: hs source
+//   identity set …" > notes.txt`), and every non-git command.
+//
+// Obfuscation handling mirrors env-vault-guard.decide.mjs where practical:
+// unquoted `# …` comments are stripped; a de-quoted / de-escaped shadow copy
+// (`"user.email"`, `user.e\mail`, `$'\x2d'c`) is scanned alongside the raw
+// text; `git.exe`, `/usr/bin/git` and `& git` (PowerShell call operator) are
+// recognised; `$(…)` and backtick substitutions are their own command
+// position; a config key with backslashes is compared without them.
+
+const IDENTITY_KEY_RE = /^user\.(?:email|name)$/i;
+const IDENTITY_KEY_ASSIGN_RE = /^user\.(?:email|name)=/i;
+
+/** A config key never legitimately contains a backslash — `user.e\mail` is an
+ * escape-split spelling, so backslashes are dropped before the key test. */
+function keyToken(t) {
+  return String(t ?? '').replace(/\\/g, '');
+}
+function isIdentityKey(t) {
+  return IDENTITY_KEY_RE.test(keyToken(t));
+}
+function isIdentityKeyAssign(t) {
+  return IDENTITY_KEY_ASSIGN_RE.test(keyToken(t));
+}
+
+export const IDENTITY_ENV_VARS = [
+  'GIT_AUTHOR_EMAIL',
+  'GIT_AUTHOR_NAME',
+  'GIT_COMMITTER_EMAIL',
+  'GIT_COMMITTER_NAME',
+  'HS_HUMAN_IDENTITY',
+];
+
+/** `git config` flags that read. A key with one of these is never a write. */
+const CONFIG_READ_FLAGS = new Set([
+  '--get',
+  '--get-all',
+  '--get-regexp',
+  '--get-urlmatch',
+  '--get-color',
+  '--get-colorbool',
+  '--show-origin',
+  '--show-scope',
+  '--list',
+  '-l',
+]);
+/** `git config` flags that write even without a positional value. */
+const CONFIG_WRITE_FLAGS = new Set(['--unset', '--unset-all', '--replace-all', '--add']);
+const CONFIG_EDIT_FLAGS = new Set(['--edit', '-e']);
+const CONFIG_SECTION_FLAGS = new Set(['--remove-section', '--rename-section']);
+/** `git config` flags that consume the next token. */
+const CONFIG_FLAGS_WITH_ARG = new Set(['--file', '-f', '--blob', '--type', '--default', '--fixed-value']);
+/** `git` global options that consume the next token (when not `=`-joined). */
+const GIT_GLOBAL_WITH_ARG = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path', '--super-prefix', '--config-env']);
+
+/** A git config FILE path mention — the thing the "path write" rule protects. */
+const CONFIG_PATH_RE =
+  /(?:^|[\s"'=:(])(?:[^\s"'`;&|<>()]*[\\/])?(?:\.git[\\/]config(?:\.worktree)?|\.gitconfig|\.config[\\/]git[\\/]config)\b/i;
+
+/** Leading commands that only READ a file (path rule). `git` is here because the git-config rule owns it. */
+const PATH_READ_COMMANDS = new Set([
+  'cat', 'head', 'tail', 'less', 'more', 'grep', 'rg', 'egrep', 'fgrep', 'wc', 'file', 'stat', 'ls', 'dir', 'type', 'test',
+  'diff', 'cmp', 'cut', 'sort', 'uniq', 'strings', 'md5sum', 'sha1sum', 'sha256sum', 'find', 'realpath', 'readlink',
+  'get-content', 'gc', 'get-item', 'gi', 'get-childitem', 'gci', 'select-string', 'sls', 'test-path', 'get-filehash',
+  'compare-object', 'git', 'echo', 'printf', 'write-output', 'write-host', 'cd', 'pushd', 'set-location', '[',
+]);
+/** Read-capable commands that become writers with `-i` (in-place). */
+const INPLACE_COMMANDS = new Set(['sed', 'perl', 'awk', 'gawk', 'ruby']);
+
+/** Tokens that may precede the real command without changing what it is. */
+const WRAPPERS = new Set([
+  '&', '(', '{', 'sudo', 'time', 'nohup', 'exec', 'env', 'node', 'npx', 'npm', 'run', 'cmd', '/c', '/k', 'bash', 'sh',
+  'zsh', 'pwsh', 'powershell', '-c', '-command', '-noprofile', '-nologo', '--', '--yes', '-y', 'call', 'start',
+]);
+
+// ── text normalisation ──────────────────────────────────────────────────────
+
+/** Strip unquoted `# …` comments; a `#` inside quotes is left alone. */
+function stripComments(text) {
+  const out = [];
+  for (const line of String(text ?? '').split('\n')) {
+    let quote = null;
+    let cut = -1;
+    for (let i = 0; i < line.length; i += 1) {
+      const c = line[i];
+      if (quote) {
+        if (c === quote) quote = null;
+        continue;
+      }
+      if (c === '"' || c === "'" || c === '`') {
+        quote = c;
+        continue;
+      }
+      if (c === '#' && (i === 0 || /\s/.test(line[i - 1]))) {
+        cut = i;
+        break;
+      }
+    }
+    out.push(cut === -1 ? line : line.slice(0, cut));
+  }
+  return out.join('\n');
+}
+
+/** De-quoted / de-escaped shadow copy used ONLY for scanning. Backslashes before
+ * alphanumerics are preserved (Windows path separators). */
+function deobfuscate(text) {
+  return String(text ?? '')
+    .replace(/\\x([0-9a-fA-F]{2})/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)))
+    .replace(/\\([^A-Za-z0-9\s])/g, '$1')
+    .replace(/["'`]/g, '');
+}
+
+function scanVariants(command) {
+  const base = stripComments(String(command ?? ''));
+  return [...new Set([base, deobfuscate(base)])];
+}
+
+/** Split on shell control operators (and `$(` / backtick substitutions) so one
+ * segment's flags never leak into the next and a substitution is its own command position. */
+function segments(text) {
+  return String(text ?? '')
+    .split(/\|\||&&|;|\||\n|\r|\$\(|`/)
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/** Tokens of a segment, with a `VAR=value` / `env VAR=value` prefix and PowerShell `&` stripped. */
+function tokensOf(segment) {
+  const toks = segment.split(/\s+/).filter(Boolean);
+  while (toks.length && (toks[0] === '&' || toks[0] === 'env' || toks[0] === 'sudo' || /^[A-Za-z_][A-Za-z0-9_]*=/.test(toks[0]))) {
+    toks.shift();
+  }
+  return toks;
+}
+
+function baseCommand(token) {
+  return String(token ?? '')
+    .replace(/^["'&]+|["']+$/g, '')
+    .replace(/^.*[\\/]/, '')
+    .replace(/\.(?:exe|cmd|bat|ps1|mjs|js)$/i, '')
+    .toLowerCase();
+}
+
+// ── rule 1: git invocations ─────────────────────────────────────────────────
+
+/** Inspect one `git …` token list (tokens[0] is git). Returns a deny record or null. */
+function inspectGit(tokens) {
+  let i = 1;
+  // global options
+  while (i < tokens.length && tokens[i].startsWith('-')) {
+    const t = tokens[i];
+    if (t === '-c' || t.startsWith('-c=') || t.startsWith('--config-env')) {
+      const kv = t === '-c' || t === '--config-env' ? tokens[i + 1] ?? '' : t.slice(t.indexOf('=') + 1);
+      if (isIdentityKeyAssign(kv) || isIdentityKey(kv)) {
+        return { kind: 'git -c identity override', matched: `${t} ${kv}`.trim() };
+      }
+      i += t === '-c' || t === '--config-env' ? 2 : 1;
+      continue;
+    }
+    if (GIT_GLOBAL_WITH_ARG.has(t)) {
+      i += 2;
+      continue;
+    }
+    i += 1;
+  }
+  const sub = (tokens[i] ?? '').toLowerCase();
+  const rest = tokens.slice(i + 1);
+  if (sub === 'config') return inspectGitConfig(rest);
+  if (sub === 'commit' || sub === 'commit-tree' || sub === 'am' || sub === 'cherry-pick' || sub === 'rebase') {
+    const author = rest.find((t) => /^--author(?:=|$)/i.test(t));
+    if (author) return { kind: `git ${sub} --author`, matched: `git ${sub} ${author}` };
+  }
+  return null;
+}
+
+function inspectGitConfig(args) {
+  const flags = [];
+  const positionals = [];
+  let sectionOp = null;
+  for (let i = 0; i < args.length; i += 1) {
+    const t = args[i];
+    if (t === '--') {
+      positionals.push(...args.slice(i + 1));
+      break;
+    }
+    if (t.startsWith('-')) {
+      const name = t.includes('=') ? t.slice(0, t.indexOf('=')) : t;
+      flags.push(name);
+      if (CONFIG_SECTION_FLAGS.has(name)) {
+        sectionOp = { flag: name, section: t.includes('=') ? t.slice(name.length + 1) : args[i + 1] ?? '' };
+        if (!t.includes('=')) i += 1;
+        continue;
+      }
+      if (CONFIG_FLAGS_WITH_ARG.has(name) && !t.includes('=')) i += 1;
+      continue;
+    }
+    positionals.push(t);
+  }
+
+  if (flags.some((f) => CONFIG_EDIT_FLAGS.has(f))) {
+    return { kind: 'git config --edit', matched: 'git config --edit' };
+  }
+  if (sectionOp && /^user$/i.test(sectionOp.section)) {
+    return { kind: `git config ${sectionOp.flag} user`, matched: `git config ${sectionOp.flag} user` };
+  }
+
+  const keyIndex = positionals.findIndex((p) => isIdentityKey(p) || isIdentityKeyAssign(p));
+  if (keyIndex === -1) return null;
+  const key = positionals[keyIndex];
+
+  if (isIdentityKeyAssign(key)) return { kind: 'git config identity write', matched: `git config ${key}` };
+  if (flags.some((f) => CONFIG_WRITE_FLAGS.has(f))) {
+    return { kind: 'git config identity write', matched: `git config ${flags.filter((f) => CONFIG_WRITE_FLAGS.has(f)).join(' ')} ${key}` };
+  }
+  if (flags.some((f) => CONFIG_READ_FLAGS.has(f))) return null;
+  // Bare `git config user.email` reads; a following positional is the value → write.
+  if (positionals.length > keyIndex + 1) {
+    return { kind: 'git config identity write', matched: `git config ${key} ${positionals[keyIndex + 1]}` };
+  }
+  return null;
+}
+
+// ── rule 2: env var assignment ──────────────────────────────────────────────
+
+const ENV_NAMES = IDENTITY_ENV_VARS.join('|');
+const ENV_NAME_RE = new RegExp(`^(?:${ENV_NAMES})$`, 'i');
+const ENV_ASSIGN_TOKEN_RE = new RegExp(`^(?:${ENV_NAMES})=`, 'i');
+const ENV_SETTERS = new Set(['export', 'env', 'set', 'setx', 'declare', 'typeset']);
+/** PowerShell / .NET forms — unambiguous wherever they appear in the text. */
+const ENV_ASSIGN_ANYWHERE_RES = [
+  new RegExp(`\\$\\{?env:(?:${ENV_NAMES})\\}?\\s*=`, 'i'),
+  new RegExp(`\\b(?:set-item|si|new-item|ni|set-content|sc)\\s+(?:-path\\s+)?["']?env:(?:${ENV_NAMES})\\b`, 'i'),
+  new RegExp(`SetEnvironmentVariable\\(\\s*["']?(?:${ENV_NAMES})\\b`, 'i'),
+];
+
+/** Bash-style assignment in COMMAND position: `VAR=… cmd`, `export VAR=…`, `env VAR=… cmd`, `set VAR=…`, `setx VAR …`. */
+function inspectEnvAssignmentSegment(segment) {
+  const toks = segment.split(/\s+/).filter(Boolean);
+  let i = 0;
+  while (i < toks.length && ['(', '{', '&', 'sudo', 'time', 'nohup'].includes(toks[i])) i += 1;
+  for (; i < toks.length; i += 1) {
+    const t = toks[i].replace(/^[({]+/, '');
+    if (ENV_ASSIGN_TOKEN_RE.test(t)) return { kind: 'identity env var assignment', matched: t };
+    if (ENV_SETTERS.has(t.toLowerCase())) {
+      for (let j = i + 1; j < toks.length; j += 1) {
+        const n = toks[j].replace(/^["']|["']$/g, '');
+        if (n.startsWith('-')) continue; // declare -x, set -e
+        if (ENV_ASSIGN_TOKEN_RE.test(n) || ENV_NAME_RE.test(n)) {
+          return { kind: 'identity env var assignment', matched: `${t} ${n}` };
+        }
+        if (/^[A-Za-z_][A-Za-z0-9_]*(=.*)?$/.test(n)) continue; // another var in the same export
+        break;
+      }
+      continue;
+    }
+    // a plain `VAR=value` prefix of another var keeps us in prefix position
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(t)) continue;
+    break; // the real command starts here — anything after is an argument, not an assignment
+  }
+  return null;
+}
+
+function inspectEnvAssignmentAnywhere(text) {
+  for (const re of ENV_ASSIGN_ANYWHERE_RES) {
+    const m = re.exec(text);
+    if (m) return { kind: 'identity env var assignment', matched: m[0].trim() };
+  }
+  return null;
+}
+
+// ── rule 3: hs source identity set|clear ────────────────────────────────────
+
+/**
+ * `hs [flags] [source] identity set|clear` or `hs-source-identity.mjs [identity] set|clear`,
+ * in COMMAND position only (after wrappers like `node`, `npx`, `npm exec … --`), so a
+ * quoted mention of the human form inside an `echo` is not a write.
+ */
+function inspectHsIdentitySegment(segment) {
+  const toks = segment.split(/\s+/).filter(Boolean);
+  let i = 0;
+  while (i < toks.length && (WRAPPERS.has(toks[i].toLowerCase()) || /^[A-Za-z_][A-Za-z0-9_]*=/.test(toks[i]))) i += 1;
+  if (i >= toks.length) return null;
+  const head = baseCommand(toks[i]);
+  if (head !== 'hs' && head !== 'hs-source-identity') return null;
+  const words = [];
+  for (let j = i + 1; j < toks.length && words.length < 3; j += 1) {
+    const t = toks[j].replace(/^["']|["']$/g, '');
+    if (t.startsWith('-')) {
+      if ((t === '--vault' || t === '--email' || t === '--name') && !t.includes('=')) j += 1;
+      continue;
+    }
+    words.push(t.toLowerCase());
+  }
+  const seq = words.join(' ');
+  const m = /^(?:source )?(?:identity )?(set|clear)\b/.exec(seq);
+  if (!m) return null;
+  if (head === 'hs' && !/\bidentity\b/.test(seq)) return null; // `hs source set` is not this command
+  return { kind: `hs source identity ${m[1]}`, matched: toks.slice(i, i + 5).join(' ') };
+}
+
+// ── rule 4: writes to a git config file path ────────────────────────────────
+
+function hasOutputRedirect(segment) {
+  const withoutStderrNoise = segment
+    .replace(/2\s*>&\s*[12]/g, ' ')
+    .replace(/2\s*>>?\s*(?:\/dev\/null|nul|\$null)\b/gi, ' ');
+  return /(?:^|[^<])>(?!\s*&)/.test(withoutStderrNoise) || /\|\s*(?:tee|out-file|set-content|add-content|sc|ac)\b/i.test(withoutStderrNoise);
+}
+
+function inspectConfigPathWrite(segment) {
+  const m = CONFIG_PATH_RE.exec(segment);
+  if (!m) return null;
+  const pathText = m[0].trim();
+  if (hasOutputRedirect(segment)) return { kind: 'git config file write', matched: `${pathText} (redirect)` };
+  const toks = tokensOf(segment);
+  const lead = baseCommand(toks[0]);
+  if (INPLACE_COMMANDS.has(lead)) {
+    const inPlace = toks.slice(1).some((t) => /^-[a-zA-Z]*i/.test(t) || /^--in-place/.test(t));
+    return inPlace ? { kind: 'git config file write', matched: `${lead} -i ${pathText}` } : null;
+  }
+  if (PATH_READ_COMMANDS.has(lead)) return null;
+  return { kind: 'git config file write', matched: `${lead} … ${pathText}` };
+}
+
+// ── the classifier ──────────────────────────────────────────────────────────
+
+/**
+ * Classify a command string. Returns null when nothing writes identity, else
+ * `{ kind, matched }` for the first write found.
+ *
+ * @param {unknown} command
+ * @returns {{ kind: string, matched: string } | null}
+ */
+export function classifyIdentityWrite(command) {
+  if (typeof command !== 'string' || !command.trim()) return null;
+  for (const variant of scanVariants(command)) {
+    const env = inspectEnvAssignmentAnywhere(variant);
+    if (env) return env;
+    for (const seg of segments(variant)) {
+      const envSeg = inspectEnvAssignmentSegment(seg);
+      if (envSeg) return envSeg;
+      const hs = inspectHsIdentitySegment(seg);
+      if (hs) return hs;
+      const toks = tokensOf(seg);
+      // a `git` token may sit after a leading wrapper (`& git`, `cmd /c git`, `bash -c "git …"`)
+      for (let i = 0; i < toks.length; i += 1) {
+        if (baseCommand(toks[i]) === 'git') {
+          const hit = inspectGit(toks.slice(i));
+          if (hit) return hit;
+          break;
+        }
+      }
+      const pathWrite = inspectConfigPathWrite(seg);
+      if (pathWrite) return pathWrite;
+    }
+  }
+  return null;
+}
+
+/**
+ * The tool-call classifier the gate calls. Only Bash / PowerShell carry a
+ * command string; every other tool is not applicable (null).
+ *
+ * @param {string} toolName
+ * @param {Record<string, unknown>} toolInput
+ * @returns {{ kind: string, matched: string } | null}
+ */
+export function classifyGitIdentity(toolName, toolInput) {
+  if (toolName !== 'Bash' && toolName !== 'PowerShell') return null;
+  return classifyIdentityWrite(toolInput?.command);
+}
+
+export const HUMAN_FORMS = Object.freeze({
+  terminal: 'hs source identity set --email you@example.com',
+  claudeCode: '!hs source identity set --email you@example.com --human',
+});
+
+export const VAULT_LESSON = 'when-git-says-author-identity-unknown';
+
+/**
+ * The deny reason. A function of the classification so tests pin its text.
+ * @param {{ kind: string, matched: string }} hit
+ * @returns {string}
+ */
+export function denyReason(hit) {
+  return (
+    `HeySpex git-identity guard: blocked ${hit.kind} (\`${hit.matched}\`). ` +
+    'Git author identity is a HUMAN-authorized action only (owner ruling 2026-09-19, vault lesson ' +
+    `${VAULT_LESSON}): agents read identity, never write it — in any scope, any spelling, any env var. ` +
+    'If git says "Author identity unknown", stop and tell the human to run it themselves: ' +
+    `in their own terminal \`${HUMAN_FORMS.terminal}\`; inside Claude Code \`${HUMAN_FORMS.claudeCode}\` ` +
+    '(the `!` prefix runs outside your tool calls). Read forms stay open: `hs source identity show`, ' +
+    '`git config --show-origin --get-all user.email`, `git log --format=%ae`. This gate has no off switch.'
+  );
+}

package/spexharness/src/gates/git-identity-guard.mjs

@@ -0,0 +1,61 @@
+// spexharness/src/gates/git-identity-guard.mjs
+//
+// The always-on PreToolUse guard that keeps an agent from WRITING a git
+// author identity through a Bash / PowerShell tool call. Same shape as
+// ./env-vault-guard.mjs (the reference security gate): a pure classifier in
+// ./git-identity-guard.decide.mjs, this thin `{ id, event, severity, run }`
+// adapter over it, a generated Claude Code shell at
+// scripts/claude-hooks/git-identity-guard.mjs, an ALWAYS_ON entry in
+// scripts/claude-hooks/_run.mjs and a PreToolUse row in .claude/settings.json
+// on the matcher `Bash|PowerShell`.
+//
+// WHY (the incident, 2026-09-19): agents that hit git's "Author identity
+// unknown" ran `git config user.email <the owner's Claude-account address>`
+// in four repos' `.git/config`. A repo-local value beats the global identity
+// the owner set later, so every commit from this machine was authored as a
+// non-team address for ten days and Vercel silently refused two production
+// deploys. Vault lesson: `when-git-says-author-identity-unknown`.
+//
+// THE RULING: a repo-local (or global) git identity override is a HUMAN-
+// authorized action only, run through `hs source identity set` by the human
+// themselves — in their own terminal, or in Claude Code with the `!` prefix
+// (which runs outside the agent's tool calls and is therefore invisible to
+// this gate; `--human` exists only because that path inherits the agent's
+// env). Agents may READ identity, never write it. The full deny/allow matrix
+// is the header of ./git-identity-guard.decide.mjs.
+//
+// NO ENV KILL SWITCH — deliberately. env-vault-guard and research-protocol-
+// gate keep an owner-only env hatch; this one does not, because the owner's
+// own path IS the identity command (typed by a human), so there is nothing a
+// hatch would enable that the sanctioned form does not already do. This is a
+// locked owner ruling, not an oversight. It is listed in _run.mjs's ALWAYS_ON
+// so .heyspex/mode.json cannot silence it either.
+//
+// Registered in ./index.mjs's PORTED_GATES (every engine front — SpexCode
+// seats, hs chat, overnight runs), not BUILT_IN_GATES (the frozen twelve).
+//
+// `ctx` is accepted for shape parity with the other gates and ignored: the
+// decision depends on the command text alone.
+
+import { classifyGitIdentity, denyReason } from './git-identity-guard.decide.mjs';
+
+export { classifyGitIdentity, classifyIdentityWrite, denyReason, HUMAN_FORMS, VAULT_LESSON } from './git-identity-guard.decide.mjs';
+
+/** The gate's id — unique across the registry; also its Claude Code hook name. */
+export const id = 'git-identity-guard';
+/** Runs pre-tool, same as its PreToolUse Claude Code hook registration. */
+export const event = 'before_tool';
+/** Denies, so "block". */
+export const severity = 'block';
+
+/**
+ * @param {{ point: string, toolName?: string, toolInput?: Record<string, unknown> }} evt
+ * @returns {{ decision: 'allow'|'deny', reason?: string }}
+ */
+export function run(evt) {
+  const hit = classifyGitIdentity(evt?.toolName, evt?.toolInput ?? {});
+  if (!hit) return { decision: 'allow' };
+  return { decision: 'deny', reason: denyReason(hit) };
+}
+
+export default { id, event, severity, run };

package/spexharness/src/gates/git-reflog-audit.mjs

@@ -0,0 +1,151 @@
+// spexharness/src/gates/git-reflog-audit.mjs
+//
+// Engine port of scripts/claude-hooks/git-reflog-audit.mjs — the session-close
+// git audit BACKSTOP (task HS-610I-P3TJ, epic HS-GG01-P3TJ), wave 6 of
+// [[HS-AZ61-NYPR]]. The rule was Claude-Code-plugin-only, so an overnight
+// DeepSeek or local seat could stash/reset/rebase a shared tree and leave no
+// independent trace. See ./PORTING.md for the recipe.
+//
+// This module does NOT reimplement the reflog parsing. The audit logic moved
+// once, into ../git-reflog-audit.mjs, and there is exactly one copy of it in
+// the tree — this gate, the Claude Code shim, and the original regression suite
+// (scripts/claude-hooks/git-reflog-audit.test.mjs) all drive that module.
+//
+// TWO GATES, one rule. The Claude Code hook was registered on BOTH SessionStart
+// and Stop and branched on `hook_event_name` inside its own `main()`. The
+// engine registry keys a gate on exactly ONE event point (registry.mjs's
+// `assertValidGate`), so the rule ships as a pair:
+//   * `git-reflog-audit-snapshot` on `session_start` — writes the baseline.
+//   * `git-reflog-audit`          on `stop`          — diffs and warns.
+// Splitting is the documented deviation from PORTING.md's one-hook-one-gate
+// shape (step 2 asks for the mapping to be written down HERE rather than
+// guessed at): inventing a multi-event gate would change registry.mjs's own
+// contract for one rule, and two ids make `hs harness gates` show both halves
+// of the witness rather than hiding the half that does the recording.
+//
+// Event mapping: SessionStart → `session_start`; Stop → `stop`. (SessionEnd,
+// which the original also accepted, maps to `session_end` in ../events.mjs —
+// `.claude/settings.json` wires only Stop, so the ported pair covers every
+// wiring that exists. A front that wants the audit at session end registers the
+// exported {@link sessionEndGate}.)
+//
+// Decision mapping: this witness NEVER blocks and never asks — "warn only" is
+// its whole scope. Its output channel is `.heyspex/guardrail-history.jsonl`,
+// not stdout, so the honest engine mapping is:
+//   * nothing flagged → `allow`.
+//   * something flagged → `inject`, carrying the finding as text so a headless
+//     seat's own loop can surface it. On the Claude Code Stop hook this is
+//     still SILENT (adapters/claude-code.mjs's `stop` branch renders only
+//     deny/rewrite-warn), which is exactly what the original hook did — the
+//     golden fixtures pin that parity.
+//
+// SIDE EFFECT, deliberately kept in the gate (a documented deviation from the
+// "gates are pure" rule the other twelve follow, PORTING.md step 1): the
+// snapshot write and the guardrail-history append ARE this rule. The other
+// gates could hand their audit row to ../adapters/audit.mjs because that row is
+// a Claude-Code-front observation of a decision; here the row IS the enforcement,
+// and routing it through the Claude Code adapter would mean a DeepSeek seat
+// silently records nothing — the exact gap this port closes. Both writes are
+// injectable through `ctx` so a test never touches the real tree.
+//
+// `ctx` contract (all optional; every field defaults to a real read/write):
+//   ctx.repoRoot     - the working tree to snapshot/diff. Defaults to
+//                      CLAUDE_PROJECT_DIR, then this repo's root.
+//   ctx.snapshotPath - override the session-scoped snapshot file (tests).
+//   ctx.append       - override the guardrail-history writer (tests).
+//   ctx.env          - env var overrides (tests use this instead of mutating
+//                      process.env).
+//
+// Env hatch (unchanged from the hook): HEYSPEX_GIT_REFLOG_AUDIT_OFF=1.
+
+import {
+  describeDiff,
+  isFlagged,
+  repoRoot as defaultRepoRoot,
+  runSessionEnd,
+  writeSnapshot,
+} from '../git-reflog-audit.mjs';
+
+const OFF_ENV = 'HEYSPEX_GIT_REFLOG_AUDIT_OFF';
+
+/** Caller-defined severity label shared by both halves; this rule only ever warns. */
+export const severity = 'warn';
+
+function isOff(ctx) {
+  const env = ctx.env ?? process.env;
+  return String(env[OFF_ENV] ?? '') === '1';
+}
+
+function resolveRoot(ctx) {
+  if (typeof ctx.repoRoot === 'string' && ctx.repoRoot.trim()) return ctx.repoRoot.trim();
+  return defaultRepoRoot(ctx.env ?? process.env);
+}
+
+/**
+ * Session-start half: write the baseline snapshot. Always `allow` — the
+ * original hook emits nothing at session start either.
+ *
+ * @param {{ point: string, sessionId?: string }} evt
+ * @param {{ repoRoot?: string, snapshotPath?: string, env?: Record<string, string|undefined> }} [ctx]
+ * @returns {{ decision: 'allow', snapshot?: object|null }}
+ */
+export function runSnapshot(evt, ctx = {}) {
+  if (isOff(ctx)) return { decision: 'allow' };
+  const snapshot = writeSnapshot({
+    repoRootPath: resolveRoot(ctx),
+    sessionId: evt?.sessionId,
+    snapshotPath: ctx.snapshotPath,
+  });
+  return { decision: 'allow', snapshot };
+}
+
+/**
+ * Stop half: diff against the baseline and, when something destructive
+ * happened, record ONE warn row and carry the finding on the decision.
+ *
+ * @param {{ point: string, sessionId?: string }} evt
+ * @param {{ repoRoot?: string, snapshotPath?: string,
+ *   append?: (row: object, repoRoot: string) => unknown,
+ *   env?: Record<string, string|undefined> }} [ctx]
+ * @returns {{ decision: 'allow'|'inject', inject?: { additionalContext: string, severity: string },
+ *   diff?: object|null }}
+ */
+export function runAudit(evt, ctx = {}) {
+  if (isOff(ctx)) return { decision: 'allow' };
+  const diff = runSessionEnd({
+    repoRootPath: resolveRoot(ctx),
+    sessionId: evt?.sessionId,
+    snapshotPath: ctx.snapshotPath,
+    ...(ctx.append ? { append: ctx.append } : {}),
+  });
+  if (!isFlagged(diff)) return { decision: 'allow', diff };
+
+  const text =
+    'Destructive git activity happened during this session and was recorded by the ' +
+    `git-reflog-audit witness (warn only, nothing was blocked): ${describeDiff(diff)}. ` +
+    'Say so in the hand-off rather than letting it go unmentioned.';
+  return { decision: 'inject', inject: { additionalContext: text, severity: 'warn' }, diff };
+}
+
+/** The session-start half of the witness — writes the baseline snapshot. */
+export const snapshotGate = {
+  id: 'git-reflog-audit-snapshot',
+  event: 'session_start',
+  severity,
+  run: runSnapshot,
+};
+
+/** The session-end half, for a front that closes on `session_end` rather than `stop`. */
+export const sessionEndGate = {
+  id: 'git-reflog-audit-session-end',
+  event: 'session_end',
+  severity,
+  run: runAudit,
+};
+
+/** The stop half of the witness — the diff, and the only half that can warn. */
+export const id = 'git-reflog-audit';
+export const event = 'stop';
+export const run = runAudit;
+
+export default { id, event, severity, run };