TenantAtlas/specs/292-workspace-tenant-closure/spec.md

# Feature Specification: Workspace & Tenant Closure Lifecycle v1

**Feature Branch**: `292-workspace-tenant-closure`  
**Created**: 2026-05-07  
**Status**: Approved for implementation  
**Input**: User description: "Promote the lifecycle taxonomy follow-through into one bounded runtime slice that closes workspaces, removes tenants from workspaces, and defines explicit suspended read-only versus closed behavior without introducing purge flows."

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

- **Problem**: TenantPilot already has partial lifecycle truth for tenant operability, archived workspaces, and subscription-driven suspended read-only posture, but it still has no explicit product truth for deliberately closing a workspace or removing a tenant from a workspace while preserving history.
- **Today's failure**: Operators can archive records or lose access implicitly through membership or context drift, but they cannot make an explicit, auditable closure decision. `archived`, `suspended read-only`, selector invalidation, and historical access are still separate behaviors rather than one bounded closure contract.
- **User-visible improvement**: Platform and workspace operators can close or reopen workspaces and remove or restore tenants with explicit confirmation, clear read-only behavior, consistent chooser recovery, and preserved historical viewers instead of relying on implicit 404s or overloaded archive semantics.
- **Smallest enterprise-capable version**: Add explicit closure truth on `Workspace`, explicit removed-from-workspace truth on `ManagedEnvironment`, reuse existing admin and system Filament surfaces, keep history readable, block new mutations and starts where required, and stop short of export, purge, or billing-provider workflows.
- **Explicit non-goals**: No hard delete, no purge engine, no export-before-delete flow, no retention executor, no customer self-serve billing portal, no payment-provider integration, no membership auto-deletion, no new panel, no new global-search resource, no broad lifecycle engine, and no reopening of the full Spec 262 taxonomy package.
- **Permanent complexity imported**: One bounded closure/removal truth on existing records, one bounded write orchestration path, explicit close/reopen and remove/restore action surfaces, chooser and context recovery rules, and focused audit plus feature-test coverage. No new standalone closure table or workflow engine is introduced.
- **Why now**: Spec 262 deliberately reserved `Workspace & Tenant Closure Lifecycle v1` as the next runtime follow-through after the taxonomy-first package, and the repo now has enough real substrate in tenant operability, commercial lifecycle, audit, and workspace context handling to implement it safely.
- **Why not local**: Closure and removal semantics affect workspace selection, tenant selection, tenant-bound routes, canonical run viewers, action gating, audit, and platform/admin surfaces together. A local page fix would preserve ambiguity and drift.
- **Approval class**: Core Enterprise
- **Red flags triggered**: New lifecycle truth, cross-plane UI impact, and destructive-like action semantics. Defense: the slice stays explicitly bounded, reuses existing surfaces and audit paths, adds no purge or export behavior, and resists a generic lifecycle framework.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 1 | Wiederverwendung: 2 | **Gesamt: 10/12**
- **Decision**: approve

## Spec Scope Fields *(mandatory)*

- **Scope**: workspace + tenant-bound + canonical-view
- **Primary Routes**:
  - `/system/directory/workspaces`
  - `/system/directory/workspaces/{workspace}`
  - `/system/directory/tenants/{tenant}`
  - `/system/ops/runs/{run}`
  - `/admin/workspaces`
  - `/admin/workspaces/{record}`
  - `/admin/choose-workspace`
  - `/admin/choose-tenant`
  - `/admin/settings/workspace`
  - existing tenant-management resource pages backed by `apps/platform/app/Filament/Resources/TenantResource.php`
  - existing tenant-context routes under `/admin/t/{tenant}/...`
- **Data Ownership**:
  - Workspace closure truth remains workspace-owned and lives on the existing `Workspace` record.
  - Tenant removal truth remains workspace-owned on the existing `ManagedEnvironment` record and does not create cross-workspace sharing.
  - Workspace memberships, tenant memberships, audit logs, evidence, review artifacts, and `OperationRun` history remain owned by their current records and are preserved in place.
  - This feature does not introduce new historical ledgers, export bundles, or purge artifacts.
- **RBAC**:
  - Authorization planes involved: platform `/system` for workspace close and reopen; admin `/admin` for workspace read-only visibility, chooser recovery, and tenant remove or restore within the current workspace.
  - Non-members or actors outside the relevant workspace or tenant scope receive deny-as-not-found (`404`).
  - Actors who are in scope but lack the required capability receive forbidden (`403`).
  - Canonical record viewers continue to authorize off record ownership and entitlement, not off remembered workspace or tenant context.

For canonical-view specs, the spec MUST define:

