Add linter pre-commit hooks and enforce installation in ACP sessions and local dev

[jeremyeder]

Problem

The current pre-commit hook (scripts/git-hooks/pre-commit) only enforces branch protection (blocking commits to main/master/production). It does not run any linters. This means developers can commit unlinted code that then fails in CI, wasting review cycles.

Current State

Linter	CI Workflow	Pre-commit	Gap
gofmt (backend)	go-lint.yml	Missing	Code can be committed unformatted
go vet (backend)	go-lint.yml	Missing	Suspicious constructs slip through
golangci-lint (backend)	go-lint.yml	Missing	Lint issues caught only in CI
gofmt (operator)	go-lint.yml	Missing	Same as backend
go vet (operator)	go-lint.yml	Missing	Same as backend
golangci-lint (operator)	go-lint.yml	Missing	Same as backend
eslint (frontend)	frontend-lint.yml	Missing	Lint issues caught only in CI
tsc --noEmit (frontend)	frontend-lint.yml	Missing	Type errors caught only in CI
npm run build (frontend)	frontend-lint.yml	Missing	Build failures caught only in CI
Mermaid syntax	mermaid-lint.yml	Missing	Invalid diagrams caught only in CI

The existing hook infrastructure (scripts/git-hooks/, scripts/install-git-hooks.sh) is solid but only used for branch protection.

Proposed Solution

1. Add linters to the pre-commit hook

Extend scripts/git-hooks/pre-commit (or adopt the pre-commit framework) to run changed-file-scoped linting:

Go (backend + operator):

• gofmt -l on staged .go files
• go vet ./... in affected component directories
• golangci-lint run in affected component directories (if installed)

Frontend:

• npx eslint on staged .ts/.tsx files
• npx tsc --noEmit (or skip in pre-commit since it's slow — keep in pre-push)

General:

• Keep existing branch protection logic

2. Enforce pre-commit installation locally

Options (pick one or combine):

• a) Add make setup-hooks as a dependency of make dev-start (currently referenced in README but may not be wired)
• b) Add a Makefile check that warns if hooks aren't installed when running common targets
• c) Document in CLAUDE.md that make setup-hooks must be run after clone

3. Enforce pre-commit installation in ACP sessions

When the Claude Code Runner spawns a session that clones a repo:

• Auto-run scripts/install-git-hooks.sh if it exists in the repo
• Or add a CLAUDE.md instruction telling Claude to run make setup-hooks before committing

4. Add CLAUDE.md instructions

Add to the project CLAUDE.md (and possibly the global ~/.claude/CLAUDE.md):

## Pre-Commit Hooks

- ALWAYS run `make setup-hooks` after cloning the repo
- NEVER use `--no-verify` to bypass linters (branch protection override is acceptable)
- If pre-commit hooks fail, fix the issues before committing

Decision Points

• pre-commit framework vs. custom script: The pre-commit framework (.pre-commit-config.yaml) is industry-standard and handles changed-file scoping, caching, and tool installation automatically. The alternative is extending the existing Python script. Pre-commit framework is recommended.
• Scope for pre-commit vs. pre-push: Fast checks (formatting, simple lint) in pre-commit; slow checks (full build, type-checking) in pre-push.
• golangci-lint in pre-commit: Can be slow on large changes. Consider running only on staged files or deferring to pre-push.

Acceptance Criteria

• Pre-commit hook runs gofmt, go vet, and eslint on staged files
• Pre-push hook runs golangci-lint and tsc --noEmit
• make setup-hooks installs all hooks
• make dev-start (and make kind-up) automatically installs hooks
• CLAUDE.md documents the requirement to install hooks
• ACP runner sessions automatically install hooks when cloning repos that have them
• CI continues to run the same linters as a safety net