TenantAtlas/specs/267-artifact-lifecycle-retention/spec.md

# Feature Specification: Governance Artifact Lifecycle & Retention v1

**Feature Branch**: `267-artifact-lifecycle-retention`  
**Created**: 2026-05-03  
**Status**: Ready for implementation  
**Input**: User description: "Promote the manual-backlog governance artifact lifecycle candidate as the next best remaining target after the auto-prep queue emptied and the decision-register gap moved to Spec 265, while keeping the slice prep-only and tightly bounded to one runtime lifecycle contract for governance artifacts."

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

- **Problem**: TenantPilot already stores governance artifacts such as evidence snapshots, stored reports, review packs, and accepted-risk decision history, but each family still exposes local status fragments instead of one honest contract for identity, retention, exportability, hold state, deletion intent, and suspended-read-only access.
- **Today's failure**: Operators can tell that an artifact exists, but not reliably whether it is still the current artifact, whether it is retained only as historical evidence, whether it may still be downloaded or exported, whether a hold blocks deletion, or whether suspended-read-only workspace posture preserves safe access. This creates misleading product claims and inconsistent audit expectations.
- **User-visible improvement**: Existing artifact detail and download surfaces state one calm truth: what the artifact is, whether it is immutable, what lifecycle role it currently has, what retention state applies, which actions are still allowed, and why a blocked action is blocked.
- **Smallest enterprise-capable version**: Add one shared governance-artifact lifecycle contract over existing artifact-owning records, with immutable artifact reference, bounded lifecycle state, bounded retention state, honest export and deletion-request semantics, hold semantics, and suspended-read-only access rules, reused on current artifact surfaces, with hold or deletion-request mutations shipping only where current-owner persistence stays bounded, without introducing a generic artifact super-table, purge engine, or new workflow console.
- **Explicit non-goals**: No purge engine implementation, no workspace or tenant closure flows, no billing or subscription truth changes, no support-access governance package, no generic workflow engine, no broad customer portal, no reopening of Spec 262 taxonomy work, no provider-lifecycle expansion beyond existing truth, no dedicated Stored Reports Surface rewrite, and no export-before-deletion bundle workflow in this v1 slice.
- **Permanent complexity imported**: One shared artifact reference contract, one bounded artifact lifecycle state family, one bounded artifact retention state family, action and audit semantics reused across existing surfaces, and focused test coverage for lifecycle gating and read-only behavior. No new generic artifact registry UI, no new panel, and no new meta-framework are introduced.
- **Why now**: The active auto-prep queue is intentionally empty, `Decision Register & Approval Workflow v1` is already specced as Spec 265, and this candidate is now the next best manual-promotion target in both the backlog priority list and roadmap order. It is the clearest remaining trust and auditability gap on top of already-real evidence and review foundations.
- **Why not local**: Review packs, evidence snapshots, stored reports, decision records, download controllers, read-only workspace gating, and audit expectations must all mean the same thing. Local page checks or one-off labels would drift immediately and recreate the current ambiguity.
- **Approval class**: Core Enterprise
- **Red flags triggered**: New state axis, lifecycle-themed cross-surface contract, and multi-surface adoption. Defense: the scope is intentionally limited to one runtime contract over already-existing artifact records and current surfaces, with explicit follow-up slices for portal, export-before-delete, purge, closure, and support-access work.
- **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 + canonical-view
- **Primary Routes**:
  - existing tenant-scoped evidence snapshot list and detail surfaces under `/admin/t/{tenant}/evidence` and `/admin/t/{tenant}/evidence/{record}`
  - existing tenant-scoped review list and detail surfaces under `/admin/t/{tenant}/reviews` and `/admin/t/{tenant}/reviews/{record}` where the current export or retained artifact is explained
  - existing tenant-scoped review-pack list and detail surfaces under `/admin/t/{tenant}/review-packs` and `/admin/t/{tenant}/review-packs/{record}`
  - existing signed review-pack download route `admin.review-packs.download`
  - existing customer review workspace surface under `/admin/reviews/workspace` when retained artifacts are consumed during suspended-read-only posture
  - no new standalone stored-report or decision-register route is introduced in v1; stored reports and accepted-risk decision history consume the contract headlessly in this slice
- **Data Ownership**:
  - the lifecycle contract applies primarily to existing tenant-owned governance artifact records, including evidence snapshots, stored reports, review packs, and accepted-risk or decision history records
  - tenant reviews remain the current review-owned context surface that points to retained artifacts; this spec does not redefine tenant-review publication or supersede semantics beyond how retained artifacts are presented there
  - workspace-owned canonical views may display artifact lifecycle truth but do not become the owning source of that truth
  - this spec does not create a new product table or generic artifact super-entity
- **RBAC**:
  - workspace entitlement and tenant entitlement remain mandatory before any artifact record, summary, lifecycle badge, or download affordance is revealed
  - non-members or wrong-scope actors remain deny-as-not-found (`404`)
  - in-scope members missing the relevant capability remain forbidden (`403`)
  - any destructive-like lifecycle action shipped in this slice, such as deletion request, hold release, or irreversible expiration, still requires explicit confirmation and server-side authorization
  - suspended-read-only posture may preserve read access for authorized actors but does not bypass normal scope or capability checks

For canonical-view specs, the spec MUST define:

- **Default filter behavior when tenant-context is active**: Canonical review-workspace and retained-artifact consumption surfaces open prefiltered to the current tenant when launched from tenant context. The filter is convenience only and must not widen back to other tenants implicitly.
- **Explicit entitlement checks preventing cross-tenant leakage**: Lifecycle state, retention state, download availability, hold markers, and deletion-request indicators on canonical surfaces must be derived only from artifact rows that belong to entitled tenants inside the current workspace. Signed downloads and linked detail views must re-check tenant entitlement at request time.

## 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)**: evidence and report viewers, status messaging, lifecycle badges, detail summaries, download actions, destructive-like lifecycle actions, and audit-linked artifact navigation
- **Systems touched**: existing evidence snapshot resource, tenant review resource, review-pack resource, review-pack download controller, customer review workspace, shared badge rendering, shared artifact truth presentation, existing workspace commercial lifecycle overlay, and workspace audit logging
- **Existing pattern(s) to extend**: existing governance artifact truth summaries on evidence, review, and review-pack surfaces; existing workspace suspended-read-only gating; existing audit logging for review-pack downloads and review lifecycle mutations
- **Shared contract / presenter / builder / renderer to reuse**: shared artifact-truth presentation, centralized badge catalog and badge renderer, existing capability and policy enforcement, workspace audit logger with stable action IDs, and the current commercial lifecycle resolver for suspended-read-only behavior
- **Why the existing shared path is sufficient or insufficient**: the current shared artifact-truth path already explains execution and readiness truth for evidence, reviews, and review packs. It is insufficient for immutable identity, retention state, hold and delete-request semantics, and the difference between historical readability and active exportability. This spec extends that contract instead of creating a second lifecycle language.
- **Allowed deviation and why**: none. Stored-report adoption and accepted-risk decision-history adoption stay headless in v1, but they must still consume this same contract rather than inventing a parallel local model.
- **Consistency impact**: `current`, `historical`, `superseded`, `retained`, `on hold`, `deletion requested`, `expired access`, `download allowed`, and `blocked in suspended-read-only` must each keep one meaning across evidence, review-pack, stored-report, and decision-record contexts.
- **Review focus**: reviewers must verify that the implementation extends the shared artifact-truth and audit path, does not add page-local lifecycle taxonomies, and does not bypass existing read-only gating or download authorization.

