TenantAtlas/specs/251-commercial-entitlements-billing-state/tasks.md

description
Task list for feature implementation

Tasks: Commercial Entitlements and Billing-State Maturity

Input: Design documents from /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/ Prerequisites: /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/plan.md (required), /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/spec.md (required), /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/checklists/requirements.md (required), /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/research.md, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/data-model.md, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/contracts/workspace-commercial-lifecycle-overlay.logical.openapi.yaml, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/quickstart.md

Tests: Required (Pest) for all runtime behavior changes. Keep proof in focused Unit plus Feature lanes only, using the targeted Sail commands already captured in the feature spec, plan, and quickstart artifacts.

Test Governance Notes

• Lane assignment: fast-feedback and confidence are the narrowest sufficient proof for resolver precedence, system-plane mutation, onboarding gating, review-pack start blocking, and preserved suspended read-only continuation.
• Keep new coverage inside /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Unit/Entitlements/ plus focused /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/System/, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Onboarding/, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/ReviewPack/, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Reviews/, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Evidence/; do not widen this slice into browser or heavy-governance families.
• Reuse existing workspace, platform-user, workspace-member, onboarding-draft, tenant, review-pack, and evidence fixtures; any new helper or factory state must stay opt-in and cheap by default.
• If implementation needs a bounded exception for blocked-decision transport or preserved read-only scope, record document-in-feature or follow-up-spec in the final close-out task instead of widening feature scope.

Scope Control Notes

• Keep implementation inside one commercial lifecycle overlay, one system-plane lifecycle mutation surface, managed-tenant onboarding activation gating, review-pack generation/regeneration/export gating, and preserved read-only review/evidence/download semantics while suspended.
• Do not add payment provider, invoicing, checkout, website, customer-account, localization, external support-desk handoff, or broad billing-platform work.

---

Phase 1: Setup (Shared Infrastructure)

Purpose: Lock the bounded slice, contract semantics, and validation plan before runtime edits begin.

• T001 Review the bounded slice, explicit non-goals, scope-control decisions, and review outcomes in /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/spec.md, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/plan.md, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/checklists/requirements.md
• T002 [P] Review the lifecycle-state model, system/admin split, preserved read-only contract, and 404 versus 403 versus business-state semantics in /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/research.md, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/data-model.md, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/contracts/workspace-commercial-lifecycle-overlay.logical.openapi.yaml
• T003 [P] Confirm the focused Sail/Pest proof commands and reviewer scenarios in /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/quickstart.md

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Add the shared lifecycle primitives that every user story depends on.

⚠️ CRITICAL: No user story work should begin until this phase is complete.

• T004 [P] Register the commercial lifecycle state and rationale setting definitions, validation metadata, and operator-facing labels in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/Settings/SettingsRegistry.php
• T005 [P] Add the bounded four-state catalog, action-decision matrix, and shared overlay resolution logic in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Entitlements/WorkspaceCommercialLifecycleResolver.php
• T006 Thread lifecycle setting resolution, default active_paid fallback, and lifecycle change attribution through /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Settings/SettingsResolver.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Settings/SettingsWriter.php, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Entitlements/WorkspaceCommercialLifecycleResolver.php

Checkpoint: Foundation ready. User story work can now proceed independently without inventing local lifecycle state.

---

Phase 3: User Story 1 - Set Workspace Commercial State Centrally (Priority: P1) 🎯 MVP

Goal: Let an authorized platform operator inspect and change one workspace commercial lifecycle state from the existing system workspace detail surface.

Independent Test: Open /system/directory/workspaces/{workspace} as an authorized and unauthorized platform actor, change the lifecycle state with rationale, and verify the page shows current state, affected behavior summary, last-changed attribution, and audit-backed mutation semantics without creating a second control plane.

Tests for User Story 1

• T007 [P] [US1] Add unit coverage for default active_paid fallback, explicit stored states, default_active_paid versus workspace_setting source resolution, grace versus suspended action outcomes, and last-change attribution in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Unit/Entitlements/WorkspaceCommercialLifecycleResolverTest.php
• T008 [P] [US1] Extend system-plane feature coverage for lifecycle summary and source-label rendering, capability-gated mutation, confirmation plus rationale validation for every explicit transition, and 404 versus 403 semantics in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/System/ViewWorkspaceEntitlementsTest.php and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/System/Spec113/AuthorizationSemanticsTest.php

