# Tasks: Operator Explanation Layer

**Input**: Design documents from `/specs/161-operator-explanation-layer/`
**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/openapi.yaml, quickstart.md

**Tests**: Tests are REQUIRED because this feature changes runtime behavior on governance read surfaces, reason translation, artifact-truth presentation, and operator-facing interpretation.
**Operations**: This feature does not introduce new long-running operations. Existing governance `OperationRun` flows remain canonical, and tasks below preserve queued-only toast behavior, progress-only active surfaces, terminal `OperationRunCompleted`, service-owned run transitions, and numeric-only `summary_counts`.
**RBAC**: Existing workspace, tenant, and canonical Monitoring authorization behavior is preserved. Non-members remain 404, members without capability remain 403, and no new destructive actions are introduced.
**Badges**: Any changed status-like semantics must stay centralized in `app/Support/Badges/BadgeCatalog.php`, `app/Support/Badges/OperatorOutcomeTaxonomy.php`, and related support classes; no ad-hoc Filament mappings are allowed.

## Phase 1: Setup (Shared Infrastructure)

**Purpose**: Create the reusable explanation-layer scaffolding before story-specific adoption begins.

- [X] T001 Create the core operator explanation value object in `app/Support/Ui/OperatorExplanation/OperatorExplanationPattern.php`
- [X] T002 [P] Create the count descriptor value object in `app/Support/Ui/OperatorExplanation/CountDescriptor.php`
- [X] T003 [P] Add reusable explanation test fixtures in `tests/Feature/Concerns/BuildsOperatorExplanationFixtures.php`

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: Add the shared semantic and translation infrastructure required by all user stories.

**⚠️ CRITICAL**: No user story work should start until this phase is complete.

- [X] T004 Create shared explanation-family and trustworthiness enums in `app/Support/Ui/OperatorExplanation/ExplanationFamily.php` and `app/Support/Ui/OperatorExplanation/TrustworthinessLevel.php`
- [X] T005 [P] Extend translated reason envelopes with trust-impact and absence-pattern fields in `app/Support/ReasonTranslation/ReasonResolutionEnvelope.php`
- [X] T006 [P] Add the shared explanation builder in `app/Support/Ui/OperatorExplanation/OperatorExplanationBuilder.php`
- [X] T007 [P] Create the baseline compare explanation registry in `app/Support/Baselines/BaselineCompareExplanationRegistry.php`
- [X] T008 [P] Extend baseline compare reason semantics in `app/Support/Baselines/BaselineCompareReasonCode.php` and `app/Support/Baselines/BaselineReasonCodes.php`
- [X] T009 [P] Register centralized outcome and badge semantics for explanation-layer states in `app/Support/Badges/OperatorOutcomeTaxonomy.php` and `app/Support/Badges/BadgeCatalog.php`
- [X] T010 Add foundational unit and translation coverage in `tests/Unit/Support/OperatorExplanation/OperatorExplanationBuilderTest.php` and `tests/Feature/ReasonTranslation/ReasonTranslationExplanationTest.php`

**Checkpoint**: Shared explanation composition, reason enrichment, and badge semantics are ready for story-level adoption.

---

## Phase 3: User Story 1 - Understand Degraded Results Without Diagnostics (Priority: P1) 🎯 MVP

**Goal**: Baseline Compare explains degraded, partial, suppressed, and no-result states in operator language without requiring diagnostics.

**Independent Test**: Open Baseline Compare for a case with `0 findings` and evidence gaps, then verify the page explains incomplete evaluation, result trust, and next action from default-visible content alone.

### Tests for User Story 1 ⚠️

> **NOTE: Write these tests first and confirm they fail before implementation.**

- [X] T011 [P] [US1] Extend baseline compare reason-code regression coverage in `tests/Feature/Baselines/BaselineCompareWhyNoFindingsReasonCodeTest.php`
- [X] T012 [P] [US1] Add baseline compare explanation-surface coverage in `tests/Feature/Filament/BaselineCompareExplanationSurfaceTest.php`
- [X] T013 [P] [US1] Add tenant-surface authorization regression coverage for Baseline Compare in `tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php`

### Implementation for User Story 1

