18 KiB
Tasks: Tenant Dashboard KPI & Attention Truth Alignment
Input: Design documents from /specs/173-tenant-dashboard-truth-alignment/
Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/, quickstart.md
Tests: Tests are REQUIRED for this feature. Use Pest coverage in tests/Feature/Filament/DashboardKpisWidgetTest.php, tests/Feature/Filament/TenantDashboardTruthAlignmentTest.php, tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php, tests/Feature/Filament/NeedsAttentionWidgetTest.php, tests/Feature/Filament/BaselineCompareNowWidgetTest.php, tests/Feature/Filament/BaselineCompareSummaryConsistencyTest.php, tests/Feature/Findings/FindingsListDefaultsTest.php, tests/Feature/Findings/FindingsListFiltersTest.php, tests/Feature/Findings/FindingAdminTenantParityTest.php, tests/Feature/OpsUx/CanonicalViewRunLinksTest.php, tests/Feature/Filament/TenantDashboardTenantScopeTest.php, tests/Feature/Filament/TenantDashboardDbOnlyTest.php, tests/Feature/Filament/TableStandardsBaselineTest.php, and tests/Feature/Filament/TableDetailVisibilityTest.php.
Operations: This feature does not create a new OperationRun type or change run lifecycle ownership. Existing canonical Operations routes remain the only operations destinations involved, and the work here is limited to tenant-prefilter continuity and operator-facing summary truth.
RBAC: Existing tenant-context membership, entitlement, and 404 vs 403 semantics remain unchanged. Tasks must preserve tenant-safe dashboard destinations and ensure canonical Operations drill-throughs remain filtered to the originating tenant when entered from tenant context.
Operator Surfaces: DashboardKpis, NeedsAttention, BaselineCompareNow, RecentDriftFindings, and RecentOperations must stay operator-first, with governance posture and compare caution above recency context.
Filament UI Action Surfaces: No new destructive actions or redundant inspect affordances are added. DashboardKpis and NeedsAttention remain drill-through summary surfaces, BaselineCompareNow remains a single-next-step compare surface, and RecentDriftFindings and RecentOperations remain row-click diagnostic tables.
Filament UI UX-001: No new create, edit, or view pages are introduced. Existing dashboard summary and table widgets keep their current layout while truth alignment and destination continuity are hardened.
Badges: Existing badge semantics for finding severity, finding status, compare posture, operation status, and operation outcome remain authoritative; no new page-local mappings are introduced.
Organization: Tasks are grouped by user story so each story can be implemented and verified as an independent increment.
Phase 1: Setup (Dashboard Truth Test Scaffolding)
Purpose: Create the focused regression files and fixtures needed to implement Spec 173 safely.
- T001 Create dashboard truth-alignment regression scaffolding in
tests/Feature/Filament/DashboardKpisWidgetTest.phpandtests/Feature/Filament/TenantDashboardTruthAlignmentTest.php - T002 [P] Create canonical operations drill-through regression scaffolding in
tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php
Phase 2: Foundational (Blocking Destination and Semantics Helpers)
Purpose: Establish the canonical findings and operations drill-through semantics that all stories depend on.
⚠️ CRITICAL: No user story work should begin until this phase is complete.
- T003 Add destination-side continuity and permission-limited affordance assertions for dashboard-driven findings and operations filters in
tests/Feature/Findings/FindingsListFiltersTest.phpandtests/Feature/OpsUx/CanonicalViewRunLinksTest.php - T004 [P] Implement reusable findings subset semantics for dashboard links in
app/Models/Finding.phpandapp/Filament/Resources/FindingResource/Pages/ListFindings.php - T005 [P] Implement tenant-prefiltered canonical Operations collection links in
app/Support/OperationRunLinks.phpandapp/Filament/Pages/Monitoring/Operations.php
Checkpoint: Dashboard destinations now have one canonical findings subset model and one tenant-safe canonical Operations entry path.
Phase 3: User Story 1 - Trust The Dashboard At A Glance (Priority: P1) 🎯 MVP
Goal: Make the tenant dashboard read honestly at a glance so it never looks calmer than the tenant's actual governance and findings state.
Independent Test: Seed one tenant with overdue findings, lapsed or expiring governance, compare limitations, attention-worthy operations follow-up, and healthy all-clear states, then verify the dashboard summary surfaces do not emit contradictory calm and warning signals.
Tests for User Story 1
- T006 [P] [US1] Add KPI truth, no-all-clear regression cases, and permission-limited KPI affordance coverage in
tests/Feature/Filament/DashboardKpisWidgetTest.php - T007 [P] [US1] Add full-dashboard calmness suppression scenarios for overdue, lapsed, or expiring governance, compare limitations, and attention-worthy operations follow-up in
tests/Feature/Filament/TenantDashboardTruthAlignmentTest.php
Implementation for User Story 1
- T008 [US1] Align KPI labels and count universes with canonical active/high-severity semantics and disabled/non-clickable fallback behavior in
app/Filament/Widgets/Dashboard/DashboardKpis.php - T009 [US1] Gate healthy fallback and attention wording against aggregate-backed lapsed or expiring governance, severity truth, and defined operations follow-up in
app/Filament/Widgets/Dashboard/NeedsAttention.phpandresources/views/filament/widgets/dashboard/needs-attention.blade.php - T010 [US1] Keep compare calmness and baseline-compare landing next-step continuity aligned with tenant attention conditions from the existing compare assessment and governance aggregate outputs in
app/Filament/Widgets/Dashboard/BaselineCompareNow.phpandresources/views/filament/widgets/dashboard/baseline-compare-now.blade.php - T011 [US1] Run focused US1 verification against
tests/Feature/Filament/DashboardKpisWidgetTest.php,tests/Feature/Filament/TenantDashboardTruthAlignmentTest.php,tests/Feature/Filament/NeedsAttentionWidgetTest.php,tests/Feature/Filament/BaselineCompareNowWidgetTest.php, andtests/Feature/Filament/BaselineCompareSummaryConsistencyTest.php
Checkpoint: The dashboard no longer presents an all-clear when overdue, lapsed, or compare-limited tenant states exist.
Phase 4: User Story 2 - Click A Number And Recover The Same Problem (Priority: P1)
Goal: Make KPI and attention drill-throughs land on destinations where the same problem family is immediately recognizable.
Independent Test: Click representative KPI and attention states for findings, compare posture, and operations activity, then verify the destination preserves tenant context and exposes the same problem family through filters, tabs, or explicit framing, or renders a disabled or non-clickable explanatory state when the member lacks destination capability.
Tests for User Story 2
- T012 [P] [US2] Add findings drill-through continuity cases and permission-limited KPI fallback cases in
tests/Feature/Filament/DashboardKpisWidgetTest.phpandtests/Feature/Findings/FindingsListFiltersTest.php - T013 [P] [US2] Add high-severity attention, baseline-compare landing, and Operations drill-through continuity cases, including permission-limited disabled or non-clickable states, in
tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.phpandtests/Feature/Filament/TenantDashboardTruthAlignmentTest.php
Implementation for User Story 2
- T014 [US2] Implement findings KPI URLs that reproduce named subsets through tabs and filters, with disabled or non-clickable fallback when destination capability is missing, in
app/Filament/Widgets/Dashboard/DashboardKpis.phpandapp/Filament/Resources/FindingResource/Pages/ListFindings.php - T015 [US2] Add one tenant-safe primary action per central attention item, including high-severity active-findings coverage, baseline-compare landing continuity, and disabled or non-clickable helper text when destination capability is missing, in
app/Filament/Widgets/Dashboard/NeedsAttention.phpandresources/views/filament/widgets/dashboard/needs-attention.blade.php - T016 [US2] Preserve tenant context for dashboard Operations drill-throughs in
app/Support/OperationRunLinks.phpandapp/Filament/Pages/Monitoring/Operations.php - T017 [US2] Run focused US2 verification against
tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php,tests/Feature/Filament/DashboardKpisWidgetTest.php,tests/Feature/Filament/TenantDashboardTruthAlignmentTest.php, andtests/Feature/Findings/FindingsListFiltersTest.php
Checkpoint: KPI and attention signals now open tenant-safe findings, baseline-compare, and operations destinations that clearly match the originating problem family.
Phase 5: User Story 3 - Separate Posture From Activity And History (Priority: P2)
Goal: Keep governance posture, operations activity, and recent diagnostic history visibly distinct so the dashboard remains a priority surface rather than a mixed feed.
Independent Test: Seed one tenant with healthy operations-only activity, failed, warning, stalled, or unusually long-running operations follow-up, governance-only issues, and recent successful history, then verify the dashboard preserves posture-first attention while leaving recent tables diagnostic.
Tests for User Story 3
- T018 [P] [US3] Add healthy operations-only, failed, warning, stalled, or unusually long-running follow-up, and recency-does-not-override-posture scenarios in
tests/Feature/Filament/TenantDashboardTruthAlignmentTest.php - T019 [P] [US3] Add diagnostic-surface safeguards and row-click detail continuity checks for recent tables in
tests/Feature/Filament/TenantDashboardDbOnlyTest.phpandtests/Feature/Filament/TableDetailVisibilityTest.php
Implementation for User Story 3
- T020 [US3] Separate healthy operations activity wording from governance posture and map failed, warning, stalled, or unusually long-running runs to explicit follow-up attention in
app/Filament/Widgets/Dashboard/DashboardKpis.phpandapp/Filament/Widgets/Dashboard/NeedsAttention.php - T021 [US3] Preserve diagnostic-only framing and existing full-row detail navigation for recent tables in
app/Filament/Widgets/Dashboard/RecentDriftFindings.phpandapp/Filament/Widgets/Dashboard/RecentOperations.php - T022 [US3] Run focused US3 verification against
tests/Feature/Filament/TenantDashboardTruthAlignmentTest.php,tests/Feature/Filament/TenantDashboardDbOnlyTest.php,tests/Feature/Filament/TableStandardsBaselineTest.php, andtests/Feature/Filament/TableDetailVisibilityTest.php
Checkpoint: The dashboard now distinguishes what is risky, what is merely running, and what is only recent context.
Phase 6: Polish & Cross-Cutting Concerns
Purpose: Finish copy alignment, formatting, and the focused verification pack across all stories.
- T023 [P] Align operator-facing dashboard copy for the 10-second operator scan, operations follow-up wording, and permission-limited helper text in
app/Filament/Widgets/Dashboard/DashboardKpis.php,app/Filament/Widgets/Dashboard/NeedsAttention.php,app/Filament/Widgets/Dashboard/BaselineCompareNow.php,resources/views/filament/widgets/dashboard/needs-attention.blade.php, andresources/views/filament/widgets/dashboard/baseline-compare-now.blade.php - T024 Run formatting with
vendor/bin/sail bin pint --dirty --format agentusingspecs/173-tenant-dashboard-truth-alignment/quickstart.md - T025 Run the final verification pack from
specs/173-tenant-dashboard-truth-alignment/quickstart.mdagainsttests/Feature/Filament/DashboardKpisWidgetTest.php,tests/Feature/Filament/TenantDashboardTruthAlignmentTest.php,tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php,tests/Feature/Filament/NeedsAttentionWidgetTest.php,tests/Feature/Filament/BaselineCompareNowWidgetTest.php,tests/Feature/Filament/BaselineCompareSummaryConsistencyTest.php,tests/Feature/Findings/FindingsListDefaultsTest.php,tests/Feature/Findings/FindingsListFiltersTest.php,tests/Feature/Findings/FindingAdminTenantParityTest.php,tests/Feature/OpsUx/CanonicalViewRunLinksTest.php,tests/Feature/Filament/TenantDashboardTenantScopeTest.php,tests/Feature/Filament/TenantDashboardDbOnlyTest.php,tests/Feature/Filament/TableStandardsBaselineTest.php, andtests/Feature/Filament/TableDetailVisibilityTest.php - T026 Run the timed operator-comprehension smoke check from
specs/173-tenant-dashboard-truth-alignment/quickstart.mdon seeded tenants, including a permission-limited member scenario
Dependencies & Execution Order
Phase Dependencies
- Setup (Phase 1): Starts immediately and creates the new regression files for this slice.
- Foundational (Phase 2): Depends on Setup and blocks all user stories until destination semantics are canonicalized.
- User Stories (Phase 3+): All depend on Foundational completion.
- Polish (Phase 6): Depends on all desired user stories being complete.
User Story Dependencies
- User Story 1 (P1): Can start after Foundational completion and delivers the MVP truth-alignment slice.
- User Story 2 (P1): Can start after Foundational completion and should remain independently testable, though it touches some of the same dashboard widgets as US1.
- User Story 3 (P2): Can start after Foundational completion and remains independently testable, though it overlaps with the same dashboard surface family.
Within Each User Story
- Story tests should be written before or alongside the implementation tasks and must fail before the story is considered complete.
- Destination helper changes should land before the focused story-level verification run.
- Widget logic should land before any view-copy refinements tied to the same story.
Parallel Opportunities
T001andT002can run in parallel during Setup.T004andT005can run in parallel during Foundational work.T006andT007can run in parallel for User Story 1.T012andT013can run in parallel for User Story 2.T018andT019can run in parallel for User Story 3.T023can run while final verification commands are being prepared.
Parallel Example: User Story 1
# User Story 1 tests in parallel:
Task: T006 tests/Feature/Filament/DashboardKpisWidgetTest.php
Task: T007 tests/Feature/Filament/TenantDashboardTruthAlignmentTest.php
# User Story 1 implementation split after foundational semantics are in place:
Task: T008 app/Filament/Widgets/Dashboard/DashboardKpis.php
Task: T010 app/Filament/Widgets/Dashboard/BaselineCompareNow.php and resources/views/filament/widgets/dashboard/baseline-compare-now.blade.php
Parallel Example: User Story 2
# User Story 2 tests in parallel:
Task: T012 tests/Feature/Filament/DashboardKpisWidgetTest.php and tests/Feature/Findings/FindingsListFiltersTest.php
Task: T013 tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php and tests/Feature/Filament/TenantDashboardTruthAlignmentTest.php
# User Story 2 implementation split after tests exist:
Task: T015 app/Filament/Widgets/Dashboard/NeedsAttention.php and resources/views/filament/widgets/dashboard/needs-attention.blade.php
Task: T016 app/Support/OperationRunLinks.php and app/Filament/Pages/Monitoring/Operations.php
Parallel Example: User Story 3
# User Story 3 tests in parallel:
Task: T018 tests/Feature/Filament/TenantDashboardTruthAlignmentTest.php
Task: T019 tests/Feature/Filament/TenantDashboardDbOnlyTest.php and tests/Feature/Filament/TableDetailVisibilityTest.php
# User Story 3 implementation split after posture/activity requirements are settled:
Task: T020 app/Filament/Widgets/Dashboard/DashboardKpis.php and app/Filament/Widgets/Dashboard/NeedsAttention.php
Task: T021 app/Filament/Widgets/Dashboard/RecentDriftFindings.php and app/Filament/Widgets/Dashboard/RecentOperations.php
Implementation Strategy
MVP First (User Story 1 Only)
- Complete Phase 1: Setup.
- Complete Phase 2: Foundational.
- Complete Phase 3: User Story 1.
- STOP and VALIDATE: Verify the dashboard no longer emits false calm when tenant attention conditions exist.
Incremental Delivery
- Complete Setup + Foundational to lock down canonical destination semantics.
- Deliver User Story 1 as the MVP truth-alignment slice.
- Add User Story 2 for drill-through continuity.
- Add User Story 3 for posture/activity/recency separation.
- Finish with polish, formatting, the timed operator smoke check, and the final focused verification pack.
Parallel Team Strategy
- One developer can prepare the new regression files while another hardens canonical findings and Operations destination helpers.
- After Foundational work is complete, one developer can focus on KPI and compare calmness while another handles
NeedsAttentionactionability and Operations drill-through continuity. - Rejoin for story-level verification and final polish because several stories touch the same dashboard widget family.
Notes
[P]tasks target different files or safe concurrent work after foundational semantics are in place.[US1],[US2], and[US3]labels map tasks directly to the feature specification user stories.- The suggested MVP scope is Phase 1 through Phase 3 only.
- No task in this plan introduces new persistence, a new Graph contract, a new panel/provider registration, or a new destructive action.