- **Default filter behavior when tenant-context is active**: Closed workspaces and removed tenants must never become the remembered active context. Canonical viewers may still render historically linked records when entitlement allows, even if the current remembered context was cleared.
- **Explicit entitlement checks preventing cross-tenant leakage**: Canonical viewers must validate workspace ownership of the record, referenced-tenant ownership where applicable, active actor entitlement to the workspace and referenced tenant, and route legitimacy independent of remembered selector state. Closed or removed lifecycle flags are product posture, not authorization shortcuts.

## 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)**: status messaging, badges, header actions, row or detail actions, chooser recovery messaging, canonical detail viewers, and audit-backed lifecycle copy
- **Systems touched**: `WorkspaceContext`, chooser pages, tenant operability, commercial lifecycle summaries, admin and system detail pages, audit logging, and canonical run or tenant viewers
- **Existing pattern(s) to extend**: `WorkspaceCommercialLifecycleResolver`, `TenantOperabilityService`, `BadgeCatalog` and `BadgeRenderer`, current audit-log infrastructure, current Filament action surfaces, and existing chooser or context-recovery flows
- **Shared contract / presenter / builder / renderer to reuse**: `WorkspaceContext`, `TenantOperabilityService`, `BadgeCatalog` and `BadgeRenderer`, `WorkspaceAuditLogger`, tenant audit logging, current Filament detail and table action patterns, and the current system-directory plus admin resource surfaces
- **Why the existing shared path is sufficient or insufficient**: The repo already has the shared chooser, audit, and status paths needed for bounded runtime delivery. What is missing is the explicit closure and removed-from-workspace truth those shared paths must consume.
- **Allowed deviation and why**: none. This feature must not create a parallel lifecycle language or a page-local closure vocabulary.
- **Consistency impact**: `Suspended read-only`, `Closed`, `Removed from workspace`, `Archived`, and `Provider missing` must remain distinct meanings with consistent badges, copy, and blocked-action explanations.
- **Review focus**: Reviewers must verify that workspace closure and tenant removal reuse the existing shared status, chooser, audit, and canonical viewer seams instead of introducing one-off page logic.

## 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, by lifecycle gating and canonical historical viewing only
- **Shared OperationRun UX contract/layer reused**: existing shared `OperationRun` start UX and current canonical monitoring surfaces remain authoritative
- **Delegated start/completion UX behaviors**: blocked starts in closed workspaces or removed-tenant contexts must happen before enqueue, create no new run, and keep current `View run` or canonical-detail links unchanged for already-existing history
- **Local surface-owned behavior that remains**: system and admin surfaces own only the close/reopen and remove/restore inputs plus the impact summary shown before confirmation
- **Queued DB-notification policy**: unchanged; this feature introduces no new queued notification family
- **Terminal notification path**: unchanged; no new `OperationRun` lifecycle is introduced
- **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 or platform boundary is broadened here. Workspace closure and tenant removal are workspace-owned lifecycle concerns and must not be modeled as provider state.

## 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 |
|---|---|---|---|---|---|---|
| System workspace detail close or reopen controls | yes | Native Filament | header actions, badges, audit-backed detail summaries | page, detail | no | n/a |
| Admin workspace detail read-only closure summary | yes | Native Filament | status messaging, summary sections | page, detail | no | n/a |
| Managed tenant list and detail remove or restore controls | yes | Native Filament | row/detail actions, badges, lifecycle explanations | page, detail | no | n/a |
| Workspace and tenant chooser recovery after closure or removal | yes | Native Filament + global context shell | navigation, shell recovery, selector messaging | shell, page | no | special shell handling only |
| Canonical run and tenant viewers for removed or closed history | yes | Native Filament | shared detail family, historical evidence visibility | detail | no | no new mutation surface |

## 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 |
|---|---|---|---|---|---|---|---|
| System workspace detail | Primary Decision Surface | Decide whether a workspace should be closed or reopened | Current posture, impact summary, closure reason, one dominant action | Audit history, affected tenant counts, related historical records | Primary because platform users make the closure decision here | Follows workspace governance, not storage internals | Removes guesswork about what closure changes and what remains readable |
| Managed tenant list and detail | Primary Decision Surface | Decide whether a tenant remains in the active workspace set | Tenant posture, removal impact, one dominant remove or restore action | Related memberships, historical runs, audit trail | Primary because workspace operators govern tenant presence here | Aligns to tenant-management workflow | Avoids overloading archive and implicit chooser disappearance |
| Admin workspace detail | Secondary Context Surface | Understand why the workspace is read-only or unavailable for active selection | Workspace posture, read-only explanation, next allowed inspection path | Closure reason, timestamps, linked history | Not primary because the admin plane does not own closure mutation | Supports post-decision inspection inside the workspace family | Keeps one clear explanation instead of repeating blockers across pages |
| Workspace and tenant chooser recovery | Secondary Context Surface | Recover from a cleared or invalid remembered context | Why the prior context is invalid and one next step | Optional timestamps or posture detail only if needed | Not primary because the user is recovering from an already-made decision | Follows operator recovery flow | Replaces silent redirects with one clear explanation |
| Canonical run and historical viewers | Tertiary Evidence / Diagnostics Surface | Inspect historical evidence after closure or removal | Historical record remains readable plus lifecycle badge on related workspace or tenant | Linked audit trail, tenant or workspace metadata | Not primary because the feature does not ask operators to decide here | Keeps evidence and history accessible without reopening active context | Prevents false not-found errors when context changed |

