chore: consolidate git hooks into lefthook, perfect the repo

Dual hook systems (.githooks/ + lefthook.yml) consolidated into single
canonical lefthook setup:

- Remove .githooks/ — functionality merged into lefthook.yml
- lefthook.yml pre-commit: add ast-grep scan (moved from .githooks)
- lefthook.yml commit-msg: add Co-authored-by stripping (moved from .githooks)
- lefthook.yml: soft-skip gofumpt/goimports when missing (was hard-exit)
- lefthook.yml: bump pre-push test timeout 60s -> 120s to match 'make test'
- Makefile setup: auto-install lefthook and run 'lefthook install'
- Makefile hooks target: use 'lefthook install' (was 'git config core.hooksPath')
- CONTRIBUTING.md: update co-author guidance to use 'make hooks'

Author: Patel230

.githooks/pre-commit

@@ -74,10 +74,11 @@ refactor!: rename ClientV1 to Client (BREAKING CHANGE)
 ```
 
 **Co-authors:** do not add `Co-authored-by:` trailers. Commits should list
-only the human author. Enable the repo hook with:
+only the human author. Hooks are auto-installed by `make setup` via
+[lefthook](https://github.com/evilmartians/lefthook). To re-install manually:
 
 ```bash
-git config core.hooksPath .githooks
+make hooks
 ```
 
 ## Pull request checklist

.githooks/prepare-commit-msg

@@ -175,8 +175,12 @@ setup: ## Set up local development environment (go.work + external repos).
 	@command -v $(GOIMPORTS) >/dev/null 2>&1 || go install golang.org/x/tools/cmd/goimports@latest
 	@command -v $(GOLANGCI)  >/dev/null 2>&1 || go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
 	@command -v $(GOVULNCHECK) >/dev/null 2>&1 || go install golang.org/x/vuln/cmd/govulncheck@latest
+	@command -v lefthook >/dev/null 2>&1 || go install github.com/evilmartians/lefthook@latest
 	@echo "✓ All tools installed"
 	@echo ""
+	@echo "=== Installing git hooks ==="
+	@lefthook install || echo "  ⚠ lefthook install failed (run 'make hooks' manually)"
+	@echo ""
 	@echo "=== Setup complete! ==="
 	@echo "Run 'make ci' to verify everything works."
 
@@ -197,8 +201,9 @@ compat-check: ## Strict validation — non-zero exit if any component lacks a ve
 	@go run ./cmd/compat-test -matrix=next -strict -file=testdata/compatibility-matrix.json
 
 .PHONY: hooks
-hooks:
-	git config core.hooksPath .githooks
+hooks: ## Install git hooks via lefthook (formatting, linting, conventional commits).
+	@command -v lefthook >/dev/null 2>&1 || (echo "install: go install github.com/evilmartians/lefthook@latest" && exit 1)
+	lefthook install
 # === Cross-platform binary targets (add after existing 'build' target) ===
 
 .PHONY: build-all build-static size-check

CONTRIBUTING.md

@@ -6,7 +6,7 @@
 #   go install github.com/evilmartians/lefthook@latest
 #   npm install -g lefthook      (cross-platform)
 #
-# Activate hooks in this repo (one time):
+# Activate hooks in this repo (one time, done automatically by `make setup`):
 #   lefthook install
 #
 # Skip hooks for a single commit (use sparingly):
@@ -23,7 +23,8 @@ pre-commit:
       glob: "*.go"
       run: |
         if ! command -v gofumpt >/dev/null 2>&1; then
-          echo "lefthook: gofumpt not installed (go install mvdan.cc/gofumpt@latest)"; exit 1
+          echo "lefthook: gofumpt not installed (go install mvdan.cc/gofumpt@latest) — skipping"
+          exit 0
         fi
         gofumpt -w {staged_files}
       stage_fixed: true
@@ -32,7 +33,8 @@ pre-commit:
       glob: "*.go"
       run: |
         if ! command -v goimports >/dev/null 2>&1; then
-          echo "lefthook: goimports not installed (go install golang.org/x/tools/cmd/goimports@latest)"; exit 1
+          echo "lefthook: goimports not installed (go install golang.org/x/tools/cmd/goimports@latest) — skipping"
+          exit 0
         fi
         goimports -w {staged_files}
       stage_fixed: true
@@ -47,6 +49,18 @@ pre-commit:
         golangci-lint run --new-from-rev=HEAD~1 --fix {staged_files}
       stage_fixed: true
 
+    ast-grep:
+      glob: "*.go"
+      run: |
+        # Run ast-grep structural code search on staged Go files.
+        # Falls back gracefully if `sg` (ast-grep) is not installed.
+        STAGED=$(git diff --cached --name-only --diff-filter=ACMR | grep '\.go$' || true)
+        if [ -n "$STAGED" ]; then
+          if command -v sg >/dev/null 2>&1; then
+            echo "$STAGED" | xargs sg scan 2>&1 | head -20
+          fi
+        fi
+
     yaml-lint:
       glob: "*.{yml,yaml}"
       run: |
@@ -76,7 +90,7 @@ pre-push:
   commands:
 
     test:
-      run: go test ./... -count=1 -timeout=60s
+      run: go test ./... -count=1 -timeout=120s
 
     vet:
       run: go vet ./...
@@ -90,7 +104,7 @@ pre-push:
         govulncheck ./...
 
 # ---------------------------------------------------------------------------
-# commit-msg — validate Conventional Commits (release-please depends on it).
+# commit-msg — validate Conventional Commits and strip AI co-author trailers.
 # ---------------------------------------------------------------------------
 commit-msg:
   commands:
@@ -110,3 +124,9 @@ commit-msg:
           echo "  full guide: https://www.conventionalcommits.org/"
           exit 1
         fi
+
+    strip-co-authored-by:
+      run: |
+        # Strip Co-authored-by: trailers that AI tools (Claude, Cursor, etc.) add.
+        # This enforces the rule that commits list only the human author.
+        sed '/^[Cc]o-[Aa]uthored-[Bb]y:/d' "{1}" > "{1}.tmp" && mv "{1}.tmp" "{1}"