sprints completion. new product advisories prepared

2026-01-16 16:30:03 +02:00
parent a927d924e3
commit 4ca3ce8fb4
255 changed files with 42434 additions and 1020 deletions
--- a/docs/operations/unknowns-queue-runbook.md
+++ b/docs/operations/unknowns-queue-runbook.md
@@ -628,9 +628,150 @@ To allow approved exceptions to cover specific unknown reason codes, set excepti
 - [Triage Technical Reference](../product/advisories/14-Dec-2025%20-%20Triage%20and%20Unknowns%20Technical%20Reference.md)
 - [Score Proofs Runbook](./score-proofs-runbook.md)
 - [Policy Engine](../modules/policy/architecture.md)
+- [Determinization API](../modules/policy/determinization-api.md)
+- [VEX Consensus Guide](../VEX_CONSENSUS_GUIDE.md)

 ---

-**Last Updated**: 2025-12-22  
-**Version**: 1.0.0  
-**Sprint**: 3500.0004.0004
+## 8. Grey Queue Operations
+
+> **Sprint**: SPRINT_20260112_010_CLI_unknowns_grey_queue_cli
+
+The Grey Queue handles observations with uncertain status requiring operator attention or additional evidence. These are distinct from standard HOT/WARM/COLD band unknowns.
+
+### 8.1 Grey Queue Overview
+
+Grey Queue items have:
+- **Observation state**: `PendingDeterminization`, `Disputed`, or `GuardedPass`
+- **Reanalysis fingerprint**: Deterministic ID for reproducible replays
+- **Triggers**: Events that caused reanalysis
+- **Conflicts**: Detected evidence disagreements
+- **Next actions**: Suggested resolution paths
+
+### 8.2 List Grey Queue Items
+
+```bash
+# List all grey queue items
+stella unknowns list --state grey
+
+# List by observation state
+stella unknowns list --observation-state pending-determinization
+stella unknowns list --observation-state disputed
+stella unknowns list --observation-state guarded-pass
+
+# List with fingerprint details
+stella unknowns list --state grey --show-fingerprint
+
+# List with conflict summary
+stella unknowns list --state grey --show-conflicts
+```
+
+### 8.3 View Grey Queue Details
+
+```bash
+# Show grey queue item with full details
+stella unknowns show unk-12345678-... --grey
+
+# Output:
+# ID: unk-12345678-...
+# Observation State: Disputed
+# 
+# Reanalysis Fingerprint:
+#   ID: sha256:abc123...
+#   Computed At: 2026-01-15T10:00:00Z
+#   Policy Config Hash: sha256:def456...
+# 
+# Triggers (2):
+#   - epss.updated@1 (2026-01-15T09:55:00Z) delta=0.15
+#   - vex.updated@1 (2026-01-15T09:50:00Z)
+# 
+# Conflicts (1):
+#   - VexStatusConflict: vendor-a reports 'not_affected', vendor-b reports 'affected'
+#     Severity: high
+#     Adjudication: manual_review
+# 
+# Next Actions:
+#   - trust_resolution: Resolve issuer trust conflict
+#   - manual_review: Escalate to security team
+
+# Show fingerprint only
+stella unknowns fingerprint unk-12345678-...
+
+# Show triggers only
+stella unknowns triggers unk-12345678-...
+```
+
+### 8.4 Grey Queue Triage Actions
+
+```bash
+# Resolve a grey queue item (operator determination)
+stella unknowns resolve unk-12345678-... \
+  --status not_affected \
+  --justification "Verified vendor VEX is authoritative" \
+  --evidence-ref "vex-observation-id-123"
+
+# Escalate for manual review
+stella unknowns escalate unk-12345678-... \
+  --priority P1 \
+  --reason "Conflicting VEX requires security team decision"
+
+# Defer pending additional evidence
+stella unknowns defer unk-12345678-... \
+  --await vex \
+  --reason "Waiting for upstream vendor VEX statement"
+```
+
+### 8.5 Grey Queue Conflict Resolution
+
+```bash
+# List items with conflicts
+stella unknowns list --has-conflicts
+
+# Filter by conflict type
+stella unknowns list --conflict-type vex-status-conflict
+stella unknowns list --conflict-type vex-reachability-contradiction
+stella unknowns list --conflict-type trust-tie
+
+# Resolve a conflict manually
+stella unknowns resolve-conflict unk-12345678-... \
+  --winner vendor-a \
+  --reason "vendor-a is the upstream maintainer"
+```
+
+### 8.6 Grey Queue Summary
+
+```bash
+# Get grey queue summary
+stella unknowns summary --grey
+
+# Output:
+# Grey Queue: 23 items
+# 
+# By State:
+#   PendingDeterminization: 15 (65%)
+#   Disputed: 5 (22%)
+#   GuardedPass: 3 (13%)
+# 
+# Conflicts: 8 items have conflicts
+# Avg. Triggers: 2.3 per item
+# Oldest: 7 days
+```
+
+### 8.7 Grey Queue Export
+
+```bash
+# Export grey queue for analysis
+stella unknowns export --state grey --format json --output grey-queue.json
+
+# Export with full fingerprints and triggers
+stella unknowns export --state grey --verbose --output grey-full.json
+
+# Export conflicts only
+stella unknowns export --has-conflicts --format csv --output conflicts.csv
+```
+
+---
+
+**Last Updated**: 2026-01-16  
+**Version**: 1.1.0  
+**Sprint**: SPRINT_20260112_010_CLI_unknowns_grey_queue_cli