# Policy trace panel ("why blocked" / "what would make it pass")

## Module
Api

## Status
VERIFIED

## Description
Block explanation API controller, CLI explain commands, and verdict rationale renderer provide policy trace functionality explaining why artifacts are blocked and what would unblock them.

## Implementation Details
- **Scoring Endpoints**: `src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/ScoringEndpoints.cs` -- exposes REST endpoints for querying scored findings with policy trace context, including why a finding is blocked and which evidence would change the outcome.
- **Evidence Graph Endpoints**: `src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/EvidenceGraphEndpoints.cs` -- serves evidence graph subgraphs connecting findings to attestations, VEX statements, and policy decisions, showing the trace of what inputs led to the verdict.
- **Finding Summary Endpoints**: `src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/FindingSummaryEndpoints.cs` -- returns finding summaries with policy evaluation trace context including rule names, evaluation outcomes, and evidence references.
- **Finding Scoring Service**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/FindingScoringService.cs` -- computes and caches finding scores combining CVSS, EPSS, VEX, and reachability signals; explains score composition.
- **Evidence Graph Builder**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/EvidenceGraphBuilder.cs` -- constructs evidence subgraphs from ledger events and attestation pointers for trace visualization.
- **VEX Consensus Service**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/VexConsensusService.cs` -- aggregates VEX decisions across sources to explain the consensus status.
- **Policy Evaluation Service**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Policy/PolicyEngineEvaluationService.cs` -- evaluates policy rules against findings and returns detailed trace output explaining each rule's contribution.
- **Inline Policy Evaluation Service**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Policy/InlinePolicyEvaluationService.cs` -- lightweight inline evaluation for single-finding traces without external policy engine calls.
- **Tests**: `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/Integration/ScoringEndpointsIntegrationTests.cs`, `ScoringAuthorizationTests.cs`, `PolicyEngineEvaluationServiceTests.cs`, `InlinePolicyEvaluationServiceTests.cs`, `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/Services/EvidenceGraphBuilderTests.cs`, `FindingScoringServiceTests.cs`

## E2E Test Plan
- [x] Query finding summaries (`GET /api/v1/findings/summaries`) with auth and verify structured summary payload is returned.
- [x] Query summary with invalid finding ID and verify `400` problem-details response.
- [x] Query unknown finding summary and verify `404`.
- [x] Query unknown finding evidence graph and verify `404`.
- [x] Query summaries without auth and verify `401`.

## Verification
- Verified on 2026-02-11 via FLOW Tier 0/1/2 replay in `run-001`.
- Tier 0: `docs/qa/feature-checks/runs/api/policy-trace-panel/run-001/tier0-source-check.json`
- Tier 1: `docs/qa/feature-checks/runs/api/policy-trace-panel/run-001/tier1-build-check.json`
- Tier 2: `docs/qa/feature-checks/runs/api/policy-trace-panel/run-001/tier2-api-check.json`