docs consolidation and others

docs/modules/risk-engine/guides/explainability.md

@@ -0,0 +1,35 @@
+# Risk Explainability
+
+> Source: `CONTRACT-RISK-SCORING-002` (2025-12-05). Fixtures live under `docs/modules/risk-engine/samples/explain/`; all hashes in `SHA256SUMS`. Keep outputs deterministic (frozen payloads, stable ordering).
+
+## Purpose
+- Show how the scoring engine produces per-factor contributions and traces that UI/CLI/export surfaces render for auditors and operators.
+
+## Scope & Audience
+- Audience: Console/CLI users, auditors, SREs.
+- In scope: explainability payload shape, field meanings, provenance, UI/CLI mapping, offline/export behavior.
+- Out of scope: formula math (see `formulas.md`), API specifics (see `api.md`).
+
+## Payload Shape
+- Envelope: `job_id`, `tenant_id`, `context_id`, `profile_id`, `profile_version`, `profile_hash`, `finding_id`, `raw_score`, `normalized_score`, `severity`, `signal_values{}`, `signal_contributions{}`, optional `override_applied`, `override_reason`, `gates_triggered[]`, `scored_at`, `provenance` (job hash + fixture hashes).
+- Factor entries (from `signal_values`/`signal_contributions`): `name`, `source`, `type`, `path`, `raw_value`, `normalized_value`, `weight`, `contribution`, `provenance`.
+- UI/CLI expectations: deterministic ordering (factor type → source → timestamp), highlight top contributors, show attestation status for each factor.
+
+## UI/CLI Views
+- Console: frame sample in `docs/modules/risk-engine/samples/explain/console-frame.json` shows top contributors, gate badges, and provenance hashes.
+- CLI `stella risk explain job-001`: deterministic text fixture in `docs/modules/risk-engine/samples/explain/cli-explain.txt`; `--json` mirrors `explain-trace.json`.
+- Export Center: embed explain payload + SHA256 manifest; CSV export keeps deterministic ordering.
+
+## Determinism & Offline Posture
+- Example payload: `docs/modules/risk-engine/samples/explain/explain-trace.json` (hash in `SHA256SUMS`).
+- No live calls; all captures from frozen fixtures. Use exact ordering and timestamps when regenerating.
+
+## Open Items
+- Add schema file once JSON schema is frozen; update references accordingly.
+
+## References
+- `docs/modules/risk-engine/guides/overview.md`
+- `docs/modules/risk-engine/guides/profiles.md`
+- `docs/modules/risk-engine/guides/factors.md`
+- `docs/modules/risk-engine/guides/formulas.md`
+- `docs/modules/risk-engine/guides/api.md`