more features checks. setup improvements

docs/features/checked/policy/explainability-testing-framework.md

@@ -0,0 +1,42 @@
+# Explainability Testing Framework
+
+## Module
+Policy
+
+## Status
+IMPLEMENTED
+
+## Description
+Explainability testing framework with assertion helpers and verdict rationale rendering, ensuring decisions can be traced back to evidence and assumptions.
+
+## Implementation Details
+- **VerdictRationaleRenderer**: `src/Policy/__Libraries/StellaOps.Policy.Explainability/VerdictRationaleRenderer.cs` (sealed class implements `IVerdictRationaleRenderer`)
+  - `Render(VerdictRationaleInput)` produces structured 4-line rationale with content-addressed RationaleId
+  - `RenderPlainText(rationale)` produces plain text output (4 lines)
+  - `RenderMarkdown(rationale)` produces Markdown with headers (Evidence, Policy Clause, Attestations, Decision)
+  - `RenderJson(rationale)` produces canonical JSON (RFC 8785) via `CanonJson.Serialize`
+  - Content-addressed ID: `rat:sha256:{hash}` computed from SHA256 of canonical JSON (with empty RationaleId for self-referential hashing)
+- **VerdictRationale model**: `src/Policy/__Libraries/StellaOps.Policy.Explainability/VerdictRationale.cs`
+  - 4-line template structure:
+    - Line 1 (`RationaleEvidence`): CVE, Component (PURL, name, version, ecosystem), Reachability (vulnerable function, entry point, path summary)
+    - Line 2 (`RationalePolicyClause`): ClauseId, RuleDescription, Conditions
+    - Line 3 (`RationaleAttestations`): PathWitness, VexStatements, Provenance (each as AttestationReference with Id, Type, Digest, Summary)
+    - Line 4 (`RationaleDecision`): Verdict, Score, Recommendation, Mitigation (Action, Details)
+  - `RationaleInputDigests` for reproducibility: VerdictDigest, PolicyDigest, EvidenceDigest
+  - SchemaVersion: "1.0"
+- **VerdictRationaleInput**: `src/Policy/__Libraries/StellaOps.Policy.Explainability/IVerdictRationaleRenderer.cs`
+  - Full input record with VerdictRef, Cve, Component, Reachability, PolicyClauseId, PolicyRuleDescription, PolicyConditions, attestation references, Verdict, Score, Recommendation, Mitigation, GeneratedAt, digest fields
+- **Property-based tests**: `src/Policy/__Tests/StellaOps.Policy.Determinization.Tests/PropertyTests/DeterminismPropertyTests.cs` -- tests determinism of rationale rendering
+- **Explainability integration tests**: verify that `Render` followed by `RenderPlainText`, `RenderMarkdown`, and `RenderJson` all produce deterministic output for identical inputs
+
+## E2E Test Plan
+- [ ] Render rationale with CVE, component, reachability; verify Evidence.FormattedText contains CVE ID, component name, vulnerable function, entry point
+- [ ] Render rationale with policy clause; verify PolicyClause.FormattedText contains ClauseId and conditions
+- [ ] Render rationale with path witness and VEX statements; verify Attestations.FormattedText includes both references
+- [ ] Render rationale without attestations; verify FormattedText is "No attestations available."
+- [ ] Render rationale with score and mitigation; verify Decision.FormattedText includes score value and mitigation action
+- [ ] Render same input twice; verify RationaleId is identical (content-addressed determinism)
+- [ ] Render different inputs; verify RationaleIds differ
+- [ ] RenderMarkdown produces valid Markdown with ## headers for each section
+- [ ] RenderJson produces valid JSON parseable by standard JSON parser
+- [ ] Verify RationaleId format matches `rat:sha256:{64 hex chars}`