- [X] T014 [US1] Add explanation-oriented count classification and trust-state helpers in `app/Support/Baselines/BaselineCompareStats.php`
- [X] T015 [US1] Build baseline compare explanation payloads from translated reasons in `app/Services/Baselines/BaselineCompareService.php` and `app/Jobs/CompareBaselineToTenantJob.php`
- [X] T016 [US1] Refactor page state mapping to explanation-first rendering in `app/Filament/Pages/BaselineCompareLanding.php`
- [X] T017 [US1] Rework the baseline compare primary explanation and diagnostics layout in `resources/views/filament/pages/baseline-compare-landing.blade.php`
- [X] T018 [US1] Prefer operator explanation fields over raw reason-message fallbacks in `app/Support/ReasonTranslation/ReasonPresenter.php`

**Checkpoint**: Baseline Compare no longer lets `0 findings` or absent output read as implicit all-clear when evaluation was limited.

---

## Phase 4: User Story 2 - Separate Execution Success From Result Trust (Priority: P2)

**Goal**: Governance-oriented Monitoring run detail and baseline-capture result presentation show execution outcome, result trust, dominant cause, and next action as distinct visible concepts.

**Independent Test**: Open a governance run detail page and a Baseline Snapshot result surface for technically completed but limited-confidence outcomes, then verify both surfaces separate execution success from decision confidence without relying on JSON.

### Tests for User Story 2 ⚠️

- [X] T019 [P] [US2] Extend governance run-detail truth coverage in `tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php`
- [X] T020 [P] [US2] Extend operation-run explanation-surface assertions in `tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php`
- [X] T021 [P] [US2] Add operation-run explanation builder unit coverage in `tests/Unit/Support/OperatorExplanation/OperationRunExplanationTest.php`
- [X] T022 [P] [US2] Add baseline-capture result explanation coverage in `tests/Feature/Filament/BaselineCaptureResultExplanationSurfaceTest.php`
- [X] T023 [P] [US2] Extend canonical-surface authorization regression coverage for run detail and Baseline Snapshot result presentation in `tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php`

### Implementation for User Story 2

- [X] T024 [US2] Compose operation-run and baseline-capture explanation patterns from artifact truth in `app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php`
- [X] T025 [US2] Align Monitoring run-detail explanation sections and count semantics in `app/Filament/Resources/OperationRunResource.php`
- [X] T026 [US2] Route canonical tenantless run viewing through explanation-first rendering in `app/Filament/Pages/Operations/TenantlessOperationRunViewer.php`
- [X] T027 [US2] Normalize governance run summaries and next-action wording in `app/Support/OpsUx/OperationUxPresenter.php`
- [X] T028 [US2] Render baseline-capture result explanation-first state in `app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php` and `app/Filament/Resources/BaselineSnapshotResource.php`

**Checkpoint**: Monitoring run detail and Baseline Snapshot result presentation answer what happened, how reliable the result is, why it looks this way, and what to do next before diagnostics.

---

## Phase 5: User Story 3 - Reuse One Explanation Pattern Across Domains (Priority: P3)

**Goal**: At least one additional governance artifact family reuses the same explanation pattern and next-action semantics beyond baseline compare and run detail.

**Independent Test**: Compare a tenant-review surface to the baseline compare reference case and verify both use the same reading order and explanation-family semantics for degraded or missing-input states.

### Tests for User Story 3 ⚠️

- [X] T029 [P] [US3] Add tenant review detail and Review Register explanation reuse coverage in `tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php`
- [X] T030 [P] [US3] Extend shared governance-artifact explanation unit coverage in `tests/Unit/Badges/GovernanceArtifactTruthTest.php`
- [X] T031 [P] [US3] Extend secondary-governance authorization regression coverage for Tenant Review detail and Review Register in `tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php`

### Implementation for User Story 3

- [X] T032 [US3] Map tenant review artifact truth into shared explanation patterns in `app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php`
- [X] T033 [US3] Render explanation-first tenant review detail state in `app/Filament/Resources/TenantReviewResource.php`
- [X] T034 [US3] Align Review Register row outcome and next-step columns with shared explanation patterns in `app/Filament/Pages/Reviews/ReviewRegister.php`

**Checkpoint**: The explanation layer is proven reusable on a non-baseline governance surface without inventing a new state dialect.

---

## Phase 6: Polish & Cross-Cutting Concerns

**Purpose**: Harden regression coverage, confirm centralized semantics, and validate the rollout against the documented surface rules.

