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

Feature Specification: Customer Health Score

Feature Branch: 245-customer-health-score
Created: 2026-04-27
Status: Ready for implementation
Input: User description: "Promote the roadmap-fit candidate Customer Health Score as a narrow, implementation-ready slice that derives an explainable workspace health summary from existing telemetry, onboarding readiness, provider connection health, operation outcomes, findings pressure, and review-pack readiness, then surfaces one attention-oriented summary on the existing system dashboard without introducing CRM, predictive scoring, billing collection, or customer-facing account-management workflows."

Spec Candidate Check (mandatory — SPEC-GATE-001)

• Problem: TenantPilot still requires founder-style manual inspection across onboarding, provider connections, failed runs, findings, review packs, and telemetry to understand which workspaces actually need attention.
• Today's failure: The product exposes isolated health clues, but no explainable workspace-level summary. Operators must reconstruct risk by hopping between /system, tenant directory, run lists, and tenant surfaces, which delays support and masks silent customer/workspace deterioration.
• User-visible improvement: A platform operator can open the existing /system dashboard and immediately see which workspaces are healthy, which need attention, why they need attention, and which existing platform-safe surface to open next. When the operator follows that link into the existing system tenant or workspace detail, the page repeats the decision-first health explanation above the existing diagnostics.
• Smallest enterprise-capable version: Add one derived customer-health query path with six fixed first-slice dimensions, reuse the existing system dashboard and window selector, show aggregate health counts plus an attention-needed workspace list, and keep the entire slice read-only and non-persistent.
• Explicit non-goals: No CRM or customer-success suite, no billing collection or entitlement enforcement, no predictive churn model, no customer-facing health portal, no tenant/admin-plane health viewer, no new persisted score table, no background recomputation job, and no AI-generated account-management actions.
• Permanent complexity imported: One bounded CustomerHealth support namespace, one derived summary query path, one small fixed dimension catalog, two dashboard widgets, and focused unit plus feature coverage.
• Why now: Self-Service Tenant Onboarding & Connection Readiness, Support Diagnostic Pack, Operational Controls, Product Usage & Adoption Telemetry, and Product Knowledge are now specced or implemented. Customer Health Score is the smallest next slice that turns those foundations into one operator-facing attention signal before lifecycle communication, AI assistance, or broader portfolio workflows expand.
• Why not local: Local counters on the system dashboard or one-off health badges in the directory would either duplicate logic across surfaces or hide how onboarding, provider, operational, governance, review-pack, and adoption truth combine into one explainable workspace summary.
• Approval class: Core Enterprise
• Red flags triggered: New abstraction, many-signal summary. Defense: the slice stays derived-only, reuses the existing SystemHealth level language, fixes the first-slice dimension inventory at six signals, and limits UI impact to the existing /system dashboard.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 1 | Komplexität: 1 | Produktnähe: 2 | Wiederverwendung: 2 | Gesamt: 10/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: platform, workspace, tenant
• Primary Routes:
  • /system existing system dashboard for aggregate health counts and the attention-needed workspace list
  • existing platform-safe deep links from those widgets into the system tenant directory and system operations surfaces
  • existing /system/directory/tenants/{tenant} and /system/directory/workspaces/{workspace} residual detail pages as read-only health follow-up surfaces
• Data Ownership: No new persisted customer-health truth is introduced. The summary is derived from existing tenant-owned product truths such as product_usage_events, provider_connections, operation_runs, findings, review_packs, and onboarding-readiness state already owned by existing onboarding/session/provider records.
• RBAC: Reads remain platform-plane only through the existing /system dashboard access gate. No tenant/admin-plane or customer-facing health surface is introduced in this slice.

For canonical-view specs, the spec MUST define:

• Default filter behavior when tenant-context is active: N/A - the first slice is a platform-plane dashboard addition under /system, not a tenant-context admin view.
• Explicit entitlement checks preventing cross-tenant leakage: The slice exposes derived counts and system-safe drilldown links only to existing platform users who can already access the system dashboard. It does not expose raw tenant-owned health rows or create any cross-plane deep link into /admin tenant surfaces.