## 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 |
|---|---|---|---|---|---|---|---|
| System workspace detail | support-platform | Current posture, closure reason summary, impact, close or reopen action | Related tenant counts, membership posture, recent activity | Full audit events and internal IDs | `Close workspace` or `Reopen workspace` | Raw audit payloads and low-level IDs remain secondary | One top summary states the posture once; lower sections add evidence only |
| Managed tenant list and detail | operator-MSP, support-platform | Tenant posture, removal explanation, remove or restore action | Related memberships, lifecycle timestamps, affected history counts | Raw audit details and internal identifiers | `Remove tenant` or `Restore tenant` | Raw audit details stay secondary or support-only | The tenant posture chip and summary line are the single visible source of truth |
| Admin workspace detail | operator-MSP | Workspace posture and what remains readable | Commercial-state detail, closure timestamps, guidance to history surfaces | Platform-only internal detail stays hidden | `Review workspace history` | Platform-only internal detail stays hidden | Read-only explanation appears once in the summary region |
| Workspace and tenant chooser recovery | operator-MSP | Why the context was cleared and which chooser or page to use next | Minimal recovery detail only | None | `Choose workspace` or `Choose tenant` | Internal route or entitlement diagnostics stay hidden | Recovery page states the blocker once and points to one next action |
| Canonical run and historical viewers | operator-MSP, support-platform | Historical record remains readable and the related workspace or tenant posture | Linked workspace and tenant metadata, timestamps, linked audit | Raw identifiers and platform-only debug metadata | `Review history` | Raw metadata remains secondary | The record summary owns the lifecycle note so deeper sections do not restate it |

## 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 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| System workspace detail | Detail / Header Actions | Governance detail | Close or reopen workspace | Route-record detail | n/a | Secondary detail links stay inside sections | Detail header only with confirmation | `/system/directory/workspaces` | `/system/directory/workspaces/{workspace}` | Workspace identity, posture badge | Workspace | Open, suspended read-only, or closed posture plus impact | none |
| Admin workspace detail | Detail / Context Summary | Workspace management detail | Review closure posture and history | Route-record detail | n/a | Related links inside sections | none on admin plane for closure | `/admin/workspaces` | `/admin/workspaces/{record}` | Workspace identity, posture badge | Workspace | Read-only explanation and next allowed path | none |
| Managed tenant list | List / Table / More | Registry list | Inspect tenant and decide remove or restore | Full-row click | required | `More` for remove or restore and rare actions | `More` only | `/admin/tenants` | `/admin/tenants/{tenant}` | Workspace context, tenant posture | Tenant | Active versus removed posture | none |
| Managed tenant detail | Detail / Header Actions | Governance detail | Remove or restore tenant | Route-record detail | n/a | Secondary lifecycle links inside sections | Detail header or `More` with confirmation | `/admin/tenants` | `/admin/tenants/{tenant}` | Workspace identity, tenant posture | Tenant | Removed-from-workspace state and impact | none |
| Workspace and tenant chooser recovery | Shell / Recovery | Global-context shell | Recover to a valid current context | Single recovery card / chooser list | chooser row click only | None beyond recovery guidance | none | `/admin/choose-workspace` or `/admin/choose-tenant` | same as collection | Current workspace and tenant context validity | Workspace / Tenant | Why the previous context is invalid | global-context-shell |
| Canonical run and historical viewers | Detail / Evidence | Historical detail | Inspect history without reopening active context | Route-record detail | n/a | Secondary related links inside sections | none | `/system/ops/runs` or current historical collection | `/system/ops/runs/{run}` and related detail routes | Workspace or tenant posture badges | Run / Historical record | Historical legitimacy plus related lifecycle note | shared-detail-family |

