up

docs/uncertainty/README.md

@@ -224,5 +224,103 @@ Extended schema with tier information:
 
 - **Tier calculation:** `UncertaintyTierCalculator` in `src/Signals/StellaOps.Signals/Services/`
 - **Risk score math:** `ReachabilityScoringService.ComputeRiskScore()` (extend existing)
-- **Policy integration:** `docs/reachability/policy-gate.md` for gate rules
+- **Policy integration:** `docs/policy/dsl.md` §12 for uncertainty gates
 - **Lattice integration:** `docs/reachability/lattice.md` §9 for v1 lattice states
+
+---
+
+## 8. Policy Guidance (v1 — Sprint 0401)
+
+Uncertainty gates enforce evidence-quality thresholds in the Policy Engine. When entropy is too high or evidence is missing, policies block or downgrade VEX decisions.
+
+### 8.1 Gate Mapping
+
+| Gate | Uncertainty State | Tier | Policy Action |
+|------|------------------|------|---------------|
+| `U1` | `MissingSymbolResolution` | T1/T2 | Block `not_affected`, require review |
+| `U2` | `MissingPurl` | T2/T3 | Warn on `not_affected`, add review flag |
+| `U3` | `UntrustedAdvisory` | T3/T4 | Advisory caveat, no blocking |
+
+### 8.2 Sample Policy Rules
+
+```dsl
+// Block not_affected when symbol resolution has high entropy
+rule u1_gate_high_entropy priority 5 {
+  when signals.uncertainty.level == "U1"
+       and signals.uncertainty.entropy >= 0.7
+  then status := "under_investigation"
+       annotate gate := "U1"
+       annotate remediation := "Upload symbols or close unknowns registry"
+  because "High symbol entropy blocks strong VEX claims";
+}
+
+// Tier-based compound gate
+rule tier1_block_not_affected priority 3 {
+  when signals.uncertainty.aggregateTier == "T1"
+       and vex.any(status == "not_affected")
+  then status := "under_investigation"
+       annotate blocked_reason := "T1 uncertainty requires evidence"
+  because "Maximum uncertainty tier blocks all exclusion claims";
+}
+```
+
+### 8.3 YAML Configuration
+
+```yaml
+uncertainty_gates:
+  u1_gate:
+    entropy_threshold: 0.7
+    blocked_statuses: [not_affected]
+    fallback_status: under_investigation
+    remediation_hint: "Upload symbols or resolve unknowns"
+  u2_gate:
+    entropy_threshold: 0.4
+    blocked_statuses: [not_affected]
+    warn_on_block: true
+  u3_gate:
+    entropy_threshold: 0.1
+    annotate_caveat: true
+```
+
+See `docs/policy/dsl.md` §12 for complete gate rules and tier-aware compound patterns.
+
+---
+
+## 9. Remediation Actions
+
+Each uncertainty state has recommended remediation steps:
+
+| State | Code | Remediation | CLI Command |
+|-------|------|-------------|-------------|
+| MissingSymbolResolution | `U1` | Upload debug symbols, resolve unknowns | `stella symbols ingest --path <symbols>` |
+| MissingPurl | `U2` | Generate lockfile, verify package coordinates | `stella sbom refresh --resolve` |
+| UntrustedAdvisory | `U3` | Cross-reference trusted sources | `stella advisory verify --source NVD,GHSA` |
+| Unknown | `U4` | Run initial analysis | `stella scan --full` |
+
+### 9.1 Automated Remediation Flow
+
+```
+1. Policy blocks decision with U1/U2 gate
+   ↓
+2. Console/CLI shows remediation hint
+   ↓
+3. User runs remediation command (e.g., stella symbols ingest)
+   ↓
+4. Signals recomputes uncertainty states
+   ↓
+5. Risk score updates, tier may drop
+   ↓
+6. Policy re-evaluates, decision may proceed
+```
+
+### 9.2 Remediation Priority
+
+When multiple uncertainty states exist, prioritize by tier:
+
+1. **T1 states first** — Block all exclusions until resolved
+2. **T2 states** — May proceed with warnings if T1 cleared
+3. **T3/T4 states** — Normal flow with caveats
+
+---
+
+*Last updated: 2025-12-13 (Sprint 0401).*