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

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.

• T001 Create the core operator explanation value object in app/Support/Ui/OperatorExplanation/OperatorExplanationPattern.php
• T002 [P] Create the count descriptor value object in app/Support/Ui/OperatorExplanation/CountDescriptor.php
• 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.

• T004 Create shared explanation-family and trustworthiness enums in app/Support/Ui/OperatorExplanation/ExplanationFamily.php and app/Support/Ui/OperatorExplanation/TrustworthinessLevel.php
• T005 [P] Extend translated reason envelopes with trust-impact and absence-pattern fields in app/Support/ReasonTranslation/ReasonResolutionEnvelope.php
• T006 [P] Add the shared explanation builder in app/Support/Ui/OperatorExplanation/OperatorExplanationBuilder.php
• T007 [P] Create the baseline compare explanation registry in app/Support/Baselines/BaselineCompareExplanationRegistry.php
• T008 [P] Extend baseline compare reason semantics in app/Support/Baselines/BaselineCompareReasonCode.php and app/Support/Baselines/BaselineReasonCodes.php
• T009 [P] Register centralized outcome and badge semantics for explanation-layer states in app/Support/Badges/OperatorOutcomeTaxonomy.php and app/Support/Badges/BadgeCatalog.php
• 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.

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

Implementation for User Story 1

• T014 [US1] Add explanation-oriented count classification and trust-state helpers in app/Support/Baselines/BaselineCompareStats.php
• T015 [US1] Build baseline compare explanation payloads from translated reasons in app/Services/Baselines/BaselineCompareService.php and app/Jobs/CompareBaselineToTenantJob.php
• T016 [US1] Refactor page state mapping to explanation-first rendering in app/Filament/Pages/BaselineCompareLanding.php
• T017 [US1] Rework the baseline compare primary explanation and diagnostics layout in resources/views/filament/pages/baseline-compare-landing.blade.php
• 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 ⚠️

• T019 [P] [US2] Extend governance run-detail truth coverage in tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php
• T020 [P] [US2] Extend operation-run explanation-surface assertions in tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php
• T021 [P] [US2] Add operation-run explanation builder unit coverage in tests/Unit/Support/OperatorExplanation/OperationRunExplanationTest.php
• T022 [P] [US2] Add baseline-capture result explanation coverage in tests/Feature/Filament/BaselineCaptureResultExplanationSurfaceTest.php
• 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

• T024 [US2] Compose operation-run and baseline-capture explanation patterns from artifact truth in app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php
• T025 [US2] Align Monitoring run-detail explanation sections and count semantics in app/Filament/Resources/OperationRunResource.php
• T026 [US2] Route canonical tenantless run viewing through explanation-first rendering in app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
• T027 [US2] Normalize governance run summaries and next-action wording in app/Support/OpsUx/OperationUxPresenter.php
• 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 ⚠️

• T029 [P] [US3] Add tenant review detail and Review Register explanation reuse coverage in tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php
• T030 [P] [US3] Extend shared governance-artifact explanation unit coverage in tests/Unit/Badges/GovernanceArtifactTruthTest.php
• 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

• T032 [US3] Map tenant review artifact truth into shared explanation patterns in app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php
• T033 [US3] Render explanation-first tenant review detail state in app/Filament/Resources/TenantReviewResource.php
• 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.

• T035 [P] Refresh centralized taxonomy and badge regression coverage in tests/Unit/Badges/OperatorOutcomeTaxonomyTest.php
• T036 [P] Add absent-output and suppressed-output fallback coverage in tests/Feature/Baselines/BaselineCompareExplanationFallbackTest.php and tests/Feature/Monitoring/GovernanceRunExplanationFallbackTest.php
• 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
• T038 Run focused verification commands from specs/161-operator-explanation-layer/quickstart.md
• 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

# 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

# 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

# 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