TenantAtlas/specs/245-customer-health-score/tasks.md

description
Task list for Customer Health Score

Tasks: Customer Health Score

Input: Design documents from /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/245-customer-health-score/
Prerequisites: /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/245-customer-health-score/plan.md (required), /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/245-customer-health-score/spec.md (required), /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/245-customer-health-score/checklists/requirements.md (required)

Tests (TEST-GOV-001): REQUIRED (Pest) for all runtime behavior changes in this slice. Keep proof in Unit + Feature lanes only.
Operations: This slice must not change OperationRun start, completion, notification, or link UX.
RBAC: Existing /system dashboard access remains authoritative. No tenant/admin-plane or customer-facing health viewer is introduced.
Organization: Tasks are grouped by user story so aggregate health counts, the attention-needed workspace list, and edge-case hardening remain independently deliverable. Core unknown-handling lives in the foundational query path.

Phase 1: Setup (Shared Infrastructure)

Purpose: Prepare the bounded support namespace and narrow test surfaces for the first slice.

• T001 Create the feature-local support namespace and test directories under apps/platform/app/Support/CustomerHealth/, apps/platform/tests/Unit/Support/CustomerHealth/, and apps/platform/tests/Feature/System/CustomerHealth/

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Add the single shared dimension catalog and derived summary query before any dashboard UI adoption.

Checkpoint: One bounded, derived-only customer-health path exists before the dashboard starts rendering it, including the base unknown-handling and review-pack-readiness rules.

• T002 Create the fixed first-slice dimension catalog in apps/platform/app/Support/CustomerHealth/CustomerHealthDimensionCatalog.php, reusing existing SystemHealth level semantics and locking the first slice to onboarding readiness, provider connection health, operational stability, governance pressure, review-pack readiness, and engagement freshness
• T003 Create the derived workspace summary query in apps/platform/app/Support/CustomerHealth/WorkspaceHealthSummaryQuery.php that reads existing onboarding, provider connection, telemetry, OperationRun, findings, and review-pack truth without introducing a persisted score model, and bakes in the base unknown-handling plus selected-window review-pack-readiness rules
• T004 [P] Add unit coverage for dimension labels, level precedence, unknown handling, the selected-window review-pack-readiness rule table, and windowed versus point-in-time signal rules in apps/platform/tests/Unit/Support/CustomerHealth/CustomerHealthDimensionCatalogTest.php and apps/platform/tests/Unit/Support/CustomerHealth/WorkspaceHealthSummaryQueryTest.php
• T005 Run the foundational unit suite with export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/CustomerHealth/CustomerHealthDimensionCatalogTest.php tests/Unit/Support/CustomerHealth/WorkspaceHealthSummaryQueryTest.php

---

Phase 3: User Story 1 - See Portfolio Health At A Glance (Priority: P1) 🎯 MVP

Goal: Show aggregate workspace-health counts on the existing /system dashboard.

Independent Test: Seed mixed workspace truth and verify the dashboard renders aggregate ok, warn, critical, and unknown counts with explicit unknown handling.

Tests for User Story 1

• T006 [P] [US1] Add dashboard feature coverage for aggregate health counts, unknown handling, selected-window behavior, and a visible time-basis cue in apps/platform/tests/Feature/System/CustomerHealth/CustomerHealthDashboardWidgetsTest.php

Implementation for User Story 1

• T007 [US1] Create the summary stats widget in apps/platform/app/Filament/System/Widgets/CustomerHealthKpis.php using the shared StatsOverviewWidget pattern and WorkspaceHealthSummaryQuery, including visible copy that distinguishes selected-window dimensions from point-in-time dimensions
• T008 [US1] Register the new summary widget on apps/platform/app/Filament/System/Pages/Dashboard.php without changing the existing system dashboard access gate or header actions
• T009 [US1] Run the first-slice dashboard summary proof with export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/System/CustomerHealth/CustomerHealthDashboardWidgetsTest.php

---

Phase 4: User Story 2 - Review Attention-Needed Workspaces With Explainable Reasons (Priority: P1)

Goal: List the worst workspaces first with dominant health dimensions and one platform-safe next link.

Independent Test: Seed several unhealthy workspaces and verify the dashboard shows them in priority order with dominant reasons and platform-safe links only.

Tests for User Story 2

• T010 [P] [US2] Add feature coverage for deterministic workspace ordering, dominant-dimension rendering, operator-first default disclosure, absence of raw/support detail on the default dashboard surface, absence of duplicate visible decision summaries across the two widgets, and exactly one platform-safe next link per row with the tenant-detail fallback path in apps/platform/tests/Feature/System/CustomerHealth/CustomerHealthExplainabilityTest.php

Implementation for User Story 2

• T011 [US2] Create the compact attention widget in apps/platform/app/Filament/System/Widgets/CustomerHealthTopWorkspaces.php
• T012 [US2] Add the companion Blade view in apps/platform/resources/views/filament/system/widgets/customer-health-top-workspaces.blade.php, keeping the surface read-only and triage-first
• T013 [US2] Use existing platform-plane link helpers inside apps/platform/app/Filament/System/Widgets/CustomerHealthTopWorkspaces.php so each row exposes exactly one next link on system directory or system operations surfaces, with fallback to system tenant detail when no more specific platform-plane route is appropriate
• T014 [US2] Register the attention-needed widget on apps/platform/app/Filament/System/Pages/Dashboard.php without turning /system into a second workbench page
• T015 [US2] Run the explainability and link proof with export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/System/CustomerHealth/CustomerHealthExplainabilityTest.php

