TenantAtlas/specs/247-plans-entitlements-billing-readiness/spec.md

Feature Specification: Plans, Entitlements & Billing Readiness

Feature Branch: 247-plans-entitlements-billing-readiness
Created: 2026-04-27
Status: Draft
Input: User description: "Update the existing candidate as a workspace-first entitlement foundation. Keep the candidate title recognizable, but scope the first slice to one workspace-owned plan profile, explicit entitlement overrides with rationale, operator-visible decision truth, and first enforcement on managed-tenant onboarding activation plus review-pack generation. Reuse existing workspace settings, capability registries, onboarding, review-pack, and system-directory surfaces. Do not assume checkout, invoices, payment providers, proration, or a separate customer-account domain."

Spec Candidate Check (mandatory - SPEC-GATE-001)

• Problem: TenantPilot has no product-owned workspace truth for what a workspace is commercially allowed to do, so plan availability and limit decisions live in founder memory, ad hoc support explanations, or scattered future guesses instead of one auditable runtime decision path.
• Today's failure: Authorized operators can reach activation or review-pack entry points without any product-side entitlement explanation, while the product cannot truthfully answer why a feature is unavailable, whether a workspace is over its allowed managed-tenant count, or which manual override currently applies.
• User-visible improvement: Workspace admins can set one plan profile and explicit override values once, and operators then see a calm but truthful allow-or-block reason directly on onboarding activation, review-pack generation, and system support views.
• Smallest enterprise-capable version: Extend the existing workspace settings foundation with one workspace plan profile, two first-slice entitlement keys, explicit workspace override values with rationale, one derived entitlement resolver, read-only system visibility, and server-enforced checks on managed-tenant onboarding activation plus review-pack generation.
• Explicit non-goals: No customer-account domain, no subscription lifecycle engine, no invoices, no checkout, no payment provider integration, no proration, no public pricing surface, no trial/grace/suspension workflow, no seat or report-retention matrix, no tenant/user/export/deletion entitlement spread beyond the two first-slice checks, and no platform-wide backoffice billing framework.
• Permanent complexity imported: One bounded plan-profile catalog, one bounded first-slice entitlement key catalog, one derived entitlement decision/resolution layer, one new entitlement section on the existing workspace settings page, one read-only system summary, and focused unit plus feature coverage.
• Why now: This candidate is upstream of customer lifecycle communication, demo and trial readiness, and broader commercial readiness. Adjacent self-service and support candidates are already specced, and they need a truthful entitlement source before later commercial workflows can remain narrow.
• Why not local: The same commercial truth must drive workspace settings, onboarding activation, review-pack generation, and system operator visibility. Local conditionals on each surface would drift immediately and recreate the current manual explanation problem.
• Approval class: Core Enterprise
• Red flags triggered: New semantic axis, foundation-sounding theme, and multi-surface touchpoint. Defense: this slice is explicitly limited to existing workspace settings, two entitlement keys, two runtime enforcement points, and one read-only system summary. It does not introduce a customer-account model, payment flow, or broad plan matrix.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: workspace
• Primary Routes:
  • /admin/settings/workspace on App\Filament\Pages\Settings\WorkspaceSettings
  • /admin/onboarding/{onboardingDraft} on App\Filament\Pages\Workspaces\ManagedTenantOnboardingWizard
  • /admin/reviews on App\Filament\Pages\Reviews\ReviewRegister
  • existing review-pack generation entry surfaces on the tenant dashboard, tenant review detail pages, and review-pack registry/detail surfaces backed by App\Services\ReviewPackService
  • /system/directory/workspaces/{workspace} on App\Filament\System\Pages\Directory\ViewWorkspace
• Data Ownership: Current-release entitlement truth is workspace-owned and stored through existing WorkspaceSetting records plus code-owned plan-profile defaults. Managed-tenant counts, review-pack runs, and existing artifacts remain derived from current workspace and tenant truth. No new billing/account/customer-subscription table is introduced.
• RBAC: Workspace membership remains the isolation boundary for /admin. Capabilities::WORKSPACE_SETTINGS_VIEW and Capabilities::WORKSPACE_SETTINGS_MANAGE govern configuration visibility and mutation. Capabilities::WORKSPACE_MANAGED_TENANT_ONBOARD_ACTIVATE and Capabilities::REVIEW_PACK_MANAGE remain the execution capabilities on the first enforcement surfaces. PlatformCapabilities::DIRECTORY_VIEW governs read-only system visibility. Non-members and wrong-plane actors receive 404. Members missing capability receive 403. Members with capability but without entitlement receive a truthful business-state block rather than a hidden surface or false 403.

For canonical-view specs, the spec MUST define:

