# Tasks: Finding Governance Health & Resolution Semantics Surface Hardening **Input**: Design documents from `/specs/166-finding-governance-health/` **Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/, quickstart.md **Tests**: Tests are REQUIRED for this feature because it changes runtime operator behavior across Filament resources, widgets, authorization-sensitive surfaces, and shared badge semantics. **Operations**: This feature introduces no new `OperationRun`; tasks focus on DB-backed surface hardening, existing confirmation behavior, and semantic consistency across findings, exceptions, and summary surfaces. **RBAC**: This feature changes tenant and canonical read surfaces, so tasks must preserve capability-registry enforcement, `404` vs `403` semantics, tenant-safe filtering, and cross-tenant leakage guards. **Filament UI**: This feature modifies Filament resources, pages, and widgets, so tasks include Action Surface Contract, BADGE-001, OPSURF-001, and UX-001 regression coverage. ## Phase 1: Setup (Shared Infrastructure) **Purpose**: Prepare shared seeded scenarios and reusable verification entry points for all stories. - [ ] T001 Extend shared seeded findings scenarios for overdue, historical, healthy accepted-risk, and lapsed-governance cases, including expiring, expired, revoked, rejected where operator-visible, and missing-support governance states, in `database/factories/FindingFactory.php` and `tests/Feature/Findings/FindingRiskGovernanceProjectionTest.php` - [ ] T002 [P] Refresh shared dashboard and baseline-compare verification fixtures for governance-attention scenarios in `tests/Feature/Filament/NeedsAttentionWidgetTest.php`, `tests/Feature/Filament/BaselineCompareNowWidgetTest.php`, and `tests/Feature/Filament/BaselineCompareLandingWhyNoFindingsTest.php` --- ## Phase 2: Foundational (Blocking Prerequisites) **Purpose**: Establish the shared semantic primitives that every story depends on before surface-specific work begins. **⚠️ CRITICAL**: No user story work should begin until this phase is complete. - [X] T003 Normalize derived governance-attention, warning-message, and resolution-context behavior in `app/Services/Findings/FindingRiskGovernanceResolver.php` - [X] T004 [P] Centralize the hardened governance and lifecycle vocabulary in `app/Support/Badges/BadgeCatalog.php`, `app/Support/Badges/BadgeRenderer.php`, `app/Support/Badges/Domains/FindingRiskGovernanceValidityBadge.php`, and `app/Support/Badges/Domains/FindingStatusBadge.php` - [X] T005 [P] Extend shared lifecycle and governance filter definitions for findings and exception surfaces in `app/Support/Filament/FilterOptionCatalog.php`, `app/Filament/Resources/FindingResource.php`, and `app/Filament/Resources/FindingExceptionResource.php` - [ ] T006 Add foundational semantic regression coverage for resolver, badges, and filter truth in `tests/Feature/Findings/FindingRiskGovernanceProjectionTest.php`, `tests/Unit/Badges/FindingBadgesTest.php`, and `tests/Unit/Badges/BadgeCatalogTest.php` **Checkpoint**: Shared governance semantics are ready. User story work can now proceed. --- ## Phase 3: User Story 1 - Distinguish Safe Accepted Risk From Governance Drift (Priority: P1) 🎯 MVP **Goal**: Make tenant findings and exception surfaces visibly distinguish healthy accepted risk from accepted risk that has governance attention or drift. **Independent Test**: Seed healthy, expiring, expired, revoked, rejected where operator-visible, and missing-support accepted-risk findings and verify that findings list, finding detail, tenant exception register, and canonical queue distinguish the relevant states without contradictory semantics. ### Tests for User Story 1 - [X] T007 [P] [US1] Add findings-list coverage for healthy versus expiring, expired, revoked, rejected where operator-visible, or missing-support accepted risk, overdue prioritization, owner or assignee promotion, and governance-aware filters in `tests/Feature/Findings/FindingsListDefaultsTest.php` and `tests/Feature/Findings/FindingsListFiltersTest.php` - [ ] T008 [P] [US1] Add tenant-register and canonical-queue parity coverage for governance-validity visibility across expiring, expired, revoked, rejected where operator-visible, and missing-support states, plus tenant-prefilter handoff and authorized tenant-filter broadening in `tests/Feature/Findings/FindingExceptionRegisterTest.php`, `tests/Feature/Monitoring/FindingExceptionsQueueTest.php`, and `tests/Feature/Findings/FindingRelatedNavigationTest.php` - [ ] T009 [P] [US1] Add positive and negative authorization coverage for tenant findings and canonical exception governance states, including `404` versus `403` outcomes and no-regression capability gating for existing mutation actions in `tests/Feature/Findings/FindingRbacTest.php` and `tests/Feature/Findings/FindingExceptionAuthorizationTest.php` ### Implementation for User Story 1 - [X] T010 [US1] Harden tenant findings list lifecycle badges, governance cues, overdue emphasis, owner or assignee promotion, and related filters in `app/Filament/Resources/FindingResource.php` and `app/Filament/Resources/FindingResource/Pages/ListFindings.php` - [X] T011 [US1] Align finding detail governance warnings and healthy accepted-risk messaging with shared resolver truth in `app/Filament/Resources/FindingResource.php` and `app/Filament/Resources/FindingResource/Pages/ViewFinding.php` - [X] T012 [US1] Align tenant exception register and canonical exception queue governance semantics, tenant-prefilter entry behavior, and authorized tenant-filter broadening with finding surfaces in `app/Filament/Resources/FindingExceptionResource.php`, `app/Filament/Resources/FindingExceptionResource/Pages/ListFindingExceptions.php`, `app/Filament/Resources/FindingExceptionResource/Pages/ViewFindingException.php`, `app/Filament/Pages/Monitoring/FindingExceptionsQueue.php`, and `app/Support/Navigation/RelatedNavigationResolver.php` **Checkpoint**: User Story 1 is independently functional and closes the primary false-calm risk. --- ## Phase 4: User Story 2 - Read Resolved And Closed States Without False Reassurance (Priority: P1) **Goal**: Present `resolved` and `closed` as historical workflow states rather than implicit proof of permanent remediation. **Independent Test**: Render resolved and closed findings on list, detail, and baseline-compare summary surfaces and verify that copy stays historically accurate, with any `no longer observed` context remaining secondary. ### Tests for User Story 2 - [ ] T013 [P] [US2] Add list and detail coverage that `resolved` and `closed` remain historical workflow states instead of technical proof while preserving relevant historical governance warnings as secondary context in `tests/Feature/Findings/FindingWorkflowViewActionsTest.php` and `tests/Feature/Filament/FindingViewRbacEvidenceTest.php` - [ ] T014 [P] [US2] Add baseline-compare and summary-copy coverage for historical findings without false all-clear language in `tests/Feature/Filament/BaselineCompareLandingWhyNoFindingsTest.php` and `tests/Feature/Filament/BaselineCompareSummaryConsistencyTest.php` ### Implementation for User Story 2 - [X] T015 [US2] Revise resolved and closed list/detail copy plus secondary `no longer observed` context while preserving relevant historical governance warnings from the exception trail in `app/Filament/Resources/FindingResource.php` and `app/Filament/Resources/FindingResource/Pages/ViewFinding.php` - [X] T016 [US2] Carry cautious historical semantics into baseline-compare assessment and explanation logic in `app/Support/Baselines/BaselineCompareSummaryAssessor.php`, `app/Support/Baselines/BaselineCompareSummaryAssessment.php`, and `app/Support/Baselines/BaselineCompareExplanationRegistry.php` - [X] T017 [US2] Update baseline-compare landing presentation so historical findings never read as healthy governance or technical clearance in `app/Filament/Pages/BaselineCompareLanding.php` and `resources/views/filament/pages/baseline-compare-landing.blade.php` **Checkpoint**: User Story 2 is independently functional and removes semantic overclaim from historical findings. --- ## Phase 5: User Story 3 - See Governance And Overdue Problems In Summary Surfaces (Priority: P2) **Goal**: Make tenant dashboard and baseline-compare summary surfaces surface overdue findings and unhealthy governance even when no findings are `new`. **Independent Test**: Seed a tenant with overdue open findings, expiring governance, and lapsed governance, then verify that dashboard and baseline-compare surfaces still show attention-required states and route operators into the right lists. ### Tests for User Story 3 - [ ] T018 [P] [US3] Add tenant-dashboard coverage for overdue findings plus expiring and lapsed governance attention in `tests/Feature/Filament/NeedsAttentionWidgetTest.php` and `tests/Feature/Filament/TenantDashboardDbOnlyTest.php` - [ ] T019 [P] [US3] Add baseline-compare widget and landing parity coverage for overdue and governance-attention summaries in `tests/Feature/Filament/BaselineCompareNowWidgetTest.php`, `tests/Feature/Baselines/BaselineCompareFindingsTest.php`, and `tests/Feature/Filament/BaselineCompareLandingAdminTenantParityTest.php` ### Implementation for User Story 3 - [X] T020 [US3] Extend tenant attention aggregates for overdue findings and unhealthy governance in `app/Filament/Widgets/Dashboard/NeedsAttention.php`, `resources/views/filament/widgets/dashboard/needs-attention.blade.php`, and `app/Filament/Pages/TenantDashboard.php` - [X] T021 [US3] Extend baseline-compare stats and assessment logic for overdue and governance-attention conditions in `app/Support/Baselines/BaselineCompareStats.php`, `app/Support/Baselines/BaselineCompareSummaryAssessor.php`, and `app/Support/Baselines/BaselineCompareReasonCode.php` - [X] T022 [US3] Surface the new attention states in baseline-compare widgets and landing UI in `app/Filament/Widgets/Dashboard/BaselineCompareNow.php`, `resources/views/filament/widgets/dashboard/baseline-compare-now.blade.php`, `app/Filament/Widgets/Tenant/BaselineCompareCoverageBanner.php`, `resources/views/filament/widgets/tenant/baseline-compare-coverage-banner.blade.php`, `app/Filament/Pages/BaselineCompareLanding.php`, and `resources/views/filament/pages/baseline-compare-landing.blade.php` **Checkpoint**: User Story 3 is independently functional and summary surfaces no longer underreport overdue or governance-risk work. --- ## Phase 6: User Story 4 - Get Operator-First Detail Before Diagnostics (Priority: P2) **Goal**: Reorder finding detail so status, governance, ownership, due context, and next action appear before IDs, evidence payloads, and lower-level diagnostics. **Independent Test**: Open an active finding, a healthy accepted-risk finding, and a lapsed-governance accepted-risk finding and verify that the first visible zone communicates lifecycle, governance, due urgency, ownership, and next-action guidance before diagnostic sections. ### Tests for User Story 4 - [ ] T023 [P] [US4] Add finding-detail information-order and leading-zone coverage in `tests/Feature/Filament/FindingViewRbacEvidenceTest.php` and `tests/Feature/Findings/FindingRelatedNavigationTest.php` - [ ] T024 [P] [US4] Add action-surface and table-contract regression coverage for the hardened finding and exception screens, including no-regression confirmation requirements for existing destructive actions, in `tests/Feature/Guards/ActionSurfaceContractTest.php` and `tests/Feature/Guards/FilamentTableRiskExceptionsGuardTest.php` ### Implementation for User Story 4 - [X] T025 [US4] Reorder finding detail into an operator-first status and governance zone ahead of diagnostics in `app/Filament/Resources/FindingResource.php` and `app/Filament/Resources/FindingResource/Pages/ViewFinding.php` - [X] T026 [US4] Tighten next-action guidance and related-record navigation from the leading finding-detail zone in `app/Filament/Resources/FindingResource/Pages/ViewFinding.php`, `app/Filament/Pages/Monitoring/FindingExceptionsQueue.php`, and `app/Support/Filament/FilterOptionCatalog.php` **Checkpoint**: User Story 4 is independently functional and the detail page becomes operator-first instead of diagnostics-first. --- ## Phase 6b: Queue Surface Hardening — Exception Register Enterprise UX (Priority: P2) **Goal**: Make the tenant risk-exception register (Finding Exceptions list) enterprise-grade by adding severity visibility, actionable finding titles, relative expiry context, KPI stats, and segmented quick-tabs. **Independent Test**: Open the tenant exception register and verify that severity badges, descriptive finding titles, relative time descriptions, stats overview, and quick-tab segmentation are visible and functional. ### Implementation for Queue Surface Hardening - [X] T032 [US1+US3] Add finding severity badge column to exception register table using centralized `FindingSeverity` badge domain in `app/Filament/Resources/FindingExceptionResource.php` - [X] T033 [US1] Improve finding summary in exception register to show subject display name plus finding type instead of bare `Finding #ID` in `app/Filament/Resources/FindingExceptionResource.php` - [X] T034 [US3] Add relative time descriptions (e.g. "In 3 days", "2 days ago") to review_due_at and expires_at columns in `app/Filament/Resources/FindingExceptionResource.php` - [X] T035 [US3] Create `FindingExceptionStatsOverview` widget showing Active/Expiring/Expired/Pending counts above the exception register table in `app/Filament/Widgets/Tenant/FindingExceptionStatsOverview.php` and `app/Filament/Resources/FindingExceptionResource/Pages/ListFindingExceptions.php` - [X] T036 [US1+US3] Add segmented quick-tabs (All / Needs action / Active / Historical) to exception register list page with badge count on Needs action tab in `app/Filament/Resources/FindingExceptionResource/Pages/ListFindingExceptions.php` - [X] T037 Add finding severity filter option catalog entry in `app/Support/Filament/FilterOptionCatalog.php` - [X] T038 [P] Add exception register enterprise-UX coverage for severity column, finding title, relative time, stats widget, and tab segmentation in `tests/Feature/Findings/FindingExceptionRegisterTest.php` **Checkpoint**: Exception register is enterprise-grade with severity, titles, relative timing, stats, and segmentation. --- ## Phase 7: Polish & Cross-Cutting Concerns **Purpose**: Lock in cross-surface consistency, tenant isolation, and final verification. - [ ] T027 [P] Add cross-surface consistency coverage for the same governance state across findings list, finding detail, exception register, canonical queue, tenant dashboard attention, and baseline-compare summary surfaces in `tests/Feature/Findings/FindingRiskGovernanceProjectionTest.php`, `tests/Feature/Findings/FindingExceptionRegisterTest.php`, `tests/Feature/Monitoring/FindingExceptionsQueueTest.php`, `tests/Feature/Filament/NeedsAttentionWidgetTest.php`, and `tests/Feature/Filament/BaselineCompareSummaryConsistencyTest.php` - [X] T028 [P] Refresh tenant-owned query and cross-tenant leakage guards for hardened findings, summaries, and exception surfaces in `tests/Feature/Guards/TenantOwnedQueryGuardTest.php`, `tests/Feature/Findings/FindingAdminTenantParityTest.php`, and `tests/Feature/Filament/TenantDashboardTenantScopeTest.php` - [X] T029 [P] Refresh no-ad-hoc status and warning badge guards for the new governance-attention states in `tests/Feature/Guards/NoAdHocStatusBadgesTest.php` and `tests/Feature/Guards/NoDiagnosticWarningBadgesTest.php` - [X] T030 Validate the Spec 166 quickstart scenarios and focused Pest pack in `specs/166-finding-governance-health/quickstart.md`, `tests/Feature/Findings/FindingsListDefaultsTest.php`, `tests/Feature/Findings/FindingExceptionRegisterTest.php`, `tests/Feature/Filament/NeedsAttentionWidgetTest.php`, and `tests/Feature/Filament/BaselineCompareLandingWhyNoFindingsTest.php` - [X] T031 Document any semantic distinction that cannot be stably derived from existing truth as follow-up foundation work in `specs/166-finding-governance-health/spec.md` and `specs/166-finding-governance-health/plan.md` --- ## Dependencies & Execution Order ### Phase Dependencies - **Setup (Phase 1)**: No dependencies; can start immediately. - **Foundational (Phase 2)**: Depends on Setup completion; blocks all user stories. - **User Story 1 (Phase 3)**: Depends on Foundational completion; recommended MVP slice. - **User Story 2 (Phase 4)**: Depends on Foundational completion and benefits from User Story 1 because hardened list/detail semantics are reused. - **User Story 3 (Phase 5)**: Depends on Foundational completion and benefits from User Story 1 and User Story 2 because summary attention logic should reuse the same governance and historical semantics. - **User Story 4 (Phase 6)**: Depends on Foundational completion and benefits from User Story 1 because the leading zone reuses the hardened governance cues. - **Polish (Phase 7)**: Depends on all desired user stories being complete. ### User Story Dependencies - **US1**: No dependency on other stories after Foundational; this is the MVP. - **US2**: Can start after Foundational, but should land after or alongside US1 so findings surfaces reuse the same accepted-risk semantics. - **US3**: Can start after Foundational, but should follow US1 and US2 for consistent governance and historical messaging on summaries. - **US4**: Can start after Foundational, but is safest after US1 because the detail leading zone depends on the hardened governance cues. ### Within Each User Story - Tests MUST be written and confirmed failing before implementation tasks begin. - Shared semantic helpers and badges must be updated before surface-specific copy or layout work closes. - Resource and page behavior should land before final guard and parity coverage is refreshed. ### Parallel Opportunities - `T002`, `T004`, and `T005` can run in parallel once `T001` and `T003` establish the seeded scenarios and semantic baseline. - In each user story, all `[P]` test tasks can run in parallel. - `T020` and `T021` can run in parallel during US3 once summary test expectations are in place. - `T027`, `T028`, and `T029` can run in parallel in the polish phase. --- ## Parallel Execution Examples ### User Story 1 ```bash # Run the User Story 1 test tasks in parallel: T007 Add findings-list coverage for healthy versus expiring or lapsed accepted risk. T008 Add tenant-register and canonical-queue parity coverage for governance-validity visibility. T009 Add positive and negative authorization coverage for tenant findings and canonical exception governance states. # Then implement the shared surface hardening in sequence: T010 Harden tenant findings list lifecycle badges, governance cues, overdue emphasis, and filters. T011 Align finding detail governance warnings and healthy accepted-risk messaging. T012 Align tenant exception register and canonical exception queue governance semantics. ``` ### User Story 2 ```bash # Run the User Story 2 test tasks in parallel: T013 Add list and detail coverage for cautious resolved and closed semantics. T014 Add baseline-compare and summary-copy coverage for historical findings. # Then implement the historical-state hardening in sequence: T015 Revise resolved and closed list/detail copy. T016 Carry cautious historical semantics into baseline-compare assessment logic. T017 Update baseline-compare landing presentation. ``` ### User Story 3 ```bash # Run the User Story 3 test tasks in parallel: T018 Add tenant-dashboard attention coverage. T019 Add baseline-compare widget and landing parity coverage. # Then implement the summary-surface work in sequence: T020 Extend tenant attention aggregates. T021 Extend baseline-compare stats and assessment logic. T022 Surface the new attention states in widgets and landing UI. ``` ### User Story 4 ```bash # Run the User Story 4 test tasks in parallel: T023 Add finding-detail information-order and leading-zone coverage. T024 Add action-surface and table-contract regression coverage. # Then implement the detail-page reordering in sequence: T025 Reorder finding detail into an operator-first status and governance zone. T026 Tighten next-action guidance and related-record navigation. ``` --- ## Implementation Strategy ### MVP First 1. Complete Phase 1 and Phase 2. 2. Deliver User Story 1 as the MVP so accepted risk no longer hides governance drift. 3. Confirm the main false-calm risk is closed before broadening summary and detail refinements. ### Incremental Delivery 1. Add User Story 2 to remove false reassurance from `resolved` and `closed` surfaces. 2. Add User Story 3 so dashboard and baseline-compare summaries report overdue and unhealthy governance honestly. 3. Add User Story 4 to make the detail page operator-first and reduce time-to-decision. ### Suggested MVP Scope - **Recommended MVP**: Phases 1 through 3 only. - **Why**: This delivers the highest-risk business correction first by making governance drift immediately visible on the primary findings workflow surfaces.