# Risk Explainability

> Source: `CONTRACT-RISK-SCORING-002` (2025-12-05). Fixtures live under `docs/risk/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/risk/samples/explain/console-frame.json` shows top contributors, gate badges, and provenance hashes.
- CLI `stella risk explain job-001`: deterministic text fixture in `docs/risk/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/risk/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/risk/overview.md`
- `docs/risk/profiles.md`
- `docs/risk/factors.md`
- `docs/risk/formulas.md`
- `docs/risk/api.md`