Cross-Cutting / Shared Pattern Reuse (mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write N/A - no shared interaction family touched)

• Cross-cutting feature?: yes
• Interaction class(es): dashboard signals/cards, read-only attention list, system-safe deep links, status badges
• Systems touched: App\Filament\System\Pages\Dashboard, existing system dashboard widget family, App\Support\ProductTelemetry\ProductTelemetrySummaryQuery, App\Services\Providers\ProviderConnectionStateProjector, App\Support\SystemConsole\StuckRunClassifier, existing Finding and ReviewPack truth queries, and existing system link helpers
• Existing pattern(s) to extend: the /system dashboard widget composition, the existing dashboard time-window selector, ControlTowerHealthIndicator, and ControlTowerTopOffenders
• Shared contract / presenter / builder / renderer to reuse: StatsOverviewWidget, existing custom system widgets, BadgeRenderer with BadgeDomain::SystemHealth, SystemConsoleWindow, SystemOperationRunLinks, and existing system directory links
• Why the existing shared path is sufficient or insufficient: Existing shared paths already solve dashboard placement, read-only system-plane rendering, time-window selection, and system-safe navigation. They are insufficient because none of them currently derives one explainable workspace-health summary from multiple existing truths.
• Allowed deviation and why: One bounded CustomerHealth support namespace is allowed to centralize health derivation. Page-local health arithmetic, widget-local badge vocabularies, or duplicated query seams are not allowed.
• Consistency impact: Overall health levels must reuse the existing SystemHealth vocabulary (ok, warn, critical, unknown), and the first-slice dimension labels plus time-basis copy must remain consistent between summary widgets and any linked system-safe detail flow.
• Review focus: Reviewers must verify that the slice stays derived-only, does not add a hidden score table, does not invent a second badge taxonomy, does not create platform-to-admin deep links, and does not broaden into customer-success or billing workflow scope.

OperationRun UX Impact (mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an OperationRun; otherwise write N/A - no OperationRun start or link semantics touched)

• Touches OperationRun start/completion/link UX?: no
• Shared OperationRun UX contract/layer reused: N/A - the slice reads existing run truth only and may link to existing system run lists.
• Delegated start/completion UX behaviors: N/A
• Local surface-owned behavior that remains: N/A
• Queued DB-notification policy: N/A
• Terminal notification path: N/A
• Exception required?: none

Provider Boundary / Platform Core Check (mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write N/A - no shared provider/platform boundary touched)

• Shared provider/platform boundary touched?: yes
• Boundary classification: mixed
• Seams affected: provider verification and consent statuses as one health-dimension input, review-pack status labels, telemetry family activity, and system-safe health copy
• Neutral platform terms preserved or introduced: customer health, workspace health, health dimension, attention needed, engagement freshness, review readiness, operational stability
• Provider-specific semantics retained and why: Microsoft-specific provider consent and verification outcomes remain inside the provider-health dimension because they are existing current-release truth owned by provider-connection workflows.
• Why this does not deepen provider coupling accidentally: The top-level summary stays platform-owned and explainable. Provider-specific codes and statuses are consumed only as one input dimension and are not promoted into a new platform taxonomy.
• Follow-up path: Customer Lifecycle Communication and later portfolio workflows may reuse the summary, but they remain separate specs.

UI / Surface Guardrail Impact (mandatory when operator-facing surfaces are changed; otherwise write N/A)

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
System dashboard customer-health KPI widget	yes	Native Filament + shared stats widget	dashboard signals/cards	page, widget, window query	no	Read-only KPI addition on existing /system dashboard
System dashboard attention-needed workspace widget	yes	Native system widget family with custom Blade view	dashboard signals/cards, read-only attention list, navigation links	page, widget, detail-link state	no	Compact list of unhealthy workspaces only; no new page or workbench
System tenant and workspace residual detail pages customer-health decision card	yes	Existing custom system detail pages	linked follow-up context, decision-first explanation	page, window query	no	Read-only summary card above existing diagnostics; no new page or mutation

Decision-First Surface Role (mandatory when operator-facing surfaces are changed)

