TenantAtlas/specs/146-central-tenant-status-presentation/tasks.md

Tasks: Central Tenant Status Presentation

Input: Design documents from /specs/146-central-tenant-status-presentation/ Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/

Tests: For runtime behavior changes in this repo, tests are REQUIRED (Pest). Only docs-only changes may omit tests. Operations: This feature does not introduce long-running, remote, queued, or scheduled work. No OperationRun creation or lifecycle changes are required. RBAC: This feature does not change authorization behavior. Existing tenant/workspace and canonical-view access checks remain unchanged; tests here focus on presentation consistency after authorization has already succeeded. UI Naming: Lifecycle copy must stay canonical as Draft, Onboarding, Active, and Archived across badges, helper text, and referenced-tenant context copy. Filament UI Action Surfaces: This feature changes presentation only. No header, row, bulk, empty-state CTA, or destructive action behavior is added or changed. Filament UI UX-001 (Layout & IA): Existing layouts remain intact. Tasks below only change lifecycle presentation within current table, infolist, summary, banner, selector, and tenantless-operations-viewer structures. Badges: Tenant lifecycle badge changes MUST continue to use BadgeCatalog / BadgeRenderer and MUST NOT introduce ad-hoc Filament mappings.

Organization: Tasks are grouped by user story to enable independent implementation and testing of each story.

Format: [ID] [P?] [Story] Description

• [P]: Can run in parallel (different files, no dependencies)
• [Story]: Which user story this task belongs to (e.g., US1, US2, US3)
• Include exact file paths in descriptions

Phase 1: Setup (Shared Infrastructure)

Purpose: Prepare the shared test targets and implementation files for lifecycle presentation work.

• T001 [P] Create the central lifecycle presentation unit test file in tests/Unit/Support/Tenants/TenantLifecyclePresentationTest.php
• T002 [P] Create the tenant surface lifecycle regression test file in tests/Feature/Filament/TenantLifecyclePresentationAcrossTenantSurfacesTest.php
• T003 [P] Create the canonical viewer lifecycle regression test file in tests/Feature/Filament/ReferencedTenantLifecyclePresentationTest.php

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Build the shared lifecycle presentation contract and exhaustive badge integration before any story-specific surface work starts.

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

• T004 Implement the central lifecycle presentation contract in app/Support/Tenants/TenantLifecyclePresentation.php
• T005 [P] Implement the referenced-tenant lifecycle presentation adapter in app/Support/Tenants/ReferencedTenantLifecyclePresentation.php
• T006 Update tenant lifecycle normalization to route canonical and invalid-state handling through the shared contract in app/Support/Badges/BadgeCatalog.php
• T007 Update the tenant lifecycle badge mapper to consume the shared presentation contract in app/Support/Badges/Domains/TenantStatusBadge.php
• T008 Audit and remove scattered valid-lifecycle mappings across app/Filament/Resources/TenantResource.php, app/Filament/Pages/ChooseTenant.php, app/Filament/Pages/Operations/TenantlessOperationRunViewer.php, resources/views/filament/pages/choose-tenant.blade.php, and resources/views/filament/widgets/tenant/tenant-archived-banner.blade.php
• T009 Add exhaustive unit coverage for canonical lifecycle values and invalid fallback for non-canonical data in tests/Unit/Support/Tenants/TenantLifecyclePresentationTest.php

Checkpoint: Foundation ready - tenant lifecycle presentation can now be rolled out across surfaces in parallel.

---

Phase 3: User Story 1 - Read Trusted Lifecycle Badges Everywhere (Priority: P1) 🎯 MVP

Goal: Make tenant lifecycle render with the same canonical labels and meaning across tenant index, tenant detail summary areas, archived banner surfaces, choose-tenant, and onboarding-linked tenant surfaces.

Independent Test: Render tenants in draft, onboarding, active, and archived across tenant list/detail summary, archived-banner, and chooser surfaces and verify the canonical label appears every time with no Unknown fallback.

Tests for User Story 1 ⚠️