## 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 |
|---|---|---|---|---|---|---|---|---|---|---|
| System workspace detail | Platform operator | Decide whether workspace should be closed or reopened | Governance detail | Should this workspace remain operable? | Workspace posture, closure reason, impact, what remains readable | Full audit trail, internal IDs, related history counts | commercial posture, closure posture | TenantPilot only | Close workspace, Reopen workspace | Close workspace |
| Admin workspace detail | Workspace owner or manager | Understand why current workspace is read-only or unavailable for active context | Workspace management detail | What does this posture change for my workspace work? | Workspace posture, read-only explanation, history access path | Timestamps and related summary counts | commercial posture, closure posture | None on this surface | Review workspace history | None |
| Managed tenant list and detail | Workspace owner | Decide whether tenant remains part of the workspace's active operating set | Governance list/detail | Should this tenant stay operable in this workspace? | Tenant posture, removal explanation, effect on selectors and actions | Membership and historical record details | tenant lifecycle, removed-from-workspace posture | TenantPilot only | Remove tenant, Restore tenant | Remove tenant |
| Workspace and tenant chooser recovery | Workspace member | Recover from invalid remembered context | Global-context shell | Which valid workspace or tenant should I use now? | Recovery explanation and one next chooser action | Minimal recovery detail only | context validity, closure or removal posture | None | Choose workspace, Choose tenant | None |
| Canonical run and historical viewers | Workspace operator or platform operator | Inspect history after closure or removal | Historical detail | Is this record still legitimate and what lifecycle posture does it reflect? | Record summary plus related workspace or tenant posture | Audit links and related metadata | record status, workspace or tenant posture | None | Review history | None |

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: yes - explicit workspace closed truth and explicit tenant removed-from-workspace truth on existing records
- **New persisted entity/table/artifact?**: yes - new persisted lifecycle fields on `Workspace` and `ManagedEnvironment`; no new standalone entity or table family beyond targeted columns
- **New abstraction?**: yes, one bounded write-orchestration service if needed for close/reopen and remove/restore audit-safe mutations; no generic lifecycle framework
- **New enum/state/reason family?**: yes - explicit closed and removed-from-workspace posture with audit reason text and derived blocked-action consequences
- **New cross-domain UI framework/taxonomy?**: no
- **Current operator problem**: the product cannot currently make a deliberate closure or removal decision without misusing archive semantics, implicit 404s, or commercial suspension language.
- **Existing structure is insufficient because**: `archived_at` on workspaces and the subscription resolver's suspended-read-only posture do not encode an explicit closure decision, and current tenant lifecycle does not cover workspace-specific removal while preserving history.
- **Narrowest correct implementation**: add bounded fields on existing records, derive read-only and selector behavior from those fields plus current commercial posture, reuse current surfaces, and keep mutations inside one bounded orchestration seam.
- **Ownership cost**: migration work, model and middleware touch points, Filament surface updates, audit-log additions, and focused feature-test maintenance.
- **Alternative intentionally rejected**: overloading archive or suspended-read-only semantics was rejected because it would preserve ambiguity; a generic lifecycle engine or new closure table was rejected because current-release truth only needs bounded fields and shared-surface reuse.
- **Release truth**: current-release truth

### Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, migration shims, historical alias states, and compatibility-specific tests are out of scope unless implementation reveals a concrete current-release blocker.

Canonical replacement of ambiguous archive or suspension meanings is preferred over preserving overloaded semantics.

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

- **Test purpose / classification**: Feature
- **Validation lane(s)**: fast-feedback, confidence
- **Why this classification and these lanes are sufficient**: The slice changes Filament surfaces, middleware or context recovery, audit-backed mutations, and canonical viewer legitimacy. Focused feature coverage is the narrowest honest proof because route, policy, and page behavior matter more than isolated unit indirection.
- **New or expanded test families**: focused feature coverage for system directory, admin workspace and tenant resources, chooser recovery, and canonical run or historical viewers
- **Fixture / helper cost impact**: moderate but bounded; test setup needs explicit workspace membership, tenant membership, commercial posture, and closure or removal state, but no new heavy provider or browser defaults
- **Heavy-family visibility / justification**: none; browser coverage is not required for the initial proof path
- **Special surface test profile**: standard-native-filament, global-context-shell, shared-detail-family
- **Standard-native relief or required special coverage**: functional-core plus state-contract coverage is required; browser or heavy-governance coverage is out of scope unless implementation proves a shell-only gap that feature tests cannot honestly prove
- **Reviewer handoff**: reviewers must verify that close/reopen and remove/restore remain confirmation-protected and audit-backed, that chooser recovery clears invalid context explicitly, that blocked start or mutate paths do not create runs, and that canonical historical viewers stay accessible when entitlement allows
- **Budget / baseline / trend impact**: none expected beyond one feature-local increase in admin and system feature coverage
- **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/Feature/System/Directory/ViewWorkspaceClosureTest.php tests/Feature/System/Ops/ClosedWorkspaceHistoricalAccessTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/Resources/Workspaces/WorkspaceClosureStatusTest.php tests/Feature/Filament/Resources/TenantResource/TenantWorkspaceRemovalTest.php tests/Feature/Filament/Pages/WorkspaceContextClosureRecoveryTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Close a workspace without losing history (Priority: P1)

