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

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

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

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

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

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

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

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

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.