259 lines
21 KiB
Markdown
259 lines
21 KiB
Markdown
# 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.
|