TenantAtlas/specs/143-tenant-lifecycle-operability-context-semantics/tasks.md

Tasks: Tenant Lifecycle, Operability, and Context Semantics Foundation

Input: Design documents from /specs/143-tenant-lifecycle-operability-context-semantics/ Prerequisites: plan.md, spec.md, checklists/requirements.md, research.md, data-model.md, quickstart.md, contracts/admin-tenant-context-foundation.openapi.yaml

Tests: Runtime behavior changes in this repo require Pest coverage. Each user story below includes the focused tests needed to keep the change independently verifiable. Operations: This foundation changes canonical OperationRun viewer semantics but does not add a new run type or new queued work. Tasks must preserve existing OperationRunService ownership and canonical Monitoring navigation. RBAC: This feature changes admin-plane authorization semantics. Tasks must preserve 404 vs 403 rules, policy enforcement, canonical capability registry usage, and tenant-safe global-search behavior. Badges: Tenant lifecycle badge behavior must stay centralized through BadgeCatalog and TenantStatusBadge. Audit: Any lifecycle mutation or newly clarified lifecycle action semantics must emit explicit workspace audit entries through the existing audit layer.

Phase 1: Setup (Shared Infrastructure)

Purpose: Prepare shared fixtures and support types used by every story.

• T001 Create tenant lifecycle factory states in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/database/factories/TenantFactory.php
• T002 [P] Create operation-run mismatch fixtures in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/database/factories/OperationRunFactory.php
• T003 [P] Create onboarding draft lifecycle fixtures in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/database/factories/TenantOnboardingSessionFactory.php

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Central abstractions that all stories depend on.

⚠️ CRITICAL: No user story work should start before this phase is complete.

• T004 Create canonical tenant lifecycle enum in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Tenants/TenantLifecycle.php
• T005 [P] Create page category enum in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Tenants/TenantPageCategory.php
• T006 [P] Create tenant operability decision DTO in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Tenants/TenantOperabilityDecision.php
• T007 Implement central operability rules in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Services/Tenants/TenantOperabilityService.php
• T008 Integrate canonical lifecycle helpers into /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Models/Tenant.php
• T009 [P] Wire remembered tenant eligibility helpers into /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Workspaces/WorkspaceContext.php
• T010 [P] Wire active entitled tenant resolution to operability rules in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/OperateHub/OperateHubShell.php
• T011 [P] Extend lifecycle audit action identifiers in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Audit/AuditActionId.php
• T012 [P] Add lifecycle audit logging helper coverage in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Services/Audit/WorkspaceAuditLogger.php
• T013 [P] Add unit coverage for lifecycle and operability decisions in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Tenants/TenantOperabilityServiceTest.php
• T014 [P] Add unit coverage for lifecycle enum normalization in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Tenants/TenantLifecycleTest.php
• T015 [P] Add unit coverage for page-category resolution in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Tenants/TenantPageCategoryTest.php

Checkpoint: Central lifecycle, operability, and audit helpers are available for all user stories.

---

Phase 3: User Story 1 - Trust Canonical Record Views (Priority: P1) 🎯 MVP

Goal: Canonical workspace-owned record viewers remain valid when remembered tenant context differs from the record’s tenant.

Independent Test: Open a valid /admin/operations/{run} route while another tenant is selected and verify the page still renders for entitled users, while non-members still receive 404 and members missing capability still receive 403.

Tests for User Story 1

• T016 [P] [US1] Update canonical operation viewer behavior tests in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Operations/TenantlessOperationRunViewerTest.php
• T017 [P] [US1] Update remembered-context mismatch regression coverage in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Spec085/CanonicalMonitoringDoesNotMutateTenantContextTest.php
• T018 [P] [US1] Update canonical URL and tenant entitlement tests in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Monitoring/OperationsCanonicalUrlsTest.php
• T019 [P] [US1] Update positive and negative authorization coverage for run access in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/RunAuthorizationTenantIsolationTest.php

Implementation for User Story 1

• T020 [US1] Refactor canonical viewer mount and mismatch handling in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
• T021 [US1] Refactor canonical run URL generation and back-navigation behavior in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/OperationRunLinks.php
• T022 [US1] Apply workspace-scoped filter semantics to operation lists and defaults in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Resources/OperationRunResource.php
• T023 [US1] Preserve policy-based 404 and 403 semantics for canonical runs in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Policies/OperationRunPolicy.php
• T024 [US1] Align operations route semantics with canonical viewer rules in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/routes/web.php
• T025 [US1] Preserve canonical viewer page-category behavior in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Concerns/ResolvesPanelTenantContext.php

Checkpoint: Canonical operation run viewing works independently of remembered tenant context and remains authorization-safe.

---

Phase 4: User Story 2 - Select Only Operable Tenants (Priority: P2)

Goal: Standard tenant selection surfaces expose only valid normal operating tenants, while onboarding and archived tenants remain visible in the right management surfaces.

Independent Test: Seed tenants in draft, onboarding, active, and archived states, then verify that /admin/choose-tenant, tenant-selection posts, and tenant global search expose only eligible tenants while onboarding and administrative pages still show the non-active tenants appropriately.

