From 31626536951426125865ba364410375e2688e3dd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?V=C3=ADctor=20R=2E=20Escobar?= <victor@vrescobar.com>
Date: Sat, 14 Feb 2026 14:07:37 +0100
Subject: [PATCH] chore: add pre-push hook enforcing fmt, clippy, and tests

Adds .githooks/pre-push that runs cargo fmt --check, cargo clippy
-- -D warnings, and cargo test before every push. Enable with:

  git config core.hooksPath .githooks

Skip with git push --no-verify for rapid iteration.

Documented in README.md and CONTRIBUTING.md.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .githooks/pre-push | 28 ++++++++++++++++++++++++++++
 CONTRIBUTING.md    | 19 +++++++++++++++++--
 README.md          | 14 ++++++++++++++
 3 files changed, 59 insertions(+), 2 deletions(-)
 create mode 100755 .githooks/pre-push

diff --git a/.githooks/pre-push b/.githooks/pre-push
new file mode 100755
index 0000000..4d8eea7
--- /dev/null
+++ b/.githooks/pre-push
@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+#
+# pre-push hook — runs fmt, clippy, and tests before every push.
+# Install:  git config core.hooksPath .githooks
+# Skip:     git push --no-verify
+
+set -euo pipefail
+
+echo "==> pre-push: checking formatting..."
+cargo fmt -- --check || {
+    echo "FAIL: cargo fmt -- --check found unformatted code."
+    echo "Run 'cargo fmt' and try again."
+    exit 1
+}
+
+echo "==> pre-push: running clippy..."
+cargo clippy -- -D warnings || {
+    echo "FAIL: clippy reported warnings."
+    exit 1
+}
+
+echo "==> pre-push: running tests..."
+cargo test || {
+    echo "FAIL: some tests did not pass."
+    exit 1
+}
+
+echo "==> pre-push: all checks passed."
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a18a9c0..c319cc5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -9,19 +9,34 @@ Thanks for your interest in contributing to ZeroClaw! This guide will help you g
 git clone https://github.com/theonlyhennygod/zeroclaw.git
 cd zeroclaw
 
+# Enable the pre-push hook (runs fmt, clippy, tests before every push)
+git config core.hooksPath .githooks
+
 # Build
 cargo build
 
-# Run tests (180 tests, all must pass)
+# Run tests (all must pass)
 cargo test
 
 # Format & lint (must pass before PR)
 cargo fmt && cargo clippy -- -D warnings
 
-# Release build (~3.1MB)
+# Release build (~3.4MB)
 cargo build --release
 ```
 
+### Pre-push hook
+
+The repo includes a pre-push hook in `.githooks/` that enforces `cargo fmt --check`, `cargo clippy -- -D warnings`, and `cargo test` before every push. Enable it with `git config core.hooksPath .githooks`.
+
+To skip it during rapid iteration:
+
+```bash
+git push --no-verify
+```
+
+> **Note:** CI runs the same checks, so skipped hooks will be caught on the PR.
+
 ## Architecture: Trait-Based Pluggability
 
 ZeroClaw's architecture is built on **traits** — every subsystem is swappable. This means contributing a new integration is as simple as implementing a trait and registering it in the factory function.
diff --git a/README.md b/README.md
index 4f2c745..5efbbf7 100644
--- a/README.md
+++ b/README.md
@@ -219,6 +219,20 @@ cargo fmt                # Format
 cargo test --test memory_comparison -- --nocapture
 ```
 
+### Pre-push hook
+
+A git hook runs `cargo fmt --check`, `cargo clippy -- -D warnings`, and `cargo test` before every push. Enable it once:
+
+```bash
+git config core.hooksPath .githooks
+```
+
+To skip the hook when you need a quick push during development:
+
+```bash
+git push --no-verify
+```
+
 ## License
 
 MIT — see [LICENSE](LICENSE)