Surface	Decision Role	Human-in-the-loop Moment	Immediately Visible for First Decision	On-Demand Detail / Evidence	Why This Is Primary or Why Not	Workflow Alignment	Attention-load Reduction
System dashboard customer-health KPI widget	Secondary Context Surface	Decide whether overall platform attention is rising and whether to inspect unhealthy workspaces now	Count of healthy, warning, critical, and unknown workspaces for the selected window	Existing system tenant directory, operations list, and source surfaces remain evidence	Secondary because it frames attention, not the underlying remediation workflow	Fits the founder or platform-operator control-tower loop	Replaces manual reconstruction across onboarding, telemetry, runs, and findings surfaces
System dashboard attention-needed workspace widget	Secondary Context Surface	Decide which workspace to inspect next and which source truth is driving the problem	Workspace name, overall level, dominant dimensions, and one platform-safe next link	Existing system-safe detail surfaces and linked source contexts	Secondary because the actual action still happens on existing system detail and run surfaces	Keeps the dashboard as a triage layer, not a second operations workbench	Surfaces the next workspace to inspect without requiring freeform database or log inspection
System tenant and workspace residual detail pages customer-health decision card	Primary Decision Context	Decide why this workspace is critical, warn, or unknown before reading lower-level diagnostics	Overall level, repeated top drivers, operator impact, and recommended next action	Existing connectivity, permissions, tenant, and recent-run sections remain the lower-level evidence	Primary because the card turns the residual detail page into an explain-first follow-up instead of a diagnostic puzzle	Keeps /system drilldowns decision-first while preserving the existing read-mostly detail shape	Removes the need to infer the health reason from several independent sections

UI/UX Surface Classification (mandatory when operator-facing surfaces are changed)

Surface	Action Surface Class	Surface Type	Likely Next Operator Action	Primary Inspect/Open Model	Row Click	Secondary Actions Placement	Destructive Actions Placement	Canonical Collection Route	Canonical Detail Route	Scope Signals	Canonical Noun	Critical Truth Visible by Default	Exception Type / Justification
System dashboard customer-health KPI widget	Dashboard / Overview / KPI widget	Read-only operational summary	Decide whether there is platform-wide attention pressure	In-page stat cards	forbidden	none	none	/system	/system	Existing dashboard time window and health-level counts	Customer health / Workspace health	Current health-level distribution for visible workspaces	none
System dashboard attention-needed workspace widget	Dashboard / Overview / compact list widget	Read-only attention registry	Open the most relevant existing system-safe detail surface for one unhealthy workspace	Named link per workspace row	forbidden	One explicit platform-safe next link per row	none	/system	existing linked system detail surfaces only	Workspace label, dominant dimensions, and selected time window	Attention-needed workspaces / Workspace	Which workspace needs review next and why	Compact dashboard widget justified because the list is triage-only, not a new registry page

Operator Surface Contract (mandatory when operator-facing surfaces are changed)

Surface	Primary Persona	Decision / Operator Action Supported	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
System dashboard customer-health KPI widget	Platform operator	Decide whether customer or workspace health is deteriorating overall	Dashboard summary	How many workspaces are healthy, unknown, warning, or critical right now?	Level counts, selected time window, and clear empty or unknown handling	Raw contributing rows, provider-specific details, and per-tenant evidence stay out of the widget	overall health level only	none	existing dashboard time-window selection only	none
System dashboard attention-needed workspace widget	Platform operator	Decide which workspace to inspect next and what kind of issue is driving it	Compact attention list	Which workspace needs attention first, and what is the dominant reason?	Workspace label, overall level, top one or two non-ok dimensions, and one system-safe next link	Full source record sets, provider codes, detailed finding counts, and review-pack internals remain in linked surfaces	overall level plus dominant health dimensions	none	open linked system-safe detail surface	none
System tenant and workspace residual detail pages customer-health decision card	Platform operator	Decide what to review first on the current detail page	Read-only follow-up summary	Why is this workspace unhealthy or unknown, and what should I inspect next?	Overall health, repeated top drivers, operator impact, recommended next action, and preserved selected-window context for windowed dimensions	Lower-level connectivity, permission, tenant, and recent-run evidence remains in the existing sections below	overall level plus dominant health dimensions	none	open existing linked follow-up surfaces only when already present on the page	none

