TenantAtlas/specs/262-lifecycle-governance-taxonomy/plan.md

# Implementation Plan: Workspace, Tenant & Managed Object Lifecycle Governance v1

**Branch**: `262-lifecycle-governance-taxonomy` | **Date**: 2026-05-01 | **Spec**: [spec.md](spec.md)
**Input**: Feature specification from [spec.md](spec.md)

## Summary

Prepare one taxonomy-first lifecycle governance package that converts the deferred lifecycle candidate into an implementation-ready standards and contract slice without reopening runtime deletion, purge, or provider-specific rollout work. The narrow implementation path is to codify six lifecycle dimensions, their authoritative repo sources, transition-governance rules, export/retention/restoreability preconditions, and explicit follow-up boundaries in one new product standard plus one machine-readable contract artifact.

Repo truth already provides the inputs this slice needs: tenant lifecycle and canonical-view semantics in `specs/143-tenant-lifecycle-operability-context-semantics`, workspace commercial lifecycle in `specs/251-commercial-entitlements-billing-state`, provider-missing policy truth in `specs/261-provider-missing-policy-visibility`, reversible archive / irreversible force-delete in `specs/091-backupschedule-retention-lifecycle`, and current runtime lifecycle evidence in `apps/platform/app/Models/Tenant.php`, `apps/platform/app/Models/Policy.php`, `apps/platform/app/Models/ReviewPack.php`, `apps/platform/app/Models/BackupSet.php`, `apps/platform/app/Models/RestoreRun.php`, `apps/platform/app/Console/Commands/PruneReviewPacksCommand.php`, and `apps/platform/config/tenantpilot.php`.

V1 therefore stays deliberately non-runtime: no new app behavior, no migration, no new lifecycle service, no delete or purge flow, no panel/provider work, and no asset changes. It is a standards-track contract that later runtime specs must cite.

## Technical Context

**Language/Version**: Markdown and YAML governance artifacts inside a PHP 8.4 / Laravel 12 repo  
**Primary Dependencies**: existing specs 143, 251, 261, 091; product standards workflow in `docs/product/standards/README.md`; current lifecycle-bearing runtime models and commands as source truth only  
**Storage**: none for product runtime; one standards document and one machine-readable contract artifact  
**Testing**: manual artifact review plus targeted repo-search validation  
**Validation Lanes**: N/A (docs/standards-only package)
**Target Platform**: repo standards and spec artifacts only  
**Project Type**: Laravel monorepo with documentation and standards track  
**Performance Goals**: N/A  
**Constraints**: no runtime behavior change, no new persistence, no reinterpretation of current lifecycle fields, no new panel/provider/assets, and no hidden follow-up implementation  
**Scale/Scope**: 1 new standards-track lifecycle contract, 6 lifecycle dimensions, 1 transition-governance matrix, 5 named follow-up slices, and bounded updates to candidate history

## Likely Affected Repo Surfaces

- `docs/product/standards/README.md` as the existing landing zone for shared standards.
- `docs/product/standards/lifecycle-governance.md` as the intended new standard for later implementation.
- `docs/product/spec-candidates.md` to record explicit promotion history for the deferred candidate.
- `specs/143-tenant-lifecycle-operability-context-semantics/spec.md` as the current tenant lifecycle authority.
- `specs/251-commercial-entitlements-billing-state/spec.md` as the current workspace commercial lifecycle authority.
- `specs/261-provider-missing-policy-visibility/spec.md` as the current provider-presence authority.
- `specs/091-backupschedule-retention-lifecycle/spec.md` as the current reversible archive / irreversible force-delete pattern authority.
- `apps/platform/app/Models/Tenant.php`, `apps/platform/app/Models/Policy.php`, `apps/platform/app/Models/ReviewPack.php`, `apps/platform/app/Models/BackupSet.php`, `apps/platform/app/Models/RestoreRun.php`, `apps/platform/app/Console/Commands/PruneReviewPacksCommand.php`, and `apps/platform/config/tenantpilot.php` as repo-real lifecycle inputs that the contract classifies but does not change.

