feat(content-guards)!: generalize no-real-ips → sensitive-content-guard

[JacobPEvans]

Summary

Generalizes the IPv4-only no-real-ips hook into a 7-detector
sensitive-content-guard covering the full org secrets-policy.md
attack surface. Each detector has its own allowlist; the first-block /
second-allow UX is preserved per-(file, detector, value) so a retry
acknowledges only the specific category.

Detectors

• ipv4 — IPv4 outside 192.168.0.0/24, loopback, 0.0.0.0,
  broadcast (255.255.255.x), link-local metadata (169.254.169.254).
  Skips rev: vX.Y.Z version pins.
• ipv6 — outside ::, ::1, fe80:: (link-local),
  fc00::/7 (ULA), 2001:db8:: (RFC 3849 doc prefix), ff00::
  (multicast). Skips cas-sha256:/sha256: hash lines.
• email — real addresses outside noreply@github.com,
  *@users.noreply.github.com, *@example.{com,org,net,local},
  *@test, *@localhost, <user@host> placeholder shapes.
• absolute_user_path — hard-coded /Users/<name>/ or
  /home/<name>/ outside ${USER}, $USER, <user> placeholders.
• private_key_header — -----BEGIN ... PRIVATE KEY-----;
  always blocked.
• aws_account_id — bare 12-digit numbers on lines mentioning
  account_id, arn:aws:, aws_account_id, or :account:. Allows
  AWS's documented 123456789012 placeholder.
• real_domain — only flags tokens whose TLD is in a focused
  ~29-entry REAL_TLDS allowlist of popular public TLDs (com,
  net, org, io, ai, dev, app, co, cloud, gov, edu,
  mil, info, biz, me, tv, fm, ly, us, uk, de,
  jp, ca, au, fr, cn, eu, tech, xyz, online, sh).
  Anything outside that set (filenames like foo.py, version strings)
  is treated as not-a-domain. Also allows *.example.*, *.test,
  *.localhost, *.invalid, *.local, and a short explicit
  allowlist (github.com, api.github.com,
  raw.githubusercontent.com, docs.jacobpevans.com, runs-on.com,
  healthchecks.io). Skips pre-commit repo:, container image:,
  and markdown link-reference lines.

State key is (file, detector, value) so acknowledging one IPv4 does
NOT pre-allow an unrelated email.

Test plan

• Bats: 55/55 pass across
  tests/content-guards/sensitive-content/sensitive-content.bats (IPv4
  regression + state machine, 25 cases) and
  tests/content-guards/sensitive-content/detectors.bats (per-detector
  • cross-detector isolation, 30 cases).
• pre-commit run passes (JSON, markdown, EOF newlines, large file
  cap).
• Verified _domain_allowed against 14 representative cases after
  the REAL_TLDS flip (filenames like foo.py/foo.tsx/foo.md pass;
  real .io/.com/.ai/.dev/.gov/.uk block; allowlist exacts
  preserved).

Breaking changes

• validate-no-real-ips.py → validate-sensitive-content.py
• State file no-real-ips-state.json → sensitive-content-state.json
• Env var NO_REAL_IPS_STATE_FILE → SENSITIVE_CONTENT_STATE_FILE

5-min TTL on the old state file makes the rename self-healing; no
migration code needed.

False-positive notes

The real_domain detector is the highest false-positive risk. The
focused 29-entry REAL_TLDS allowlist is the main mitigation —
anything not ending in a TLD we care about is left alone. Line-level
skips for repo:/image:/markdown link-references handle common
documentation patterns. If churn shows up in practice, the
first-block / second-allow UX gives the agent a clean
acknowledge-and-proceed path.

Related: JacobPEvans/orbstack-kubernetes#234

[gemini-code-assist]

Code Review

This pull request introduces the no-real-ips content guard, which prevents the accidental commitment of live IPv4 addresses by blocking them on the first attempt and requiring a retry within five minutes for acknowledgment. The implementation includes a Python validation script, hook registration, and a comprehensive BATS test suite. Review feedback focuses on hardening the implementation by refining the IPv4 regex to strictly match the 0-255 octet range, ensuring atomic state file writes to prevent corruption during concurrent execution, and normalizing file paths to absolute paths for consistent acknowledgment tracking.