save checkpoint

docs/features/checked/policy/security-state-delta.md

@@ -0,0 +1,41 @@
+# Security State Delta (Diff Engine)
+
+## Module
+Policy
+
+## Status
+IMPLEMENTED
+
+## Description
+A diff engine that takes baseline and target snapshot digests and produces structured delta objects with baseline selection methods (previous build, last approved, last deployed).
+
+## Implementation Details
+- **WhatIfSimulationService**: `src/Policy/StellaOps.Policy.Engine/WhatIfSimulation/WhatIfSimulationService.cs`
+  - `SimulateAsync()` computes baseline vs target deltas
+  - Baseline selection: current artifact state as baseline, simulated changes as target
+  - Delta objects: decision changes (status_changed, severity_changed, new, removed)
+  - Impact summary: risk delta (increased/decreased/unchanged), blocked/warning deltas
+- **ConsoleSimulationDiffService**: `src/Policy/StellaOps.Policy.Engine/Console/ConsoleSimulationDiffService.cs`
+  - Schema version: console-policy-23-001
+  - Structured before/after delta with severity breakdowns
+  - Rule impact analysis: which policy rules drove the delta
+  - Deterministic output for same inputs
+- **DriftGateEvaluator**: `src/Policy/StellaOps.Policy.Engine/Gates/DriftGateEvaluator.cs`
+  - SBOM drift detection between baseline and target snapshots
+  - Produces structured drift delta with component additions/removals/upgrades
+- **DriftGateContext**: `src/Policy/StellaOps.Policy.Engine/Gates/DriftGateContext.cs` -- context for drift evaluation with baseline/target digests
+- **KnowledgeSnapshotManifest**: `src/Policy/__Libraries/StellaOps.Policy/Snapshots/KnowledgeSnapshotManifest.cs`
+  - Content-addressed snapshots enable diff between any two evaluation states
+  - Baseline selection via SnapshotId comparison
+
+## E2E Test Plan
+- [ ] Compute delta between baseline and target with 2 new critical findings; verify delta shows 2 new findings with severity=Critical
+- [ ] Compute delta between baseline and target with 1 resolved finding; verify delta shows 1 removed finding
+- [ ] Compute delta with severity change (High->Critical); verify delta shows severity_changed
+- [ ] Compute delta with status change (Warn->Block); verify delta shows status_changed
+- [ ] Select baseline as "previous build"; verify correct baseline snapshot used
+- [ ] Select baseline as "last approved"; verify correct baseline snapshot used
+- [ ] Verify delta includes risk delta (increased/decreased/unchanged) summary
+- [ ] Verify ConsoleSimulationDiffService produces deterministic delta for same inputs
+- [ ] Verify DriftGateEvaluator detects component additions in SBOM drift
+- [ ] Verify delta is empty when baseline and target are identical