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

Sprint 126 - Policy & Reasoning

Last updated: November 8, 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.IV

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

#	Task ID & handle	State	Key dependency / next step	Owners
1	POLICY-ENGINE-40-003	DONE	Provide API/SDK utilities for consumers (Web Scanner, Graph Explorer) to request policy decisions with source evidence summaries (top severity sources, conflict counts) (Deps: POLICY-ENGINE-40-002)	Policy Guild, Web Scanner Guild / src/Policy/StellaOps.Policy.Engine
2	POLICY-ENGINE-50-001	DONE	Implement SPL compiler: validate YAML, canonicalize, produce signed bundle, store artifact in object storage, write policy_revisions with AOC metadata (Deps: POLICY-ENGINE-40-003)	Policy Guild, Platform Security / src/Policy/StellaOps.Policy.Engine
3	POLICY-ENGINE-50-002	TODO	Build runtime evaluator executing compiled plans over advisory/vex linksets + SBOM asset metadata with deterministic caching (Redis) and fallback path (Deps: POLICY-ENGINE-50-001)	Policy Guild, Runtime Guild / src/Policy/StellaOps.Policy.Engine
4	POLICY-ENGINE-50-003	TODO	Implement evaluation/compilation metrics, tracing, and structured logs (policy_eval_seconds, policy_compiles_total, explanation sampling) (Deps: POLICY-ENGINE-50-002)	Policy Guild, Observability Guild / src/Policy/StellaOps.Policy.Engine
5	POLICY-ENGINE-50-004	TODO	Build event pipeline: subscribe to linkset/SBOM updates, schedule re-eval jobs, emit policy.effective.updated events with diff metadata (Deps: POLICY-ENGINE-50-003)	Policy Guild, Platform Events Guild / src/Policy/StellaOps.Policy.Engine
6	POLICY-ENGINE-50-005	TODO	Design and implement policy_packs, policy_revisions, policy_runs, policy_artifacts collections with indexes, TTL, and tenant scoping (Deps: POLICY-ENGINE-50-004)	Policy Guild, Storage Guild / src/Policy/StellaOps.Policy.Engine
7	POLICY-ENGINE-50-006	TODO	Implement explainer persistence + retrieval APIs linking decisions to explanation tree and AOC chain (Deps: POLICY-ENGINE-50-005)	Policy Guild, QA Guild / src/Policy/StellaOps.Policy.Engine
8	POLICY-ENGINE-50-007	TODO	Provide evaluation worker host/DI wiring and job orchestration hooks for batch re-evaluations after policy activation (Deps: POLICY-ENGINE-50-006)	Policy Guild, Scheduler Worker Guild / src/Policy/StellaOps.Policy.Engine
9	POLICY-ENGINE-60-001	TODO	Maintain Redis effective decision maps per asset/snapshot for Graph overlays; implement versioning and eviction strategy (Deps: POLICY-ENGINE-50-007)	Policy Guild, SBOM Service Guild / src/Policy/StellaOps.Policy.Engine
10	POLICY-ENGINE-60-002	TODO	Expose simulation bridge for Graph What-if APIs, supporting hypothetical SBOM diffs and draft policies without persisting results (Deps: POLICY-ENGINE-60-001)	Policy Guild, BE-Base Platform Guild / src/Policy/StellaOps.Policy.Engine
11	POLICY-ENGINE-70-002	TODO	Design and create Mongo collections (exceptions, exception_reviews, exception_bindings) with indexes and migrations; expose repository APIs (Deps: POLICY-ENGINE-60-002)	Policy Guild, Storage Guild / src/Policy/StellaOps.Policy.Engine
12	POLICY-ENGINE-70-003	TODO	Build Redis exception decision cache (exceptions_effective_map) with warm/invalidation logic reacting to exception.* events (Deps: POLICY-ENGINE-70-002)	Policy Guild, Runtime Guild / src/Policy/StellaOps.Policy.Engine
13	POLICY-ENGINE-70-004	TODO	Extend metrics/tracing/logging for exception application (latency, counts, expiring events) and include AOC references in logs (Deps: POLICY-ENGINE-70-003)	Policy Guild, Observability Guild / src/Policy/StellaOps.Policy.Engine
14	POLICY-ENGINE-70-005	TODO	Provide APIs/workers hook for exception activation/expiry (auto start/end) and event emission (exception.activated/expired) (Deps: POLICY-ENGINE-70-004)	Policy Guild, Scheduler Worker Guild / src/Policy/StellaOps.Policy.Engine
15	POLICY-ENGINE-80-001	TODO	Integrate reachability/exploitability inputs into evaluation pipeline (state/score/confidence) with caching and explain support (Deps: POLICY-ENGINE-70-005)	Policy Guild, Signals Guild / src/Policy/StellaOps.Policy.Engine
16	POLICY-RISK-90-001	TODO	Ingest entropy penalty inputs from Scanner (entropy.report.json, layer_summary.json), extend trust algebra with configurable weights/caps, and expose explanations/metrics for opaque ratio penalties (docs/modules/scanner/entropy.md).	Policy Guild, Scanner Guild / src/Policy/StellaOps.Policy.Engine