- [X] T035 [P] Refresh centralized taxonomy and badge regression coverage in `tests/Unit/Badges/OperatorOutcomeTaxonomyTest.php`
- [X] T036 [P] Add absent-output and suppressed-output fallback coverage in `tests/Feature/Baselines/BaselineCompareExplanationFallbackTest.php` and `tests/Feature/Monitoring/GovernanceRunExplanationFallbackTest.php`
- [X] T037 [P] Review changed operator surfaces against `docs/product/standards/list-surface-review-checklist.md` and record any approved implementation notes in `specs/161-operator-explanation-layer/plan.md`
- [X] T038 Run focused verification commands from `specs/161-operator-explanation-layer/quickstart.md`
- [X] T039 Run formatting for changed files with `vendor/bin/sail bin pint --dirty --format agent` after updating `specs/161-operator-explanation-layer/quickstart.md`

---

## Dependencies & Execution Order

### Phase Dependencies

- **Setup (Phase 1)**: Starts immediately.
- **Foundational (Phase 2)**: Depends on Setup completion and blocks all user stories.
- **User Stories (Phases 3-5)**: All depend on Foundational completion.
- **Polish (Phase 6)**: Depends on all implemented user stories being complete.

### User Story Dependencies

- **User Story 1 (P1)**: Starts after Foundational and delivers the MVP reference implementation on Baseline Compare.
- **User Story 2 (P2)**: Starts after Foundational and reuses the same explanation infrastructure on Monitoring run detail.
- **User Story 3 (P3)**: Starts after Foundational and proves the explanation layer is reusable on a second governance domain.

### Within Each User Story

- Write tests first and confirm they fail before implementation.
- Update shared builders or presenters before wiring them into Filament surfaces.
- Finish the main support-layer logic before page-resource rendering changes.
- Validate each story against its independent checkpoint before moving to the next priority.

## Parallel Opportunities

- `T002` and `T003` can run in parallel after `T001`.
- `T005` through `T009` can run in parallel once `T004` establishes the shared explanation-state vocabulary.
- Story test tasks marked `[P]` can run in parallel within each user story.
- Surface adoption work in different files can split after the shared explanation infrastructure lands.

## Parallel Example: User Story 1

```bash
# Write and run Baseline Compare tests in parallel:
T011 tests/Feature/Baselines/BaselineCompareWhyNoFindingsReasonCodeTest.php
T012 tests/Feature/Filament/BaselineCompareExplanationSurfaceTest.php
T013 tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php

# After shared explanation primitives are ready, split story files:
T014 app/Support/Baselines/BaselineCompareStats.php
T016 app/Filament/Pages/BaselineCompareLanding.php
T017 resources/views/filament/pages/baseline-compare-landing.blade.php
```

## Parallel Example: User Story 2

```bash
# Prepare run-detail coverage together:
T019 tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php
T020 tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php
T021 tests/Unit/Support/OperatorExplanation/OperationRunExplanationTest.php
T022 tests/Feature/Filament/BaselineCaptureResultExplanationSurfaceTest.php
T023 tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php

# Then split implementation by layer:
T024 app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php
T025 app/Filament/Resources/OperationRunResource.php
T026 app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
T028 app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php
```

## Parallel Example: User Story 3

```bash
# Reuse coverage can be written together:
T029 tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php
T030 tests/Unit/Badges/GovernanceArtifactTruthTest.php
T031 tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php

# Then split the second-domain rollout:
T032 app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php
T033 app/Filament/Resources/TenantReviewResource.php
T034 app/Filament/Pages/Reviews/ReviewRegister.php
```

## Implementation Strategy

### MVP First

1. Complete Phase 1 and Phase 2.
2. Deliver User Story 1 on Baseline Compare as the first shippable explanation-layer slice.
3. Validate the motivating `0 findings` plus evidence-gap case before moving on.

### Incremental Delivery

1. Add User Story 2 to align governance Monitoring run detail and Baseline Snapshot capture-result presentation with the same reading model.
2. Add User Story 3 to prove the pattern is reusable across governance domains on Tenant Review detail and Review Register.
3. Finish Phase 6 for regression hardening, checklist review, and verification.

### Suggested MVP Scope

- Phase 1: Setup
- Phase 2: Foundational
- Phase 3: User Story 1 only