TenantAtlas/specs/173-tenant-dashboard-truth-alignment/tasks.md

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.php and tests/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.php and tests/Feature/OpsUx/CanonicalViewRunLinksTest.php
• T004 [P] Implement reusable findings subset semantics for dashboard links in app/Models/Finding.php and app/Filament/Resources/FindingResource/Pages/ListFindings.php
• T005 [P] Implement tenant-prefiltered canonical Operations collection links in app/Support/OperationRunLinks.php and app/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.php and resources/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.php and resources/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, and tests/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.php and tests/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.php and tests/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.php and app/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.php and resources/views/filament/widgets/dashboard/needs-attention.blade.php
• T016 [US2] Preserve tenant context for dashboard Operations drill-throughs in app/Support/OperationRunLinks.php and app/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, and tests/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.php and tests/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.php and app/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.php and app/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, and tests/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, and resources/views/filament/widgets/dashboard/baseline-compare-now.blade.php
• T024 Run formatting with vendor/bin/sail bin pint --dirty --format agent using specs/173-tenant-dashboard-truth-alignment/quickstart.md
• T025 Run the final verification pack from specs/173-tenant-dashboard-truth-alignment/quickstart.md against 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
• T026 Run the timed operator-comprehension smoke check from specs/173-tenant-dashboard-truth-alignment/quickstart.md on 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

• T001 and T002 can run in parallel during Setup.
• T004 and T005 can run in parallel during Foundational work.
• T006 and T007 can run in parallel for User Story 1.
• T012 and T013 can run in parallel for User Story 2.
• T018 and T019 can run in parallel for User Story 3.
• T023 can 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)

1. Complete Phase 1: Setup.
2. Complete Phase 2: Foundational.
3. Complete Phase 3: User Story 1.
4. STOP and VALIDATE: Verify the dashboard no longer emits false calm when tenant attention conditions exist.

Incremental Delivery

1. Complete Setup + Foundational to lock down canonical destination semantics.
2. Deliver User Story 1 as the MVP truth-alignment slice.
3. Add User Story 2 for drill-through continuity.
4. Add User Story 3 for posture/activity/recency separation.
5. Finish with polish, formatting, the timed operator smoke check, and the final focused verification pack.

Parallel Team Strategy

1. One developer can prepare the new regression files while another hardens canonical findings and Operations destination helpers.
2. After Foundational work is complete, one developer can focus on KPI and compare calmness while another handles NeedsAttention actionability and Operations drill-through continuity.
3. 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.