move docs/**/archived/* to docs-archived/**/*

2026-01-05 16:02:11 +02:00
parent dfab8a29c3
commit d0a7b88398
1083 changed files with 4 additions and 1 deletions
--- a/docs-archived/implplan/2026-01-04-completed-sprints/SPRINT_20260104_001_BE_adaptive_noise_gating.md
+++ b/docs-archived/implplan/2026-01-04-completed-sprints/SPRINT_20260104_001_BE_adaptive_noise_gating.md
@@ -0,0 +1,195 @@
+# Sprint 20260104_001_BE - Adaptive Noise-Gating for Vulnerability Graphs
+
+## Topic & Scope
+
+Implement adaptive noise-gating for vulnerability graphs to reduce alert fatigue and improve triage UX. The feature enables:
+
+1. **Semantic Edge Deduplication**: Collapse redundant edges from multiple sources into single edges with provenance sets
+2. **Proof Strength Hierarchy**: Formalize evidence authority ordering (Authority > Binary > Static > Heuristic)
+3. **Stability Damping**: Prevent flip-flopping verdicts through hysteresis-based state transitions
+4. **Delta Reports**: Surface only meaningful changes with typed sections (New, Resolved, ConfidenceUp, ConfidenceDown, PolicyImpact)
+
+**Working directory:** `src/__Libraries/`, `src/VexLens/`, `src/Policy/`
+
+## Dependencies & Concurrency
+
+- Builds on existing `VexConsensusEngine`, `PolicyGateEvaluator`, and `NoisePriorService`
+- No external dependencies; integrates with existing modules
+- Tasks can be executed in parallel across modules
+
+## Documentation Prerequisites
+
+- docs/README.md
+- docs/07_HIGH_LEVEL_ARCHITECTURE.md
+- docs/modules/platform/architecture-overview.md
+- CLAUDE.md (especially Section 8: Code Quality & Determinism Rules)
+
+## Delivery Tracker
+
+| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
+| --- | --- | --- | --- | --- | --- |
+| 1 | NG-001 | DONE | None | Guild | Add ProofStrength enum to StellaOps.Evidence.Core |
+| 2 | NG-002 | DONE | NG-001 | Guild | Add ProofStrength field to EvidenceRecord |
+| 3 | NG-003 | DONE | None | Guild | Create EdgeSemanticKey and deduplication logic in ReachGraph |
+| 4 | NG-004 | DONE | None | Guild | Add StabilityDampingGate to Policy.Engine.Gates |
+| 5 | NG-005 | DONE | NG-004 | Guild | Add StabilityDampingOptions with configurable thresholds |
+| 6 | NG-006 | DONE | None | Guild | Create DeltaSection enum in VexLens |
+| 7 | NG-007 | DONE | NG-006 | Guild | Extend VexDelta with section categorization |
+| 8 | NG-008 | DONE | NG-001,NG-003,NG-004,NG-006 | Guild | Create INoiseGate interface and NoiseGateService |
+| 9 | NG-009 | DONE | NG-008 | Guild | Add DI registration in VexLensServiceCollectionExtensions |
+| 10 | NG-010 | DONE | All | Guild | Add unit tests for all new components |
+| 11 | NG-011 | DONE | NG-010 | Guild | Update module AGENTS.md files |
+
+## Task Details
+
+### NG-001: ProofStrength Enum
+
+Add `ProofStrength` enum to formalize evidence authority hierarchy:
+
+```csharp
+public enum ProofStrength
+{
+    Authoritative = 100,  // Vendor VEX, CSAF publisher
+    BinaryProof = 80,     // Patch signature, binary analysis
+    StaticAnalysis = 60,  // Reachability, call graph
+    Heuristic = 40        // Version matching, advisory correlation
+}
+```
+
+Location: `src/__Libraries/StellaOps.Evidence/ProofStrength.cs`
+
+### NG-002: EvidenceRecord Extension
+
+Add optional `ProofStrength` field to existing evidence models for backward compatibility.
+
+### NG-003: Edge Semantic Key
+
+Create semantic key for edge deduplication:
+
+```csharp
+public readonly record struct EdgeSemanticKey(
+    string EntryPointId,
+    string SinkId,
+    string VulnerabilityId,
+    string? GateApplied)
+{
+    public string ComputeKey() =>
+        $"{EntryPointId}|{SinkId}|{VulnerabilityId}|{GateApplied ?? "none"}";
+}
+```
+
+Location: `src/__Libraries/StellaOps.ReachGraph/Deduplication/`
+
+### NG-004: StabilityDampingGate
+
+Implement hysteresis-based gate that:
+- Tracks last verdict state per (artifact, CVE) tuple
+- Requires score to persist for N hours OR change by X% before state transition
+- Prevents flip-flopping notifications
+
+Location: `src/Policy/StellaOps.Policy.Engine/Gates/StabilityDampingGate.cs`
+
+### NG-005: StabilityDampingOptions
+
+Configuration options:
+- `MinDurationBeforeChange`: TimeSpan (default: 4 hours)
+- `MinConfidenceDeltaPercent`: double (default: 15%)
+- `EnabledStatuses`: List of VexStatus to apply damping
+
+### NG-006: DeltaSection Enum
+
+Categorize delta entries for UX:
+
+```csharp
+public enum DeltaSection
+{
+    New,              // First-time finding
+    Resolved,         // Status changed to not_affected/fixed
+    ConfidenceUp,     // Confidence increased significantly
+    ConfidenceDown,   // Confidence decreased significantly
+    PolicyImpact      // Gate decision changed
+}
+```
+
+### NG-007: VexDelta Extension
+
+Extend existing VexDelta with section categorization and aggregate summary.
+
+### NG-008: INoiseGate Interface
+
+Central interface for noise-gating operations:
+
+```csharp
+public interface INoiseGate
+{
+    Task<IReadOnlyList<Edge>> DedupeEdgesAsync(
+        IReadOnlyList<Edge> edges,
+        CancellationToken ct = default);
+
+    Task<Verdict> ResolveNodeAsync(
+        string nodeId,
+        IReadOnlyList<Evidence> evidences,
+        CancellationToken ct = default);
+
+    Task<GraphSnapshot> GateAsync(
+        GraphSnapshot raw,
+        CancellationToken ct = default);
+
+    Task<DeltaReport> DiffAsync(
+        GraphSnapshot previous,
+        GraphSnapshot current,
+        CancellationToken ct = default);
+}
+```
+
+### NG-009: DI Registration
+
+Register services in `VexLensServiceCollectionExtensions`:
+
+```csharp
+services.AddSingleton<INoiseGate, NoiseGateService>();
+services.AddOptions<StabilityDampingOptions>()
+    .Bind(config.GetSection("NoiseGate:StabilityDamping"))
+    .ValidateDataAnnotations()
+    .ValidateOnStart();
+```
+
+### NG-010: Unit Tests
+
+Required test coverage:
+- Edge deduplication with multi-source inputs
+- Proof strength ordering in verdict resolution
+- Hysteresis behavior (flip-flop prevention)
+- Delta section categorization
+- Determinism (same inputs = same outputs)
+
+### NG-011: AGENTS.md Updates
+
+Update module documentation:
+- `src/VexLens/AGENTS.md`
+- `src/Policy/AGENTS.md`
+- `src/__Libraries/StellaOps.Evidence/AGENTS.md`
+
+## Decisions & Risks
+
+| Decision | Rationale |
+|----------|-----------|
+| Use ProofStrength instead of EvidenceClass | Avoids naming collision with existing EvidenceType enum |
+| Integrate with existing VexConsensusEngine | Leverages proven consensus logic rather than creating parallel infrastructure |
+| Make damping optional per-status | Production environments can enable for affected/not_affected but skip for under_investigation |
+| Store dedup metadata for audit | Provenance tracking required for transparency |
+
+## Execution Log
+
+| Date | Action | Notes |
+|------|--------|-------|
+| 2026-01-04 | Sprint created | Based on product advisory review |
+| 2026-01-04 | NG-001,NG-002 | Created ProofStrength enum, ProofStrengthExtensions, ProofRecord in StellaOps.Evidence.Models |
+| 2026-01-04 | NG-003 | Created EdgeSemanticKey, DeduplicatedEdge, EdgeDeduplicator in StellaOps.ReachGraph.Deduplication |
+| 2026-01-04 | NG-004,NG-005 | Created StabilityDampingGate, StabilityDampingOptions in StellaOps.Policy.Engine.Gates |
+| 2026-01-04 | NG-006,NG-007 | Created DeltaSection, DeltaEntry, DeltaReport, DeltaReportBuilder in StellaOps.VexLens.Delta |
+| 2026-01-04 | NG-008,NG-009 | Created INoiseGate, NoiseGateService, NoiseGateOptions; registered DI in VexLensServiceCollectionExtensions |
+| 2026-01-04 | NG-010 | Added StabilityDampingGateTests, NoiseGateServiceTests, DeltaReportBuilderTests |
+| 2026-01-04 | NG-011 | Updated VexLens and Policy.Engine AGENTS.md files |
+| 2026-01-04 | Sprint complete | All 11 tasks DONE |
+