From a201b7564d6c268e2b472183d61aedb05da16b56 Mon Sep 17 00:00:00 2001
From: Jordan Winters <dralgorhythm@users.noreply.github.com>
Date: Fri, 24 Jul 2026 11:50:28 -0500
Subject: [PATCH 1/2] feat(hooks): commit gate runs detected gates with
 content-bound evidence (U5b)

pre-commit-verification.sh moves from advisory-only to enforcing (jq
present; jq-absent path unchanged, still silent fail-open). On `git
commit` it now runs every gate gate-lib.sh detects, each under
timeout "${CLAUDE_GATE_TIMEOUT_SECS:-120}" from the project dir,
logging to .claude/hooks/.state/gate-<label>.log:

- All green -> writes a hook-authored evidence stamp
  (.claude/hooks/.state/commit-verified, `{epoch, tree-hash}`),
  trusted on a later commit only when BOTH <=5 minutes old AND its
  tree-hash matches the current `git write-tree` output -- content-
  bound, not time-only, so an edit staged seconds ago forces a
  re-run despite an otherwise-fresh stamp.
- A red gate -> denies, naming the gate, its log, and the existing
  anti-test-deletion sentence.
- A gate exceeding its budget -> asks (never a silent kill or hang);
  no stamp is written.
- No gates detected -> falls back to the original advisory text,
  unchanged (its self-write instruction is removed since the stamp
  is hook-authored only in every branch now).
- CLAUDE_SKIP_GATE_HOOK=1 escape hatch allows unconditionally, with
  the skip always disclosed in context.

settings.json: raises only this hook's registered timeout 5 -> 300
(per-gate defaults sum safely under it). docs/hooks.md gains a
"Quality Gates" subsection; MIGRATION.md and CHANGELOG.md record the
newly-blocking behavior.

New scripts/hook-tests.d/30-gates-lane.sh covers red/green/timeout/
escape-hatch/cache-invalidation against three fixtures. failing-
project and slow-gate each gain an empty package-lock.json (verified
via gate_lib_detect: no lockfile picks pnpm, which ubuntu-latest
runners don't ship, so an npm-selecting lockfile keeps the fixtures
CI-executable); new sibling fixture passing-project covers the
green/stamp path. slow-gate also gains a package.json wiring its
"test" script to `bash gate.sh`.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .claude/hooks/pre-commit-verification.sh      | 147 +++++++++++----
 .claude/settings.json                         |   2 +-
 CHANGELOG.md                                  |   1 +
 MIGRATION.md                                  |  20 +++
 docs/hooks.md                                 |  13 +-
 .../failing-project/package-lock.json         |   0
 .../passing-project/package-lock.json         |   0
 scripts/fixtures/passing-project/package.json |   9 +
 scripts/fixtures/slow-gate/package-lock.json  |   0
 scripts/fixtures/slow-gate/package.json       |   9 +
 scripts/hook-tests.d/30-gates-lane.sh         | 169 ++++++++++++++++++
 11 files changed, 337 insertions(+), 33 deletions(-)
 create mode 100644 scripts/fixtures/failing-project/package-lock.json
 create mode 100644 scripts/fixtures/passing-project/package-lock.json
 create mode 100644 scripts/fixtures/passing-project/package.json
 create mode 100644 scripts/fixtures/slow-gate/package-lock.json
 create mode 100644 scripts/fixtures/slow-gate/package.json
 create mode 100644 scripts/hook-tests.d/30-gates-lane.sh

diff --git a/.claude/hooks/pre-commit-verification.sh b/.claude/hooks/pre-commit-verification.sh
index c180acb..7de0327 100755
--- a/.claude/hooks/pre-commit-verification.sh
+++ b/.claude/hooks/pre-commit-verification.sh
@@ -1,12 +1,26 @@
 #!/bin/bash
 # Hook: pre-commit-verification
 # Event: PreToolUse (Bash)
-# Purpose: Ensure tests and linting pass before git commits
+# Purpose: Run the project's detected quality gates before git commits and
+# block the commit on failure.
+#
+# Enforcement rewrite (artifacts/plan_framework_hardening.md, unit U5b): this
+# hook used to only ever print advisory text and trust a time-only stamp the
+# AGENT was instructed to write by hand — self-attestation, not verification
+# (see the plan's Design Principles). It now runs the gates itself. A stamp
+# is trusted only when BOTH fresh (<=5 min) AND content-bound: its recorded
+# tree-hash must equal the current `git write-tree` output, so a change
+# staged seconds ago forces a re-run even if the last stamp is a minute old
+# (review F8 — a time-only stamp rides post-edit changes). The stamp file is
+# hook-authored only; nothing in this file's own output ever instructs the
+# agent to write it.
 
 INPUT=$(cat)
 
 # jq is required to parse tool input; fail open if unavailable (hooks are
-# guardrails, not a security boundary)
+# guardrails, not a security boundary). This path is byte-for-byte the same
+# as before this rewrite — no gates ever ran on the jq-absent path, and none
+# do now either.
 command -v jq >/dev/null 2>&1 || exit 0
 
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
@@ -18,48 +32,60 @@ if [ "$TOOL_NAME" != "Bash" ]; then
     exit 0
 fi
 