• Default filter behavior when tenant-context is active: N/A - this slice is workspace-owned and does not introduce a tenantless cross-tenant collection that filters tenant records.
• Explicit entitlement checks preventing cross-tenant leakage: N/A - existing tenant access rules remain authoritative. The new workspace entitlement truth never reveals tenant-owned records outside the current workspace or platform directory visibility.

Cross-Cutting / Shared Pattern Reuse (mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write N/A - no shared interaction family touched)

• Cross-cutting feature?: yes
• Interaction class(es): configuration settings, status messaging, action gating/helper text, review-pack start UX, read-only system diagnostics
• Systems touched: WorkspaceSetting, SettingsResolver, SettingsWriter, workspace audit logging, canonical capability registries, managed-tenant onboarding activation, review-pack generation entry surfaces, and the system directory workspace detail view
• Existing pattern(s) to extend: existing workspace settings update/reset + audit pattern, existing capability-gated Filament actions, existing review-pack queued-start UX, and existing system directory detail summaries
• Shared contract / presenter / builder / renderer to reuse: App\Services\Settings\SettingsResolver, App\Services\Settings\SettingsWriter, App\Services\Audit\WorkspaceAuditLogger, App\Support\Auth\Capabilities, App\Support\Auth\PlatformCapabilities, App\Support\OpsUx\OperationUxPresenter, and App\Support\OperationRunLinks; one new bounded WorkspaceEntitlementResolver (or equivalently named resolver) is introduced because there is no existing shared commercial-decision path
• Why the existing shared path is sufficient or insufficient: The existing settings stack is already sufficient for workspace-owned persistence, validation, and audit. It is insufficient for runtime commercial truth because multiple surfaces need the same resolved plan-default versus override decision, source attribution, and usage context without duplicating business rules.
• Allowed deviation and why: none. The feature must not create page-local entitlement checks, local billing copy, or a second support-facing commercial summary.
• Consistency impact: Plan profile labels, entitlement source labels, blocked copy, override rationale labels, and current-usage summaries must mean the same thing on workspace settings, onboarding activation, review-pack generation, and the system directory page.
• Review focus: Reviewers must verify that the same resolved decision object drives all first-slice surfaces, that no surface invents its own commercial vocabulary, and that existing review-pack operation UX remains unchanged when entitlement allows execution.

OperationRun UX Impact (mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an OperationRun; otherwise write N/A - no OperationRun start or link semantics touched)

• Touches OperationRun start/completion/link UX?: yes
• Shared OperationRun UX contract/layer reused: Existing review-pack generation continues to use App\Services\ReviewPackService, App\Support\OpsUx\OperationUxPresenter, and App\Support\OperationRunLinks. Managed-tenant onboarding activation remains a confirmed, audited page mutation and does not introduce a new OperationRun.
• Delegated start/completion UX behaviors: When review-pack generation is entitled, queued toast, Open operation link, dedupe handling, browser event dispatch, and terminal lifecycle notifications stay on the existing shared path. When generation is not entitled, no run is created and no queued or terminal notification is emitted.
• Local surface-owned behavior that remains: Workspace settings save and reset actions, onboarding completion helper text and callouts, and blocked reason presentation on review-pack entry surfaces remain surface-owned.
• Queued DB-notification policy: unchanged. The feature adds no new queued DB notification behavior and no new review-pack run type.
• Terminal notification path: central lifecycle mechanism for existing review-pack generation only
• Exception required?: none

Provider Boundary / Platform Core Check (mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write N/A - no shared provider/platform boundary touched)

N/A - no shared provider/platform boundary touched. The new plan and entitlement vocabulary is platform-core and must remain provider-neutral even when it gates provider-backed review-pack generation.

UI / Surface Guardrail Impact (mandatory when operator-facing surfaces are changed; otherwise write N/A)

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Workspace settings entitlement section	yes	Native Filament + existing singleton settings page	settings, status messaging, helper text	page, section, resolved settings summary	no	Extends the existing singleton page instead of creating a new admin surface
Managed tenant onboarding completion gate	yes	Native Filament wizard + existing completion action	action gating, callouts, helper text	wizard step, confirmation action	no	Reuses the existing completion step and keeps onboarding calm
Review-pack generation entry family	yes	Native Filament widget/resource actions	operation start gating, helper text, queued-start UX	widget action, detail action, list/header action	no	One entitlement decision must cover all current Generate pack, Regenerate, and Export executive pack entry points
System directory workspace entitlement summary	yes	Native Filament system detail page	read-only diagnostics, support/commercial visibility	detail section/card	no	Read-only only in the first slice

Decision-First Surface Role (mandatory when operator-facing surfaces are changed)