As a platform operator, I need to close and later reopen a workspace explicitly, so that I can stop active operations and mutations while preserving readable history and audit evidence.

**Why this priority**: Workspace closure is the core enterprise-trust behavior missing from the current product. Without it, every related lifecycle action still depends on implicit archive or access loss.

**Independent Test**: Can be fully tested by closing a workspace from the system directory, confirming chooser and action gating update, verifying historical viewers remain readable for entitled actors, and reopening the workspace to restore normal operability.

**Acceptance Scenarios**:

1. **Given** a platform actor is authorized to govern a workspace, **When** the actor closes the workspace with confirmation and a reason, **Then** the workspace becomes non-selectable as current context, in-scope active mutations are blocked, and the closure decision is written to audit.
2. **Given** a workspace is closed, **When** an entitled actor opens a historical run or workspace detail viewer, **Then** the record remains readable with explicit closed posture and no false not-found error.
3. **Given** a workspace is closed, **When** the platform actor reopens it, **Then** the workspace becomes selectable again and existing memberships plus historical records remain intact.

---

### User Story 2 - Remove a tenant from a workspace without deleting tenant history (Priority: P1)

As a workspace owner, I need to remove and later restore a tenant from the active workspace set, so that the tenant stops appearing as an operable context without destroying its history, memberships, or canonical records.

**Why this priority**: Workspace operators need a bounded lifecycle action smaller than deletion and more explicit than archive or hidden selector disappearance.

**Independent Test**: Can be fully tested by removing a tenant from the tenant-management surface, confirming chooser and tenant-context routes stop treating it as operable, verifying canonical historical viewers still render, and restoring the tenant.

**Acceptance Scenarios**:

1. **Given** an owner is authorized for tenant governance, **When** the owner removes a tenant from the workspace with confirmation and a reason, **Then** the tenant no longer appears in choose-tenant or tenant-context start flows and the action is written to audit.
2. **Given** a tenant was removed from the workspace, **When** an entitled actor opens a canonical run or historical detail page that references that tenant, **Then** the record remains readable and the tenant is labeled removed from workspace.
3. **Given** a tenant is removed from the workspace, **When** the owner restores it, **Then** the tenant becomes selectable and operable again without recreating memberships or historical records.

---

### User Story 3 - Distinguish suspended read-only, closed, and removed clearly (Priority: P2)

As an operator, I need workspace and tenant posture to explain whether I am blocked because the workspace is commercially suspended, explicitly closed, or the tenant was removed from the workspace, so that I know what next action is legitimate.

**Why this priority**: Clear posture language prevents operators from treating commercial billing state, workspace closure, and tenant removal as the same event.

**Independent Test**: Can be fully tested by rendering admin and system surfaces plus chooser recovery for a suspended-read-only workspace, a closed workspace, and a removed tenant and confirming each posture has distinct copy, badge semantics, and blocked-action behavior.

**Acceptance Scenarios**:

1. **Given** a workspace is commercially suspended but not closed, **When** the actor opens admin or system summaries, **Then** the posture reads suspended read-only and not closed.
2. **Given** a workspace is closed, **When** the actor lands on chooser or current-context recovery surfaces, **Then** the UI explains that the prior workspace is closed and offers one valid next action instead of a silent redirect.
3. **Given** a tenant is removed from the workspace, **When** the actor visits tenant management or historical detail surfaces, **Then** the tenant is labeled removed from workspace and not archived or provider missing.

### Edge Cases

- A user lands on `/admin` with a remembered current workspace that was closed after the last session; the product must clear the invalid context and route through an explicit recovery path.
- A remembered current tenant was removed from the workspace while the workspace itself remains open; the tenant context must be cleared without breaking workspace-scoped pages.
- A workspace is already `SUSPENDED_READ_ONLY` from the commercial resolver and then becomes explicitly closed; the product must show both truths without collapsing them into one ambiguous blocker.
- A removed tenant or closed workspace is still referenced by `OperationRun`, audit, evidence, or review artifacts; canonical viewers must stay readable when entitlement allows.
- A workspace close or tenant removal action is attempted while a last-owner or active-membership guard would otherwise make the result unsafe; the feature must preserve current owner-guard behavior and surface a clear failure reason.
- A reopen or restore action is performed after the remembered context was cleared; the product must not silently reactivate old context without the chooser or explicit selection flow confirming it.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature introduces no Microsoft Graph calls. It does introduce destructive-like lifecycle mutations, so close/reopen and remove/restore must be previewed, confirmation-protected, audit-logged, authorization-checked server-side, and covered by focused tests. No purge or hard-delete behavior is allowed in this slice.

**Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001):** The feature adds bounded persisted lifecycle truth on existing records because current release truth now requires a deliberate closure posture distinct from archive and commercial suspension. A generic lifecycle engine, registry, or new closure history ledger is explicitly out of scope. The narrowest correct implementation is to add fields on existing records, derive blocking behavior from those fields plus current commercial posture, and keep write orchestration bounded.

**Constitution alignment (XCUT-001):** The feature reuses existing chooser, context, badge, audit, and canonical-viewer seams. It must not introduce page-local status vocabularies or a parallel action language for closure and removal.

**Constitution alignment (DECIDE-AUD-001 / OPSURF-001):** System workspace detail and managed tenant detail are the primary decision surfaces. Chooser recovery and historical viewers remain secondary or tertiary surfaces. Default-visible content must explain posture and one next action; deeper audit and raw identifiers stay secondary.

**Constitution alignment (PROV-001):** This slice is platform-core lifecycle work. Provider presence remains a separate lifecycle dimension from Spec 261 and must not be reused to model closure or removal.

**Constitution alignment (TEST-GOV-001):** Proof stays in focused feature coverage for native Filament surfaces, chooser recovery, and canonical viewers. No heavy-governance or browser lane should be introduced unless implementation reveals a shell-only gap that feature tests cannot honestly prove.

**Constitution alignment (OPS-UX):** The feature does not add a new `OperationRun` type. It does require that blocked starts in closed workspaces or removed-tenant contexts fail before enqueue and that existing canonical run viewers remain authoritative and readable when entitlement allows.

**Constitution alignment (OPS-UX-START-001):** Existing start surfaces continue to rely on the shared `OperationRun` start UX path when allowed. Close or remove posture only changes whether a start is permitted; it must not introduce local queued toast, dedupe, or notification semantics.

**Constitution alignment (RBAC-UX):** Platform and admin planes remain separated. Workspace non-members, tenant non-members, and wrong-plane actors get `404`; in-scope actors lacking capability get `403`. Destructive-like actions must use `->requiresConfirmation()` and server-side authorization. Closed or removed posture is never a substitute for an authorization decision.

**Constitution alignment (OPS-EX-AUTH-001):** This feature does not change auth-handshake behavior.

**Constitution alignment (BADGE-001):** Workspace and tenant posture badges must be centralized. `Suspended read-only`, `Closed`, and `Removed from workspace` must not fall back to ad hoc labels or local color choices.

**Constitution alignment (UI-FIL-001):** All changed admin and system surfaces remain native Filament pages or resources. No local card system, no ad hoc status-color system, and no fake row interactivity may be introduced. One dominant action per primary decision surface is required.

**Constitution alignment (UI-NAMING-001):** Primary operator-facing verbs are `Close workspace`, `Reopen workspace`, `Remove tenant`, and `Restore tenant`. `Workspace` and `Tenant` are the real target objects and must remain stable across buttons, modals, audit prose, and notifications.

**Constitution alignment (DECIDE-001):** This feature adds explicit human-in-the-loop lifecycle decisions. The default experience must become calmer and clearer by separating active context, read-only closure posture, and historical evidence rather than adding more ambiguous lifecycle states.

**Constitution alignment (UI-CONST-001 / UI-SURF-001 / ACTSURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001 / HDR-001):** Changed surfaces must preserve exactly one primary inspect/open model, keep destructive actions in header or `More`, avoid redundant view actions, and keep chooser recovery and historical viewers focused on one immediate question.

**Constitution alignment (ACTSURF-001 - action hierarchy):** Workspace close/reopen and tenant remove/restore must not compete with navigation. Primary decision surfaces keep one dominant action; rare or adjacent lifecycle actions stay grouped.

**Constitution alignment (OPSURF-001):** Every changed surface must show whether the blocker is commercial suspension, explicit closure, or tenant removal. Mutation scope must stay legible: all lifecycle mutations in this slice are TenantPilot-only and do not mutate Microsoft tenants.

**Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001):** The feature must map existing domain truth directly to UI posture without adding a new presentation taxonomy or semantic wrapper layer. Tests should prove user-facing business consequences and access behavior, not thin indirection.

**Constitution alignment (Filament Action Surfaces):** System workspace detail, admin workspace detail, managed tenant list and detail, chooser recovery, and any touched historical viewers must satisfy the action-surface contract described in the matrix below.

**Constitution alignment (UX-001 - Layout & Information Architecture):** Existing Filament layouts remain in force. Any added summary or warning content must fit current Main/Aside or detail-section layouts, keep one primary action, and preserve native empty-state and badge semantics.

### Functional Requirements

