TenantAtlas/specs/161-operator-explanation-layer/plan.md

Implementation Plan: 161 — Operator Explanation Layer

Branch: 161-operator-explanation-layer | Date: 2026-03-23 | Spec: specs/161-operator-explanation-layer/spec.md Input: Feature specification from specs/161-operator-explanation-layer/spec.md

Note: This template is filled in by the /speckit.plan command. See .specify/scripts/ for helper scripts.

Summary

Introduce a shared operator explanation layer that turns degraded, partial, suppressed, and missing-input governance outcomes into one reusable reading model: what happened, how trustworthy the result is, why it looks this way, and what to do next. The implementation will extend the existing reason-translation, operator-outcome taxonomy, artifact-truth presentation, and baseline-compare stats infrastructure instead of inventing a parallel system, then apply that shared pattern first to Baseline Compare, governance-oriented Operation Run detail, Baseline Snapshot list/detail as baseline-capture result presentation, and the explicit reuse proof surfaces Tenant Review detail and Review Register.

Technical Context

Language/Version: PHP 8.4
Primary Dependencies: Laravel 12, Filament v5, Livewire v4
Storage: PostgreSQL (via Sail) plus existing read models persisted in application tables
Testing: Pest v4 on PHPUnit 12
Target Platform: Dockerized Laravel web application (Sail locally, Dokploy in deployment)
Project Type: Web application
Performance Goals: Preserve DB-only render behavior for Monitoring surfaces, add no render-time remote calls, and keep explanation rendering lightweight enough for existing list/detail surfaces
Constraints:

• No new Microsoft Graph contracts or render-time remote work
• No change to OperationRun lifecycle ownership or feedback channels
• No change to workspace or tenant authorization boundaries
• Badge/state semantics must remain centralized under existing support layers
• Diagnostics remain available but must become visually secondary on the affected surfaces Scale/Scope: Cross-cutting read-surface work touching shared support layers, one baseline reference page, canonical run-detail presentation, and at least one additional governance artifact surface, with focused updates to unit and feature tests rather than a platform-wide rollout in one slice

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

• Inventory-first: PASS — this feature changes explanation of already-observed and already-produced governance data; it does not alter inventory as the last-observed source of truth.
• Read/write separation: PASS — the feature is read-surface and presentation oriented. Existing mutating flows and confirmations remain unchanged.
• Graph contract path: PASS — no new Graph calls or contract-registry additions are introduced.
• Deterministic capabilities: PASS — no capability-derivation changes are introduced; existing registries remain canonical.
• RBAC-UX: PASS — workspace-admin, tenant, and canonical Monitoring surfaces keep current 404/403 behavior and server-side checks.
• Workspace isolation: PASS — no new workspace-context leakage is introduced; canonical surfaces remain tenant-safe.
• RBAC confirmations: PASS — no new destructive actions are introduced.
• Global search: PASS — no changes to global-search scope or visibility.
• Tenant isolation: PASS — tenant-owned run and governance data remain entitlement-checked before disclosure.
• Run observability: PASS — existing governance runs continue to use OperationRun; this feature layers interpretation on top rather than altering execution semantics.
• Ops-UX 3-surface feedback: PASS — no new toasts, progress surfaces, or terminal notifications are introduced.
• Ops-UX lifecycle: PASS — OperationRun.status and OperationRun.outcome remain service-owned.
• Ops-UX summary counts: PASS — counts remain numeric execution metrics; this feature adds interpretation rules above them.
• Ops-UX guards: PASS — focused regression tests can protect explanation behavior without relaxing existing CI guards.
• Ops-UX system runs: PASS — unchanged.
• Automation: PASS — no queue/idempotency behavior changes required in this slice.
• Data minimization: PASS — diagnostics stay secondary and no new secret-bearing payload fields are introduced.
• Badge semantics (BADGE-001): PASS — explanation states will consume BadgeCatalog, BadgeRenderer, and OperatorOutcomeTaxonomy rather than ad-hoc mappings.
• UI naming (UI-NAMING-001): PASS — operator wording becomes more domain-first, not more implementation-first.
• Operator surfaces (OPSURF-001): PASS — the entire feature exists to reinforce operator-first defaults and explicit diagnostics layering.
• Filament UI Action Surface Contract: PASS — action topology remains largely unchanged; the primary refactor is read-surface explanation hierarchy.
• Filament UI UX-001 (Layout & IA): PASS — affected pages continue to use structured sections; the feature adds deliberate explanation blocks and diagnostics grouping.
• UI-STD-001 list-surface review: PASS — Review Register and any touched governance list surfaces are explicitly in scope for docs/product/standards/list-surface-review-checklist.md review.