Surface	Decision Role	Human-in-the-loop Moment	Immediately Visible for First Decision	On-Demand Detail / Evidence	Why This Is Primary or Why Not	Workflow Alignment	Attention-load Reduction
Workspace settings entitlement section	Primary Decision Surface	Workspace owner or manager decides what this workspace is commercially allowed to do	Current plan profile, effective entitlements, source, rationale, and current usage summary	Audit attribution and related affected surfaces	Primary because this is the one configuration point that changes later runtime behavior	Configuration first, enforcement second	Removes ad hoc founder-only plan decisions and scattered explanations
Managed tenant onboarding completion gate	Primary Decision Surface	Operator decides whether the tenant may be activated now	Activation eligibility, current active managed-tenant usage versus allowed limit, and the one next action	Existing verification and bootstrap diagnostics remain secondary	Primary because onboarding completion is the actual high-impact decision point for tenant activation	Keeps commercial truth inside the onboarding workflow instead of forcing cross-page lookup	Prevents silent failure or false calmness at the moment of activation
Review-pack generation entry family	Secondary Context Surface	Operator decides whether to start or retry review-pack generation from the current tenant or review context	Allow-or-block state, source, and the next step when blocked	Existing operation detail, review-pack status, and artifact truth stay secondary	Not primary because the surface exists to continue reporting/review workflows, not to manage commercial posture	Stays inside the existing reporting workflow	Avoids back-and-forth to support or settings just to understand why generation is blocked
System directory workspace entitlement summary	Tertiary Evidence / Diagnostics Surface	Platform operator or support user verifies what entitlement truth is active for a workspace	Resolved plan profile, effective entitlement values, source, and last changed attribution	Existing tenant counts, recent runs, and admin workspace link stay supporting context	Not primary because system operators inspect rather than change commercial posture in this slice	Supports support and escalation workflows without adding a second mutation plane	Avoids separate manual lookup across admin pages, audit logs, and founder memory

Audience-Aware Disclosure (mandatory when operator-facing surfaces are changed)

Surface	Audience Modes In Scope	Decision-First Default-Visible Content	Operator Diagnostics	Support / Raw Evidence	One Dominant Next Action	Hidden / Gated By Default	Duplicate-Truth Prevention
Workspace settings entitlement section	operator-MSP	Plan profile, two first-slice entitlements, current usage, source, and saveable override inputs	Last modified attribution and reset state	none	Save	Any future billing/account metadata and broader commercial lifecycle fields stay out of scope	The same resolved values shown here are reused on downstream surfaces instead of reworded locally
Managed tenant onboarding completion gate	operator-MSP	Activation eligibility, active managed-tenant count, limit source, and concise blocked reason	Verification and operability detail already present on the wizard	none	Complete onboarding or a clear blocked explanation when unavailable	Broader commercial configuration stays off the onboarding page	The onboarding step shows only the one commercial fact needed for activation and does not restate full settings data
Review-pack generation entry family	operator-MSP	Review-pack generation availability, source, and the next step when blocked	Existing queued/run state and artifact status remain secondary	none	The in-context start action: Generate pack, Regenerate, or Export executive pack when allowed	Full workspace plan configuration stays off these surfaces	The same entitlement reason object is rendered consistently across the widget, Review Register, tenant review detail, and review-pack resource actions
System directory workspace entitlement summary	support-platform	Read-only plan profile, effective entitlement values, source, and last changed attribution	Tenant counts, recent runs, and admin workspace link	none	Open admin workspace	Mutation controls and raw settings payload stay hidden in the system plane	The system page mirrors resolved truth only and does not become a second editable source

UI/UX Surface Classification (mandatory when operator-facing surfaces are changed)

Surface	Action Surface Class	Surface Type	Likely Next Operator Action	Primary Inspect/Open Model	Row Click	Secondary Actions Placement	Destructive Actions Placement	Canonical Collection Route	Canonical Detail Route	Scope Signals	Canonical Noun	Critical Truth Visible by Default	Exception Type / Justification
Workspace settings entitlement section	Config / Settings / Singleton	Workspace configuration page	Save or reset an entitlement-related setting	In-page settings section	forbidden	Per-field reset actions and helper text stay inside the section	None beyond confirmed reset of overrides if added	/admin/settings/workspace	/admin/settings/workspace	Active workspace context	Plan profile / Entitlements	Effective values, source, rationale, and usage	Singleton-settings exception already exists and remains bounded
Managed tenant onboarding completion gate	Workflow / Guided action entry	Onboarding completion step	Complete onboarding or stop because the workspace is over limit	In-page completion section	forbidden	Back-navigation and linked-tenant navigation stay secondary	Existing Cancel draft and Delete draft header actions remain destructive and confirmation-protected	/admin/onboarding	/admin/onboarding/{onboardingDraft}	Workspace context plus linked tenant identity	Onboarding entitlement	Activation eligibility and current limit usage	Guided-workflow exception remains valid
Review-pack generation entry family	Contextual action family	Tenant widget plus Review Register, tenant review detail, and tenant-scoped review-pack registry/detail actions	Start or retry review-pack generation when allowed	Explicit action on the current tenant or review context	mixed - forbidden on widget/detail actions, existing clickable row remains on the registry	Existing View and Download actions remain secondary and outside the entitlement gate; Generate pack, Regenerate, and Export executive pack are the only in-scope gated actions	Existing expire or similar destructive actions remain where the current resource contract places them	current tenant dashboard, /admin/reviews, tenant review detail, and tenant review-pack registry	current tenant dashboard, tenant review detail, and tenant review-pack registry/view	Active workspace, active tenant, and current review or review-pack context	Review pack generation entitlement	Allowed or blocked state and why	Grouped-action family exception documented here to avoid divergent gating
System directory workspace entitlement summary	System / Detail / Diagnostics	Read-only workspace detail page	Inspect current workspace commercial truth	Dedicated workspace detail page	forbidden	Existing admin-workspace and runs links stay secondary	none	/system/directory/workspaces	/system/directory/workspaces/{workspace}	Platform workspace identity and tenant count	Workspace entitlement summary	Effective plan profile, source, and last change attribution	Read-only system diagnostic surface