UI Action Matrix (mandatory when Filament is changed)

Surface	Location	Header Actions	Inspect Affordance (List/Table)	Row Actions (max 2 visible)	Bulk Actions (grouped)	Empty-State CTA(s)	View Header Actions	Create/Edit Save+Cancel	Audit log?	Notes / Exemptions
System dashboard page	App\Filament\System\Pages\Dashboard	Existing Time window header action only; no new header actions	n/a	n/a	none	n/a	n/a	n/a	no	Action Surface Contract remains satisfied because the feature adds read-only widgets only and does not alter the page-level mutation model
Attention-needed workspace widget	App\Filament\System\Widgets\CustomerHealthTopWorkspaces	none	One named platform-safe next link per row; row click remains forbidden	Max one visible next link, chosen as Review health details or Open runs based on the dominant reason	none	One explanatory empty state with no CTA when no workspace needs attention	n/a	n/a	no	Every row must still expose one platform-safe next link. If no more specific route fits, the row falls back to the existing system tenant-detail context rather than inventing a new surface or showing no link

List-surface standard reference: The attention-needed workspace widget is a compact list surface and MUST be reviewed against /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/standards/list-surface-review-checklist.md before implementation sign-off. Accepted v1 exceptions are limited to compact dashboard-widget constraints: no persistence trio, no bulk actions, no row click, and no empty-state CTA because this surface is triage-only rather than a standalone registry page.

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no
• New persisted entity/table/artifact?: no
• New abstraction?: yes
• New enum/state/reason family?: no - the slice reuses existing SystemHealth levels
• New cross-domain UI framework/taxonomy?: no
• Current operator problem: the platform has no single explainable workspace-health summary even though the underlying truth already exists in onboarding, provider, operations, findings, review packs, and telemetry.
• Existing structure is insufficient because: the existing structures each explain one domain only. None can honestly answer which workspace is unhealthy overall without duplicating cross-domain query logic or forcing manual reconstruction.
• Narrowest correct implementation: add one bounded derived-query path and one small fixed dimension catalog, then surface it on the existing system dashboard only.
• Ownership cost: one support namespace, two dashboard widgets, fixed dimension rules, and focused unit plus feature coverage.
• Alternative intentionally rejected: a persisted score table, a customer-success page, a background recomputation pipeline, or an opaque weighted scoring engine.
• Release truth: current-release truth

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec.

Canonical replacement is preferred over preservation.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Unit, Feature
• Validation lane(s): fast-feedback, confidence
• Why this classification and these lanes are sufficient: Unit tests can prove health-level derivation, dimension precedence, unknown handling, and signal inclusion rules. Feature tests can prove dashboard rendering, platform-plane authorization, and system-safe link behavior without browser automation.
• New or expanded test families: One focused CustomerHealth unit family plus a small set of /system feature tests for summary widgets, explainability, and authorization.
• Fixture / helper cost impact: Moderate. Reuse existing workspaces, tenants, provider connections, onboarding sessions, product-usage events, operation runs, findings, and review packs. Avoid new browser helpers, seeded dashboards, or heavy system defaults.
• Heavy-family visibility / justification: none
• Special surface test profile: standard-native-filament
• Standard-native relief or required special coverage: standard native Filament feature coverage is sufficient because the slice adds read-only widgets only.
• Reviewer handoff: Reviewers must confirm that the health summary is derived-only, that unknown and stale data are not silently treated as healthy, that system-safe links remain on the platform plane, that no new persistence appears, and that the selected window affects only the intended windowed dimensions.
• Budget / baseline / trend impact: Low-to-moderate increase in narrow unit plus feature coverage only.
• Escalation needed: none
• Active feature PR close-out entry: Guardrail
• Test-governance outcome: keep
• Planned validation commands:
  • 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
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/System/CustomerHealth/CustomerHealthDashboardWidgetsTest.php tests/Feature/System/CustomerHealth/CustomerHealthExplainabilityTest.php tests/Feature/System/CustomerHealth/CustomerHealthAuthorizationTest.php

