Initial commit

docs/work/epics/ci-security-and-supply-chain/07-gitleaks-precommit/_story.md

@@ -0,0 +1,41 @@
+---
+id: 07-gitleaks-precommit
+epic: ci-security-and-supply-chain
+title: Gitleaks pre-commit hook
+type: technical-story
+status: done
+feature: tooling
+depends-on: []
+blocks: [09-ci-security-guide-and-docs]
+created: 2026-05-14T18:59:12+02:00
+updated: 2026-05-14T19:21:52.308Z
+---
+
+## Goal
+
+Add `gitleaks protect --staged --redact` as a step in `.husky/pre-commit` and ship a `.gitleaks.toml` allowlist that covers test-fixture patterns in `__seeds__/**`, so a commit containing a known secret pattern is blocked locally before it reaches the remote.
+
+## Why
+
+Developer accidents (pasting tokens into config, seeding test fixtures with real-looking keys) are the most common secret-leak vector. A pre-commit hook stops the leak at the earliest possible point — before the secret is ever pushed. GitHub native push protection is the second line of defense (documented in Story 09's guide); the hook is the first. The `__seeds__/**` allowlist prevents false positives from test fixtures that deliberately use token-shaped strings as dummy data.
+
+## Done when
+
+- `.husky/pre-commit` has a `gitleaks protect --staged --redact` step that runs before the existing state-sync guard (or after — order between guards doesn't matter, both must run).
+- `.gitleaks.toml` exists at repo root with at minimum one allowlist rule scoping `__seeds__/**` test fixtures (using `paths` or `allowlist.paths` depending on the gitleaks version).
+- A smoke test (bash script or vitest) pipes a staged commit containing a Stripe-style test key (`sk_test_...`) through the hook and asserts non-zero exit code. The smoke test is documented in the story's Done-when but may live as a manual verification step given gitleaks requires a binary; include instructions in `docs/guides/ci-security.md` (Story 09) for consumers to verify locally.
+- `pnpm typecheck && pnpm lint && pnpm test && pnpm conformance && pnpm fallow:audit && pnpm coverage:diff` all pass.
+
+## In scope
+
+- `.husky/pre-commit` — new `gitleaks` step.
+- `.gitleaks.toml` — allowlist config.
+
+## Out of scope
+
+- Installing `gitleaks` as a project devDependency — consumers install it via their OS package manager or `brew`; the hook exits gracefully with a warning if `gitleaks` is not found in `$PATH` (to avoid blocking developers who haven't installed it yet, while still enforcing for those who have).
+- GitHub native push protection configuration — consumer-facing instruction deferred to Story 09's guide.
+
+## Tasks
+
+- [x] Add `gitleaks protect --staged --redact` step to `.husky/pre-commit` (exit-gracefully if `gitleaks` not in `$PATH`); create `.gitleaks.toml` at repo root with `__seeds__/**` allowlist for test-fixture patterns; one commit, all gates pass.