Operator Surface Contract (mandatory when operator-facing surfaces are changed)

Surface	Primary Persona	Decision / Operator Action Supported	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
Workspace settings entitlement section	Workspace owner or manager	Set or clear the workspace commercial posture for the first slice	Singleton settings page	What is this workspace allowed to do, and do I need to override the default?	Current plan profile, managed-tenant activation limit, review-pack generation availability, source, rationale, and current usage	Last modified attribution and reset availability	commercial profile, entitlement source, current usage	TenantPilot only	Save, Reset override	none
Managed tenant onboarding completion gate	Workspace owner completing managed tenant onboarding	Decide whether onboarding may be completed now	Guided workflow step	Can I activate this managed tenant under the current workspace entitlements?	Active managed-tenant usage, allowed limit, source, blocked reason, and existing completion prerequisites	Existing verification/operability diagnostics	onboarding readiness, entitlement eligibility	TenantPilot only for completion state; Microsoft tenant only for existing provider actions already on the page	Complete onboarding	Cancel draft, Delete draft
Review-pack generation entry family	Workspace manager or reporting operator	Decide whether to start or retry review-pack generation	Widget/action family	Can I start Generate pack, Regenerate, or Export executive pack from this workspace under the current entitlements?	Review-pack generation availability, source, and blocked reason	Existing run state, artifact truth, and review status; View and Download stay outside the entitlement decision	entitlement availability, run state, artifact status	TenantPilot only until the existing generation flow starts; then existing review-pack run semantics apply	Generate pack, Export executive pack, Regenerate	Existing destructive actions remain unchanged and out of scope
System directory workspace entitlement summary	Platform support or operations user	Verify workspace commercial truth without switching planes	Read-only detail page	What plan and overrides are currently in effect for this workspace?	Resolved plan profile, entitlement values, source, and last changed attribution	Recent runs, tenant counts, and admin workspace link	commercial profile, entitlement source	none	Open admin workspace	none

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: yes - workspace-owned plan profile and explicit entitlement override truth become current-release business truth, but they are stored in the existing workspace settings mechanism rather than a new table
• New persisted entity/table/artifact?: no
• New abstraction?: yes - one bounded resolver for effective entitlement decisions across multiple surfaces
• New enum/state/reason family?: yes - one bounded plan-profile identifier set, one bounded first-slice entitlement key catalog, and a small entitlement source vocabulary
• New cross-domain UI framework/taxonomy?: no
• Current operator problem: Operators and support users cannot truthfully explain whether a workspace is allowed to activate more managed tenants or generate review packs, and the product currently has no auditable commercial decision path.
• Existing structure is insufficient because: Generic settings storage alone does not provide a consistent runtime decision path, source attribution, usage context, or blocked-action explanation across onboarding, reporting, and system support surfaces.
• Narrowest correct implementation: Keep persistence inside existing workspace settings, limit the catalog to two entitlement keys, derive current usage from existing workspace and artifact truth, add one bounded resolver, and gate only two existing runtime actions in the first slice.
• Ownership cost: One new resolver and small catalog need ongoing tests and vocabulary review. One settings section and one system summary need ongoing UX discipline. No new tables, background workflows, or billing-provider seams are introduced.
• Alternative intentionally rejected: A new Plan, Subscription, or CustomerAccount model family was rejected because the repo has no current account or payment domain, and the first slice only needs workspace-owned runtime entitlement truth.
• Release truth: current-release truth with explicit follow-up candidates for later billing lifecycle work

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec.

