Hooks: add pre-commit docs guard for git and Claude Code

- scripts/hook-pre-commit-docs.sh: blocks git commit when .py/.js/.html/.css files are staged but README.md or CLAUDE.md are not
- scripts/install-hooks.sh: one-shot setup that installs the git hook and registers the Claude Code PreToolUse hook into .claude/settings.json
- CLAUDE.md: document the hooks and the install command

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -178,6 +178,17 @@ is `deploy/hf-spaces/TASKS.md`. Non-obvious bits:
   asked. Only commit/push when explicitly asked.
 - End commit messages with the `Co-Authored-By: Claude` trailer.
 
+## Hooks (enforced automatically)
+
+Two hooks block commits that stage source files without updating both docs:
+
+| Hook | When it fires | Source |
+|---|---|---|
+| `scripts/hook-pre-commit-docs.sh` | `git commit` (terminal) | installed to `.git/hooks/pre-commit` |
+| `.claude/hooks/pre-commit-docs-check.sh` | Claude Code `Bash` tool with `git commit` | registered in `.claude/settings.json` `PreToolUse` |
+
+Run `sh scripts/install-hooks.sh` after cloning to install both. `.git/hooks/` and `.claude/` are not tracked by git — the canonical hook source lives in `scripts/`.
+
 ## Quick commands
 
 ```bash

scripts/hook-pre-commit-docs.sh

@@ -0,0 +1,27 @@
+#!/bin/sh
+# Git pre-commit hook: block commits that stage source files without updating README.md + CLAUDE.md.
+# Installed to .git/hooks/pre-commit by scripts/install-hooks.sh.
+
+STAGED=$(git diff --cached --name-only)
+
+# Only enforce when at least one source file is changing
+SOURCE_CHANGED=$(echo "$STAGED" | grep -E '\.(py|js|html|css)$' | grep -v '^tests/' | head -1)
+[ -z "$SOURCE_CHANGED" ] && exit 0
+
+README_STAGED=$(echo "$STAGED" | grep '^README\.md$')
+CLAUDE_STAGED=$(echo "$STAGED" | grep '^CLAUDE\.md$')
+
+if [ -z "$README_STAGED" ] || [ -z "$CLAUDE_STAGED" ]; then
+  echo ""
+  echo "  Commit blocked: source files staged but docs not updated"
+  echo ""
+  [ -z "$README_STAGED" ] && echo "  • README.md not staged"
+  [ -z "$CLAUDE_STAGED" ] && echo "  • CLAUDE.md not staged"
+  echo ""
+  echo "  Update both to reflect your changes, git add them, then retry."
+  echo "  Bypass with:  git commit --no-verify"
+  echo ""
+  exit 1
+fi
+
+exit 0

scripts/install-hooks.sh

@@ -0,0 +1,77 @@
+#!/bin/sh
+# Install git hook and Claude Code hook for this repo.
+# Run once after cloning: sh scripts/install-hooks.sh
+
+set -e
+REPO_ROOT=$(git rev-parse --show-toplevel)
+
+# ── Git pre-commit hook ────────────────────────────────────────────────────
+HOOK_DST="$REPO_ROOT/.git/hooks/pre-commit"
+cp "$REPO_ROOT/scripts/hook-pre-commit-docs.sh" "$HOOK_DST"
+chmod +x "$HOOK_DST"
+echo "✓ git pre-commit hook installed → .git/hooks/pre-commit"
+
+# ── Claude Code PreToolUse hook ────────────────────────────────────────────
+CLAUDE_DIR="$REPO_ROOT/.claude"
+CLAUDE_HOOKS="$CLAUDE_DIR/hooks"
+CLAUDE_SETTINGS="$CLAUDE_DIR/settings.json"
+
+mkdir -p "$CLAUDE_HOOKS"
+
+# Copy the hook script into .claude/hooks/
+cp "$REPO_ROOT/scripts/hook-pre-commit-docs.sh" "$CLAUDE_HOOKS/pre-commit-docs-check.sh"
+chmod +x "$CLAUDE_HOOKS/pre-commit-docs-check.sh"
+
+# Merge the hook entry into .claude/settings.json
+if [ -f "$CLAUDE_SETTINGS" ]; then
+  # Add hooks key if not already present using Python
+  python3 - "$CLAUDE_SETTINGS" <<'PYEOF'
+import sys, json
+
+path = sys.argv[1]
+with open(path) as f:
+    cfg = json.load(f)
+
+hook_entry = {
+    "type": "command",
+    "command": "bash .claude/hooks/pre-commit-docs-check.sh"
+}
+hooks = cfg.setdefault("hooks", {})
+pre = hooks.setdefault("PreToolUse", [])
+
+# Find or create Bash matcher
+bash_matchers = [m for m in pre if m.get("matcher") == "Bash"]
+if bash_matchers:
+    existing = bash_matchers[0].setdefault("hooks", [])
+    cmds = [h.get("command") for h in existing]
+    if hook_entry["command"] not in cmds:
+        existing.append(hook_entry)
+else:
+    pre.append({"matcher": "Bash", "hooks": [hook_entry]})
+
+with open(path, "w") as f:
+    json.dump(cfg, f, indent=2)
+    f.write("\n")
+
+print("✓ Claude Code PreToolUse hook registered → .claude/settings.json")
+PYEOF
+else
+  cat > "$CLAUDE_SETTINGS" <<JSON
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/pre-commit-docs-check.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+JSON
+  echo "✓ Claude Code PreToolUse hook registered → .claude/settings.json (created)"
+fi