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 Input: Feature specification from 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)

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)

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