Canonical replacement is preferred over preservation.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Unit, Feature
• Validation lane(s): fast-feedback, confidence
• Why this classification and these lanes are sufficient: Unit coverage proves plan-profile defaults, override merging, source attribution, and current-usage calculation. Focused feature coverage proves the existing Filament settings page, onboarding completion gate, review-pack generation gate, and system directory visibility without adding browser or heavy-governance scope.
• New or expanded test families: one new Entitlements unit family plus focused feature coverage for workspace settings, onboarding, review-pack generation, and system-directory visibility
• Fixture / helper cost impact: Add only workspace, membership, active managed-tenant, review-pack-capable tenant/review, and platform-user fixtures required to prove the first-slice decisions. Avoid new browser harnesses, payment-provider mocks, or broad commercial seeds.
• Heavy-family visibility / justification: none
• Special surface test profile: standard-native-filament, monitoring-state-page, shared-detail-family
• Standard-native relief or required special coverage: Standard Filament feature coverage is sufficient for the workspace settings page and onboarding wizard. Review-pack gating also needs monitoring-state assertions to prove that blocked attempts do not create a run, while the system directory page needs one read-only platform-plane detail assertion.
• Reviewer handoff: Reviewers must confirm that entitlement denials are distinct from 404 and 403 RBAC outcomes, blocked review-pack actions never create an OperationRun, lowered limits do not mutate existing tenants or packs, and the same reason text is reused across all first-slice surfaces.
• Budget / baseline / trend impact: low feature-local increase only
• Escalation needed: none
• Active feature PR close-out entry: Guardrail
• Planned validation commands:
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Entitlements/WorkspaceEntitlementResolverTest.php tests/Unit/Entitlements/WorkspacePlanProfileCatalogTest.php
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/Settings/WorkspaceEntitlementsSettingsPageTest.php tests/Feature/Onboarding/ManagedTenantOnboardingEntitlementTest.php
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPacks/ReviewPackEntitlementEnforcementTest.php tests/Feature/System/Directory/ViewWorkspaceEntitlementsTest.php

Scope Boundaries (required for this slice)

In Scope

• One workspace-owned plan profile selected and audited through the existing workspace settings surface
• Exactly two first-slice entitlement keys:
  • active managed-tenant activation limit for onboarding completion
  • review-pack generation availability for existing Generate pack, Regenerate, and Export executive pack entry points
• Explicit workspace override values for those keys with operator-entered rationale and reset-to-default behavior
• One derived effective entitlement decision path showing value, source, rationale, and current usage where applicable
• Read-only system-plane visibility of the resolved workspace commercial truth on the existing workspace directory page

Non-Goals

• Trial, grace, suspension, cancellation, or renewal lifecycle states
• Checkout, invoices, payment collection, taxes, proration, or billing-provider adapters
• A separate customer account, subscription, contract, or offer domain model
• Broader entitlement spread across seats, exports, retention, user counts, support SLAs, or feature flags
• Platform-plane mutation or emergency override controls in the first slice
• Customer-facing plan self-service or website pricing integration

Assumptions

• Existing WorkspaceSetting, SettingsResolver, and SettingsWriter are sufficient persistence and audit primitives for the current-release commercial truth.
• The first slice may use a small code-owned plan-profile catalog because there is no existing billing or account model to import from.
• Managed-tenant activation limit is measured against the current workspace's active managed tenants and blocks future activation only; it does not retroactively deactivate existing tenants.
• Review-pack generation entitlement governs new Generate pack, Regenerate, and Export executive pack attempts only; existing View and Download access to already-generated artifacts continues to follow current artifact and capability rules.

Risks

• Plan-profile naming can become prematurely productized if the catalog expands beyond the two first-slice entitlements.
• Partial gating would be misleading if one review-pack entry point enforces entitlement while another bypasses it.
• Lowering a managed-tenant limit below current usage creates an over-limit workspace that must be explained carefully so operators are not misled into expecting retroactive enforcement.
• Support users could misread the system view as a second source of truth if the admin and system surfaces drift in wording or source labels.

Follow-up Candidates

• Customer lifecycle communication driven by plan and entitlement state
• Demo and trial readiness built on top of the same workspace commercial truth
• Broader entitlement keys for exports, retention, seats, and support-plan limits
• External billing, subscription, or contract integration once a real account domain exists

User Scenarios & Testing (mandatory)

User Story 1 - Configure workspace commercial truth in one place (Priority: P1)

As a workspace owner or manager, I want to set the workspace plan profile and any first-slice overrides on the existing workspace settings page so later runtime behavior is predictable and attributable.

Why this priority: The first slice fails immediately if the product cannot define one authoritative workspace entitlement posture before runtime enforcement begins.

Independent Test: Open the existing workspace settings page, save a plan profile and one override with rationale, then verify that the resolved values, source, and current usage summary update without touching any onboarding or reporting surface.

Acceptance Scenarios:

1. Given a workspace manager can access workspace settings, When they save a plan profile with no overrides, Then the page shows the resolved first-slice entitlements from that profile and records the change through the existing workspace-setting audit path.
2. Given a workspace manager sets an explicit override for one entitlement, When they save the change with rationale, Then the resolved source changes to workspace override and the rationale is visible on the page.
3. Given a workspace manager resets an override, When the reset completes, Then the effective value returns to the plan-profile default and the reset is attributable in audit history.

---

User Story 2 - Truthfully gate managed-tenant activation (Priority: P1)

As an authorized onboarding operator, I want the final onboarding step to tell me whether the workspace may activate another managed tenant and why, so I do not complete onboarding under a false assumption.

Why this priority: Managed-tenant activation is the highest-risk first-slice lifecycle mutation. It needs a truthful commercial gate before later trial or lifecycle specs build on top of it.

Independent Test: Seed workspaces under limit, at limit, and over limit, open the existing onboarding completion step, and verify that the same action is allowed or blocked with the right reason before any tenant activation mutation occurs.

Acceptance Scenarios:

1. Given a workspace is within its allowed managed-tenant limit and the actor has onboarding activation capability, When they reach the existing completion step, Then the step shows the current limit usage and allows completion.
2. Given a workspace is at or above its allowed managed-tenant limit, When the same actor reaches the completion step, Then the action remains visible but blocked with a truthful explanation and no tenant activation occurs.
3. Given the workspace has an explicit override that increases the allowed limit, When the actor reaches the completion step, Then the action uses the override value and labels the source accordingly.

---

User Story 3 - Truthfully gate review-pack generation and expose the reason to support (Priority: P2)

As a reporting operator or platform support user, I want review-pack generation to use the same entitlement decision everywhere and be inspectable from the system directory so I can explain blocked behavior without guesswork.

Why this priority: Review-pack generation is an existing shared product workflow with several entry points. If it is not gated consistently, the product will immediately create conflicting commercial behavior.

Independent Test: Seed a workspace where review-pack generation is disabled, attempt generation from current tenant or review surfaces, confirm no new run is created, and then verify the same resolved reason on the read-only system workspace page.

Acceptance Scenarios:

1. Given review-pack generation is enabled for a workspace and the actor has review_pack.manage, When they start generation from an existing entry surface, Then the existing queued review-pack flow continues unchanged.
2. Given review-pack generation is disabled for that workspace, When the same actor attempts generation or regeneration from any current entry surface, Then the action is blocked before any OperationRun or ReviewPack is created and the reason matches the workspace entitlement decision.
3. Given a platform user with platform.directory.view opens the system workspace detail page, When they inspect the workspace entitlement summary, Then they can see the resolved plan profile, source, effective values, and last changed attribution without changing the admin-plane truth.

Edge Cases

• A workspace with no explicit plan profile override must still resolve deterministically from the system default plan profile so operators never see an unset commercial state.
• Lowering the managed-tenant limit below the workspace's current active count must not deactivate existing tenants; it only blocks future onboarding activation and must show the workspace as over limit.
• Disabling review-pack generation must not remove access to already-generated review packs, downloads, or run history that remain allowed under existing artifact permissions.
• If review-pack generation is already queued and the workspace later becomes not entitled, existing runs may complete, but new Generate pack, Regenerate, or Export executive pack attempts must block from that point forward.
• A user who is a workspace member but lacks workspace_settings.manage, workspace_managed_tenant.onboard.activate, or review_pack.manage must still receive 403 for those actions even when the workspace itself is entitled.
• A non-member or wrong-plane actor must not learn whether a workspace is over limit or review-pack generation is disabled; those requests continue to resolve as 404.

Requirements (mandatory)

Constitution alignment (required): This feature adds runtime-changing workspace-owned product truth and mutating settings writes, but it does not add Microsoft Graph calls, new provider dispatch, or a new queued workflow family. Workspace plan-profile and override changes use the existing workspace-setting audit path. Review-pack generation continues to rely on the existing OperationRun-backed flow only when entitlement allows the action.

Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001): The feature introduces new workspace-owned commercial truth and one bounded resolver because current-release operator workflows need one consistent decision across settings, onboarding, reporting, and system support. A narrower approach would still scatter plan logic across surfaces. The feature deliberately avoids a new table, customer-account model, or billing lifecycle state machine.

Constitution alignment (XCUT-001): All first-slice surfaces must use the same effective entitlement decision object for value, source, rationale, and current usage. No surface may invent local blocked copy or local plan semantics.

Constitution alignment (DECIDE-AUD-001 / OPSURF-001): Settings and action surfaces must show only the one commercial fact needed for the current decision. Support or audit detail remains secondary. No surface may present a neutral or success-like state when the workspace is actually blocked by entitlement or limit usage.

Constitution alignment (PROV-001): Plan profile, entitlement, override, and current-usage vocabulary remain platform-neutral. The feature must not introduce provider-shaped plan keys or account semantics.