Project Structure

Documentation (this feature)

specs/161-operator-explanation-layer/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── openapi.yaml
├── checklists/
│   └── requirements.md
└── tasks.md

Source Code (repository root)

app/
├── Filament/
│   ├── Pages/
│   │   └── BaselineCompareLanding.php
│   ├── Resources/
│   │   ├── OperationRunResource.php
│   │   ├── BaselineSnapshotResource.php
│   │   ├── EvidenceSnapshotResource.php
│   │   ├── TenantReviewResource.php
│   │   └── ReviewPackResource.php
│   └── System/
├── Jobs/
│   └── CompareBaselineToTenantJob.php
├── Support/
│   ├── Badges/
│   ├── Baselines/
│   ├── OpsUx/
│   ├── ReasonTranslation/
│   └── Ui/
│       └── GovernanceArtifactTruth/
├── Services/
│   └── Baselines/
resources/
└── views/
tests/
├── Feature/
│   ├── Baselines/
│   ├── Filament/
│   ├── Monitoring/
│   └── ReasonTranslation/
└── Unit/
    ├── Badges/
    └── Support/

Structure Decision: Web application (Laravel 12). The work stays within existing Filament pages/resources, support-layer presenters and translators, baseline compare services and jobs, Blade views where already used, and focused Pest coverage. No new top-level architectural area is needed.

Complexity Tracking

No constitution violations are required for this feature.

Phase 0 — Outline & Research (DONE)

Outputs:

• specs/161-operator-explanation-layer/research.md

Key decisions captured:

• Build on the existing ReasonPresenter, ReasonTranslator, OperatorOutcomeTaxonomy, BadgeCatalog, and ArtifactTruthPresenter layers rather than creating an isolated explanation subsystem.
• Introduce a shared operator explanation pattern that explicitly separates execution outcome, evaluation meaning, reliability, coverage, and next action.
• Formalize count-role semantics so empty-looking output counts cannot be misread as complete evaluation.
• Make Baseline Compare the golden-path reference implementation, then apply the same pattern to Monitoring run detail, Baseline Snapshot result presentation, and the secondary proof surfaces Tenant Review detail plus Review Register.
• Keep diagnostics available through the existing reason and artifact-truth infrastructure, but demote them behind primary explanation blocks.

Phase 1 — Design & Contracts (DONE)

Outputs:

• specs/161-operator-explanation-layer/data-model.md
• specs/161-operator-explanation-layer/contracts/openapi.yaml
• specs/161-operator-explanation-layer/quickstart.md

Design highlights:

• The explanation layer is modeled as a reusable view-model contract rather than as a new persistence model.
• ReasonResolutionEnvelope and ArtifactTruthEnvelope remain the core semantic inputs, but a new explanation pattern composes them into operator-facing sections and count semantics.
• Count presentation is explicitly typed into execution counts, evaluation-output counts, and coverage or reliability counts so surfaces can explain why 0 findings is not always healthy.
• Governance run-detail and baseline compare read models are aligned on one reading order: outcome, trust statement, cause summary, next action, then diagnostics.
• Adoption is intentionally phased: baseline compare first, then governance run detail plus baseline-capture result presentation, then Tenant Review detail and Review Register as the secondary reuse proof.

Phase 1 — Agent Context Update (REQUIRED)

Run:

• .specify/scripts/bash/update-agent-context.sh copilot

Constitution Check — Post-Design Re-evaluation

• PASS — the design remains read-surface focused and does not introduce new write paths, Graph calls, or authorization changes.
• PASS — explanation and badge semantics stay centralized in existing support layers.
• PASS — canonical Monitoring and tenant-scoped surfaces keep existing entitlement and run-observability rules.
• PASS — no new action-surface or UX-001 exemptions are needed; the work fits the current structured layouts.

Phase 2 — Implementation Plan

Step 1 — Shared explanation pattern and semantic taxonomy extension

Goal: implement FR-001 through FR-009 and establish the reusable operator explanation model.

Changes:

• Add a shared explanation-pattern view model or builder in the support layer that composes:
  • execution outcome
  • evaluation result
  • reliability or trust statement
  • coverage or completeness statement
  • recommended action category