-# Check if this is a git commit command
 if ! echo "$COMMAND" | grep -qE '\bgit\s+commit\b'; then
     exit 0
 fi
 
-# Check for state file indicating verification already completed
 STATE_DIR="$PROJECT_DIR/.claude/hooks/.state"
 mkdir -p "$STATE_DIR"
-VERIFICATION_FILE="$STATE_DIR/commit-verified"
+STAMP_FILE="$STATE_DIR/commit-verified"
 
-# If verification was completed recently (within last 5 minutes), allow commit
-if [ -f "$VERIFICATION_FILE" ]; then
-    VERIFIED_TIME=$(cat "$VERIFICATION_FILE" 2>/dev/null || echo 0)
-    [[ "$VERIFIED_TIME" =~ ^[0-9]+$ ]] || VERIFIED_TIME=0
-    CURRENT_TIME=$(date +%s)
-    TIME_DIFF=$((CURRENT_TIME - VERIFIED_TIME))
-
-    if [ "$TIME_DIFF" -lt 300 ]; then
-        # Verification is recent, allow commit
-        exit 0
-    fi
+# Escape hatch: unconditional, checked before the stamp or any gate ever
+# runs, and always disclosed — never a silent skip.
+if [ "${CLAUDE_SKIP_GATE_HOOK:-}" = "1" ]; then
+    cat << EOF
+{
+  "hookSpecificOutput": {
+    "additionalContext": "[GATE HOOK SKIPPED] CLAUDE_SKIP_GATE_HOOK=1 is set — quality gates were NOT run for this commit. Unset it to restore enforcement."
+  }
+}
+EOF
+    exit 0
 fi
 
 # Detect project type and available gates — detection lives in gate-lib.sh
-# (artifacts/plan_framework_hardening.md, unit U5a): one shared function
-# emits invocable commands per gate; this hook only needs the human labels
-# for its advisory text below, reconstructed here in the same order and
-# format ("<label>" tokens space-joined) as before the extraction, so the
-# advisory output stays byte-identical.
+# (unit U5a): one shared function emits invocable commands plus the human
+# label the advisory has always shown.
 # shellcheck source=gate-lib.sh
 # shellcheck disable=SC1091  # dynamic path (BASH_SOURCE-relative); the
 # above source= directive documents it for anyone re-running with `-x`
 source "$(dirname "${BASH_SOURCE[0]}")/gate-lib.sh"
-gate_lib_detect "$PROJECT_DIR"
 
-DETECTED_TOOLS=""
-for _gate_label in "${GATE_LABELS[@]}"; do
-    DETECTED_TOOLS="$DETECTED_TOOLS $_gate_label"
-done
+# A stamp is trusted only if BOTH fresh (<5 min) AND content-bound to the
+# CURRENT index — computed once, up front, before we even know whether there
+# are gates to trust it for.
+CURRENT_TREE=$(git -C "$PROJECT_DIR" write-tree 2>/dev/null || true)
+
+if [ -f "$STAMP_FILE" ] && [ -n "$CURRENT_TREE" ]; then
+    STAMP_EPOCH=""
+    STAMP_TREE=""
+    read -r STAMP_EPOCH STAMP_TREE < "$STAMP_FILE" 2>/dev/null || true
+    [[ "$STAMP_EPOCH" =~ ^[0-9]+$ ]] || STAMP_EPOCH=0
+    NOW=$(date +%s)
+    AGE=$((NOW - STAMP_EPOCH))
+    if [ "$AGE" -lt 300 ] && [ "$STAMP_TREE" = "$CURRENT_TREE" ]; then
+        exit 0
+    fi
+fi
+
+gate_lib_detect "$PROJECT_DIR"
 
-# Build verification context message
-cat << EOF
+# No gates detected: nothing for the hook to run automatically — keep
+# today's advisory guidance (manual verification is the only check that
+# happens here; the stamp stays hook-authored-only in every branch, so this
+# text no longer tells the agent to write it by hand).
+if [ "${#GATE_LABELS[@]}" -eq 0 ]; then
+    cat << EOF
 {
   "hookSpecificOutput": {
     "additionalContext": "
@@ -73,7 +99,7 @@ Before committing, you MUST complete these steps:
    - Run linting/formatting checks and fix any issues
    - Run type checking if available
 
-   Detected tools in this project: ${DETECTED_TOOLS:-none detected - check manually}
+   Detected tools in this project: none detected - check manually
 
 2. FIX ALL FAILURES:
    - If tests fail, fix the code until they pass
@@ -87,11 +113,70 @@ Before committing, you MUST complete these steps:
    - Fix the actual code issues instead
 
 4. AFTER VERIFICATION SUCCEEDS:
-   - Mark verification complete: echo \$(date +%s) > $STATE_DIR/commit-verified
-   - Then proceed with the git commit
+   - Proceed with the git commit. No gates were detected for this project,
+     so this manual pass is the only verification that happens — nothing
+     here is written or re-checked automatically.
 
 If you cannot fix a test legitimately, STOP and ask the user for guidance.
 ---"
   }
 }
 EOF
