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

# Quickstart: Tenant Dashboard KPI & Attention Truth Alignment

## Goal

Validate that the tenant dashboard no longer appears calmer than the tenant's real governance, findings, compare, and operations state, and that KPI and attention drill-throughs lead to semantically matching destinations.

## Prerequisites

1. Start Sail.
2. Ensure you have a tenant with dashboard access and current workspace context.
3. Seed or create tenant scenarios for:
   - no attention-worthy conditions
   - overdue active findings with no new drift
   - lapsed accepted-risk governance
   - expiring governance
   - high-severity active findings
   - compare trust limitations or stale compare posture
   - healthy operations-only activity with otherwise healthy governance
   - failed, warning, or unusually long-running or stalled operations that require follow-up
4. Ensure the current user is entitled to the tenant dashboard, tenant findings list, Baseline Compare landing, and canonical Operations routes.
5. Prepare one in-scope tenant member who can open the dashboard but lacks at least one downstream destination capability so disabled or non-clickable affordances can be verified.

## Implementation Validation Order

### 1. Run existing compare and attention truth baselines

```bash
vendor/bin/sail artisan test --compact tests/Feature/Filament/NeedsAttentionWidgetTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareNowWidgetTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareSummaryConsistencyTest.php
```

Expected outcome:
- Existing aggregate-backed compare and governance truth remains stable.
- Compare posture still suppresses false calm for stale, unavailable, failed, and limited-confidence scenarios.

### 2. Run focused dashboard truth-alignment coverage

```bash
vendor/bin/sail artisan test --compact tests/Feature/Filament/DashboardKpisWidgetTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantDashboardTruthAlignmentTest.php
```

Expected outcome:
- KPI labels match their count universe.
- High-severity and active findings semantics are consistent or explicitly differentiated.
- The full tenant dashboard does not present an all-clear when overdue, lapsed, or expiring governance, compare-limited conditions, or attention-worthy operations follow-up exist.

### 3. Run destination continuity and tenant-scope coverage

```bash
vendor/bin/sail artisan test --compact tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php
vendor/bin/sail artisan test --compact tests/Feature/OpsUx/CanonicalViewRunLinksTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantDashboardTenantScopeTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantDashboardDbOnlyTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/TableStandardsBaselineTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/TableDetailVisibilityTest.php
```

Expected outcome:
- Canonical Operations links opened from the tenant dashboard preserve tenant context.
- Dashboard drill-throughs remain tenant-safe and DB-only at render time.
- Members who can see a dashboard state but lack the downstream capability get disabled or non-clickable explanatory affordances instead of clickable dead-end links.
- Recent table surfaces retain their diagnostic framing and detail-visibility rules in the final verification pack.

### 4. Run destination-side findings filter coverage

```bash
vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingsListDefaultsTest.php
vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingsListFiltersTest.php
vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingAdminTenantParityTest.php
```

Expected outcome:
- Findings destinations still honor the tabs and filters that dashboard drill-throughs depend on.
- Active, overdue, and high-severity continuity remains recognizable on the target list.

### 5. Format touched implementation files

```bash
vendor/bin/sail bin pint --dirty --format agent
```

Expected outcome:
- All changed implementation files conform to project formatting rules.

### 6. Re-run the final verification pack

```bash
vendor/bin/sail artisan test --compact tests/Feature/Filament/DashboardKpisWidgetTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantDashboardTruthAlignmentTest.php
vendor/bin/sail artisan test --compact tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/NeedsAttentionWidgetTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareNowWidgetTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareSummaryConsistencyTest.php
vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingsListDefaultsTest.php
vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingsListFiltersTest.php
vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingAdminTenantParityTest.php
vendor/bin/sail artisan test --compact tests/Feature/OpsUx/CanonicalViewRunLinksTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantDashboardTenantScopeTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantDashboardDbOnlyTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/TableStandardsBaselineTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/TableDetailVisibilityTest.php
```

Expected outcome:
- The formatted implementation still passes the same consolidated verification pack described in the tasks artifact.

## Manual Smoke Check

1. Start a 10-second timer and open `/admin/t/{tenant}` for seeded tenants representing overdue findings, expiring governance, compare limitations, healthy operations-only activity, and attention-worthy operations follow-up.
2. Within the 10-second scan, confirm an operator can tell whether the tenant has governance attention, compare caution, operations-only activity, attention-worthy operations follow-up, or no immediate action required.
3. For a tenant with overdue findings but no `new` drift findings, confirm the dashboard still reads as needing attention and does not fall back to calm or trustworthy wording.
4. Click the relevant KPI and confirm the findings destination shows the same subset or explicitly broader related framing.
5. Click a `Needs Attention` item for overdue findings, high-severity active findings, lapsed governance, expiring governance, compare posture, and operations follow-up and confirm each lands on the correct tenant-scoped working surface.
6. Open the operations KPI or operations attention path and confirm `/admin/operations` opens with tenant context preserved.
7. Sign in as the permission-limited in-scope member and confirm any visible dashboard state without downstream capability renders helper text with a disabled or non-clickable affordance instead of a clickable dead-end link.
8. Verify that `Recent Drift Findings` and `Recent Operations` still read as recent context rather than the page's primary queue.
9. Click one row in `Recent Drift Findings` and one row in `Recent Operations` and confirm each opens the expected canonical detail surface.
10. Switch to a tenant with healthy compare posture and no attention-worthy conditions and confirm calm or healthy signals return consistently.

## Non-Goals For This Slice

- No new database migration.
- No new Graph contract or provider workflow.
- No new tenant-posture hero component.
- No new dashboard route family.
- No conversion of recent tables into full action queues.