Functional Requirements

• FR-001: The system MUST derive one workspace-health summary from exactly six first-slice dimensions: onboarding readiness, provider connection health, operational stability, governance pressure, review-pack readiness, and engagement freshness.
• FR-002: The system MUST compute the overall workspace health level from existing SystemHealth semantics with explicit precedence: critical outranks warn, warn outranks unknown, and unknown outranks ok.
• FR-003: The system MUST keep the first slice derived-only. No persisted score table, asynchronous recomputation store, or secondary health ledger may be introduced.
• FR-004: The existing /system dashboard MUST show aggregate health counts and an attention-needed workspace list using the existing dashboard window selector for windowed dimensions.
• FR-005: The system MUST keep platform-safe navigation boundaries. Health widgets may link only to existing platform-plane system surfaces, never directly to tenant-admin /admin routes.
• FR-006: The system MUST make stale or missing source truth explicit. Missing or stale inputs must not silently produce ok.
• FR-007: Review-pack readiness in the first slice MUST stay narrow: it may reflect recent review-pack requests and the latest relevant pack status, but it must not become a quarterly review-obligation engine.
• FR-008: The slice MUST not introduce any new customer-facing communication, entitlement, billing, or AI workflow.

Non-Functional Requirements

• NFR-001: The summary query must stay bounded and reusable from the existing system dashboard without new background jobs or remote calls.
• NFR-002: Widget copy must remain calm, explainable, and dashboard-first rather than CRM-like, sales-like, or predictive.
• NFR-003: Health-level rendering must reuse existing badge or status semantics instead of inventing a second color or severity language.

UX Requirements

• UX-001: The dashboard must remain triage-first. Summary counts and dominant reasons are visible by default; raw counts and low-level diagnostics stay behind existing linked surfaces.
• UX-002: The slice must not become a new workbench page. /system remains the only first-slice entry point, and any health follow-up must stay inside existing residual detail pages rather than creating a new health detail page.
• UX-003: The widget and the linked residual detail decision card must distinguish point-in-time dimensions from windowed dimensions in their copy or presentation so operators do not assume one false time basis.

RBAC / Security Requirements

• SEC-001: Only existing platform users who can already access /system may see customer-health widgets.
• SEC-002: No tenant/admin-plane, customer-facing, or raw-row viewer may be introduced in this slice.
• SEC-003: System-safe deep links must remain guarded by existing platform-plane route policies and must not reveal tenant-admin paths or scoped data to the wrong plane.

Auditability / Observability Requirements

• OBS-001: The slice must reuse existing product truths and must not duplicate audit entries or OperationRun records for derived reads.
• OBS-002: The source dimension set and level precedence must be testable so future changes cannot silently redefine health semantics.

Data / Truth-Source Requirements

• DATA-001: Onboarding readiness must reuse existing onboarding-session and readiness truth rather than a copied health field.
• DATA-002: Provider connection health must reuse provider-owned verification and consent truth rather than a new platform-owned provider score.
• DATA-003: Operational stability must reuse existing failed and stuck OperationRun truth within the selected SystemConsoleWindow.
• DATA-004: Governance pressure must reuse existing findings and risk-acceptance truth.
• DATA-005: Review-pack readiness must reuse existing review-pack truth plus recent request context where needed.
• DATA-006: Engagement freshness must reuse existing product_usage_events truth rather than page views or ad-hoc counters.
• DATA-007: Archived workspaces must be excluded from active portfolio counts, and archived tenants must not contribute source truth into active workspace-health derivation.

Review-Pack Readiness Rule

Recent means the currently selected dashboard window. Request context is derived from existing review-pack request telemetry when available, falling back to a ReviewPack created for the same workspace inside that same window.

