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

Tasks: Provider Readiness Source-of-Truth Cleanup

Input: Design documents from /specs/179-provider-truth-cleanup/ Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/provider-truth-cleanup.openapi.yaml, quickstart.md

Tests: Required. Write or update Pest coverage before each behavior change and keep Sail-first verification focused.

Organization: Tasks are grouped by user story so each story can be implemented and validated independently.

Phase 1: Setup (Shared Regression Scaffolding)

Purpose: Create the focused regression entry points for Spec 179 before changing operator-facing surfaces.

• T001 [P] Create the tenant truth-cleanup Pest scaffold in tests/Feature/Filament/TenantTruthCleanupSpec179Test.php
• T002 [P] Create the provider truth-cleanup Pest scaffold in tests/Feature/ProviderConnections/ProviderConnectionTruthCleanupSpec179Test.php

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Lock route, scope, and discovery invariants before changing any tenant or provider truth surfaces.

⚠️ CRITICAL: No user story work should begin until this phase is complete.

• T003 Preserve canonical provider CTA and deny-as-not-found invariants in tests/Feature/Tenants/TenantProviderConnectionsCtaTest.php, tests/Feature/Rbac/TenantResourceAuthorizationTest.php, tests/Feature/ProviderConnections/ProviderConnectionListAuthorizationTest.php, and tests/Feature/ProviderConnections/ProviderConnectionAuthorizationTest.php
• T004 [P] Preserve tenant global-search scope and provider-connection global-search exclusion in tests/Feature/Rbac/AdminGlobalSearchContextSafetyTest.php, tests/Feature/Filament/TenantGlobalSearchLifecycleScopeTest.php, and tests/Feature/Filament/TenantScopingTest.php

Checkpoint: Scope guards and discovery invariants are ready; tenant and provider truth cleanup can now proceed.

---

Phase 3: User Story 1 - Read truthful tenant surfaces (Priority: P1) 🎯 MVP

Goal: Make tenant list and tenant detail lifecycle-led, remove app_status as leading truth, and show provider consent and verification separately from lifecycle.

Independent Test: Seed tenants whose lifecycle, legacy app_status, consent, and verification disagree, then verify tenant list and tenant detail show lifecycle separately and no longer treat app_status as current truth.

Tests for User Story 1

• T005 [P] [US1] Add tenant list truth regression cases in tests/Feature/Filament/TenantTruthCleanupSpec179Test.php for active-plus-unknown, onboarding-plus-blocked, missing-default-connection, and multi-connection unsafe-summary omission scenarios
• T006 [P] [US1] Rewrite lifecycle-separation expectations in tests/Feature/Filament/TenantLifecycleStatusDomainSeparationTest.php so lifecycle and RBAC remain visible while app_status stops acting as primary truth

Implementation for User Story 1

• T007 [US1] Remove default-visible app_status columns and primary app_status filter usage from app/Filament/Resources/TenantResource.php, and keep any tenant-list provider signal omitted when current provider truth cannot be compressed safely
• T008 [US1] Remove leading app_status detail output and repoint providerConnectionState() to consent_status and verification_status in app/Filament/Resources/TenantResource.php
• T009 [US1] Rewrite the tenant Provider summary in resources/views/filament/infolists/entries/provider-connection-state.blade.php to lead with consent and verification and demote legacy status and health to diagnostics
• T010 [US1] Align verification deep-dive wording with the new tenant summary contract in app/Filament/Widgets/Tenant/TenantVerificationReport.php and resources/views/filament/widgets/tenant/tenant-verification-report.blade.php
• T011 [US1] Update canonical provider-connections CTA assertions after the tenant detail summary change in tests/Feature/Tenants/TenantProviderConnectionsCtaTest.php

Checkpoint: Tenant list and tenant detail now answer lifecycle and provider questions without implying readiness from legacy fields.

---

Phase 4: User Story 2 - Diagnose provider connections from current axes (Priority: P1)

Goal: Make provider connection list, view, and edit surfaces lead with consent and verification while demoting legacy connection status and health to diagnostics.

Independent Test: Seed provider connections whose legacy status and health_status conflict with consent_status and verification_status, then verify list, view, and edit surfaces elevate the current axes and keep DB-only rendering intact.

Tests for User Story 2

• T012 [P] [US2] Add provider list, view, and edit truth regression cases in tests/Feature/ProviderConnections/ProviderConnectionTruthCleanupSpec179Test.php for consent and verification versus legacy status and health conflicts
• T013 [P] [US2] Update provider filter expectations in tests/Feature/ProviderConnections/RequiredFiltersTest.php to require consent-led and verification-led filters plus default_only
• T014 [P] [US2] Update DB-only rendering expectations in tests/Feature/Filament/ProviderConnectionsDbOnlyTest.php for the new default-visible provider state columns

