learningcircuit--local-deep-research/docs/decisions/0001-remove-detect-secrets.md

# ADR-0001: Remove detect-secrets in favor of gitleaks

**Date:** 2026-02-28
**Status:** Accepted

## Context

The repository used two pre-commit secret scanners:

1. **detect-secrets** (Yelp) — entropy + pattern analysis, tracking false positives
   in a `.secrets.baseline` JSON file (173 KB, ~5200 lines)
2. **gitleaks** — pattern-based detection with path/regex allowlists in
   `.gitleaks.toml`

### Problems with detect-secrets

detect-secrets tracks known false positives using **line numbers** in
`.secrets.baseline`. When any file changes above a flagged line, the baseline
shifts and must be regenerated. This caused:

- **Constant merge conflicts** on `.secrets.baseline` across branches
- **Manual re-staging** of the baseline on every commit touching flagged files
- **173 KB of PR churn** unrelated to actual secret scanning

All 34 entropy-only detections in the baseline were verified as false positives
(git SHAs, GPG fingerprints, base64 character sets, test fixtures).

### Why gitleaks is sufficient

- gitleaks uses **path-based and regex-based** allowlists (`.gitleaks.toml`)
  that are stable across line changes — no baseline regeneration needed
- gitleaks covers every service-specific detector that detect-secrets provides
  (AWS, GitHub, Stripe, Slack, etc.)
- gitleaks runs as both a **pre-commit hook** and in **CI workflows**
  (`gitleaks.yml` on PRs, `gitleaks-main.yml` as release gate)
- Additional CI coverage from **Semgrep** (`p/secrets`) and **Bearer**
  (`scanner: sast,secrets`) in the release gate

## Decision

Remove detect-secrets entirely:

- Delete the `Yelp/detect-secrets` hook from `.pre-commit-config.yaml`
- Delete `.secrets.baseline`
- Clean up references in `.gitleaks.toml`, `.gitleaksignore`, `CODEOWNERS`,
  `danger-zone-alert.yml`, `SECURITY_REVIEW_PROCESS.md`, `SECURITY.md`,
  and `.file-whitelist.txt`

**Do not re-add detect-secrets.** Use `.gitleaks.toml` allowlists for managing
false positives instead.

## Consequences

- Eliminates merge conflicts and churn from `.secrets.baseline`
- Simplifies the pre-commit pipeline (one secret scanner instead of two)
- False positives are managed via `.gitleaks.toml` path/regex allowlists and
  `.gitleaksignore` commit fingerprints, both of which are stable across
  line-number changes
- No loss of detection coverage — gitleaks + Semgrep + Bearer provide
  equivalent or better coverage