docs consolidation and others

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

@@ -0,0 +1,62 @@
+# Risk Formulas
+
+> Based on `CONTRACT-RISK-SCORING-002` (2025-12-05). Keep math examples deterministic with fixed fixtures.
+
+## Purpose
+- Describe how normalized factors combine into a 0–100 risk score with severity bands.
+- Capture gating, weighting, normalization, and override rules.
+
+## Scope & Audience
+- Audience: risk engineers, policy authors, auditors.
+- In scope: weighting strategies, aggregation functions, severity thresholds, gating rules, tie-breakers.
+- Out of scope: full API payloads (see `api.md`), factor definitions (see `factors.md`).
+
+## Formula Building Blocks
+- Weighted sum with per-factor caps; enforce max contribution per family (exploitability, reachability, runtime).
+- Base rule (contract): `raw_score = Σ(signal_value × weight)`, `normalized_score = clamp(raw_score, 0.0, 1.0)`.
+- VEX gate: if `signals.HasVexDenial`, return `0.0` immediately (mitigated finding).
+- CVSS + KEV provider: `score = clamp01((cvss/10) + (kev ? 0.2 : 0))`.
+- Guard rails: hard gates when `(exploit_likelihood >= T1) AND (reachability >= T2)` or when provenance trust below minimum.
+- Decay/time weighting: exponential decay for stale runtime/KEV signals; fresh VEX `not_affected` may down-weight exploit scores.
+- Tenant/asset overrides: additive/override blocks with expiry; always logged in explainability output.
+- Safety: divide-by-zero and null handling must be deterministic and reflected in explain trace.
+
+## Severity Mapping
+- Contract levels: `critical`, `high`, `medium`, `low`, `informational` (priority 1–5).
+- Map `normalized_score` to bands per profile policy; include band rationale in explainability payload.
+
+## Determinism
+- Stable ordering of factors before aggregation.
+- Use fixed precision (e.g., 4 decimals) before severity mapping; round not truncate.
+- Hash fixtures and record SHA256 for every example payload in `docs/modules/risk-engine/samples/formulas/SHA256SUMS`.
+
+Interim notes: mirror legacy rule — simulation and production must share the exact evaluation codepath; no per-environment divergences. Severity buckets must be deterministic and governed by Authority scopes.
+
+## Example (contract-aligned)
+```json
+{
+  "finding_id": "f-123",
+  "profile_id": "default-profile",
+  "profile_version": "1.0.0",
+  "raw_score": 0.75,
+  "normalized_score": 0.85,
+  "severity": "high",
+  "signal_values": { "cvss": 7.5, "kev": true, "reachability": 0.9 },
+  "signal_contributions": { "cvss": 0.4, "kev": 0.3, "reachability": 0.3 },
+  "override_applied": "kev-boost",
+  "override_reason": "Known Exploited Vulnerability",
+  "scored_at": "2025-12-05T00:00:02Z"
+}
+```
+- CLI/Console screenshots pending telemetry assets (keep deterministic fixture IDs).
+
+## Open Items
+- Fixtures for jobs/results and explainability traces.
+- Final per-profile severity thresholds (document once agreed).
+- UI traces for console/CLI explainability views.
+
+## 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/api.md`