Explainable Triage Workflows - Implementation Plan

Executive Summary

This document outlines the implementation plan for delivering Explainable Triage Workflows as defined in the product advisory dated 21-Dec-2025. The capability set enables vulnerability-first, policy-backed, reachability-informed verdicts with full explainability and auditability.

Vision

Every vulnerability finding must resolve to a policy-backed, reachability-informed, runtime-corroborated verdict that is exportable as one signed attestation attached to the built artifact.

Current State Analysis

Already Implemented (75%)

Already Planned (15%)

Net New Gaps (10%)

Implementation Roadmap

Phase 1: Foundation (Existing + New)

Objective: Establish core verdict and confidence infrastructure.

Sprints:

• SPRINT_4100_0003_0001: Risk Verdict Attestation
• SPRINT_4100_0002_0001: Knowledge Snapshot Manifest
• SPRINT_7000_0002_0001: Unified Confidence Model
• SPRINT_7000_0004_0001: Progressive Fidelity (parallel)
• SPRINT_7000_0004_0002: Evidence Budgets (parallel)

Key Deliverables:

• RiskVerdictAttestation model with PASS/FAIL/PASS_WITH_EXCEPTIONS/INDETERMINATE
• ConfidenceScore with 5-factor breakdown
• FidelityLevel enum with Quick/Standard/Deep modes
• EvidenceBudget with retention tiers

Phase 2: UX Layer

Objective: Deliver vulnerability-first presentation layer.

Sprints:

• SPRINT_7000_0002_0002: Vulnerability-First UX API

Key Deliverables:

• FindingSummaryResponse with verdict chip, confidence, one-liner
• ProofBadges (Reachability, Runtime, Policy, Provenance)
• GET /api/v1/findings list endpoint
• GET /api/v1/findings/{id}/summary detail endpoint

Phase 3: Visualization APIs

Objective: Enable evidence exploration and click-through.

Sprints (parallelizable):

• SPRINT_7000_0003_0001: Evidence Graph API
• SPRINT_7000_0003_0002: Reachability Mini-Map API
• SPRINT_7000_0003_0003: Runtime Timeline API

Key Deliverables:

• GET /api/v1/findings/{id}/evidence-graph
• GET /api/v1/findings/{id}/reachability-map
• GET /api/v1/findings/{id}/runtime-timeline

Phase 4: Metrics & Observability

Objective: Track quality KPIs for continuous improvement.

Sprints:

• SPRINT_7000_0005_0001: Quality KPIs Tracking

Key Deliverables:

• TriageQualityKpis model
• GET /api/v1/metrics/kpis dashboard endpoint
• Trend tracking over time

Architecture Changes

New Libraries

src/
├── Policy/
│   └── __Libraries/
│       └── StellaOps.Policy.Confidence/     # NEW: Confidence model
│           ├── Models/
│           ├── Services/
│           └── Configuration/
├── Scanner/
│   └── __Libraries/
│       └── StellaOps.Scanner.Orchestration/ # NEW: Fidelity orchestration
│           └── Fidelity/
├── Findings/
│   └── StellaOps.Findings.WebService/       # EXTEND: UX APIs
│       ├── Contracts/
│       ├── Services/
│       └── Endpoints/
├── Evidence/                                 # NEW: Evidence management
│   └── StellaOps.Evidence/
│       ├── Budgets/
│       └── Retention/
└── Metrics/                                  # NEW: KPI tracking
    └── StellaOps.Metrics/
        └── Kpi/

Database Changes

API Surface

Non-Negotiables

From the advisory:

1. Vulnerability-first UX: Users start from CVE/finding and immediately see applicability, reachability, runtime corroboration, and policy rationale.

2. Single canonical verdict artifact: One built-in, signed verdict attestation per subject (OCI digest), replayable.

3. Deterministic evidence: Evidence objects are content-hashed and versioned.

4. Unknowns are first-class: “Unknown reachability/runtime/config” is not hidden; it is budgeted and policy-controlled.

Quality KPIs

Risk Management

Definition of Done

Per advisory, a release is “done” only if:

• [ ] Build produces OCI artifact with attached signed verdict attestation
• [ ] Each verdict is explainable (reason steps + proof pointers)
• [ ] Reachability evidence stored as reproducible subgraph (or explicitly UNKNOWN with reason)
• [ ] Replay verification reproduces same verdict with pinned inputs
• [ ] UX starts from vulnerabilities and links directly to proofs and audit export

References

• Advisory: docs/product/advisories/archived/21-Dec-2025 - Designing Explainable Triage Workflows.md
• Sprint Summary: docs/implplan/SPRINT_7000_SUMMARY.md
• Individual Sprints: docs/implplan/SPRINT_7000_*.md

Revision History