Implementation for User Story 2

• T015 [US2] Promote consent_status and verification_status to default-visible list columns and demote legacy status and health_status columns in app/Filament/Resources/ProviderConnectionResource.php
• T016 [US2] Replace primary status and health_status filters with consent-led and verification-led filters and mark any retained legacy filters as diagnostic in app/Filament/Resources/ProviderConnectionResource.php
• T017 [US2] Split the provider connection view infolist into Current state and Diagnostics sections in app/Filament/Resources/ProviderConnectionResource.php
• T018 [US2] Split the provider connection edit form context into Current state and Diagnostics sections in app/Filament/Resources/ProviderConnectionResource.php

Checkpoint: Provider connection pages now answer whether a connection is consented and verified before showing any legacy projections.

---

Phase 5: User Story 3 - Avoid false readiness language across surfaces (Priority: P2)

Goal: Keep tenant and provider surfaces from collapsing active, connected, or consented into ready, and keep RBAC separate from provider truth.

Independent Test: Render tenant and provider surfaces for records that look favorable in one status family but unfavorable in another and verify no default-visible wording, badge, or section title implies readiness.

Tests for User Story 3

• T019 [P] [US3] Add cross-surface false-readiness assertions in tests/Feature/Filament/TenantTruthCleanupSpec179Test.php and tests/Feature/ProviderConnections/ProviderConnectionTruthCleanupSpec179Test.php for active-plus-blocked or error, consented-plus-unknown, and RBAC-separated scenarios
• T020 [P] [US3] Re-run scope-leak and capability regression coverage in tests/Feature/Rbac/TenantResourceAuthorizationTest.php, tests/Feature/ProviderConnections/ProviderConnectionListAuthorizationTest.php, and tests/Feature/ProviderConnections/ProviderConnectionAuthorizationTest.php against the cleaned surfaces

Implementation for User Story 3

• T021 [US3] Normalize operator-facing labels and section headings to Lifecycle, Consent, Verification, and Diagnostics wording in app/Filament/Resources/TenantResource.php and app/Filament/Resources/ProviderConnectionResource.php
• T022 [US3] Add centralized badge mappings for provider consent and provider verification, keep legacy app-status or connection-status badges diagnostic-only, and avoid any synthetic readiness domain in app/Support/Badges/BadgeCatalog.php, app/Support/Badges/BadgeDomain.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, and app/Support/Badges/Domains/ProviderConnectionHealthBadge.php
• T023 [US3] Update unit badge regression coverage for centralized lifecycle, provider consent, provider verification, and legacy diagnostic mappings in tests/Unit/Badges/TenantBadgesTest.php and tests/Unit/Badges/ProviderConnectionBadgesTest.php

Checkpoint: No targeted tenant or provider surface uses favorable legacy language to imply provider readiness.

---

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Format, verify, and manually confirm the cleaned truth hierarchy across all affected surfaces.

• T024 Run vendor/bin/sail bin pint --dirty --format agent for touched files under app/, resources/views/, and tests/ as governed by composer.json
• T025 Run the focused Sail verification pack from specs/179-provider-truth-cleanup/quickstart.md against tests/Feature/Filament/TenantLifecycleStatusDomainSeparationTest.php, tests/Feature/Filament/TenantTruthCleanupSpec179Test.php, tests/Feature/Filament/ProviderConnectionsDbOnlyTest.php, tests/Feature/ProviderConnections/ProviderConnectionTruthCleanupSpec179Test.php, tests/Feature/ProviderConnections/RequiredFiltersTest.php, tests/Feature/Tenants/TenantProviderConnectionsCtaTest.php, tests/Feature/Rbac/TenantResourceAuthorizationTest.php, tests/Feature/ProviderConnections/ProviderConnectionListAuthorizationTest.php, tests/Feature/ProviderConnections/ProviderConnectionAuthorizationTest.php, tests/Feature/Rbac/AdminGlobalSearchContextSafetyTest.php, tests/Feature/Filament/TenantGlobalSearchLifecycleScopeTest.php, tests/Feature/Filament/TenantScopingTest.php, tests/Unit/Badges/TenantBadgesTest.php, and tests/Unit/Badges/ProviderConnectionBadgesTest.php
• T026 Execute the manual smoke checklist in specs/179-provider-truth-cleanup/quickstart.md against app/Filament/Resources/TenantResource.php and app/Filament/Resources/ProviderConnectionResource.php on /admin/tenants and /admin/provider-connections
• T027 Validate that the final implementation introduces no schema migration, no new persisted truth, and no unplanned status-family expansion by reviewing database/migrations/, app/Models/Tenant.php, app/Models/ProviderConnection.php, app/Support/Providers/ProviderConsentStatus.php, app/Support/Providers/ProviderVerificationStatus.php, 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, and specs/179-provider-truth-cleanup/plan.md against the final diff

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): No dependencies; start immediately.
• Foundational (Phase 2): Depends on Setup completion; blocks all user story work.
• User Story 1 (Phase 3): Depends on Foundational completion.
• User Story 2 (Phase 4): Depends on Foundational completion.
• User Story 3 (Phase 5): Depends on User Story 1 and User Story 2 completion because it harmonizes cross-surface wording and diagnostic semantics.
• Polish (Phase 6): Depends on all desired user stories being complete.

