# Lifecycle Governance Standard

> Canonical taxonomy for lifecycle-sensitive TenantPilot work.
> This standard governs naming, source ownership, transition safeguards, and follow-up boundaries before runtime lifecycle flows are implemented.

**Last reviewed**: 2026-05-01

---

## Governing Principle

**Lifecycle meanings stay orthogonal.**
Do not reuse one lifecycle field, label, badge, or status as a proxy for another lifecycle dimension.
The machine-readable source for Spec 262 is `specs/262-lifecycle-governance-taxonomy/contracts/lifecycle-governance-taxonomy.yaml`; this document is the reviewer-facing standard that future lifecycle specs must cite.

This v1 standard introduces no application behavior, migration, lifecycle service, provider rollout, panel surface, or purge/delete/export runtime flow.

---

## Canonical Dimensions

Every lifecycle concern must map to exactly one primary dimension.

| Dimension | Answers | Current repo-real authorities | Current repo-real values | Reserved follow-up values | Must not proxy |
|---|---|---|---|---|---|
| Local record lifecycle | Is a TenantPilot-owned record active, onboarding, archived, removed, or purged locally? | `specs/143-tenant-lifecycle-operability-context-semantics/spec.md`, `specs/091-backupschedule-retention-lifecycle/spec.md`, `apps/platform/app/Models/Tenant.php` | `tenant.draft`, `tenant.onboarding`, `tenant.active`, `tenant.archived`, `backup_schedule.active`, `backup_schedule.archived`, `backup_schedule.force_deleted` | `locally_removed`, `local_purge_scheduled`, `locally_purged` | Provider presence, commercial state, retention expiry |
| Provider presence lifecycle | Is a managed object observed in the supported provider-backed result set? | `specs/261-provider-missing-policy-visibility/spec.md`, `apps/platform/app/Models/Policy.php` | `present`, `provider_missing` | `provider_deleted`, `provider_reappeared` | Local deletion, local suppression, restoreability |
| Operator suppression lifecycle | Did an operator intentionally hide or restore local visibility? | `specs/261-provider-missing-policy-visibility/spec.md`, `apps/platform/app/Models/Policy.php` | `visible`, `ignored`, `restored_to_visibility` | `scoped_suppression_reason_families` | Provider missing, retention, commercial state |
| Commercial/workspace lifecycle | What commercial posture controls workspace expansion and read-only behavior? | `specs/251-commercial-entitlements-billing-state/spec.md` | `trial`, `active_paid`, `grace`, `suspended_read_only` | `closed` | Tenant archive, provider missing, purge due |
| Retention/compliance lifecycle | What must be retained, exported, held, deleted, or purged? | `apps/platform/app/Models/ReviewPack.php`, `apps/platform/app/Console/Commands/PruneReviewPacksCommand.php`, `apps/platform/config/tenantpilot.php` | `review_pack.expired`, `configured_retention_days` | `retained`, `export_requested`, `deletion_requested`, `deletion_scheduled`, `legal_hold`, `purge_due`, `purged` | Workspace suspension, local archive, provider missing |
| Restoreability lifecycle | Is historical backup or evidence truth still restorable? | `specs/261-provider-missing-policy-visibility/spec.md`, `apps/platform/app/Models/BackupSet.php`, `apps/platform/app/Models/RestoreRun.php` | `historical_restore_continuity_available` | `metadata_only`, `blocked_by_dependency`, `not_restorable`, `expired_by_retention` | Provider presence, commercial state, local suppression |

Rules:

- Use current repo-real values only when the repo already owns that meaning.
- Use reserved follow-up values only to name later specs; do not render, persist, or enforce them in this slice.
- If a concern seems to belong to multiple dimensions, choose the dimension that owns the operator consequence and document the secondary relationship as context only.

---

## Mandatory Meaning Answers

### Deleted

`Deleted` is not a shared lifecycle state.
Local removal, provider hard deletion, retention purge, and reduced restoreability are separate lifecycle meanings.

- Local deletion belongs to local record lifecycle and requires an explicit runtime follow-up before it can exist beyond current archive/force-delete patterns.
- Provider hard deletion belongs to provider presence lifecycle and remains provider-owned evidence.
- Purge belongs to retention/compliance lifecycle.
- Not restorable belongs to restoreability lifecycle.

### Missing From Provider

`Provider missing` means the managed object is not observed in the supported provider-backed result set.
It does not mean the local record was deleted, ignored, purged, or no longer historically restorable.

### Ignored

`Ignored` means intentional local operator suppression.
It does not mean the provider object disappeared, the workspace is suspended, or the record is retention-expired.

