# Tasks: Tenant Action Taxonomy and Lifecycle-Safe Visibility **Input**: Design documents from `/specs/145-tenant-action-taxonomy-lifecycle-safe-visibility/` **Prerequisites**: `plan.md` (required), `spec.md` (required for user stories), `research.md`, `data-model.md`, `contracts/`, `quickstart.md` **Tests**: Runtime behavior changes in this repo require Pest coverage. This feature changes runtime behavior across tenant-management and onboarding surfaces, so tests are required for every user story. **Operations**: This feature does not introduce new long-running or remote work. Existing run-producing actions remain under their current Ops-UX contracts and are not expanded here. **RBAC**: This feature changes authorization-driven action visibility. Tasks below include central policy enforcement, canonical capability-registry usage, explicit 404 versus 403 semantics, and positive/negative authorization tests. **Global Search**: This feature does not redesign tenant global search, but because the spec carries RBAC-UX safety requirements, tasks below include an explicit regression check that touched tenant action semantics do not introduce non-member leakage or tenant-context unsafe search behavior. **UI Naming**: This feature changes operator-facing action labels, modal titles, notifications, and audit-aligned helper copy. Tasks below standardize `View`, `Resume onboarding`, `Archive`, and `Restore` vocabulary across surfaces. **Filament UI Action Surfaces**: This feature modifies Filament resources and pages. Tasks below keep list/detail/onboarding action surfaces aligned with the spec matrix, maintain max two visible row actions before overflow, preserve inspection affordances, and keep destructive-like actions confirmation-gated. **Filament UI UX-001**: This feature is not a layout redesign. Tasks below keep existing layouts intact while hardening action grouping and lifecycle-safe affordances. **Badges**: Tenant lifecycle badge semantics remain centralized; tasks below ensure touched surfaces continue to derive lifecycle wording from shared badge/lifecycle helpers rather than ad hoc mappings. **Contract Artifact**: `/specs/145-tenant-action-taxonomy-lifecycle-safe-visibility/contracts/tenant-action-taxonomy.openapi.yaml` is a design contract for internal action semantics and resolver shape, not a commitment to add public controller endpoints in this spec slice. **Organization**: Tasks are grouped by user story so each story can be implemented and tested independently. ## Phase 1: Setup (Shared Infrastructure) **Purpose**: Prepare shared fixtures and test entry points used by the rest of the implementation. - [X] T001 Create shared tenant lifecycle/action test helpers in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Pest.php` - [X] T002 [P] Create the new regression test entry points in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Tenants/TenantActionPolicySurfaceTest.php`, `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/TenantLifecycleActionVisibilityTest.php`, `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/TenantLifecycleActionNamingTest.php`, and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php` --- ## Phase 2: Foundational (Blocking Prerequisites) **Purpose**: Build the central tenant-action semantics layer that all user stories depend on. **⚠️ CRITICAL**: No user story work should begin until this phase is complete. - [X] T003 [P] Add failing foundational unit coverage for lifecycle-safe action predicates in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Tenants/TenantActionPolicySurfaceTest.php` and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Tenants/TenantOperabilityServiceTest.php` - [X] T004 Create tenant action value objects and enums in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Tenants/TenantActionContext.php`, `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Tenants/TenantActionDescriptor.php`, `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Tenants/TenantActionFamily.php`, and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Tenants/TenantActionSurface.php` - [X] T005 Implement the central resolver in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Services/Tenants/TenantActionPolicySurface.php` using `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Services/Tenants/TenantOperabilityService.php` and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Services/Onboarding/OnboardingLifecycleService.php` - [X] T006 Update reusable lifecycle predicates in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Tenants/TenantOperabilityDecision.php`, `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Tenants/TenantLifecycle.php`, and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Services/Tenants/TenantOperabilityService.php` **Checkpoint**: Foundation ready. User story implementation can now proceed. --- ## Phase 3: User Story 1 - See The Right Next Action (Priority: P1) 🎯 MVP **Goal**: Show only lifecycle-valid next actions for each tenant state across tenant-management and onboarding surfaces. **Independent Test**: Prepare `draft`, `onboarding`, `active`, and `archived` tenants and verify each in-scope surface shows only the correct next action, with non-members denied as 404 and in-scope capability denials preserved as 403 or disabled via current UI-enforcement patterns. ### Tests for User Story 1 - [X] T007 [P] [US1] Extend lifecycle visibility and authorization coverage in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/TenantResourceAuthorizationTest.php` and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/TenantLifecycleActionVisibilityTest.php` - [X] T008 [P] [US1] Extend onboarding-specific action availability coverage in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Onboarding/OnboardingDraftLifecycleTest.php` and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php` - [X] T009 [P] [US1] Add explicit lifecycle-invalid and workflow-invalid failure-honesty coverage in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/TenantLifecycleActionVisibilityTest.php` and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Onboarding/OnboardingDraftLifecycleTest.php` - [X] T010 [P] [US1] Add selected-header-tenant independence coverage for tenant action legitimacy in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/TenantLifecycleActionVisibilityTest.php` and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php` ### Implementation for User Story 1 - [X] T011 [US1] Refactor tenant row actions to consume the central action policy in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Resources/TenantResource.php` - [X] T012 [US1] Refactor tenant header lifecycle actions to consume the central action policy in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Resources/TenantResource/Pages/ViewTenant.php` and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Resources/TenantResource/Pages/EditTenant.php` - [X] T013 [US1] Refactor onboarding entry and workflow actions so onboarding stays workflow-contextual in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Resources/TenantResource/Pages/ListTenants.php` and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` - [X] T014 [US1] Align server-side lifecycle-action guards, failure-honesty messages, and 404 versus 403 behavior in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Resources/TenantResource.php`, `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Resources/TenantResource/Pages/ViewTenant.php`, and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Policies/TenantOnboardingSessionPolicy.php` **Checkpoint**: User Story 1 is complete when every tenant lifecycle shows the correct next action without surfacing invalid archive/restore/onboarding transitions. --- ## Phase 4: User Story 2 - Trust Action Labels (Priority: P2) **Goal**: Ensure tenant lifecycle action labels, modal titles, notifications, and audit-aligned copy describe actual domain behavior. **Independent Test**: Verify that archive-like behavior is always labeled `Archive`, archived recovery is always `Restore`, and onboarding continuation remains `Resume onboarding`, with no `Deactivate` terminology across touched admin surfaces. ### Tests for User Story 2 - [X] T015 [P] [US2] Extend operator-facing naming and confirmation-regression coverage in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/EditTenantArchiveUiEnforcementTest.php` and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/TenantLifecycleActionNamingTest.php` - [X] T016 [P] [US2] Extend lifecycle wording coverage in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Onboarding/OnboardingDraftLifecycleTest.php` and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/144/CanonicalOperationViewerContextMismatchTest.php` ### Implementation for User Story 2 - [X] T017 [US2] Centralize action labels and taxonomy metadata in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Services/Tenants/TenantActionPolicySurface.php` and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Tenants/TenantActionDescriptor.php` - [X] T018 [US2] Replace lifecycle action labels, modal titles, and notification copy in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Resources/TenantResource.php`, `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Resources/TenantResource/Pages/ViewTenant.php`, `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Resources/TenantResource/Pages/EditTenant.php`, and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` - [X] T019 [US2] Align audit-facing prose and lifecycle-supporting wording without changing stable audit action IDs in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Badges/Domains/TenantStatusBadge.php`, `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Widgets/Tenant/TenantArchivedBanner.php`, and the touched Filament lifecycle-action surfaces **Checkpoint**: User Story 2 is complete when all touched operator-facing lifecycle copy uses honest taxonomy and avoids ambiguous or implementation-first wording. --- ## Phase 5: User Story 3 - Get Consistent Cross-Surface Behavior (Priority: P3) **Goal**: Keep lifecycle action availability consistent across list rows, detail headers, onboarding surfaces, and contextual tenant affordances. **Independent Test**: Compare the same tenant lifecycle across index, detail, onboarding, and contextual surfaces and confirm there are no contradictory lifecycle actions or mismatched hidden/disabled behaviors. ### Tests for User Story 3 - [X] T020 [P] [US3] Extend cross-surface consistency coverage in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php` and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/TenantRBAC/ArchivedTenantRouteAccessTest.php` - [X] T021 [P] [US3] Extend selector and UI-enforcement consistency coverage in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/TenantRBAC/TenantSwitcherScopeTest.php` and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/UiEnforcementNonMemberHiddenTest.php` - [X] T022 [P] [US3] Add tenant global-search safety regression coverage or explicit non-impact verification in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php` and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/TenantRBAC/TenantSwitcherScopeTest.php` ### Implementation for User Story 3 - [X] T023 [US3] Reuse a single resolved action catalog for runtime action selection across `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Resources/TenantResource.php`, `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Resources/TenantResource/Pages/ViewTenant.php`, `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Resources/TenantResource/Pages/EditTenant.php`, and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` - [X] T024 [US3] Update action-surface declarations and contract-oriented overflow behavior only, without introducing resolver logic, in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Resources/TenantResource.php` and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Ui/ActionSurface/ActionSurfaceDeclaration.php` - [X] T025 [US3] Normalize contextual lifecycle affordances in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Resources/TenantResource/Pages/ListTenants.php`, `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Widgets/Tenant/TenantArchivedBanner.php`, and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Widgets/Tenant/TenantVerificationReport.php` **Checkpoint**: User Story 3 is complete when equivalent tenant lifecycles no longer expose contradictory actions across touched surfaces. --- ## Phase 6: Polish & Cross-Cutting Concerns **Purpose**: Finalize shared validation and clean up cross-story regressions. - [X] T026 [P] Add final shared regression assertions in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Tenants/TenantActionPolicySurfaceTest.php` and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php` - [X] T027 Run and stabilize the full focused validation suite documented in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/145-tenant-action-taxonomy-lifecycle-safe-visibility/quickstart.md`, including `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Tenants/TenantOperabilityServiceTest.php`, `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Tenants/TenantActionPolicySurfaceTest.php`, `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/TenantResourceAuthorizationTest.php`, `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/TenantLifecycleActionVisibilityTest.php`, `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/TenantLifecycleActionNamingTest.php`, `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php`, `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/EditTenantArchiveUiEnforcementTest.php`, `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Onboarding/OnboardingDraftLifecycleTest.php`, `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/TenantRBAC/TenantSwitcherScopeTest.php`, and `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/TenantRBAC/ArchivedTenantRouteAccessTest.php` - [X] T028 Run formatting for touched PHP files using `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/145-tenant-action-taxonomy-lifecycle-safe-visibility/quickstart.md` --- ## Dependencies & Execution Order ### Phase Dependencies - **Phase 1: Setup** has no dependencies and can start immediately. - **Phase 2: Foundational** depends on Phase 1 and blocks all story work. - **Phase 3: User Story 1** depends on Phase 2 and delivers the MVP. - **Phase 4: User Story 2** depends on Phase 2 and benefits from User Story 1’s central policy surface. - **Phase 5: User Story 3** depends on Phase 2 and should follow after the main policy surface is integrated into list/detail/onboarding surfaces. - **Phase 6: Polish** depends on the chosen story phases being complete. ### User Story Dependencies - **US1 (P1)**: Starts immediately after foundational work and establishes lifecycle-safe availability. - **US2 (P2)**: Depends on the foundational policy surface and reuses US1 integration points for naming consistency. - **US3 (P3)**: Depends on the foundational policy surface and validates consistency after US1 and US2 integrations are in place. ### Within Each User Story - Write or extend tests first and confirm they fail before implementing the corresponding behavior. - Central support/value objects come before surface refactors. - Surface refactors come before copy cleanup and final contract alignment. - Story-level regression coverage must pass before moving to the next priority. ### Parallel Opportunities - `T002` and `T003` can be done in parallel after the initial test-helper setup. - `T007`, `T008`, `T009`, and `T010` can run in parallel within US1. - `T015` and `T016` can run in parallel within US2. - `T020`, `T021`, and `T022` can run in parallel within US3. - `T026` can run in parallel with parts of `T027` once implementation is complete. --- ## Parallel Example: User Story 1 ```bash # Execute lifecycle visibility and onboarding workflow test updates in parallel: Task: "Extend lifecycle visibility and authorization coverage in tests/Feature/Rbac/TenantResourceAuthorizationTest.php and tests/Feature/Rbac/TenantLifecycleActionVisibilityTest.php" Task: "Extend onboarding-specific action availability coverage in tests/Feature/Onboarding/OnboardingDraftLifecycleTest.php and tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php" ``` ## Parallel Example: User Story 2 ```bash # Execute naming and lifecycle-copy regression updates in parallel: Task: "Extend operator-facing naming coverage in tests/Feature/Rbac/EditTenantArchiveUiEnforcementTest.php and tests/Feature/Rbac/TenantLifecycleActionNamingTest.php" Task: "Extend lifecycle wording coverage in tests/Feature/Onboarding/OnboardingDraftLifecycleTest.php and tests/Feature/144/CanonicalOperationViewerContextMismatchTest.php" ``` ## Parallel Example: User Story 3 ```bash # Execute cross-surface and selector consistency coverage in parallel: Task: "Extend cross-surface consistency coverage in tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php and tests/Feature/TenantRBAC/ArchivedTenantRouteAccessTest.php" Task: "Extend selector and UI-enforcement consistency coverage in tests/Feature/TenantRBAC/TenantSwitcherScopeTest.php and tests/Feature/Rbac/UiEnforcementNonMemberHiddenTest.php" ``` --- ## Implementation Strategy ### MVP First 1. Complete Setup and Foundational phases. 2. Deliver User Story 1 by centralizing lifecycle-safe action availability across tenant list, detail, and onboarding surfaces. 3. Validate the focused regression suite before moving on. ### Incremental Delivery 1. Add taxonomy-honest labels and copy through User Story 2 without changing ownership boundaries or onboarding activation semantics. 2. Finish User Story 3 by eliminating cross-surface drift and documenting contract-compliant action layouts. ### Completion 1. Run the focused validation suite from `quickstart.md`. 2. Run Pint on touched files. 3. Confirm the implementation matches the spec’s UI Action Matrix and lifecycle-by-action matrix.