Condition	Review-pack readiness level	Notes
No request context and no relevant pack activity in the selected window	unknown	The first slice does not infer quarterly review obligations from silence
Request context exists in the selected window and no relevant pack is usable yet	warn	Covers queued, running, or not-yet-materialized pack generation
Latest relevant pack in the selected window is ready and not expired	ok	A usable recent pack exists
Latest relevant pack in the selected window is failed or expired	critical	Recent review-pack work ended unusably and needs attention

Attention Ordering Rule

The attention-needed workspace list is deterministic in v1:

1. Higher overall health severity sorts first: critical before warn before unknown
2. Within the same overall level, workspaces with more non-ok dimensions sort first
3. Remaining ties sort by workspace name ascending, then workspace id ascending

User Scenarios & Testing (mandatory)

User Story 1 - See Portfolio Health At A Glance (Priority: P1)

As a platform operator, I need the existing /system dashboard to summarize customer or workspace health so I can tell quickly whether attention pressure is rising.

Why this priority: Without an aggregate signal, operators still need to inspect several unrelated surfaces before they even know whether a health problem exists.

Independent Test: Seed workspaces with different combinations of healthy, warning, critical, and unknown source truth and verify that /system renders the correct health-level counts, explicit unknown handling, and a visible cue for windowed versus point-in-time dimensions.

Acceptance Scenarios:

1. Given multiple visible workspaces with mixed source truth, When an authorized platform user opens /system, Then the dashboard shows aggregate counts for ok, warn, critical, and unknown workspaces using the first-slice health rules.
2. Given a workspace has only stale or missing source truth for one or more dimensions, When the dashboard renders, Then that workspace is not shown as healthy by default.
3. Given the summary mixes operational and point-in-time signals, When the dashboard renders, Then the widget shows a visible cue that operations and engagement honor the selected window while onboarding, provider, governance, and review-readiness remain state-based.

---

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

As a platform operator, I need a compact list of the workspaces that need attention most so I know where to inspect next and why.

Why this priority: Aggregate counts alone do not reduce support load unless operators can immediately identify which workspace needs review and what category of issue is driving that state.

Independent Test: Seed multiple unhealthy workspaces and confirm the dashboard lists them with overall health level, dominant dimensions, and one platform-safe next link per row.

Acceptance Scenarios:

1. Given multiple warning or critical workspaces, When the dashboard renders, Then the attention-needed widget lists the worst workspaces first with overall level and dominant health dimensions.
2. Given a workspace row offers a next action, When the user activates that action, Then the link stays on an existing platform-plane system surface and does not deep-link into /admin tenant routes.
3. Given the operator follows a health-detail link from the dashboard, When the linked system tenant or workspace detail page renders, Then a decision-first customer-health card appears above the existing diagnostics and repeats the same dominant health drivers together with overall level, impact, and recommended next action.

---

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

As the product owner, I need the health summary to stay explainable and bounded so it does not become an opaque score, a hidden persistence layer, or a substitute for existing source truth.

Why this priority: A misleading or overbuilt score would add maintenance and trust debt immediately.

Independent Test: Inspect the derived summary rules and verify that unknown or mixed-time-basis inputs remain explicit, no new persistence appears, and no customer-facing workflow is introduced.

Acceptance Scenarios:

1. Given the first-slice dimension rules are evaluated, When one dimension is critical and another is unknown, Then the overall workspace level resolves deterministically and the dominant reasons remain explainable.
2. Given recent review-pack generation was requested but no usable pack is yet available, When the review-readiness dimension is evaluated, Then the workspace is not falsely shown as healthy.
3. Given a user without existing /system access attempts to read customer health, When they hit the surface, Then access stays denied through the existing platform-plane gate.

Edge Cases

• Archived workspaces or tenants must not inflate active health counts.
• A workspace can have healthy current provider state but no recent engagement telemetry; the slice must make the time basis explicit instead of collapsing that into a misleading single timestamp.
• A recent review-pack request can exist before a ready pack exists; that gap must not render as healthy.
• A workspace with no onboarding-linked tenant yet must remain unknown or explicitly non-healthy rather than silently ok.
• Mixed workspace truth across several tenants must still produce one explainable workspace-level result without exposing raw tenant-owned rows on the dashboard.

