Harden CHORUS security and messaging stack

docs/decisions/2025-02-16-shhh-sentinel-foundation.md

@@ -0,0 +1,30 @@
+# 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).