docs consolidation and others

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

@@ -0,0 +1,46 @@
+# Risk Factors
+
+> Aligned to `CONTRACT-RISK-SCORING-002` (published 2025-12-05). Keep fixtures deterministic and offline-friendly.
+
+## Purpose
+- Catalog supported factors (exploit likelihood, VEX state, reachability, runtime facts, fix availability, asset criticality, provenance trust, tenant overrides) and how they normalize into risk math.
+
+## Scope & Audience
+- Audience: risk engineers, policy authors, platform SREs.
+- In scope: factor definitions, required/optional fields, normalization rules, TTLs, provenance expectations.
+- Out of scope: full formula math (see `formulas.md`), API wiring (see `api.md`).
+
+## Factor Catalog (mirrors profile `signals[]`)
+| Factor | Required fields | Optional fields | Notes |
+| --- | --- | --- | --- |
+| CVSS / exploit likelihood | `name`, `source`, `type:"numeric"`, `path`, `transform:"normalize_10"` | `unit:"score"`, `last_seen`, `confidence` | Normalize 0–10 to 0–1; clamp and keep original in provenance. |
+| KEV flag | `name`, `source`, `type:"boolean"`, `path` | `last_seen` | Boolean boost; drives severity overrides/decisions. |
+| Reachability | `name`, `source`, `type:"numeric"`, `path` | `unit:"score"`, `guards` | May fuse static reachability + runtime observation; ordered by entrypoint/path hash. |
+| Runtime facts | `name`, `source`, `type:"categorical" or "numeric"`, `path` | `trace_id`, `span_id` | Includes host/container identity and provenance for runtime traces. |
+| Fix availability | `name`, `source`, `type`, `path` | `mitigation`, `vendor_status` | Decay older advisories; keep mitigation text intact. |
+| Asset criticality | `name`, `source`, `type`, `path` | `tenant_scope`, `owner` | Used as multiplier/guard in formulas. |
+| Provenance trust | `name`, `source`, `type:"categorical"`, `path` | `key_id`, `chain_of_custody` | Gate low-trust inputs; must carry attestation hash. |
+| Custom overrides | `name`, `source`, `type`, `path` | `override_reason`, `reviewer`, `expires_at` | Logged and expiring; surfaced in `signal_contributions`. |
+
+## Normalization Rules
+- Validate against profile `signals.type` and known transforms; reject unknown fields.
+- Clamp numeric inputs to 0–1; record original value in provenance for audit.
+- TTL/decay: apply per-factor defaults (pending payload fixtures); drop expired signals deterministically.
+- Precedence: signed → unsigned; runtime → static; newer → older; when tied, lowest hash order.
+
+Interim notes: follow legacy profile guidance — preserve provenance, never mutate source evidence, and keep ordering stable so explainability hashes are repeatable across UI/CLI/exports.
+
+## Determinism & Ordering
+- Sort factors by `factor_type` then `source` then `timestamp_utc`; deterministic hashing for fixtures.
+- Record SHA256 for sample payloads in `docs/modules/risk-engine/samples/factors/SHA256SUMS` once provided.
+
+## Open Items
+- Sample payloads per factor for fixtures + hashes.
+- TTL/decay parameters from Risk Engine Guild.
+- Provenance attestation examples (signed runtime traces, KEV ingestion evidence).
+
+## References
+- `docs/modules/risk-engine/guides/overview.md`
+- `docs/modules/risk-engine/guides/profiles.md`
+- `docs/modules/risk-engine/guides/formulas.md`
+- `docs/modules/risk-engine/guides/api.md`