## Lifecycle Taxonomy Fit

- Treat lifecycle governance as a standards contract, not as a runtime engine or umbrella service.
- Keep the six lifecycle dimensions orthogonal:
  - local record lifecycle
  - provider presence lifecycle
  - operator suppression lifecycle
  - commercial/workspace lifecycle
  - retention/compliance lifecycle
  - restoreability lifecycle
- For each dimension, distinguish:
  - current repo-real values and sources
  - reserved follow-up values that are named for future work but not yet repo-real
  - forbidden proxy meanings that later specs may not reuse locally
- Explicitly classify where current repo truth already exists versus where the taxonomy is defining a prerequisite for later runtime work.
- Treat `contracts/lifecycle-governance-taxonomy.yaml` as the canonical machine-readable lifecycle matrix for this package; supporting prose artifacts must mirror it.
- Classify `export requested` as a reserved retention/compliance value while keeping `Data Export Before Deletion v1` as the dedicated runtime follow-up that fulfills that state before irreversible deletion.

## Transition Governance Fit

- Build one transition matrix that answers, per lifecycle dimension:
  - who owns the transition
  - whether confirmation is required
  - whether audit evidence is required
  - whether shared `OperationRun` execution semantics are required
  - whether an `export requested` state or other export-before-delete / retention preconditions must be satisfied first
- Reuse current repo truth instead of inventing new action families:
  - direct audit-backed local mutation already proven by Spec 091
  - provider observation transitions already bounded by Spec 261
  - commercial-workspace gating already bounded by Spec 251
  - canonical-view legitimacy already bounded by Spec 143
- Do not let the matrix imply runtime behavior beyond those current boundaries.

## UI / Surface Guardrail Plan

- **Guardrail scope**: workflow-only guardrail change
- **Native vs custom classification summary**: N/A
- **Shared-family relevance**: status vocabulary, destructive-action naming, audit wording, retention wording, restoreability claims
- **State layers in scope**: none
- **Audience modes in scope**: N/A
- **Decision/diagnostic/raw hierarchy plan**: N/A
- **Raw/support gating plan**: N/A
- **One-primary-action / duplicate-truth control**: the package states lifecycle meaning once per dimension and forbids duplicate cross-dimension summaries
- **Handling modes by drift class or surface**: review-mandatory
- **Repository-signal treatment**: review-mandatory because this package sets a new cross-domain taxonomy
- **Special surface test profiles**: N/A
- **Required tests or manual smoke**: manual artifact review only
- **Exception path and spread control**: none; any runtime scope added here is out-of-scope drift
- **Active feature PR close-out entry**: Guardrail

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes
- **Systems touched**: lifecycle-bearing specs, product standards workflow, audit naming, and future destructive or retention-sensitive follow-up specs
- **Shared abstractions reused**: current specs, current standards workflow, `BadgeCatalog` / `BadgeRenderer`, `AuditLog`, and the shared OperationRun UX contract as referenced authorities only
- **New abstraction introduced? why?**: one governance contract only; no new runtime abstraction
- **Why the existing abstraction was sufficient or insufficient**: the repo already has enough bounded lifecycle slices, but not enough shared classification to stop future overlap
- **Bounded deviation / spread control**: none planned

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: yes, as a rule-setting artifact only
- **Central contract reused**: shared OperationRun UX contract remains authoritative
- **Delegated UX behaviors**: later lifecycle slices must delegate any queued, long-running, or remote destructive flow to the shared OperationRun path; this package does not add a new run type
- **Surface-owned behavior kept local**: later runtime surfaces remain responsible for their own initiation UI once the taxonomy tells them which safeguard path applies
- **Queued DB-notification policy**: unchanged
- **Terminal notification path**: unchanged
- **Exception path**: none

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: yes
- **Provider-owned seams**: provider proof of object presence, subtype filtering, and hard-deletion evidence
- **Platform-core seams**: archive versus delete semantics, suppression, retention, restoreability, commercial suspension, and audit/export preconditions
- **Neutral platform terms / contracts preserved**: `provider missing`, `archived`, `retained`, `purge due`, `restorable`, `metadata only`, `suspended read-only`
- **Retained provider-specific semantics and why**: provider-specific hard deletion remains reserved because the repo does not yet have a generalized proof path for it
- **Bounded extraction or follow-up path**: `follow-up-spec` for explicit provider-deleted semantics and broader managed-object rollout

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

