TenantAtlas/specs/179-provider-truth-cleanup/quickstart.md

# Quickstart: Provider Readiness Source-of-Truth Cleanup

## Goal

Validate that tenant and provider operator surfaces no longer elevate `Tenant.app_status`, `ProviderConnection.status`, or `ProviderConnection.health_status` as leading truth, and that lifecycle, consent, and verification now answer the primary operator questions.

## Prerequisites

1. Start Sail.
2. Prepare one workspace member with at least one visible tenant and provider connection management access.
3. Seed or create tenant scenarios for:
   - active tenant with `app_status` populated but provider verification `unknown`
   - onboarding tenant with granted consent and blocked verification
   - tenant with no default Microsoft provider connection
4. Seed or create provider connection scenarios for:
   - consent `granted`, verification `degraded`, legacy `status=connected`, legacy `health_status=ok`
   - consent `required` or `revoked`, verification `blocked`, legacy `status` still optimistic
   - configured connection that has never been verified
   - disabled connection with retained legacy status or health values
5. Prepare one non-member or cross-workspace actor for deny-as-not-found checks.

## Implementation Validation Order

### 1. Run the current baseline tenant and provider surface tests

```bash
vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantLifecycleStatusDomainSeparationTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/ProviderConnectionsDbOnlyTest.php
vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/RequiredFiltersTest.php
vendor/bin/sail artisan test --compact tests/Feature/Tenants/TenantProviderConnectionsCtaTest.php
```

Expected outcome:
- Existing tenant detail, provider connection pages, canonical tenantless provider route, and provider CTA behavior still render correctly before the cleanup changes are applied.

### 2. Run focused tenant truth-cleanup coverage

```bash
vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantLifecycleStatusDomainSeparationTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantTruthCleanupSpec179Test.php
```

Expected outcome:
- Tenant list no longer shows `app_status` as default-visible truth.
- Tenant detail keeps lifecycle separate from provider consent and verification.
- Tenant detail Provider section stops leading with legacy `status` and `health_status`.

### 3. Run focused provider truth-cleanup coverage

```bash
vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionTruthCleanupSpec179Test.php
vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/RequiredFiltersTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/ProviderConnectionsDbOnlyTest.php
```

Expected outcome:
- Provider connection list promotes consent and verification to the default-visible columns.
- Provider connection view and edit pages show current state separately from diagnostics.
- Legacy `status` and `health_status` remain secondary or hidden by default.

### 4. Re-run authorization and discovery-safety coverage on touched resources

```bash
vendor/bin/sail artisan test --compact tests/Feature/Rbac/TenantResourceAuthorizationTest.php
vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionListAuthorizationTest.php
vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionAuthorizationTest.php
vendor/bin/sail artisan test --compact tests/Feature/Rbac/AdminGlobalSearchContextSafetyTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantGlobalSearchLifecycleScopeTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantScopingTest.php
```

Expected outcome:
- Workspace and tenant scoping remain unchanged.
- Non-members still receive deny-as-not-found behavior.
- Members without capability do not gain new visibility or mutation access.
- Tenant global search remains workspace-safe.
- Provider connections remain excluded from global search.

### 5. Run badge-mapping coverage

```bash
vendor/bin/sail artisan test --compact tests/Unit/Badges/TenantBadgesTest.php
vendor/bin/sail artisan test --compact tests/Unit/Badges/ProviderConnectionBadgesTest.php
```

Expected outcome:
- Lifecycle, provider consent, provider verification, and retained legacy diagnostic badges resolve through centralized badge mappings only.

### 6. Format touched files

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

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

### 7. Run the final focused verification pack

```bash
vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantLifecycleStatusDomainSeparationTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantTruthCleanupSpec179Test.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/ProviderConnectionsDbOnlyTest.php
vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionTruthCleanupSpec179Test.php
vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/RequiredFiltersTest.php
vendor/bin/sail artisan test --compact tests/Feature/Tenants/TenantProviderConnectionsCtaTest.php
vendor/bin/sail artisan test --compact tests/Feature/Rbac/TenantResourceAuthorizationTest.php
vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionListAuthorizationTest.php
vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionAuthorizationTest.php
vendor/bin/sail artisan test --compact tests/Feature/Rbac/AdminGlobalSearchContextSafetyTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantGlobalSearchLifecycleScopeTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantScopingTest.php
vendor/bin/sail artisan test --compact tests/Unit/Badges/TenantBadgesTest.php
vendor/bin/sail artisan test --compact tests/Unit/Badges/ProviderConnectionBadgesTest.php
```

Expected outcome:
- The targeted tenant and provider surfaces keep truthful status hierarchy, keep DB-only rendering where already promised, and preserve existing authorization boundaries.

### 8. Validate no migration and no new persisted truth were introduced

```bash
git diff --name-only -- database/migrations app/Models app/Support/Providers app/Support/Badges/BadgeDomain.php app/Support/Badges/BadgeCatalog.php app/Support/Badges/Domains/ProviderConsentStatusBadge.php app/Support/Badges/Domains/ProviderVerificationStatusBadge.php app/Support/Badges/Domains/TenantAppStatusBadge.php app/Support/Badges/Domains/ProviderConnectionStatusBadge.php app/Support/Badges/Domains/ProviderConnectionHealthBadge.php specs/179-provider-truth-cleanup
```

Expected outcome:
- No new migration file is introduced for this feature.
- No new persisted readiness artifact or new provider-status family appears outside the approved centralized badge mapping work.
- Central badge changes are limited to the approved consent, verification, and retained diagnostic badge mappers.

## Manual Smoke Check

1. Open `/admin/tenants` and confirm lifecycle remains visible while `app_status` is no longer a default-visible status badge.
2. Open one tenant detail page and confirm the `Provider` section now leads with consent and verification, not connection `status` and `health`.
3. Confirm the `Verification report` widget still provides the deeper stored verification surface and does not depend on outbound HTTP at render time.
4. Open `/admin/provider-connections` and confirm consent and verification are the primary default-visible state columns.
5. Confirm any retained legacy `status` or `health` values are secondary diagnostics rather than peer badges.
6. Open a provider connection view page and confirm `configured`, `connected`, or `consented` no longer read as equivalent to verified or ready.
7. Open a provider connection edit page and confirm current consent and verification context are visible before any mutation, while diagnostics remain secondary.
8. Repeat one tenant and one provider URL as a non-member or out-of-scope actor and confirm deny-as-not-found behavior still holds.

## Non-Goals For This Slice

- No database migration.
- No new readiness enum, score, or persisted summary.
- No change to verification queueing, `OperationRun` semantics, or provider mutation workflows.
- No removal of legacy database fields or projection writers.