- **FR-001**: The system MUST model workspace closure as explicit product truth distinct from `archived_at` and distinct from commercial `SUSPENDED_READ_ONLY` posture.
- **FR-002**: Authorized platform actors MUST be able to close and reopen a workspace through an explicit confirmation flow that captures a human-readable reason and writes an audit event.
- **FR-003**: A closed workspace MUST stop being selectable as the current workspace in `/admin/choose-workspace` and MUST clear any remembered tenant context tied to that workspace.
- **FR-004**: A closed workspace MUST block the in-scope tenant start surface and the in-scope state-changing admin surfaces touched by this slice while preserving entitled read access to management and historical viewers.
- **FR-005**: The admin plane MUST show read-only closure posture for an affected workspace without exposing a second closure-mutation plane.
- **FR-006**: The system MUST model tenant removal from workspace as explicit product truth distinct from tenant archive and distinct from provider-missing lifecycle.
- **FR-007**: Authorized workspace actors MUST be able to remove and restore a tenant from the workspace through explicit confirmation flows that capture a reason and write audit events.
- **FR-008**: A removed tenant MUST stop being selectable in `/admin/choose-tenant` and MUST stop being a valid tenant-context route target under `/admin/t/{tenant}/...`.
- **FR-009**: A removed tenant MUST remain inspectable on tenant-management and canonical historical viewer surfaces when the actor remains entitled to the workspace and tenant history.
- **FR-010**: Canonical historical viewers in scope for this v1, specifically system run viewers and system workspace or tenant historical detail viewers, MUST remain viewable when they reference a closed workspace or removed tenant and entitlement still allows access.
- **FR-011**: The system MUST preserve existing workspace-membership and tenant-membership records during close/reopen and remove/restore flows in this v1 slice; no membership purge or recreation workflow is allowed.
- **FR-012**: The product MUST distinguish `Suspended read-only`, `Closed`, and `Removed from workspace` with separate badge semantics, copy, and blocked-action explanations.
- **FR-013**: Chooser and context-recovery surfaces MUST explain why a remembered context was cleared and MUST offer one valid next action rather than silently redirecting.
- **FR-014**: Authorization on affected surfaces MUST preserve `404` for non-members or wrong-plane actors and `403` for in-scope actors missing capability.
- **FR-015**: Lifecycle mutations in this feature MUST be labeled consistently as `Close workspace`, `Reopen workspace`, `Remove tenant`, and `Restore tenant` across buttons, modals, notifications, and audit prose.
- **FR-016**: Close/reopen and remove/restore actions MUST be TenantPilot-only mutations; no Microsoft tenant or provider mutation is performed in this slice.
- **FR-017**: Blocked starts caused by closed workspaces or removed tenants on the in-scope tenant start surface MUST not create `OperationRun` records, local blocked-run substitutes, or new notification families.
- **FR-018**: The feature MUST preserve current owner-guard and membership-safety behavior rather than bypassing it through lifecycle mutations.
- **FR-019**: This feature MUST not widen discovery: existing global-search and list entitlement rules remain unchanged, and no new discovery path may leak closed or removed records to actors who are not already entitled to inspect them.
- **FR-020**: The feature MUST not add purge, export-before-delete, retention execution, or billing-provider logic.

## UI Action Matrix *(mandatory when Filament is changed)*

If this feature adds or modifies any Filament Resource / RelationManager / Page, fill out the matrix below.

For each surface, list the exact action labels, whether they are destructive (confirmation? typed confirmation?), RBAC gating (capability + enforcement helper), whether the mutation writes an audit log, and any exemption or exception used.

| 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 |
|---|---|---|---|---|---|---|---|---|---|---|
| System workspace detail | `apps/platform/app/Filament/System/Pages/Directory/ViewWorkspace.php` | `Close workspace` or `Reopen workspace` | Route-record detail | none | none | n/a | `Close workspace` or `Reopen workspace` | n/a | yes | Platform capability only; confirmation required; no second control plane on `/admin` |
| Admin workspace detail | `apps/platform/app/Filament/Resources/Workspaces/Pages/ViewWorkspace.php` | none added in this slice | Route-record detail | none | none | n/a | none for closure on admin plane | Save/cancel unchanged where edit already exists | no direct mutation | Read-only summary only |
| Managed tenant list | `apps/platform/app/Filament/Resources/TenantResource.php` list page | none beyond current list controls | Full-row click to tenant detail | current safe shortcuts only; `Remove tenant` or `Restore tenant` lives in `More` | none in this slice | existing tenant-creation CTA stays unchanged | n/a | n/a | yes for remove/restore | Destructive-like action grouped to `More` |
| Managed tenant detail | `apps/platform/app/Filament/Resources/TenantResource.php` view page | `Remove tenant` or `Restore tenant` plus existing safe navigation | Route-record detail | none | none | n/a | `Remove tenant` or `Restore tenant` | Save/cancel unchanged where edit already exists | yes | Owner or equivalent capability only; confirmation required |
| Workspace chooser | `apps/platform/app/Filament/Pages/ChooseWorkspace.php` | none | chooser row or card select | `Choose workspace` | none | existing empty-state CTA only if no valid workspace exists | n/a | n/a | no | Closed workspaces excluded from selectable set |
| Tenant chooser | `apps/platform/app/Filament/Pages/ChooseTenant.php` | none | chooser row or card select | `Choose tenant` for active tenants only | none | existing empty-state CTA only if no valid tenant exists | n/a | n/a | no | Removed tenants excluded from selectable set |