• T010 [P] [US1] Add tenant index, tenant detail summary, and archived-banner lifecycle assertions in tests/Feature/Filament/TenantLifecyclePresentationAcrossTenantSurfacesTest.php
• T011 [P] [US1] Add chooser and onboarding-linked lifecycle copy assertions in tests/Feature/Onboarding/TenantLifecyclePresentationCopyTest.php

Implementation for User Story 1

• T012 [US1] Refactor tenant list lifecycle badge rendering to consume the shared presentation contract in app/Filament/Resources/TenantResource.php
• T013 [US1] Add detailed lifecycle helper presentation to tenant detail identity and summary sections in app/Filament/Resources/TenantResource.php
• T014 [US1] Align archived tenant banner lifecycle copy with the shared contract in app/Filament/Widgets/Tenant/TenantArchivedBanner.php and resources/views/filament/widgets/tenant/tenant-archived-banner.blade.php
• T015 [US1] Expose lifecycle presentation data to chooser records in app/Filament/Pages/ChooseTenant.php
• T016 [US1] Update chooser lifecycle prose and card metadata to use canonical lifecycle semantics in resources/views/filament/pages/choose-tenant.blade.php
• T017 [US1] Align onboarding-linked tenant lifecycle copy with the shared contract in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php

Checkpoint: User Story 1 is complete when tenant management and chooser surfaces all render canonical lifecycle labels and helper copy consistently.

---

Phase 4: User Story 2 - Understand Referenced Tenant Context in the Operations Viewer (Priority: P2)

Goal: Make referenced tenant lifecycle in the tenantless operations viewer use the same lifecycle vocabulary as tenant management surfaces.

Independent Test: Open authorized tenantless operations viewer cases for onboarding and archived tenants and verify the referenced tenant lifecycle uses the same canonical label set and does not imply the record is broken or deleted.

Tests for User Story 2 ⚠️

• T018 [P] [US2] Add onboarding and archived referenced-tenant banner and summary assertions in tests/Feature/Filament/ReferencedTenantLifecyclePresentationTest.php

Implementation for User Story 2

• T019 [US2] Render referenced tenant lifecycle through the shared contract in app/Filament/Pages/Operations/TenantlessOperationRunViewer.php and resources/views/filament/pages/operations/tenantless-operation-run-viewer.blade.php
• T020 [US2] Update the OperationRunResource enterprise-detail summary payload so referenced tenant lifecycle helper text stays aligned with the tenantless operations viewer banner in app/Filament/Resources/OperationRunResource.php

Checkpoint: User Story 2 is complete when the tenantless operations viewer presents onboarding and archived referenced tenants intentionally and with the same lifecycle vocabulary as tenant pages.

---

Phase 5: User Story 3 - Distinguish Lifecycle from Other Tenant Status Domains (Priority: P3)

Goal: Keep lifecycle presentation clearly separate from provider, verification, RBAC, and run-status domains on mixed-status surfaces.

Independent Test: Render mixed-status tenant and tenantless-operations-viewer surfaces where lifecycle appears alongside provider or RBAC status and verify lifecycle remains canonical while adjacent domains keep their own distinct labels.

Tests for User Story 3 ⚠️

• T021 [P] [US3] Add mixed-status separation assertions for lifecycle, app status, and RBAC status in tests/Feature/Filament/TenantLifecycleStatusDomainSeparationTest.php

Implementation for User Story 3

• T022 [US3] Keep lifecycle helper text separate from provider and RBAC summaries in app/Filament/Resources/TenantResource.php
• T023 [US3] Separate lifecycle context wording from run status and operability messaging in app/Filament/Pages/Operations/TenantlessOperationRunViewer.php

Checkpoint: User Story 3 is complete when mixed-status surfaces communicate lifecycle, provider/app state, RBAC status, and run status as distinct concepts.

---

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Final regression cleanup, validation, and formatting across all stories.