Notes & Risks (2025-11-27)

• POLICY-ENGINE-40-003 implementation complete: Added PolicyDecisionModels.cs, PolicyDecisionService.cs, PolicyDecisionEndpoint.cs, and PolicyDecisionServiceTests.cs. Service registered in Program.cs. All 9 tests pass.
• POLICY-ENGINE-50-001 implementation complete: Extended SPL compiler with AOC (Attestation of Compliance) metadata support:
  • Added PolicyAocMetadata, PolicyProvenance, PolicyAttestationRef records to PolicyPackRecord.cs
  • Added PolicyProvenanceInput, PolicyAocMetadataResponse to PolicyBundleModels.cs
  • Updated PolicyBundleService to capture compilation ID, source/artifact digests, complexity metrics, provenance
  • Added 4 new tests for AOC metadata in PolicyBundleServiceTests.cs (all pass)
  • Existing YAML validation via PolicyBinder, canonicalization via PolicyCompilationService, signed bundles via PolicyBundleService, storage via IPolicyPackRepository all integrate with new AOC metadata
• Pre-existing test issue: EvidenceSummaryServiceTests.Summarize_BuildsDeterministicSummary fails due to date derivation mismatch (unrelated to current changes)
• Pre-existing build issues resolved:
  • StellaOps.Telemetry.Core: Fixed TelemetryContext API (added CorrelationId/TraceId aliases, Current/Context property aliases), added Grpc.AspNetCore package, removed duplicate FrameworkReference.
  • StellaOps.Policy.RiskProfile: Fixed JsonSchema.Net v5 API changes (ValidationResults → EvaluationResults), JsonDocument.Parse signature.
  • StellaOps.Policy.Engine: Fixed OpenTelemetry Meter API changes (observeValues parameter, nullable returns), SamplingResult API changes, parameter casing fixes.
  • Test project: Added Microsoft.Extensions.TimeProvider.Testing package, fixed using directives, fixed parameter casing.

Execution Log

Date (UTC)	Update	Owner
2025-11-27	Started POLICY-ENGINE-40-003; implemented PolicyDecisionService, PolicyDecisionEndpoint, PolicyDecisionModels, tests. Blocked by pre-existing build issues in Telemetry.Core and RiskProfile projects.	Implementer
2025-11-27	Fixed pre-existing build issues (TelemetryContext API mismatch, JsonSchema.Net v5 API changes, OpenTelemetry Meter API changes, test project missing packages/namespaces). All 9 PolicyDecisionServiceTests pass. POLICY-ENGINE-40-003 marked DONE.	Implementer
2025-11-27	Implemented POLICY-ENGINE-50-001: Extended SPL compiler with AOC metadata support. Added PolicyAocMetadata, PolicyProvenance, PolicyAttestationRef models. Updated PolicyBundleService to capture compilation metadata, source/artifact digests, complexity metrics, provenance info. Added 4 new tests (all pass). POLICY-ENGINE-50-001 marked DONE.	Implementer