> Per AI Blitz Plan §claude. Layer: 1. Repo: devops-infra-helm-charts.

# 08 — Pre-commit and hooks

What runs when you `git commit` here, what blocks, what doesn't, and why nothing should be bypassed.

## Hook installation

One-time, per clone:

```
pre-commit install \
  --hook-type pre-commit \
  --hook-type pre-push \
  --hook-type post-commit
```

If the hooks aren't installed, the local commit will skip them — but PR review is the catch-net, and a missed scan in a feature branch can still catch the secret before merge.

## Active hooks

### TruffleHog (pre-commit, blocking)

Scans the staged content for high-entropy strings and known secret patterns (AWS keys, GCP service-account JSON, GitHub tokens, generic JWTs, etc.).

- **Blocks the commit** on any positive match.
- **NEVER bypass** with `git commit --no-verify` or `git commit -n`. This is on the don't-touch list — see [`../docs/global/SANCTITY_RULES.md`](../docs/global/SANCTITY_RULES.md).
- If the hook fires on a **real secret**: stop, rotate the credential immediately (any value that touched a Git working tree is half-burned), then move to External Secrets Operator. See [`./06-secrets-and-identity.md`](./06-secrets-and-identity.md).
- If the hook fires on a **false positive**: fix the regex in `pre-commit-scripts/` rather than skip-listing the file. The fix is reusable across the org.

### CAC and Yaak (pre-commit / pre-push, gated)

These hooks exist in the platform's standard `.pre-commit-config.yaml`, but they are gated on file paths this repo doesn't carry (CAC config files, Yaak collections). They no-op here. The same scripts run for real in service repos.

If a future change ever introduces matching paths, the hooks will start firing — read their messages and fix forward. Do not disable.

## Background hooks

### Cursor AI commit metric collector (post-commit, non-blocking)

Posts a metric ping to `observe.meeshogcp.in` describing the commit (author, files touched, AI tool used). Runs in the background, does not block, and silently drops on failure.

- This is **the only sanctioned outbound call to a `*.meeshogcp.in` host** the agent should ever observe in this repo. Agents must still refuse to *initiate* any such call themselves. See [`../docs/global/SANCTITY_RULES.md`](../docs/global/SANCTITY_RULES.md).
- If the post-commit script is failing, that's a platform issue — escalate per [`../docs/global/escalation-matrix.md`](../docs/global/escalation-matrix.md). Do not remove the script.

## Why never `--no-verify`

A bypassed pre-commit hook is invisible to the PR reviewer. Real secrets ship through merged PRs are very expensive to recover from:

- The credential itself must be rotated everywhere it's used.
- The Git history must be force-rewritten (and even then, the Git push may be cached on a mirror).
- Any system that ingested the secret value (CI logs, Slack quotes, downstream forks) is now compromised.

The 5 seconds saved bypassing the hook is a 5-day-or-more incident later.

## When the hook is wrong

Two kinds of false-positive:

1. **Pattern over-matches** — TruffleHog regex matches a non-secret high-entropy string (a hash, a UUID, a build label). Fix: tighten the regex in `pre-commit-scripts/`.
2. **Genuine fixture / test data** — a fake-looking string in a chart's example values or test fixture. Fix: same — tighten the pattern, or move the fixture to a path TruffleHog already excludes (chart `templates/` test fixtures usually qualify).

Either way, the fix is in the hook, not in the bypass.

## See also

- [`./06-secrets-and-identity.md`](./06-secrets-and-identity.md)
- [`../docs/global/SANCTITY_RULES.md`](../docs/global/SANCTITY_RULES.md)
- [`../docs/global/agent-operations-guide.md`](../docs/global/agent-operations-guide.md)