• T024 [P] Run focused lifecycle presentation Pest suites covering tests/Unit/Support/Tenants/TenantLifecyclePresentationTest.php, tests/Feature/Filament/TenantLifecyclePresentationAcrossTenantSurfacesTest.php, tests/Feature/Filament/ReferencedTenantLifecyclePresentationTest.php, tests/Feature/Filament/TenantLifecycleStatusDomainSeparationTest.php, and tests/Feature/Onboarding/TenantLifecyclePresentationCopyTest.php
• T025 Run formatting for touched lifecycle presentation files using the validation commands in specs/146-central-tenant-status-presentation/quickstart.md

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): No dependencies - can start immediately
• Foundational (Phase 2): Depends on Setup completion - BLOCKS all user stories
• User Story 1 (Phase 3): Depends on Foundational completion
• User Story 2 (Phase 4): Depends on Foundational completion and should follow User Story 1 once the shared tenant-surface vocabulary is stable
• User Story 3 (Phase 5): Depends on Foundational completion and is safest after User Stories 1 and 2 because it hardens mixed-status behavior on the same touched surfaces
• Polish (Phase 6): Depends on all desired user stories being complete

User Story Dependencies

• User Story 1 (P1): Starts immediately after Foundational and delivers the MVP lifecycle consistency baseline
• User Story 2 (P2): Depends on the shared presentation contract and benefits from the canonical vocabulary established in US1
• User Story 3 (P3): Depends on the shared presentation contract and the surface rollouts from US1/US2 so mixed-status separation is hardened on the final rendered output

Within Each User Story

• Tests for the story should be written first and fail before implementation
• Shared presentation contract usage should land before per-surface copy refinements
• Surface rendering changes should land before cross-surface cleanup assertions
• Story-specific validation should pass before moving to the next priority story

Parallel Opportunities

• T001, T002, and T003 can run in parallel because they create separate test targets
• T005 can run in parallel with T006 once T004 defines the core presentation contract shape
• T010 and T011 can run in parallel because they cover different feature files
• T018 and T021 can run in parallel because they target separate feature test files

---

Parallel Example: User Story 1

# Launch the P1 test coverage tasks together:
Task: "Add tenant index and tenant detail lifecycle assertions in tests/Feature/Filament/TenantLifecyclePresentationAcrossTenantSurfacesTest.php"
Task: "Add chooser and onboarding-linked lifecycle copy assertions in tests/Feature/Onboarding/TenantLifecyclePresentationCopyTest.php"

Parallel Example: User Story 2

# After the shared presentation contract is stable, canonical-view work can split by test and implementation:
Task: "Add onboarding and archived referenced-tenant viewer assertions in tests/Feature/Filament/ReferencedTenantLifecyclePresentationTest.php"
Task: "Render referenced tenant lifecycle through the shared contract in app/Filament/Pages/Operations/TenantlessOperationRunViewer.php"

Parallel Example: User Story 3

# Mixed-status hardening can separate regression coverage from resource refinement:
Task: "Add mixed-status separation assertions for lifecycle, app status, and RBAC status in tests/Feature/Filament/TenantLifecycleStatusDomainSeparationTest.php"
Task: "Keep lifecycle helper text separate from provider and RBAC summaries in app/Filament/Resources/TenantResource.php"

---

Implementation Strategy

MVP First

• Complete Phase 1 and Phase 2
• Deliver User Story 1 as the MVP because it establishes the shared lifecycle vocabulary and removes Unknown fallback from the primary tenant management surfaces
• Validate the focused P1 tests before moving on

Incremental Delivery

• Add User Story 2 next to align the tenantless operations viewer with the same lifecycle contract
• Add User Story 3 last to harden separation from adjacent status domains on mixed-status surfaces
• Finish with the Polish phase for focused validation and formatting

Team Strategy

• One engineer can own the foundational contract and badge integration work
• A second engineer can prepare the tenant-surface regression tests in parallel once the contract shape is clear
• Canonical viewer and mixed-status hardening can proceed as separate follow-up streams after the foundational phase is merged