docs: document the v1.5 PHI hook (CHANGELOG, CONTRIBUTING, README)

CHANGELOG.md

@@ -6,6 +6,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.2.1] - 2026-06-22
+
+### Security
+- **PHI pre-commit hook hardened to v1.5.** Closed seven false-negatives in the
+  `hooks/phi_hook.py` gate, each covered by a regression test:
+  a structured-data (`.csv`/`.tsv`/`.psv`) gate for patient line-list exports;
+  value-shaped record rows (`name, DOB-value, id`) that carried no literal `DOB`/`MRN`
+  label; Pattern 1 now scans staged file **paths**, not just content; the disease
+  allowlist now requires **both** slug tokens be clinical; name matching now catches
+  middle initials and apostrophes; the bracket-placeholder allowlist was narrowed so a
+  real bracketed name is no longer immunized; and credential matching now catches
+  prefixed secrets files (`config-secrets.yaml`, `*secrets.json`).
+
+### Added
+- **`hooks/scan-history.py`** — read-only retroactive scanner that applies the same gate
+  across a repo's full git history (the pre-commit hook only guards new commits).
+- Hook test suite expanded to 86 stdlib-unittest cases (zero deps).
+
 ## [1.2.0] - 2026-04-07
 
 ### Added

CONTRIBUTING.md

@@ -44,10 +44,32 @@ We also welcome:
 
 ## Guidelines
 
-- **Don't include personal data.** No real names, addresses, Notion IDs, or calendar details. Use fictional examples if you need to demonstrate something.
+- **Don't include personal data.** No real names, addresses, Notion IDs, or calendar details. Use fictional examples if you need to demonstrate something. This is enforced by a PHI/secret pre-commit hook (see below) — but the hook is a backstop, not a substitute for judgment.
 - **Keep store profiles consistent.** Follow the existing format in `store-profiles.md` so all profiles look the same.
 - **One store per PR** makes review easier, but bundling related stores (e.g., all Kroger subsidiaries) in one PR is fine.
 
+## PHI / secret protection
+
+This repo ships a defense-in-depth gate against committing personal data, credentials, or
+patient information:
+
+- **Pre-commit hook** — install it once per clone:
+  ```sh
+  ln -sf ../../hooks/pre-commit .git/hooks/pre-commit
+  ```
+  It blocks staged credential/env files, PHI-risk binaries, structured-data exports
+  (`.csv`/`.tsv`), and content that looks like a name next to a DOB/MRN. Override only when
+  you're certain it's a false positive: `git commit --no-verify`.
+- **Retroactive audit** — scan a repo's entire history (the hook only guards new commits):
+  ```sh
+  python hooks/scan-history.py
+  ```
+- **Tests** — `python -m unittest discover -s hooks/tests` (86 cases, zero deps). Add a
+  regression test alongside any change to the gate's patterns.
+
+The hook is a heuristic backstop with known limits — it raises the floor, it is not a
+guarantee. Real-name/PHI hygiene is still the contributor's responsibility.
+
 ## Questions?
 
 Open an issue if you're unsure about anything. We'd rather help you contribute than have you give up.

README.md

@@ -160,6 +160,11 @@ parent-helper/
     family-config-example.md         # Example of a fully configured family profile
   examples/
     sunday-briefing-example.md       # Example weekly briefing output
+  hooks/
+    pre-commit                       # Git hook entry point (thin wrapper)
+    phi_hook.py                      # PHI / credential / secret gate (importable)
+    scan-history.py                  # Retroactive full-history PHI scanner
+    tests/                           # 86 stdlib-unittest cases (zero deps)
   assets/
     parent-helper-banner.jpg         # Banner image
 ```
@@ -186,6 +191,19 @@ parent-helper/
 - **Gmail** — for co-parent coordination and partner briefing emails
 - **Chrome MCP** ([Claude in Chrome](https://chromewebstore.google.com/detail/claude-in-chrome/)) — for grocery cart automation and multi-store price scanning
 
+## Privacy & Safety
+
+Parent Helper works with real family data (schedules, names, co-parent details), so the repo
+ships a defense-in-depth gate to keep that data out of commits:
+
+- **`hooks/pre-commit`** blocks staged credential/env files, PHI-risk binaries, structured-data
+  exports (`.csv`/`.tsv`), and content that reads like a name next to a DOB/MRN. Install it
+  per clone: `ln -sf ../../hooks/pre-commit .git/hooks/pre-commit`
+- **`hooks/scan-history.py`** audits a repo's entire history retroactively.
+
+It's a heuristic backstop that raises the floor — not a guarantee. Keep real names and personal
+details out of your config and examples regardless. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## Contributing
 
 Found a way to make Parent Helper better for your family? PRs welcome.