added repo

claude/08-pre-commit-and-hooks.md

@@ -0,0 +1,69 @@
+> 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)