+    exit 0
+fi
+
+# Gates detected: run each one under its own timeout, from PROJECT_DIR,
+# logging to its own file. Fail-fast on the first red or timed-out gate —
+# the reason names exactly one gate, matching the plan's fixtures.
+GATE_TIMEOUT="${CLAUDE_GATE_TIMEOUT_SECS:-120}"
+FAILED_LABEL=""
+FAILED_LOG=""
+TIMED_OUT_LABEL=""
+
+for _gate_i in "${!GATE_LABELS[@]}"; do
+    _gate_label="${GATE_LABELS[$_gate_i]}"
+    _gate_cmd="${GATE_COMMANDS[$_gate_i]}"
+    _gate_log="$STATE_DIR/gate-${_gate_label//\//_}.log"
+    ( cd "$PROJECT_DIR" && timeout "$GATE_TIMEOUT" bash -c "$_gate_cmd" </dev/null ) >"$_gate_log" 2>&1
+    _gate_rc=$?
+    if [ "$_gate_rc" -eq 124 ]; then
+        TIMED_OUT_LABEL="$_gate_label"
+        break
+    elif [ "$_gate_rc" -ne 0 ]; then
+        FAILED_LABEL="$_gate_label"
+        FAILED_LOG="$_gate_log"
+        break
+    fi
+done
+
+if [ -n "$TIMED_OUT_LABEL" ]; then
+    cat << EOF
+{
+  "hookSpecificOutput": {
+    "permissionDecision": "ask",
+    "permissionDecisionReason": "Quality gate '$TIMED_OUT_LABEL' exceeded its ${GATE_TIMEOUT}s budget and was stopped — gates did not finish, so nothing was verified either way. Run them manually before committing; no evidence stamp was written."
+  }
+}
+EOF
+    exit 0
+fi
+
+if [ -n "$FAILED_LABEL" ]; then
+    cat << EOF
+{
+  "hookSpecificOutput": {
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Quality gate '$FAILED_LABEL' failed. See $FAILED_LOG for details. Do not delete or weaken tests to force a pass — fix the issue or ask the user."
+  }
+}
+EOF
+    exit 0
+fi
+
+# All gates green: hook-authored stamp only, content-bound to the index we
+# actually checked — no instruction anywhere tells the agent to write this
+# file itself.
+if [ -n "$CURRENT_TREE" ]; then
+    echo "$(date +%s) $CURRENT_TREE" > "$STAMP_FILE"
+fi
+exit 0
diff --git a/.claude/settings.json b/.claude/settings.json
index 7d2475b..3570688 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -342,7 +342,7 @@
           {
             "type": "command",
             "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-commit-verification.sh",
-            "timeout": 5
+            "timeout": 300
           },
           {
             "type": "command",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9a2b9f4..b46e395 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -36,6 +36,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Correction-capture loop (O14): `.claude/rules/core-directives.md` gains a compact "Correction Capture" subsection — when a user correction contradicts a standing rule/skill/instruction, append one line to `scratchpad/corrections.log` (`YYYY-MM-DD | correction | surface`); `land-the-plane`'s Handoff section gains a Retro step that maps each logged entry to the strongest enforcement rung it can support (rule/skill/hook/CI — the same discipline `postmortem`'s Prevention step already applies), promotes it via a small PR or filed issue, then removes the line; `stop-validator.sh` now emits a one-line session-end reminder naming the pending count when the log is non-empty. New `scripts/hook-tests.d/40-self-improvement.sh` harness cases cover the 2-line, absent, and zero-byte log states (unit U16)
 - `docs/customization.md`'s new "Session Learning: Auto-Memory vs. Repo Rules" section draws the line between Claude Code's personal, unreviewed auto-memory and this repo's team-shared, reviewed `.claude/rules/`/`.claude/skills/`/`.claude/hooks/` layer, cross-linking the Correction Capture convention; `CONTRIBUTING.md`'s new "Standing self-improvement loop" section names the full capture → escalate → verify → re-audit cycle the eval-first and retirement policies feed into, including re-running `artifacts/research_ai_coding_frustrations.md`'s failure-taxonomy coverage audit at each model-generation bump (unit U16)
 - `branch-pr-discipline.sh`'s no-jq sed fallback switched to `sed -E` — the old BRE alternation silently never matched on BSD/macOS sed, disabling the hook's warnings whenever jq was absent (same bug class fixed in `pre-push-main-blocker.sh` by U1); regression cases added in `scripts/hook-tests.d/50-discipline.sh`
