feat(hooks): wave-1 guards -- approval ask, plan gate, test lock, post-edit check

Wave-1 order 4 (P7, P12, the P9 test lock, the P3 plan-approval guard). All command hooks; none runs a model. - P12: pre-bash-executor answers permissionDecision "ask" before merge into main, push, tag/publish and destructive git (holds in auto mode). post-approval-log writes exactly what the person was asked to the K2 approval log: merge/push to main as `merge`, tag/publish as `release`, with a one-hour expiry; nothing when no person was asked. - P3: pre-plan-gate runs the K3 plan gate on a Voyage plan leaving plan mode and sends a refused plan back; "not measured" asks, never passes. - P9: lib/util/test-lock.mjs (K8). pre-write-executor refuses edits to locked test files; stop-test-lock refuses "done" for the locking session (stop_hook_active guarded). - P7: post-edit-check runs the target repo's own formatter/linter per edit, only during a Voyage plan run or after opt-in (.claude/voyage-guards.json); lib/verification/step-check.mjs (K9) fails the step on findings; no tool reads "not measured", never green. - STORM cap matcher also names `Agent` (the tool's name since 2.1.63). - Mod precondition stated in README, SECURITY.md and every PreToolUse stop guard: Voyage's guards are deterministic only when no installed mod handles `tool.check`. K2, K3 and K5 are stubbed in tests until orders 2 and 3 are merged. Two independent review rounds; every finding has a regression test. Suite 1600 (1598 pass / 0 fail / 2 skipped). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 20:09:32 +02:00 · 2026-10-06 20:09:32 +02:00 · 2ee8137e7c
commit 2ee8137e7c
parent 2c89a6b580
31 changed files with 3278 additions and 107 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -52,6 +52,18 @@ Full flag reference for each command (modes, `--gates`, `--profile`, breaking ch
 > pre-registered measurement in `docs/storm-measurement.md` — decline is a
 > no-op, adopt is one constant.
 > **Guards (P3/P7/P9/P12).** Command hooks only, wired for every session.
 > `pre-bash-executor` answers `ask` (holds in auto mode) before merge into
 > main, push, tag/publish and destructive git; `post-approval-log` writes
 > approvals to the K2 log. `pre-plan-gate` runs the K3 plan gate on a Voyage
 > plan leaving plan mode. `pre-write-executor` + `stop-test-lock` enforce the
 > K8 test lock (`lib/util/test-lock.mjs`). `post-edit-check` runs the target
 > repo's own format/lint only during a Voyage plan run or after opt-in
 > (`.claude/voyage-guards.json`); `lib/verification/step-check.mjs` (K9) fails
 > the step on findings. A missing contract CLI reads "not measured"/"not
 > logged", never green. Voyage's guards are deterministic only when no
 > installed mod handles `tool.check`.
 ## Agents
 | Agent | Model | Role |
--- a/README.md
+++ b/README.md
@ -351,6 +351,17 @@ The executor implements defense-in-depth security across three layers:
 2. **Prompt-level denylist** — Security rules embedded in the executor command and session spec template that hold even if a hook does not fire
 3. **Pre-execution plan scan** — Phase 2.4 scans all `Verify:` and `Checkpoint:` commands against the denylist before execution begins, catching dangerous commands before they reach the executor
 **Guards during the build.** All are command hooks; none runs a model.
 - **Approval guard (P12)** — `pre-bash-executor.mjs` answers `ask` before a merge into `main`, a push, a tag or package publish, and destructive git (hard reset, forced clean, force-deleted branch, dropped stash, discarded changes, history rewrite). Claude Code shows the prompt labelled `[plugin:voyage]`, also in auto mode, and the prompt names the way forward. `post-approval-log.mjs` writes an approved merge or push to `main` (`merge`) and a tag or publish (`release`) to the approval log with a one-hour expiry. It logs exactly what the person was asked, and nothing in a permission mode that shows no prompts, where no one is asked; other pushes and destructive git are asked about but not logged. Claude Code's own notification for a waiting permission prompt is the alert; Voyage adds none.
 - **Plan gate (P3)** — `pre-plan-gate.mjs` runs Voyage's plan gate on the plan Claude Code's plan mode presents and sends an invalid Voyage plan back to planning; when the gate cannot run, the prompt says "not measured". An approved Voyage plan is logged with the hash of its text. A plan without `plan_version` passes untouched.
 - **Test lock (P9)** — while a step's test is locked (`lib/util/test-lock.mjs`), `pre-write-executor.mjs` refuses Write, Edit and NotebookEdit on it, and `stop-test-lock.mjs` refuses "done" in the session that took the lock until the executor unlocks it.
 - **Post-edit check (P7)** — `post-edit-check.mjs` runs the target repo's own formatter and linter on each edited file (check-only; a tool is never downloaded) and logs the result. `lib/verification/step-check.mjs` re-runs them on the diff at step end, adds the type checker, and fails the step on findings. A repo without tools, or a configured tool that is missing or crashes, reads "not measured", never green. The check is on only while Voyage executes a plan in that repo, or when the repo switches it on with `.claude/voyage-guards.json` = `{ "post_edit_check": true }`.
 **Precondition.** Voyage's guards are deterministic only when no installed mod handles `tool.check`. Claude Code runs such a mod after the hooks, and its answer can replace theirs: it can approve a call a Voyage guard stopped or asked about ([permissions](https://code.claude.com/docs/en/permissions)). A hook cannot tell whether such a mod is installed; `/plugin` lists the mods a session loaded.
 **Credits.** The four approval classes come from Superpowers; a block that names the way forward from agent-skills; guard plus log from ai-native-sdlc; the alert from Cherny's practice. The post-edit tiers and "not measured" come from agent-skills' constraint-driven development, formatting per edit with the rest at step end from Cherny, the per-file / step-end split from Kiro, a check seen to pass and to fail on a planted problem from Pocock, and guard tests in both directions from ai-native-sdlc. The test lock, the plan-mode wrap and the post-edit hook are Claude Code's own documented hook patterns. Superpowers, Pocock, agent-skills and ai-native-sdlc are MIT-licensed; only ideas are borrowed, no code.
 #### Recommended: disable Skill shell execution (CC v2.1.91+)
 For fork-ers handling untrusted task briefs or plans from external
@ -823,7 +834,7 @@ trekplan/
 │                  └ 20 spawnable (1 dormant: synthesis-agent, Δ≈0) + 3 orchestrator reference docs (not spawned)
 ├── commands/      6 slash commands (trekbrief, trekresearch, trekplan, trekexecute, trekreview, trekcontinue) + trekendsession helper
 ├── templates/     Frontmatter templates for brief, research, plan, session
-├── hooks/         8 hooks (pre-bash, pre-write, pre-agent-cap, session-title, post-bash-stats, pre-compact-flush, post-compact-flush, otel-export)
+├── hooks/         12 hooks (pre-bash, pre-write, pre-agent-cap, pre-plan-gate, session-title, post-bash-stats, post-approval-log, post-edit-check, pre-compact-flush, post-compact-flush, otel-export, stop-test-lock)
 ├── lib/           Zero-dep parsers and validators (CLI shims under lib/validators/)
 ├── tests/         comprehensive node:test suite — `npm test` is the fork-readiness gate
 ├── docs/          HANDOVER-CONTRACTS.md + architect-bridge-test.md
--- a/SECURITY.md
+++ b/SECURITY.md
@ -31,15 +31,35 @@ The plugin's security posture covers:
 | Hook | Trigger | Purpose |
 |------|---------|---------|
-| `pre-bash-executor.mjs` | `PreToolUse` for Bash | BLOCKs known-dangerous shell patterns; WARNs on suspicious ones; fails open on parse errors |
+| `pre-bash-executor.mjs` | `PreToolUse` for Bash | BLOCKs known-dangerous shell patterns; WARNs on suspicious ones; answers `ask` before merge into `main`, push, tag/publish and destructive git (P12); fails open on parse errors |
-| `pre-write-executor.mjs` | `PreToolUse` for Write, Edit, NotebookEdit | BLOCKs writes to `.git/hooks/`, `~/.ssh/`, `.env`, and other sensitive paths; fails closed when it cannot read the target path |
+| `pre-write-executor.mjs` | `PreToolUse` for Write, Edit, NotebookEdit | BLOCKs writes to `.git/hooks/`, `~/.ssh/`, `.env`, and other sensitive paths, to Voyage's own state in the git directory (`voyage/`), and to test files a step has locked (P9); fails closed when it cannot read the target path or the lock, or cannot load the lock code |
 | `pre-plan-gate.mjs` | `PreToolUse` for ExitPlanMode | Runs Voyage's plan gate on a Voyage plan (it carries `plan_version`) and denies one the gate refuses; asks with "not measured" when the gate cannot run; other plans pass (P3) |
 | `post-approval-log.mjs` | `PostToolUse` for Bash, ExitPlanMode | Writes an approved merge/push to `main`, tag/publish, or Voyage plan to the approval log; says "not logged" when it cannot |
 | `post-edit-check.mjs` | `PostToolUse` for Edit, Write | Runs the target repo's own formatter and linter on the edited file, check-only, while Voyage executes a plan there or the repo has switched it on (P7) |
 | `stop-test-lock.mjs` | `Stop` | Refuses "done" while the session's step holds its test lock; lets the stop through when `stop_hook_active` is set (P9) |
 | `pre-compact-flush.mjs` | `PreCompact` | Flushes `progress.json` from git history before compaction (P0 drift fix); read-only beyond `progress.json` |
 | `session-title.mjs` *(planned, F9)* | `UserPromptSubmit` | Sets session title `voyage:<command>:<slug>` for telling parallel sessions apart |
-All hooks are zero-dependency Node.js (`.mjs`) scripts and are designed
+All hooks are zero-dependency Node.js (`.mjs`) scripts. Most are designed
-to **fail open** — a hook crash never blocks the user's work. Hooks log
+to **fail open** — a hook crash never blocks the user's work. The
-to stderr only; they never write to user files outside their declared
+exceptions are stated per hook above: the write guard fails closed when it
-scope.
+cannot read a path or a test lock, and the plan gate asks rather than
 passes when it cannot run. No hook runs a model. Hooks never write to user
 files outside their declared scope; the test lock and the post-edit log
 live in the repository's git directory (`<git dir>/voyage/`), where they
 cannot be committed.
 ### Precondition: mods
 Voyage's guards are deterministic only when no installed mod handles `tool.check`.
 A Claude Code mod that handles `tool.check` answers after the permission
 rules and the `PreToolUse` hooks have decided, and its answer can replace
 theirs: it can approve a call a plugin hook blocked or asked about, and
 outside managed settings and Team/Enterprise plans it can approve a call a
 deny rule refuses (code.claude.com/docs/en/permissions, § Extend
 permissions with hooks). Voyage's hooks cannot tell whether such a mod is installed:
 no hook input names the loaded mods. `/plugin` shows them to a person
 (`N mods active · …`). Voyage itself ships no mods.
 ### Prompt-level denylist (`commands/trekexecute.md`)
--- a/hooks/hooks.json
+++ b/hooks/hooks.json
@ -22,7 +22,7 @@
        ]
      },
      {
-        "matcher": "WebSearch|WebFetch|Task",
+        "matcher": "WebSearch|WebFetch|Task|Agent",
        "hooks": [
          {
            "type": "command",
@ -30,6 +30,16 @@
            "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/scripts/pre-agent-cap.mjs"]
          }
        ]
      },
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/scripts/pre-plan-gate.mjs"]
          }
        ]
      }
    ],
    "UserPromptSubmit": [
@ -53,6 +63,26 @@
            "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/scripts/post-bash-stats.mjs"]
          }
        ]
      },
      {
        "matcher": "Bash|ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/scripts/post-approval-log.mjs"]
          }
        ]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/scripts/post-edit-check.mjs"]
          }
        ]
      }
    ],
    "PreCompact": [
@ -86,6 +116,15 @@
            "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/scripts/otel-export.mjs"]
          }
        ]
      },
      {
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/scripts/stop-test-lock.mjs"]
          }
        ]
      }
    ]
  }
