git.stella-ops.org/docs/features/unchecked/web/audit-trail-why-am-i-seeing-this.md

Audit Trail "Why am I seeing this?" (Reason Capsule)

Module

Web

Status

IMPLEMENTED

Description

The advisory proposed a ReasonCapsuleComponent with per-row expandable explanations showing policy name, rule ID, graph revision ID, and inputs digest. Instead, verdict explanation is implemented via VerdictWhySummaryComponent (3-5 bullet driver explanations with evidence drill-down links) and WhySafePanels in the lineage feature. The exact ReasonCapsuleComponent name and API contract (/api/audit/reasons/:verdictId) were not found, but the concept is substantially realized under different component names.

What's Implemented

• Existing components:
  • ai-code-guard-badge (src/Web/StellaOps.Web/src/app/features/triage/components/ai-code-guard-badge/ai-code-guard-badge.component.ts)
  • ai-recommendation-panel (src/Web/StellaOps.Web/src/app/features/triage/components/ai-recommendation-panel/ai-recommendation-panel.component.ts)
  • attestation-viewer (src/Web/StellaOps.Web/src/app/features/triage/components/attestation-viewer/attestation-viewer.component.ts)
  • bulk-action-modal (src/Web/StellaOps.Web/src/app/features/triage/components/bulk-action-modal/bulk-action-modal.component.ts)
  • case-header (src/Web/StellaOps.Web/src/app/features/triage/components/case-header/case-header.component.ts)
  • decision-drawer-enhanced (src/Web/StellaOps.Web/src/app/features/triage/components/decision-drawer/decision-drawer-enhanced.component.ts)
  • decision-drawer (src/Web/StellaOps.Web/src/app/features/triage/components/decision-drawer/decision-drawer.component.ts)
  • attestation-chain (src/Web/StellaOps.Web/src/app/features/triage/components/evidence-panel/attestation-chain.component.ts)
  • backport-verdict-badge (src/Web/StellaOps.Web/src/app/features/triage/components/evidence-panel/backport-verdict-badge.component.ts)
  • binary-diff-tab (src/Web/StellaOps.Web/src/app/features/triage/components/evidence-panel/binary-diff-tab.component.ts)
• Existing services:
  • advisory-ai (src/Web/StellaOps.Web/src/app/features/triage/services/advisory-ai.service.ts)
  • binary-diff-evidence (src/Web/StellaOps.Web/src/app/features/triage/services/binary-diff-evidence.service.ts)
  • diff-evidence (src/Web/StellaOps.Web/src/app/features/triage/services/diff-evidence.service.ts)
  • display-preferences (src/Web/StellaOps.Web/src/app/features/triage/services/display-preferences.service.ts)
  • evidence-tab (src/Web/StellaOps.Web/src/app/features/triage/services/evidence-tab.service.ts)

What's Missing

• ReasonCapsuleComponent: No per-row expandable component showing policy name, rule ID, graph revision ID, and inputs digest for each finding/verdict in table views
• Audit reasons API: No /api/audit/reasons/:verdictId endpoint returning structured reason data for display
• Per-finding explanation inline: VerdictWhySummaryComponent and WhySafePanels exist for verdict-level and lineage-level explanation, but no per-row inline "why" capsule in triage table views

Implementation Plan

• Create ReasonCapsuleComponent as expandable per-row explanation in triage/finding tables
• Add /api/audit/reasons/:verdictId endpoint returning policy name, rule ID, graph revision, inputs digest
• Wire capsule into triage table views for inline "why am I seeing this" explanation

E2E Test Plan

• Setup:
  • Log in with a user that has appropriate permissions
  • Navigate to /triage/artifacts
  • Ensure test data exists (scanned artifacts, SBOM data, or seed data as needed)
• Core verification:
  • Verify the component renders correctly with sample data
  • Verify interactive elements respond to user input
  • Verify data is fetched and displayed from the correct API endpoints
• Edge cases:
  • Verify graceful handling when backend API is unavailable (error state)
  • Verify responsive layout at different viewport sizes
  • Verify accessibility (keyboard navigation, screen reader labels, ARIA attributes)