+- `pre-commit-verification.sh` rewritten from advisory-only to enforcing (jq present): on `git commit`, runs every gate `gate-lib.sh` detects, each under `timeout "${CLAUDE_GATE_TIMEOUT_SECS:-120}"` from the project dir, logging to `.claude/hooks/.state/gate-<label>.log`. All green writes a hook-authored evidence stamp (`.claude/hooks/.state/commit-verified`, `{epoch, tree-hash}`) trusted on a later commit only when BOTH ≤5 minutes old AND its tree-hash matches the current `git write-tree` output — content-bound, not time-only (review F8), so an edit staged seconds ago forces a re-run despite an otherwise-fresh stamp. A red gate denies the commit, naming the gate, its log, and the existing anti-test-deletion sentence; a gate that exceeds its budget asks instead of silently killing or hanging, and writes no stamp. No gates detected → falls back to the original advisory text, unchanged. `CLAUDE_SKIP_GATE_HOOK=1` escape hatch allows unconditionally with the skip always disclosed in context; the jq-absent path is unchanged (silent fail-open). `settings.json`'s registration for this hook is raised from 5s to 300s to fit real gate runs (per-gate defaults sum safely under it). New `scripts/hook-tests.d/30-gates-lane.sh` covers the red/green/timeout/escape-hatch/cache-invalidation matrix against three fixtures — `scripts/fixtures/failing-project/` and `.../slow-gate/` each gain an (empty) `package-lock.json` so `gate-lib.sh` picks npm over pnpm (GitHub-hosted ubuntu-latest ships the former, not the latter, keeping the fixtures CI-executable); new sibling fixture `scripts/fixtures/passing-project/` covers the green/stamp path. `docs/hooks.md` gains a "Quality Gates" subsection documenting the stamp, `CLAUDE_GATE_TIMEOUT_SECS`, and the escape hatch (unit U5b)
 
 ## [4.0.0] - 2026-07-23
 
diff --git a/MIGRATION.md b/MIGRATION.md
index fc57c59..188f694 100644
--- a/MIGRATION.md
+++ b/MIGRATION.md
@@ -287,3 +287,23 @@ Correction Capture convention; adopters who aren't will never see this reminder,
 empty log stays exactly as silent as before.
 
 <!-- Future v3 migration notes appended here. -->
+
+### Commits are newly blocking when a quality gate is detected
+
+**Who is affected:** any project with a detectable stack — a `package.json` with a `test`/`lint`/`typecheck`/`biome` script, a `pyproject.toml` with `pytest`/`ruff`/`mypy`, a `go.mod`, or a `Cargo.toml`. Projects with none of these see no behavior change.
+
+**What breaks:** `pre-commit-verification.sh` used to only print advisory text before a `git commit` — it never ran anything itself, and trusted a stamp the agent was instructed to write by hand after manually verifying (self-attestation). It now runs the project's detected quality gates itself (detection: `.claude/hooks/gate-lib.sh`) and blocks the commit if one fails:
+
+- A failing gate denies the commit, naming the gate and its log (`.claude/hooks/.state/gate-<label>.log`), plus a reminder never to delete or weaken a test to force a pass.
+- A passing run writes a hook-authored evidence stamp (`.claude/hooks/.state/commit-verified`) so an immediately-following commit doesn't always re-run the same gates — but the stamp is trusted only when BOTH ≤5 minutes old AND content-bound (its recorded tree-hash matches the current `git write-tree` output), so staging any change invalidates it even seconds after a fresh stamp.
+- A gate that runs longer than its timeout produces an `ask` (an honest "exceeded budget, run manually" reason), never a silent kill or an indefinite hang, and writes no stamp.
+- The hook's own registration in `.claude/settings.json` is raised from 5s to 300s to fit real gate runs; each individual gate still defaults to a 120s budget.
+
+**Action required:**
+
+- If a gate legitimately takes longer than the 120s default, set `CLAUDE_GATE_TIMEOUT_SECS` (seconds) in your environment before committing.
+- To skip gate enforcement for one commit (e.g. mid-refactor, or a known-slow environment), set `CLAUDE_SKIP_GATE_HOOK=1`. The skip is always disclosed in the hook's own output, never silent.
+- If you don't want this hook running gates at all, remove its entry from `.claude/settings.json`'s `hooks.PreToolUse` (`Bash` matcher) — see `docs/hooks.md`'s "How to disable a hook."
+- If `jq` is unavailable in your environment, this hook's behavior is unchanged from before this release (silent no-op; no gates run, no advisory shown).
+
+<!-- Future migration notes appended here. -->
diff --git a/docs/hooks.md b/docs/hooks.md
index 9059cb9..23dd74b 100644
--- a/docs/hooks.md
+++ b/docs/hooks.md
@@ -10,7 +10,7 @@ Hooks run automatically at key points in Claude Code's lifecycle.
 | `pre-tool-use-validator.sh` | PreToolUse | File locking, secret detection (Write/Edit + Bash redirects/heredocs), protected file enforcement, config-write ask-gate |
 | `dangerous-command-guard.sh` | PreToolUse (Bash) | Guard against dangerous shell commands (force push, rm -rf, etc.) |
 | `pre-push-main-blocker.sh` | PreToolUse (Bash) | Block direct pushes to main/master branch |
