TenantAtlas/specs/175-workspace-governance-attention/quickstart.md

# Quickstart: Workspace Governance Attention Foundation

## Goal

Validate that `/admin` no longer appears calm when visible tenants carry governance-critical conditions, that workspace summary metrics distinguish risk from activity, and that workspace attention items identify the correct tenant and open the correct next surface.

## Prerequisites

1. Start Sail.
2. Ensure you have one workspace with multiple visible tenants and current workspace session context.
3. Prepare seeded tenant scenarios for:
   - no governance-critical conditions and no unusual activity
   - overdue findings with otherwise quiet operations
   - lapsed governance
   - expiring governance
   - high-severity active findings
   - stale, failed, or materially degraded compare posture
   - activity-only workspace noise with otherwise healthy governance posture
   - optional existing evidence or review attention if those truth surfaces are already available
4. Prepare one workspace member who can see the workspace home but lacks at least one downstream tenant destination capability so disabled or fallback attention behavior can be verified.
5. Prepare one workspace member who belongs to the workspace but has zero accessible tenants so the choose-workspace recovery path can be verified.

## Implementation Validation Order

### 1. Run the existing workspace overview baseline pack

```bash
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewAccessTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewAuthorizationTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewLandingTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewNavigationTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewContentTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewPermissionVisibilityTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewOperationsTest.php
```

Expected outcome:
- The existing workspace home still renders, remains workspace-scoped, and preserves current access and operations behavior.

### 2. Run focused governance-attention coverage

```bash
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewGovernanceAttentionTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewSummaryMetricsTest.php
```

Expected outcome:
- Visible tenants with overdue findings, lapsed governance, expiring governance, high-severity active findings, or stale, failed, or materially degraded compare posture now promote governance attention into the workspace home.
- Governance-risk metrics count affected tenants and remain distinct from operations or alerts volume.

### 3. Run drill-through continuity and RBAC-safe navigation coverage

```bash
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewDrilldownContinuityTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewPermissionVisibilityTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewAuthorizationTest.php
```

Expected outcome:
- Workspace attention items carry tenant context and open the correct findings, compare, evidence, review, tenant dashboard, or operations destination.
- Members missing a downstream capability do not receive clickable dead-end links.

### 4. Re-run workspace empty-state and calmness coverage

```bash
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewGovernanceAttentionTest.php --filter=calm
```

Expected outcome:
- The workspace no longer renders a calm or “nothing urgent” state when visible governance-critical tenant conditions exist.
- Zero-tenant and low-permission states remain clearly distinct from healthy calmness, zero-tenant recovery defaults to `Switch workspace`, and permission-limited recovery defaults to `Open operations` unless a more specific allowed action exists.

### 5. Format touched files

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

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

### 6. Run the final focused verification pack

```bash
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewAccessTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewAuthorizationTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewLandingTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewNavigationTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewContentTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewPermissionVisibilityTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewOperationsTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewDbOnlyTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewGovernanceAttentionTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewSummaryMetricsTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewDrilldownContinuityTest.php
```

Expected outcome:
- The formatted implementation preserves landing, authorization, content, empty-state, operations, governance-attention, stat-separation, and drill-through contracts for the workspace home.

## Manual Smoke Check

1. Open `/admin` for a workspace where one visible tenant has overdue findings but operations are quiet.
2. Confirm the workspace home does not read as calm and identifies the tenant explicitly.
3. Open `/admin` for a workspace where a visible tenant has lapsed governance or stale, failed, or materially degraded compare posture and confirm that tenant is prioritized above activity-only items.
4. Click a governance attention item and confirm the destination reproduces the same tenant problem family.
5. Verify that the summary strip clearly distinguishes tenant risk from active operations.
6. Switch to a healthy workspace and confirm calm wording only appears when both governance and activity domains are truly calm within visible scope.
7. Sign in as the zero-tenant workspace member and confirm the workspace does not look healthy and instead offers `Switch workspace` as the next action.
8. Sign in as the permission-limited workspace member and confirm visible attention does not expose a clickable dead-end link and the page still presents `Open operations` as the valid workspace-safe next action.

## Non-Goals For This Slice

- No database migration.
- No new Graph contract or provider workflow.
- No full portfolio matrix or posture score.
- No new workspace evidence or review aggregate.
- No conversion of recent operations into a primary governance queue.