### Key Entities *(include if feature involves data)*

- **Workspace closure truth**: Explicit lifecycle posture on `Workspace` that marks a workspace as closed or reopened and records the reason and actor without deleting the workspace.
- **Tenant removal truth**: Explicit lifecycle posture on `ManagedEnvironment` that marks a tenant as removed from the active workspace set or restored without deleting the tenant record.
- **Remembered workspace and tenant context**: Convenience selection state that must be cleared when closure or removal makes it invalid.
- **Canonical historical viewer in scope**: Existing system run viewers plus system workspace and tenant detail viewers that remain readable even when active context becomes invalid.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: In validation scenarios, 100% of close/reopen and remove/restore actions show explicit posture and impact summary with no ambiguous fallback to `Archived`.
- **SC-002**: In validation scenarios, 0 closed workspaces and 0 removed tenants appear as selectable choices in the normal workspace and tenant choosers.
- **SC-003**: In validation scenarios, 100% of entitled system run viewers and in-scope system historical detail viewers remain accessible when they reference a closed workspace or removed tenant.
- **SC-004**: In validation scenarios, 100% of blocked actions explain whether the blocker is `Suspended read-only`, `Closed`, or `Removed from workspace`.
- **SC-005**: In validation scenarios, 100% of lifecycle mutations covered by this slice write audit events that include actor, prior state, new state, timestamp, and reason.

## Summary

Workspace closure and tenant removal are the next runtime follow-through after the lifecycle taxonomy foundation from Spec 262. The feature does not attempt deletion, purge, or export. It introduces one explicit workspace-level closure truth, one explicit tenant removed-from-workspace truth, and the minimum surface, chooser, and canonical-view behavior needed to make those truths operable and auditable.

The key product distinction is that commercial suspension, explicit workspace closure, tenant removal from workspace, tenant archive, and provider-missing lifecycle are not the same thing. This feature productizes the first two missing runtime decisions without reopening the broader lifecycle package.

## Goals

- Let platform users close and reopen workspaces deliberately and auditably.
- Let workspace owners remove and restore tenants from the active workspace set without deleting history.
- Make chooser, context-recovery, and canonical-view behavior explicit when closure or removal invalidates active context.
- Keep suspended read-only posture distinct from explicit closure and tenant removal.
- Reuse current Filament, audit, chooser, and canonical-view seams rather than introducing a new lifecycle framework.

## Non-Goals

- No purge, export-before-delete, or retention-execution workflow.
- No hard delete or membership-deletion cascade.
- No payment-provider or billing-portal work.
- No reopening of broader provider lifecycle or retention taxonomy work.
- No new panel, global-search resource, or custom UI system.

## Assumptions

- `WorkspaceCommercialLifecycleResolver` remains the source of commercial suspension truth and is not replaced by closure logic.
- Workspace memberships and tenant memberships remain the entitlement backbone even when a workspace is closed or a tenant is removed.
- Existing canonical historical viewers already have legitimate workspace identity and can keep rendering when lifecycle posture changes.
- Close/reopen and remove/restore are TenantPilot-only mutations in this v1.

## Risks

- Closure and removal could be mistakenly folded into existing archive semantics if the implementation does not keep badges, copy, and blocked-action explanations distinct.
- Chooser recovery could regress into silent redirects if the feature does not explicitly handle cleared context.
- Canonical historical viewers could accidentally inherit active-context requirements and start returning false not-found errors.
- The slice could widen into purge, export, or billing-provider logic unless the follow-up boundaries stay explicit.

## Follow-Up Work

- Export-before-delete and retention/purge governance remain separate follow-up specs.
- Any future customer self-service offboarding or billing-driven closure workflow remains a separate commercial or portal slice.
- Broader lifecycle alignment for other governed objects remains outside this workspace and tenant closure follow-through.

## Final Direction

The intended runtime contract is: a suspended workspace stays readable but commercially blocked, a closed workspace becomes non-selectable and read-only for entitled actors, and a removed tenant stops being an active workspace context without losing historical legitimacy. The implementation should add only the truth and behavior needed to make those distinctions real.