---

Phase 5: User Story 3 - Keep Health Honest And Narrow (Priority: P2)

Goal: Harden archived-workspace and archived-tenant handling, authorization, and dominant-reason edge cases after the foundational unknown-handling rules are already in place.

Independent Test: Verify that archived workspaces stay out of active attention counts, archived tenants do not drive active workspace health, review-pack edge cases continue to follow the selected-window rule, and unauthorized users cannot read the widgets.

Tests for User Story 3

• T016 [P] [US3] Add feature coverage for /system authorization boundaries in apps/platform/tests/Feature/System/CustomerHealth/CustomerHealthAuthorizationTest.php
• T017 [P] [US3] Extend apps/platform/tests/Unit/Support/CustomerHealth/WorkspaceHealthSummaryQueryTest.php with archived-workspace, archived-tenant, dominant-reason ordering, and recent-review-pack-request edge cases that harden the existing foundational rules

Implementation for User Story 3

• T018 [US3] Harden apps/platform/app/Support/CustomerHealth/WorkspaceHealthSummaryQuery.php for archived-workspace and archived-tenant exclusions, dominant-reason ordering, and review-pack edge cases without moving the core unknown-handling rules out of the foundation
• T019 [US3] Keep overall level rendering on existing BadgeDomain::SystemHealth semantics inside apps/platform/app/Filament/System/Widgets/CustomerHealthKpis.php and apps/platform/app/Filament/System/Widgets/CustomerHealthTopWorkspaces.php rather than introducing a new score language
• T020 [US3] Run the narrow safety and authorization proof with export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/CustomerHealth/WorkspaceHealthSummaryQueryTest.php tests/Feature/System/CustomerHealth/CustomerHealthAuthorizationTest.php

---

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Lock down vocabulary, formatting, and the minimal validation suite before implementation close-out.

• T021 [P] Confirm that dashboard labels, dominant reason copy, health levels, the visible time-basis cue, and the no-duplicate-visible-summary rule stay aligned across apps/platform/app/Support/CustomerHealth/CustomerHealthDimensionCatalog.php, the dashboard widgets, and any linked platform-safe surfaces
• T022 Run formatting on touched platform files with export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
• T023 Run the full narrow validation suite with export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/CustomerHealth tests/Feature/System/CustomerHealth/CustomerHealthDashboardWidgetsTest.php tests/Feature/System/CustomerHealth/CustomerHealthExplainabilityTest.php tests/Feature/System/CustomerHealth/CustomerHealthAuthorizationTest.php
• T024 Review apps/platform/app/Filament/System/Widgets/CustomerHealthTopWorkspaces.php and apps/platform/resources/views/filament/system/widgets/customer-health-top-workspaces.blade.php against /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/standards/list-surface-review-checklist.md, recording the accepted compact-widget exceptions before sign-off

Accepted compact-widget exceptions for sign-off: no persistence trio, no bulk actions, no row click, and no empty-state CTA because this is a read-only dashboard triage widget rather than a standalone Filament table surface.

---

Phase 7: Detail Follow-Up Decision Context

Purpose: Keep the dashboard-to-detail drilldown explainable by repeating the health decision above existing residual diagnostics.

• T025 [US2] Preserve the selected dashboard time window on system health-detail drilldown links in apps/platform/app/Support/CustomerHealth/WorkspaceHealthSummaryQuery.php so the linked residual detail pages can explain the same dominant drivers as the dashboard
• T026 [US2] Rename the tenant/workspace drilldown affordance in apps/platform/app/Support/CustomerHealth/WorkspaceHealthSummaryQuery.php from an opening verb to the decision-first Review health details copy while keeping Open runs unchanged for operational follow-up
• T027 [US2] Add a read-only customer-health decision card above existing diagnostics on apps/platform/app/Filament/System/Pages/Directory/ViewTenant.php, apps/platform/app/Filament/System/Pages/Directory/ViewWorkspace.php, and their directory Blade views by reusing WorkspaceHealthSummaryQuery
• T028 [P] [US2] Add focused feature coverage for the new residual detail follow-up card in apps/platform/tests/Feature/System/CustomerHealth/CustomerHealthDetailDecisionTest.php
• T029 [US2] Run the focused drilldown validation proof with export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/CustomerHealth/WorkspaceHealthSummaryQueryTest.php tests/Feature/System/CustomerHealth/CustomerHealthExplainabilityTest.php tests/Feature/System/CustomerHealth/CustomerHealthDetailDecisionTest.php

---

Dependencies & Execution Order

Recommended Execution Order

Phase 1 (Setup)
  ↓
Phase 2 (Dimension catalog + derived summary query)
  ↙        ↘
US1 (aggregate health counts)   US2 (attention-needed workspace list)
  ↓
US3 (honest unknown handling + authorization hardening)

Parallel Opportunities

• The foundational unit tests can be authored in parallel once the fixed first-slice dimension inventory is agreed.
• The aggregate summary widget and attention-needed widget feature tests can be written in parallel after the derived summary shape is stable.
• Authorization coverage can proceed in parallel with final unknown-handling hardening because it exercises existing /system gates.

---

Test Governance Checklist

• Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
• New or changed tests stay in the smallest honest family, and no heavy-governance or browser family is introduced accidentally.
• Shared helpers and fixture setup remain cheap by default.
• Planned validation commands cover the change without pulling in unrelated lane cost.
• The adopted surfaces explicitly use standard-native-filament relief.
• No material budget or baseline escalation is introduced.

Test-governance outcome (TEST-GOV-001): keep