Merge pull request #147 from mq-rest-admin-project/feature/146-hook-guard

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

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

@@ -103,11 +103,9 @@ translation between Ruby idioms and native MQSC parameter names.
 
 ### Standard Tooling
 
-```bash
-cd ../vergil-tooling && uv sync                                                # Install vergil-tooling
-export PATH="../vergil-tooling/.venv/bin:../vergil-tooling/scripts/bin:$PATH" # Put tools on PATH
-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.
 
 ### Environment Setup
 

docs/repository-standards.md

@@ -14,7 +14,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

@@ -65,18 +65,11 @@ bundle exec rubocop -A             # Auto-fix
 gem build mq-rest-admin.gemspec
 ```
 
-## Git hooks
+## Claude Code hook guard
 
-Enable repository git hooks before committing:
-
-```bash
-git config core.hooksPath scripts/git-hooks
-```
-
-The hooks enforce:
-
-- **pre-commit**: Branch naming conventions and protected branch rules
-- **commit-msg**: Conventional Commits format and co-author trailer validation
+The `.claude/hooks/guard.sh` PreToolUse hook blocks raw `git` and
+`gh` commands in AI agent sessions — all operations must go through
+the `vrg-git` / `vrg-gh` wrappers.
 
 ## Documentation