Implementation for User Story 1

• T009 [US1] Add the dedicated commercial-lifecycle management capability and apply it to the system workspace detail action surface in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/Auth/PlatformCapabilities.php and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/System/Pages/Directory/ViewWorkspace.php
• T010 [US1] Project the shared lifecycle state, source label, rationale, affected-behavior summary, and last-changed attribution onto /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/System/Pages/Directory/ViewWorkspace.php and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/resources/views/filament/system/pages/directory/view-workspace.blade.php
• T011 [US1] Add the confirmation-protected Change commercial state action with audited old/new state writes and rationale validation for every explicit lifecycle transition in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/System/Pages/Directory/ViewWorkspace.php and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Settings/SettingsWriter.php

Checkpoint: User Story 1 is independently functional when the system plane exposes one canonical lifecycle decision and one audited mutation path.

---

Phase 4: User Story 2 - Truthfully Gate Managed-Tenant Activation (Priority: P1)

Goal: Keep onboarding completion visible to otherwise authorized workspace actors while blocking activation with business-state truth when grace or suspended_read_only freezes expansion.

Independent Test: Seed workspaces in trial, active_paid, grace, and suspended_read_only, open the existing onboarding completion step, and verify that activation is either allowed or blocked with the correct lifecycle explanation before any tenant activation mutation occurs.

Tests for User Story 2

• T012 [P] [US2] Extend onboarding feature coverage for trial/active allow, grace block, suspended block, and 404 versus 403 versus business-state outcomes in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Onboarding/ManagedTenantOnboardingEntitlementTest.php and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Onboarding/OnboardingRbacSemanticsTest.php

Implementation for User Story 2

• T013 [US2] Project the shared lifecycle decision onto the onboarding completion step and helper text in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
• T014 [US2] Enforce lifecycle blocking before any tenant activation mutation or onboarding completion audit path in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
• T015 [US2] Keep grace and suspended explanations distinct from entitlement-limit and authorization failures by sourcing block messaging from /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/Entitlements/WorkspaceCommercialLifecycleResolver.php inside /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php

Checkpoint: User Story 2 is independently functional when onboarding activation exposes one truthful lifecycle decision and never mutates tenant state after a commercial-state block.

---

Phase 5: User Story 3 - Block New Review-Pack Starts While Preserving Read-Only History (Priority: P2)

Goal: Reuse one lifecycle decision for Generate pack, Regenerate, and Export executive pack while keeping current review, evidence, and already-generated pack consumption available under existing RBAC during suspension.

Independent Test: Switch a workspace with existing review history, evidence, and generated packs to suspended_read_only, verify that all in-scope start actions block before any new ReviewPack or OperationRun write occurs, and confirm that authorized actors can still view or download existing artifacts.

Tests for User Story 3

• T016 [P] [US3] Extend review-pack feature coverage for allowed trial/active_paid, warned-but-allowed grace starts, blocked suspended_read_only starts, no new ReviewPack or OperationRun writes, no queued or terminal notification on blocked starts, and already queued or running review-pack work remaining unaffected by later suspension in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/ReviewPack/ReviewPackEntitlementEnforcementTest.php and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/ReviewPack/ReviewPackGenerationTest.php
• T017 [P] [US3] Extend suspended read-only consumption coverage for customer review workspace access, current pack download, and evidence snapshot detail access in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/ReviewPack/ReviewPackDownloadTest.php, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php

Implementation for User Story 3

• T018 [US3] Enforce lifecycle gating before any new ReviewPack, OperationRun, or blocked-start notification path and reuse the existing blocked-decision transport instead of adding a second exception path while leaving already-created runs unaffected in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Services/ReviewPackService.php and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Exceptions/Entitlements/WorkspaceEntitlementBlockedException.php
• T019 [P] [US3] Project lifecycle allow/warn/block messaging onto the tenant dashboard and review register start surfaces in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Widgets/Tenant/TenantReviewPackCard.php and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/Reviews/ReviewRegister.php
• T020 [P] [US3] Gate Generate pack, Regenerate, and Export executive pack actions while keeping View and Download affordances unchanged in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/TenantReviewResource.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/ReviewPackResource.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/ReviewPackResource/Pages/ListReviewPacks.php, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/ReviewPackResource/Pages/ViewReviewPack.php
• T021 [US3] Preserve suspended read-only review history, evidence, and generated-pack consumption without widening into a broader suspension sweep in /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/ReviewPackResource/Pages/ViewReviewPack.php, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php

