ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects 1 Releases Wiki Activity
d98dc30520
TenantAtlas/specs/166-finding-governance-health/tasks.md
ahmido 55aef627aa feat: harden finding governance health surfaces (#197) 
## Summary
- harden findings and finding-exception Filament surfaces so workflow state, governance validity, overdue urgency, and next action are operator-first
- add tenant stats widgets, segmented tabs, richer governance warnings, and baseline/dashboard attention propagation for overdue and lapsed governance states
- add Spec 166 artifacts plus regression coverage for findings, badges, baseline summaries, tenantless operation viewer behavior, and critical table standards

## Verification
- `vendor/bin/sail bin pint --dirty --format agent`
- `vendor/bin/sail artisan test --compact`

## Filament Notes
- Livewire v4.0+ compliance: yes, implementation stays on Filament v5 / Livewire v4 APIs only
- Provider registration: unchanged, Laravel 12 panel/provider registration remains in `bootstrap/providers.php`
- Global search: unchanged in this slice; `FindingExceptionResource` stays not globally searchable, no new globally searchable resource was introduced
- Destructive actions: existing revoke/reject/approve/renew/workflow mutations remain capability-gated and confirmation-gated where already defined
- Asset strategy: no new assets added; existing deploy process remains unchanged, including `php artisan filament:assets` when registered assets are used
- Testing plan delivered: findings list/detail, exception register, dashboard attention, baseline summary, badge semantics, and tenantless operation viewer coverage

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #197
2026-03-28 10:11:12 +00: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

  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.