chore: catch codegen drift in pre-commit hook

Extends .githooks/pre-commit to run 'make generate' and fail the commit
if CRDs/deepcopy are out of sync, but only when api/ type files are
staged (so normal commits stay fast).

Also documents required status checks for main branch protection, so
the Codegen & Helm sync job blocks PR merges instead of failing
silently post-merge.

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Author: AlexsJones

.githooks/pre-commit

@@ -1,5 +1,7 @@
 #!/usr/bin/env bash
-# Pre-commit hook: ensure all Go files are gofmt-formatted before committing.
+# Pre-commit hook:
+#   1. ensure all Go files are gofmt-formatted
+#   2. if api/ types changed, ensure generated CRDs/deepcopy are in sync
 
 set -euo pipefail
 
@@ -12,3 +14,20 @@ if [ -n "$unformatted" ]; then
   echo "Run 'make fmt' or 'gofmt -s -w .' to fix, then re-add and commit."
   exit 1
 fi
+
+# Only run codegen check if API types are part of this commit.
+if git diff --cached --name-only | grep -qE '^api/.*\.go$'; then
+  echo "api/ types changed — verifying generated code is in sync..."
+  if ! make generate >/dev/null 2>&1; then
+    echo "ERROR: 'make generate' failed. Fix the errors, then re-commit."
+    exit 1
+  fi
+  drift=$(git diff --name-only -- config/crd/bases charts/sympozium/crds api/ 2>/dev/null || true)
+  if [ -n "$drift" ]; then
+    echo "ERROR: Generated code is out of sync with api/ types. Drifted files:"
+    echo "$drift" | sed 's/^/  /'
+    echo ""
+    echo "Run 'make generate', then 'git add' the updated files and re-commit."
+    exit 1
+  fi
+fi

CONTRIBUTING.md

@@ -108,6 +108,31 @@ make build      # compile all binaries
 go build ./...  # quick compile check
 ```
 
+### Pre-commit hook
+
+The repo ships a pre-commit hook at `.githooks/pre-commit` that:
+
+1. verifies all Go files are `gofmt`-formatted, and
+2. if any `api/` type files are staged, runs `make generate` and fails the commit if CRDs/deepcopy are out of sync.
+
+Enable it once per clone:
+
+```bash
+make setup-hooks
+```
+
+This catches codegen drift locally — without it, the drift only surfaces in the `Codegen & Helm sync` CI job after push.
+
+### Required status checks
+
+The following CI jobs should be configured as **required status checks** on the `main` branch in GitHub branch protection, so PRs can't merge while red:
+
+- `Vet`
+- `Test`
+- `Build`
+- `Codegen & Helm sync`
+- `Format`
+
 ---
 
 ## Multi-Architecture Builds