Tests for User Story 2

• T026 [P] [US2] Update tenant chooser lifecycle eligibility tests in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Auth/TenantChooserSelectionTest.php
• T027 [P] [US2] Update remembered tenant switcher scope tests in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/TenantRBAC/TenantSwitcherScopeTest.php
• T028 [P] [US2] Add managed-tenants landing lifecycle visibility coverage in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Filament/ManagedTenantsLandingLifecycleTest.php
• T029 [P] [US2] Update archived tenant route access expectations in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/TenantRBAC/ArchivedTenantRouteAccessTest.php
• T030 [P] [US2] Add tenant global-search lifecycle scope coverage in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Filament/TenantGlobalSearchLifecycleScopeTest.php

Implementation for User Story 2

• T031 [US2] Apply central operability filtering to chooser rendering in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Pages/ChooseTenant.php
• T032 [US2] Apply central operability filtering to tenant selection writes in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Http/Controllers/SelectTenantController.php
• T033 [US2] Clear or ignore ineligible remembered tenant context in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Http/Controllers/ClearTenantContextController.php
• T034 [US2] Enforce workspace-level remembered tenant validity in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Workspaces/WorkspaceContext.php
• T035 [US2] Align managed-tenant landing visibility with operability rules in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Pages/Workspaces/ManagedTenantsLanding.php
• T036 [US2] Align workspace selection and graceful fallback behavior in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Http/Middleware/EnsureWorkspaceSelected.php
• T037 [US2] Scope tenant global search to eligible tenant records in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Resources/TenantResource.php

Checkpoint: Tenant selectors, remembered context, and global search enforce active-only operating selection without making onboarding or archived tenants disappear from management flows.

---

Phase 5: User Story 3 - Understand Lifecycle and Actions Clearly (Priority: P3)

Goal: Tenant lifecycle labels, badges, actions, and audit behavior are centrally defined and semantically accurate across tenant management and onboarding surfaces.

Independent Test: Inspect tenant management and onboarding surfaces and verify that each lifecycle renders explicitly, archive-like actions use Archive, onboarding tenants can expose Resume onboarding when valid, no valid lifecycle renders as Unknown, and lifecycle mutations emit the expected audit records.

Tests for User Story 3

• T038 [P] [US3] Update tenant lifecycle badge mapping coverage in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Badges/TenantStatusBadgeTest.php
• T039 [P] [US3] Update tenant resource authorization and action visibility coverage in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/TenantResourceAuthorizationTest.php
• T040 [P] [US3] Update archive action enforcement coverage in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/EditTenantArchiveUiEnforcementTest.php
• T041 [P] [US3] Update onboarding lifecycle visibility and resume semantics coverage in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Onboarding/OnboardingDraftLifecycleTest.php
• T042 [P] [US3] Update onboarding authorization semantics for linked tenants in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php
• T043 [P] [US3] Add lifecycle audit log coverage in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Audit/TenantLifecycleAuditLogTest.php

Implementation for User Story 3

• T044 [US3] Centralize tenant lifecycle badge presentation in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Badges/Domains/TenantStatusBadge.php
• T045 [US3] Wire tenant lifecycle badge normalization through /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Badges/BadgeCatalog.php
• T046 [US3] Align tenant table actions, filters, labels, and audit hooks with lifecycle-safe semantics in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Resources/TenantResource.php
• T047 [US3] Align onboarding wizard resume and view affordances with tenant lifecycle boundaries in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
• T048 [US3] Preserve onboarding workflow versus tenant lifecycle boundaries and audit emission in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Services/Onboarding/OnboardingLifecycleService.php
• T049 [US3] Preserve draft resolution and entitlement semantics for linked tenants in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Services/Onboarding/OnboardingDraftResolver.php
• T050 [US3] Preserve workflow-model lifecycle boundaries in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Models/TenantOnboardingSession.php

Checkpoint: Lifecycle presentation, lifecycle-driven actions, and lifecycle audit behavior are centrally defined, semantically accurate, and independently testable.

---

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Close gaps that affect multiple stories and run final validation.

• T051 [P] Add a guard against new ad hoc lifecycle checks in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Guards/NoAdHocTenantLifecycleChecksSpec143Test.php
• T052 Run the focused Spec 143 validation suite from /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/143-tenant-lifecycle-operability-context-semantics/quickstart.md using /Users/ahmeddarrazi/Documents/projects/TenantAtlas/vendor/bin/sail artisan test --compact
• T053 Run formatting for all changed PHP files with /Users/ahmeddarrazi/Documents/projects/TenantAtlas/vendor/bin/sail bin pint --dirty --format agent

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): Starts immediately.
• Foundational (Phase 2): Depends on Setup and blocks all user stories.
• 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 Foundational completion.
• Polish (Phase 6): Depends on the completion of the user stories included in the delivery scope.

User Story Dependencies

• US1: No dependency on other user stories. This is the MVP because it resolves the highest-trust canonical viewer failure.
• US2: Depends only on foundational operability and remembered-context helpers, not on US1.
• US3: Depends only on foundational lifecycle, operability, and audit abstractions, not on US1 or US2, though it benefits from their shared helpers.

