ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
149-queued-execution-reauthorization
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

19 KiB
Raw Permalink Blame History

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.

  • T001 Create shared tenant lifecycle/action test helpers in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Pest.php
  • 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.

  • 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
  • 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
  • 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
  • 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

  • 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
  • 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
  • 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
  • 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

  • T011 [US1] Refactor tenant row actions to consume the central action policy in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Resources/TenantResource.php
  • 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
  • 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
  • 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

  • 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
  • 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

  • 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
  • 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
  • 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

  • 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
  • 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
  • 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

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

  • 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
  • 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
  • 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

# 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

# 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

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