# Decision Record: Establish SHHH Sentinel Foundations

- **Date:** 2025-02-16
- **Status:** Accepted
- **Context:** CHORUS roadmap Phase 1 requires a secrets sentinel (`pkg/shhh`) before we wire COOEE/WHOOSH telemetry and audit plumbing. The runtime previously emitted placeholder TODOs and logged sensitive payloads without guard rails.

## Problem
- We lacked a reusable component to detect and redact secrets prior to log/telemetry fan-out.
- Without a dedicated sentinel we could not attach audit sinks or surface metrics for redaction events, blocking roadmap item `SEC-SHHH`.

## Decision
- Introduce `pkg/shhh` as the SHHH sentinel with:
  - Curated default rules (API keys, bearer/OAuth tokens, private key PEM blocks, OpenAI secrets).
  - Extensible configuration for custom regex rules and per-rule severity/tags.
  - Optional audit sink and statistics collection for integration with COOEE/WHOOSH pipelines.
  - Helpers to redact free-form text and `map[string]any` payloads used by our logging pipeline.

## Rationale
- Starting with a focused set of high-signal rules gives immediate coverage for the most damaging leak classes without delaying larger SLURP/SHHH workstreams.
- The API mirrors other CHORUS subsystems (options, config structs, stats snapshots) so existing operators can plug metrics/audits without bespoke glue.
- Providing deterministic findings/locations simplifies future enforcement (e.g., WHOOSH UI badges, COOEE replay) while keeping implementation lean.

## Impact
- Runtime components can now instantiate SHHH and guarantee `[REDACTED]` placeholders for sensitive fields.
- Audit/event plumbing can be wired incrementally—hashes are emitted for replay without storing raw secrets.
- Future roadmap tasks (policy driven rules, replay, UCXL evidence) can extend `pkg/shhh` rather than implementing ad-hoc redaction in each subsystem.

## Related Work
- Roadmap: `docs/progress/CHORUS-WHOOSH-roadmap.md` (Phase 1.2 `SEC-SHHH`).
- README coverage gap noted in `README.md` table (SHHH not implemented).