--- a/hooks/lib/approval-record.mjs
+++ b/hooks/lib/approval-record.mjs
@ -0,0 +1,60 @@
 // hooks/lib/approval-record.mjs
 // What the person was asked. pre-bash-executor.mjs writes one record per
 // asked call, keyed by session_id + tool_use_id (both in PreToolUse and
 // PostToolUse input); post-approval-log.mjs takes it after the call ran and
 // logs exactly that -- never a re-reading of the command afterwards, which
 // can see another branch than the one the question named. No record = the
 // person was not asked = nothing is logged.
 //
 // Records live in the OS temp dir (voyage-approvals-<uid>/), are removed when taken,
 // and anything older than a day is swept on the next write.
 import { mkdirSync, writeFileSync, readFileSync, rmSync, readdirSync, statSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 // One directory per user: another user's directory in a shared /tmp is never ours.
 const DIR = join(tmpdir(), `voyage-approvals-${process.getuid ? process.getuid() : 'u'}`);
 const MAX_AGE_MS = 24 * 60 * 60 * 1000;
 function pathFor(sessionId, toolUseId) {
  const key = createHash('sha256').update(`${sessionId || ''}\n${toolUseId}`).digest('hex').slice(0, 32);
  return join(DIR, `${key}.json`);
 }
 function sweep() {
  try {
    const now = Date.now();
    for (const f of readdirSync(DIR)) {
      const p = join(DIR, f);
      try { if (now - statSync(p).mtimeMs > MAX_AGE_MS) rmSync(p, { force: true }); } catch { /* raced */ }
    }
  } catch { /* no dir yet */ }
 }
 /** @returns {boolean} written */
 export function writeApprovalRecord(sessionId, toolUseId, record) {
  if (!toolUseId) return false;
  try {
    mkdirSync(DIR, { recursive: true });
    sweep();
    writeFileSync(pathFor(sessionId, toolUseId), JSON.stringify(record));
    return true;
  } catch {
    return false;
  }
 }
 /** Read and remove the record; null when there is none. */
 export function takeApprovalRecord(sessionId, toolUseId) {
  if (!toolUseId) return null;
  const p = pathFor(sessionId, toolUseId);
  try {
    const rec = JSON.parse(readFileSync(p, 'utf8'));
    rmSync(p, { force: true });
    return rec;
  } catch {
    return null;
  }
 }
--- a/hooks/lib/bash-view.mjs
+++ b/hooks/lib/bash-view.mjs
@ -0,0 +1,130 @@
 // hooks/lib/bash-view.mjs
 // How the Bash guards read a command. Moved out of pre-bash-executor.mjs so
 // the guard that asks before a call (pre-bash-executor.mjs) and the hook that
 // logs the approval after it (post-approval-log.mjs) read a command the same
 // way. Behavior unchanged from the inline copy.
 //
 // Bash normalization from llm-security/scanners/lib/bash-normalize.mjs (MIT,
 // same author); lib/parsers/bash-normalize.mjs keeps the test-suite copy.
 // Strips bash evasion techniques: empty quotes, ${} expansion, backslash splitting.
 export function normalizeBashExpansion(cmd) {
  if (!cmd || typeof cmd !== 'string') return cmd || '';
  let result = cmd
    // Strip empty single quotes: w''get -> wget
    .replace(/''/g, '')
    // Strip empty double quotes: r""m -> rm
    .replace(/""/g, '')
    // Single-char ${x} -> x (evasion: c${u}rl -> curl, assumes x=x)
    .replace(/\$\{(\w)\}/g, '$1')
    // Multi-char ${ANYTHING} -> '' (unknown value, strip entirely)
    .replace(/\$\{[^}]*\}/g, '')
    // Strip backtick subshell with empty/whitespace content
    .replace(/`\s*`/g, '');
  // Iteratively strip backslash between word chars (c\u\r\l needs 2 passes)
  let prev;
  do {
    prev = result;
    result = result.replace(/(\w)\\(\w)/g, '$1$2');
  } while (result !== prev);
  return result;
 }
 // Strip ANSI, collapse whitespace.
 export function normalizeCommand(cmd) {
  return cmd
    .replace(/\x1B\[[0-9;]*m/g, '')
    .replace(/\s+/g, ' ')
    .trim();
 }
 // ---------------------------------------------------------------------------
 // Command-position view -- for rules that must distinguish a command from data
 // that merely names one. Whitespace is NOT collapsed, so newline stays a
 // separator. Quoted spans and heredoc bodies become data; the argument of a
 // shell wrapper stays a command; backslash-escaped names are seen through.
 // ---------------------------------------------------------------------------
 // `out` ends with the `-c` of a shell invocation -- the next quoted span is a
 // command string, not data. Optional leading `sudo` and absolute path.
 const SHELL_C_TAIL =
  /(?:^|[\s;|&])(?:sudo\s+(?:-[a-zA-Z]+\s+)*)?(?:[\w./-]*\/)?(?:ba|z|k|da|a)?sh\s+(?:-[a-zA-Z]+\s+)*-c\s*$/;
 // Drop heredoc bodies, keeping the operator line. Their newlines are not
 // command separators, and without this every heredoc line that happens to
 // start with a matched word reads as command position. Runs before the quote
 // scan, since a body may contain quotes that would desync it.
 export function stripHeredocBodies(cmd) {
  return cmd.replace(
    /(<<-?\s*(['"]?)(\w+)\2[^\n]*\n)[\s\S]*?(?:\n[ \t]*\3[ \t]*(?=\n|$)|$)/g,
    (_match, head) => head,
  );
 }
 // `out` ends with `eval` -- like `sh -c`, its quoted argument is run as a command.
 const EVAL_TAIL = /(?:^|[\s;|&])eval\s*$/;
 // A quoted span that is one plain word ("push", 'git', "main").
 const PLAIN_WORD = /^[^\s'"`$;|&()<>{}\\]+$/;
 // opts.keepWords: a quoted plain word stays that word (`git "push"` reads as
 // `git push`); without it every quoted span is data, as the BLOCK rules have
 // always read it. Quoted text with spaces is data either way.
 export function commandPositionView(cmd, opts = {}) {
  const src = stripHeredocBodies(cmd);
  let out = '';
  let i = 0;
  while (i < src.length) {
    const ch = src[i];
    if (ch === '\\' && i + 1 < src.length) {
      // An escaped character is literal: `don\'t` opens no quote, and an
      // escaped space stays inside its word (so `a\ #b` starts no comment).
      // A backslash-newline continues the line.
      const next = src[i + 1];
      out += next === '\n' ? ' ' : /\s/.test(next) ? '_' : next;
      i += 2;
    } else if (ch === '#' && (out === '' || /[\s;|&(]$/.test(out))) {
      // A comment runs to the end of the line; its apostrophes are not quotes.
      const nl = src.indexOf('\n', i);
      i = nl === -1 ? src.length : nl;
    } else if (ch === "'" || ch === '"') {
      // Inside double quotes a backslash escapes the next character (`"a \" b"`
      // is one span); inside single quotes nothing is escaped.
      let close = i + 1;
      while (close < src.length && src[close] !== ch) close += ch === '"' && src[close] === '\\' ? 2 : 1;
      if (close >= src.length) close = -1;
      if (close === -1) {
        // Unterminated quote: the shell would not run this as written, so
        // read the rest as code rather than hide it as data.
        i += 1;
        continue;
      }
      const inner = src.slice(i + 1, close);
      if (SHELL_C_TAIL.test(out) || EVAL_TAIL.test(out)) out += `;${inner};`;
      else out += opts.keepWords && PLAIN_WORD.test(inner) ? inner : ' ';
      i = close + 1;
    } else {
      out += ch;
      i += 1;
    }
  }
  return (
    out
      // `xargs [flags] <cmd>` puts <cmd> at command position with no separator
      // in front of it. Flags taking a separate argument (`-I {}`) are not
      // parsed -- the separator lands before the argument, not the command.
      .replace(/\bxargs((?:\s+-[a-zA-Z0-9-]+)*)/g, 'xargs$1 ;')
      // `\name` runs name -- the backslash only suppresses alias expansion.
      // normalizeBashExpansion covers the between-word-chars case; this covers
      // a backslash at command position.
      .replace(/\\(\w)/g, '$1')
  );
 }
 // The command-position view of a raw command string, as the guards build it.
 export function viewOf(command, opts = {}) {
  return commandPositionView(normalizeBashExpansion(command).replace(/\x1B\[[0-9;]*m/g, ''), opts);
 }
--- a/hooks/lib/contract-cli.mjs
+++ b/hooks/lib/contract-cli.mjs
@ -0,0 +1,39 @@
 // hooks/lib/contract-cli.mjs
 // Runs a contract CLI that another wave-1 order owns (K2 approval log, K3 plan
 // gate, K5 arch rules) and maps its answer. A CLI that is not there yet, or
 // that cannot run, is "not measured" / "not logged" -- never green.
 import { existsSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 export const PLUGIN_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
 export const CONTRACTS = {
  K2: join(PLUGIN_ROOT, 'lib', 'util', 'approval-log.mjs'),
  K3: join(PLUGIN_ROOT, 'lib', 'validators', 'plan-gate.mjs'),
  K5: join(PLUGIN_ROOT, 'lib', 'verification', 'arch-rules.mjs'),
 };
 /**
 * @returns {{ ran: boolean, code: number|null, stdout: string, stderr: string, why?: string }}
 *   ran=false when the CLI file is missing or could not be started.
 */
 export function runContract(id, args, { cwd, timeout = 60_000 } = {}) {
  const cli = CONTRACTS[id];
  if (!existsSync(cli)) return { ran: false, code: null, stdout: '', stderr: '', why: `${id} CLI not present (${cli})` };
  // No shell: every argument is passed as-is, so no text is ever spliced into a command line.
  const r = spawnSync(process.execPath, [cli, ...args], { cwd, encoding: 'utf8', timeout });
  if (r.error || r.status === null) {
    return { ran: false, code: null, stdout: r.stdout || '', stderr: r.stderr || '', why: `${id} could not run (${r.error?.message || 'signal'})` };
  }
  return { ran: true, code: r.status, stdout: r.stdout || '', stderr: r.stderr || '' };
 }
 // A Voyage plan carries `plan_version` in its leading frontmatter block.
 export function isVoyagePlan(text) {
  if (typeof text !== 'string') return false;
  const m = text.replace(/^\uFEFF/, '').match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
  return !!m && /^plan_version\s*:/m.test(m[1]);
 }
--- a/hooks/lib/git-approval.mjs
+++ b/hooks/lib/git-approval.mjs
@ -0,0 +1,382 @@
 // hooks/lib/git-approval.mjs
 // P12 -- which shell commands need a person's approval before they run, and
 // which of those approvals go into the approval log (contract K2).
 //
 // The four classes (merge into main, push, tag/release, destructive git) are
 // Superpowers' (MIT, `8ca22db`); "a block names the way forward" is
 // agent-skills' (MIT, `9d0c60d`); guard + log is ai-native-sdlc's (MIT,
 // `11fb8d7`). Ideas only; no code is copied.
 //
 // Log kinds (operator decision 06.10): merge into main and push to main are
 // logged as `merge`; a tag, a pushed tag and a package publish as `release`.
 // A push of another branch and destructive git are asked about but not logged
 // (kind null): K2 has no kind for them, and the contract stays as it is.
 //
 // Read on the command-position view (bash-view.mjs), so a quoted commit
 // message or an `echo` that names `git push` is data, not a command. The
 // command is followed segment by segment: `cd <dir>`, `git -C <dir>` and
 // `git checkout|switch <branch>` change which repo and branch the next git
 // call acts on. Not seen: git aliases (`git p`), commands assembled in
 // variables, and `git worktree remove --force` (routine executor cleanup,
 // Hard Rule 12).
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { dirname, join, resolve, isAbsolute } from 'node:path';
 import { homedir } from 'node:os';
 import { viewOf } from './bash-view.mjs';
 // How long a logged P12 approval stays valid (K2 `--expires`).
 export const APPROVAL_TTL_MS = 60 * 60 * 1000;
 const MAIN = /^(?:main|master)$/;
 // Wrapper programs that run the command after them, with the options of each
 // that take a separate value.
 const WRAPPERS = {
  sudo: ['-u', '-g', '-C', '-D', '-h', '-p', '-r', '-t', '-U', '-T'],
  env: ['-u', '-S', '-C', '--unset', '--chdir', '--split-string'],
  timeout: ['-s', '-k', '--signal', '--kill-after'],
  nice: ['-n', '--adjustment'],
  time: ['-f', '-o', '--format', '--output'],
  exec: ['-a'],
  xargs: ['-n', '-I', '-L', '-P', '-d', '-E', '-s', '-a', '--max-args', '--max-procs', '--delimiter', '--arg-file', '--replace'],
  stdbuf: ['-i', '-o', '-e'],
  command: [], builtin: [], nohup: [], eval: [], then: [], do: [], else: [], '!': [],
  if: [], elif: [], while: [], until: [],
 };
 // git options that take a separate value before the subcommand.
 const GIT_OPTS_WITH_VALUE = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path', '--config-env']);
 const base = (p) => String(p || '').split('/').pop();
 // Redirections are not arguments: `git checkout main 2>/dev/null` names one
 // branch, not a branch and a path. An operator standing alone takes the next
 // token as its target.
 function dropRedirects(tokens) {
  const out = [];
  for (let i = 0; i < tokens.length; i += 1) {
    const t = tokens[i];
    if (/^\d*(?:>>?|<<?|>\|)$/.test(t)) { i += 1; continue; }
    if (/^\d*(?:>>?|<<?)\S/.test(t)) continue;
    out.push(t);
  }
  return out;
 }
 function segments(view) {
  return view
    // `2>&1`, `>&2`, `&>file` would otherwise split at their `&`.
    .replace(/\d*>&\d*-?/g, ' ')
    .replace(/&>>?/g, ' > ')
    .split(/\$\(|[\n;|&()`{}]/)
    .map((s) => s.trim())
    .filter(Boolean)
    .map((s) => dropRedirects(s.split(/\s+/)))
    .filter((t) => t.length);
 }
 // Drop env assignments and wrapper words (with their options); return the
 // tokens from the real program on.
 function programTokens(tokens) {
  let i = 0;
  while (i < tokens.length) {
    const t = tokens[i];
    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(t) || /^\d+$/.test(t)) { i += 1; continue; }
    const w = WRAPPERS[base(t)];
    if (!w) break;
    const name = base(t);
    i += 1;
    while (i < tokens.length && tokens[i].startsWith('-') && tokens[i] !== '-') {
      i += w.includes(tokens[i]) ? 2 : 1;
    }
    if (name === 'timeout' && i < tokens.length) i += 1; // the duration
  }
  return tokens.slice(i);
 }
 // For `git [global opts] <sub> <args...>`, return { sub, args, dir }.
 function gitCall(tokens) {
  if (base(tokens[0]) !== 'git') return null;
  let i = 1;
  let dir = null;
  while (i < tokens.length && tokens[i].startsWith('-')) {
    const t = tokens[i];
    if (t === '-C' && tokens[i + 1]) dir = dir ? join(dir, tokens[i + 1]) : tokens[i + 1];
    i += GIT_OPTS_WITH_VALUE.has(t) ? 2 : 1;
  }
  if (i >= tokens.length) return null;
  return { sub: tokens[i], args: tokens.slice(i + 1), dir };
 }
 const hasFlag = (args, ...flags) => args.some((a) => flags.includes(a));
 // A short-flag cluster such as -fdx contains `ch`.
 const shortHas = (args, ch) => args.some((a) => /^-[A-Za-z]+$/.test(a) && a.includes(ch));
 const positional = (args) => args.filter((a) => !a.startsWith('-'));
 // Positionals, skipping the values of the options that take one.
 function positionalSkipping(args, valued) {
  const out = [];
  for (let i = 0; i < args.length; i += 1) {
    if (valued.includes(args[i])) { i += 1; continue; }
    if (!args[i].startsWith('-')) out.push(args[i]);
  }
  return out;
 }
 const PUSH_VALUED = ['-o', '--push-option', '--repo', '--receive-pack', '--exec'];
 const WAY = {
  merge: 'approve to merge now; deny and Claude stops here. A merge into main is recorded in the approval log.',
  push: 'approve to push now; deny and Claude stops here. A push to main is recorded in the approval log.',
  release: 'approve to tag or publish now; deny and Claude stops here. The release is recorded in the approval log.',
  destructive: 'approve only if losing that work is intended; deny and Claude stops here. Nothing is logged.',
 };
 const destructive = (name) => ({ cls: 'destructive', name, kind: null });
 function classifyPush(args, ctx) {
  if (hasFlag(args, '-n', '--dry-run') || shortHas(args, 'n')) return [];
  const tags = hasFlag(args, '--tags', '--follow-tags');
  const del = hasFlag(args, '--delete', '-d');
  const force = hasFlag(args, '--force', '--force-with-lease', '--mirror') ||
    args.some((a) => a.startsWith('--force-with-lease=') || a.startsWith('+')) || shortHas(args, 'f');
  const refspecs = positionalSkipping(args, PUSH_VALUED).slice(1); // the first positional is the remote
  const out = [];
  let toMain = false;
  let other = false;
  let tagPush = tags;
  for (const r of refspecs) {
    if (del || r.startsWith(':')) { out.push(destructive('delete a remote branch or tag')); continue; }
    const dst = (r.includes(':') ? r.split(':').pop() : r).replace(/^\+/, '');
    const name = dst.replace(/^refs\/heads\//, '');
    if (dst.startsWith('refs/tags/') || (!dst.startsWith('refs/') && tagExists(ctx.cwd, name) && !MAIN.test(name))) tagPush = true;
    else if (MAIN.test(name) || (name === 'HEAD' && MAIN.test(ctx.branch || ''))) toMain = true;
    else other = true;
  }
  if (refspecs.length === 0 && !tags) {
    if (MAIN.test(ctx.branch || '')) toMain = true;
    else other = true;
  }
  if (toMain) out.push({ cls: 'push', name: force ? 'force push to main' : 'push to main', kind: 'merge' });
  if (other) out.push({ cls: 'push', name: force ? 'force push' : 'push', kind: null });
  if (tagPush) out.push({ cls: 'release', name: 'push of tags', kind: 'release' });
  return out;
 }
 function classifyGit(call, ctx) {
  const { sub, args } = call;
  switch (sub) {
    case 'push':
      return classifyPush(args, ctx);
    case 'merge':
      if (hasFlag(args, '--abort', '--continue', '--quit')) return [];
      return MAIN.test(ctx.branch || '') ? [{ cls: 'merge', name: 'merge into main', kind: 'merge' }] : [];
    case 'tag': {
      if (hasFlag(args, '-l', '--list', '-v', '--verify') || shortHas(args, 'l')) return [];
      if (hasFlag(args, '-d', '--delete')) return [{ cls: 'release', name: 'delete a tag', kind: null }];
      // Options that take a value: their value is not a tag name.
      const valued = new Set(['-m', '-F', '-u', '--message', '--file', '--local-user', '--sort', '--contains', '--no-contains', '--points-at', '--merged', '--no-merged', '--format', '--cleanup']);
      const names = [];
      for (let i = 0; i < args.length; i += 1) {
        if (valued.has(args[i])) { i += 1; continue; }
        if (!args[i].startsWith('-')) names.push(args[i]);
      }
      return names.length > 0 ? [{ cls: 'release', name: 'create a tag', kind: 'release' }] : [];
    }
    case 'reset':
      return hasFlag(args, '--hard') ? [destructive('hard reset')] : [];
    case 'clean':
      if (hasFlag(args, '-n', '--dry-run') || shortHas(args, 'n')) return [];
      return hasFlag(args, '--force') || shortHas(args, 'f') ? [destructive('clean with force')] : [];
    case 'branch': {
      const del = hasFlag(args, '-d', '--delete') || shortHas(args, 'd');
      const force = hasFlag(args, '-f', '--force') || shortHas(args, 'f');
      if (hasFlag(args, '-D') || shortHas(args, 'D') || (del && force)) return [destructive('force-delete a branch')];
      if (hasFlag(args, '-M') || shortHas(args, 'M')) return [destructive('force-rename a branch')];
      return [];
    }
    case 'stash':
      return args[0] === 'drop' || args[0] === 'clear' ? [destructive(`stash ${args[0]}`)] : [];
    case 'checkout': {
      if (hasFlag(args, '-b', '-B', '--orphan')) return [];
      const pos = positional(args);
      const discard = hasFlag(args, '--', '-f', '--force') || pos.includes('.') || pos.length >= 2;
      return discard ? [destructive('discard working-tree changes')] : [];
    }
    case 'switch':
      return hasFlag(args, '-f', '--force', '--discard-changes') ? [destructive('discard working-tree changes')] : [];
    case 'restore': {
      const staged = hasFlag(args, '--staged', '-S');
      const worktree = hasFlag(args, '--worktree', '-W');
      return !staged || worktree ? [destructive('discard working-tree changes')] : [];
    }
    case 'filter-branch':
    case 'filter-repo':
      return [destructive('history rewrite')];
    case 'update-ref':
      return hasFlag(args, '-d') ? [destructive('delete a ref')] : [];
    case 'reflog':
      return args[0] === 'expire' || args[0] === 'delete' ? [destructive('reflog expiry')] : [];
    default:
      return [];
  }
 }
 // The branch a checkout/switch leaves the repo on, or undefined if it does not move.
 function branchAfter(call) {
  const { sub, args } = call;
  if (sub !== 'checkout' && sub !== 'switch') return undefined;
  if (hasFlag(args, '--detach') || (sub === 'switch' && hasFlag(args, '-d'))) return null; // detached: no branch
  const create = sub === 'checkout' ? ['-b', '-B', '--orphan'] : ['-c', '-C', '--create', '--force-create', '--orphan'];
  for (let i = 0; i < args.length; i += 1) if (create.includes(args[i]) && args[i + 1]) return args[i + 1];
  if (hasFlag(args, '--')) return undefined;
  const pos = positional(args);
  return pos.length === 1 && pos[0] !== '.' ? pos[0] : undefined;
 }
 function classifyPublish(tokens) {
  let t = tokens;
  if (['npx', 'pnpx', 'bunx'].includes(base(t[0]))) t = t.slice(1);
  const prog = base(t[0]);
  if (['npm', 'pnpm', 'yarn', 'bun', 'cargo'].includes(prog)) {
    const rest = t.slice(1);
    // The subcommand is the first positional (option values skipped);
    // `yarn npm publish` is Yarn Berry's form.
    const pos = positionalSkipping(rest, ['--tag', '--registry', '--access', '--otp', '-w', '--workspace',
      '--filter', '--cwd', '-C', '--prefix', '--manifest-path', '--package', '-p', '--token']);
    const sub = prog === 'yarn' && pos[0] === 'npm' ? pos[1] : pos[0];
    if (sub === 'publish' && !hasFlag(rest, '--dry-run', '-n')) {
      return [{ cls: 'release', name: `${prog} publish`, kind: 'release' }];
    }
  }
  if (prog === 'gh' && t[1] === 'release' && t[2] === 'create') {
    return [{ cls: 'release', name: 'gh release create', kind: 'release' }];
  }
  return [];
 }
 const expandHome = (p) => (p === '~' ? homedir() : p.startsWith('~/') ? join(homedir(), p.slice(2)) : p);
 /**
 * Which approvals a command needs.
 * @param {string} command raw Bash command
 * @param {{ cwd?: string, branch?: string|null }} ctx where the command runs; `branch`
 *   overrides the branch read from `cwd` for the first segment (tests).
 * @returns {Array<{cls, name, kind: 'merge'|'release'|null, way, subject}>}
 *   `subject` is the top of the repo the matched call acts on.
 */
 export function classifyGitApproval(command, ctx = {}) {
  if (!command || typeof command !== 'string') return [];
  let cwd = resolve(ctx.cwd || process.cwd());
  let branch = ctx.branch !== undefined ? ctx.branch : currentBranch(cwd);
  const out = [];
  for (const seg of segments(viewOf(command, { keepWords: true }))) {
    const tokens = programTokens(seg);
    if (base(tokens[0]) === 'cd') {
      const to = tokens[1] && tokens[1] !== '-' ? tokens[1] : null;
      if (to) { cwd = resolve(cwd, expandHome(to)); branch = currentBranch(cwd); }
      continue;
    }
    const call = gitCall(tokens);
    if (call) {
      const callCwd = call.dir ? resolve(cwd, expandHome(call.dir)) : cwd;
      const callBranch = call.dir ? currentBranch(callCwd) : branch;
      const subject = repoRootOf(callCwd);
      for (const m of classifyGit(call, { branch: callBranch, cwd: callCwd })) out.push({ ...m, subject });
      const next = branchAfter(call);
      if (next !== undefined && !call.dir) branch = next;
      continue;
    }
    for (const m of classifyPublish(tokens)) out.push({ ...m, subject: repoRootOf(cwd) });
  }
  return out.map((m) => ({ ...m, way: WAY[m.cls] }));
 }
 // ---------------------------------------------------------------------------
 // The repository a command runs in -- read from the filesystem, no git spawn.
 // ---------------------------------------------------------------------------
 function findDotGit(start) {
  let dir = resolve(start);
  while (!existsSync(dir)) {
    const up = dirname(dir);
    if (up === dir) return null;
    dir = up;
  }
  for (;;) {
    const p = join(dir, '.git');
    if (existsSync(p)) return { root: dir, dotGit: p };
    const up = dirname(dir);
    if (up === dir) return null;
    dir = up;
  }
 }
 function gitDirOf(found) {
  try {
    if (statSync(found.dotGit).isDirectory()) return found.dotGit;
    const m = readFileSync(found.dotGit, 'utf8').match(/^gitdir:\s*(.+?)\s*$/m);
    if (!m) return null;
    return isAbsolute(m[1]) ? m[1] : resolve(found.root, m[1]);
  } catch {
    return null;
  }
 }
 // A worktree's git dir names the shared one in `commondir`; refs live there.
 function commonDirOf(gitDir) {
  try {
    const c = readFileSync(join(gitDir, 'commondir'), 'utf8').trim();
    return isAbsolute(c) ? c : resolve(gitDir, c);
  } catch {
    return gitDir;
  }
 }
 // The checked-out branch of the repo at `cwd`, or null (detached, no repo).
 export function currentBranch(cwd) {
  try {
    const found = findDotGit(cwd || process.cwd());
    if (!found) return null;
    const gitDir = gitDirOf(found);
    if (!gitDir) return null;
    const head = readFileSync(join(gitDir, 'HEAD'), 'utf8').trim();
    const m = head.match(/^ref:\s*refs\/heads\/(.+)$/);
    return m ? m[1] : null;
  } catch {
    return null;
  }
 }
 // Does tag `name` exist in the repo at `cwd` (loose or packed)?
 export function tagExists(cwd, name) {
  if (!name || name.includes('..')) return false;
  try {
    const found = findDotGit(cwd || process.cwd());
    if (!found) return false;
    const gitDir = gitDirOf(found);
    if (!gitDir) return false;
    const common = commonDirOf(gitDir);
    if (existsSync(join(common, 'refs', 'tags', name))) return true;
    const packed = join(common, 'packed-refs');
    return existsSync(packed) && readFileSync(packed, 'utf8').split('\n').some((l) => l.endsWith(` refs/tags/${name}`));
  } catch {
    return false;
  }
 }
 // The top of the repo at `cwd` (the approval's subject), or cwd itself.
 export function repoRootOf(cwd) {
  const found = findDotGit(cwd || process.cwd());
  return found ? found.root : resolve(cwd || process.cwd());
 }
 // The prompt text for an ask. Names Voyage, the classes, and the way forward.
 export function askReason(matches) {
  const names = [...new Set(matches.map((m) => m.name))].join('; ');
  const ways = [...new Set(matches.map((m) => m.way))].join(' ');
  return (
    `Voyage asks before this command (P12 approval guard): ${names}. ` +
    'It changes something outside this working copy or throws work away, so a person decides. ' +
    `Way forward: ${ways}`
  );
 }
--- a/hooks/lib/post-edit.mjs
+++ b/hooks/lib/post-edit.mjs
@ -0,0 +1,76 @@
 // hooks/lib/post-edit.mjs
 // Shared by the post-edit guard (P7, hooks/scripts/post-edit-check.mjs) and
 // the step check (K9, lib/verification/step-check.mjs): when the guard is on,
 // and where its log lives.
 //
 // On (operator decision 06.10): while Voyage executes a plan in the repo -- a
 // `.claude/projects/*/progress.json` (or legacy `.trekexecute-progress-*.json`)
 // with status "in_progress" -- or when the repo has switched it on with
 // `.claude/voyage-guards.json` = { "post_edit_check": true }. Off everywhere
 // else, because the guard is wired for every session in every repo.
 import { existsSync, readFileSync, readdirSync, mkdirSync, appendFileSync } from 'node:fs';
 import { join } from 'node:path';
 export const OPT_IN_FILE = join('.claude', 'voyage-guards.json');
 function readJson(p) {
  try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; }
 }
 function inProgress(p) {
  return readJson(p)?.status === 'in_progress';
 }
 export function executingPlan(root) {
  const projects = join(root, '.claude', 'projects');
  try {
    for (const d of readdirSync(projects, { withFileTypes: true })) {
      if (d.isDirectory() && inProgress(join(projects, d.name, 'progress.json'))) return true;
    }
  } catch { /* no projects dir */ }
  try {
    for (const f of readdirSync(root)) {
      if (/^\.trekexecute-progress-.+\.json$/.test(f) && inProgress(join(root, f))) return true;
    }
  } catch { /* unreadable root */ }
  return false;
 }
 export function optedIn(root) {
  const p = join(root, OPT_IN_FILE);
  return existsSync(p) && readJson(p)?.post_edit_check === true;
 }
 /** @returns {'plan'|'opt-in'|null} why the guard is on, or null when it is off */
 export function postEditActive(root) {
  if (optedIn(root)) return 'opt-in';
  if (executingPlan(root)) return 'plan';
  return null;
 }
 export function postEditLogPath(gitDir) {
  return join(gitDir, 'voyage', 'post-edit.jsonl');
 }
 export function appendPostEditLog(gitDir, record) {
  const p = postEditLogPath(gitDir);
  mkdirSync(join(gitDir, 'voyage'), { recursive: true });
  appendFileSync(p, JSON.stringify(record) + '\n');
  return p;
 }
 // The latest record per file (repo-relative path).
 export function latestPostEditRecords(gitDir) {
  const p = postEditLogPath(gitDir);
  const out = new Map();
  if (!existsSync(p)) return out;
  for (const line of readFileSync(p, 'utf8').split('\n')) {
    if (!line.trim()) continue;
    try {
      const r = JSON.parse(line);
      if (r && typeof r.file === 'string') out.set(r.file, r);
    } catch { /* a torn line is skipped, never read as clean */ }
  }
  return out;
 }
--- a/hooks/scripts/post-approval-log.mjs
+++ b/hooks/scripts/post-approval-log.mjs
@ -0,0 +1,89 @@
 #!/usr/bin/env node
 // Hook: post-approval-log.mjs
 // Event: PostToolUse (Bash, ExitPlanMode)
 // Purpose: write an approval a person gave through Claude Code's prompt into
 //   the approval log (contract K2, lib/util/approval-log.mjs).
 //   - Bash: the call ran, so the ask from pre-bash-executor.mjs was approved.
 //     What is logged is the record that hook wrote of what the person was
 //     asked (hooks/lib/approval-record.mjs); no record, nothing logged.
 //     Merge/push to main is logged as `merge`, tag/publish as `release`, each
 //     with `--expires` (APPROVAL_TTL_MS). Push of other branches and
 //     destructive git are not logged (operator decision 06.10). In
 //     bypassPermissions mode nothing is logged: no person was asked.
 //     sha256 binds the approval to the command and the commit it left HEAD on.
 //   - ExitPlanMode: the person approved a plan. A Voyage plan (it carries
 //     `plan_version`) is logged as `plan`, bound to the sha256 of the approved
 //     text (`tool_response.plan`, hooks reference section ExitPlanMode).
 // The guard never blocks (PostToolUse cannot), and it is never silent about a
 // lost approval: when K2 is missing, refuses (1) or cannot run (2), Claude is
 // told "not logged".
 import { readFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { APPROVAL_TTL_MS } from '../lib/git-approval.mjs';
 import { takeApprovalRecord } from '../lib/approval-record.mjs';
 import { runContract, isVoyagePlan } from '../lib/contract-cli.mjs';
 const sha256 = (s) => createHash('sha256').update(s).digest('hex');
 function say(text) {
  process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: text } }));
 }
 function headOf(cwd) {
  const r = spawnSync('git', ['rev-parse', 'HEAD'], { cwd, encoding: 'utf8', timeout: 10_000 });
  return r.status === 0 ? r.stdout.trim() : '';
 }
 function append(kind, subject, hash, cwd, expires) {
  const args = ['append', '--kind', kind, '--subject', subject, '--sha256', hash];
  if (expires) args.push('--expires', expires);
  const r = runContract('K2', args, { cwd });
  if (!r.ran) return `${kind} approval not logged: ${r.why}`;
  if (r.code === 0) return `${kind} approval logged${expires ? ` (expires ${expires})` : ''}`;
  const why = (r.stderr || r.stdout).trim().split('\n')[0] || `exit ${r.code}`;
  return `${kind} approval not logged: the approval log ${r.code === 1 ? 'refused it' : 'could not run'} (${why})`;
 }
 let input;
 try {
  input = JSON.parse(readFileSync(0, 'utf-8'));
 } catch {
  process.exit(0);
 }
 const cwd = input?.cwd || process.cwd();
 if (input?.tool_name === 'ExitPlanMode') {
  const plan = input?.tool_response?.plan ?? input?.tool_input?.plan;
  if (!isVoyagePlan(plan)) process.exit(0);
  const subject = input?.tool_response?.filePath || input?.tool_input?.planFilePath || '(plan without a file path)';
  say(`[voyage] ${append('plan', subject, sha256(plan), cwd)}.`);
  process.exit(0);
 }
 if (input?.tool_name === 'Bash') {
  // Log what the person was asked (pre-bash-executor.mjs wrote it), nothing else.
  const rec = takeApprovalRecord(input?.session_id, input?.tool_use_id);
  const matches = (rec?.matches || []).filter((m) => m.kind);
  if (matches.length === 0) process.exit(0);
  if (rec.permission_mode === 'bypassPermissions') {
    say('[voyage] approval not logged: the session runs in bypassPermissions mode, so no person was asked.');
    process.exit(0);
  }
  const expires = new Date(Date.now() + APPROVAL_TTL_MS).toISOString();
  const seen = new Set();
  const notes = [];
  for (const m of matches) {
    const key = `${m.kind}\n${m.subject}`;
    if (seen.has(key)) continue;
    seen.add(key);
    const subject = m.subject || cwd;
    const hash = sha256(`${rec.command}\n${headOf(subject)}`);
    notes.push(append(m.kind, subject, hash, cwd, expires));
  }
  say(`[voyage] ${notes.join('; ')}.`);
 }
 process.exit(0);
--- a/hooks/scripts/post-edit-check.mjs
+++ b/hooks/scripts/post-edit-check.mjs
@ -0,0 +1,90 @@
 #!/usr/bin/env node
 // Hook: post-edit-check.mjs
 // Event: PostToolUse (Edit, Write)
 // Purpose: P7 -- after each edit, run the target repo's OWN formatter and
 //   linter on the edited file (the fast tier of three: per file here / step
 //   end and full in lib/verification/step-check.mjs, contract K9). Findings go
 //   back to Claude next to the tool result (`decision: "block"`, hooks
 //   reference section PostToolUse decision control); the edit itself already
 //   happened, so the stop is at step end, where K9 exits 1 on them.
 //   A file no configured, installed tool covers is "not measured" -- never
 //   clean. Every result is logged in <git dir>/voyage/post-edit.jsonl for K9.
 //
 // On only while Voyage executes a plan in the repo, or when the repo has
 // switched it on (hooks/lib/post-edit.mjs; operator decision 06.10). In every
 // other session it exits at once and says nothing.
 //
 // Credit: running the formatter after Edit|Write is Anthropic's own documented
 // hook pattern (hooks-guide); formatting per edit and the rest at step end is
 // Cherny's; the cost tiers and "not measured" are agent-skills' (MIT); the
 // per-file / step-end split is Kiro's. Ideas only.
 import { readFileSync } from 'node:fs';
 import { relative } from 'node:path';
 import { resolveRepo, detectTools, toolsForFile, runTool, canonicalPath } from '../../lib/verification/repo-tools.mjs';
 import { postEditActive, appendPostEditLog } from '../lib/post-edit.mjs';
 let input;
 try {
  input = JSON.parse(readFileSync(0, 'utf-8'));
 } catch {
  process.exit(0);
 }
 const file = input?.tool_input?.file_path;
 if (!file || typeof file !== 'string') process.exit(0);
 const repo = resolveRepo(file);
 if (!repo) process.exit(0);
 const why = postEditActive(repo.root);
 if (!why) process.exit(0);
 const rel = relative(repo.root, canonicalPath(file));
 const all = detectTools(repo.root);
 const tools = toolsForFile(all, file);
 const record = { ts: new Date().toISOString(), file: rel, on: why, session: input?.session_id ?? null };
 function out(obj) {
  process.stdout.write(JSON.stringify(obj));
  process.exit(0);
 }
 if (tools.length === 0) {
  const missing = all.filter((t) => !t.available).map((t) => t.reason);
  appendPostEditLog(repo.gitDir, { ...record, status: 'not_measured', results: [], reason: missing.join('; ') || 'no tool for this file type' });
  out({
    hookSpecificOutput: {
      hookEventName: 'PostToolUse',
      additionalContext:
        `[voyage] post-edit check: not measured for ${rel} -- no formatter or linter for this file type is ` +
        `both configured and installed in this repository${missing.length ? ` (${missing.join('; ')})` : ''}.`,
    },
  });
 }
 const results = tools.map((t) => runTool(t, [rel], { cwd: repo.root, timeout: 30_000 }));
 const findings = results.filter((r) => r.status === 'finding');
 const errors = results.filter((r) => r.status === 'error');
 const status = findings.length ? 'finding' : errors.length ? 'not_measured' : 'clean';
 appendPostEditLog(repo.gitDir, { ...record, status, results: results.map(({ output, ...r }) => r) });
 const errText = errors.length ? ` Not measured: ${errors.map((e) => `${e.name} could not run (exit ${e.exit})`).join('; ')}.` : '';
 if (findings.length) {
  out({
    decision: 'block',
    reason:
      `[voyage] post-edit check found problems in ${rel}: ` +
      findings.map((f) => `${f.name} (${f.kind}): ${f.output.split('\n').slice(0, 15).join('\n')}`).join('\n') +
      `\nFix them before the step ends; the step check fails on them.${errText}`,
  });
 }
 out({
  hookSpecificOutput: {
    hookEventName: 'PostToolUse',
    additionalContext: status === 'clean'
      ? `[voyage] post-edit check clean for ${rel}: ${results.map((r) => r.name).join(', ')}.`
      : `[voyage] post-edit check for ${rel}:${errText}`,
  },
 });
--- a/hooks/scripts/pre-agent-cap.mjs
+++ b/hooks/scripts/pre-agent-cap.mjs
@ -1,8 +1,16 @@
 #!/usr/bin/env node
 // Hook: pre-agent-cap.mjs
-// Event: PreToolUse (WebSearch | WebFetch | Task)
+// Event: PreToolUse (WebSearch | WebFetch | Task | Agent)
 // Purpose: Enforce the /trekresearch Phase 5 loop bound at the harness level,
 //   so the cap is a reader that fells rather than prose the model obeys.
 //   The subagent tool is `Agent` since Claude Code 2.1.63; the docs keep `Task`
 //   as an alias only "in settings and agent definitions", so the matcher names
 //   both (tests/hooks/storm-matcher.test.mjs).
 //
 // Precondition: Voyage's guards are deterministic only when no installed mod
 //   handles `tool.check`. A mod that does answers after the PreToolUse hooks
 //   and can replace their answer (code.claude.com/docs/en/permissions section Extend
 //   permissions with hooks). A hook cannot see whether such a mod is installed.
 //
 // Why this exists: the Phase 5 budget gate (lib/util/research-loop-cap.mjs) is
 // invoked BY the loop. A gate the caller chooses to consult is advice. The
--- a/hooks/scripts/pre-bash-executor.mjs
+++ b/hooks/scripts/pre-bash-executor.mjs
@ -1,51 +1,51 @@
 #!/usr/bin/env node
 // Hook: pre-bash-executor.mjs
 // Event: PreToolUse (Bash)
-// Purpose: Block or warn about destructive shell commands. Wired universally
+// Purpose: Block or warn about destructive shell commands, and ask a person
-//   (every Voyage session, not just execution) by deliberate decision — these
+//   before merge into main, push, tag/release and destructive git (P12).
-//   are session-agnostic safety rails (rm -rf /, fork bombs, …). The CC if:
+//   Wired universally (every Voyage session, not just execution) by deliberate
-//   path-scoping mechanism now works, but narrowing to execute-only would only
+//   decision -- these are session-agnostic safety rails (rm -rf /, fork bombs,
-//   weaken protection with no offsetting benefit. See cc-upgrade matrix CC-15/F2.
+//   ...). The CC if: path-scoping mechanism now works, but narrowing to
 //   execute-only would only weaken protection with no offsetting benefit. See
 //   cc-upgrade matrix CC-15/F2.
 //
 // Precondition: Voyage's guards are deterministic only when no installed mod
 //   handles `tool.check`. A mod that does answers after the PreToolUse hooks
 //   and can replace their answer (code.claude.com/docs/en/permissions section Extend
 //   permissions with hooks). A hook cannot see whether such a mod is installed.
 //
 // Protocol:
-//   - Read JSON from stdin: { tool_name, tool_input }
+//   - Read JSON from stdin: { tool_name, tool_input, cwd }
 //   - tool_input.command — the shell command string
 //   - BLOCK (exit 2): catastrophic/irreversible operations
 //   - ASK   (exit 0, JSON permissionDecision "ask"): merge into main, push,
 //     tag/release, destructive git (hooks/lib/git-approval.mjs). The prompt is
 //     labelled [plugin:voyage] and also appears in auto mode (hooks reference
 //     section PreToolUse decision control). Advisories are added to the prompt.
 //   - WARN  (exit 0): risky but recoverable operations — advisory to stderr
 //   - Allow (exit 0): everything else
 //
 // Based on llm-security's pre-bash-destructive.mjs with executor-specific additions.
-// bash-normalize logic copied inline (MIT) — cannot import from separate plugin.
+// Command reading lives in hooks/lib/bash-view.mjs (shared with the hook that
 // logs approvals).
 import { readFileSync } from 'node:fs';
-// ---------------------------------------------------------------------------
+// The guard's own modules are loaded so that a broken install cannot crash
-// Bash normalization (from llm-security/scanners/lib/bash-normalize.mjs)
+// the hook: a crash (exit 1) is a non-blocking error to Claude Code, which
-// Strips bash evasion techniques: empty quotes, ${} expansion, backslash splitting.
+// would let every command through. A module that will not load makes the
-// ---------------------------------------------------------------------------
+// guard ask about every command instead.
-function normalizeBashExpansion(cmd) {
+let lib;
-  if (!cmd || typeof cmd !== 'string') return cmd || '';
+let loadError = null;
-
+try {
-  let result = cmd
+  const [view, approval, record] = await Promise.all([
-    // Strip empty single quotes: w''get -> wget
+    import('../lib/bash-view.mjs'),
-    .replace(/''/g, '')
+    import('../lib/git-approval.mjs'),
-    // Strip empty double quotes: r""m -> rm
+    import('../lib/approval-record.mjs'),
-    .replace(/""/g, '')
+  ]);
-    // Single-char ${x} -> x (evasion: c${u}rl -> curl, assumes x=x)
+  lib = { ...view, ...approval, ...record };
-    .replace(/\$\{(\w)\}/g, '$1')
+} catch (e) {
-    // Multi-char ${ANYTHING} -> '' (unknown value, strip entirely)
+  loadError = e;
    .replace(/\$\{[^}]*\}/g, '')
    // Strip backtick subshell with empty/whitespace content
    .replace(/`\s*`/g, '');
  // Iteratively strip backslash between word chars (c\u\r\l needs 2 passes)
  let prev;
  do {
    prev = result;
    result = result.replace(/(\w)\\(\w)/g, '$1$2');
  } while (result !== prev);
  return result;
 }
 // ---------------------------------------------------------------------------
@ -197,69 +197,6 @@ const WARN_RULES = [
  },
 ];
 // ---------------------------------------------------------------------------
 // Normalize: strip ANSI, collapse whitespace
 // ---------------------------------------------------------------------------
 function normalizeCommand(cmd) {
  return cmd
    .replace(/\x1B\[[0-9;]*m/g, '')
    .replace(/\s+/g, ' ')
    .trim();
 }
 // ---------------------------------------------------------------------------
 // Command-position view — for rules that must distinguish a command from data
 // that merely names one. Whitespace is NOT collapsed, so newline stays a
 // separator. Quoted spans and heredoc bodies become data; the argument of a
 // shell wrapper stays a command; backslash-escaped names are seen through.
 // ---------------------------------------------------------------------------
 // `out` ends with the `-c` of a shell invocation — the next quoted span is a
 // command string, not data. Optional leading `sudo` and absolute path.
 const SHELL_C_TAIL =
  /(?:^|[\s;|&])(?:sudo\s+(?:-[a-zA-Z]+\s+)*)?(?:[\w./-]*\/)?(?:ba|z|k|da|a)?sh\s+(?:-[a-zA-Z]+\s+)*-c\s*$/;
 // Drop heredoc bodies, keeping the operator line. Their newlines are not
 // command separators, and without this every heredoc line that happens to
 // start with a matched word reads as command position. Runs before the quote
 // scan, since a body may contain quotes that would desync it.
 function stripHeredocBodies(cmd) {
  return cmd.replace(
    /(<<-?\s*(['"]?)(\w+)\2[^\n]*\n)[\s\S]*?(?:\n[ \t]*\3[ \t]*(?=\n|$)|$)/g,
    (_match, head) => head,
  );
 }
 function commandPositionView(cmd) {
  const src = stripHeredocBodies(cmd);
  let out = '';
  let i = 0;
  while (i < src.length) {
    const ch = src[i];
    if (ch === "'" || ch === '"') {
      const close = src.indexOf(ch, i + 1);
      const inner = close === -1 ? src.slice(i + 1) : src.slice(i + 1, close);
      // Unterminated quote — treat the remainder as one span and stop.
      out += SHELL_C_TAIL.test(out) ? `;${inner};` : ' ';
      i = close === -1 ? src.length : close + 1;
    } else {
      out += ch;
      i += 1;
    }
  }
  return (
    out
      // `xargs [flags] <cmd>` puts <cmd> at command position with no separator
      // in front of it. Flags taking a separate argument (`-I {}`) are not
      // parsed — the separator lands before the argument, not the command.
      .replace(/\bxargs((?:\s+-[a-zA-Z0-9-]+)*)/g, 'xargs$1 ;')
      // `\name` runs name — the backslash only suppresses alias expansion.
      // normalizeBashExpansion covers the between-word-chars case; this covers
      // a backslash at command position.
      .replace(/\\(\w)/g, '$1')
  );
 }
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@ -278,6 +215,20 @@ if (!command || typeof command !== 'string') {
  process.exit(0);
 }
 if (loadError) {
  process.stdout.write(JSON.stringify({
    hookSpecificOutput: {
      hookEventName: 'PreToolUse',
      permissionDecision: 'ask',
      permissionDecisionReason:
        `Voyage's Bash guard could not load its rules (${loadError.message}), so this command was not checked. ` +
        'Way forward: approve only a command you have read yourself; reinstall Voyage to restore the guard.',
    },
  }));
  process.exit(0);
 }
 const { normalizeBashExpansion, normalizeCommand, commandPositionView, classifyGitApproval, askReason, writeApprovalRecord } = lib;
 // Strip bash evasion, then normalize whitespace
 const deobfuscated = normalizeBashExpansion(command);
 const normalized = normalizeCommand(deobfuscated);
@ -311,4 +262,35 @@ if (warnings.length > 0) {
  );
 }
 // P12: ask a person before merge into main, push, tag/release, destructive git.
 // A classifier error must not turn into a silent allow of a push: ask instead.
 let approvals;
 try {
  approvals = classifyGitApproval(command, { cwd: input.cwd });
 } catch (e) {
  approvals = [{ name: `a command the approval guard could not read (${e.message})`, kind: null, way: 'approve only if you have read the command yourself.' }];
 }
 if (approvals.length > 0) {
  // What the person is asked is what post-approval-log.mjs logs once the call ran.
  const loggable = approvals.filter((m) => m.kind).map(({ kind, name, subject }) => ({ kind, name, subject }));
  const recorded = writeApprovalRecord(input.session_id, input.tool_use_id, {
    command,
    permission_mode: input.permission_mode ?? null,
    matches: loggable,
    asked_at: new Date().toISOString(),
  });
  // Say it now if this approval cannot reach the log afterwards.
  const unlogged = loggable.length > 0 && !recorded
    ? ' Note: this approval will not be logged (Voyage could not record the question).' : '';
  const advisory = (warnings.length > 0 ? ` Advisory: ${warnings.map((w) => w.trim()).join(' ')}` : '') + unlogged;
  process.stdout.write(JSON.stringify({
    hookSpecificOutput: {
      hookEventName: 'PreToolUse',
      permissionDecision: 'ask',
      permissionDecisionReason: askReason(approvals) + advisory,
    },
  }));
 }
 process.exit(0);
--- a/hooks/scripts/pre-plan-gate.mjs
+++ b/hooks/scripts/pre-plan-gate.mjs
@ -0,0 +1,71 @@
 #!/usr/bin/env node
 // Hook: pre-plan-gate.mjs
 // Event: PreToolUse (ExitPlanMode)
 // Purpose: P3 -- wrap Claude Code's plan approval. Claude Code hands this hook
 //   the plan text and the plan file path (hooks reference section ExitPlanMode:
 //   "Claude Code injects the plan content and file path before passing the
 //   input to hooks"). For a Voyage plan (it carries `plan_version`) the hook
 //   runs Voyage's plan gate (contract K3, lib/validators/plan-gate.mjs) on that
 //   file and sends a plan the gate refuses back to planning. Every other plan
 //   passes untouched: the hook runs in every session.
 //
 // Precondition: Voyage's guards are deterministic only when no installed mod
 //   handles `tool.check`. A mod that does answers after the PreToolUse hooks
 //   and can replace their answer (code.claude.com/docs/en/permissions section Extend
 //   permissions with hooks). A hook cannot see whether such a mod is installed.
 //
 // Answers:
 //   - K3 exit 0           -> exit 0, no output (Claude Code's own approval follows)
 //   - K3 exit 1           -> exit 2 (deny): the gate's words go to Claude
 //   - K3 exit 2 / missing / no plan file -> "ask" with "not measured": never a
 //     silent pass, and not a refusal of a plan nobody could check
 // Credit: wrapping plan mode is Claude Code's own pattern (P3 analysis).
 import { readFileSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { runContract, isVoyagePlan } from '../lib/contract-cli.mjs';
 function ask(reason) {
  process.stdout.write(JSON.stringify({
    hookSpecificOutput: {
      hookEventName: 'PreToolUse',
      permissionDecision: 'ask',
      permissionDecisionReason: `Voyage plan gate: not measured (${reason}). Approve only if you have checked the plan yourself.`,
    },
  }));
  process.exit(0);
 }
 let input;
 try {
  input = JSON.parse(readFileSync(0, 'utf-8'));
 } catch {
  // Unreadable input: nothing to judge, and no plan to call Voyage's.
  process.exit(0);
 }
 const plan = input?.tool_input?.plan;
 if (!isVoyagePlan(plan)) process.exit(0);
 const cwd = input?.cwd || process.cwd();
 const given = input?.tool_input?.planFilePath;
 // Plan paths are absolute in practice; a relative one is read from the
 // session's directory, the same one the gate runs in.
 const planPath = typeof given === 'string' && given ? resolve(cwd, given) : null;
 if (!planPath || !existsSync(planPath)) {
  ask('Claude Code attached no readable plan file');
 }
 const r = runContract('K3', [planPath], { cwd });
 if (!r.ran) ask(r.why);
 if (r.code === 0) process.exit(0);
 if (r.code === 1) {
  const words = (r.stdout + r.stderr).trim().slice(0, 4000) || 'the plan gate refused the plan';
  process.stderr.write(
    '[voyage] Plan sent back: Voyage\'s plan gate refused this plan.\n' +
    `${words}\n` +
    'Way forward: fix what the gate names, or plan again; then ask for approval again.\n'
  );
  process.exit(2);
 }
 ask(`the plan gate exited ${r.code}`);
--- a/hooks/scripts/pre-write-executor.mjs
+++ b/hooks/scripts/pre-write-executor.mjs
@ -6,6 +6,12 @@
 //   ~/.ssh, ~/.aws, .git/hooks, .env, shell configs benefits every session.
 //   The CC if: path-scoping mechanism now works, but narrowing to execute-only
 //   would only weaken protection with no benefit. See cc-upgrade matrix CC-15/F2.
 //   Also enforces the test lock (P9, contract K8, lib/util/test-lock.mjs).
 //
 // Precondition: Voyage's guards are deterministic only when no installed mod
 //   handles `tool.check`. A mod that does answers after the PreToolUse hooks
 //   and can replace their answer (code.claude.com/docs/en/permissions section Extend
 //   permissions with hooks). A hook cannot see whether such a mod is installed.
 //
 // Protocol:
 //   - Read JSON from stdin: { tool_name, tool_input }
@ -13,11 +19,26 @@
 //     tool_input.notebook_path (NotebookEdit)
 //   - BLOCK (exit 2): writes to security infrastructure, shell configs, secrets
 //   - BLOCK (exit 2): no readable target path (fail closed)
 //   - BLOCK (exit 2): a test file the current step has locked (K8), and any
 //     write in a repo whose lock cannot be read (fail closed)
 //   - Allow (exit 0): everything else
 // Bash can still rewrite a locked file (sed -i, >); this guard covers the
 // file tools only.
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 // The lock code is loaded so that a broken install cannot crash this hook (a
 // crash is a non-blocking error: every write would pass, the path rules
 // included). A lock module that will not load blocks the write instead.
 let lockLib = null;
 let lockLoadError = null;
 try {
  lockLib = await import('../../lib/util/test-lock.mjs');
 } catch (e) {
  lockLoadError = e;
 }
 const HOME = process.env.HOME || process.env.USERPROFILE || '/tmp';
 // ---------------------------------------------------------------------------
@ -26,11 +47,20 @@ const HOME = process.env.HOME || process.env.USERPROFILE || '/tmp';
 const BLOCK_RULES = [
  {
    name: 'Git hook injection (.git/hooks/)',
-    test: (p) => /\/\.git\/hooks\//.test(p),
+    test: (p) => /\/\.git\/hooks\//i.test(p),
    description:
      'Writing to .git/hooks/ could inject malicious git hooks that execute ' +
      'on every commit, push, or checkout. Blocked.',
  },
  {
    name: "Voyage's own guard state (.git/voyage/)",
    // The test lock and the post-edit log. A worktree's git dir is
    // .git/worktrees/<name>/, so that form is covered too.
    test: (p) => /\/\.git\/(?:worktrees\/[^/]+\/)?voyage(?:\/|$)/i.test(p),
    description:
      'Writing to the git directory\'s voyage/ folder would unlock a locked test or ' +
      'rewrite the post-edit log. Blocked; the executor and the operator manage it.',
  },
  {
    name: 'Claude settings self-modification',
    test: (p) => /\/\.claude\/settings[^/]*\.json$/.test(p),
@ -149,5 +179,39 @@ for (const rule of BLOCK_RULES) {
  }
 }
 // P9 test lock (K8).
 if (lockLoadError) {
  process.stderr.write(
    '[voyage] BLOCKED: the test-lock guard could not load\n' +
    `  ${lockLoadError.message}\n` +
    '  Without it no write can be checked against a locked test. Blocked (fail ' +
    'closed). Reinstall Voyage to restore the guard.\n'
  );
  process.exit(2);
 }
 const { readLock, isLockedFile } = lockLib;
 const lock = readLock(resolved);
 if (lock.state === 'corrupt') {
  process.stderr.write(
    '[voyage] BLOCKED: unreadable test lock\n' +
    `  Lock: ${lock.path} (${lock.error})\n` +
    '  A step locked its tests, but the lock cannot be read, so no write in this ' +
    'repository can be checked against it. Blocked (fail closed). Ask the operator ' +
    'to inspect the lock file.\n'
  );
  process.exit(2);
 }
 if (lock.state === 'locked' && isLockedFile(lock.lock, resolved)) {
  process.stderr.write(
    `[voyage] BLOCKED: locked test file (step ${lock.lock.step})\n` +
    `  Path: ${resolved}\n` +
    `  Step ${lock.lock.step} locked this test after it was seen failing; it must pass ` +
    'unchanged. Way forward: change the code under test, not the test. If the test ' +
    'itself is wrong, stop and tell the operator; only the operator or the executor ' +
    'unlocks it.\n'
  );
  process.exit(2);
 }
 // Allow
 process.exit(0);
--- a/hooks/scripts/stop-test-lock.mjs
+++ b/hooks/scripts/stop-test-lock.mjs
@ -0,0 +1,50 @@
 #!/usr/bin/env node
 // Hook: stop-test-lock.mjs
 // Event: Stop
 // Purpose: P9 (3) -- "done" is refused while a step's tests are locked (K8,
 //   lib/util/test-lock.mjs). The executor unlocks a step only after its test
 //   passes, so a held lock means the step's test has not been seen passing.
 //
 // Scope: only the session that took the lock is held (the lock records
 //   CLAUDE_CODE_SESSION_ID, which the docs say matches the hook input's
 //   session_id: code.claude.com/docs/en/env-vars). Any other session
 //   in the same repository stops freely, so a lock left behind by a crash
 //   cannot trap unrelated work.
 // Loop guard: when stop_hook_active is true, Claude Code is already continuing
 //   because of a stop hook; this hook then lets the stop through
 //   (code.claude.com/docs/en/hooks section Stop input; hooks-guide "Stop hook hits
 //   the block cap").
 // TaskCompleted is not used: it fires on the TaskUpdate tool, which current
 //   models do not get by default (tools-reference section Task tool availability).
 //
 // Credit: refusing "done" until the check passes is Claude Code's own
 // documented pattern (hooks reference section TaskCompleted / Stop decision control).
 import { readFileSync } from 'node:fs';
 import { readLock, lockForSession } from '../../lib/util/test-lock.mjs';
 let input;
 try {
  input = JSON.parse(readFileSync(0, 'utf-8'));
 } catch {
  process.exit(0);
 }
 if (input?.stop_hook_active === true) process.exit(0);
 // The lock in the session's current repo, else the one this session took
 // elsewhere (the session may have moved to another directory since).
 let lock = readLock(input?.cwd || process.cwd());
 if (lock.state !== 'locked' || lock.lock.session !== input?.session_id) lock = lockForSession(input?.session_id);
 if (lock.state !== 'locked') process.exit(0);
 if (!lock.lock.session || lock.lock.session !== input?.session_id) process.exit(0);
 const files = lock.lock.files.join(', ');
 process.stdout.write(JSON.stringify({
  decision: 'block',
  reason:
    `[voyage] Not done: step ${lock.lock.step} still holds its test lock (${files}). ` +
    "The step is done when its test passes and the executor unlocks it. Run the step's " +
    'test; if it passes, finish the step. If it cannot pass, say so plainly and stop.',
 }));
 process.exit(0);
--- a/lib/util/test-lock.mjs
+++ b/lib/util/test-lock.mjs
@ -0,0 +1,186 @@
 #!/usr/bin/env node
 // lib/util/test-lock.mjs
 // K8 -- the test lock. The executor (wave-1 order 1) locks a step's test files
 // once the test is written and seen failing, and unlocks them when the test
 // passes. Two guards read the lock:
 //   - pre-write-executor.mjs refuses Write/Edit/NotebookEdit on a locked file;
 //   - stop-test-lock.mjs refuses "done" while the session that took the lock
 //     still holds it.
 // The lock lives in the repository's git directory (<git dir>/voyage/
 // test-lock.json), so it can never be committed, and each worktree has its own.
 //
 // Usage:
 //   node lib/util/test-lock.mjs lock --files <a,b> --step <N> [--cwd <dir>]
 //   node lib/util/test-lock.mjs unlock [--cwd <dir>]
 //   node lib/util/test-lock.mjs status [--cwd <dir>]      (JSON on stdout)
 // Exit: 0 = done, 1 = refused (another step holds the lock), 2 = could not
 // run (not a repository, bad usage, unreadable lock). 2 is never "unlocked".
 // Paths in --files are relative to the --cwd (default: the current directory).
 // The session is taken from CLAUDE_CODE_SESSION_ID, which Claude Code sets in
 // Bash tool subprocesses (code.claude.com/docs/en/env-vars).
 //
 // Credit: locking tests during a fix is Claude Code's own hook pattern
 // (hooks-guide "Block edits to protected files").
 import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync, realpathSync, readdirSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createHash } from 'node:crypto';
 import { tmpdir } from 'node:os';
 import { resolveRepo, canonicalPath } from '../verification/repo-tools.mjs';
 export const LOCK_VERSION = 1;
 export function lockPathFor(gitDir) {
  return join(gitDir, 'voyage', 'test-lock.json');
 }
 /**
 * Read the lock for the repo that `start` (a file or directory) belongs to.
 * @returns {{ state: 'no-repo'|'none'|'locked'|'corrupt', lock?: object, path?: string, error?: string }}
 */
 export function readLock(start) {
  const repo = resolveRepo(start);
  if (!repo) return { state: 'no-repo' };
  const path = lockPathFor(repo.gitDir);
  if (!existsSync(path)) return { state: 'none', path, repo };
  try {
    const lock = JSON.parse(readFileSync(path, 'utf8'));
    if (!lock || !Array.isArray(lock.files) || !Number.isInteger(lock.step)) {
      return { state: 'corrupt', path, repo, error: 'lock has no files/step' };
    }
    return { state: 'locked', lock, path, repo };
  } catch (e) {
    return { state: 'corrupt', path, repo, error: e.message };
  }
 }
 // A pointer from the session that took a lock to the lock file, so the stop
 // guard finds it even after the session has moved to another directory.
 const SESSION_DIR = join(tmpdir(), `voyage-test-locks-${process.getuid ? process.getuid() : 'u'}`);
 const sessionPointer = (sessionId) =>
  join(SESSION_DIR, `${createHash('sha256').update(String(sessionId)).digest('hex').slice(0, 32)}.json`);
 // Pointers whose lock is gone are dropped on the next lock.
 function sweepPointers() {
  try {
    for (const f of readdirSync(SESSION_DIR)) {
      const p = join(SESSION_DIR, f);
      try {
        if (!existsSync(JSON.parse(readFileSync(p, 'utf8')).lock_path)) rmSync(p, { force: true });
      } catch { rmSync(p, { force: true }); }
    }
  } catch { /* no dir yet */ }
 }
 function writeSessionPointer(sessionId, lockPath) {
  if (!sessionId) return;
  try {
    mkdirSync(SESSION_DIR, { recursive: true });
    sweepPointers();
    writeFileSync(sessionPointer(sessionId), JSON.stringify({ lock_path: lockPath }));
  } catch { /* the cwd lookup still works */ }
 }
 function removeSessionPointer(sessionId) {
  if (sessionId) rmSync(sessionPointer(sessionId), { force: true });
 }
 /**
 * The lock this session holds, wherever it lives: { state: 'locked', lock, path }
 * or { state: 'none' }. A pointer to a lock that is gone, or that another
 * session now holds, is not this session's lock.
 */
 export function lockForSession(sessionId) {
  if (!sessionId) return { state: 'none' };
  try {
    const { lock_path } = JSON.parse(readFileSync(sessionPointer(sessionId), 'utf8'));
    const lock = JSON.parse(readFileSync(lock_path, 'utf8'));
    if (lock?.session === sessionId && Array.isArray(lock.files) && Number.isInteger(lock.step)) {
      return { state: 'locked', lock, path: lock_path };
    }
  } catch { /* no pointer, or the lock is gone */ }
  return { state: 'none' };
 }
 // Is `file` one of the locked files? Compared as canonical real paths.
 export function isLockedFile(lock, file) {
  const c = canonicalPath(file);
  return lock.files.includes(c);
 }
 function parseArgs(argv) {
  const out = { _: [] };
  for (let i = 0; i < argv.length; i += 1) {
    const a = argv[i];
    if (a === '--files' || a === '--step' || a === '--cwd') { out[a.slice(2)] = argv[i + 1]; i += 1; }
    else out._.push(a);
  }
  return out;
 }
 function fail(code, msg) {
  process.stderr.write(`[voyage] test-lock: ${msg}\n`);
  process.exit(code);
 }
 function main(argv) {
  const args = parseArgs(argv);
  const cmd = args._[0];
  if (!['lock', 'unlock', 'status'].includes(cmd)) fail(2, 'usage: test-lock.mjs lock --files <a,b> --step <N> | unlock | status [--cwd <dir>]');
  const cwd = resolve(args.cwd || process.cwd());
  const cur = readLock(cwd);
  if (cur.state === 'no-repo') fail(2, `not a git repository: ${cwd}`);
  if (cmd === 'status') {
    if (cur.state === 'corrupt') {
      process.stdout.write(JSON.stringify({ locked: null, state: 'corrupt', lock_path: cur.path, error: cur.error }, null, 2) + '\n');
      process.exit(2);
    }
    const l = cur.lock || {};
    process.stdout.write(JSON.stringify({
      locked: cur.state === 'locked', step: l.step ?? null, files: l.files ?? [], session: l.session ?? null,
      locked_at: l.locked_at ?? null, lock_path: cur.path,
    }, null, 2) + '\n');
    process.exit(0);
  }
  if (cmd === 'unlock') {
    if (cur.state === 'corrupt') fail(2, `unreadable lock ${cur.path} (${cur.error}); inspect it before removing it`);
    removeSessionPointer(cur.lock?.session);
    rmSync(cur.path, { force: true });
    process.exit(0);
  }
  // lock
  if (!args.files) fail(2, 'lock needs --files <a,b>');
  if (args.step === undefined || !/^\d+$/.test(String(args.step))) fail(2, 'lock needs --step <N> (a whole number)');
  const step = Number(args.step);
  if (cur.state === 'corrupt') fail(2, `unreadable lock ${cur.path} (${cur.error})`);
  if (cur.state === 'locked' && cur.lock.step !== step) {
    fail(1, `step ${cur.lock.step} holds the lock; unlock it first`);
  }
  const files = String(args.files).split(',').map((f) => f.trim()).filter(Boolean).map((f) => canonicalPath(resolve(cwd, f)));
  if (files.length === 0) fail(2, 'lock needs at least one file');
  const lock = {
    version: LOCK_VERSION,
    step,
    files: [...new Set(files)],
    session: process.env.CLAUDE_CODE_SESSION_ID || null,
    locked_at: new Date().toISOString(),
  };
  mkdirSync(dirname(cur.path), { recursive: true });
  writeFileSync(cur.path, JSON.stringify(lock, null, 2) + '\n');
  writeSessionPointer(lock.session, cur.path);
  process.exit(0);
 }
 function isMain() {
  try {
    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
  } catch {
    return false;
  }
 }
 if (isMain()) main(process.argv.slice(2));
--- a/lib/verification/repo-tools.mjs
+++ b/lib/verification/repo-tools.mjs
@ -0,0 +1,275 @@
 #!/usr/bin/env node
 // lib/verification/repo-tools.mjs
 // Finds the target repository's OWN formatter, linter and type checker, and
 // runs them. Used by the post-edit guard (P7, hooks/scripts/post-edit-check.mjs,
 // the fast per-file tier) and by the step check (K9, step-check.mjs, the
 // step-end and full tiers).
 //
 // Rules:
 //   - A tool counts only when the repo configures it AND it is installed:
 //     node tools in the repo's node_modules/.bin, the rest on PATH. Nothing is
 //     ever downloaded (no npx), so a check never reaches the network.
 //   - Every run is check-only (prettier --check, ruff format --check, ...): the
 //     guard reports, it never rewrites a file behind Claude's back.
 //   - Each tool's exit code maps to clean / finding / error. An error is a
 //     tool that could not give an answer; it is never read as clean.
 //   - Spawned without a shell; file names are passed as arguments.
 // The exit-code meanings below are the tools' documented conventions as I
 // know them; they were not re-read per tool for this module (ikke verifisert).
 //
 // The tiers (fast per file / step end / full) and "not measured" are from
 // agent-skills' constraint-driven development (MIT, `9d0c60d`); the split
 // between per-file and step-end checks is Kiro's (docs only). Ideas only.
 //
 // CLI: node lib/verification/repo-tools.mjs --repo <dir>
 //   prints the detected tools as JSON. Exit 0 = at least one available tool,
 //   2 = none available (not measured) or not a repository.
 import { existsSync, readFileSync, statSync, realpathSync, accessSync, constants } from 'node:fs';
 import { dirname, join, resolve, isAbsolute, extname, delimiter } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 // ---------------------------------------------------------------------------
 // The repository
 // ---------------------------------------------------------------------------
 // Real path of `p`, or of its nearest existing ancestor joined with the rest:
 // macOS reaches /var through /private/var, and a path that does not exist yet
 // must still compare equal to the same path once it does. The native realpath
 // also returns the on-disk letter case, so `Tests/a.js` and `tests/a.js` on a
 // case-insensitive file system are one path (the JS realpath keeps the case
 // it was given).
 export function canonicalPath(p) {
  let cur = resolve(p);
  const rest = [];
  while (!existsSync(cur)) {
    const up = dirname(cur);
    if (up === cur) break;
    rest.unshift(cur.slice(up.length).replace(/^\/+/, ''));
    cur = up;
  }
  let real = cur;
  try { real = realpathSync.native(cur); } catch { /* keep resolved */ }
  return rest.length ? join(real, ...rest) : real;
 }
 /**
 * The repository a path belongs to: { root, gitDir } (real paths), or null.
 * Reads the filesystem only; follows a worktree's `.git` file to its git dir.
 */
 export function resolveRepo(start) {
  let dir = canonicalPath(start || process.cwd());
  try { if (!statSync(dir).isDirectory()) dir = dirname(dir); } catch { dir = dirname(dir); }
  while (!existsSync(dir)) dir = dirname(dir);
  for (;;) {
    const dotGit = join(dir, '.git');
    if (existsSync(dotGit)) {
      try {
        if (statSync(dotGit).isDirectory()) return { root: dir, gitDir: realpathSync.native(dotGit) };
        const m = readFileSync(dotGit, 'utf8').match(/^gitdir:\s*(.+?)\s*$/m);
        if (!m) return null;
        const gd = isAbsolute(m[1]) ? m[1] : resolve(dir, m[1]);
        return { root: dir, gitDir: realpathSync.native(gd) };
      } catch {
        return null;
      }
    }
    const up = dirname(dir);
    if (up === dir) return null;
    dir = up;
  }
 }
 // ---------------------------------------------------------------------------
 // The tools
 // ---------------------------------------------------------------------------
 const JS_EXT = ['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.mts', '.cts', '.vue'];
 const PRETTIER_EXT = [...JS_EXT, '.json', '.css', '.scss', '.less', '.md', '.yaml', '.yml', '.html'];
 function readText(p) {
  try { return readFileSync(p, 'utf8'); } catch { return null; }
 }
 function anyFile(root, names) {
  return names.some((n) => existsSync(join(root, n)));
 }
 function pkgKey(root, key) {
  const txt = readText(join(root, 'package.json'));
  if (!txt) return false;
  try { return Object.prototype.hasOwnProperty.call(JSON.parse(txt), key); } catch { return false; }
 }
 function tomlHas(root, file, section) {
  const txt = readText(join(root, file));
  return !!txt && txt.split('\n').some((l) => l.trim() === `[${section}]` || l.trim().startsWith(`[${section}.`));
 }
 function isExecutable(p) {
  try { accessSync(p, constants.X_OK); return statSync(p).isFile(); } catch { return false; }
 }
 function localBin(root, name) {
  const p = join(root, 'node_modules', '.bin', name);
  return isExecutable(p) ? p : null;
 }
 function onPath(name, env) {
  for (const dir of String(env.PATH || '').split(delimiter)) {
    if (!dir) continue;
    const p = join(dir, name);
    if (isExecutable(p)) return p;
  }
  return null;
 }
 // Each spec: when the repo configures it, where its binary lives, how to call
 // it for a list of files (file tier) or for the whole repo (repo tier), and
 // which exit codes mean "found problems".
 const SPECS = [
  {
    name: 'prettier', kind: 'format', tier: 'file', ext: PRETTIER_EXT,
    configured: (r) => anyFile(r, ['.prettierrc', '.prettierrc.json', '.prettierrc.yaml', '.prettierrc.yml', '.prettierrc.json5',
      '.prettierrc.js', '.prettierrc.cjs', '.prettierrc.mjs', '.prettierrc.toml', 'prettier.config.js', 'prettier.config.cjs',
      'prettier.config.mjs']) || pkgKey(r, 'prettier'),
    bin: (r) => localBin(r, 'prettier'),
    argv: (files) => ['--check', ...files], findingCodes: [1],
  },
  {
    name: 'biome', kind: 'lint', tier: 'file', ext: [...JS_EXT, '.json', '.jsonc', '.css'],
    configured: (r) => anyFile(r, ['biome.json', 'biome.jsonc']),
    bin: (r) => localBin(r, 'biome'),
    argv: (files) => ['check', ...files], findingCodes: [1],
  },
  {
    name: 'eslint', kind: 'lint', tier: 'file', ext: JS_EXT,
    configured: (r) => anyFile(r, ['eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs', 'eslint.config.ts',
      '.eslintrc', '.eslintrc.js', '.eslintrc.cjs', '.eslintrc.json', '.eslintrc.yml', '.eslintrc.yaml']) || pkgKey(r, 'eslintConfig'),
    bin: (r) => localBin(r, 'eslint'),
    argv: (files) => [...files], findingCodes: [1],
  },
  {
    name: 'tsc', kind: 'typecheck', tier: 'repo',
    configured: (r) => existsSync(join(r, 'tsconfig.json')),
    bin: (r) => localBin(r, 'tsc'),
    argv: () => ['--noEmit', '-p', '.'], findingCodes: [1, 2],
  },
  {
    name: 'ruff-check', kind: 'lint', tier: 'file', ext: ['.py', '.pyi'],
    configured: (r) => anyFile(r, ['ruff.toml', '.ruff.toml']) || tomlHas(r, 'pyproject.toml', 'tool.ruff'),
    bin: (r, env) => (isExecutable(join(r, '.venv', 'bin', 'ruff')) ? join(r, '.venv', 'bin', 'ruff') : onPath('ruff', env)),
    argv: (files) => ['check', ...files], findingCodes: [1],
  },
  {
    name: 'ruff-format', kind: 'format', tier: 'file', ext: ['.py', '.pyi'],
    configured: (r) => anyFile(r, ['ruff.toml', '.ruff.toml']) || tomlHas(r, 'pyproject.toml', 'tool.ruff'),
    bin: (r, env) => (isExecutable(join(r, '.venv', 'bin', 'ruff')) ? join(r, '.venv', 'bin', 'ruff') : onPath('ruff', env)),
    argv: (files) => ['format', '--check', ...files], findingCodes: [1],
  },
  {
    name: 'mypy', kind: 'typecheck', tier: 'repo',
    configured: (r) => anyFile(r, ['mypy.ini', '.mypy.ini']) || tomlHas(r, 'pyproject.toml', 'tool.mypy') || tomlHas(r, 'setup.cfg', 'mypy'),
    bin: (r, env) => (isExecutable(join(r, '.venv', 'bin', 'mypy')) ? join(r, '.venv', 'bin', 'mypy') : onPath('mypy', env)),
    argv: () => ['.'], findingCodes: [1],
  },
  {
    // gofmt -l lists unformatted files and exits 0: a listed file is a finding.
    name: 'gofmt', kind: 'format', tier: 'file', ext: ['.go'],
    configured: (r) => existsSync(join(r, 'go.mod')),
    bin: (_r, env) => onPath('gofmt', env),
    argv: (files) => ['-l', ...files], findingCodes: [], stdoutIsFinding: true,
  },
  {
    name: 'go-vet', kind: 'lint', tier: 'repo',
    configured: (r) => existsSync(join(r, 'go.mod')),
    bin: (_r, env) => onPath('go', env),
    argv: () => ['vet', './...'], findingCodes: [1],
  },
  {
    name: 'rustfmt', kind: 'format', tier: 'file', ext: ['.rs'],
    configured: (r) => existsSync(join(r, 'Cargo.toml')),
    bin: (_r, env) => onPath('rustfmt', env),
    argv: (files) => ['--check', ...files], findingCodes: [1],
  },
  {
    name: 'swiftformat', kind: 'format', tier: 'file', ext: ['.swift'],
    configured: (r) => existsSync(join(r, '.swiftformat')),
    bin: (_r, env) => onPath('swiftformat', env),
    argv: (files) => ['--lint', ...files], findingCodes: [1],
  },
 ];
 /**
 * The tools the repo at `root` configures, each marked available or not.
 * @returns {Array<{name, kind, tier, ext?, available: boolean, bin: string|null, reason: string}>}
 */
 export function detectTools(root, { env = process.env } = {}) {
  const out = [];
  for (const s of SPECS) {
    if (!s.configured(root)) continue;
    const bin = s.bin(root, env);
    out.push({
      name: s.name, kind: s.kind, tier: s.tier, ext: s.ext, bin, available: !!bin,
      reason: bin ? '' : `${s.name} is configured in the repo but not installed`,
      spec: s,
    });
  }
  return out;
 }
 // Available file-tier tools that apply to this file.
 export function toolsForFile(tools, file) {
  const ext = extname(file).toLowerCase();
  return tools.filter((t) => t.available && t.tier === 'file' && t.ext.includes(ext));
 }
 /**
 * Run one tool. `files` is ignored for repo-tier tools.
 * @returns {{ name, kind, status: 'clean'|'finding'|'error', exit: number|null, output: string }}
 */
 export function runTool(tool, files, { cwd, timeout = 120_000, env = process.env } = {}) {
  const s = tool.spec;
  // A file named like `-x.js` or `--config=y` would reach the tool as an
  // option; `./` keeps it a file for every tool, with or without `--` support.
  const safe = files.map((f) => (f.startsWith('-') ? `./${f}` : f));
  const r = spawnSync(tool.bin, s.argv(safe), { cwd, encoding: 'utf8', timeout, env });
  const output = `${r.stdout || ''}${r.stderr || ''}`.trim().slice(0, 4000);
  let status;
  if (r.error || r.status === null) status = 'error';
  else if (s.stdoutIsFinding) status = r.status === 0 ? ((r.stdout || '').trim() ? 'finding' : 'clean') : 'error';
  else if (r.status === 0) status = 'clean';
  else status = s.findingCodes.includes(r.status) ? 'finding' : 'error';
  return { name: tool.name, kind: tool.kind, status, exit: r.status ?? null, output: r.error ? String(r.error.message) : output };
 }
 // ---------------------------------------------------------------------------
 // CLI
 // ---------------------------------------------------------------------------
 function isMain() {
  try {
    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
  } catch {
    return false;
  }
 }
 if (isMain()) {
  const i = process.argv.indexOf('--repo');
  const start = i !== -1 ? process.argv[i + 1] : null;
  if (!start) {
    process.stderr.write('usage: repo-tools.mjs --repo <dir>\n');
    process.exit(2);
  }
  const repo = resolveRepo(start);
  if (!repo) {
    process.stdout.write(JSON.stringify({ status: 'not_measured', reason: 'not a git repository', tools: [] }, null, 2) + '\n');
    process.exit(2);
  }
  const tools = detectTools(repo.root).map(({ spec, ...t }) => t);
  const any = tools.some((t) => t.available);
  process.stdout.write(JSON.stringify({ status: any ? 'tools' : 'not_measured', root: repo.root, tools }, null, 2) + '\n');
  process.exit(any ? 0 : 2);
 }
--- a/lib/verification/step-check.mjs
+++ b/lib/verification/step-check.mjs
@ -0,0 +1,127 @@
 #!/usr/bin/env node
 // lib/verification/step-check.mjs
 // K9 -- the step check. At step end (and on --full) it runs the target repo's
 // own tools and reads the post-edit guard's log (P7):
 //   - file-tier tools (formatters, linters) over the changed files -- the diff
 //     against HEAD plus untracked files -- or, with --full, over every tracked
 //     file;
 //   - repo-tier tools (type checkers, `go vet`) once;
 //   - the post-edit log: a changed file whose latest record is a finding, and
 //     that no tool re-checked now, still counts as a finding;
 //   - optionally the architecture-rule runner (K5, lib/verification/
 //     arch-rules.mjs, wave-1 order 3): missing or exit 2 = listed as not
 //     measured, exit 1 = a finding.
 //
 // Usage: node lib/verification/step-check.mjs --cwd <dir> [--full]
 // Output: JSON on stdout { status, root, files, not_covered, checks: [...] }.
 // Exit: 0 = green (something was measured, every configured tool answered,
 //       nothing found), 1 = findings, 2 = not measured (a configured tool
 //       is missing or crashed, nothing could be checked, not a repository,
 //       bad usage). 2 is never green. Changed files no tool covers are listed
 //       in `not_covered`.
 //
 // Credit: the tiers and "not measured" are agent-skills' constraint-driven
 // development (MIT, `9d0c60d`); the stop at step end is Cherny's and Kiro's.
 import { existsSync, realpathSync } from 'node:fs';
 import { join, extname } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { resolveRepo, detectTools, runTool } from './repo-tools.mjs';
 import { latestPostEditRecords } from '../../hooks/lib/post-edit.mjs';
 import { runContract } from '../../hooks/lib/contract-cli.mjs';
 // NUL-separated and unquoted, so a name with spaces or non-ASCII letters
 // comes back as it is on disk (git quotes such names by default).
 function gitPaths(cwd, args) {
  const r = spawnSync('git', ['-c', 'core.quotePath=false', ...args, '-z'], { cwd, encoding: 'utf8', timeout: 60_000 });
  if (r.status !== 0) return null;
  return r.stdout.split('\0').filter(Boolean);
 }
 function changedFiles(root) {
  const tracked = gitPaths(root, ['diff', '--name-only', 'HEAD']) ?? gitPaths(root, ['diff', '--name-only']) ?? [];
  const untracked = gitPaths(root, ['ls-files', '--others', '--exclude-standard']) ?? [];
  return [...new Set([...tracked, ...untracked])].filter((f) => existsSync(join(root, f)));
 }
 function allFiles(root) {
  return (gitPaths(root, ['ls-files']) ?? []).filter((f) => existsSync(join(root, f)));
 }
 export function stepCheck({ cwd, full = false }) {
  const repo = resolveRepo(cwd);
  if (!repo) return { status: 'not_measured', reason: `not a git repository: ${cwd}`, checks: [] };
  const files = full ? allFiles(repo.root) : changedFiles(repo.root);
  const tools = detectTools(repo.root);
  const checks = [];
  const covered = new Set();
  for (const t of tools) {
    if (!t.available) {
      checks.push({ name: t.name, kind: t.kind, status: 'not_measured', reason: t.reason });
      continue;
    }
    if (t.tier === 'repo') {
      const r = runTool(t, [], { cwd: repo.root, timeout: 300_000 });
      checks.push({ ...r, status: r.status === 'error' ? 'not_measured' : r.status });
      continue;
    }
    const mine = files.filter((f) => t.ext.includes(extname(f).toLowerCase()));
    if (mine.length === 0) continue;
    const r = runTool(t, mine, { cwd: repo.root, timeout: 300_000 });
    checks.push({ ...r, files: mine, status: r.status === 'error' ? 'not_measured' : r.status });
    if (r.status !== 'error') mine.forEach((f) => covered.add(f));
  }
  const log = latestPostEditRecords(repo.gitDir);
  const stale = files.filter((f) => !covered.has(f) && log.get(f)?.status === 'finding');
  if (stale.length) {
    checks.push({ name: 'post-edit-log', kind: 'log', status: 'finding', files: stale,
      output: 'the post-edit guard logged findings for these files and no tool re-checked them now' });
  }
  const arch = runContract('K5', ['--repo', repo.root], { cwd: repo.root, timeout: 300_000 });
  if (!arch.ran) checks.push({ name: 'arch-rules', kind: 'architecture', status: 'not_measured', reason: arch.why });
  else {
    const status = arch.code === 0 ? 'clean' : arch.code === 1 ? 'finding' : 'not_measured';
    checks.push({ name: 'arch-rules', kind: 'architecture', status, exit: arch.code, output: (arch.stdout + arch.stderr).trim().slice(0, 4000) });
  }
  // Changed files no available tool covers: listed, never dropped. They do not
  // turn the step red or grey on their own (a README edit in a JS repo is
  // normal), but the report names them.
  const notCovered = files.filter((f) => !tools.some((t) => t.available && t.tier === 'file' && t.ext.includes(extname(f).toLowerCase())));
  // A tool the repo configures that gave no answer (not installed, crashed)
  // means the step was not fully measured: never green. The arch-rule runner
  // is optional (K5) and is exempt.
  const unanswered = checks.filter((c) => c.status === 'not_measured' && c.name !== 'arch-rules');
  const measured = checks.filter((c) => c.status === 'clean' || c.status === 'finding');
  let status;
  if (checks.some((c) => c.status === 'finding')) status = 'findings';
  else if (unanswered.length || measured.length === 0) status = 'not_measured';
  else status = 'green';
  return { status, root: repo.root, full, files, not_covered: notCovered, checks };
 }
 function isMain() {
  try {
    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
  } catch {
    return false;
  }
 }
 if (isMain()) {
  const argv = process.argv.slice(2);
  const i = argv.indexOf('--cwd');
  const cwd = i !== -1 ? argv[i + 1] : null;
  if (!cwd) {
    process.stdout.write(JSON.stringify({ status: 'not_measured', reason: 'usage: step-check.mjs --cwd <dir> [--full]', checks: [] }) + '\n');
    process.exit(2);
  }
  const report = stepCheck({ cwd, full: argv.includes('--full') });
  process.stdout.write(JSON.stringify(report, null, 2) + '\n');
  process.exit(report.status === 'green' ? 0 : report.status === 'findings' ? 1 : 2);
 }
--- a/tests/hooks/approval-ask.test.mjs
+++ b/tests/hooks/approval-ask.test.mjs
@ -0,0 +1,126 @@
 // tests/hooks/approval-ask.test.mjs
 // P12 — approval as a guard. The Bash guard answers `permissionDecision: "ask"`
 // for merge into main, push, tag/release and destructive git, so a person sees
 // the call before it runs — also in auto mode (code.claude.com/docs/en/hooks
 // § PreToolUse decision control: «A hook's "ask" also forces a permission
 // prompt in auto mode»). Tested both ways per event: every "must ask" has a
 // "must pass" neighbour, so a guard that asks about everything fails here too.
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
 import { join } from 'node:path';
 import { runHook } from '../helpers/hook-helper.mjs';
 import { ROOT, scriptsFor, makeRepo, gitIn, parseJsonOut } from './guard-helpers.mjs';
 const PRE_BASH = join(ROOT, 'hooks', 'scripts', 'pre-bash-executor.mjs');
 const { classifyGitApproval } = await import(join(ROOT, 'hooks', 'lib', 'git-approval.mjs')).catch(() => ({}));
 const MAIN_REPO = makeRepo('main');
 const FEATURE_REPO = makeRepo('main');
 gitIn(FEATURE_REPO, 'checkout', '-q', '-b', 'feat');
 async function decide(command, cwd = FEATURE_REPO) {
  const r = await runHook(PRE_BASH, { hook_event_name: 'PreToolUse', tool_name: 'Bash', cwd, tool_input: { command } });
  let out = null;
  try { out = parseJsonOut(r.stdout); } catch { out = null; }
  return { ...r, out, decision: out?.hookSpecificOutput?.permissionDecision ?? null };
 }
 const MUST_ASK = [
  // [command, cwd, why]
  ['git push origin main', FEATURE_REPO, 'push to main'],
  ['git push', FEATURE_REPO, 'push (any branch)'],
  ['git push origin feat', FEATURE_REPO, 'push of a feature branch'],
  ['git push --force-with-lease origin feat', FEATURE_REPO, 'force push'],
  ['git push --tags', FEATURE_REPO, 'push of tags'],
  ['git -C /tmp/x push origin main', FEATURE_REPO, 'git with -C before the subcommand'],
  ['FOO=1 git push origin main', FEATURE_REPO, 'env-prefixed push'],
  ['npm test && git push origin main', FEATURE_REPO, 'push after a test'],
  ['sh -c "git push origin main"', FEATURE_REPO, 'push inside a shell wrapper'],
  ['git merge --no-ff worktree-x', MAIN_REPO, 'merge while on main'],
  ['git merge --ff-only feat', MAIN_REPO, 'fast-forward merge while on main'],
  ['git checkout main && git merge feat', FEATURE_REPO, 'switch to main, then merge'],
  ['git switch master; git merge feat', FEATURE_REPO, 'switch to master, then merge'],
  ['git tag v1.2.3', FEATURE_REPO, 'create a tag'],
  ['git tag -a v1 -m "release"', FEATURE_REPO, 'annotated tag'],
  ['git tag -d v1', FEATURE_REPO, 'delete a tag'],
  ['npm publish', FEATURE_REPO, 'publish a package'],
  ['git reset --hard HEAD~1', FEATURE_REPO, 'hard reset'],
  ['git clean -fd', FEATURE_REPO, 'clean with force'],
  ['git clean -xdf', FEATURE_REPO, 'clean with combined flags'],
  ['git branch -D feat', FEATURE_REPO, 'force-delete a branch'],
  ['git branch --delete --force feat', FEATURE_REPO, 'force-delete, long flags'],
  ['git stash drop', FEATURE_REPO, 'drop a stash'],
  ['git stash clear', FEATURE_REPO, 'clear all stashes'],
  ['git checkout -- src/a.js', FEATURE_REPO, 'discard changes to a file'],
  ['git checkout .', FEATURE_REPO, 'discard all changes'],
  ['git restore src/a.js', FEATURE_REPO, 'restore the working tree'],
  ['git filter-branch --tree-filter x HEAD', FEATURE_REPO, 'history rewrite'],
 ];
 const MUST_PASS = [
  ['git status', FEATURE_REPO, 'read-only'],
  ['git log --oneline -5', FEATURE_REPO, 'read-only'],
  ['git merge-base --is-ancestor main HEAD', MAIN_REPO, 'merge-base is not a merge'],
  ['git merge feat', FEATURE_REPO, 'merge into a feature branch'],
  ['git merge --abort', MAIN_REPO, 'aborting a merge'],
  ['git tag', FEATURE_REPO, 'list tags'],
  ['git tag -l "v*"', FEATURE_REPO, 'list tags with a pattern'],
  ['git tag --list', FEATURE_REPO, 'list tags, long flag'],
  ['echo "git push origin main"', FEATURE_REPO, 'quoted data, not a command'],
  ['git commit -m "never git push to main"', FEATURE_REPO, 'commit message naming push'],
  ['git restore --staged src/a.js', FEATURE_REPO, 'unstage only'],
  ['git branch -d feat', FEATURE_REPO, 'safe branch delete'],
  ['git stash list', FEATURE_REPO, 'list stashes'],
  ['git checkout -b new-branch', FEATURE_REPO, 'create a branch'],
  ['git checkout main', FEATURE_REPO, 'switch branch'],
  ['git fetch origin', FEATURE_REPO, 'fetch'],
  ['npm test', FEATURE_REPO, 'tests'],
  ['git worktree remove /tmp/wt --force', FEATURE_REPO, 'worktree cleanup (Hard Rule 12)'],
  ['git clean -n', FEATURE_REPO, 'clean dry run'],
 ];
 for (const [cmd, cwd, why] of MUST_ASK) {
  test(`P12 must ask: ${cmd} (${why})`, async () => {
    const r = await decide(cmd, cwd);
    assert.equal(r.code, 0, `ask is a JSON answer on exit 0, not a block; stderr: ${r.stderr}`);
    assert.equal(r.decision, 'ask', `expected permissionDecision "ask" for \`${cmd}\`; stdout: ${r.stdout}`);
    assert.equal(r.out.hookSpecificOutput.hookEventName, 'PreToolUse');
    const reason = r.out.hookSpecificOutput.permissionDecisionReason;
    assert.match(reason, /Voyage/, 'the prompt names Voyage as the asker');
    assert.match(reason, /Way forward:/, 'the prompt explains the way forward');
  });
 }
 for (const [cmd, cwd, why] of MUST_PASS) {
  test(`P12 must pass: ${cmd} (${why})`, async () => {
    const r = await decide(cmd, cwd);
    assert.equal(r.code, 0, `stderr: ${r.stderr}`);
    assert.equal(r.decision, null, `no ask expected for \`${cmd}\`; stdout: ${r.stdout}`);
  });
 }
 test('P12: a BLOCK rule still wins over ask (exit 2, no JSON)', async () => {
  const r = await decide('git push origin main; rm -rf /');
  assert.equal(r.code, 2);
 });
 test('P12: the Bash guard that asks is the one hooks.json runs for Bash', () => {
  const scripts = scriptsFor('PreToolUse', 'Bash');
  assert.ok(scripts.some((s) => s.endsWith('pre-bash-executor.mjs')), JSON.stringify(scripts));
 });
 test('P12: approval kinds follow the operator decision (06.10): merge/push to main = merge, tag/publish = release, the rest unlogged', () => {
  assert.equal(typeof classifyGitApproval, 'function', 'hooks/lib/git-approval.mjs must export classifyGitApproval');
  const kinds = (cmd, branch) => classifyGitApproval(cmd, { branch }).map((m) => m.kind);
  assert.deepEqual(kinds('git merge feat', 'main'), ['merge']);
  assert.deepEqual(kinds('git push origin main', 'feat'), ['merge']);
  assert.deepEqual(kinds('git push origin HEAD:refs/heads/main', 'feat'), ['merge']);
  assert.deepEqual(kinds('git push', 'main'), ['merge'], 'a bare push from main pushes main');
  assert.deepEqual(kinds('git push origin feat', 'feat'), [null]);
  assert.deepEqual(kinds('git tag v1', 'feat'), ['release']);
  assert.deepEqual(kinds('git push --tags', 'feat'), ['release']);
  assert.deepEqual(kinds('npm publish', 'feat'), ['release']);
  assert.deepEqual(kinds('git reset --hard', 'feat'), [null]);
  assert.deepEqual(kinds('git status', 'main'), []);
 });
--- a/tests/hooks/approval-log.test.mjs
+++ b/tests/hooks/approval-log.test.mjs
@ -0,0 +1,135 @@
 // tests/hooks/approval-log.test.mjs
 // P12 + P3 — an approval a person gave through Claude Code's prompt is written
 // to the approval log (contract K2, lib/util/approval-log.mjs, owned by wave-1
 // order 2). The log CLI is a STUB here until order 2 is merged: the stub
 // records its argv. When the CLI is missing, the guard says "not logged" —
 // never green, never silent.
 //
 // Operator decision 06.10: merge/push to main is logged as `merge`, tag and
 // publish as `release`; push of other branches and destructive git are asked
 // about but not logged. P12 approvals carry an expiry (`--expires`).
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 import { runHookWithEnv } from '../helpers/hook-helper.mjs';
 import { scriptsFor, pluginCopy, makeRepo, gitIn, tmp, readStubLog, parseJsonOut } from './guard-helpers.mjs';
 const K2 = 'lib/util/approval-log.mjs';
 const STUBBED = pluginCopy({ [K2]: 'stub' });
 const MISSING = pluginCopy({ [K2]: 'missing' });
 const hookIn = (root) => join(root, 'hooks', 'scripts', 'post-approval-log.mjs');
 const REPO = makeRepo('main');
 gitIn(REPO, 'checkout', '-q', '-b', 'feat');
 const sha = (s) => createHash('sha256').update(s).digest('hex');
 let callNo = 0;
 // A Bash call goes through the same two hooks as in a session: the guard asks
 // (and records what it asked), the call runs, then the approval is logged.
 async function post(root, input, env = {}) {
  const logFile = join(tmp(), 'stub.jsonl');
  const ids = { session_id: 'sess-log', tool_use_id: `toolu_log_${(callNo += 1)}` };
  if (input.tool_name === 'Bash') {
    await runHookWithEnv(join(root, 'hooks', 'scripts', 'pre-bash-executor.mjs'),
      { hook_event_name: 'PreToolUse', cwd: REPO, ...ids, tool_name: 'Bash', tool_input: input.tool_input }, env);
  }
  const r = await runHookWithEnv(hookIn(root), { hook_event_name: 'PostToolUse', cwd: REPO, ...ids, ...input }, { STUB_LOG: logFile, ...env });
  return { ...r, calls: readStubLog(logFile), out: parseJsonOut(r.stdout) };
 }
 const bash = (command) => ({ tool_name: 'Bash', tool_input: { command }, tool_response: { stdout: '', stderr: '' } });
 const VOYAGE_PLAN = '---\nplan_version: 1.7\n---\n\n# Plan\n\n### Step 1: x\n';
 const OTHER_PLAN = '# Refactor auth\n\n1. Extract the helper\n';
 const exitPlan = (plan, filePath = '/tmp/plans/p.md') => ({
  tool_name: 'ExitPlanMode',
  tool_input: { plan, planFilePath: filePath },
  tool_response: { plan, filePath },
 });
 function arg(call, flag) {
  const i = call.argv.indexOf(flag);
  return i === -1 ? undefined : call.argv[i + 1];
 }
 test('K2: push to main is logged as merge, with subject, sha256 and an expiry', async () => {
  const r = await post(STUBBED, bash('git push origin main'));
  assert.equal(r.code, 0, r.stderr);
  assert.equal(r.calls.length, 1, `one append expected; got ${JSON.stringify(r.calls)}`);
  const c = r.calls[0];
  assert.equal(c.argv[0], 'append');
  assert.equal(arg(c, '--kind'), 'merge');
  assert.ok(arg(c, '--subject'), 'subject (a path) is given');
  assert.match(arg(c, '--sha256'), /^[0-9a-f]{64}$/);
  const exp = Date.parse(arg(c, '--expires'));
  assert.ok(Number.isFinite(exp) && exp > Date.now(), 'expires is a future ISO time');
  assert.match(r.out.hookSpecificOutput.additionalContext, /approval logged/i);
 });
 test('K2: a tag is logged as release', async () => {
  const r = await post(STUBBED, bash('git tag v9.9.9'));
  assert.equal(r.calls.length, 1);
  assert.equal(arg(r.calls[0], '--kind'), 'release');
 });
 test('K2: push of a feature branch is asked about but NOT logged', async () => {
  const r = await post(STUBBED, bash('git push origin feat'));
  assert.equal(r.code, 0);
  assert.equal(r.calls.length, 0);
 });
 test('K2: destructive git is asked about but NOT logged', async () => {
  const r = await post(STUBBED, bash('git reset --hard HEAD~1'));
  assert.equal(r.code, 0, r.stderr);
  assert.equal(r.calls.length, 0);
 });
 test('K2: an ordinary command logs nothing and says nothing', async () => {
  const r = await post(STUBBED, bash('npm test'));
  assert.equal(r.code, 0, r.stderr);
  assert.equal(r.calls.length, 0);
  assert.equal(r.out, null);
 });
 test('K2 missing: the approval is reported "not logged", never green', async () => {
  const r = await post(MISSING, bash('git push origin main'));
  assert.equal(r.code, 0);
  assert.match(r.out.hookSpecificOutput.additionalContext, /not logged/i);
 });
 test('K2 refuses (exit 1): reported "not logged"', async () => {
  const r = await post(STUBBED, bash('git push origin main'), { STUB_EXIT: '1' });
  assert.match(r.out.hookSpecificOutput.additionalContext, /not logged/i);
 });
 test('K2 could not run (exit 2): reported "not logged"', async () => {
  const r = await post(STUBBED, bash('git push origin main'), { STUB_EXIT: '2' });
  assert.match(r.out.hookSpecificOutput.additionalContext, /not logged/i);
 });
 test('P3: an approved Voyage plan is logged as plan, bound to the sha256 of the approved text', async () => {
  const r = await post(STUBBED, exitPlan(VOYAGE_PLAN, '/tmp/plans/voyage-plan.md'));
  assert.equal(r.calls.length, 1, JSON.stringify(r.calls));
  const c = r.calls[0];
  assert.equal(arg(c, '--kind'), 'plan');
  assert.equal(arg(c, '--subject'), '/tmp/plans/voyage-plan.md');
  assert.equal(arg(c, '--sha256'), sha(VOYAGE_PLAN));
 });
 test('P3: an approved plan without plan_version is not Voyage\'s and is not logged', async () => {
  const r = await post(STUBBED, exitPlan(OTHER_PLAN));
  assert.equal(r.code, 0, r.stderr);
  assert.equal(r.calls.length, 0);
  assert.equal(r.out, null);
 });
 test('wiring: hooks.json runs post-approval-log on PostToolUse for Bash and ExitPlanMode', () => {
  for (const tool of ['Bash', 'ExitPlanMode']) {
    const s = scriptsFor('PostToolUse', tool);
    assert.ok(s.some((p) => p.endsWith('post-approval-log.mjs')), `${tool}: ${JSON.stringify(s)}`);
  }
 });
--- a/tests/hooks/guard-helpers.mjs
+++ b/tests/hooks/guard-helpers.mjs
@ -0,0 +1,143 @@
 // tests/hooks/guard-helpers.mjs
 // Shared helpers for the wave-1 guard tests (P3, P7, P9 lock, P12). Not a test
 // file itself (no `.test.mjs`), so `npm test` does not run it.
 //
 // - Resolves hooks.json the way Claude Code does (matcher semantics:
 //   code.claude.com/docs/en/hooks § Matcher patterns), so a wiring gap fails
 //   even when a script is correct. Same rules as write-guard-coverage.test.mjs.
 // - Builds throwaway git repos and a throwaway copy of the plugin in which the
 //   contract CLIs another wave-1 order owns (K2 approval log, K3 plan gate, K5
 //   arch rules) are stubs that record their argv and exit with a chosen code.
 import { readFileSync, mkdtempSync, mkdirSync, writeFileSync, copyFileSync, readdirSync, chmodSync, existsSync, rmSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 const HERE = dirname(fileURLToPath(import.meta.url));
 export const ROOT = join(HERE, '..', '..');
 export const HOOKS_JSON = join(ROOT, 'hooks', 'hooks.json');
 // "*", "" or omitted match all; a value of only letters, digits, _, -, spaces,
 // `,` and `|` is a list of exact names; anything else is an unanchored regex.
 export function matcherFires(matcher, name) {
  if (matcher === undefined || matcher === '' || matcher === '*') return true;
  if (/^[A-Za-z0-9_\- ,|]+$/.test(matcher)) {
    return matcher.split(/[|,]/).map((s) => s.trim()).includes(name);
  }
  return new RegExp(matcher).test(name);
 }
 // Every script hooks.json would run for this event (and tool, when the event
 // has a matcher), with ${CLAUDE_PLUGIN_ROOT} resolved to `root`.
 export function scriptsFor(event, name, root = ROOT) {
  const cfg = JSON.parse(readFileSync(join(root, 'hooks', 'hooks.json'), 'utf8'));
  const out = [];
  for (const entry of cfg.hooks[event] || []) {
    if (name !== undefined && !matcherFires(entry.matcher, name)) continue;
    for (const h of entry.hooks || []) {
      const arg = (h.args || []).find((a) => a.endsWith('.mjs'));
      if (arg) out.push(arg.replace('${CLAUDE_PLUGIN_ROOT}', root));
    }
  }
  return out;
 }
 export function tmp(prefix = 'voyage-guard-') {
  return mkdtempSync(join(tmpdir(), prefix));
 }
 function git(cwd, ...args) {
  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
 }
 // A git repo with one commit on `branch`.
 export function makeRepo(branch = 'main') {
  const dir = tmp('voyage-repo-');
  git(dir, 'init', '-q', '-b', branch);
  git(dir, 'config', 'user.email', 't@example.invalid');
  git(dir, 'config', 'user.name', 'T');
  git(dir, 'config', 'commit.gpgsign', 'false');
  git(dir, 'config', 'tag.gpgsign', 'false');
  writeFileSync(join(dir, 'README.md'), '# t\n');
  git(dir, 'add', 'README.md');
  git(dir, 'commit', '-q', '-m', 'init');
  return dir;
 }
 export function gitIn(cwd, ...args) {
  return git(cwd, ...args);
 }
 // A stub CLI: records its argv and cwd as one JSON line in $STUB_LOG, prints
 // $STUB_STDOUT, exits with $STUB_EXIT (default 0).
 const STUB = `#!/usr/bin/env node
 import { appendFileSync } from 'node:fs';
 const log = process.env.STUB_LOG;
 if (log) appendFileSync(log, JSON.stringify({ argv: process.argv.slice(2), cwd: process.cwd() }) + '\\n');
 if (process.env.STUB_STDOUT) process.stdout.write(process.env.STUB_STDOUT);
 process.exit(Number(process.env.STUB_EXIT || 0));
 `;
 function copyTree(src, dst) {
  mkdirSync(dst, { recursive: true });
  for (const e of readdirSync(src, { withFileTypes: true })) {
    const s = join(src, e.name);
    const d = join(dst, e.name);
    if (e.isDirectory()) copyTree(s, d);
    else copyFileSync(s, d);
  }
 }
 // A copy of the plugin's hooks/ and the lib modules the guards import, with
 // the named contract CLIs replaced by the stub (or left out when `missing`).
 // stubs: { 'lib/util/approval-log.mjs': 'stub' | 'missing', ... }
 export function pluginCopy(stubs = {}) {
  const root = tmp('voyage-plugin-');
  copyTree(join(ROOT, 'hooks'), join(root, 'hooks'));
  copyTree(join(ROOT, 'lib'), join(root, 'lib'));
  for (const [rel, mode] of Object.entries(stubs)) {
    const p = join(root, rel);
    if (mode === 'missing') {
      rmSync(p, { force: true });
      continue;
    }
    mkdirSync(dirname(p), { recursive: true });
    writeFileSync(p, STUB);
  }
  return root;
 }
 export function readStubLog(path) {
  if (!existsSync(path)) return [];
  return readFileSync(path, 'utf8').trim().split('\n').filter(Boolean).map((l) => JSON.parse(l));
 }
 // An executable shell stub at <dir>/<name>: exits 1 and prints a line when any
 // file argument contains the text BAD, else exits 0. Used as a fake formatter
 // or linter so the post-edit check can be shown to stop AND to pass.
 export function fakeTool(dir, name, { findingExit = 1 } = {}) {
  mkdirSync(dir, { recursive: true });
  const p = join(dir, name);
  writeFileSync(
    p,
    `#!/bin/sh
 found=0
 for a in "$@"; do
  case "$a" in -*) continue ;; esac
  if [ -f "$a" ] && grep -q BAD "$a"; then echo "${name}: problem in $a"; found=1; fi
 done
 if [ "$found" = 1 ]; then exit ${findingExit}; fi
 exit 0
 `,
  );
  chmodSync(p, 0o755);
  return p;
 }
 export function parseJsonOut(stdout) {
  const s = String(stdout || '').trim();
  if (!s) return null;
  return JSON.parse(s);
 }
--- a/tests/hooks/guards-review-regressions.test.mjs
+++ b/tests/hooks/guards-review-regressions.test.mjs
@ -0,0 +1,301 @@
 // tests/hooks/guards-review-regressions.test.mjs
 // Regressions from the independent review of the wave-1 guards (06.10). Each
 // test reproduces one finding the first test set did not cover; all failed
 // before the fix.
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
 import { spawnSync } from 'node:child_process';
 import { writeFileSync, mkdirSync, realpathSync } from 'node:fs';
 import { join } from 'node:path';
 import { runHook, runHookWithEnv } from '../helpers/hook-helper.mjs';
 import { ROOT, makeRepo, gitIn, fakeTool, tmp, pluginCopy, readStubLog, parseJsonOut } from './guard-helpers.mjs';
 const PRE_BASH = join(ROOT, 'hooks', 'scripts', 'pre-bash-executor.mjs');
 const PRE_WRITE = join(ROOT, 'hooks', 'scripts', 'pre-write-executor.mjs');
 const STOP = join(ROOT, 'hooks', 'scripts', 'stop-test-lock.mjs');
 const LOCK = join(ROOT, 'lib', 'util', 'test-lock.mjs');
 const STEP = join(ROOT, 'lib', 'verification', 'step-check.mjs');
 const { classifyGitApproval } = await import(join(ROOT, 'hooks', 'lib', 'git-approval.mjs'));
 const FEAT = makeRepo('main');
 gitIn(FEAT, 'checkout', '-q', '-b', 'feat');
 const MAIN = makeRepo('main');
 async function decision(command, cwd = FEAT) {
  const r = await runHook(PRE_BASH, { hook_event_name: 'PreToolUse', tool_name: 'Bash', cwd, tool_input: { command } });
  let out = null;
  try { out = parseJsonOut(r.stdout); } catch { out = null; }
  return out?.hookSpecificOutput?.permissionDecision ?? (r.code === 2 ? 'block' : null);
 }
 // 1. Quotes that are not quotes
 for (const cmd of [
  "# push it, it's ready\ngit push origin main",
  "echo don\\'t; git push origin main",
  "echo 'unterminated; git push origin main",
 ]) {
  test(`review 1: an apostrophe that is not a closed quote does not hide a push: ${JSON.stringify(cmd)}`, async () => {
    assert.equal(await decision(cmd), 'ask');
  });
 }
 // 2. Quoted program, subcommand or ref
 for (const cmd of ['git "push" origin feat', '"git" push', "'git' push", "git 'push' origin feat"]) {
  test(`review 2: a quoted word is still the word: ${cmd}`, async () => {
    assert.equal(await decision(cmd), 'ask');
  });
 }
 test('review 2: a quoted ref keeps its kind (push to "main" is a merge approval)', () => {
  assert.deepEqual(classifyGitApproval('git push origin "main"', { branch: 'feat' }).map((m) => m.kind), ['merge']);
 });
 test('review 2: quoted data with spaces stays data', async () => {
  assert.equal(await decision('echo "git push origin main"'), null);
  assert.equal(await decision('git commit -m "wip"'), null);
 });
 // 3. Wrappers
 for (const cmd of ['timeout 60 git push', 'nice git push', 'nice -n 5 git push', 'env -i git push', 'env -u HOME git push',
  'sudo -u bob git push', 'command -p git push', 'time -p git push', 'eval git push', 'xargs -n 1 git push']) {
  test(`review 3: wrapper seen through: ${cmd}`, async () => {
    assert.equal(await decision(cmd), 'ask');
  });
 }
 // 8. One branch model for the whole command
 test('review 8: switching to main then pushing is a push to main', () => {
  assert.deepEqual(classifyGitApproval('git checkout main && git push', { branch: 'feat' }).map((m) => m.kind), ['merge']);
 });
 test('review 8: switching away from main then merging is not a merge into main', () => {
  assert.deepEqual(classifyGitApproval('git checkout feat && git merge x', { branch: 'main' }), []);
 });
 test('review 8: git -C <dir> reads that repo\'s branch', () => {
  assert.deepEqual(classifyGitApproval(`git -C ${MAIN} merge x`, { cwd: FEAT }).map((m) => m.kind), ['merge']);
 });
 test('review 8: cd <dir> && ... reads that repo\'s branch', () => {
  assert.deepEqual(classifyGitApproval(`cd ${MAIN} && git merge x`, { cwd: FEAT }).map((m) => m.kind), ['merge']);
 });
 test('review 8: the log records what the person was asked, not a re-reading after the command', async () => {
  const plugin = pluginCopy({ 'lib/util/approval-log.mjs': 'stub' });
  const repo = makeRepo('main');
  gitIn(repo, 'checkout', '-q', '-b', 'feat');
  const cmd = 'git checkout main && git merge feat';
  const base = { session_id: 's-8', tool_use_id: 'toolu_8', cwd: repo, tool_name: 'Bash', tool_input: { command: cmd } };
  const pre = await runHook(join(plugin, 'hooks', 'scripts', 'pre-bash-executor.mjs'), { ...base, hook_event_name: 'PreToolUse' });
  assert.match(pre.stdout, /merge into main/);
  gitIn(repo, 'checkout', '-q', 'main'); // the command ran
  const log = join(tmp(), 'stub.jsonl');
  await runHookWithEnv(join(plugin, 'hooks', 'scripts', 'post-approval-log.mjs'), { ...base, hook_event_name: 'PostToolUse' }, { STUB_LOG: log });
  const calls = readStubLog(log);
  assert.equal(calls.length, 1);
  assert.equal(calls[0].argv[calls[0].argv.indexOf('--kind') + 1], 'merge');
 });
 test('review 8: a command nobody was asked about is not logged, even if it reads like one afterwards', async () => {
  const plugin = pluginCopy({ 'lib/util/approval-log.mjs': 'stub' });
  const repo = makeRepo('main');
  const log = join(tmp(), 'stub.jsonl');
  await runHookWithEnv(join(plugin, 'hooks', 'scripts', 'post-approval-log.mjs'), {
    hook_event_name: 'PostToolUse', session_id: 's-9', tool_use_id: 'toolu_never_asked', cwd: repo,
    tool_name: 'Bash', tool_input: { command: 'git push origin main' },
  }, { STUB_LOG: log });
  assert.equal(readStubLog(log).length, 0);
 });
 test('uncertain (bypass mode): an approval that no person gave is not logged', async () => {
  const plugin = pluginCopy({ 'lib/util/approval-log.mjs': 'stub' });
  const repo = makeRepo('main');
  const base = { session_id: 's-b', tool_use_id: 'toolu_b', cwd: repo, tool_name: 'Bash', tool_input: { command: 'git push origin main' }, permission_mode: 'bypassPermissions' };
  await runHook(join(plugin, 'hooks', 'scripts', 'pre-bash-executor.mjs'), { ...base, hook_event_name: 'PreToolUse' });
  const log = join(tmp(), 'stub.jsonl');
  const r = await runHookWithEnv(join(plugin, 'hooks', 'scripts', 'post-approval-log.mjs'), { ...base, hook_event_name: 'PostToolUse' }, { STUB_LOG: log });
  assert.equal(readStubLog(log).length, 0);
  assert.match(parseJsonOut(r.stdout).hookSpecificOutput.additionalContext, /not logged/i);
 });
 // 9. Classification
 const kinds = (cmd, branch = 'feat', cwd) => classifyGitApproval(cmd, { branch, cwd }).map((m) => m.kind);
 for (const cmd of ['git tag -v v1', 'git tag --verify v1', 'git push -n', 'git push --dry-run origin main']) {
  test(`review 9: not asked: ${cmd}`, () => assert.deepEqual(kinds(cmd), []));
 }
 for (const cmd of ['npm --tag beta publish', 'pnpm -r publish', 'yarn npm publish', 'npx npm publish', 'gh release create v1']) {
  test(`review 9: release: ${cmd}`, () => assert.deepEqual(kinds(cmd), ['release']));
 }
 test('review 9: pushing an existing tag by name is a release', () => {
  const repo = makeRepo('main');
  gitIn(repo, 'tag', 'v1.0');
  assert.deepEqual(kinds('git push origin v1.0', 'main', repo), ['release']);
 });
 for (const cmd of ['git checkout HEAD file.txt', 'git switch -f main', 'git switch --discard-changes main', 'git branch -M main']) {
  test(`review 9: destructive: ${cmd}`, () => assert.deepEqual(kinds(cmd, 'feat'), [null]));
 }
 test('review 9: deleting main on the remote is destructive, not a merge approval', () => {
  assert.deepEqual(kinds('git push origin :main'), [null]);
  assert.deepEqual(kinds('git push origin --delete main'), [null]);
 });
 // 5 + 6 + 7. The write guard
 test('review 5: a lock module that cannot load blocks the write (fail closed), the path rules still run', async () => {
  const plugin = pluginCopy({ 'lib/util/test-lock.mjs': 'missing' });
  const hook = join(plugin, 'hooks', 'scripts', 'pre-write-executor.mjs');
  const r = await runHook(hook, { tool_name: 'Edit', tool_input: { file_path: join(makeRepo('main'), 'a.js') } });
  assert.equal(r.code, 2);
  assert.match(r.stderr, /could not load/i);
 });
 test('review 5: a guard module that cannot load makes the Bash guard ask, never pass silently', async () => {
  const plugin = pluginCopy({ 'hooks/lib/git-approval.mjs': 'missing' });
  const r = await runHook(join(plugin, 'hooks', 'scripts', 'pre-bash-executor.mjs'), { tool_name: 'Bash', tool_input: { command: 'ls' } });
  assert.equal(parseJsonOut(r.stdout)?.hookSpecificOutput?.permissionDecision, 'ask');
 });
 function lockIn(repo, rel, env = {}) {
  const r = spawnSync(process.execPath, [LOCK, 'lock', '--files', rel, '--step', '1'], { cwd: repo, encoding: 'utf8', env: { ...process.env, ...env } });
  assert.equal(r.status, 0, r.stderr);
 }
 test('review 6: another letter case does not get past the lock (case-insensitive file systems)', async () => {
  const repo = makeRepo('main');
  mkdirSync(join(repo, 'tests'));
  writeFileSync(join(repo, 'tests', 'a.test.mjs'), 'x');
  lockIn(repo, 'tests/a.test.mjs');
  const upper = join(repo, 'Tests', 'a.test.mjs');
  let caseInsensitive = false;
  try { realpathSync(upper); caseInsensitive = true; } catch { caseInsensitive = false; }
  const r = await runHook(PRE_WRITE, { tool_name: 'Edit', tool_input: { file_path: upper } });
  if (caseInsensitive) assert.equal(r.code, 2, 'same file, other case');
  else assert.equal(r.code, 0, 'a different file on a case-sensitive file system');
 });
 test('review 7: the lock file itself cannot be written with the file tools (repo and worktree git dirs)', async () => {
  for (const p of ['/r/.git/voyage/test-lock.json', '/r/.git/worktrees/wt/voyage/test-lock.json', '/r/.git/voyage/post-edit.jsonl']) {
    const r = await runHook(PRE_WRITE, { tool_name: 'Write', tool_input: { file_path: p, content: '{}' } });
    assert.equal(r.code, 2, p);
  }
 });
 // 10. The stop guard finds the session's lock wherever the session now stands
 const SESS_MOVED = `sess-moved-${process.pid}-${Date.now()}`;
 test('review 10: the stop guard finds the lock taken by this session from another directory', async () => {
  const repo = makeRepo('main');
  writeFileSync(join(repo, 'a.test.js'), 'x');
  lockIn(repo, 'a.test.js', { CLAUDE_CODE_SESSION_ID: SESS_MOVED });
  const r = await runHook(STOP, { hook_event_name: 'Stop', session_id: SESS_MOVED, cwd: tmp(), stop_hook_active: false });
  assert.equal(parseJsonOut(r.stdout)?.decision, 'block');
  spawnSync(process.execPath, [LOCK, 'unlock'], { cwd: repo });
  const after = await runHook(STOP, { hook_event_name: 'Stop', session_id: SESS_MOVED, cwd: tmp(), stop_hook_active: false });
  assert.equal(parseJsonOut(after.stdout), null, 'unlock clears it');
 });
 // 4, 11, 12. The step check
 function runStep(repo) {
  const r = spawnSync(process.execPath, [STEP, '--cwd', repo], { encoding: 'utf8', env: { ...process.env, PATH: '/usr/bin:/bin' } });
  return { code: r.status, json: JSON.parse(r.stdout) };
 }
 function jsRepo() {
  const repo = makeRepo('main');
  writeFileSync(join(repo, '.prettierrc'), '{}');
  writeFileSync(join(repo, '.gitignore'), 'node_modules/\n');
  gitIn(repo, 'add', '.prettierrc', '.gitignore');
  gitIn(repo, 'commit', '-q', '-m', 'tools');
  fakeTool(join(repo, 'node_modules', '.bin'), 'prettier');
  return repo;
 }
 test('review 4: a configured tool that crashed is not green', () => {
  const repo = jsRepo();
  writeFileSync(join(repo, 'eslint.config.js'), 'export default []');
  // eslint is configured and installed, but crashes (exit 2 = config error) on every call
  writeFileSync(join(repo, 'node_modules', '.bin', 'eslint'), '#!/bin/sh\nexit 2\n', { mode: 0o755 });
  writeFileSync(join(repo, 'a.js'), 'ok'); // prettier: clean
  const r = runStep(repo);
  assert.equal(r.code, 2, JSON.stringify(r.json));
  assert.equal(r.json.status, 'not_measured');
 });
 test('review 4: changed files no tool covers are listed, never silently dropped', () => {
  const repo = jsRepo();
  writeFileSync(join(repo, 'a.js'), 'ok');
  writeFileSync(join(repo, 'b.py'), 'x = 1');
  const r = runStep(repo);
  assert.deepEqual(r.json.not_covered, ['b.py']);
 });
 test('review 11: a changed file whose name starts with "-" reaches the tool as a file, not a flag', () => {
  const repo = jsRepo();
  writeFileSync(join(repo, '-x.js'), 'BAD');
  const r = runStep(repo);
  assert.equal(r.code, 1, JSON.stringify(r.json));
 });
 test('review 12: a changed file with a non-ASCII name is checked', () => {
  const repo = jsRepo();
  writeFileSync(join(repo, 'blåbær.js'), 'BAD');
  const r = runStep(repo);
  assert.equal(r.code, 1, JSON.stringify(r.json));
 });
 test('uncertain (relative plan path): the plan gate resolves planFilePath against the session cwd', async () => {
  const plugin = pluginCopy({ 'lib/validators/plan-gate.mjs': 'stub' });
  const dir = tmp();
  writeFileSync(join(dir, 'plan.md'), '---\nplan_version: 1.7\n---\n');
  const log = join(tmp(), 'stub.jsonl');
  const r = await runHookWithEnv(join(plugin, 'hooks', 'scripts', 'pre-plan-gate.mjs'), {
    hook_event_name: 'PreToolUse', tool_name: 'ExitPlanMode', cwd: dir,
    tool_input: { plan: '---\nplan_version: 1.7\n---\n', planFilePath: 'plan.md' },
  }, { STUB_LOG: log, STUB_EXIT: '1' });
  assert.equal(r.code, 2, r.stdout);
  assert.equal(readStubLog(log)[0].argv[0], join(dir, 'plan.md'));
 });
 // ---------------------------------------------------------------------------
 // Second review round (06.10): what the first fixes left open or introduced.
 // ---------------------------------------------------------------------------
 for (const cmd of [
  'git commit -m "fix \\"x\\" bug" && git push origin main && echo "ok"',
  'echo "a\\"b" ; git push origin main ; echo "c"',
  'if git push origin main; then echo ok; fi',
  'while git push origin main; do sleep 1; done',
  "eval 'git push origin main'",
  'echo a\\ #b; git push origin main',
 ]) {
  test(`review 2nd round: still asks: ${JSON.stringify(cmd)}`, async () => {
    assert.equal(await decision(cmd), 'ask');
  });
 }
 test('review 2nd round (7): the .git/voyage block ignores letter case', async () => {
  for (const p of ['/r/.GIT/voyage/test-lock.json', '/r/.git/VOYAGE/test-lock.json', '/r/.Git/hooks/pre-commit']) {
    const r = await runHook(PRE_WRITE, { tool_name: 'Write', tool_input: { file_path: p, content: '{}' } });
    assert.equal(r.code, 2, p);
  }
 });
 test('review 2nd round (N1): redirections are not file arguments', () => {
  assert.deepEqual(kinds('git checkout main 2>/dev/null && git merge x', 'feat'), ['merge']);
  assert.deepEqual(kinds('git checkout feat2 2>&1', 'feat'), []);
  assert.deepEqual(kinds('git push origin 2>&1', 'main'), ['merge']);
  assert.deepEqual(kinds('git checkout main > /dev/null && git merge x', 'feat'), ['merge']);
 });
 for (const cmd of ['npm publish --dry-run', 'cargo publish --dry-run', 'npm view x publish', 'yarn info publish']) {
  test(`review 2nd round (N2): not a release: ${cmd}`, () => assert.deepEqual(kinds(cmd), []));
 }
 test('review 2nd round (N5): a detached switch leaves no branch to merge into', () => {
  assert.deepEqual(kinds('git switch --detach main && git merge x', 'feat'), []);
  assert.deepEqual(kinds('git checkout --detach main && git merge x', 'feat'), []);
 });
 test('review 2nd round: a push option value is not the remote', () => {
  assert.deepEqual(kinds('git push -o ci.skip origin main', 'feat'), ['merge']);
 });
 test('review 2nd round (N4): when the record cannot be written, the prompt says the approval will not be logged', async () => {
  const plugin = pluginCopy({});
  // TMPDIR points at a file, so the record directory cannot be created.
  const fileAsDir = join(tmp(), 'not-a-dir');
  writeFileSync(fileAsDir, 'x');
  const r = await runHookWithEnv(join(plugin, 'hooks', 'scripts', 'pre-bash-executor.mjs'), {
    hook_event_name: 'PreToolUse', session_id: 's-n4', tool_use_id: 'toolu_n4', cwd: makeRepo('main'),
    tool_name: 'Bash', tool_input: { command: 'git push origin main' },
  }, { TMPDIR: fileAsDir });
  const reason = parseJsonOut(r.stdout).hookSpecificOutput.permissionDecisionReason;
  assert.match(reason, /will not be logged/i);
 });
--- a/tests/hooks/plan-gate-hook.test.mjs
+++ b/tests/hooks/plan-gate-hook.test.mjs
@ -0,0 +1,95 @@
 // tests/hooks/plan-gate-hook.test.mjs
 // P3 — Claude Code's plan approval, wrapped. A PreToolUse hook on ExitPlanMode
 // receives the plan text and the plan file path (code.claude.com/docs/en/hooks
 // § ExitPlanMode: «Claude Code injects the plan content and file path before
 // passing the input to hooks»), runs Voyage's plan gate (contract K3,
 // lib/validators/plan-gate.mjs, owned by wave-1 order 3; a STUB here until it
 // is merged) and sends an invalid Voyage plan back. Only Voyage plans (they
 // carry `plan_version`) are gated: the hook runs in every session, so every
 // other plan passes untouched.
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
 import { writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { runHookWithEnv } from '../helpers/hook-helper.mjs';
 import { scriptsFor, pluginCopy, tmp, readStubLog, parseJsonOut } from './guard-helpers.mjs';
 const K3 = 'lib/validators/plan-gate.mjs';
 const STUBBED = pluginCopy({ [K3]: 'stub' });
 const MISSING = pluginCopy({ [K3]: 'missing' });
 const hookIn = (root) => join(root, 'hooks', 'scripts', 'pre-plan-gate.mjs');
 const VOYAGE_PLAN = '---\nplan_version: 1.7\n---\n\n# Plan\n\n### Step 1: x\n';
 const OTHER_PLAN = '# Refactor auth\n\n1. Extract the helper\n';
 function planFile(text) {
  const dir = join(tmp(), 'plans');
  mkdirSync(dir, { recursive: true });
  const p = join(dir, 'plan.md');
  writeFileSync(p, text);
  return p;
 }
 async function exitPlanMode(root, plan, env = {}, { withPath = true } = {}) {
  const logFile = join(tmp(), 'stub.jsonl');
  const input = { plan };
  if (withPath) input.planFilePath = planFile(plan);
  const r = await runHookWithEnv(
    hookIn(root),
    { hook_event_name: 'PreToolUse', tool_name: 'ExitPlanMode', cwd: tmp(), tool_input: input },
    { STUB_LOG: logFile, ...env },
  );
  let out = null;
  try { out = parseJsonOut(r.stdout); } catch { out = null; }
  return { ...r, out, calls: readStubLog(logFile), path: input.planFilePath };
 }
 test('P3 must stop: a Voyage plan the gate refuses (K3 exit 1, open BLOCKER) is sent back', async () => {
  const r = await exitPlanMode(STUBBED, VOYAGE_PLAN, { STUB_EXIT: '1', STUB_STDOUT: 'BLOCKER open: step 2 has no Verify' });
  assert.equal(r.code, 2, `deny = exit 2; stdout ${r.stdout}`);
  assert.match(r.stderr, /Voyage/);
  assert.match(r.stderr, /BLOCKER open/, 'the gate\'s own words reach Claude');
  assert.equal(r.calls.length, 1);
  assert.equal(r.calls[0].argv[0], r.path, 'the gate runs on the plan file Claude Code attached');
 });
 test('P3 must pass: a Voyage plan the gate accepts (K3 exit 0) goes on', async () => {
  const r = await exitPlanMode(STUBBED, VOYAGE_PLAN, { STUB_EXIT: '0' });
  assert.equal(r.code, 0, r.stderr);
  assert.equal(r.out, null, 'no decision: Claude Code\'s own approval prompt follows');
  assert.equal(r.calls.length, 1);
 });
 test('P3 must pass: a plan without plan_version is not Voyage\'s; the gate is not even run', async () => {
  const r = await exitPlanMode(STUBBED, OTHER_PLAN, { STUB_EXIT: '1' });
  assert.equal(r.code, 0);
  assert.equal(r.out, null);
  assert.equal(r.calls.length, 0);
 });
 test('P3 not measured: K3 could not run (exit 2) -> ask, never a silent pass', async () => {
  const r = await exitPlanMode(STUBBED, VOYAGE_PLAN, { STUB_EXIT: '2' });
  assert.equal(r.code, 0);
  assert.equal(r.out?.hookSpecificOutput?.permissionDecision, 'ask');
  assert.match(r.out.hookSpecificOutput.permissionDecisionReason, /not measured/i);
 });
 test('P3 not measured: K3 missing (order 3 not merged) -> ask "not measured"', async () => {
  const r = await exitPlanMode(MISSING, VOYAGE_PLAN);
  assert.equal(r.out?.hookSpecificOutput?.permissionDecision, 'ask');
  assert.match(r.out.hookSpecificOutput.permissionDecisionReason, /not measured/i);
 });
 test('P3 not measured: a Voyage plan with no plan file path -> ask "not measured"', async () => {
  const r = await exitPlanMode(STUBBED, VOYAGE_PLAN, {}, { withPath: false });
  assert.equal(r.out?.hookSpecificOutput?.permissionDecision, 'ask');
  assert.equal(r.calls.length, 0);
 });
 test('wiring: hooks.json runs pre-plan-gate on PreToolUse for ExitPlanMode only', () => {
  assert.ok(scriptsFor('PreToolUse', 'ExitPlanMode').some((p) => p.endsWith('pre-plan-gate.mjs')));
  for (const tool of ['Bash', 'Write', 'Edit', 'Agent', 'EnterPlanMode']) {
    assert.ok(!scriptsFor('PreToolUse', tool).some((p) => p.endsWith('pre-plan-gate.mjs')), tool);
  }
 });
--- a/tests/hooks/post-edit-check.test.mjs
+++ b/tests/hooks/post-edit-check.test.mjs
@ -0,0 +1,126 @@
 // tests/hooks/post-edit-check.test.mjs
 // P7 — the guard after edits (PostToolUse Edit|Write). It runs the target
 // repo's OWN formatter and linter on the edited file (the fast tier), logs the
 // result for the step check (K9), and says "not measured" when the repo has no
 // tool for that file — never green.
 //
 // Operator decision 06.10: it is on only while Voyage executes a plan in that
 // repo, or when the repo has switched it on (.claude/voyage-guards.json with
 // "post_edit_check": true). Every other session sees nothing.
 //
 // Tested both ways: a file the fake formatter rejects must be reported (the
 // "must stop" side — PostToolUse cannot undo the edit, so the stop happens at
 // step end, via K9), and a clean file must pass.
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
 import { writeFileSync, mkdirSync, existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { runHook } from '../helpers/hook-helper.mjs';
 import { ROOT, scriptsFor, makeRepo, fakeTool, parseJsonOut } from './guard-helpers.mjs';
 const HOOK = join(ROOT, 'hooks', 'scripts', 'post-edit-check.mjs');
 function optIn(repo) {
  mkdirSync(join(repo, '.claude'), { recursive: true });
  writeFileSync(join(repo, '.claude', 'voyage-guards.json'), JSON.stringify({ post_edit_check: true }));
 }
 function executing(repo, status = 'in_progress') {
  const dir = join(repo, '.claude', 'projects', '2026-10-06-x');
  mkdirSync(dir, { recursive: true });
  writeFileSync(join(dir, 'progress.json'), JSON.stringify({ status, steps: {} }));
 }
 function prettierRepo() {
  const repo = makeRepo('main');
  writeFileSync(join(repo, '.prettierrc'), '{}\n');
  fakeTool(join(repo, 'node_modules', '.bin'), 'prettier');
  return repo;
 }
 async function afterEdit(repo, rel, content) {
  const file = join(repo, rel);
  mkdirSync(join(file, '..'), { recursive: true });
  writeFileSync(file, content);
  const r = await runHook(HOOK, {
    hook_event_name: 'PostToolUse', tool_name: 'Edit', cwd: repo,
    tool_input: { file_path: file, old_string: 'a', new_string: 'b' },
    tool_response: { filePath: file },
  });
  return { ...r, out: parseJsonOut(r.stdout) };
 }
 const logOf = (repo) => {
  const p = join(repo, '.git', 'voyage', 'post-edit.jsonl');
  return existsSync(p) ? readFileSync(p, 'utf8').trim().split('\n').map((l) => JSON.parse(l)) : [];
 };
 test('P7 off: a repo that has not switched it on and runs no Voyage plan -> silent, no log', async () => {
  const repo = prettierRepo();
  const r = await afterEdit(repo, 'src/a.js', 'BAD\n');
  assert.equal(r.code, 0);
  assert.equal(r.out, null);
  assert.equal(logOf(repo).length, 0);
 });
 test('P7 must report: switched on, the repo\'s formatter rejects the file', async () => {
  const repo = prettierRepo();
  optIn(repo);
  const r = await afterEdit(repo, 'src/a.js', 'BAD\n');
  assert.equal(r.code, 0, r.stderr);
  assert.equal(r.out?.decision, 'block', `findings go back to Claude next to the tool result: ${r.stdout}`);
  assert.match(r.out.reason, /prettier/);
  const log = logOf(repo);
  assert.equal(log.length, 1);
  assert.equal(log[0].status, 'finding');
 });
 test('P7 must pass: switched on, the formatter accepts the file', async () => {
  const repo = prettierRepo();
  optIn(repo);
  const r = await afterEdit(repo, 'src/a.js', 'ok\n');
  assert.equal(r.code, 0);
  assert.notEqual(r.out?.decision, 'block');
  assert.equal(logOf(repo)[0].status, 'clean');
 });
 test('P7 on during a Voyage plan run (progress.json in_progress), without the switch', async () => {
  const repo = prettierRepo();
  executing(repo);
  const r = await afterEdit(repo, 'src/a.js', 'BAD\n');
  assert.equal(r.out?.decision, 'block');
 });
 test('P7 off once the plan run is completed', async () => {
  const repo = prettierRepo();
  executing(repo, 'completed');
  const r = await afterEdit(repo, 'src/a.js', 'BAD\n');
  assert.equal(r.code, 0, r.stderr);
  assert.equal(r.out, null);
 });
 test('P7 not measured: switched on in a repo with no tools -> "not measured", never green', async () => {
  const repo = makeRepo('main');
  optIn(repo);
  const r = await afterEdit(repo, 'src/a.js', 'whatever\n');
  assert.equal(r.code, 0);
  assert.match(r.out?.hookSpecificOutput?.additionalContext || '', /not measured/i);
  assert.doesNotMatch(r.out.hookSpecificOutput.additionalContext, /\bclean\b/i);
  assert.equal(logOf(repo)[0].status, 'not_measured');
 });
 test('P7 not measured: a configured tool that is not installed is not a pass', async () => {
  const repo = makeRepo('main');
  optIn(repo);
  writeFileSync(join(repo, '.prettierrc'), '{}\n'); // config, but no node_modules/.bin/prettier
  const r = await afterEdit(repo, 'src/a.js', 'BAD\n');
  assert.match(r.out?.hookSpecificOutput?.additionalContext || '', /not measured/i);
 });
 test('wiring: hooks.json runs post-edit-check on PostToolUse for Edit and Write', () => {
  for (const tool of ['Edit', 'Write']) {
    assert.ok(scriptsFor('PostToolUse', tool).some((p) => p.endsWith('post-edit-check.mjs')), tool);
  }
  assert.ok(!scriptsFor('PostToolUse', 'Bash').some((p) => p.endsWith('post-edit-check.mjs')));
 });
--- a/tests/hooks/storm-matcher.test.mjs
+++ b/tests/hooks/storm-matcher.test.mjs
@ -0,0 +1,26 @@
 // tests/hooks/storm-matcher.test.mjs
 // The STORM cap (pre-agent-cap.mjs) must see subagent spawns. The tool was
 // renamed Task -> Agent in Claude Code 2.1.63; the docs state the old name
 // still works as an alias «in settings and agent definitions»
 // (code.claude.com/docs/en/sub-agents, the rename note) and say nothing about
 // hook matchers, which compare against the tool name the hook input carries.
 // So the matcher must name `Agent` itself. Resolved with Claude Code's matcher
 // rules (hooks § Matcher patterns), as write-guard-coverage.test.mjs does.
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
 import { scriptsFor } from './guard-helpers.mjs';
 const fires = (tool) => scriptsFor('PreToolUse', tool).some((p) => p.endsWith('pre-agent-cap.mjs'));
 test('STORM cap fires on Agent (the tool name since 2.1.63)', () => {
  assert.ok(fires('Agent'), 'pre-agent-cap.mjs must fire for tool_name "Agent"');
 });
 test('STORM cap still fires on WebSearch, WebFetch and the old Task name', () => {
  for (const t of ['WebSearch', 'WebFetch', 'Task']) assert.ok(fires(t), t);
 });
 test('STORM cap does not fire on unrelated tools', () => {
  for (const t of ['Bash', 'Edit', 'Write', 'Read', 'AgentOutput', 'ExitPlanMode']) assert.ok(!fires(t), t);
 });
--- a/tests/hooks/test-lock-guard.test.mjs
+++ b/tests/hooks/test-lock-guard.test.mjs
@ -0,0 +1,131 @@
 // tests/hooks/test-lock-guard.test.mjs
 // P9 (3) — the lock on the tests. Two guards read the K8 lock:
 //   - the write guard (pre-write-executor.mjs, PreToolUse Write|Edit|
 //     NotebookEdit) refuses a change to a locked test file;
 //   - the stop guard (stop-test-lock.mjs, Stop) refuses "done" while the step
 //     that took the lock in THIS session still holds it, with the
 //     stop_hook_active guard (code.claude.com/docs/en/hooks § Stop input).
 // Pattern: Claude Code's own hooks (hooks-guide «Block edits to protected
 // files»; hooks reference § TaskCompleted/Stop decision control).
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
 import { spawnSync } from 'node:child_process';
 import { writeFileSync, mkdirSync, realpathSync } from 'node:fs';
 import { join } from 'node:path';
 import { runHook } from '../helpers/hook-helper.mjs';
 import { ROOT, scriptsFor, makeRepo, parseJsonOut } from './guard-helpers.mjs';
 const CLI = join(ROOT, 'lib', 'util', 'test-lock.mjs');
 const PRE_WRITE = join(ROOT, 'hooks', 'scripts', 'pre-write-executor.mjs');
 const STOP = join(ROOT, 'hooks', 'scripts', 'stop-test-lock.mjs');
 const RUN = `${process.pid}-${Date.now()}`;
 const SESS_A = `sess-A-${RUN}`;
 const SESS_B = `sess-B-${RUN}`;
 function lockedRepo({ session = SESS_A, step = 2 } = {}) {
  const repo = makeRepo('main');
  mkdirSync(join(repo, 'tests'), { recursive: true });
  writeFileSync(join(repo, 'tests', 'locked.test.js'), 'x\n');
  writeFileSync(join(repo, 'tests', 'free.test.js'), 'y\n');
  writeFileSync(join(repo, 'nb.ipynb'), '{}\n');
  const r = spawnSync(process.execPath, [CLI, 'lock', '--files', 'tests/locked.test.js,nb.ipynb', '--step', String(step)], {
    cwd: repo, encoding: 'utf8', env: { ...process.env, CLAUDE_CODE_SESSION_ID: session },
  });
  assert.equal(r.status, 0, `lock failed: ${r.stderr}`);
  return repo;
 }
 const edit = (file_path) => ({ hook_event_name: 'PreToolUse', tool_name: 'Edit', tool_input: { file_path, old_string: 'x', new_string: 'z' } });
 test('P9 lock must stop: Edit on a locked test file -> exit 2, names the step', async () => {
  const repo = lockedRepo();
  const r = await runHook(PRE_WRITE, edit(join(repo, 'tests', 'locked.test.js')));
  assert.equal(r.code, 2, r.stderr);
  assert.match(r.stderr, /locked/i);
  assert.match(r.stderr, /step 2/);
  assert.match(r.stderr, /operator/, 'the way forward: a wrong test goes to the operator');
 });
 test('P9 lock must stop: the same file reached through a symlinked path (/tmp vs /private/tmp)', async () => {
  const repo = lockedRepo();
  const real = realpathSync(repo);
  const alias = real.startsWith('/private/') ? real.slice('/private'.length) : real;
  const r = await runHook(PRE_WRITE, edit(join(alias, 'tests', 'locked.test.js')));
  assert.equal(r.code, 2);
 });
 test('P9 lock must stop: Write and NotebookEdit too', async () => {
  const repo = lockedRepo();
  const w = await runHook(PRE_WRITE, { tool_name: 'Write', tool_input: { file_path: join(repo, 'tests', 'locked.test.js'), content: '' } });
  assert.equal(w.code, 2);
  const n = await runHook(PRE_WRITE, { tool_name: 'NotebookEdit', tool_input: { notebook_path: join(repo, 'nb.ipynb'), new_source: '' } });
  assert.equal(n.code, 2);
 });
 test('P9 lock must pass: Edit on an unlocked file in the same repo', async () => {
  const repo = lockedRepo();
  const r = await runHook(PRE_WRITE, edit(join(repo, 'tests', 'free.test.js')));
  assert.equal(r.code, 0, r.stderr);
 });
 test('P9 lock must pass: a repo with no lock at all', async () => {
  const repo = makeRepo('main');
  const r = await runHook(PRE_WRITE, edit(join(repo, 'README.md')));
  assert.equal(r.code, 0, r.stderr);
 });
 test('P9 lock must pass: after unlock', async () => {
  const repo = lockedRepo();
  spawnSync(process.execPath, [CLI, 'unlock'], { cwd: repo });
  const r = await runHook(PRE_WRITE, edit(join(repo, 'tests', 'locked.test.js')));
  assert.equal(r.code, 0, r.stderr);
 });
 test('P9 lock fails closed: an unreadable lock blocks writes in that repo', async () => {
  const repo = lockedRepo();
  const st = JSON.parse(spawnSync(process.execPath, [CLI, 'status'], { cwd: repo, encoding: 'utf8' }).stdout);
  writeFileSync(st.lock_path, '{not json');
  const r = await runHook(PRE_WRITE, edit(join(repo, 'README.md')));
  assert.equal(r.code, 2);
  assert.ok(r.stderr.includes(st.lock_path), 'the message names the lock file to inspect');
 });
 const stop = (repo, extra = {}) => ({ hook_event_name: 'Stop', session_id: SESS_A, cwd: repo, stop_hook_active: false, ...extra });
 test('P9 stop must stop: "done" refused while this session\'s step holds the lock', async () => {
  const repo = lockedRepo();
  const r = await runHook(STOP, stop(repo));
  assert.equal(r.code, 0);
  const out = parseJsonOut(r.stdout);
  assert.equal(out?.decision, 'block', r.stdout);
  assert.match(out.reason, /step 2/);
 });
 test('P9 stop must pass: stop_hook_active is true (no endless loop)', async () => {
  const repo = lockedRepo();
  const r = await runHook(STOP, stop(repo, { stop_hook_active: true }));
  assert.equal(r.code, 0);
  assert.equal(parseJsonOut(r.stdout), null);
 });
 test('P9 stop must pass: the lock belongs to another session', async () => {
  const repo = lockedRepo({ session: SESS_B });
  // a session that holds no lock anywhere stops in a repo another session locked
  const r = await runHook(STOP, stop(repo, { session_id: `sess-free-${RUN}` }));
  assert.equal(parseJsonOut(r.stdout), null);
 });
 test('P9 stop must pass: no lock', async () => {
  const r = await runHook(STOP, stop(makeRepo('main'), { session_id: `sess-none-${RUN}` }));
  assert.equal(r.code, 0);
  assert.equal(parseJsonOut(r.stdout), null);
 });
 test('wiring: the write guard covers the lock for Write, Edit, NotebookEdit; the stop guard runs on Stop', () => {
  for (const tool of ['Write', 'Edit', 'NotebookEdit']) {
    assert.ok(scriptsFor('PreToolUse', tool).some((p) => p.endsWith('pre-write-executor.mjs')), tool);
  }
  assert.ok(scriptsFor('Stop').some((p) => p.endsWith('stop-test-lock.mjs')));
 });
--- a/tests/lib/guards-prose-pins.test.mjs
+++ b/tests/lib/guards-prose-pins.test.mjs
@ -0,0 +1,71 @@
 // tests/lib/guards-prose-pins.test.mjs
 // Prose pins owned by the guards process (wave-1 order 4). Counted as doc pins
 // by lib/util/test-census.mjs (PIN_FILE_RE matches `prose-pins.test.mjs`).
 //
 // The mod precondition: a Claude Code mod that handles `tool.check` answers
 // AFTER the rules and the PreToolUse hooks, and «its answer can replace
 // theirs» — it can approve a call a plugin PreToolUse hook blocked
 // (code.claude.com/docs/en/permissions § Extend permissions with hooks,
 // verified verbatim 06.10). So Voyage's stop guards are deterministic only
 // under a stated condition, and the condition is written where the guards are
 // described: README § Security hardening, SECURITY.md, and the head of every
 // PreToolUse stop guard.
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
 import { readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const read = (rel) => readFileSync(join(ROOT, rel), 'utf8');
 export const MOD_PRECONDITION = "Voyage's guards are deterministic only when no installed mod handles `tool.check`.";
 const STOP_GUARDS = [
  'hooks/scripts/pre-bash-executor.mjs',
  'hooks/scripts/pre-write-executor.mjs',
  'hooks/scripts/pre-agent-cap.mjs',
  'hooks/scripts/pre-plan-gate.mjs',
 ];
 test('mod precondition: README § Security hardening states it', () => {
  const md = read('README.md');
  const start = md.indexOf('### Security hardening');
  assert.ok(start !== -1);
  const end = md.indexOf('\n### ', start + 1);
  assert.ok(md.slice(start, end).includes(MOD_PRECONDITION), 'README § Security hardening must state the mod precondition');
 });
 test('mod precondition: SECURITY.md states it', () => {
  assert.ok(read('SECURITY.md').includes(MOD_PRECONDITION));
 });
 test('mod precondition: the head of every PreToolUse stop guard states it', () => {
  for (const rel of STOP_GUARDS) {
    const head = read(rel).split('\n').slice(0, 40).join('\n').replace(/^\/\/ ?/gm, '').replace(/\n/g, ' ');
    assert.ok(head.replace(/\s+/g, ' ').includes(MOD_PRECONDITION), `${rel}: the first 40 lines must state the mod precondition`);
  }
 });
 test('mod precondition: the guards cannot see a mod; the docs say so where it is stated', () => {
  // Looked up 06.10: no hook input field names installed mods; the documented
  // ways to see them are `/plugin` and a CLI subcommand, both for a person.
  assert.match(read('SECURITY.md'), /cannot tell whether such a mod is installed/);
 });
 test('P12 guard: README names the classes it asks about and that it holds in auto mode', () => {
  const md = read('README.md');
  const sec = md.slice(md.indexOf('### Security hardening'), md.indexOf('#### Recommended: disable Skill shell execution'));
  for (const w of ['merge into `main`', 'push', 'tag', 'destructive git', 'auto mode']) {
    assert.ok(sec.includes(w), `README § Security hardening must mention ${w}`);
  }
 });
 test('borrowings are credited where the guards are described (PLAN fixed limit 3)', () => {
  const md = read('README.md');
  const sec = md.slice(md.indexOf('### Security hardening'), md.indexOf('#### Recommended: disable Skill shell execution'));
  for (const src of ['Superpowers', 'agent-skills', 'ai-native-sdlc', 'Pocock', 'Kiro', 'Cherny', 'Claude Code']) {
    assert.ok(sec.includes(src), `credit missing for ${src}`);
  }
 });
--- a/tests/lib/repo-tools.test.mjs
+++ b/tests/lib/repo-tools.test.mjs
@ -0,0 +1,96 @@
 // tests/lib/repo-tools.test.mjs
 // lib/verification/repo-tools.mjs finds the target repo's OWN formatter,
 // linter and type checker. A tool counts only when the repo configures it AND
 // it is installed locally (node_modules/.bin) or on PATH; nothing is ever
 // downloaded. Exit codes are mapped per tool to clean / finding / error, and an
 // error is never read as clean.
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
 import { writeFileSync, mkdirSync, realpathSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { makeRepo, fakeTool, tmp } from '../hooks/guard-helpers.mjs';
 const HERE = dirname(fileURLToPath(import.meta.url));
 const mod = await import(join(HERE, '..', '..', 'lib', 'verification', 'repo-tools.mjs'));
 const { resolveRepo, detectTools, toolsForFile, runTool } = mod;
 test('resolveRepo: finds the root and git dir from a file path that does not exist yet', () => {
  const repo = makeRepo('main');
  const r = resolveRepo(join(repo, 'src', 'new', 'file.js'));
  assert.equal(r.root, realpathSync(repo));
  assert.equal(r.gitDir, realpathSync(join(repo, '.git')));
 });
 test('resolveRepo: null outside a repository', () => {
  assert.equal(resolveRepo(tmp()), null);
 });
 test('detectTools: prettier counts only with config AND a local binary', () => {
  const repo = makeRepo('main');
  writeFileSync(join(repo, '.prettierrc'), '{}');
  let tools = detectTools(repo, { env: { PATH: '/nonexistent' } });
  const p = tools.find((t) => t.name === 'prettier');
  assert.ok(p && !p.available, 'configured but not installed is listed as unavailable');
  fakeTool(join(repo, 'node_modules', '.bin'), 'prettier');
  tools = detectTools(repo, { env: { PATH: '/nonexistent' } });
  assert.ok(tools.find((t) => t.name === 'prettier').available);
 });
 test('detectTools: a repo with nothing configured has no tools', () => {
  assert.deepEqual(detectTools(makeRepo('main'), { env: { PATH: '/nonexistent' } }), []);
 });
 test('detectTools: eslint and tsc (repo tier) from config + local binaries', () => {
  const repo = makeRepo('main');
  writeFileSync(join(repo, 'eslint.config.js'), 'export default [];');
  writeFileSync(join(repo, 'tsconfig.json'), '{}');
  fakeTool(join(repo, 'node_modules', '.bin'), 'eslint');
  fakeTool(join(repo, 'node_modules', '.bin'), 'tsc');
  const tools = detectTools(repo, { env: { PATH: '/nonexistent' } });
  const eslint = tools.find((t) => t.name === 'eslint');
  const tsc = tools.find((t) => t.name === 'tsc');
  assert.equal(eslint.kind, 'lint');
  assert.equal(eslint.tier, 'file');
  assert.equal(tsc.kind, 'typecheck');
  assert.equal(tsc.tier, 'repo');
 });
 test('detectTools: ruff from pyproject [tool.ruff] and a binary on PATH', () => {
  const repo = makeRepo('main');
  writeFileSync(join(repo, 'pyproject.toml'), '[tool.ruff]\nline-length = 100\n');
  const bin = join(tmp(), 'bin');
  fakeTool(bin, 'ruff');
  const tools = detectTools(repo, { env: { PATH: bin } });
  assert.ok(tools.some((t) => t.name === 'ruff-check' && t.available));
  assert.ok(tools.some((t) => t.name === 'ruff-format' && t.available));
 });
 test('toolsForFile: by extension, file tier only', () => {
  const repo = makeRepo('main');
  writeFileSync(join(repo, '.prettierrc'), '{}');
  writeFileSync(join(repo, 'tsconfig.json'), '{}');
  fakeTool(join(repo, 'node_modules', '.bin'), 'prettier');
  fakeTool(join(repo, 'node_modules', '.bin'), 'tsc');
  const tools = detectTools(repo, { env: { PATH: '/nonexistent' } });
  assert.deepEqual(toolsForFile(tools, 'src/a.ts').map((t) => t.name), ['prettier']);
  assert.deepEqual(toolsForFile(tools, 'image.png').map((t) => t.name), []);
 });
 test('runTool: clean, finding and error are three different answers', () => {
  const repo = makeRepo('main');
  writeFileSync(join(repo, '.prettierrc'), '{}');
  fakeTool(join(repo, 'node_modules', '.bin'), 'prettier');
  mkdirSync(join(repo, 'src'));
  writeFileSync(join(repo, 'src', 'good.js'), 'ok');
  writeFileSync(join(repo, 'src', 'bad.js'), 'BAD');
  const tool = detectTools(repo, { env: { PATH: '/nonexistent' } }).find((t) => t.name === 'prettier');
  assert.equal(runTool(tool, ['src/good.js'], { cwd: repo }).status, 'clean');
  const f = runTool(tool, ['src/bad.js'], { cwd: repo });
  assert.equal(f.status, 'finding');
  assert.match(f.output, /problem/);
  // exit 7 is neither clean nor a finding for prettier
  fakeTool(join(repo, 'node_modules', '.bin'), 'prettier', { findingExit: 7 });
  assert.equal(runTool(tool, ['src/bad.js'], { cwd: repo }).status, 'error');
 });
--- a/tests/lib/step-check.test.mjs
+++ b/tests/lib/step-check.test.mjs
@ -0,0 +1,106 @@
 // tests/lib/step-check.test.mjs
 // K9 — the step check (lib/verification/step-check.mjs --cwd <dir>). At step
 // end it runs the repo's own tools over the changed files (and the repo-wide
 // ones, such as the type checker), reads the post-edit guard's log, and
 // answers 0 = green, 1 = findings, 2 = "not measured" (never green). JSON on
 // stdout. The architecture-rule runner (K5, wave-1 order 3) is optional: when
 // it is missing, it is listed as not measured.
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
 import { spawnSync } from 'node:child_process';
 import { writeFileSync, mkdirSync, appendFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ROOT, makeRepo, gitIn, fakeTool, tmp, pluginCopy } from '../hooks/guard-helpers.mjs';
 const CLI = join(ROOT, 'lib', 'verification', 'step-check.mjs');
 function run(cli, args, env = {}) {
  const r = spawnSync(process.execPath, [cli, ...args], { encoding: 'utf8', env: { ...process.env, PATH: '/usr/bin:/bin', ...env } });
  let json = null;
  try { json = JSON.parse(r.stdout); } catch { json = null; }
  return { code: r.status, stdout: r.stdout, stderr: r.stderr, json };
 }
 function toolRepo() {
  const repo = makeRepo('main');
  writeFileSync(join(repo, '.prettierrc'), '{}');
  writeFileSync(join(repo, '.gitignore'), 'node_modules/\n');
  gitIn(repo, 'add', '.prettierrc', '.gitignore');
  gitIn(repo, 'commit', '-q', '-m', 'tools');
  fakeTool(join(repo, 'node_modules', '.bin'), 'prettier');
  return repo;
 }
 test('K9 green (0): the changed files pass the repo\'s own tools', () => {
  const repo = toolRepo();
  writeFileSync(join(repo, 'a.js'), 'ok\n');
  const r = run(CLI, ['--cwd', repo]);
  assert.equal(r.code, 0, r.stdout + r.stderr);
  assert.equal(r.json.status, 'green');
  assert.ok(r.json.checks.some((c) => c.name === 'prettier' && c.status === 'clean'));
 });
 test('K9 findings (1): a changed file the formatter rejects', () => {
  const repo = toolRepo();
  writeFileSync(join(repo, 'a.js'), 'BAD\n');
  const r = run(CLI, ['--cwd', repo]);
  assert.equal(r.code, 1, r.stdout);
  assert.equal(r.json?.status, 'findings');
 });
 test('K9 findings (1): the post-edit log holds a finding for a changed file no tool can re-check', () => {
  const repo = makeRepo('main');
  writeFileSync(join(repo, 'a.js'), 'x\n');
  mkdirSync(join(repo, '.git', 'voyage'), { recursive: true });
  appendFileSync(join(repo, '.git', 'voyage', 'post-edit.jsonl'),
    JSON.stringify({ ts: new Date().toISOString(), file: 'a.js', status: 'finding', results: [{ name: 'prettier', status: 'finding' }] }) + '\n');
  const r = run(CLI, ['--cwd', repo]);
  assert.equal(r.code, 1, r.stdout);
  assert.equal(r.json?.status, 'findings', 'exit 1 must be a finding, not a crash');
 });
 test('K9 not measured (2): a repo with no tools at all -> never green', () => {
  const repo = makeRepo('main');
  writeFileSync(join(repo, 'a.js'), 'BAD\n');
  const r = run(CLI, ['--cwd', repo]);
  assert.equal(r.code, 2, r.stdout);
  assert.equal(r.json.status, 'not_measured');
 });
 test('K9 not measured (2): not a git repository', () => {
  const r = run(CLI, ['--cwd', tmp()]);
  assert.equal(r.code, 2);
 });
 test('K9 usage error (2): no --cwd', () => {
  assert.equal(run(CLI, []).code, 2);
 });
 test('K9 --full: checks tracked files, not only the diff', () => {
  const repo = toolRepo();
  writeFileSync(join(repo, 'old.js'), 'BAD\n');
  gitIn(repo, 'add', 'old.js');
  gitIn(repo, 'commit', '-q', '-m', 'old');
  assert.notEqual(run(CLI, ['--cwd', repo]).json.status, 'findings', 'old.js is not in the diff');
  assert.equal(run(CLI, ['--cwd', repo, '--full']).code, 1);
 });
 test('K5 optional: arch-rules missing is listed as not measured and does not turn green into red', () => {
  const plugin = pluginCopy({ 'lib/verification/arch-rules.mjs': 'missing' });
  const repo = toolRepo();
  writeFileSync(join(repo, 'a.js'), 'ok\n');
  const r = run(join(plugin, 'lib', 'verification', 'step-check.mjs'), ['--cwd', repo]);
  assert.equal(r.code, 0, r.stdout);
  const arch = r.json.checks.find((c) => c.name === 'arch-rules');
  assert.equal(arch.status, 'not_measured');
 });
 test('K5 optional: arch-rules stub reporting a breach (exit 1) makes the step red', () => {
  const plugin = pluginCopy({ 'lib/verification/arch-rules.mjs': 'stub' });
  const repo = toolRepo();
  writeFileSync(join(repo, 'a.js'), 'ok\n');
  const r = run(join(plugin, 'lib', 'verification', 'step-check.mjs'), ['--cwd', repo], { STUB_EXIT: '1' });
  assert.equal(r.code, 1, r.stdout);
  assert.equal(r.json?.checks.find((c) => c.name === 'arch-rules')?.status, 'finding');
 });
--- a/tests/lib/test-lock.test.mjs
+++ b/tests/lib/test-lock.test.mjs
@ -0,0 +1,104 @@
 // tests/lib/test-lock.test.mjs
 // K8 — the test lock CLI (lib/util/test-lock.mjs). The executor (wave-1 order
 // 1) locks a step's test files once the test is written and seen failing, and
 // unlocks them when the test passes. The lock lives inside the repository's
 // git directory, so it can never be committed.
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { makeRepo, gitIn, tmp } from '../hooks/guard-helpers.mjs';
 const HERE = dirname(fileURLToPath(import.meta.url));
 const CLI = join(HERE, '..', '..', 'lib', 'util', 'test-lock.mjs');
 function run(cwd, args, env = {}) {
  const r = spawnSync(process.execPath, [CLI, ...args], { cwd, encoding: 'utf8', env: { ...process.env, ...env } });
  return { code: r.status, stdout: r.stdout, stderr: r.stderr };
 }
 function repoWithTests() {
  const repo = makeRepo('main');
  mkdirSync(join(repo, 'tests'), { recursive: true });
  writeFileSync(join(repo, 'tests', 'a.test.js'), 'a\n');
  writeFileSync(join(repo, 'tests', 'b.test.js'), 'b\n');
  return repo;
 }
 test('K8 lock: exit 0, status names the step and the files', () => {
  const repo = repoWithTests();
  const r = run(repo, ['lock', '--files', 'tests/a.test.js,tests/b.test.js', '--step', '3']);
  assert.equal(r.code, 0, r.stderr);
  const s = run(repo, ['status']);
  assert.equal(s.code, 0);
  const st = JSON.parse(s.stdout);
  assert.equal(st.locked, true);
  assert.equal(st.step, 3);
  assert.equal(st.files.length, 2);
  assert.ok(st.files.every((f) => f.endsWith('.test.js')));
 });
 test('K8 lock: stored outside what can be committed (git status stays clean)', () => {
  const repo = repoWithTests();
  gitIn(repo, 'add', '-A');
  gitIn(repo, 'commit', '-q', '-m', 'tests');
  assert.equal(run(repo, ['lock', '--files', 'tests/a.test.js', '--step', '1']).code, 0);
  assert.equal(gitIn(repo, 'status', '--porcelain'), '', 'the lock must not appear as a change in the repo');
  const st = JSON.parse(run(repo, ['status']).stdout);
  assert.ok(st.lock_path.includes(`${'.git'}`), `lock path should be inside the git dir: ${st.lock_path}`);
 });
 test('K8 lock records the Claude Code session it was taken in', () => {
  const repo = repoWithTests();
  run(repo, ['lock', '--files', 'tests/a.test.js', '--step', '2'], { CLAUDE_CODE_SESSION_ID: 'sess-123' });
  assert.equal(JSON.parse(run(repo, ['status']).stdout).session, 'sess-123');
 });
 test('K8 unlock: exit 0, status unlocked', () => {
  const repo = repoWithTests();
  run(repo, ['lock', '--files', 'tests/a.test.js', '--step', '1']);
  assert.equal(run(repo, ['unlock']).code, 0);
  assert.equal(JSON.parse(run(repo, ['status']).stdout).locked, false);
 });
 test('K8 lock refuses (exit 1) while another step holds the lock', () => {
  const repo = repoWithTests();
  run(repo, ['lock', '--files', 'tests/a.test.js', '--step', '1']);
  const r = run(repo, ['lock', '--files', 'tests/b.test.js', '--step', '2']);
  assert.equal(r.code, 1);
  assert.match(r.stderr, /step 1/);
 });
 test('K8: --cwd points at another directory', () => {
  const repo = repoWithTests();
  assert.equal(run(tmp(), ['lock', '--cwd', repo, '--files', 'tests/a.test.js', '--step', '4']).code, 0);
  assert.equal(JSON.parse(run(tmp(), ['status', '--cwd', repo]).stdout).step, 4);
 });
 test('K8 could not run (exit 2): not a git repository', () => {
  const r = run(tmp(), ['lock', '--files', 'x.test.js', '--step', '1']);
  assert.equal(r.code, 2);
 });
 test('K8 could not run (exit 2): bad usage', () => {
  const repo = repoWithTests();
  assert.equal(run(repo, ['lock', '--step', '1']).code, 2, 'no --files');
  assert.equal(run(repo, ['lock', '--files', 'tests/a.test.js']).code, 2, 'no --step');
  assert.equal(run(repo, ['lock', '--files', 'tests/a.test.js', '--step', 'x']).code, 2, 'step not a number');
  assert.equal(run(repo, ['frobnicate']).code, 2);
 });
 test('K8 status on a corrupt lock: exit 2, never "unlocked"', () => {
  const repo = repoWithTests();
  run(repo, ['lock', '--files', 'tests/a.test.js', '--step', '1']);
  const path = JSON.parse(run(repo, ['status']).stdout).lock_path;
  writeFileSync(path, '{not json');
  const s = run(repo, ['status']);
  assert.equal(s.code, 2);
  assert.ok(existsSync(path));
  assert.ok(!/"locked":\s*false/.test(s.stdout));
  assert.ok(readFileSync(path, 'utf8').startsWith('{not'), 'status never rewrites the lock');
 });