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)

```text
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)

```text
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.