From 2fd70818fbe1d4feab004afae4a0f3734acf7057 Mon Sep 17 00:00:00 2001
From: James <james@prestwi.ch>
Date: Tue, 7 Apr 2026 16:51:18 -0400
Subject: [PATCH] Add Claude pre-push hooks for clippy and doc checks

Adds a Claude Code hook that runs before every `git push`:
- cargo +nightly fmt --check
- cargo clippy with -D warnings
- RUSTDOCFLAGS="-D warnings" cargo doc

Clippy and doc warnings are hard failures that block the push.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .claude/hooks/pre-push.sh | 32 ++++++++++++++++++++++++++++++++
 .claude/settings.json     | 17 +++++++++++++++++
 CLAUDE.md                 | 12 ++++++++++++
 3 files changed, 61 insertions(+)
 create mode 100755 .claude/hooks/pre-push.sh
 create mode 100644 .claude/settings.json

diff --git a/.claude/hooks/pre-push.sh b/.claude/hooks/pre-push.sh
new file mode 100755
index 00000000..b1b5dcc5
--- /dev/null
+++ b/.claude/hooks/pre-push.sh
@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Consume stdin (hook protocol)
+cat > /dev/null
+
+cd "$(dirname "$0")/../.."
+
+echo "Running pre-push checks..." >&2
+
+if ! cargo +nightly fmt -- --check 2>&1; then
+    echo "Format check failed. Run 'cargo +nightly fmt' to fix." >&2
+    exit 2
+fi
+
+if ! cargo clippy --workspace --all-targets --all-features -- -D warnings 2>&1; then
+    echo "Clippy (--all-features) failed." >&2
+    exit 2
+fi
+
+if ! cargo clippy --workspace --all-targets --no-default-features -- -D warnings 2>&1; then
+    echo "Clippy (--no-default-features) failed." >&2
+    exit 2
+fi
+
+if ! RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps 2>&1; then
+    echo "Doc check failed." >&2
+    exit 2
+fi
+
+echo "All pre-push checks passed." >&2
+exit 0
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 00000000..cc3faa1e
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,17 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "if": "Bash(git push *)",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/pre-push.sh",
+            "timeout": 600
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/CLAUDE.md b/CLAUDE.md
index 2951863a..e98b249b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -15,6 +15,18 @@ long-term maintenance and may receive active work.
 Pre-push: clippy (both feature sets where applicable) + fmt. Never use `cargo check/build`.
 These checks apply before any push — new commits, rebases, cherry-picks, etc.
 
+### Pre-push Checks (enforced by Claude hook)
+
+A Claude hook in `.claude/settings.json` runs `.claude/hooks/pre-push.sh`
+before every `git push`. The push is blocked if any check fails. The checks:
+
+- `cargo +nightly fmt -- --check`
+- `cargo clippy --workspace --all-targets --all-features -- -D warnings`
+- `cargo clippy --workspace --all-targets --no-default-features -- -D warnings`
+- `RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps`
+
+Clippy and doc warnings are hard failures.
+
 ## Style
 
 - Functional combinators over imperative control flow