git.stella-ops.org/docs/ui/explainers.md

Policy Explainers (UI)

Imposed rule: Explain views must show evidence hashes, signals, and rule rationale; omit or obfuscate none. AOC tenants must see AOC badge and tenant-only data.

This guide describes how the Console renders explainability for policy decisions.

1. Surfaces

• Findings table: each row links to an explainer drawer.
• Explainer drawer: rule stack, inputs, signals, evidence hashes, reachability path, VEX statements, attestation refs.
• Timeline tab: events for submit/approve/publish/activate and recent runs.
• Runs tab: runId, input cursors, IR hash, shadow flag, coverage evidence.

2. Drawer layout

• Header: status, severity, policy version, shadow flag, AOC badge.
• Evidence panel: SBOM digest, advisory snapshot, VEX IDs, reachability graph hash, runtime hit flag, attestation refs.
• Rule hits: ordered list with because, signals snapshot, actions taken.
• Reachability path: signed call path when available; shows graph hash + edge bundle hash; link to Verify.
• Signals: trust_score, reachability.state/score, entropy_penalty, uncertainty.level, runtime_hits.

3. Interactions

• Verify evidence: button triggers stella policy explain --verify equivalent; shows DSSE/Rekor status.
• Toggle baseline: compare against previous policy version; highlights changed rules/outcomes.
• Download: export explain as JSON with evidence hashes; offline-friendly.

4. Accessibility

• Keyboard navigation: Tab order header → evidence → rules → actions; Enter activates verify/download.
• Screen reader labels include status, severity, reachability state, trust score.

5. Offline

• Drawer works on offline bundles; verify uses embedded DSSE/attestations; if Rekor unavailable, show “offline verify” with bundle digest.

6. Error states

• Missing evidence: display unknown chips; prompt to rerun when inputs unfrozen.
• Attestation mismatch: show warning badge and link to governance doc.

References

• docs/policy/overview.md
• docs/policy/runtime.md
• docs/policy/governance.md
• docs/policy/api.md