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>

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-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-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, 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
-to **fail open** — a hook crash never blocks the user's work. Hooks log
-to stderr only; they never write to user files outside their declared
-scope.
+All hooks are zero-dependency Node.js (`.mjs`) scripts. Most are designed
+to **fail open** — a hook crash never blocks the user's work. The
+exceptions are stated per hook above: the write guard fails closed when it
+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`)