-| `pre-commit-verification.sh` | PreToolUse (Bash) | Pre-commit quality checks |
+| `pre-commit-verification.sh` | PreToolUse (Bash) | Runs detected quality gates before `git commit`; blocks on failure, asks on timeout |
 | `post-tool-use-tracker.sh` | PostToolUse | Track file changes |
 | `stop-validator.sh` | Stop | Release file locks, cleanup session state, warn about uncommitted/unpushed work and unprocessed `scratchpad/corrections.log` entries |
 | `subagent-stop-validator.sh` | SubagentStop | Log swarm worker completion |
@@ -59,6 +59,17 @@ Asks for confirmation (not a hard block) before a direct Write/Edit to:
 
 These are the same paths `/tailor` proposes changes to rather than writing directly (see `tailor/SKILL.md`'s Output Contract) — this hook backs that contract mechanically instead of leaving it as convention only.
 
+### Quality Gates (pre-commit-verification.sh)
+
+Runs the project's detected quality gates before every `git commit` and blocks the commit if one fails (unit U5b of `artifacts/plan_framework_hardening.md`):
+
+- **Detection**: gate labels/commands come from `.claude/hooks/gate-lib.sh` (unit U5a) — per-stack: TS/JS via the detected package manager, Python, Go, Rust. No gates detected → the hook falls back to its original advisory text (manual verification guidance), unchanged.
+- **Evidence stamp**: a passing run writes `{epoch, tree-hash}` to `.claude/hooks/.state/commit-verified` — hook-authored only; nothing in this hook's own output ever instructs the agent to write it by hand. A later commit trusts the stamp only if it's BOTH ≤5 minutes old AND its recorded tree-hash matches the current `git write-tree` output — content-bound, not just time-bound, so staging an edit a second ago invalidates a minute-old stamp.
+- **On failure**: denies the commit, naming the failing gate and its log (`.claude/hooks/.state/gate-<label>.log`), plus a fixed reminder never to delete or weaken a test to force a pass.
+- **On timeout**: each gate runs under `timeout "${CLAUDE_GATE_TIMEOUT_SECS:-120}"` (default 120s per gate; set the env var to override). The hook's own registration in `settings.json` is 300s, leaving headroom above the per-gate default so ordinary (non-commit) Bash calls still return instantly via the hook's early exits. A gate that exceeds its budget produces an `ask`, never a silent kill or an indefinite hang — and no stamp is written.
+- **Escape hatch**: `CLAUDE_SKIP_GATE_HOOK=1` allows the commit unconditionally; the skip is always disclosed in the hook's own `additionalContext`, never silent.
+- **jq-absent**: identical to every other hook in this repo — silent exit 0, no gates run, no advisory shown (the repo's fail-open convention, see Security model below). Broader jq-availability degradation visibility is a session-level concern (`session-start-loader.sh`), not something this specific hook re-announces per commit.
+
 ### Push Blocking (pre-push-main-blocker.sh)
 
 Enforces trunk-based development by blocking pushes to main/master:
diff --git a/scripts/fixtures/failing-project/package-lock.json b/scripts/fixtures/failing-project/package-lock.json
new file mode 100644
index 0000000..e69de29
diff --git a/scripts/fixtures/passing-project/package-lock.json b/scripts/fixtures/passing-project/package-lock.json
new file mode 100644
index 0000000..e69de29
diff --git a/scripts/fixtures/passing-project/package.json b/scripts/fixtures/passing-project/package.json
new file mode 100644
index 0000000..f1e73a5
--- /dev/null
+++ b/scripts/fixtures/passing-project/package.json
@@ -0,0 +1,9 @@
+{
+  "name": "passing-project-fixture",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Dependency-free fixture for hook-behavior tests: a project whose test script always succeeds (no npm install needed) — exercises the pre-commit gate's green path and hook-authored evidence-stamp write (unit U5b). Sibling of failing-project (red path) and slow-gate (timeout path).",
+  "scripts": {
+    "test": "node -e \"process.exit(0)\""
+  }
+}
diff --git a/scripts/fixtures/slow-gate/package-lock.json b/scripts/fixtures/slow-gate/package-lock.json
new file mode 100644
index 0000000..e69de29
diff --git a/scripts/fixtures/slow-gate/package.json b/scripts/fixtures/slow-gate/package.json
new file mode 100644
index 0000000..c3b2962
--- /dev/null
+++ b/scripts/fixtures/slow-gate/package.json
@@ -0,0 +1,9 @@
+{
+  "name": "slow-gate-fixture",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Fixture whose test script shells out to gate.sh, which sleeps past a deliberately short per-gate timeout — exercises the pre-commit gate's honest 'ask' path on timeout, never a silent kill or hang (unit U5b). See gate.sh for the sleep itself.",
+  "scripts": {
+    "test": "bash gate.sh"
+  }
+}
diff --git a/scripts/hook-tests.d/30-gates-lane.sh b/scripts/hook-tests.d/30-gates-lane.sh
new file mode 100644
index 0000000..8205b29
--- /dev/null
+++ b/scripts/hook-tests.d/30-gates-lane.sh
@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+# scripts/hook-tests.d/30-gates-lane.sh — PR4 gates-enforce lane: unit U5b of
+# artifacts/plan_framework_hardening.md (commit-gate enforcement, content-bound
+# evidence stamp, per-gate timeout, escape hatch). Extends the harness per its
+# own open/closed contract (a new numbered file, never edits to
+# scripts/test-hooks.sh or the other lane files), so this lane stays
+# independently mergeable. Reuses 00-baseline.sh's `_fresh_dir` helper (sourced
+# before this file, so already in scope) and the runner's `run_case`/`report`.
+#
+# Hermeticity: every case below gets its OWN fresh directory and never
+# operates on the checked-in scripts/fixtures/* trees directly — see
+# 10-hooks-lane.sh's u2_clean_remote comment for why sharing mutable git
+# state across cases makes results order-dependent.
+#
+# Fixture note: scripts/fixtures/failing-project/, .../slow-gate/, and the new
+# .../passing-project/ (added here, sibling of failing-project) each ship an
+# EMPTY package-lock.json alongside their package.json. Verified directly via
+# gate_lib_detect: without a lockfile it picks pnpm ("test(pnpm)" / "pnpm
+# test"); GitHub-hosted ubuntu-latest runners ship node+npm but not pnpm, so
+# an npm-selecting lockfile keeps every case below deterministic in CI instead
+# of only on a dev machine that happens to have pnpm installed.
+
+# --- shared setup: a git repo from a fixture's files, staged, no commit yet
+# (the hook intercepts `git commit` BEFORE it runs, so a staged-but-uncommitted
+# index is the realistic state to test against) ------------------------------
+_gate_fixture_repo() { # $1=fixture dir (repo-root-relative) -> prints fresh repo path
+    local src="$1" dir
+    dir=$(_fresh_dir)
+    cp "$src"/* "$dir/" 2>/dev/null
+    git -C "$dir" init -q >/dev/null 2>&1
+    git -C "$dir" add -A >/dev/null 2>&1
+    printf '%s' "$dir"
+}
+
+_gate_commit_json='{"tool_name":"Bash","tool_input":{"command":"git commit -m wip"}}'
+
+# ============================================================================
+# failing-project fixture: red gate -> deny, naming the gate + log + the
+# fixed anti-test-deletion sentence
+# ============================================================================
+u5b_fail_dir=$(_gate_fixture_repo scripts/fixtures/failing-project)
+
+run_case \
+  "pre-commit-verification: failing-project fixture denies the commit" \
+  ".claude/hooks/pre-commit-verification.sh" \
+  "$_gate_commit_json" \
+  "CLAUDE_PROJECT_DIR=$u5b_fail_dir" \
+  "deny-json"
+
+run_case \
+  "pre-commit-verification: deny reason names the failing gate label" \
+  ".claude/hooks/pre-commit-verification.sh" \
+  "$_gate_commit_json" \
+  "CLAUDE_PROJECT_DIR=$u5b_fail_dir" \
+  "stdout-contains:test(npm)"
+
+run_case \
+  "pre-commit-verification: deny reason names the gate's log path" \
+  ".claude/hooks/pre-commit-verification.sh" \
+  "$_gate_commit_json" \
+  "CLAUDE_PROJECT_DIR=$u5b_fail_dir" \
+  "stdout-contains:$u5b_fail_dir/.claude/hooks/.state/gate-test(npm).log"
+
+run_case \
+  "pre-commit-verification: deny reason includes the exact anti-test-deletion sentence" \
+  ".claude/hooks/pre-commit-verification.sh" \
+  "$_gate_commit_json" \
+  "CLAUDE_PROJECT_DIR=$u5b_fail_dir" \
+  "stdout-contains:Do not delete or weaken tests to force a pass — fix the issue or ask the user."
+
+# --- escape hatch on the same (still-failing) fixture: allow, disclosed ----
+run_case \
+  "pre-commit-verification: CLAUDE_SKIP_GATE_HOOK=1 allows even a failing gate" \
+  ".claude/hooks/pre-commit-verification.sh" \
+  "$_gate_commit_json" \
+  "CLAUDE_PROJECT_DIR=$u5b_fail_dir CLAUDE_SKIP_GATE_HOOK=1" \
+  "stdout-contains:GATE HOOK SKIPPED"
+
+run_case \
+  "pre-commit-verification: escape hatch disclosure names the env var" \
+  ".claude/hooks/pre-commit-verification.sh" \
+  "$_gate_commit_json" \
+  "CLAUDE_PROJECT_DIR=$u5b_fail_dir CLAUDE_SKIP_GATE_HOOK=1" \
+  "stdout-contains:CLAUDE_SKIP_GATE_HOOK=1"
+
+# ============================================================================
+# passing-project fixture: green gate -> silent allow, hook-authored stamp
+# content-bound to the current index; a later staged change forces a re-run
+# even though the stamp is still well within the 5-minute freshness window
+# ============================================================================
+u5b_pass_dir=$(_gate_fixture_repo scripts/fixtures/passing-project)
+u5b_pass_stamp="$u5b_pass_dir/.claude/hooks/.state/commit-verified"
+u5b_tree_1=$(git -C "$u5b_pass_dir" write-tree 2>/dev/null)
+
+run_case \
+  "pre-commit-verification: passing-project fixture allows silently" \
+  ".claude/hooks/pre-commit-verification.sh" \
+  "$_gate_commit_json" \
+  "CLAUDE_PROJECT_DIR=$u5b_pass_dir" \
+  "exit0-silent"
+
+u5b_stamp_epoch_1="" u5b_stamp_tree_1=""
+if [ -f "$u5b_pass_stamp" ]; then
+    read -r u5b_stamp_epoch_1 u5b_stamp_tree_1 < "$u5b_pass_stamp" 2>/dev/null || true
+fi
+report \
+  "pre-commit-verification: passing-project writes a hook-authored stamp bound to the current write-tree hash" \
+  "$([ -n "$u5b_stamp_tree_1" ] && [ "$u5b_stamp_tree_1" = "$u5b_tree_1" ]; echo $?)" \
+  "stamp epoch=${u5b_stamp_epoch_1:-missing} tree=${u5b_stamp_tree_1:-missing} expected=${u5b_tree_1:-empty}"
+
+# --- unmodified re-run within the freshness window: cache hit, stamp mtime
+# (and content) must NOT change — proves the fast path is actually taken,
+# not just coincidentally also green -----------------------------------------
+u5b_stamp_mtime_before=$(stat -f '%m' "$u5b_pass_stamp" 2>/dev/null || stat -c '%Y' "$u5b_pass_stamp" 2>/dev/null)
+
+run_case \
+  "pre-commit-verification: unmodified re-run within 5 min allows silently (cache hit)" \
+  ".claude/hooks/pre-commit-verification.sh" \
+  "$_gate_commit_json" \
+  "CLAUDE_PROJECT_DIR=$u5b_pass_dir" \
+  "exit0-silent"
+
+u5b_stamp_mtime_after=$(stat -f '%m' "$u5b_pass_stamp" 2>/dev/null || stat -c '%Y' "$u5b_pass_stamp" 2>/dev/null)
+report \
+  "pre-commit-verification: unmodified re-run does not rewrite the stamp (true cache hit, not a coincidental re-pass)" \
+  "$([ "$u5b_stamp_mtime_before" = "$u5b_stamp_mtime_after" ]; echo $?)" \
+  "mtime before=$u5b_stamp_mtime_before after=$u5b_stamp_mtime_after"
+
+# --- modify + re-stage a TRACKED file: tree-hash changes even though the
+# stamp is still fresh by time alone -> must force a real re-run, not ride
+# the stale-but-recent timestamp ---------------------------------------------
+printf '{}' > "$u5b_pass_dir/package-lock.json"
+git -C "$u5b_pass_dir" add -A >/dev/null 2>&1
+u5b_tree_2=$(git -C "$u5b_pass_dir" write-tree 2>/dev/null)
+
+run_case \
+  "pre-commit-verification: re-run after staging a change still allows (gate re-ran and passed again)" \
+  ".claude/hooks/pre-commit-verification.sh" \
+  "$_gate_commit_json" \
+  "CLAUDE_PROJECT_DIR=$u5b_pass_dir" \
+  "exit0-silent"
+
+u5b_stamp_epoch_2="" u5b_stamp_tree_2=""
+if [ -f "$u5b_pass_stamp" ]; then
+    read -r u5b_stamp_epoch_2 u5b_stamp_tree_2 < "$u5b_pass_stamp" 2>/dev/null || true
+fi
+report \
+  "pre-commit-verification: a staged tree-hash change forces a fresh re-run despite an otherwise-fresh stamp (tree mismatch, not cached-allow)" \
+  "$([ "$u5b_stamp_tree_2" = "$u5b_tree_2" ] && [ "$u5b_stamp_tree_2" != "$u5b_tree_1" ]; echo $?)" \
+  "stamp epoch=${u5b_stamp_epoch_2:-missing} tree after re-run=${u5b_stamp_tree_2:-missing}, new tree=${u5b_tree_2:-empty}, old tree=${u5b_tree_1:-empty}"
+
+# ============================================================================
+# slow-gate fixture: a gate that outlives its budget -> an honest ask, never
+# a silent kill or an indefinite hang, and no stamp is written
+# ============================================================================
+u5b_slow_dir=$(_gate_fixture_repo scripts/fixtures/slow-gate)
+u5b_slow_stamp="$u5b_slow_dir/.claude/hooks/.state/commit-verified"
+
+run_case \
+  "pre-commit-verification: slow-gate fixture asks rather than silently killing or hanging" \
+  ".claude/hooks/pre-commit-verification.sh" \
+  "$_gate_commit_json" \
+  "CLAUDE_PROJECT_DIR=$u5b_slow_dir CLAUDE_GATE_TIMEOUT_SECS=2" \
+  "ask-json"
+
+report \
+  "pre-commit-verification: a timed-out gate does not write an evidence stamp" \
+  "$([ ! -f "$u5b_slow_stamp" ]; echo $?)" \
+  "stamp unexpectedly present at $u5b_slow_stamp"

From 6ec2dbca6399855f763eb76707ba39e97e837080 Mon Sep 17 00:00:00 2001
From: Jordan Winters <dralgorhythm@users.noreply.github.com>
Date: Fri, 24 Jul 2026 11:52:40 -0500
Subject: [PATCH 2/2] fix(hooks): portable per-gate timeout
 (timeout/gtimeout/unbounded fallback)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Stock macOS ships no GNU timeout — unguarded, every gate run would exit
127 and deny all commits. Resolve timeout|gtimeout once; degrade to
unbounded-within-hook-ceiling when neither exists, documented.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .claude/hooks/pre-commit-verification.sh | 12 +++++++++++-
 docs/hooks.md                            |  1 +
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/.claude/hooks/pre-commit-verification.sh b/.claude/hooks/pre-commit-verification.sh
index 7de0327..80b3425 100755
--- a/.claude/hooks/pre-commit-verification.sh
+++ b/.claude/hooks/pre-commit-verification.sh
@@ -128,7 +128,13 @@ fi
 # Gates detected: run each one under its own timeout, from PROJECT_DIR,
 # logging to its own file. Fail-fast on the first red or timed-out gate —
 # the reason names exactly one gate, matching the plan's fixtures.
+# `timeout` is GNU coreutils: present on Linux/CI, absent on stock macOS
+# (Homebrew installs it as `gtimeout`). Without either, gates run unbounded
+# inside the hook's own settings.json ceiling — bounded worse, never broken.
 GATE_TIMEOUT="${CLAUDE_GATE_TIMEOUT_SECS:-120}"
+if command -v timeout >/dev/null 2>&1; then TIMEOUT_BIN="timeout"
+elif command -v gtimeout >/dev/null 2>&1; then TIMEOUT_BIN="gtimeout"
+else TIMEOUT_BIN=""; fi
 FAILED_LABEL=""
 FAILED_LOG=""
 TIMED_OUT_LABEL=""
@@ -137,7 +143,11 @@ for _gate_i in "${!GATE_LABELS[@]}"; do
     _gate_label="${GATE_LABELS[$_gate_i]}"
     _gate_cmd="${GATE_COMMANDS[$_gate_i]}"
     _gate_log="$STATE_DIR/gate-${_gate_label//\//_}.log"
-    ( cd "$PROJECT_DIR" && timeout "$GATE_TIMEOUT" bash -c "$_gate_cmd" </dev/null ) >"$_gate_log" 2>&1
+    if [ -n "$TIMEOUT_BIN" ]; then
+        ( cd "$PROJECT_DIR" && "$TIMEOUT_BIN" "$GATE_TIMEOUT" bash -c "$_gate_cmd" </dev/null ) >"$_gate_log" 2>&1
+    else
+        ( cd "$PROJECT_DIR" && bash -c "$_gate_cmd" </dev/null ) >"$_gate_log" 2>&1
+    fi
     _gate_rc=$?
     if [ "$_gate_rc" -eq 124 ]; then
         TIMED_OUT_LABEL="$_gate_label"
diff --git a/docs/hooks.md b/docs/hooks.md
index 23dd74b..3d73f1e 100644
--- a/docs/hooks.md
+++ b/docs/hooks.md
@@ -67,6 +67,7 @@ Runs the project's detected quality gates before every `git commit` and blocks t
 - **Evidence stamp**: a passing run writes `{epoch, tree-hash}` to `.claude/hooks/.state/commit-verified` — hook-authored only; nothing in this hook's own output ever instructs the agent to write it by hand. A later commit trusts the stamp only if it's BOTH ≤5 minutes old AND its recorded tree-hash matches the current `git write-tree` output — content-bound, not just time-bound, so staging an edit a second ago invalidates a minute-old stamp.
 - **On failure**: denies the commit, naming the failing gate and its log (`.claude/hooks/.state/gate-<label>.log`), plus a fixed reminder never to delete or weaken a test to force a pass.
 - **On timeout**: each gate runs under `timeout "${CLAUDE_GATE_TIMEOUT_SECS:-120}"` (default 120s per gate; set the env var to override). The hook's own registration in `settings.json` is 300s, leaving headroom above the per-gate default so ordinary (non-commit) Bash calls still return instantly via the hook's early exits. A gate that exceeds its budget produces an `ask`, never a silent kill or an indefinite hang — and no stamp is written.
+On stock macOS, GNU `timeout` is absent — the hook falls back to `gtimeout` (Homebrew coreutils) or, failing both, runs gates unbounded within its own settings.json timeout ceiling; install coreutils to restore per-gate bounding.
 - **Escape hatch**: `CLAUDE_SKIP_GATE_HOOK=1` allows the commit unconditionally; the skip is always disclosed in the hook's own `additionalContext`, never silent.
 - **jq-absent**: identical to every other hook in this repo — silent exit 0, no gates run, no advisory shown (the repo's fail-open convention, see Security model below). Broader jq-availability degradation visibility is a session-level concern (`session-start-loader.sh`), not something this specific hook re-announces per commit.