User Story Dependencies

• US1: Independent after Phase 2 and is the recommended MVP slice.
• US2: Independent after Phase 2 and can run in parallel with US1.
• US3: Depends on the finished tenant and provider surface hierarchy from US1 and US2.

Within Each User Story

• Write or update the story tests first and confirm they fail for the intended reason.
• Update the primary resource or shared surface contract before adjusting dependent Blade or widget output.
• Finish story-specific assertions after the implementation lands.
• Keep authorization regressions green before advancing to the next story.

Parallel Opportunities

• T001 and T002 can run in parallel.
• T003 and T004 can run in parallel.
• T005 and T006 can run in parallel.
• T012, T013, and T014 can run in parallel.
• T019 and T020 can run in parallel.
• Phase 3 and Phase 4 can run in parallel after Phase 2 completes.

---

Parallel Example: User Story 1

# Launch the tenant truth regressions together before changing tenant surfaces:
Task: T005 Add tenant list truth regression cases in tests/Feature/Filament/TenantTruthCleanupSpec179Test.php
Task: T006 Rewrite lifecycle-separation expectations in tests/Feature/Filament/TenantLifecycleStatusDomainSeparationTest.php

Parallel Example: User Story 2

# Launch the provider list and rendering guards together before changing ProviderConnectionResource:
Task: T012 Add provider list, view, and edit truth regression cases in tests/Feature/ProviderConnections/ProviderConnectionTruthCleanupSpec179Test.php
Task: T013 Update provider filter expectations in tests/Feature/ProviderConnections/RequiredFiltersTest.php
Task: T014 Update DB-only rendering expectations in tests/Feature/Filament/ProviderConnectionsDbOnlyTest.php

Parallel Example: User Story 3

# Lock the cross-surface wording and scope guards together once US1 and US2 are complete:
Task: T019 Add cross-surface false-readiness assertions in tests/Feature/Filament/TenantTruthCleanupSpec179Test.php and tests/Feature/ProviderConnections/ProviderConnectionTruthCleanupSpec179Test.php
Task: T020 Re-run scope-leak and capability regression coverage in tests/Feature/Rbac/TenantResourceAuthorizationTest.php, tests/Feature/ProviderConnections/ProviderConnectionListAuthorizationTest.php, and tests/Feature/ProviderConnections/ProviderConnectionAuthorizationTest.php

---

Implementation Strategy

MVP First (User Story 1 Only)

1. Complete Phase 1: Setup.
2. Complete Phase 2: Foundational.
3. Complete Phase 3: User Story 1.
4. Validate tenant surfaces with the US1-focused subset of specs/179-provider-truth-cleanup/quickstart.md.
5. Demo or review the tenant truth cleanup before expanding to provider surfaces.

Incremental Delivery

1. Finish Setup and Foundational work.
2. Deliver US1 and validate tenant truth cleanup.
3. Deliver US2 and validate provider truth cleanup.
4. Deliver US3 and validate cross-surface wording and diagnostic consistency.
5. Finish Phase 6 verification and manual smoke checks.

Parallel Team Strategy

1. One developer completes Phase 1 and Phase 2.
2. After Phase 2, one developer takes US1 while another takes US2.
3. Rejoin on US3 once both surface hierarchies are stable.
4. Finish with shared formatting, focused Sail tests, and manual smoke validation.

---

Notes

• Every task follows the required checklist format: checkbox, task ID, optional parallel marker, required story label for story phases, and exact file paths.
• The task list preserves the plan decision not to invent a new tenant-list readiness badge in this slice.
• No task introduces new persistence, a new readiness enum, or a new presenter layer.