chore(hooks): add Claude Code hook guard, scrub legacy hooksPath refs (#509)

Add .claude/hooks/guard.sh PreToolUse hook, update settings.json with hook wiring and permissions, update docs.

Author: wphillipmoore

.claude/hooks/guard.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Claude Code PreToolUse hook shim.
+# Delegates to vrg-hook-guard if available; falls back to a
+# jq-based git/gh check that hard-denies when vergil-tooling
+# is not installed.
+set -euo pipefail
+
+if command -v vrg-hook-guard &>/dev/null; then
+  exec vrg-hook-guard
+fi
+
+input=$(cat)
+command=$(printf '%s' "$input" | jq -r '.tool_input.command // empty')
+bin=$(printf '%s' "$command" | awk '{print $1}')
+base=$(basename "$bin" 2>/dev/null || printf '%s' "$bin")
+
+case "$base" in
+  git|gh)
+    jq -n '{
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: "vergil-tooling is not available. This repository requires a correctly configured environment — all git/gh operations are blocked until resolved."
+      }
+    }'
+    exit 0
+    ;;
+esac
+
+exit 0

.claude/settings.json

@@ -1,4 +1,22 @@
 {
+  "permissions": {
+    "allow": [
+      "Bash(vrg-*)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard.sh"
+          }
+        ]
+      }
+    ]
+  },
   "extraKnownMarketplaces": {
     "vergil-marketplace": {
       "source": {

CLAUDE.md

@@ -98,9 +98,9 @@ All fields are required.
 
 ### Standard Tooling
 
-```bash
-git config core.hooksPath ../vergil-tooling/scripts/lib/git-hooks  # Enable git hooks
-```
+The Claude Code PreToolUse hook guard (`.claude/hooks/guard.sh`)
+blocks raw `git` and `gh` commands — use `vrg-git` / `vrg-gh`
+wrappers.
 
 VERGIL CLI tools (`vrg-commit`, `vrg-validate`, etc.) are
 pre-installed in the dev container images. No local setup required.

docs/repository-standards.md

@@ -15,7 +15,7 @@
 - Before modifying any files, check the current branch with `git status -sb`.
 - If on `develop`, create a short-lived `feature/*` branch or ask for explicit approval to proceed on `develop`.
 - If approval is granted to work on `develop`, call it out in the response and proceed only for that user-approved scope.
-- Enable repository git hooks before committing: `git config core.hooksPath .githooks`.
+- The Claude Code hook guard (`.claude/hooks/guard.sh`) blocks raw `git`/`gh` — use `vrg-git`/`vrg-gh`.
 
 ## Local validation
 

docs/site/docs/development/developer-setup.md

@@ -55,8 +55,8 @@ cd pymqrest
 # Install all dependencies including dev group
 uv sync --group dev
 
-# Enable repository git hooks
-git config core.hooksPath scripts/git-hooks
+# The Claude Code hook guard (.claude/hooks/guard.sh) blocks raw
+# git/gh commands — use vrg-git / vrg-gh wrappers.
 ```
 
 ## Running validation

docs/standards-compliance-gates.md

@@ -34,7 +34,7 @@ Blocks commits on protected branches (`develop`, `release`, `main`,
 `release/*`) and enforces branch naming prefixes (`feature/*`, `bugfix/*`,
 `hotfix/*`).
 
-Enable with: `git config core.hooksPath scripts/git-hooks`
+Enforcement is now handled by the Claude Code hook guard (`.claude/hooks/guard.sh`).
 
 ### Commit message hook