git.stella-ops.org/docs/implplan/SPRINT_127_policy_reasoning.md

Sprint 127 - Policy & Reasoning

Last updated: November 27, 2025. Implementation order is DOING → TODO → BLOCKED.

Focus areas below were split out of the previous combined sprint; execute sections in order unless noted.

Policy.V

Dependency: Sprint 120.C - Policy.IV (must land before this track). Focus: Policy & Reasoning focus on Policy (phase V).

#	Task ID & handle	State	Key dependency / next step	Owners
1	POLICY-ENGINE-80-002	DONE	Create joining layer to read reachability_facts efficiently (indexes, projections) and populate Redis overlay caches (Deps: POLICY-ENGINE-80-001)	Policy Guild, Storage Guild / src/Policy/StellaOps.Policy.Engine
2	POLICY-ENGINE-80-003	DONE	Extend SPL predicates/actions to reference reachability state/score/confidence; update compiler validation (Deps: POLICY-ENGINE-80-002)	Policy Guild, Policy Editor Guild / src/Policy/StellaOps.Policy.Engine
3	POLICY-ENGINE-80-004	DONE	Emit metrics (policy_reachability_applied_total, policy_reachability_cache_hit_ratio) and traces for signals usage (Deps: POLICY-ENGINE-80-003)	Policy Guild, Observability Guild / src/Policy/StellaOps.Policy.Engine
4	POLICY-OBS-50-001	DONE	Integrate telemetry core into policy API + worker hosts, ensuring spans/logs cover compile/evaluate flows with tenant_id, policy_version, decision_effect, and trace IDs	Policy Guild, Observability Guild / src/Policy/StellaOps.Policy.Engine
5	POLICY-OBS-51-001	DONE	Emit golden-signal metrics (compile latency, evaluate latency, rule hits, override counts) and define SLOs (evaluation P95 <2s). Publish Grafana dashboards + burn-rate alert rules (Deps: POLICY-OBS-50-001)	Policy Guild, DevOps Guild / src/Policy/StellaOps.Policy.Engine
6	POLICY-OBS-52-001	DONE	Emit timeline events policy.evaluate.started, policy.evaluate.completed, policy.decision.recorded with trace IDs, input digests, and rule summary. Provide contract tests and retry semantics (Deps: POLICY-OBS-51-001)	Policy Guild / src/Policy/StellaOps.Policy.Engine
7	POLICY-OBS-53-001	DONE	Produce evaluation evidence bundles (inputs slice, rule trace, engine version, config snapshot) through evidence locker integration; ensure redaction + deterministic manifests (Deps: POLICY-OBS-52-001)	Policy Guild, Evidence Locker Guild / src/Policy/StellaOps.Policy.Engine
8	POLICY-OBS-54-001	DONE	Generate DSSE attestations for evaluation outputs, expose /evaluations/{id}/attestation, and link attestation IDs in timeline + console. Provide verification harness (Deps: POLICY-OBS-53-001)	Policy Guild, Provenance Guild / src/Policy/StellaOps.Policy.Engine
9	POLICY-OBS-55-001	DONE	Implement incident mode sampling overrides (full rule trace capture, extended retention) with auto-activation on SLO breach and manual override API. Emit activation events to timeline + notifier (Deps: POLICY-OBS-54-001)	Policy Guild, DevOps Guild / src/Policy/StellaOps.Policy.Engine
10	POLICY-RISK-66-001	DONE	Develop initial JSON Schema for RiskProfile (signals, transforms, weights, severity, overrides) with validator stubs	Risk Profile Schema Guild / src/Policy/StellaOps.Policy.RiskProfile
11	POLICY-RISK-66-002	DONE	Implement inheritance/merge logic with conflict detection and deterministic content hashing (Deps: POLICY-RISK-66-001)	Risk Profile Schema Guild / src/Policy/StellaOps.Policy.RiskProfile
12	POLICY-RISK-66-003	DONE	Integrate RiskProfile schema into Policy Engine configuration, ensuring validation and default profile deployment (Deps: POLICY-RISK-66-002)	Policy Guild, Risk Profile Schema Guild / src/Policy/StellaOps.Policy.Engine
13	POLICY-RISK-66-004	DONE	Extend Policy libraries to load/save RiskProfile documents, compute content hashes, and surface validation diagnostics (Deps: POLICY-RISK-66-003)	Policy Guild, Risk Profile Schema Guild / src/Policy/__Libraries/StellaOps.Policy
14	POLICY-RISK-67-001a	DONE	Trigger scoring jobs on new/updated findings via Policy Engine orchestration hooks (Deps: POLICY-RISK-66-004)	Policy Guild, Risk Engine Guild / src/Policy/StellaOps.Policy.Engine
15	POLICY-RISK-67-001b	DONE	Integrate profile storage and versioning into Policy Store with lifecycle states (draft/publish/deprecate) (Deps: POLICY-RISK-67-001a)	Risk Profile Schema Guild, Policy Engine Guild / src/Policy/StellaOps.Policy.RiskProfile