- Inventory-first / snapshot truth: PASS. The package classifies current inventory, backup, and historical restore truths without redefining them.
- Read/write separation: PASS. No write path is introduced.
- Graph contract path: PASS. No new Graph family or provider behavior is introduced.
- Deterministic capabilities: PASS. No capability or role changes are introduced.
- Workspace and tenant isolation: PASS. Existing isolation rules remain referenced, not changed.
- RBAC-UX: PASS. Lifecycle state remains explicitly separate from authorization.
- Destructive confirmation standard: PASS. The package defines when later destructive work must require confirmation instead of implementing it now.
- Global search safety: PASS. No resource or search behavior changes are proposed.
- OperationRun / Ops-UX: PASS. The package only states when future lifecycle work must reuse the shared contract.
- Data minimization: PASS. No new runtime data or payload exposure is introduced.
- Test governance (TEST-GOV-001): PASS. The package leaves explicit validation and workflow outcomes despite being docs-only.
- Proportionality / no premature abstraction: PASS. One contract is the narrowest way to answer the deferred candidate questions.
- Persisted truth (PERSIST-001): PASS. No new product persistence.
- Behavioral state (STATE-001): PASS. The package classifies current and reserved states without implementing new runtime state machines.
- Provider boundary (PROV-001): PASS. Shared language stays provider-neutral.
- Filament / Laravel planning contract: PASS. Filament remains v5 on Livewire v4, provider registration remains in `apps/platform/bootstrap/providers.php`, no globally searchable resource behavior changes, and no asset work is planned.

**Gate evaluation**: PASS.

- The package remains valid only if implementation stays on the standards and contract path.
- The gate fails if runtime deletion, purge, panel, provider, or lifecycle-engine work appears in this slice.

**Post-design re-check**: PASS. `research.md`, `data-model.md`, `quickstart.md`, `contracts/lifecycle-governance-taxonomy.yaml`, and `checklists/requirements.md` are present and aligned with the package.

## Test Governance Check

- **Test purpose / classification by changed surface**: N/A - docs/standards package
- **Affected validation lanes**: N/A
- **Why this lane mix is the narrowest sufficient proof**: runtime proof is unnecessary because the slice changes no runtime behavior
- **Narrowest proving command(s)**:
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd /Users/ahmeddarrazi/Documents/projects/wt-plattform && rg -n -- "Workspace, Tenant & Managed Object Lifecycle Governance v1|Provider-Missing Managed Object Truth v1|Workspace & Tenant Closure Lifecycle v1|Data Export Before Deletion v1|Retention & Purge Governance v1|Restoreability Expiry & Evidence Retention v1" docs/product/spec-candidates.md specs/262-lifecycle-governance-taxonomy`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd /Users/ahmeddarrazi/Documents/projects/wt-plattform && rg -n -- "draft|onboarding|active|archived|ignored_at|missing_from_provider_at|suspended|expired|retention" apps/platform/app/Models/Tenant.php apps/platform/app/Models/Policy.php apps/platform/app/Models/ReviewPack.php apps/platform/app/Models/BackupSet.php apps/platform/app/Models/RestoreRun.php apps/platform/app/Console/Commands/PruneReviewPacksCommand.php apps/platform/config/tenantpilot.php specs/143-tenant-lifecycle-operability-context-semantics/spec.md specs/251-commercial-entitlements-billing-state/spec.md specs/261-provider-missing-policy-visibility/spec.md specs/091-backupschedule-retention-lifecycle/spec.md`
- **Fixture / helper / factory / seed / context cost risks**: none
- **Expensive defaults or shared helper growth introduced?**: no
- **Heavy-family additions, promotions, or visibility changes**: none
- **Surface-class relief / special coverage rule**: N/A
- **Closing validation and reviewer handoff**: reviewers must confirm the dimensions, authoritative sources, transition matrix, and follow-up boundaries stay aligned and non-runtime
- **Budget / baseline / trend follow-up**: none
- **Review-stop questions**: hidden runtime scope, future-state speculation, contradictory lifecycle meanings, missing transition safeguards, or missing follow-up boundaries
- **Escalation path**: `reject-or-split` if runtime work appears; `follow-up-spec` if a new lifecycle family is discovered later
- **Active feature PR close-out entry**: Guardrail
- **Why no dedicated follow-up spec is needed**: this package itself is the dedicated governance follow-up for lifecycle taxonomy; later runtime work remains separate