Constitution alignment (TEST-GOV-001): Proof stays in focused unit plus feature lanes. New fixtures remain local to workspace, tenant, review-pack, and platform-directory contexts. No browser or heavy-governance family is justified for this slice.

Constitution alignment (OPS-UX): The feature does not add a new run family. Existing review-pack generation keeps the current queued toast, progress, and terminal notification path. Blocked review-pack attempts must not create a run, and therefore must not emit run lifecycle notifications.

Constitution alignment (OPS-UX-START-001): Review-pack generation entry surfaces continue delegating queued-start UX and canonical links to the shared review-pack and operation-run path. The new entitlement gate must sit before run creation rather than replacing that shared path.

Constitution alignment (RBAC-UX): Two authorization planes are involved: tenant/admin /admin and system /system. Wrong-plane or non-member access remains 404. Members missing capability remain 403. Entitlement denial for an otherwise authorized actor is a product-state block, not a membership failure. Existing destructive-like actions such as onboarding draft cancellation and deletion remain confirmation-protected. Any new override reset action must also use explicit confirmation if it materially changes runtime access.

Constitution alignment (BADGE-001): If the slice introduces status or source badges for entitlement state, those semantics must be centralized and reused across admin and system views rather than implemented with page-local color logic.

Constitution alignment (UI-FIL-001): The first slice extends existing native Filament pages, widgets, actions, sections, callouts, and detail views. No custom backoffice shell or local billing panel is allowed.

Constitution alignment (UI-NAMING-001): Primary operator labels must stay product-facing and specific: Plan profile, Managed tenant limit, Review pack generation, Override reason, Complete onboarding, Generate pack, and Open admin workspace. Terms such as subscription, checkout, invoice, proration, or Stripe must not appear.

Constitution alignment (DECIDE-001): Workspace settings remains the one primary commercial decision surface. Onboarding and review-pack surfaces remain contextual decision points that show only the commercial truth needed for the action at hand. The system directory page remains read-only evidence.

Constitution alignment (UI-CONST-001 / UI-SURF-001 / ACTSURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001 / HDR-001): The feature must preserve the existing singleton settings, guided workflow, grouped review-pack actions, and read-only system detail patterns. It may not add redundant inspect actions, shadow settings routes, or mixed action groups that hide the blocked reason.

Constitution alignment (ACTSURF-001 - action hierarchy): Settings mutation stays on the workspace settings page. Onboarding completion remains the primary action at the completion step. Review-pack generation remains the primary reporting action where already present. Navigation and diagnostics stay secondary.

Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001): One thin decision layer is justified because direct reads from raw settings would still force each surface to rebuild merge rules, source attribution, and current usage. Tests must target business outcomes such as allowed versus blocked execution and correct source labeling, not cosmetic rendering alone.

Constitution alignment (Filament Action Surfaces): The action-surface contract remains satisfied with documented existing exceptions for the singleton settings page and onboarding wizard. The review-pack generation entry family must keep the existing Generate pack, Regenerate, and Export executive pack start actions in scope, leave existing View and Download affordances outside the entitlement gate, and must not add redundant inspect affordances or placeholder action groups.

Constitution alignment (UX-001 - Layout & Information Architecture): The settings changes stay inside the existing sectioned workspace settings page. Onboarding and review-pack surfaces keep the current layout and only add bounded decision truth. The system directory page remains a detail/information surface rather than a second settings panel.

Functional Requirements