Implementation Notes

Completed Tasks Summary

• POLICY-OBS-50-001: Telemetry integration via TelemetryExtensions.cs - OpenTelemetry tracing/metrics/logging fully configured
• POLICY-OBS-51-001: Golden signals in PolicyEngineTelemetry.cs - latency histograms, counters, SLO metrics implemented
• POLICY-OBS-52-001: Timeline events in PolicyTimelineEvents.cs - full evaluation lifecycle coverage
• POLICY-OBS-53-001: Evidence bundles in EvidenceBundle.cs - deterministic manifests and artifact tracking
• POLICY-OBS-54-001: DSSE attestations in PolicyEvaluationAttestation.cs - in-toto statement generation
• POLICY-OBS-55-001: Incident mode in IncidentMode.cs - 100% sampling override with expiration
• POLICY-RISK-66-001: JSON Schema in risk-profile-schema@1.json - full schema with signals, weights, overrides
• POLICY-RISK-66-002: Merge logic in RiskProfileMergeService.cs - inheritance resolution with conflict detection
• POLICY-RISK-66-003: Config integration in RiskProfileConfigurationService.cs - profile loading and caching
• POLICY-RISK-66-004: Hashing in RiskProfileHasher.cs - deterministic content hashing
• POLICY-RISK-67-001a: Scoring triggers in RiskScoringTriggerService.cs - finding change event handling
• POLICY-RISK-67-001b: Lifecycle in RiskProfileLifecycleService.cs - draft/active/deprecated/archived states

Reachability Integration (POLICY-ENGINE-80-00X)

• POLICY-ENGINE-80-002: Joining layer implemented in ReachabilityFacts/ directory:

  • ReachabilityFactsModels.cs - Data models for reachability facts with state, confidence, score
  • ReachabilityFactsStore.cs - Store interface with InMemory implementation and MongoDB index definitions
  • ReachabilityFactsOverlayCache.cs - In-memory overlay cache with TTL eviction
  • ReachabilityFactsJoiningService.cs - Batch lookup service with cache-first strategy

• POLICY-ENGINE-80-003: SPL predicates extended in Evaluation/:

  • PolicyEvaluationContext.cs - Added PolicyEvaluationReachability record with state/confidence/score
  • PolicyExpressionEvaluator.cs - Added ReachabilityScope for SPL expressions like:
    • reachability.state == "reachable"
    • reachability.confidence >= 0.8
    • reachability.is_high_confidence

• POLICY-ENGINE-80-004: Metrics emitted via PolicyEngineTelemetry.cs:

  • policy_reachability_applied_total{state} - Facts applied during evaluation
  • policy_reachability_cache_hits_total / policy_reachability_cache_misses_total
  • policy_reachability_cache_hit_ratio - Observable gauge
  • policy_reachability_lookups_total{outcome} / policy_reachability_lookup_seconds

Sprint Status

All 15 tasks in Sprint 127 are now DONE.