Checkpoint: User Story 3 is independently functional when all in-scope start actions share one lifecycle gate and suspended workspaces still retain safe read-only access to existing history and evidence.

---

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Run the narrow validation lanes, format touched files, and capture the feature-local close-out without widening scope.

• T022 Run the targeted unit Sail/Pest command from /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/plan.md and /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/quickstart.md against /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Unit/Entitlements/WorkspaceCommercialLifecycleResolverTest.php
• T023 Run the targeted system-plane and onboarding Sail/Pest command from /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/plan.md and /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/quickstart.md against /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/System/ViewWorkspaceEntitlementsTest.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/System/Spec113/AuthorizationSemanticsTest.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Onboarding/ManagedTenantOnboardingEntitlementTest.php, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Onboarding/OnboardingRbacSemanticsTest.php
• T024 Run the targeted review-pack, blocked-start no-notification, in-flight-boundary, and preserved-read-only Sail/Pest command from /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/plan.md and /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/quickstart.md against /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/ReviewPack/ReviewPackEntitlementEnforcementTest.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/ReviewPack/ReviewPackGenerationTest.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/ReviewPack/ReviewPackDownloadTest.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php, /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php
• T025 Run dirty-only Pint through Sail for touched platform files using the command recorded in /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/quickstart.md
• T026 Record the final guardrail close-out, lane results, workflow outcome (keep unless implementation proves otherwise), and any bounded document-in-feature or follow-up-spec note for blocked-decision transport or preserved read-only scope in /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/plan.md and /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/251-commercial-entitlements-billing-state/checklists/requirements.md

---

Dependencies & Execution Order

Phase Dependencies

• Phase 1 (Setup): starts immediately.
• Phase 2 (Foundational): depends on Phase 1 and blocks all user stories.
• Phase 3 (US1), Phase 4 (US2), and Phase 5 (US3): each depends on Phase 2 and is independently testable after the shared lifecycle setting and resolver primitives exist.
• Phase 6 (Polish): depends on all desired user stories being complete.

User Story Dependencies

• US1 (P1): first shippable increment once Phase 2 is complete.
• US2 (P1): independently testable after Phase 2 and should follow US1 in the main implementation loop because the system-plane lifecycle vocabulary and audit semantics become canonical there.
• US3 (P2): independently testable after Phase 2 and should merge after US1 because review-pack surfaces must reuse the same lifecycle vocabulary and blocked-decision transport.

Within Each User Story

• Write the listed Pest coverage first and make it fail for the intended gap before implementation.
• Complete the shared service or enforcement seam before wiring multiple UI entry points that depend on it.
• Re-run the narrowest relevant proof command after each story checkpoint before moving to the next story.

---

Parallel Opportunities

Phase 1

• T002 and T003 can run in parallel after T001 confirms the bounded slice.

Phase 2

• T004 and T005 can run in parallel.
• T006 should follow once the lifecycle setting keys and resolver shape exist.

User Story 1

• T007 and T008 can run in parallel.
• T009 can proceed before T010 and T011, but T010 and T011 should stay coordinated because both touch /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/System/Pages/Directory/ViewWorkspace.php.

User Story 2

• T012 can run in parallel with any remaining US1 validation once Phase 2 is complete.
• T013, T014, and T015 should stay sequential because they all tighten the same onboarding completion boundary.

User Story 3

• T016 and T017 can run in parallel.
• After T018 establishes the service-level gate, T019 and T020 can run in parallel.
• T021 should follow the shared start-gate work so preserved read-only semantics stay bounded to existing consumption surfaces.

---

Implementation Strategy

Suggested MVP Scope

• MVP = Phase 2 + User Story 1 + User Story 2. This is the smallest slice that creates canonical lifecycle truth, exposes the one platform-side mutation surface, and proves a real business-state consequence (grace / suspended_read_only onboarding activation gating) without yet widening into review-pack and preserved-history follow-up.

Incremental Delivery

1. Complete Phase 1 and Phase 2.
2. Deliver US1 and validate system-plane lifecycle mutation plus audit semantics.
3. Deliver US2 and validate onboarding business-state gating.
4. Deliver US3 and validate review-pack start blocking plus preserved suspended read-only history/evidence/download access.
5. Finish with Phase 6 validation, formatting, and feature-local close-out recording.