Ahmed Darrazi 419a289dd8 feat: bridge finding exception approval queue

2026-03-28 11:07:19 +01:00

21 KiB

Raw Blame History

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.

T003 Normalize derived governance-attention, warning-message, and resolution-context behavior in app/Services/Findings/FindingRiskGovernanceResolver.php
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
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

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

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
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
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

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
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
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

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
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
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

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
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

T032 [US1+US3] Add finding severity badge column to exception register table using centralized FindingSeverity badge domain in app/Filament/Resources/FindingExceptionResource.php
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
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
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
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
T037 Add finding severity filter option catalog entry in app/Support/Filament/FilterOptionCatalog.php
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
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
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
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
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

# 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

# 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

# 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

# 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

Complete Phase 1 and Phase 2.
Deliver User Story 1 as the MVP so accepted risk no longer hides governance drift.
Confirm the main false-calm risk is closed before broadening summary and detail refinements.

Incremental Delivery

Add User Story 2 to remove false reassurance from resolved and closed surfaces.
Add User Story 3 so dashboard and baseline-compare summaries report overdue and unhealthy governance honestly.
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.

21 KiB Raw Blame History