# Tasks: Humanized Diagnostic Summaries for Governance Operations **Input**: Design documents from `/specs/220-governance-run-summaries/` **Prerequisites**: `plan.md`, `spec.md`, `research.md`, `data-model.md`, `contracts/governance-run-summaries.logical.openapi.yaml`, `quickstart.md` **Tests**: Required. This feature changes runtime behavior on a Filament-backed Monitoring detail surface, so Pest feature and unit coverage must ship with the implementation. **Test Governance Checklist** - Lane assignment stays `fast-feedback` plus `confidence` and remains the narrowest sufficient proof for this surface change. - New tests stay in focused Monitoring and unit suites; no heavy-governance or browser family is introduced. - Shared helpers and fixtures remain opt-in, especially `BuildsGovernanceArtifactTruthFixtures`. - Validation commands stay limited to the focused run-detail suites listed in `specs/220-governance-run-summaries/quickstart.md`. - The declared surface profile remains `monitoring-state-page`. - Any budget or escalation note stays inside this feature instead of becoming a follow-up spec. ## Phase 1: Setup (Shared Test Scaffolding) **Purpose**: Create the focused test seams and fixture hooks the implementation will use. - [X] T001 [P] Create the focused canonical run-detail feature suite and local scenario helpers for zero-output and multi-cause runs in `apps/platform/tests/Feature/Monitoring/GovernanceOperationRunSummariesTest.php` - [X] T002 [P] Create the focused summary-derivation unit suite in `apps/platform/tests/Unit/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilderTest.php` - [X] T003 [P] Extend only generic opt-in shared governance fixture builders for blocked, stale, and internal-only artifact cases in `apps/platform/tests/Feature/Concerns/BuildsGovernanceArtifactTruthFixtures.php` --- ## Phase 2: Foundational (Blocking Prerequisites) **Purpose**: Establish the shared derived-summary seam that all user stories build on. **⚠️ CRITICAL**: No user story work should start until this phase is complete. - [X] T004 Create the derived summary value object in `apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummary.php` - [X] T005 Create the shared summary builder with canonical `OperationRun`, artifact-truth, reason, and explanation inputs in `apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php` - [X] T006 Wire memoized governance summary access into `apps/platform/app/Support/OpsUx/OperationUxPresenter.php` - [X] T007 [P] Add guard coverage that summary derivation preserves canonical `summary_counts` meaning and does not invent new count keys in `apps/platform/tests/Unit/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilderTest.php` - [X] T008 [P] Extend canonical operator-language assertions and explicit next-step category matrix coverage for `retry later`, `resume capture or generation`, `refresh prerequisite data`, `review scope or ambiguous matches`, `manually validate`, and `no further action` in `apps/platform/tests/Unit/Support/OperatorExplanation/OperatorExplanationBuilderTest.php` and `apps/platform/tests/Unit/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilderTest.php` **Checkpoint**: The shared summary seam exists, is memoized through the current Ops UX presenter, and is guarded against count-contract drift. --- ## Phase 3: User Story 1 - Understand the dominant problem fast (Priority: P1) 🎯 MVP **Goal**: Make the canonical governance run-detail page explain the dominant problem, affected scale, and next step before any raw diagnostics. **Independent Test**: Open seeded baseline-capture and baseline-compare runs on `/admin/operations/{run}` and confirm the default-visible summary answers what happened and what to do next without opening diagnostic sections. ### Tests for User Story 1 - [X] T009 [P] [US1] Add feature scenarios for baseline-capture and baseline-compare summary-first hierarchy, no new header actions, and zero-output messaging in `apps/platform/tests/Feature/Monitoring/GovernanceOperationRunSummariesTest.php` - [X] T010 [P] [US1] Add unit cases for dominant headline, supporting reason, affected-scale cue, and next-step selection for baseline-capture and baseline-compare runs in `apps/platform/tests/Unit/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilderTest.php` ### Implementation for User Story 1 - [X] T011 [US1] Implement `baseline.capture` and `baseline.compare` summary mappings in `apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php` - [X] T012 [US1] Expose baseline summary facts through the memoized presenter API in `apps/platform/app/Support/OpsUx/OperationUxPresenter.php` - [X] T013 [US1] Render the default-visible summary block before technical diagnostics in `apps/platform/app/Filament/Resources/OperationRunResource.php` - [X] T014 [US1] Keep canonical context, lifecycle, and restore banners specialized without duplicating the dominant explanation in `apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php` - [X] T015 [US1] Preserve summary-first page-shell order for canonical run detail in `apps/platform/resources/views/filament/pages/operations/tenantless-operation-run-viewer.blade.php` - [X] T016 [US1] Update summary fallback expectations for the new first-read hierarchy in `apps/platform/tests/Feature/Monitoring/GovernanceRunExplanationFallbackTest.php` - [X] T017 [US1] Update run-detail hierarchy assertions so diagnostics stay secondary in `apps/platform/tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php` **Checkpoint**: Baseline capture and baseline compare runs are readable from the summary block alone, with diagnostics preserved but no longer leading the page. --- ## Phase 4: User Story 2 - Separate processing success from artifact trust (Priority: P2) **Goal**: Keep execution completion visible while clearly separating whether the resulting artifact is trustworthy, limited, stale, or internal-only. **Independent Test**: Open seeded evidence-snapshot and review-pack runs where processing completed but the artifact is not decision-grade, and confirm the page shows those truths as separate visible statements. ### Tests for User Story 2 - [X] T018 [P] [US2] Add feature scenarios for evidence-snapshot and review-pack runs that separate processing completion from artifact trust in `apps/platform/tests/Feature/Monitoring/GovernanceOperationRunSummariesTest.php` - [X] T019 [P] [US2] Add regression assertions for execution-outcome versus artifact-impact separation in `apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php` - [X] T020 [P] [US2] Add positive and negative authorization coverage for tenant-safe summary rendering and related links in `apps/platform/tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php` ### Implementation for User Story 2 - [X] T021 [US2] Implement `tenant.evidence.snapshot.generate` and `tenant.review_pack.generate` summary mappings with distinct execution and artifact-impact facts in `apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php` - [X] T022 [US2] Render separated execution outcome and artifact-impact facts in `apps/platform/app/Filament/Resources/OperationRunResource.php` - [X] T023 [US2] Keep related artifact navigation and tenant-context continuity aligned with summary copy in `apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php` - [X] T024 [US2] Extend canonical route isolation assertions for deny-as-not-found and in-scope `403` behavior in `apps/platform/tests/Feature/RunAuthorizationTenantIsolationTest.php` **Checkpoint**: A technically completed run can no longer read like unconditional success when the artifact itself is stale, limited, or internal-only. --- ## Phase 5: User Story 3 - Read multi-cause degraded runs without flattening (Priority: P3) **Goal**: Keep degraded governance runs understandable by showing one dominant cause first while preserving secondary causes and affected-scale context. **Independent Test**: Open a seeded multi-cause tenant-review run on `/admin/operations/{run}` and confirm the page shows one dominant cause first, preserves secondary causes, and keeps the same ordering across reloads. ### Tests for User Story 3 - [X] T025 [P] [US3] Add feature scenarios for tenant-review multi-cause degraded runs, stable dominant-cause ordering, and cross-family parity for the same cause class across at least two covered governance families in `apps/platform/tests/Feature/Monitoring/GovernanceOperationRunSummariesTest.php` - [X] T026 [P] [US3] Add unit cases for dominant-cause ranking, secondary causes, and affected-scale confidence in `apps/platform/tests/Unit/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilderTest.php` ### Implementation for User Story 3 - [X] T027 [US3] Implement `tenant.review.compose` multi-cause summary mapping and shared ranking rules across covered governance families in `apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php` - [X] T028 [US3] Render secondary-cause breakdown and affected-scale detail without flattening the dominant explanation in `apps/platform/app/Filament/Resources/OperationRunResource.php` - [X] T029 [US3] Suppress inaccessible tenant and artifact hints in summary text and related-navigation branches in `apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php` - [X] T030 [US3] Keep canonical run-detail banners and page-shell copy free of duplicated multi-cause messaging in `apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php` - [X] T031 [US3] Extend authorization surface assertions so inaccessible related context never leaks through summary or navigation output in `apps/platform/tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php` **Checkpoint**: Multi-cause degraded runs stay human-readable, deterministically ordered, and tenant-safe. --- ## Phase 6: Polish & Cross-Cutting Concerns **Purpose**: Final guardrail review, formatting, focused validation, and manual smoke. - [X] T032 [P] Review monitoring-state-page guardrail coverage, lane assignment, and fixture-cost notes against `specs/220-governance-run-summaries/plan.md` and `specs/220-governance-run-summaries/quickstart.md` - [X] T033 [P] Format changed PHP and Blade files including `apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php`, `apps/platform/app/Filament/Resources/OperationRunResource.php`, `apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php`, and `apps/platform/resources/views/filament/pages/operations/tenantless-operation-run-viewer.blade.php` - [X] T034 Run the canonical proving commands for `apps/platform/tests/Feature/Monitoring/GovernanceOperationRunSummariesTest.php`, `apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php`, `apps/platform/tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php`, `apps/platform/tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php`, `apps/platform/tests/Feature/RunAuthorizationTenantIsolationTest.php`, `apps/platform/tests/Unit/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilderTest.php`, and `apps/platform/tests/Unit/Support/OperatorExplanation/OperatorExplanationBuilderTest.php` - [X] T035 [P] Execute the manual smoke checks for summary-first hierarchy, zero-output runs, multi-cause runs, cross-family parity, and tenant-safe related links in `specs/220-governance-run-summaries/quickstart.md` --- ## Dependencies - Setup tasks `T001-T003` can begin immediately. - Foundational tasks `T004-T008` depend on setup and block all story work. - User Story 1 depends on Phase 2 and is the MVP slice. - User Story 2 depends on Phase 2 and the shared summary rendering established in User Story 1 because it extends the same builder and canonical detail surface. - User Story 3 depends on Phase 2 and should follow User Story 1 because it extends the same ranking and rendering seams; it can overlap with late User Story 2 test work once the shared builder contract is stable. - Polish tasks depend on all user stories being complete. ## Parallel Execution Examples - **US1**: Run `T009` and `T010` together; after `T011-T012`, split `T013`, `T014`, and `T015` across different files. - **US2**: Run `T018`, `T019`, and `T020` together; after `T021`, split `T022`, `T023`, and `T024` across resource, page, and authorization files. - **US3**: Run `T025` and `T026` together; after `T027`, split `T028`, `T029`, and `T030` while keeping `T031` as the final authorization proof. ## Implementation Strategy - Finish Setup and Foundational phases first so the derived summary seam and opt-in fixtures are stable. - Deliver User Story 1 as the MVP because it provides the first operator-visible improvement on canonical run detail. - Extend the same seam through User Story 2 to separate execution success from artifact trust across additional governance families. - Finish with User Story 3 to lock deterministic multi-cause ranking and no-leak summary behavior. - Close with formatting, focused proving commands, and the manual smoke pass documented in `quickstart.md`.