## 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, at the contract boundary only
- **Shared OperationRun UX contract/layer reused**: existing shared OperationRun start and completion UX for review-pack generation and any future long-running export or irreversible deletion-class automation
- **Delegated start/completion UX behaviors**: existing review-pack generation keeps the shared queued toast, link, artifact-link, and terminal-notification behavior. Any future export bundle creation or irreversible deletion automation must reuse that same shared path rather than local action messaging.
- **Local surface-owned behavior that remains**: if a family passes the bounded current-owner persistence gate, its current artifact detail surface remains responsible for reason capture, current-state disclosure, and local confirmation messaging for direct lifecycle mutations such as placing or releasing a hold or requesting deletion.
- **Queued DB-notification policy**: explicit opt-in only for future long-running export or deletion-class flows; no terminal DB notification is introduced for direct hold or deletion-request capture on any family that ships inside the bounded gate.
- **Terminal notification path**: central lifecycle mechanism for any future async export or deletion run; `N/A` for bounded direct mutations that remain synchronous in this slice.
- **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`)*

- **Shared provider/platform boundary touched?**: yes
- **Boundary classification**: platform-core
- **Seams affected**: governance artifact identity, lifecycle vocabulary, retention vocabulary, export and delete semantics, and suspended-read-only artifact consumption
- **Neutral platform terms preserved or introduced**: `governance artifact`, `artifact reference`, `lifecycle state`, `retention state`, `historical artifact`, `hold`, `deletion request`, `download allowed`, and `retained history`
- **Provider-specific semantics retained and why**: provider freshness, evidence completeness, and provider-derived content stay inside the existing artifact truth summaries. This spec does not assign provider object lifecycle meaning to governance artifacts.
- **Why this does not deepen provider coupling accidentally**: the contract governs TenantPilot-owned artifacts and their local lifecycle. It explicitly forbids using provider presence, provider deletion, or provider capability limits as a proxy for artifact retention or deletion state.
- **Follow-up path**: `follow-up-spec` for any provider-lifecycle expansion beyond current artifact truth

## 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 |
|---|---|---|---|---|---|---|
| Evidence snapshot list and detail | yes | Native Filament resource plus shared artifact-truth entry | evidence viewers, status messaging, lifecycle badges | detail header, list summary, related-context links | no | Existing `Evidence` resource keeps its shape; the lifecycle contract changes truth and allowed-action disclosure only |
| Tenant review detail and current export summary | yes | Native Filament resource plus shared artifact-truth entry | evidence/report viewers, status messaging | detail summary, related artifact references | no | Review detail stays the anchor context for review-derived artifacts; this spec does not add a new review workflow page |
| Review-pack registry, detail, and signed download | yes | Native Filament resource plus existing signed download controller | report viewers, download actions, lifecycle badges, destructive-like action copy | list summary, detail header, download gate | no | Existing `Review Packs` resource remains the primary retained-artifact surface |
| Customer review workspace retained-artifact consumption | yes | Native Filament page with existing linked detail surfaces | canonical navigation, read-only explanations, report viewers | canonical table, linked detail, read-only explanation | no | The page remains read-only and scan-first; v1 only clarifies retained-artifact truth during suspended-read-only posture |
| Stored-report and accepted-risk record browsing surfaces | no | N/A | none in v1 | none in v1 | no | Contract adoption is in scope, but stored reports stay headless and current Spec 265 browsing surfaces stay unchanged until later specs |

## 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 |
|---|---|---|---|---|---|---|---|
| Evidence snapshot list and detail | Secondary Context Surface | Operator decides whether evidence remains current, historical, held, or deletion-requested before taking downstream review or export steps | Artifact reference, lifecycle state, retention state, next allowed action, read-only or suspension note | Raw completeness reasons, operation context, dimension details | Not primary because evidence lifecycle must stay attached to the artifact being inspected, not a new global inbox | Follows existing evidence inspection workflow | Prevents operators from reconstructing lifecycle from separate status, expiry, and action states |
| Tenant review detail and current export summary | Secondary Context Surface | Operator decides whether the current review still points to an exportable retained artifact or only to historical evidence | Current export reference, lifecycle state, retention state, blocked or allowed next action | Publish blockers, related evidence, operation details | Not primary because the review detail already owns the review decision context | Keeps artifact lifecycle inside existing review navigation | Avoids jumping between review detail and review-pack detail just to understand retention truth |
| Review-pack registry, detail, and signed download | Secondary Context Surface | Operator decides whether an existing pack may be downloaded, held, or marked for deletion | Artifact reference, lifecycle state, retention state, download allowed or blocked, suspension explanation | Evidence basis, SHA, operation link, related review | Not primary because the pack lifecycle should be understood in the artifact context itself | Stays inside reporting workflow instead of creating a second artifact-management console | Removes guesswork about whether `ready` still means accessible or retained |
| Customer review workspace retained-artifact consumption | Tertiary Evidence / Diagnostics Surface | Customer-safe or operator read-only consumer verifies what history is still safely readable while a workspace is suspended read-only | Retained artifact availability and one calm read-only explanation | Raw evidence, support-only diagnostics, and lower-level lifecycle details stay linked or gated | Not primary because it answers `what remains readable now` rather than `what lifecycle change should happen` | Preserves evidence-first review consumption instead of forcing a portal rewrite | Prevents suspended workspaces from looking fully unavailable when retained history is intentionally preserved |

## 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 |
|---|---|---|---|---|---|---|---|
| Evidence snapshot list and detail | operator-MSP, support-platform | Artifact reference, lifecycle state, retention state, next allowed action | Completeness state, expiry basis, related operation, downstream review-pack reference | Raw evidence dimension payloads remain secondary | `Refresh evidence` when allowed, otherwise `View related artifact` | Raw payload JSON and low-level provenance stay hidden or support-gated | Lifecycle truth is stated once in the summary, while later sections add supporting evidence only |
| Tenant review detail and current export summary | operator-MSP, support-platform | Current export reference, lifecycle and retention summary, blocked or allowed next action | Publish blockers, evidence linkage, related pack and operation links | Support-only raw details remain hidden outside support context | `Open current export` or `View evidence` | Raw fingerprints and low-level interpretation details stay hidden outside support mode | Review status does not repeat retention truth; each section adds different information |
| Review-pack registry, detail, and signed download | customer-read-only, operator-MSP, support-platform | Artifact reference, lifecycle state, retention state, download allowed or blocked, and read-only explanation when relevant | Evidence basis, generation outcome, expiry reason, related review and operation | SHA, fingerprints, and support-only details remain gated | `Download current pack` when allowed, otherwise `View source review` | Support-only diagnostics and lifecycle mutation reasons stay collapsed or gated | Pack status, retention state, and suspension reason are shown once and not re-labeled differently later |
| Customer review workspace retained-artifact consumption | customer-read-only, operator-MSP | Available retained artifacts, whether the workspace is read-only, and why current mutations are blocked | Linked review or pack history and current artifact status | Support or raw diagnostic detail remains off the surface | `Open current review` or `Open current pack` | Any destructive or admin lifecycle controls stay hidden | The page gives one calm availability explanation and delegates deeper detail to the linked artifact pages |

## 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 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Evidence snapshot list and detail | List / Table / Detail | Read-only registry report | Open current evidence or inspect lifecycle state | Clickable row to detail | required | Existing safe navigation and related links stay secondary | `More` group or detail danger area with confirmation for destructive-like lifecycle actions | `/admin/t/{tenant}/evidence` | `/admin/t/{tenant}/evidence/{record}` | Tenant context, snapshot reference, suspension note where relevant | Evidence snapshot | Reference, lifecycle state, retention state, next action | none |
| Tenant review detail and current export summary | Detail / Report viewer | Read-only detail with retained-artifact context | Open the current retained pack or evidence basis | Detail page with linked retained artifact | allowed from list | Supporting navigation and related links stay secondary | Existing archive remains where it already lives; any new lifecycle actions on child artifacts stay off the review detail primary plane | `/admin/t/{tenant}/reviews` | `/admin/t/{tenant}/reviews/{record}` | Tenant context, review reference, linked artifact reference | Review | Current artifact availability and lifecycle truth | none |
| Review-pack registry, detail, and signed download | List / Table / Detail / Download | Read-only registry report | Open or download the current pack if retained | Clickable row to detail, then explicit download | required | Existing `Download` shortcut and linked evidence or review navigation remain secondary | `More` group or detail danger area with confirmation for deletion request or hold release | `/admin/t/{tenant}/review-packs` | `/admin/t/{tenant}/review-packs/{record}` plus `admin.review-packs.download` | Tenant context, pack reference, linked review, suspended-read-only explanation | Review pack | Reference, lifecycle state, retention state, download allowed or blocked | none |
| Customer review workspace retained-artifact consumption | Canonical / Table / Linked detail | Read-only registry report | Open the current retained review or pack | Primary link column to existing detail pages | forbidden for non-linked rows | Clear filters and supporting navigation stay secondary | none on the workspace page | `/admin/reviews/workspace` | Existing linked detail pages under review, evidence, or pack resources | Workspace context, current tenant filter, read-only explanation | Customer review artifact | What remains readable now and what is blocked now | Dedicated canonical-surface exception because the page links outward instead of owning inline detail |

## 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 |
|---|---|---|---|---|---|---|---|---|---|---|
| Evidence snapshot list and detail | Tenant operator | Decide whether this evidence artifact remains the current retained basis for review and export | List/detail | Is this evidence artifact still current, retained, and safe to use? | Artifact reference, lifecycle state, retention state, next allowed action | Raw completeness payloads and low-level provenance | artifact lifecycle, retention state, completeness, suspended-read-only availability | TenantPilot artifact truth only | Refresh evidence, open related review or pack | Request deletion, place or release hold, expire snapshot |
| Tenant review detail and current export summary | Review owner | Decide whether the current retained artifact is still the right review output to share or preserve | Detail | Which retained artifact does this review currently point to, and is it still available? | Current export reference, lifecycle state, retention state, blocked or allowed next action | Publish blockers, related evidence details, low-level interpretation context | review lifecycle context, artifact lifecycle, retention state | TenantPilot artifact truth only | Open current export, open evidence snapshot | Existing review archive only; child-artifact lifecycle changes happen on the artifact surface |
| Review-pack registry, detail, and signed download | Reporting operator or customer-safe consumer | Decide whether an already-generated pack may be downloaded now or only preserved as historical evidence | List/detail/download | Can I still use this pack, and what does its lifecycle state mean? | Artifact reference, lifecycle state, retention state, download allowed or blocked, read-only explanation | Evidence basis, generation diagnostics, SHA, operation link | artifact lifecycle, retention state, generation outcome, suspended-read-only availability | TenantPilot artifact truth only | Download current pack, view source review | Request deletion, place or release hold |
| Customer review workspace retained-artifact consumption | Customer-safe reader | Decide what retained history remains readable while the workspace is suspended read-only | Canonical table and linked detail | What history can I still read right now? | Available retained artifacts and one calm read-only explanation | Raw or support-only diagnostics remain linked or hidden | retained availability, workspace read-only posture | TenantPilot read-only only | Open current review, open current pack | none |

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

- **New source of truth?**: yes - one governance-artifact lifecycle contract over existing artifact records
- **New persisted entity/table/artifact?**: no generic new entity or table by default
- **New abstraction?**: no new generic engine; one bounded shared contract only
- **New enum/state/reason family?**: yes - one bounded lifecycle state family and one bounded retention state family for governance artifacts
- **New cross-domain UI framework/taxonomy?**: no new UI framework; only a bounded lifecycle vocabulary reused in existing surfaces
- **Current operator problem**: operators cannot currently answer whether a governance artifact is current, historical, held, deletion-requested, still downloadable, or merely blocked by suspended-read-only posture without decoding multiple local statuses.
- **Existing structure is insufficient because**: review packs, evidence snapshots, stored reports, and decision history each expose different partial status clues. None of those local clues alone answers identity, retention, or allowed-action truth.
- **Narrowest correct implementation**: reuse existing artifact-owning records and shared artifact-truth surfaces, add one shared lifecycle and retention contract, and keep destructive or long-running follow-up mechanics out of scope.
- **Ownership cost**: shared vocabulary, focused policy and surface tests, a small amount of lifecycle-specific audit data, and reviewer discipline around action semantics.
- **Alternative intentionally rejected**: a generic artifact registry, workflow engine, portal, or purge framework was rejected as too broad. Local page-only fixes were rejected because they would preserve cross-surface drift.
- **Release truth**: current-release truth grounded in already persisted governance artifacts and already-real read-only suspension behavior, not speculative future platform preparation

### Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, migration shims, historical aliases, and compatibility-only test coverage are out of scope unless a later implementation slice proves they are necessary.

Canonical replacement of ambiguous lifecycle wording is preferred over preserving overloaded terminology.

## 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 bounded implementation slice proves behavior through model and policy invariants, controller download authorization, and Livewire or Filament surface tests on current artifact pages. Browser coverage is not required unless lifecycle gating proves unstable only in the real browser.
- **New or expanded test families**: focused artifact-lifecycle feature coverage for review packs, evidence snapshots, suspended-read-only access, headless stored-report truth, and aggregate-level accepted-risk decision-history behavior
- **Fixture / helper cost impact**: moderate; tests need workspace, tenant, membership, and a small curated artifact matrix, but they do not need a new heavy governance harness or provider-wide setup
- **Heavy-family visibility / justification**: none by default. If a later implementation adds a broad cross-artifact matrix, it must be named explicitly as heavy governance rather than hidden inside ordinary Filament tests.
- **Special surface test profile**: shared-detail-family
- **Standard-native relief or required special coverage**: standard native Filament coverage is sufficient for evidence, review, and review-pack surfaces; controller download tests and policy tests cover the signed download and read-only gate behavior
- **Reviewer handoff**: reviewers must confirm that lifecycle truth stays centralized, direct mutations stay audit-backed only when the bounded current-owner gate passes, accepted-risk decision adoption stays headless in this slice, no generic artifact engine appears, and the exact proof commands stay limited to the canonical artifact-lifecycle test suite plus Pint hygiene
- **Budget / baseline / trend impact**: minor expected drift from a new cross-artifact test matrix; no browser or broad heavy-family expansion should appear in v1
- **Escalation needed**: none
- **Active feature PR close-out entry**: Guardrail
- **Planned validation commands**:
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/GovernanceArtifactTruth/GovernanceArtifactLifecycleContractTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Evidence/EvidenceSnapshotResourceTest.php tests/Feature/Evidence/EvidenceSnapshotAuditLogTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPack/ReviewPackResourceTest.php tests/Feature/ReviewPack/ReviewPackDownloadTest.php tests/Feature/ReviewPack/ReviewPackEntitlementEnforcementTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantReview/TenantReviewLifecycleTest.php tests/Feature/TenantReview/TenantReviewUiContractTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingExceptionRenewalTest.php tests/Feature/Findings/FindingExceptionRevocationTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/PermissionPosture/StoredReportModelTest.php tests/Feature/PermissionPosture/PruneStoredReportsCommandTest.php tests/Feature/EntraAdminRoles/StoredReportFingerprintTest.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 - Understand what an artifact is allowed to do now (Priority: P1)

As a reporting or review operator, I want every retained governance artifact to show one stable reference, one lifecycle role, one retention state, and one honest next action so that I do not have to infer download, hold, or delete meaning from multiple local statuses.

**Why this priority**: This is the core operator trust problem. If the artifact surface still leaves lifecycle truth ambiguous, the spec delivers no real product value.

**Independent Test**: Can be fully tested by opening an evidence snapshot, a review pack, and a review-derived artifact summary in different lifecycle states and confirming that each surface answers identity, lifecycle, retention, and next action from the first screen.

**Acceptance Scenarios**:

1. **Given** a retained review pack that is still downloadable, **When** the operator opens the pack detail, **Then** the surface shows a stable artifact reference, its lifecycle state, its retention state, and that download is currently allowed.
2. **Given** a historical evidence snapshot that is no longer the current evidence basis, **When** the operator opens it, **Then** the surface states that it is historical rather than current and does not imply that deletion or purge already happened.

---

### User Story 2 - Preserve history during suspended read-only posture (Priority: P1)

As an authorized customer-safe or operator read-only consumer, I want suspended-read-only posture to preserve retained history without implying new artifact generation or hidden deletion, so that I can still inspect evidence and downloads that the product promises to retain.

**Why this priority**: The contract must stay honest at the moment when commercial suspension or workspace freeze would otherwise make artifacts look unavailable or deceptively mutable.

**Independent Test**: Can be fully tested by placing a workspace into suspended-read-only posture and verifying that retained artifacts remain viewable and already-generated downloads remain governed by retention truth, while tenant-plane mutation or generation actions are blocked.

**Acceptance Scenarios**:

1. **Given** a suspended-read-only workspace with a retained review pack, **When** an authorized consumer opens the current pack or review workspace, **Then** the product still exposes the retained artifact and explains that mutation is blocked because the workspace is read-only.
2. **Given** a suspended-read-only workspace, **When** a tenant-plane actor attempts a new artifact generation or lifecycle mutation, **Then** the surface blocks the action with one consistent read-only explanation instead of hiding retained history.

---

### User Story 3 - Audit every lifecycle-sensitive artifact action (Priority: P2)

As a workspace or compliance operator, I want download actions and any bounded current-owner lifecycle mutations on governance artifacts to leave a stable audit trail tied to the artifact reference and scope, so that future review or customer conversations can prove what happened to an artifact and why.

**Why this priority**: Artifact lifecycle changes without audit proof would undermine the trust value this spec is meant to add.

**Independent Test**: Can be fully tested by triggering a retained-artifact download and, only on artifact families that pass the bounded current-owner persistence gate, placing a hold and requesting deletion while verifying that each shipped action records the artifact reference, actor, scope, originating surface, and before or after state.

**Acceptance Scenarios**:

1. **Given** an operator downloads a retained review pack, **When** the controller serves the file, **Then** the audit trail records the artifact reference, actor, tenant, workspace, and source surface.
2. **Given** an artifact family whose hold or deletion-request persistence stays on the current owning record, **When** an operator places a hold or requests deletion, **Then** the mutation records the reason and the before or after retention state without claiming the content was already purged.

### Edge Cases

- A review pack is `ready` but the workspace is suspended read-only; the contract must distinguish `download still allowed` from `new generation blocked`.
- An evidence snapshot is expired from direct access but remains historically referenced by a published review; the contract must not erase its immutable reference or imply that review history is invalid.
- A stored report has a stable fingerprint but no dedicated browsing surface yet; the contract must still define its lifecycle and retention expectations without forcing a new UI surface into v1.
- An accepted-risk decision record is append-only and later superseded by a newer decision; the older decision must remain historically addressable rather than looking editable or deleted.
- A deletion request is placed on an artifact that is also on hold; the hold must win and the UI must explain that the request is blocked from progressing.
- Canonical review-workspace tables must not leak that another tenant has a held, deletion-requested, or downloadable artifact outside the viewer's current entitlement.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature introduces no new Microsoft Graph call path. It governs TenantPilot-owned governance artifacts and their local lifecycle truth only. Existing safety gates, tenant isolation, and audit expectations remain mandatory.

**Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001):** This feature introduces one bounded lifecycle contract and one bounded retention contract because the current operator workflow already needs them across multiple real artifact families. It must not create a generic artifact engine, a super-table, or speculative portal infrastructure.

**Constitution alignment (XCUT-001):** The feature extends existing artifact-truth, badge, read-only gating, and audit paths. No page-local lifecycle language or one-off viewer logic is allowed.

**Constitution alignment (DECIDE-AUD-001 / OPSURF-001):** Every affected surface must separate customer-readable lifecycle truth, operator diagnostics, and support-only detail. One dominant next action must stay primary, and the same lifecycle fact must not be restated differently in multiple sections.

**Constitution alignment (PROV-001):** Provider-derived evidence remains inside the existing artifact truth summaries. Provider presence or provider deletion must not become a proxy for governance-artifact retention or deletion state.

**Constitution alignment (TEST-GOV-001):** The implementation must stay in focused feature coverage. No hidden heavy-governance or browser family may appear by default.

**Constitution alignment (OPS-UX / OPS-UX-START-001):** Existing review-pack generation and any future long-running export or irreversible deletion run must reuse the shared OperationRun UX path. If a family passes the bounded current-owner persistence gate, direct hold placement, hold release, or deletion request capture may remain direct audit-backed mutations and must not silently grow their own async notification model.

**Constitution alignment (RBAC-UX):** Authorization planes remain unchanged. Non-member or wrong-scope access returns `404`, in-scope capability denial returns `403`, server-side policies remain authoritative, and destructive-like lifecycle actions require confirmation.

**Constitution alignment (BADGE-001):** Lifecycle and retention badges must stay centralized and must not introduce page-local color or wording maps.

**Constitution alignment (UI-FIL-001 / UX-001):** Existing Filament resources and pages remain the primary surfaces. The implementation must reuse native Filament components and shared primitives, avoid ad-hoc styling, preserve one dominant primary action per surface, keep detail disclosure in infolists or native sections, and avoid adding a new artifact-management design system.

**Constitution alignment (UI-NAMING-001):** Primary operator-facing labels use `artifact`, `evidence snapshot`, `review pack`, `stored report`, `accepted-risk record`, `download`, `place hold`, `release hold`, and `request deletion`. Terms such as `soft delete`, `hard delete`, or `purge executor` stay implementation-level and must not be the primary operator wording in v1.

**Constitution alignment (Filament Action Surfaces):** The Action Surface Contract remains satisfied when evidence, review, and review-pack surfaces keep their current inspect models, add no redundant View action, keep navigation separate from mutation, and group destructive-like lifecycle actions under the existing danger or `More` placement rules.

### Functional Requirements

- **FR-267-001**: The system MUST define one shared governance-artifact lifecycle contract for evidence snapshots, stored reports, review packs, and accepted-risk or decision records.
- **FR-267-002**: The shared contract MUST expose an immutable artifact reference that remains stable across superseding, holds, deletion requests, suspended-read-only access, and historical retention.
- **FR-267-003**: The contract MUST separate artifact lifecycle state from artifact retention state.
- **FR-267-004**: The artifact lifecycle state MUST answer whether an artifact is current, historical, superseded, or otherwise removed from active circulation without implying purge or provider deletion.
- **FR-267-005**: The artifact retention state MUST answer whether an artifact is retained, on hold, deletion-requested, or expired from direct access, without collapsing those meanings into workspace suspension, review publication status, or provider truth.
- **FR-267-006**: The contract MUST distinguish direct download or export of an already-generated artifact from a future export-before-deletion workflow.
- **FR-267-007**: When v1 includes a hold mutation for a concrete artifact family, that hold MUST preserve the artifact reference, prevent deletion progression, and remain visible on the artifact surface until explicitly released.
- **FR-267-008**: When v1 includes a deletion-request mutation for a concrete artifact family, that request MUST be explicit, auditable, and reversible until a later deletion or purge follow-up executes. In v1 it MUST NOT claim that artifact content was already destroyed.
- **FR-267-009**: The first implementation slice MUST treat `deletion requested` only as reversible removal from normal operator circulation while immutable reference and audit history remain intact. Irreversible hard-delete semantics remain reserved for a later purge or closure slice.
- **FR-267-010**: Suspended-read-only workspace posture MUST preserve authorized read access to retained artifacts and already-generated downloads when their retention state allows it, while blocking tenant-plane generation or lifecycle mutations that would change artifact truth.
- **FR-267-011**: Existing evidence, review, and review-pack detail surfaces MUST present artifact reference, lifecycle state, retention state, and the next allowed or blocked action without requiring the operator to decode multiple local status fields.
- **FR-267-012**: Existing canonical customer-review consumption surfaces MUST show one calm read-only explanation and must not imply that retained artifacts vanished simply because the workspace is suspended read-only.
- **FR-267-013**: Stored reports and accepted-risk or decision records MUST adopt the same lifecycle and retention contract even if stored reports stay headless and the current decision register or detail surfaces remain unchanged in this slice.
- **FR-267-014**: Accepted-risk or decision history records MUST remain append-only and historically addressable even when a newer decision supersedes them.
- **FR-267-015**: Every in-scope download, and every hold, hold release, or deletion-request mutation that passes the bounded current-owner persistence gate, MUST write an audit event that records the artifact reference, actor, workspace, tenant when present, originating surface, and before or after lifecycle state as appropriate.
- **FR-267-016**: The first implementation slice MUST reuse existing capability and policy enforcement and MUST include both positive and negative authorization coverage for detail visibility, download access, and destructive-like lifecycle mutations.
- **FR-267-017**: The feature MUST NOT create a generic artifact registry UI, a generic workflow engine, a broad customer artifact portal, or a purge automation engine.
- **FR-267-018**: The feature MUST explicitly defer dedicated Stored Reports Surface work, Workspace and Tenant Closure Lifecycle work, Data Export Before Deletion workflow, Retention and Purge Governance, and Enterprise Access Boundary or Support Access Governance to named follow-up specs.
- **FR-267-019**: The feature MUST consume Spec 262 as closed taxonomy input and MUST NOT reopen or normalize it.
- **FR-267-020**: The feature MUST treat Spec 158 as context for truthful artifact semantics and MUST extend, not contradict, that product-truth direction.

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

| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
|---|---|---|---|---|---|---|---|---|---|---|
| Evidence snapshot resource | Existing `EvidenceSnapshotResource` list and view surfaces | Keep existing `Create snapshot`; no new lifecycle CTA on the list header in v1 | Existing `recordUrl()` clickable row remains primary | Keep current safe row actions; no more than one direct lifecycle shortcut | none | Existing `Create snapshot` empty-state CTA remains | Keep `Refresh evidence` primary; any later gated `Place hold`, `Release hold`, or `Request deletion` stays in `More` or the danger area with confirmation only if the family passes the bounded persistence gate | N/A | yes | Action Surface Contract stays satisfied; no redundant View action and no new bulk family |
| Tenant review resource | Existing `TenantReviewResource` detail surface and current export summary | Existing header actions remain; no new top-level review-lifecycle family is added by this spec | Existing clickable-row review inspection remains primary | Existing inline export shortcut remains the only direct row shortcut | none | Existing `Create first review` remains | Keep current review actions; child-artifact lifecycle changes stay on the artifact surface rather than the review primary plane | N/A | yes | This spec changes summary truth and linked artifact context, not the core review workflow |
| Review-pack resource and signed download | Existing `ReviewPackResource` list and view surfaces plus `admin.review-packs.download` | Keep existing `Generate pack` entry points outside this spec's new lifecycle family | Existing clickable row remains primary | Keep `Download` as the only direct safe shortcut | none | Existing generate CTA remains while the list is empty | Keep `Download` and `Regenerate`; any later gated `Place hold`, `Release hold`, or `Request deletion` is grouped under `More` or visible danger placement with confirmation only if the family passes the bounded persistence gate | N/A | yes | Signed download keeps server-side entitlement checks and audit logging; no new artifact portal route |
| Customer review workspace | Existing `CustomerReviewWorkspace` page | Keep only `Clear filters` | Existing primary link column remains the inspect model | none | none | Existing `Clear filters` empty-state CTA when filtered | N/A | N/A | existing open and download audits remain | No destructive actions appear on the canonical workspace page in v1 |

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

- **Governance Artifact Reference**: Stable identity for one retained governance artifact, including its family, owning scope, stable record identity, and any immutable content fingerprint or historical anchor needed to distinguish it from later artifacts.
- **Governance Artifact Lifecycle State**: The contract that answers whether the artifact is current, historical, superseded, or otherwise removed from active circulation without implying retention or purge truth.
- **Governance Artifact Retention State**: The contract that answers whether the artifact is retained, on hold, deletion-requested, or expired from direct access.
- **Governance Artifact Lifecycle Event**: The auditable action record produced when an artifact is downloaded, or when a bounded current-owner mutation path places it on hold, releases a hold, or marks it for deletion.
- **Accepted-Risk or Decision Record**: Append-only governance history entry that documents risk acceptance or decision outcomes and must remain historically addressable even when later decisions supersede it.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-267-001**: In the first implementation slice, 100% of in-scope artifact detail or download surfaces show immutable reference, lifecycle state, retention state, and next allowed or blocked action in one inspection step.
- **SC-267-002**: In a curated review set of 12 artifact cases across evidence, review-pack, and review-derived contexts, operators correctly answer whether the artifact is current, historical, held, deletion-requested, or downloadable in at least 11 of 12 cases without opening raw diagnostics.
- **SC-267-003**: In suspended-read-only validation coverage, 100% of retained artifacts that should remain readable stay accessible to authorized users, and 0 blocked tenant-plane mutation or generation actions appear as allowed.
- **SC-267-004**: In focused audit regression coverage, 100% of in-scope download actions, and 100% of any hold, hold-release, or deletion-request mutations that pass the bounded current-owner persistence gate, produce an artifact-reference-based audit trail.
- **SC-267-005**: No in-scope surface uses provider lifecycle, workspace suspension, or review publication state as a proxy for artifact retention truth.
- **SC-267-006**: If no artifact family can add hold or deletion-request persistence without widening scope, the implementation still counts as successful once read-only lifecycle truth, existing download audit, and the explicit mutation split decision are all proven.

## Assumptions

- Spec 262 is completed and remains the closed taxonomy authority. This spec consumes it as context only.
- Spec 158 remains the earlier artifact-truth foundation and is used as context only.
- Suspended-read-only workspace behavior already exists through the commercial lifecycle overlay and is reused rather than redesigned here.
- Review-pack downloads already have server-side entitlement and audit behavior that this contract extends.
- Stored reports and accepted-risk decision records already exist as persisted governance artifacts even though their dedicated browsing surfaces are still incomplete or deferred.
- Spec 265 now owns the broader decision-register and approval workflow gap; this spec only covers artifact lifecycle semantics for accepted-risk or decision records through shared contract mapping and aggregate-level history truth.

## Dependencies

- `docs/product/spec-candidates.md`
- `docs/product/roadmap.md`
- `docs/product/standards/lifecycle-governance.md`
- `specs/158-artifact-truth-semantics/spec.md`
- `specs/251-commercial-entitlements-billing-state/spec.md`
- `specs/262-lifecycle-governance-taxonomy/spec.md`
- `specs/265-decision-register-approval/spec.md`
- existing evidence, review, review-pack, and accepted-risk runtime seams, including `StoredReport`, `ReviewPack`, `TenantReview`, `FindingExceptionDecision`, `ReviewPackService`, `TenantReviewLifecycleService`, `ReviewPackResource`, `TenantReviewResource`, and `ReviewPackDownloadController`

## Non-Goals

- Implementing a purge engine, retention scheduler, or irreversible deletion executor
- Implementing workspace or tenant closure flows
- Reworking billing, subscription, or commercial-state truth
- Implementing support-access governance, delegated access, or impersonation controls
- Creating a generic artifact registry service, workflow engine, or customer artifact portal
- Reopening or normalizing Spec 262 taxonomy work
- Expanding provider-lifecycle semantics beyond current artifact truth
- Delivering the dedicated Stored Reports Surface, Data Export Before Deletion workflow, or broad retention-governance console in this v1 slice

## Candidate Selection Rationale

- **Selected candidate**: Governance Artifact Lifecycle & Retention v1
- **Source locations**:
  - `docs/product/spec-candidates.md` manual-promotion backlog priority 2
  - `docs/product/roadmap.md` productization order 3
  - `docs/product/standards/lifecycle-governance.md`
- **Why selected now**: the active auto-prep queue is intentionally empty, Spec 265 already removes the decision-register candidate from eligibility, and this is the next best remaining manual-promotion target with clear repo-real anchors.
- **Completed-spec guardrail result**: Spec 262 is treated as completed closed context only and is not reopened. Spec 158 is treated as context only. Spec 265 makes the earlier decision-register gap ineligible for this slot.
- **Smallest viable implementation slice**: apply the shared lifecycle and retention contract to current evidence, review-pack, and review-derived artifact surfaces; keep stored reports and accepted-risk records in the contract scope without forcing a new browsing console or current decision-surface rewrite; ship hold or deletion-request mutations only where bounded current-owner persistence remains local.
- **Why close alternatives are deferred**:
  - `Stored Reports Surface v1` is a dedicated product-surface follow-up and should not be hidden inside this lifecycle contract
  - `Workspace & Tenant Closure Lifecycle v1` is broader commercial and tenant lifecycle work and remains separate from artifact lifecycle
  - `Data Export Before Deletion v1` is a workflow slice and remains separate from direct download of already-generated artifacts
  - `Retention & Purge Governance v1` is the dedicated irreversible deletion and purge follow-up
  - `Enterprise Access Boundary & Support Access Governance v1` is an access-governance slice, not an artifact-lifecycle slice

## Follow-up Map

| Follow-up slice | Why it stays separate | Dependency on this spec |
|---|---|---|
| Stored Reports Surface v1 | Productizes how stored reports are browsed and consumed; it should reuse the lifecycle contract rather than create it | Reuses immutable artifact reference and retention semantics for stored reports |
| Workspace & Tenant Closure Lifecycle v1 | Governs closure behavior for broader workspace and tenant truth, not only artifacts | Reuses read-only and retained-history rules without collapsing artifact lifecycle into closure state |
| Data Export Before Deletion v1 | Owns export-request workflow, export bundle contents, proof of completion, and delete preconditions | Reuses the distinction between direct download of an existing artifact and future pre-deletion export workflow |
| Retention & Purge Governance v1 | Owns irreversible deletion, purge scheduling, purge proof, and hard-delete execution | Reuses hold and deletion-request semantics as preconditions rather than re-inventing them |
| Enterprise Access Boundary & Support Access Governance v1 | Owns support-access approval, TTL, and customer-visible access audit, not artifact retention truth | Reuses audit-trail principles but stays out of artifact lifecycle modeling |

## Final Direction

This spec turns governance artifacts into first-class retained records with one honest runtime contract. The contract is intentionally smaller than a portal, a purge engine, or a workflow framework: it gives every in-scope artifact a stable reference, separates lifecycle role from retention posture, explains what suspended-read-only means for retained history, and requires audit proof for lifecycle-sensitive actions that remain inside bounded current-owner seams. It also keeps the roadmap clean by consuming Spec 262 as closed taxonomy input, by treating Spec 158 as context rather than a new foundation, by keeping accepted-risk decision adoption headless in this slice, and by leaving Stored Reports Surface, export-before-delete, purge governance, closure lifecycle, and support-access governance as explicit follow-up slices.