feat(hooks): add pre-push --all-features cargo check hook Refs #1304

Add scripts/pre-push-check.sh that runs cargo check --workspace
--all-features before every push, catching feature-gated compilation
breaks on the developer machine before a full CI round-trip.

Wire the script into install_native_hooks() in install-hooks.sh so
./scripts/install-hooks.sh installs it as .git/hooks/pre-push.

Escape hatch: SKIP_ALL_FEATURES_CHECK=1 git push bypasses the check
for WIP pushes to non-main branches.

Document the hook in CONTRIBUTING.md and the hook overview summary.

Author: Test User

CONTRIBUTING.md

@@ -82,6 +82,8 @@ This installs pre-commit hooks that will:
 - Check for secrets and large files
 - Ensure consistent code style
 
+It also installs a **pre-push hook** that runs `cargo check --workspace --all-features` before every push, catching feature-gated compilation breaks locally before they reach CI. This saves an 8-15 minute CI round-trip for a compile error. To bypass on a WIP push: `SKIP_ALL_FEATURES_CHECK=1 git push`.
+
 **No Python required!** The script supports multiple hook managers (prek, lefthook, or native Git hooks).
 
 ### Commit Standards

scripts/install-hooks.sh

@@ -73,6 +73,14 @@ install_native_hooks() {
     else
         print_status "WARN" "Native commit-msg hook not found at scripts/hooks/commit-msg"
     fi
+
+    if [ -f "scripts/pre-push-check.sh" ]; then
+        cp scripts/pre-push-check.sh .git/hooks/pre-push
+        chmod +x .git/hooks/pre-push
+        print_status "SUCCESS" "Installed pre-push --all-features check hook"
+    else
+        print_status "WARN" "Pre-push check script not found at scripts/pre-push-check.sh"
+    fi
 }
 
 # Function to setup Biome
@@ -355,6 +363,7 @@ echo "  - JavaScript/TypeScript: Biome check"
 echo "  - Security: Secret detection, large file blocking"
 echo "  - Syntax: YAML, TOML validation"
 echo "  - Ultimate Bug Scanner (UBS): AST-based bug detection (if installed)"
+echo "  - Pre-push: cargo check --workspace --all-features (SKIP_ALL_FEATURES_CHECK=1 to bypass)"
 echo ""
 print_status "INFO" "Pre-commit/Prek/Lefthook enhancements (if installed):"
 echo "  ✓ Automatic whitespace fixing (trailing spaces, EOF)"

scripts/pre-push-check.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+#
+# Pre-push hook: cargo check --workspace --all-features
+#
+# Catches --all-features compilation breaks on the developer machine before
+# a full CI round-trip is needed. Runs in under 90 seconds on a warm cache.
+#
+# Escape hatch (for WIP pushes to non-main branches):
+#   SKIP_ALL_FEATURES_CHECK=1 git push
+#
+# This hook is installed by scripts/install-hooks.sh as .git/hooks/pre-push
+# and works alongside the CI gate added by issue #1295.
+#
+set -euo pipefail
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+if [ "${SKIP_ALL_FEATURES_CHECK:-0}" = "1" ]; then
+    echo -e "${YELLOW}[pre-push] SKIP_ALL_FEATURES_CHECK=1: skipping --all-features check${NC}"
+    exit 0
+fi
+
+echo -e "${GREEN}[pre-push] Running cargo check --workspace --all-features ...${NC}"
+echo "           (Set SKIP_ALL_FEATURES_CHECK=1 to bypass on WIP branches)"
+
+if cargo check --workspace --all-features 2>&1; then
+    echo -e "${GREEN}[pre-push] All features check passed.${NC}"
+    exit 0
+else
+    echo ""
+    echo -e "${RED}[pre-push] ERROR: cargo check --workspace --all-features failed.${NC}"
+    echo -e "${RED}           Fix the compilation errors above before pushing.${NC}"
+    echo ""
+    echo "           To bypass (WIP branches only):"
+    echo "             SKIP_ALL_FEATURES_CHECK=1 git push"
+    echo ""
+    exit 1
+fi