Acceptance Criteria

• The first slice derives workspace health from six fixed dimensions only and keeps all health truth derived from existing records.
• The existing /system dashboard exposes both aggregate health counts and an attention-needed workspace list.
• Operators can see dominant reasons for unhealthy workspaces without opening a second system page first.
• Unknown or stale source truth is explicit and never silently treated as healthy.
• The slice introduces no new persisted health entity, no customer-facing view, and no new platform-to-admin deep link.

Out Of Scope

• Customer-facing health portals
• Billing or entitlement-aware health dimensions
• Automated customer lifecycle messaging
• Predictive scoring, churn scoring, or AI-generated recommendations
• A dedicated portfolio-health page outside the existing /system dashboard
• A new persisted workspace-health model or scheduled recomputation job

Success Criteria

• A platform operator can identify whether any workspace needs attention, and which workspace to inspect first, within one /system dashboard visit.
• The first slice remains explainable enough that each visible non-healthy state can be tied back to one or two named dimensions.
• The package stays implementation-ready without introducing unresolved product decisions around billing, CRM, AI, or customer-facing UX.

Assumptions

• Product Usage & Adoption Telemetry is available or implemented before this slice is delivered.
• Existing system dashboard access rules remain the correct audience gate for the first slice.
• Existing provider-connection, finding, review-pack, and run surfaces remain the source-of-truth owners for detailed inspection.

Risks

• Too many first-slice dimensions would make the dashboard noisy; the dimension inventory is fixed at six for v1.
• Mixed point-in-time and windowed signals can confuse operators if the UI does not label them carefully.
• Review-pack readiness could drift into a broader compliance-workflow interpretation if it is not kept narrow.

Open Questions

• None blocking the first slice. The v1 contract guarantees one platform-safe next link per workspace row by falling back to the existing system tenant-detail context when a more specific platform-plane route is not appropriate.

Requirements (mandatory)

Constitution alignment (required): The slice adds no Microsoft Graph calls, no mutation flow, and no new queued or scheduled work. It derives read-only health summaries from existing onboarding, provider, telemetry, findings, review-pack, and OperationRun truth only.

Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001): The feature introduces no new persistence and reuses existing health-level semantics. The only new structure is one bounded derived-query path plus a fixed dimension catalog because current-release operator workflow now needs a single explainable workspace-health summary.

Constitution alignment (XCUT-001): This slice explicitly extends the shared system dashboard widget family, system-safe links, and shared SystemHealth presentation instead of inventing a second health dashboard language.

Constitution alignment (PROV-001): Provider-specific verification and consent semantics remain provider-owned inputs only; the top-level customer-health summary stays platform-owned and neutral.

Constitution alignment (TEST-GOV-001): Proof stays in Unit + Feature lanes only. No heavy-governance or browser family is justified.

Constitution alignment (OPS-UX): Existing OperationRun start, completion, notification, and link semantics remain unchanged. The slice reads existing run truth and may link to existing system operations surfaces only.

Constitution alignment (RBAC-UX): Reads remain platform-plane only through existing /system access checks. No tenant/admin or customer-facing health viewer is introduced.

Constitution alignment (BADGE-001): The feature reuses existing BadgeDomain::SystemHealth rendering and does not add a new badge taxonomy.

Constitution alignment (UI-FIL-001): The only operator-facing changes are native Filament system widgets on the existing dashboard. No published views, panel provider changes, or custom asset pipeline changes are introduced.

Constitution alignment (UI-NAMING-001): Widget labels and dominant health reasons must remain operator-first and platform-neutral, such as Customer health, Attention-needed workspaces, Provider health, Operational stability, and Engagement freshness.

Filament v5 / Livewire v4 compliance: The slice remains fully inside the current Filament v5 + Livewire v4 stack.

Provider registration location: No provider registration changes are introduced; Laravel 11+ provider registration remains in bootstrap/providers.php.

Global search rule: No new resource or global-search participation is introduced.

Destructive actions: No destructive actions are added in this slice.

Asset strategy: No new global or on-demand assets are added. Deployment behavior for filament:assets remains unchanged.