@thebassclef/lite 0.0.1 → 0.1.2

package/substrate/.claude/hooks/pre-commit-gate.sh

@@ -0,0 +1,451 @@
+#!/bin/bash
+# tier: lite
+# install-class: project
+set -e
+
+# Observable failure trap — closes bassclef-upstream#1075 (silent-stderr class).
+# Under `set -e`, any command failure exits the shell without printing.
+# The harness reports "No stderr output" and the agent cannot self-diagnose.
+# This trap emits filename + line + exit code + failing command to stderr
+# BEFORE the shell exits, so the failure is observable.
+# Per .claude/rules/defensive-bash.md discipline 4 (extended for observable failure).
+trap '_ec=$?; if [ "$_ec" -ne 0 ]; then echo "pre-commit-gate.sh: FAIL at line $LINENO: exit $_ec (command: $BASH_COMMAND)" >&2; fi' ERR
+
+# Pre-Commit Gate — fires on Bash PreToolUse for git commit commands.
+# Requires visible verification evidence before committing.
+# Checks: feature branch, source files without tests, UI usability.
+
+INPUT=$(cat)
+# Malformed JSON → jq exits non-zero; fail-soft to empty COMMAND so the
+# next branch (non-commit skip) fires. Hardened under WU-2a per
+# bassclef#1101 + bassclef#1098 sufficiency rubric criterion 6
+# (stdin contract). Previously crashed harness commit calls on malformed
+# stdin (exit 5 from jq).
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""' 2>/dev/null || echo "")
+
+# Only fire on git commit commands
+if ! echo "$COMMAND" | grep -q 'git commit'; then
+  exit 0
+fi
+
+# Trace log
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/trace-helper.sh"
+trace_log "pre-commit" "git commit"
+
+# --- CCF-3 operator-path guard (bassclef#740) ---
+# Reject commits adding absolute paths matching /Users/<name> or /home/<name>
+# in non-exempt locations. Operator-specific paths must live in
+# .claude/settings.local.json (gitignored), not in shared substrate.
+# Per handoff spec from 2026-05-23 cold-adopter run (PR #735, F70).
+# Exempt: rules/hooks/skills/standards/docs/strategy/chronicle/scripts/tests
+# (places where the policy itself is documented or test fixtures live).
+# Override: SKIP_OPERATOR_PATHS=1 git commit  (logged via trace-helper)
+if [ "${SKIP_OPERATOR_PATHS:-0}" != "1" ]; then
+  STAGED_NONEXEMPT=$(git diff --cached --name-only --diff-filter=AM 2>/dev/null | \
+    grep -vE '^\.claude/(rules|hooks|skills|luminaries|agents)/' | \
+    grep -vE '^standards/' | \
+    grep -vE '^architecture/' | \
+    grep -vE '^design/' | \
+    grep -vE '^docs/' | \
+    grep -vE '^chronicle/' | \
+    grep -vE '^strategy/' | \
+    grep -vE '^scripts/tests/' || true)
+  if [ -n "$STAGED_NONEXEMPT" ]; then
+    LEAKED=""
+    while IFS= read -r f; do
+      [ -z "$f" ] && continue
+      [ ! -f "$f" ] && continue
+      MATCHES=$(grep -nE '/Users/[A-Za-z0-9_.-]+|/home/[A-Za-z0-9_.-]+' "$f" 2>/dev/null || true)
+      if [ -n "$MATCHES" ]; then
+        LEAKED="${LEAKED}
+  ${f}:
+${MATCHES}
+"
+      fi
+    done <<< "$STAGED_NONEXEMPT"
+    if [ -n "$LEAKED" ]; then
+      # Wrapped in { ...; } >&2 per bassclef-upstream#1229 cure so BLOCK
+      # message reaches the agent via Claude Code's PreToolUse error path.
+      # Matches sibling scrub-hook convention (pre-gh-pseudonym-scrub.sh
+      # L204-225, pre-gh-sibling-repo-scrub.sh L212-233).
+      {
+        echo ""
+        echo "============================================"
+        echo "BLOCKED: operator path in committed file (CCF-3)"
+        echo "============================================"
+        echo "$LEAKED"
+        echo ""
+        echo "Operator-specific paths (/Users/<name>, /home/<name>) must NOT ship"
+        echo "in shared substrate. Move to .claude/settings.local.json (gitignored)."
+        echo "Policy: standards/two-layer-config.md (bassclef#740)"
+        echo ""
+        echo "Override: SKIP_OPERATOR_PATHS=1 git commit  (logged, use sparingly)"
+        echo "Silence is not deferral — see .claude/rules/blocked-items.md"
+        echo "============================================"
+      } >&2
+      exit 2
+    fi
+  fi
+fi
+
+# --- Testing-tier enforcement (bassclef#1037) ---
+# Per-path tier check: Tier 0 BLOCKs when sibling test mtime did not advance
+# with the source. Tier 1 WARNs. Tier 2/3 silent. Allowlist grace baseline
+# at .claude/hooks/testing-tier-enforce-allowlist.txt covers existing untested
+# bassclef surfaces for 60d. Override: SKIP_TESTING_TIER_ENFORCE=1.
+if [ -x "$SCRIPT_DIR/testing-tier-enforce.sh" ]; then
+  if ! "$SCRIPT_DIR/testing-tier-enforce.sh"; then
+    # Hook BLOCKed with structured stderr message. Propagate exit.
+    exit 1
+  fi
+fi
+
+# --- Cold-adopter harness fast-path (bassclef-upstream#350, bet 25h WU-2) ---
+# When staged changes touch substrate-affecting paths per
+# .claude/rules/cold-adopter-harness-discipline.md § "When this rule fires",
+# run the cold-adopter harness in fast mode (structural-only) to catch
+# adopter-observable regressions at commit time. The PR-CI job (bet 25g WU-2)
+# remains the required PR-time enforcement; this hook is the operator-side
+# fast-fail layer per Saltzer-Schroeder complete mediation.
+#
+# Override: SKIP_COLD_ADOPTER_HARNESS=1 git commit (logged via trace-helper)
+if [ "${SKIP_COLD_ADOPTER_HARNESS:-0}" != "1" ]; then
+  # The 12-pattern matcher mirrors .claude/rules/cold-adopter-harness-discipline.md
+  # § "When this rule fires". Keep these patterns in sync; a future WU may
+  # centralize the list via a sourced library function.
+  STAGED_SUBSTRATE=$(git diff --cached --name-only --diff-filter=AM 2>/dev/null | grep -E \
+    -e '^\.claude/hooks/[^/]+\.sh$' \
+    -e '^\.claude/skills/[^/]+/SKILL\.md$' \
+    -e '^\.claude/rules/[^/]+\.md$' \
+    -e '^\.claude/agents/[^/]+\.md$' \
+    -e '^\.claude/luminaries/[^/]+\.md$' \
+    -e '^lib/[^/]+\.sh$' \
+    -e '^standards/[^/]+\.md$' \
+    -e '^standards/state-spine/schemas/[^/]+\.json$' \
+    -e '^presence/install/bassclef-sync\..*\.sh$' \
+    -e '^architecture/decisions/ADR-.*\.md$' \
+    -e '^\.github/workflows/bassclef-.*\.yml$' \
+    -e '^scripts/[^/]+\.sh$' \
+    || true)
+  if [ -n "$STAGED_SUBSTRATE" ]; then
+    # Default to scripts/cold-adopter-harness-sync.sh relative to this hook's
+    # location; tests override via BASSCLEF_HARNESS_PATH env var.
+    HARNESS_PATH="${BASSCLEF_HARNESS_PATH:-$SCRIPT_DIR/../../scripts/cold-adopter-harness-sync.sh}"
+    if [ -x "$HARNESS_PATH" ]; then
+      trace_log "pre-commit" "cold-adopter harness fast-path firing"
+      HARNESS_RC=0
+      bash "$HARNESS_PATH" --mode structural --target . >/dev/null 2>&1 || HARNESS_RC=$?
+      if [ "$HARNESS_RC" != "0" ]; then
+        # Wrapped in { ...; } >&2 per bassclef-upstream#1229 cure so BLOCK
+        # message reaches the agent via Claude Code's PreToolUse error path.
+        {
+          echo ""
+          echo "============================================"
+          echo "BLOCKED: cold-adopter harness fast-path"
+          echo "============================================"
+          echo "Substrate-affecting paths staged:"
+          echo "$STAGED_SUBSTRATE" | sed 's/^/   /'
+          echo ""
+          echo "Cold-adopter harness exited with code $HARNESS_RC."
+          echo ""
+          echo "Run for diagnostic output:"
+          echo "   bash scripts/cold-adopter-harness-sync.sh --mode structural --target ."
+          echo ""
+          echo "Override (logged via trace-helper):"
+          echo "   SKIP_COLD_ADOPTER_HARNESS=1 git commit"
+          echo ""
+          echo "Discipline: .claude/rules/cold-adopter-harness-discipline.md"
+          echo "Standard:   \`standards/cold-adopter-harness.md\` (standard tier)"
+          echo "Silence is not deferral (see .claude/rules/blocked-items.md)."
+          echo "============================================"
+        } >&2
+        exit 2
+      fi
+    fi
+  fi
+fi
+
+# --- Lead-lens sign-off 3-marker gate (bet 24a Step 2b; closes #836) ---
+# Substrate-affecting paths staged? Require three markers before commit:
+#   state/markers/pre-mortem/<branch-slug>.marker
+#   state/markers/luminary/<branch-slug>.marker (with 'lead:' field)
+#   state/markers/lead-lens-signoff/<branch-slug>.marker
+# Discipline lives in .claude/rules/loop-discipline.md Step 0.5 + 2a + 5.5.
+# Override: SKIP_LEAD_LENS_SIGNOFF=1 git commit (logged via trace-helper)
+if [ "${SKIP_LEAD_LENS_SIGNOFF:-0}" != "1" ]; then
+  # Reuse the substrate-affecting matcher shape from cold-adopter fast-path.
+  STAGED_SUBSTRATE_LL=$(git diff --cached --name-only --diff-filter=AM 2>/dev/null | grep -E \
+    -e '^\.claude/hooks/[^/]+\.sh$' \
+    -e '^\.claude/skills/[^/]+/SKILL\.md$' \
+    -e '^\.claude/rules/[^/]+\.md$' \
+    -e '^\.claude/agents/[^/]+\.md$' \
+    -e '^\.claude/luminaries/[^/]+\.md$' \
+    -e '^lib/[^/]+\.sh$' \
+    -e '^standards/[^/]+\.md$' \
+    -e '^standards/state-spine/schemas/[^/]+\.json$' \
+    -e '^presence/install/bassclef-sync\..*\.sh$' \
+    -e '^architecture/decisions/ADR-.*\.md$' \
+    -e '^\.github/workflows/bassclef-.*\.yml$' \
+    -e '^scripts/[^/]+\.sh$' \
+    || true)
+  if [ -n "$STAGED_SUBSTRATE_LL" ]; then
+    LL_BRANCH_SLUG=$(git branch --show-current 2>/dev/null | tr '/' '-')
+    PREM_M="state/markers/pre-mortem/${LL_BRANCH_SLUG}.marker"
+    LUM_M="state/markers/luminary/${LL_BRANCH_SLUG}.marker"
+    SIGN_M="state/markers/lead-lens-signoff/${LL_BRANCH_SLUG}.marker"
+
+    LL_MISSING=""
+    if [ ! -f "$PREM_M" ]; then
+      LL_MISSING="${LL_MISSING}  - pre-mortem marker missing at $PREM_M\n"
+    fi
+    if [ ! -f "$LUM_M" ]; then
+      LL_MISSING="${LL_MISSING}  - luminary marker missing at $LUM_M\n"
+    elif ! grep -qE '^[[:space:]]*-[[:space:]]*lead[^a-zA-Z0-9_]' "$LUM_M"; then
+      # Accept: "- lead:", "- lead (goal-level):", "- lead luminary:", "- lead-luminary:"
+      # Reject: "- leader:" (word-boundary check), "- date:", any line without "lead" after dash
+      LL_MISSING="${LL_MISSING}  - luminary marker at $LUM_M missing lead field (expected line starting with dash lead followed by colon or modifier)\n"
+    fi
+    if [ ! -f "$SIGN_M" ]; then
+      LL_MISSING="${LL_MISSING}  - lead-lens sign-off marker missing at $SIGN_M\n"
+    fi
+
+    if [ -n "$LL_MISSING" ]; then
+      trace_log "pre-commit" "lead-lens 3-marker gate BLOCKED"
+      # Wrapped in { ...; } >&2 per bassclef-upstream#1229 cure so BLOCK
+      # message reaches the agent via Claude Code's PreToolUse error path.
+      # Prior to cure: this exact block fired 3 times in ~1 week (08-12a,
+      # 08-12d, 08-15c); agent saw "No stderr output" and bypassed via
+      # python subprocess, masking the actual discipline miss.
+      {
+        echo ""
+        echo "============================================"
+        echo "BLOCKED: lead-lens sign-off 3-marker gate (bet 24a / #836)"
+        echo "============================================"
+        echo "Substrate-affecting paths staged:"
+        echo "$STAGED_SUBSTRATE_LL" | sed 's/^/   /'
+        echo ""
+        echo "Missing:"
+        echo -e "$LL_MISSING"
+        echo "Discipline: .claude/rules/loop-discipline.md Step 0.5 + Step 2a + Step 5.5"
+        echo ""
+        echo "Cure — touch each missing marker with body content per marker-enrichment-discipline:"
+        echo "   mkdir -p state/markers/pre-mortem state/markers/luminary state/markers/lead-lens-signoff"
+        echo "   # write body content per rule Step 0.5 + 2a + 5.5"
+        echo ""
+        echo "Override (logged via trace-helper):"
+        echo "   SKIP_LEAD_LENS_SIGNOFF=1 git commit"
+        echo ""
+        echo "Silence is not deferral — see .claude/rules/blocked-items.md"
+        echo "============================================"
+      } >&2
+      exit 2
+    fi
+  fi
+fi
+
+# --- Feature branch enforcement ---
+CURRENT_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+WARNINGS=""
+if [ "$CURRENT_BRANCH" = "main" ] || [ "$CURRENT_BRANCH" = "master" ]; then
+  WARNINGS="${WARNINGS}COMMITTING DIRECTLY TO MAIN — use a feature branch and PR instead.\n"
+fi
+
+# --- Check staged source files for matching test files ---
+STAGED_SOURCE_FILES=$(git diff --cached --name-only --diff-filter=AM -- 'src/lib/*.ts' 'src/agents/*.ts' 'src/app/api/**/*.ts' 2>/dev/null || true)
+if [ -n "$STAGED_SOURCE_FILES" ]; then
+  while IFS= read -r srcfile; do
+    basename=$(basename "$srcfile" .ts)
+    case "$basename" in
+      prisma|redis|queue|auth|langfuse|secrets|index) continue ;;
+    esac
+    if echo "$srcfile" | grep -q 'src/app/api/'; then
+      if [ ! -f "src/__tests__/api-routes.test.ts" ] && [ ! -f "src/__tests__/${basename}.test.ts" ]; then
+        WARNINGS="${WARNINGS}API ROUTE WITHOUT TEST: ${srcfile}\n"
+      fi
+    elif [ ! -f "src/__tests__/${basename}.test.ts" ]; then
+      WARNINGS="${WARNINGS}SOURCE FILE WITHOUT TEST: ${srcfile} → expected src/__tests__/${basename}.test.ts\n"
+    fi
+  done <<< "$STAGED_SOURCE_FILES"
+fi
+
+# --- /verify evidence check (MUST gate) ---
+# Emit BLOCKED: /verify when source files are staged without verify evidence.
+# Checks both /tmp (desktop) and state/markers/verify/ (ephemeral-safe).
+# Per bassclef#342: markers relocated from .claude/verify-markers/ to
+# state/markers/verify/ (rulebook-vs-log drawer separation).
+# blocked-items.md rule requires resolve-or-explicit-defer.
+STAGED_SOURCE=$(git diff --cached --name-only --diff-filter=AM -- 'src/**/*.ts' 'src/**/*.tsx' 'src/**/*.js' 'scripts/**/*.ts' 2>/dev/null | head -5)
+if [ -n "$STAGED_SOURCE" ]; then
+  BRANCH_SLUG=$(git branch --show-current 2>/dev/null | tr '/' '-')
+  VERIFY_MARKER_TMP="/tmp/claude-verify-${BRANCH_SLUG}"
+  VERIFY_MARKER_GIT="state/markers/verify/${BRANCH_SLUG}.marker"
+  VERIFY_RECENT=0
+  NOW=$(date +%s)
+
+  # Check desktop marker
+  if [ -f "$VERIFY_MARKER_TMP" ]; then
+    AGE=$(( NOW - $(stat -f %m "$VERIFY_MARKER_TMP" 2>/dev/null || stat -c %Y "$VERIFY_MARKER_TMP" 2>/dev/null || echo 0) ))
+    [ "$AGE" -lt 300 ] && VERIFY_RECENT=1
+  fi
+
+  # Check ephemeral-safe (git-tracked) marker
+  if [ "$VERIFY_RECENT" -eq 0 ] && [ -f "$VERIFY_MARKER_GIT" ]; then
+    AGE=$(( NOW - $(stat -f %m "$VERIFY_MARKER_GIT" 2>/dev/null || stat -c %Y "$VERIFY_MARKER_GIT" 2>/dev/null || echo 0) ))
+    [ "$AGE" -lt 300 ] && VERIFY_RECENT=1
+  fi
+
+  if [ "$VERIFY_RECENT" -eq 0 ]; then
+    WARNINGS="${WARNINGS}BLOCKED: /verify — source files staged without recent verify evidence.\n"
+    WARNINGS="${WARNINGS}   Run /verify BEFORE committing, or explicitly defer with rationale.\n"
+    WARNINGS="${WARNINGS}   Silence is not deferral (see .claude/rules/blocked-items.md).\n"
+    WARNINGS="${WARNINGS}   Checked: $VERIFY_MARKER_TMP and $VERIFY_MARKER_GIT (5-min freshness).\n"
+  fi
+fi
+
+# --- Reserved skill names check (collision with Claude Code built-ins) ---
+# See .claude/rules/reserved-skill-names.md + standards/reserved-skill-names.md
+if [ "${SKIP_RESERVED_NAMES:-0}" != "1" ]; then
+  STAGED_NEW_SKILLS=$(git diff --cached --name-only --diff-filter=A -- '.claude/skills/*/SKILL.md' 2>/dev/null || true)
+  if [ -n "$STAGED_NEW_SKILLS" ]; then
+    # Extract reserved names from the standards table (Name column values inside backticks)
+    RESERVED_LIST=""
+    if [ -f "standards/reserved-skill-names.md" ]; then
+      RESERVED_LIST=$(grep -oE '`[a-z][a-z0-9-]+`' standards/reserved-skill-names.md | tr -d '`' | sort -u)
+    fi
+    if [ -n "$RESERVED_LIST" ]; then
+      while IFS= read -r skill_path; do
+        skill_name=$(echo "$skill_path" | sed -n 's|\.claude/skills/\([^/]*\)/SKILL\.md|\1|p')
+        if [ -n "$skill_name" ] && echo "$RESERVED_LIST" | grep -qx "$skill_name"; then
+          WARNINGS="${WARNINGS}BLOCKED: reserved skill name — \`$skill_name\` collides with a Claude Code built-in.\n"
+          WARNINGS="${WARNINGS}   See standards/reserved-skill-names.md for the list.\n"
+          WARNINGS="${WARNINGS}   Rename the skill directory, OR override with SKIP_RESERVED_NAMES=1 git commit.\n"
+          WARNINGS="${WARNINGS}   Silence is not deferral (see .claude/rules/blocked-items.md).\n"
+        fi
+      done <<< "$STAGED_NEW_SKILLS"
+    fi
+  fi
+fi
+
+# --- Bassclef evolution check: methodology/config changes being committed ---
+# Catches .claude/ changes AND settings/config changes that may be global
+STAGED_CLAUDE=$(git diff --cached --name-only -- '.claude/skills/*' '.claude/rules/*' '.claude/hooks/*' '.claude/agents/*' 2>/dev/null | grep -v 'SESSION_LOCK\|LAST_SAVE' | head -5)
+STAGED_CONFIG=$(git diff --cached --name-only -- 'settings.json' '.claude/settings.json' '*/settings.json' 'package.json' '.eslintrc*' 'tsconfig*.json' '.prettierrc*' '.env.example' 2>/dev/null | head -5)
+
+if [ -n "$STAGED_CLAUDE" ] || [ -n "$STAGED_CONFIG" ]; then
+  ALL_METHOD_FILES="${STAGED_CLAUDE}${STAGED_CONFIG}"
+  WARNINGS="${WARNINGS}BASSCLEF EVOLUTION CHECK — is this local or global?\n"
+  if [ -n "$STAGED_CLAUDE" ]; then
+    WARNINGS="${WARNINGS}   Substrate: $(echo "$STAGED_CLAUDE" | tr '\n' ', ')\n"
+  fi
+  if [ -n "$STAGED_CONFIG" ]; then
+    WARNINGS="${WARNINGS}   Config:    $(echo "$STAGED_CONFIG" | tr '\n' ', ')\n"
+  fi
+  WARNINGS="${WARNINGS}   If this applies to ANY project → run /promote before committing.\n"
+  WARNINGS="${WARNINGS}   If app-specific → proceed. If unsure → promote (cheaper to reject later).\n"
+fi
+
+# --- Chronicle Gate Evidence enforcement (MUST gate, bassclef#298) ---
+# Chronicles are the authoritative input for the 5-session gate-compliance
+# counter. A chronicle without "## Gate Evidence" reads as "no data" in the
+# counter, silencing the compliance signal (the failure mode that motivated
+# this gate). Block commits to chronicle/*.md or docs/chronicle/*.md that
+# lack the section. Override: SKIP_CHRONICLE_GATE_EVIDENCE=1 git commit.
+if [ "${SKIP_CHRONICLE_GATE_EVIDENCE:-0}" != "1" ]; then
+  STAGED_CHRONICLES=$(git diff --cached --name-only --diff-filter=AM -- 'chronicle/*.md' 'docs/chronicle/*.md' 2>/dev/null || true)
+  # Source spine accessor library when available — preferred frontmatter
+  # check route per state-spine-contract.md. Graceful fallback for repos
+  # pre-spine-v0.
+  if [ -f "lib/state.sh" ]; then
+    # shellcheck source=/dev/null
+    source "lib/state.sh" 2>/dev/null || true
+  fi
+  if [ -n "$STAGED_CHRONICLES" ]; then
+    while IFS= read -r chronicle_path; do
+      [ -z "$chronicle_path" ] && continue
+      [ ! -f "$chronicle_path" ] && continue
+      # Two acceptance paths (transitional during bassclef#298 schema rollout):
+      # 1. Frontmatter `gates_fired` populated (future-default; spine schema)
+      # 2. Markdown body section `## Gate Evidence` (legacy; current chronicles)
+      HAS_EVIDENCE=0
+      if command -v state_chronicle_gate_evidence >/dev/null 2>&1; then
+        chronicle_id=$(basename "$chronicle_path" .md)
+        gates_json=$(state_chronicle_gate_evidence "$chronicle_id" 2>/dev/null || echo "[]")
+        if [ -n "$gates_json" ] && [ "$gates_json" != "[]" ] && [ "$gates_json" != "null" ]; then
+          HAS_EVIDENCE=1
+        fi
+      fi
+      # Accept either "## Gate Evidence" or "## Gate evidence" (both forms exist historically)
+      if [ "$HAS_EVIDENCE" = "0" ] && grep -qiE "^## Gate (E|e)vidence" "$chronicle_path"; then
+        HAS_EVIDENCE=1
+      fi
+      if [ "$HAS_EVIDENCE" = "0" ]; then
+        WARNINGS="${WARNINGS}BLOCKED: chronicle missing Gate Evidence — \`${chronicle_path}\`\n"
+        WARNINGS="${WARNINGS}   Required: frontmatter \`gates_fired\` array OR \"## Gate Evidence\" body section.\n"
+        WARNINGS="${WARNINGS}   Template: templates/chronicle-template.md\n"
+        WARNINGS="${WARNINGS}   Standard: standards/sdlc-compliance.md §\"Gate Evidence Format\"\n"
+        WARNINGS="${WARNINGS}   Override: SKIP_CHRONICLE_GATE_EVIDENCE=1 git commit (logged).\n"
+        WARNINGS="${WARNINGS}   Silence is not deferral (see .claude/rules/blocked-items.md).\n"
+      fi
+    done <<< "$STAGED_CHRONICLES"
+  fi
+fi
+
+# --- UI visual review enforcement (MUST gate) ---
+STAGED_UI=$(git diff --cached --name-only -- 'src/app/**/page.tsx' 'src/components/**/*.tsx' '*.css' '*.scss' 2>/dev/null | head -5)
+if [ -n "$STAGED_UI" ]; then
+  # Check for visual review evidence
+  TODAY=$(date +%Y-%m-%d)
+  VISUAL_REVIEWS=$(git diff --cached --name-only -- 'docs/visual-reviews/*.md' 2>/dev/null || true)
+  RECENT_REVIEWS=$(find docs/visual-reviews/ -name "${TODAY}*" -type f 2>/dev/null | head -1)
+  if [ -z "$VISUAL_REVIEWS" ] && [ -z "$RECENT_REVIEWS" ]; then
+    WARNINGS="${WARNINGS}VISUAL REVIEW REQUIRED — UI change detected but no visual review report found.\n"
+    WARNINGS="${WARNINGS}   Run /visual-review on every page touched BEFORE committing.\n"
+    WARNINGS="${WARNINGS}   Report goes to: docs/visual-reviews/${TODAY}-{page-name}.md\n"
+    WARNINGS="${WARNINGS}   This is a MUST gate for UI changes. See /verify.\n"
+  fi
+  WARNINGS="${WARNINGS}UI CHANGE — usability checklist:\n"
+  WARNINGS="${WARNINGS}   Role check | Scanning distance | Jargon | Attribution | Accessibility\n"
+fi
+
+# --- Output warnings if any ---
+if [ -n "$WARNINGS" ]; then
+  echo ""
+  echo "============================================"
+  echo "TESTING CHECKS"
+  echo "============================================"
+  echo -e "$WARNINGS"
+  echo "These are WARNINGs — address before merging."
+  echo "============================================"
+  echo ""
+fi
+
+cat <<'GATE'
+============================================
+PRE-COMMIT GATE — MANDATORY BEFORE COMMITTING
+============================================
+
+STOP. Your response MUST contain a visible verification section.
+
+## Post-Build Verification (EACH task, not batched)
+- Change type: [which row applies]
+- Verification performed: [exact command(s) and output summary]
+- Tests: [file + count, or "no testable logic"]
+- Build: [passes / fails]
+- Result: [pass/fail — if fail, do not commit]
+
+| Change type                        | Minimum verification                              |
+|------------------------------------|----------------------------------------------------|
+| Pure function (scoring, parsing)   | Unit test passes for that function                 |
+| Worker / agent / queue             | Boot the worker + process at least one real job    |
+| API route                          | Hit the endpoint, verify response                  |
+| Schema migration                   | Verify column exists, Prisma client regenerated    |
+| Middleware / auth                  | Protected routes AND existing routes still work    |
+| Docs / config only                 | N/A — state "docs/config only"                     |
+
+New pure function or utility? → Write test BEFORE committing.
+"Will add tests later" is never acceptable.
+============================================
+GATE
+
+exit 0