## Rollout & Risk Controls

- Keep the contract standards-first and implementation-light.
- Keep all reserved future values clearly marked as follow-up only.
- Keep runtime authorities with their existing specs and models.
- Keep promotion history explicit so the repo does not treat this candidate as still merely deferred.
- Keep lifecycle vocabulary neutral and avoid provider-shaped truth at shared boundaries.

## Close-Out Outcome

- **Review outcome**: Core Enterprise
- **Workflow outcome**: approve for implementation on the standards-and-contract path only
- **Test-governance outcome**: keep docs-only validation; no runtime lane expansion is required in this package

## Implementation Close-Out Outcome

- **Review outcome**: Core Enterprise
- **Workflow outcome**: implemented on the standards-and-contract path only
- **Test-governance outcome**: keep docs-only validation; no runtime lane expansion was introduced
- **Runtime impact**: none; no application code, migration, Filament surface, provider behavior, asset, queue, or browser-visible flow was changed

## Project Structure

### Documentation (this feature)

```text
specs/262-lifecycle-governance-taxonomy/
├── checklists/
│   └── requirements.md
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── lifecycle-governance-taxonomy.yaml
└── tasks.md
```

### Source Code And Standards Truth (repository root)

```text
docs/product/
├── spec-candidates.md
└── standards/
    ├── README.md
    └── lifecycle-governance.md          # planned by this feature

apps/platform/
├── app/
│   ├── Console/Commands/PruneReviewPacksCommand.php
│   └── Models/
│       ├── AuditLog.php
│       ├── BackupSet.php
│       ├── Policy.php
│       ├── RestoreRun.php
│       ├── ReviewPack.php
│       └── Tenant.php
└── config/
    └── tenantpilot.php

specs/
├── 091-backupschedule-retention-lifecycle/
├── 143-tenant-lifecycle-operability-context-semantics/
├── 251-commercial-entitlements-billing-state/
└── 261-provider-missing-policy-visibility/
```

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| Cross-domain lifecycle taxonomy | The deferred candidate explicitly requires one shared answer before destructive or retention-sensitive runtime work continues | Local per-feature fixes would preserve the ambiguity the candidate is trying to remove |

## Proportionality Review

- **Current operator problem**: future lifecycle work can still mislead operators by overloading fields or labels across tenant, workspace, provider presence, retention, and restoreability contexts
- **Existing structure is insufficient because**: current bounded specs each solve their local runtime problem but do not classify how their lifecycle meanings differ
- **Narrowest correct implementation**: add one standards document and one machine-readable contract that later runtime slices must cite
- **Ownership cost**: one shared vocabulary and one review step for lifecycle-bearing follow-up specs
- **Alternative intentionally rejected**: a runtime lifecycle framework or immediate archive/delete/closure implementation was rejected as broader than the deferred candidate allows
- **Release truth**: current-release truth only; the package classifies repo-real lifecycle signals and names reserved follow-up values without pretending that later runtime deletion, export, purge, or closure flows already exist