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.

- [X] T001 [P] Create the tenant truth-cleanup Pest scaffold in `tests/Feature/Filament/TenantTruthCleanupSpec179Test.php`
- [X] 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.

- [X] 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`
- [X] 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

- [X] 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
- [X] 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

- [X] 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
- [X] T008 [US1] Remove leading `app_status` detail output and repoint `providerConnectionState()` to `consent_status` and `verification_status` in `app/Filament/Resources/TenantResource.php`
- [X] 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
- [X] 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`
- [X] 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

- [X] 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
- [X] T013 [P] [US2] Update provider filter expectations in `tests/Feature/ProviderConnections/RequiredFiltersTest.php` to require consent-led and verification-led filters plus `default_only`
- [X] 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

- [X] 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`
- [X] 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`
- [X] T017 [US2] Split the provider connection view infolist into Current state and Diagnostics sections in `app/Filament/Resources/ProviderConnectionResource.php`
- [X] 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

- [X] 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
- [X] 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

- [X] 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`
- [X] 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`
- [X] 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.

- [X] T024 Run `vendor/bin/sail bin pint --dirty --format agent` for touched files under `app/`, `resources/views/`, and `tests/` as governed by `composer.json`
- [X] 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`
- [X] 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`
- [X] 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

```bash
# 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

```bash
# 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

```bash
# 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.