Recommended Order

1. Complete Phase 1 and Phase 2.
2. Deliver US1 as the MVP trust fix.
3. Deliver US2 to align selector and global-search behavior with operability rules.
4. Deliver US3 to unify lifecycle presentation, action semantics, and audit coverage.
5. Run polish validation and formatting before merge.

Parallel Opportunities

• T002 and T003 can run in parallel after T001.
• T005, T006, T009, T010, T011, T012, T013, T014, and T015 can run in parallel once T004 is started.
• All test tasks inside each user story marked [P] can run in parallel.
• In US1, T020, T021, T022, T023, and T025 can be split across contributors after the tests are in place.
• In US2, T031, T032, T033, T034, T035, T036, and T037 can be split by controller, middleware, page, and search surfaces after the foundational service exists.
• In US3, T044, T045, T046, T047, T048, T049, and T050 can be split between badge, Filament surface, onboarding-service, and audit work.

Parallel Example: User Story 1

# Parallelize the focused US1 regression tests:
Task: T016 Update canonical operation viewer behavior tests in tests/Feature/Operations/TenantlessOperationRunViewerTest.php
Task: T017 Update remembered-context mismatch regression coverage in tests/Feature/Spec085/CanonicalMonitoringDoesNotMutateTenantContextTest.php
Task: T018 Update canonical URL and tenant entitlement tests in tests/Feature/Monitoring/OperationsCanonicalUrlsTest.php
Task: T019 Update positive and negative authorization coverage for run access in tests/Feature/RunAuthorizationTenantIsolationTest.php

# Then parallelize the implementation seams:
Task: T020 Refactor canonical viewer mount and mismatch handling in app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
Task: T021 Refactor canonical run URL generation and back-navigation behavior in app/Support/OperationRunLinks.php
Task: T022 Apply workspace-scoped filter semantics to operation lists and defaults in app/Filament/Resources/OperationRunResource.php
Task: T023 Preserve policy-based 404 and 403 semantics for canonical runs in app/Policies/OperationRunPolicy.php

Parallel Example: User Story 2

# Parallelize selector and search-scope tests:
Task: T026 Update tenant chooser lifecycle eligibility tests in tests/Feature/Auth/TenantChooserSelectionTest.php
Task: T027 Update remembered tenant switcher scope tests in tests/Feature/TenantRBAC/TenantSwitcherScopeTest.php
Task: T028 Add managed-tenants landing lifecycle visibility coverage in tests/Feature/Filament/ManagedTenantsLandingLifecycleTest.php
Task: T029 Update archived tenant route access expectations in tests/Feature/TenantRBAC/ArchivedTenantRouteAccessTest.php
Task: T030 Add tenant global-search lifecycle scope coverage in tests/Feature/Filament/TenantGlobalSearchLifecycleScopeTest.php

# Then split controller, page, and search work:
Task: T031 Apply central operability filtering to chooser rendering in app/Filament/Pages/ChooseTenant.php
Task: T032 Apply central operability filtering to tenant selection writes in app/Http/Controllers/SelectTenantController.php
Task: T035 Align managed-tenant landing visibility with operability rules in app/Filament/Pages/Workspaces/ManagedTenantsLanding.php
Task: T037 Scope tenant global search to eligible tenant records in app/Filament/Resources/TenantResource.php

Parallel Example: User Story 3

# Parallelize lifecycle presentation and audit tests:
Task: T038 Update tenant lifecycle badge mapping coverage in tests/Feature/Badges/TenantStatusBadgeTest.php
Task: T039 Update tenant resource authorization and action visibility coverage in tests/Feature/Rbac/TenantResourceAuthorizationTest.php
Task: T040 Update archive action enforcement coverage in tests/Feature/Rbac/EditTenantArchiveUiEnforcementTest.php
Task: T043 Add lifecycle audit log coverage in tests/Feature/Audit/TenantLifecycleAuditLogTest.php

# Then split badge, resource, onboarding, and audit implementation:
Task: T044 Centralize tenant lifecycle badge presentation in app/Support/Badges/Domains/TenantStatusBadge.php
Task: T046 Align tenant table actions, filters, labels, and audit hooks with lifecycle-safe semantics in app/Filament/Resources/TenantResource.php
Task: T048 Preserve onboarding workflow versus tenant lifecycle boundaries and audit emission in app/Services/Onboarding/OnboardingLifecycleService.php

Implementation Strategy

MVP First

• Deliver Phase 1, Phase 2, and Phase 3 first.
• This yields the highest-value trust fix: canonical workspace record viewers no longer fail because of remembered tenant mismatch.

Incremental Delivery

• After the MVP, deliver Phase 4 to make tenant selection and tenant global search match the new operability model.
• Then deliver Phase 5 to unify lifecycle presentation, action semantics, and audit behavior across tenant management and onboarding.
• Finish with Phase 6 guardrails, focused validation, and formatting.

Task Count Summary

• Total tasks: 53
• Setup tasks: 3
• Foundational tasks: 12
• US1 tasks: 10
• US2 tasks: 12
• US3 tasks: 13
• Polish tasks: 3