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