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

Quickstart: Commercial Entitlements and Billing-State Maturity

Date: 2026-04-28
Branch: 251-commercial-entitlements-billing-state

This quickstart is the intended reviewer flow after implementation. It stays bounded to the commercial lifecycle overlay described in the spec.

Prerequisites

1. Start the local platform stack.
   • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail up -d
2. Ensure one platform user has directory visibility plus the dedicated commercial lifecycle management capability.
3. Ensure one workspace member can complete onboarding, one reporting operator can manage review packs, and one customer-safe or operator read-only actor can open review/evidence/download surfaces under current RBAC.
4. Seed or factory-create:
   • one workspace with untouched lifecycle state
   • one onboarding draft in that workspace
   • one tenant with an existing review, evidence snapshot, and generated review pack
   • one workspace already at or above the managed-tenant activation limit for substrate-block verification

Scenario 1: Change workspace commercial state from the system plane

1. Open /system/directory/workspaces/{workspace} as the authorized platform user.
2. Confirm the page shows:
   • current lifecycle state
   • source label
   • rationale and last-changed attribution
   • affected behavior summary for onboarding and review-pack starts
   • the underlying entitlement substrate summary for context
3. Use Change commercial state to move the workspace to trial with rationale.
4. Confirm the page updates immediately and the change is attributable.
5. Repeat with grace, suspended_read_only, and active_paid.
6. Confirm every explicit state change requires rationale, including a return to active_paid, and that the Suspended / read-only path also requires explicit confirmation.

Scenario 2: Gate onboarding activation with business-state truth

1. Open /admin/onboarding/{onboardingDraft} for a workspace in trial or active_paid.
2. Confirm the completion step allows Complete onboarding when the underlying entitlement substrate also allows it.
3. Switch the same workspace to grace from the system plane.
4. Refresh the onboarding draft and confirm:
   • the action remains visible for an otherwise authorized actor
   • the step explains that expansion is frozen during grace
   • no tenant activation occurs
5. Repeat with suspended_read_only and confirm the block message changes to read-only suspension semantics instead of a permission failure.

Scenario 3: Gate review-pack starts before any run is created

1. Use a workspace in trial or active_paid where the underlying review-pack entitlement allows generation.
2. Trigger the current start family from:
   • tenant dashboard review-pack card
   • review register export action
   • tenant review detail export action
   • review-pack detail regenerate action
3. Confirm the existing queued-start UX remains unchanged when allowed.
4. Move the workspace to grace.
5. Confirm review-pack starts remain allowed with a grace warning.
6. Start one allowed review-pack action and leave the resulting work queued or running.
7. Move the workspace to suspended_read_only.
8. Confirm the already-created run remains visible and continues with the existing run UX.
9. Repeat the same start actions and confirm:
   • each surface shows the same lifecycle-based reason
   • no new ReviewPack row is created
   • no new OperationRun row is created
   • no queued or terminal review-pack notification is emitted for the blocked attempt

Scenario 4: Preserve read-only review, evidence, and generated-pack access while suspended

1. Keep the workspace in suspended_read_only.
2. Open the current read-only consumption surfaces as an already-authorized actor:
   • CustomerReviewWorkspace
   • tenant review detail
   • review-pack detail
   • evidence snapshot detail
   • current review-pack download link
3. Confirm:
   • the pages still render
   • already-generated review packs remain downloadable
   • existing review/evidence history remains visible
   • any read-only explanation stays calm and does not masquerade as 403 or 404
4. Confirm the slice does not add broad new suspension behavior to unrelated mutable controls outside the spec boundary.

RBAC and Plane Semantics Checks

1. Access lifecycle mutation from /admin and confirm there is no self-service control surface.
2. Access /system/directory/workspaces/{workspace} as a platform user lacking the dedicated lifecycle capability and confirm authorization is enforced without leaking admin-plane truth.
3. Access onboarding or review-pack surfaces as a non-member or wrong-plane actor and confirm 404.
4. Access the same surfaces as an established-scope actor lacking the relevant capability and confirm 403.
5. Access the action as an otherwise authorized actor whose workspace lifecycle blocks the action and confirm a truthful business-state block instead of 403 or 404.

Targeted Validation Commands

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Entitlements/WorkspaceCommercialLifecycleResolverTest.php

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/System/ViewWorkspaceEntitlementsTest.php tests/Feature/System/Spec113/AuthorizationSemanticsTest.php tests/Feature/Onboarding/ManagedTenantOnboardingEntitlementTest.php tests/Feature/Onboarding/OnboardingRbacSemanticsTest.php

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPack/ReviewPackEntitlementEnforcementTest.php tests/Feature/ReviewPack/ReviewPackGenerationTest.php tests/Feature/ReviewPack/ReviewPackDownloadTest.php tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php tests/Feature/Evidence/EvidenceSnapshotResourceTest.php

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

Out of Scope Confirmations

While validating this slice, confirm that the implementation does not add or imply:

• payment-provider credentials, invoices, checkout, taxes, or public pricing UI
• customer-account, subscription, or contract models
• automated expiry/reminder/renewal logic
• a second admin-plane commercial settings surface
• a broad suspension engine across unrelated mutable product surfaces