feat: add pre-commit framework with all linters

[jeremyeder]

Summary

• Adds the pre-commit framework so every linter that CI runs also runs locally before commit
• Replaces the old symlink-based git hooks with pre-commit managed hooks
• Adds make lint target to run all hooks manually

Hooks included:

Hook	Scope
trailing-whitespace, end-of-file-fixer, check-yaml, check-added-large-files, check-merge-conflict, detect-private-key	All files
ruff-format, ruff (check + fix)	Python (runners, scripts)
gofmt, go vet, golangci-lint	Go (per-module: backend, operator, public-api)
eslint	Frontend TS/JS
branch-protection	Blocks commits to main/master/production
push-protection	Blocks pushes to main/master/production

Go and ESLint use local wrapper scripts (scripts/pre-commit/) because Go has 3 separate modules and ESLint config lives in components/frontend/. All wrappers skip gracefully if the toolchain is not installed.

Files Changed

File	Action
.pre-commit-config.yaml	New — central hook config
scripts/pre-commit/{gofmt-check,go-vet,golangci-lint,eslint}.sh	New — wrapper scripts
scripts/install-git-hooks.sh	Rewritten — installs pre-commit, removes old symlinks
Makefile	Updated setup-hooks, remove-hooks; added lint
components/runners/claude-code-runner/Dockerfile	Added pre-commit to pip install
components/runners/state-sync/hydrate.sh	Auto-installs hooks after repo clone
CLAUDE.md	Added pre-commit section, updated checklists
CONTRIBUTING.md	Updated git hooks section
scripts/git-hooks/README.md	Rewritten for pre-commit framework

Test plan

• make setup-hooks installs pre-commit and registers hooks
• pre-commit run --all-files runs all hooks (trailing-whitespace and end-of-file-fixer auto-fix pre-existing issues; all other hooks pass on clean files)
• pre-commit run branch-protection passes on feature branch
• pre-commit run check-yaml --all-files passes (with --allow-multiple-documents for K8s manifests)
• make remove-hooks cleanly uninstalls
• Verify hooks fire on normal git commit

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[github-actions]

Claude Code Review

Summary

This PR successfully introduces the pre-commit framework to standardize local linting and enforce quality gates before commits. The implementation is well-architected with graceful fallbacks, proper module-aware linting for Go, and comprehensive coverage of all project components. The wrapper script pattern elegantly handles the multi-module Go setup and component-specific tooling.

Overall Assessment: Ready to merge with minor improvements recommended.

---

Issues by Severity

🚫 Blocker Issues

None identified.

🔴 Critical Issues

None identified.

🟡 Major Issues

1. Missing executable permissions verification in CI

The pre-commit wrapper scripts (gofmt-check.sh, go-vet.sh, golangci-lint.sh, eslint.sh) are correctly set as executable (+x) locally, but there is no CI check to ensure they remain executable after future commits.

Recommendation: Add the check-executables-have-shebangs hook from pre-commit-hooks v5.0.0 to verify script executability.

2. Missing test coverage documentation

The test plan shows unchecked items:

• make remove-hooks cleanly uninstalls
• Verify hooks fire on normal git commit

Recommendation: Complete test plan verification before merge or document why these are deferred.

🔵 Minor Issues

1. Hardcoded timeout in golangci-lint

golangci-lint.sh:39 uses --timeout=5m which may be insufficient for large modules or slow CI runners.

Recommendation: Make timeout configurable via environment variable.

2. CLAUDE.md checklist duplication

The pre-commit checklist mentions "Pre-commit hooks pass" which is now redundant since hooks run automatically.

Recommendation: Update checklist items to clarify hooks run automatically.

3. Missing documentation for local override

Developers may want to skip specific hooks locally (e.g., golangci-lint during rapid iteration).

Recommendation: Document SKIP usage in CONTRIBUTING.md.

---

Positive Highlights

✅ Graceful degradation: All wrapper scripts check for tool availability and skip gracefully if not installed.

✅ Module-aware Go linting: The affected_modules pattern correctly handles the multi-module structure (backend, operator, public-api).

✅ Security-conscious: Includes detect-private-key hook to prevent accidental credential commits.

✅ Comprehensive coverage: Covers all project components (Python, Go, frontend, YAML) with appropriate tooling.

✅ Automatic installation: The state-sync/hydrate.sh integration ensures hooks are set up in runner containers automatically.

✅ Clean migration: Old symlink-based hooks are removed automatically during installation.

✅ Consistent with CI: Hooks mirror what GitHub Actions runs, reducing "works on my machine" issues.

✅ Documentation quality: CLAUDE.md updates are thorough and include practical examples.

---

Recommendations

High Priority

1. Complete test plan verification before merge
2. Consider adding CI verification that pre-commit hooks pass on PRs

Medium Priority

3. Document SKIP usage in CONTRIBUTING.md
4. Make golangci-lint timeout configurable via environment variable

Low Priority

5. Consider adding check-executables-have-shebangs hook
6. Update checklist items to clarify pre-commit hooks run automatically

---

Architecture Alignment

✅ Follows CLAUDE.md development standards
✅ Aligns with configuration standards (Go, Python, Frontend sections)
✅ Integrates with existing make targets
✅ Maintains backward compatibility
✅ Respects security patterns

---

Final Verdict

LGTM with minor improvements recommended ✅

This is a high-quality implementation that significantly improves code quality enforcement. The identified issues are minor and do not block merge. Consider addressing the test plan completion and documentation enhancements post-merge if time-constrained.

---

🤖 Review completed by Claude Code using platform repository standards

---

🔍 View AI decision process (logs available for 90 days)

📋 View memory system files loaded (click to expand)

What Amber Loaded for Code Review

Amber automatically loaded these repository standards from the memory system:

1. CLAUDE.md - Master project instructions, development standards
2. backend-development.md - Go backend, K8s integration patterns
3. frontend-development.md - NextJS, Shadcn UI, React Query patterns
4. security-standards.md - Auth, RBAC, token handling
5. k8s-client-usage.md - User token vs service account patterns
6. error-handling.md - Consistent error patterns
7. react-query-usage.md - Data fetching patterns

Impact: This review used your repository's specific code quality standards, security patterns, and best practices from the memory system (PRs #359, #360) - not just generic code review guidelines.