docs consolidation and others

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

@@ -0,0 +1,85 @@
+# Risk Profiles
+
+> Contract source: `CONTRACT-RISK-SCORING-002` (published 2025-12-05). This file supersedes `docs/modules/risk-engine/guides/risk-profiles.md` once fixtures are added.
+
+## Purpose
+- Define how profiles group factors, weights, thresholds, and severity bands.
+- Describe authoring, simulation, promotion, rollback, and provenance for profiles.
+
+## Scope & Audience
+- Audience: policy authors, risk engineers, platform SREs.
+- Coverage: profile schema, lifecycle, governance, promotion paths, rollback, and observability hooks.
+
+## Schema (from CONTRACT-RISK-SCORING-002)
+- Required: `id`, `version`, `description`, `signals[]`, `weights`, `metadata`.
+- `signals[]` fields: `name`, `source`, `type` (`numeric|boolean|categorical`), `path`, optional `transform`, optional `unit`.
+- Overrides: `overrides.severity[] { when, set }`, `overrides.decisions[] { when, action, reason }`.
+- Optional: `extends`, rollout flags, tenant overrides, `valid_from`/`valid_until`.
+- Storage rules: immutable once promoted; each change creates a new version with DSSE envelope and SHA256 manifest entry (`docs/modules/risk-engine/samples/profiles/SHA256SUMS`).
+
+### Example Profile (contract snippet)
+```json
+{
+  "id": "default-profile",
+  "version": "1.0.0",
+  "description": "Default risk profile for vulnerability prioritization",
+  "extends": "base-profile",
+  "signals": [
+    { "name": "cvss", "source": "nvd", "type": "numeric", "path": "/cvss/base_score", "transform": "normalize_10", "unit": "score" },
+    { "name": "kev", "source": "cisa", "type": "boolean", "path": "/kev/in_catalog" },
+    { "name": "reachability", "source": "scanner", "type": "numeric", "path": "/reachability/score" }
+  ],
+  "weights": { "cvss": 0.4, "kev": 0.3, "reachability": 0.3 },
+  "overrides": {
+    "severity": [{ "when": { "kev": true }, "set": "critical" }],
+    "decisions": [{ "when": { "kev": true, "reachability": { "$gt": 0.8 } }, "action": "deny", "reason": "KEV with high reachability" }]
+  },
+  "metadata": {}
+}
+```
+
+### Severity Levels
+| Level | Value | Priority |
+| --- | --- | --- |
+| Critical | `critical` | 1 |
+| High | `high` | 2 |
+| Medium | `medium` | 3 |
+| Low | `low` | 4 |
+| Informational | `informational` | 5 |
+
+## Lifecycle (outline)
+1. Authoring in Policy Studio (draft state)
+2. Simulation against fixtures (deterministic inputs)
+3. Review/approval workflow
+4. Promotion to environments (dev → staging → prod)
+5. Rollback hooks and audit trail
+
+## Governance & Determinism
+- Profiles stored with DSSE/signatures; fixtures recorded in `docs/modules/risk-engine/samples/profiles/SHA256SUMS`.
+- Simulation and production share the same evaluation codepath; feature flags must be documented in `metadata.flags`.
+- Offline posture: include profiles, fixtures, and explainability bundles inside mirror packages with manifest hashes.
+
+## Explainability & Observability
+- Per-factor contribution outputs (JSON) with stable ordering (factor type → source).
+- Metrics: evaluation latency (p50/p95), cache hit ratio, factor coverage %, profile hit rate, failed provenance validations.
+- Dashboards/alerts: to be filled when telemetry payloads arrive; reserve panels for gating violations and override usage.
+
+## Open Items
+- Add signed fixtures (profiles + hashes) under `docs/modules/risk-engine/samples/profiles/` once payloads arrive.
+- Capture feature-flag list for registry alignment.
+- Telemetry field list for dashboards/alerts.
+- Finalize migration note when legacy `docs/modules/risk-engine/guides/risk-profiles.md` is archived.
+
+## References
+- `docs/modules/risk-engine/guides/overview.md`
+- `docs/modules/risk-engine/guides/factors.md`
+- `docs/modules/risk-engine/guides/formulas.md`
+- `docs/modules/risk-engine/guides/explainability.md`
+- `docs/modules/risk-engine/guides/api.md`
+- Existing context: `docs/modules/risk-engine/guides/risk-profiles.md` (to reconcile once schema lands)
+
+## Interim Notes (carried from legacy `docs/modules/risk-engine/guides/risk-profiles.md`)
+- Profiles define how evidence (CVSS/EPSS-like exploit likelihood, KEV flags, VEX status, reachability, runtime evidence, fix availability, asset criticality, provenance trust) normalizes into a 0–100 score with severity buckets.
+- Workflow highlights: author in Policy Studio → simulate with fixtures → activate in Policy Engine → explain outputs in CLI/Console → export for auditors via Export Center.
+- Governance: draft/review/approval with DSSE/signatures; rollback hooks and promotion gates enforced by Authority scopes; determinism required (same codepath for simulation and production).
+- Observability: record scoring latency, factor distribution, and profile usage; offline posture via mirror bundles with fixtures and hash manifests.