• Extend existing reason-translation outputs so reference surfaces can consume operator label, operator explanation, trustworthiness impact, and next-action guidance separately.
• Define the count-role taxonomy for execution counts, evaluation-output counts, and coverage or reliability counts.
• Define the shared absent-output and degraded-output explanation families required by the spec.

Tests:

• Add or update unit coverage for explanation-pattern composition and count-role classification.
• Extend reason-translation tests for operator-facing explanation outputs in degraded, missing-input, and suppressed cases.
• Extend badge or taxonomy tests if any new centralized values are required.

Step 2 — Baseline Compare golden-path adoption

Goal: implement FR-010, FR-014, FR-016, and FR-017 on the main motivating surface.

Changes:

• Update baseline-compare stats or presenter outputs so the page receives a composed explanation pattern instead of raw reason-message-first content.
• Refactor baseline compare surface rendering so the first visible block answers:
  • what happened
  • how trustworthy the result is
  • why it looks this way
  • what the operator should do next
• Re-label or group counts according to the new count-role taxonomy.
• Keep low-level evidence-gap payloads and reason-code detail in secondary diagnostics.

Tests:

• Extend BaselineCompareWhyNoFindingsReasonCodeTest with operator-explanation assertions.
• Add or update Filament or page-level tests verifying that 0 findings with evidence gaps does not render as all-clear.
• Add at least one suppressed-output and one true-no-findings comparison case.

Step 3 — Governance run-detail and baseline-capture result alignment

Goal: implement FR-010 through FR-012 on canonical Monitoring run detail and Baseline Snapshot result presentation.

Changes:

• Route governance-oriented OperationRun result presentation through the new explanation-pattern layer.
• Align Monitoring run-detail sections with the same reading order used on baseline compare.
• Ensure run outcome and result trust remain separate, non-contradictory visible statements.
• Keep raw JSON, raw reason codes, and low-level counters clearly secondary.
• Apply the same explanation pattern to Baseline Snapshot list/detail so baseline-capture result presentation exposes trustworthiness, dominant cause, and next action before low-level truth details.

Tests:

• Extend ArtifactTruthRunDetailTest and OperationRunBaselineTruthSurfaceTest for explanation hierarchy and count semantics.
• Add a regression asserting that a technically successful but limited-confidence run cannot render as plain success without caveat.
• Add baseline-capture result surface coverage proving snapshot result presentation follows the same default-visible order.

Step 4 — Secondary governance artifact adoption

Goal: satisfy FR-009 and SC-005 by proving reuse beyond baseline compare.

Changes:

• Apply the same explanation pattern to Tenant Review detail and Review Register as the explicit secondary governance reuse proof for this slice.
• Normalize visible wording so the same cause class uses the same explanation structure and next-action category.
• Keep existing artifact-truth detail available, but demoted behind the new primary explanation section.
• Review the touched list surface against docs/product/standards/list-surface-review-checklist.md.

Tests:

• Add or update tenant-review and Review Register feature tests proving reuse of the same explanation pattern.
• Extend governance artifact truth unit coverage if new envelope-to-explanation mapping rules are introduced.

Step 5 — Focused regression and review safety

Goal: keep the rollout bounded and protect the reading model from future regressions.

Changes:

• Add focused tests around count semantics, absent-output patterns, and degraded-result explanations.
• Add focused RBAC regression tests for Baseline Compare, canonical Monitoring run detail, Baseline Snapshot result presentation, and Tenant Review detail so non-members remain 404 and members lacking capability remain 403.
• Review list/detail surfaces touched by the feature against centralized badge and operator-surface rules.
• Keep implementation localized to shared presenters and targeted surfaces rather than broad page-by-page copy edits.

Tests:

• Run the focused baseline, Monitoring, reason-translation, and badge suites documented in quickstart.md.
• Add one targeted regression proving diagnostics remain available but not primary on a reference surface.

List Surface Review Notes

Reviewed against docs/product/standards/list-surface-review-checklist.md:

• Review Register: kept 7 visible columns, persisted filters/search/sort, clickable rows, and the existing two visible row actions while moving the operator explanation headline into the row description and keeping next-step wording wrapped and tenant-safe.
• Baseline Snapshots list: preserved resource-table persistence, clickable rows, badge-backed truth/lifecycle columns, and efficient default sorting while shifting explanation-first copy into the artifact-truth description plus next-step column without adding new relation-heavy query work.
• Tenant Reviews list: preserved tenant-scoped clickable rows, existing header/empty-state/action topology, and badge-backed truth/publication columns while reusing the shared explanation headline and next-action wording in row descriptions and next-step cells.