### Workspace Suspension Or Closure

`Suspended read-only` is commercial/workspace lifecycle.
It does not delete tenants, purge data, expire evidence, or eliminate restoreability.
`Closed` is reserved for `Workspace & Tenant Closure Lifecycle v1`; this standard only names the boundary.

### Export Before Deletion

`export_requested` is a reserved retention/compliance lifecycle value.
The actual export workflow, export contents, customer ownership, and completion proof belong to `Data Export Before Deletion v1`.

### Retained Versus Purgeable

Retained, legal hold, purge due, and purged are retention/compliance lifecycle meanings.
They must not be inferred from workspace suspension, local archive, provider missing, or restoreability status.

### Restore Eligibility

Restoreability is about whether historical backup or evidence truth remains restorable.
It remains distinct from current provider presence: a live provider object can be missing while a historical backup remains restorable, and a present provider object does not prove historical restoreability.

---

## Transition Governance

Future runtime specs must use this matrix before implementing a lifecycle transition.

| Dimension | Example transition | Transition owner | Execution path | Confirmation | Audit evidence | OperationRun | Export / retention preconditions |
|---|---|---|---|---|---|---|---|
| Local record lifecycle | Archive a local record or force-delete a backup schedule | TenantPilot local domain owner | Direct local mutation for bounded DB-only archive; shared `OperationRun` when long-running, cross-resource, or externally mediated | Always | Required | Sometimes | Required before irreversible deletion |
| Provider presence lifecycle | Mark provider missing or reappeared | Provider observation / sync process | Observation-derived update; no operator confirmation | Never | Required | Never unless part of broader reconciliation run | Not required |
| Operator suppression lifecycle | Ignore or restore local visibility | TenantPilot local domain owner | Direct local mutation | Always | Required | Never | Not required |
| Commercial/workspace lifecycle | Suspend read-only or close workspace | Platform workspace/commercial owner | Direct local mutation for bounded state change; shared `OperationRun` for closure-class or multi-artifact flows | Always | Required | Sometimes | Required for closure-class flows |
| Retention/compliance lifecycle | Mark export requested, deletion requested, hold, purge due, or purge | Compliance/retention owner | Shared `OperationRun` for purge-class automation and any long-running/export-coupled flow | Always | Required | Always for purge-class automation | Required |
| Restoreability lifecycle | Mark metadata-only or expired by retention | Backup/restore/evidence owner | Derived status when passive; shared `OperationRun` or guarded mutation when an operator reduces restoreability | Sometimes | Required | Sometimes | Required when retention or irreversible reduction is involved |

Audit-only is insufficient when the transition is destructive, long-running, externally mediated, cross-resource, export-coupled, purge-class, or materially reduces restoreability.
Those slices must reuse the shared OperationRun start and completion UX path instead of composing local queued toast, link, event, or terminal-notification behavior.

---

## Follow-Up Boundaries

Spec 262 deliberately does not implement these runtime slices:

| Follow-up slice | Boundary |
|---|---|
| `Provider-Missing Managed Object Truth v1` | Broader provider-presence rollout beyond policy records |
| `Workspace & Tenant Closure Lifecycle v1` | Workspace or tenant close/remove behavior, including closure-specific UX and authorization |
| `Data Export Before Deletion v1` | Customer-owned export workflow that fulfills `export_requested` before irreversible deletion |
| `Retention & Purge Governance v1` | Retention periods, holds, purge eligibility, irreversible deletion, and purge proof |
| `Restoreability Expiry & Evidence Retention v1` | Distinction between retained evidence and restorable payloads |

If a future spec needs one of these behaviors, it must cite this standard and implement the dedicated follow-up slice instead of expanding Spec 262 retroactively.

---

## Review Checklist

Lifecycle-bearing specs and PRs must answer these questions:

1. Which one lifecycle dimension owns the changed meaning?
2. What current repo-real source owns that meaning today?
3. Is the value current repo-real or reserved follow-up?
4. Which dimensions are explicitly forbidden as proxies?
5. Does the transition require confirmation, audit evidence, shared `OperationRun` execution, export-before-delete, or retention review?
6. Does lifecycle state remain separate from RBAC, workspace entitlement, tenant entitlement, and deny-as-not-found behavior?
7. Does provider-specific evidence stay at a provider-owned seam instead of becoming platform-core truth?
8. Is any adjacent lifecycle runtime work split into a named follow-up slice?

A change fails review if it uses lifecycle language as an authorization substitute, collapses provider absence into local deletion, treats suppression as provider truth, infers retention from commercial state, or claims restoreability from current provider presence alone.