• FR-247-001 Workspace-owned truth: The system MUST represent first-slice commercial truth at workspace scope by storing one selected plan profile and optional explicit workspace overrides through the existing workspace settings infrastructure instead of introducing a new billing or customer-account persistence model.
• FR-247-002 First-slice entitlement catalog: The first slice MUST resolve exactly two entitlement keys: active managed-tenant activation limit and review-pack generation availability. No other entitlement family is required in this spec.
• FR-247-003 Effective decision shape: The system MUST derive an effective decision for each first-slice entitlement that includes the effective value, source, operator-visible rationale, and current usage when the entitlement is limit-based.
• FR-247-004 Plan profile defaults: The system MUST provide a bounded, code-owned plan-profile catalog whose defaults drive the two first-slice entitlement keys. The catalog is a product configuration artifact, not a customer contract or payment record.
• FR-247-005 Explicit overrides: Authorized workspace managers MUST be able to set or reset explicit override values for each first-slice entitlement together with rationale, and the resulting change MUST be attributable through the existing workspace-setting audit path.
• FR-247-006 Workspace settings visibility: The existing workspace settings page MUST show the current plan profile, effective first-slice entitlements, source labels, rationale, and current usage summary after save without requiring the operator to inspect code, logs, or system pages.
• FR-247-007 Managed-tenant activation enforcement: The existing onboarding completion action MUST consult the active managed-tenant entitlement decision before activation. If the workspace is over limit, the action MUST remain visible to otherwise authorized actors, explain why completion is blocked, and stop before tenant activation mutates runtime state.
• FR-247-008 Review-pack generation enforcement: All current Generate pack, Regenerate, and Export executive pack entry points MUST consult the same review-pack entitlement decision before creating or reusing a ReviewPack or OperationRun. If blocked, the action MUST stop before any run or artifact is created.
• FR-247-009 Existing artifact access unchanged: Disabling review-pack generation MUST NOT revoke view or download access to existing review packs that remain accessible under current artifact permissions.
• FR-247-010 Over-limit behavior: Lowering a managed-tenant limit below current active usage MUST mark the workspace as over limit for future activation attempts, but MUST NOT deactivate or archive existing tenants.
• FR-247-011 System-plane visibility: The existing system directory workspace page MUST show a read-only summary of the resolved plan profile, effective first-slice entitlements, source labels, and last changed attribution to platform users with platform.directory.view.
• FR-247-012 Entitlement versus RBAC semantics: Non-members and wrong-plane actors MUST continue to receive 404. Members missing the relevant capability MUST receive 403. Actors who are otherwise authorized but whose workspace is not entitled MUST receive a truthful product-state block and no silent bypass.
• FR-247-013 No hidden commercial platform: The first slice MUST NOT introduce checkout, invoices, payment collection, proration, trial/grace/suspension lifecycle state, customer-account records, or any external billing-provider seam.

UI Action Matrix (mandatory when Filament is changed)

Surface	Location	Header Actions	Inspect Affordance (List/Table)	Row Actions (max 2 visible)	Bulk Actions (grouped)	Empty-State CTA(s)	View Header Actions	Create/Edit Save+Cancel	Audit log?	Notes / Exemptions
Workspace settings entitlement section	app/Filament/Pages/Settings/WorkspaceSettings.php	Save	N/A - singleton settings page	none	none	N/A	N/A	Save; per-setting Reset actions for plan profile and overrides	yes - existing workspace-setting update/reset audit path	Existing singleton-page exemption remains valid
Managed tenant onboarding completion gate	app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php	Back to workspace, Back to onboarding, View tenant, existing Cancel draft, existing Delete draft	N/A - guided workflow	none	none	existing onboarding start state remains unchanged	same header actions apply on the route-bound page	Complete onboarding remains confirmation-protected and now also entitlement-gated	yes - existing onboarding audit semantics remain	Existing wizard exception remains valid
Review-pack generation entry family	app/Filament/Widgets/Tenant/TenantReviewPackCard.php, app/Filament/Pages/Reviews/ReviewRegister.php, app/Filament/Resources/TenantReviewResource.php, app/Filament/Resources/ReviewPackResource.php	current Generate pack, Regenerate, or Export executive pack entry actions stay primary	Existing clickable row remains only on the review-pack registry	existing Download remains the only direct row shortcut on the registry and stays outside the entitlement gate	none	existing Generate CTA remains on empty states where already present	existing Download and Regenerate header actions stay in place; only Generate pack, Regenerate, and Export executive pack are gated	N/A - action family, not a create/edit form	existing review-pack generation behavior unchanged; no new entitlement-block audit required	Grouped action family documented here so all in-scope start actions share one gate while View and Download remain unaffected
System directory workspace entitlement summary	app/Filament/System/Pages/Directory/ViewWorkspace.php	none	dedicated page route only	none	none	N/A	existing admin-workspace and runs links remain secondary navigation	N/A	no new audit action; read-only visibility only	Read-only system detail surface

Key Entities (include if feature involves data)

• Workspace Plan Profile: A bounded workspace-owned plan identifier that maps to the two first-slice entitlement defaults. It is not a subscription, contract, invoice, or customer account.
• Workspace Entitlement Override: An explicit workspace-scoped override value for one first-slice entitlement key together with operator rationale and audit attribution, persisted through the existing workspace settings stack.
• Effective Entitlement Decision: A derived runtime decision containing effective value, source, rationale, and current usage summary, reused by settings, onboarding, review-pack, and system visibility surfaces.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Authorized workspace managers can set or reset the first-slice commercial posture from one workspace settings page and see the resolved values, source, and current usage immediately after saving.
• SC-002: Authorized operators can determine from the onboarding completion step or a review-pack entry surface in under 30 seconds whether the action is allowed, blocked by plan profile, or blocked by current limit usage, without opening logs or asking support.
• SC-003: 100% of first-slice blocked executions stop before tenant activation or review-pack run creation and show a truthful reason instead of silently hiding the action or implying success.
• SC-004: Platform operators with read-only directory access can inspect the effective workspace plan profile, entitlement source, and last changed attribution from one system detail page without switching to a second source of truth.