ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
dev
TenantAtlas/specs/145-tenant-action-taxonomy-lifecycle-safe-visibility/tasks.md
ahmido 440e63edff feat: implement tenant action taxonomy lifecycle visibility (#174) 
## Summary

Implements Spec 145 for tenant action taxonomy and lifecycle-safe visibility.

This PR:
- adds a central tenant action policy surface and supporting value objects
- aligns tenant list, detail, edit, onboarding, and widget surfaces around lifecycle-safe actions
- standardizes operator-facing lifecycle wording around View, Resume onboarding, Archive, Restore, and Complete onboarding
- tightens onboarding and tenant lifecycle authorization semantics, including honest 404 vs 403 behavior
- updates related regression coverage and spec artifacts for Spec 145
- fixes follow-on full-suite regressions uncovered during validation, including onboarding browser flows, provider consent fixtures, workspace redirect DI expectations, and critical table/action/UI expectation drift

## Validation

Executed and passed:
- vendor/bin/sail bin pint --dirty --format agent
- vendor/bin/sail artisan test --compact

Result:
- 2581 passed
- 8 skipped
- 13534 assertions

## Notes

- Base branch: dev
- Feature branch commit: a33a41b
- Filament v5 / Livewire v4 compliance preserved
- No panel provider registration changes; Laravel 12 provider registration remains in bootstrap/providers.php
- No new globally searchable resource behavior added in this slice
- Destructive lifecycle actions remain confirmation-gated and authorization-protected

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #174
2026-03-16 00:57:17 +00:00

196 lines
19 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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.
Reference in New Issue View Git Blame Copy Permalink