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

Quickstart: Governance Artifact Lifecycle & Retention v1

Goal

Implement one bounded shared lifecycle and retention contract over the existing governance-artifact families without widening into a registry UI, purge engine, closure flow, billing overlay, or new browsing console.

Recommended Implementation Order

1. Extend the current governance-artifact truth support layer.
2. Apply the shared contract to evidence, tenant-review, review-pack, customer-workspace, and signed-download surfaces.
3. Add stored-report and accepted-risk decision-history adoption through existing headless model, aggregate, and service seams.
4. Add family-local hold or deletion-request persistence only if it can stay on current tables or aggregates without widening scope; otherwise stop at read-only lifecycle truth plus existing download audit.
5. Run the focused unit and feature proof and stop.

Implementation Checklist

1. Add bounded lifecycle and retention mapping to the current artifact-truth path.
2. Keep EvidenceSnapshotResource, TenantReviewResource, ViewTenantReview, ReviewPackResource, and CustomerReviewWorkspace on their current action-surface contracts.
3. Preserve the existing review-pack split: blocked future starts may show a business-state block, but ready retained downloads stay on the current controller path.
4. Keep StoredReport adoption headless through current service, fingerprint, and prune seams.
5. Keep decision-history adoption inside FindingException, FindingExceptionDecision, and FindingExceptionService without introducing a second decision console or rewriting current Spec 265 surfaces.
6. Only add new destructive-like actions on current detail surfaces with ->action(...), ->requiresConfirmation(), and server-side authorization after the bounded current-owner persistence gate passes.
7. Stop if implementation starts demanding a generic artifact table, new console, or browser-heavy proof by default.

Focused Proof 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

Manual Checks Only If Native Proof Is Insufficient

1. Open a review-pack detail that is ready, retained, and downloadable, then confirm the surface states reference, lifecycle truth, retention truth, and allowed next action without opening diagnostics.
2. Put the workspace into suspended read-only posture and confirm that review-pack generation still blocks before creating a run while signed ready-pack downloads remain available.
3. Open the customer review workspace and confirm it stays scan-first with Open review as the dominant row affordance rather than a new download or mutation console.
4. Open an evidence snapshot detail and confirm it shows linked artifact reference, lifecycle truth, retention truth, and blocked-reason wording without turning the page into a mutation console.

Stop Conditions

• A generic artifact registry table, artifact console, or workflow engine becomes necessary.
• Hold or deletion-request persistence cannot stay on current family tables or aggregate roots.
• Accepted-risk decision adoption requires a current-slice DecisionRegister or ViewFindingException rewrite instead of staying headless.
• The slice starts to require purge, closure, export-before-delete, or support-access workflow semantics.
• Browser tests become the default proving lane instead of a bounded exception.
• The implementation proposes new global-search resources, panel-provider changes, or asset-registration changes for this slice.

Review Close-out

1. Re-check specs/267-artifact-lifecycle-retention/checklists/requirements.md before implementation and close-out.
2. Keep the review outcome class at acceptable-special-case, the workflow outcome at keep, and the test-governance outcome at keep unless the mutation split gate or a decision-surface rewrite forces escalation.
3. If the bounded current-owner persistence gate fails, flip the workflow outcome to split before continuing.