TenantAtlas/specs/406-governance-artifact-lifecycle-retention/tasks.md

Tasks: Spec 406 - Governance Artifact Lifecycle & Retention

Input: specs/406-governance-artifact-lifecycle-retention/spec.md, plan.md, checklists/requirements.md, user-provided Spec 406 draft, Spec 400 audit context, Specs 403-405 proof lineage, completed Spec 267 lifecycle close-out, and current repo truth.

Tests: Required. This is runtime lifecycle/action hardening over existing governance artifacts. Use Pest 4 Feature/Filament/Livewire action tests, focused storage/file tests, PostgreSQL lane if migrations/indexes are added, and focused browser proof for rendered lifecycle/download/action behavior.

Test Governance Checklist

• Lane assignment is Feature/Filament/Livewire + focused Browser, with PostgreSQL only when migrations/indexes are added.
• New or changed tests stay in the smallest honest family and avoid broad heavy-governance expansion.
• Fixtures remain explicit and feature-local; no new global artifact matrix harness unless justified in implementation-report.md.
• Planned validation commands cover lifecycle behavior without claiming a full browser/UX/runtime audit.
• Browser proof is required for representative existing rendered surfaces.
• Human Product Sanity and Product Surface close-out are recorded.
• Any material budget, baseline, trend, or escalation note is recorded in the implementation report.

Phase 1: Preparation And Safety

Purpose: Establish repo safety, read the package, and prevent completed-spec rewrites.

• T001 Read specs/406-governance-artifact-lifecycle-retention/spec.md, plan.md, tasks.md, and checklists/requirements.md.
• T002 Record current branch, HEAD, dirty state, tracked changed files, untracked files, and git diff --check in specs/406-governance-artifact-lifecycle-retention/implementation-report.md.
• T003 Re-read AGENTS.md, .specify/memory/constitution.md, docs/ai-coding-rules.md, docs/architecture-guidelines.md, docs/security-guidelines.md, docs/testing-guidelines.md, docs/product/standards/product-surface-contract.md, and docs/product/standards/lifecycle-governance.md.
• T004 Re-read Specs 158, 262, 267, 400, 403, 404, and 405 as read-only context; record which constraints carry forward and explicitly note Spec 404/405 PASS WITH CONDITIONS caveats.
• T005 Confirm completed Spec 267 implementation close-out, checked task history, browser proof, and deferred mutation decision are not edited, normalized, unchecked, or removed.
• T006 Create specs/406-governance-artifact-lifecycle-retention/implementation-report.md with the sections required by spec.md.

Phase 2: Artifact Inventory And Lifecycle Matrix

Purpose: Prove every lifecycle decision is intentional before runtime edits.

• T007 Inventory review-pack lifecycle, retention, file, download, audit, and prune behavior in apps/platform/app/Models/ReviewPack.php, apps/platform/app/Services/ReviewPackService.php, apps/platform/app/Http/Controllers/ReviewPackDownloadController.php, apps/platform/app/Console/Commands/PruneReviewPacksCommand.php, apps/platform/config/tenantpilot.php, and existing ReviewPack tests.
• T008 Inventory stored-report and management-PDF lifecycle, file, download, status, audit, prune, and runtime-gate behavior in apps/platform/app/Models/StoredReport.php, apps/platform/app/Http/Controllers/ManagementReportPdfDownloadController.php, management report services, apps/platform/app/Console/Commands/PruneStoredReportsCommand.php, and existing Spec379/Spec404 tests.
• T009 Inventory evidence snapshot lifecycle, currentness, retention, review-pack linkage, audit, and generated-state behavior in apps/platform/app/Models/EvidenceSnapshot.php, apps/platform/app/Services/Evidence/EvidenceSnapshotService.php, EvidenceSnapshotResource, and existing evidence tests.
• T010 Inventory customer-review retained-output access in apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php, related review-pack/review models, and customer-workspace tests.
• T011 Inventory OperationRun proof package exposure in apps/platform/app/Models/OperationRun.php, operation detail surfaces, and existing OperationRun tests without treating execution status as artifact lifecycle truth.
• T012 Inventory finding, risk exception, accepted-risk decision, and governance inbox artifact behavior in FindingException, FindingExceptionDecision, related resources/services, and findings tests.
• T013 Populate the Governance Artifact Lifecycle Matrix in implementation-report.md with each artifact type, model/table, file dependency, scope, customer-safe boundary, lifecycle fields, allowed states/actions, authorization, retention, Spec 404/405 condition impact, hold/delete/export/audit/test/browser proof, hold/delete support classification, status, risk, and follow-up.
• T014 Mark every artifact family as PASS, PASS WITH EXCEPTION, MISSING PROOF, DEFECT FOUND, PRODUCT DECISION REQUIRED, or DEFERRED, and mark hold/delete support as SUPPORTED_NOW, DEFERRED, or PRODUCT_DECISION_REQUIRED.
• T015 Stop before runtime edits if any high-risk artifact family lacks lifecycle classification, hold/delete support classification, owner, authorization decision, file-consistency rule, and risk rating.

Phase 3: User Story 1 - Operator understands artifact lifecycle and allowed action (Priority: P1)

Goal: Existing artifact surfaces state lifecycle state, retention/file availability, and one allowed or blocked next action without exposing raw diagnostics by default.

Independent Test: A permitted operator views representative review-pack, stored-report/PDF, evidence, and customer-review artifacts and can identify lifecycle state, retention/file availability, customer-safe state, and next action from existing surfaces.

Tests for User Story 1

• T016 [P] [US1] Add or update focused tests under apps/platform/tests/Feature/ReviewPack/ proving ready, expired, failed, deleted/blocked, missing-file, and historical review-pack state summaries.
• T017 [P] [US1] Add or update focused tests under apps/platform/tests/Feature/ManagementReports/ or existing Spec404/StoredReport suites proving management-PDF StoredReport lifecycle/download state and missing-file failure behavior.
• T018 [P] [US1] Add or update focused tests under apps/platform/tests/Feature/Evidence/ proving evidence snapshot current, historical, expired, failed/missing, and linked-review artifact state.
• T019 [P] [US1] Add or update focused tests for CustomerReviewWorkspace proving customer/read-only lifecycle wording and absence of raw/internal artifact details.

Implementation for User Story 1

• T020 [US1] Update existing artifact-truth/status rendering through apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php, apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthEnvelope.php, apps/platform/app/Support/Badges/BadgeCatalog.php, apps/platform/app/Support/Badges/BadgeRenderer.php, apps/platform/app/Support/Badges/Domains/GovernanceArtifactLifecycleBadge.php, apps/platform/app/Support/Badges/Domains/GovernanceArtifactRetentionBadge.php, and existing resource schemas so ReviewPackResource, ViewReviewPack, EvidenceSnapshotResource, ViewEvidenceSnapshot, and CustomerReviewWorkspace show lifecycle and next-action truth without page-local vocabulary drift.
• T021 [US1] Update StoredReport/management-PDF owner surfaces or controller responses so file-backed readiness is truthful and missing/invalid files are not offered as valid downloads.
• T022 [US1] Preserve Product Surface budgets: one lifecycle summary, one dominant next action, secondary technical links demoted, and no raw IDs/source keys/provider payloads in customer-facing defaults.

Phase 4: User Story 2 - Destructive lifecycle actions are blocked or audited correctly (Priority: P1)

Goal: Hold, unhold, archive, expire, delete, and purge-like behavior is explicitly scoped, authorized, confirmation-backed when visible, audited, and blocked when held.

Independent Test: A held artifact cannot be deleted through UI, direct action, or retention cleanup; an allowed lifecycle action records audit proof and leaves no accessible orphan file.

Tests for User Story 2

• T023 [P] [US2] For families classified SUPPORTED_NOW for hold, add failing tests proving held artifacts cannot be deleted, hard-deleted, or pruned; if review packs, stored reports, or any other high-risk family is classified DEFERRED or PRODUCT_DECISION_REQUIRED, record the no-runtime-mutation rationale instead of fabricating held fixtures.
• T024 [P] [US2] Add failing direct-execution authorization tests for delete/archive/expire/hold/unhold actions, including allowed actor, missing capability, wrong workspace, wrong managed environment, and customer reviewer.
• T025 [P] [US2] Add failing Filament action tests for destructive/high-impact lifecycle actions proving requiresConfirmation, disabled/hidden state, and server-side denial.
• T026 [P] [US2] Add failing audit tests proving lifecycle actions record actor, workspace, managed environment, artifact family, safe artifact reference, old state, new state, result, and failure reason.

Implementation for User Story 2

• T027 [US2] Add current-table lifecycle/hold/delete metadata migrations only where the lifecycle matrix classifies the behavior SUPPORTED_NOW, proves a current-release need, and no existing field can carry the behavior safely.
• T028 [US2] Implement bounded lifecycle transition services/actions on existing artifact owners; do not create a generic artifact registry or workflow engine.
• T029 [US2] Update Filament lifecycle actions only on existing artifact owner surfaces, using Action::make(...)->action(...), ->requiresConfirmation(), policy/gate authorization, and audit proof.
• T030 [US2] Update retention/prune commands so held artifacts are skipped for SUPPORTED_NOW hold families, delete behavior is explicit, deferred families preserve current behavior, and failures do not mark artifacts as safely deleted when file/database work failed.
• T031 [US2] If irreversible purge or export-before-delete becomes necessary, stop and record follow-up-spec instead of implementing it inside Spec 406.

Phase 5: User Story 3 - Customer-safe exports and downloads remain bounded (Priority: P1)

Goal: Released customer-safe artifacts can be downloaded/exported only when valid and authorized; unreleased/internal/deleted/missing-file artifacts remain unavailable.

Independent Test: Customer reviewer can download a released customer-safe artifact and cannot access unreleased, internal, failed, deleted, expired-without-access, or missing-file artifacts.

Tests for User Story 3

• T032 [P] [US3] Add or update ReviewPackDownloadController tests for authorized, missing-capability, wrong-workspace, wrong-environment, customer reviewer, expired, deleted/blocked, failed, and missing-file cases.
• T033 [P] [US3] Add or update management-PDF download tests for StoredReport status/file/customer-output gate behavior and invalid file states.
• T034 [P] [US3] Add or update customer-safe output tests proving exports/downloads exclude internal-only evidence, raw provider payloads, raw source keys, OperationRun internals, stack traces, internal exception messages, system-only links, and cross-workspace data.
• T035 [P] [US3] Add signed-url/current-state regression tests proving an old signed URL re-checks current artifact lifecycle and file state before returning bytes.

Implementation for User Story 3

• T036 [US3] Harden review-pack and management-PDF download controllers so lifecycle state, customer-output gate, authorization, file existence, file size, disk/path, and hash expectations are re-checked at request time.
• T037 [US3] Harden export/download builders so customer-safe output is derived from released/customer-safe content only and raw/internal proof remains technical or support-gated.
• T038 [US3] Ensure deleted/failed/missing-file artifacts return safe denial or not-found responses and never stream partial/internal bytes.
• T039 [US3] Record customer-safe export/download proof in implementation-report.md.

Phase 6: User Story 4 - Retention behavior is deterministic (Priority: P2)

Goal: Retention jobs/actions expire or archive only eligible artifacts, skip held artifacts for SUPPORTED_NOW hold families, and report product-decision gaps instead of inventing broad purge behavior.

Independent Test: Retention logic updates only eligible artifacts, remains idempotent, skips held artifacts for SUPPORTED_NOW hold families, and records audit/OperationRun proof according to existing conventions.

Tests for User Story 4

• T040 [P] [US4] Add or update prune/retention command tests for review packs, stored reports, and any other family classified SUPPORTED_NOW for retention/hold covering eligible, not-yet-eligible, held where applicable, wrong-workspace, already-terminal, missing-file, and command retry cases.
• T041 [P] [US4] Add tests for configured retention values and explicit defaults without legal/compliance claims.
• T042 [P] [US4] Add tests proving retention cleanup does not delete core audit trails or OperationRun proof unless a specific existing contract permits it.

Implementation for User Story 4

• T043 [US4] Update retention commands/jobs only where tests prove lifecycle gaps; keep behavior idempotent and family-local.
• T044 [US4] Add query-backed indexes only if retention scans or hold-state checks require them and document write-overhead risk.
• T045 [US4] Record scheduler, queue, config/env, storage, and Dokploy deployment impact in implementation-report.md.

Phase 7: Browser Proof And Product Sanity

Purpose: Prove representative rendered behavior and customer-safe boundaries.

• T046 Run focused browser proof for authorized review-pack detail/download state.
• T047 Run focused browser proof for held artifact delete blocked state on an existing owner surface only for families classified SUPPORTED_NOW for hold; otherwise record the matrix-backed N/A rationale without claiming proof.
• T048 Run focused browser proof for customer-review released artifact access and unreleased/internal artifact denial.
• T049 Run focused browser proof for missing-file or deleted/expired artifact not being offered as valid download.
• T050 Record route/surface, actor/role, workspace/environment, artifact type, lifecycle state, expected result, actual result, console/runtime/network result, and screenshot/artifact path where relevant.
• T051 Complete Human Product Sanity and record purpose clarity, one dominant next action, technical detail demotion, canonical status labels, visible complexity outcome, and trust result.
• T052 Review docs/ui-ux-enterprise-audit/route-inventory.md and docs/ui-ux-enterprise-audit/design-coverage-matrix.md; update them if rendered surface scope materially changed, or record a checked no-update rationale in implementation-report.md.

Phase 8: Final Validation And Close-Out

Purpose: Confirm the package is ready for review and no unrelated work entered the slice.

• T053 Run git diff --check from repo root and record result.
• T054 Run cd apps/platform && ./vendor/bin/sail pint --dirty or repo-equivalent formatting for changed PHP files.
• T055 Run focused Spec406 test command, e.g. cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec406, and record result.
• T056 Run targeted existing family tests for ReviewPack, StoredReport/management PDF, Evidence, CustomerReviewWorkspace, OperationRun, and Findings touched by the implementation.
• T057 Run PostgreSQL lane if migrations/indexes/constraints are added, and record exact command/result.
• T058 Run focused browser proof and record exact command/result, or exact blocker without claiming proof.
• T059 Verify reports, logs, screenshots, generated artifacts, and fixtures do not include secrets, tokens, raw credential payloads, sensitive provider payloads, customer data, private URLs, or stack traces.
• T060 Complete all implementation-report sections, including lifecycle matrix, Spec 404/405 condition carry-forward assessment, per-family hold/delete support classification, runtime changes, migrations, tests, browser proof, authorization/customer-safe proof, file/database consistency, retention/hold/delete proof, findings, deferred items, validation commands, and next step.
• T061 Set final Spec 406 gate result to PASS, PASS WITH CONDITIONS, or FAIL according to remaining P0/P1 lifecycle risk; do not set PASS when a required hold/delete or Spec 404/405 carry-forward condition remains unresolved for a high-risk touched path.
• T062 Confirm the final response states Livewire v4 compliance, provider registration location, global search posture, destructive/high-impact action posture, asset strategy, tests/browser result, deployment impact, visible complexity outcome, no completed-spec rewrite assertion, and explicit application implementation status.

Non-Goals Checklist

• NT001 Do not add a new customer portal, artifact portal, export center, panel, navigation entry, or broad product module.
• NT002 Do not introduce legal compliance claims such as GDPR-compliant retention, legally defensible deletion, audit-certified archive, or regulatory-grade lifecycle.
• NT003 Do not create a generic artifact registry table, universal lifecycle framework, purge platform, or workflow engine.
• NT004 Do not rewrite evidence/currentness semantics from Spec 403, PDF runtime behavior from Spec 404, JSONB storage behavior from Spec 405, or read-only lifecycle close-out from Spec 267.
• NT005 Do not change Graph/provider integration, backup/restore semantics, authorization model, global search posture, or panel/provider registration unless this spec is updated.
• NT006 Do not remove, uncheck, normalize, or rewrite completed historical specs or implementation reports.
• NT007 Do not claim Spec 404/405 staging, production, PDF-runtime, storage, or Dokploy readiness unless proven in Spec 406 or explicitly ruled not applicable in the implementation report.

Dependencies And Execution Order

• Phase 1 and Phase 2 must complete before runtime edits.
• User Stories 1, 2, and 3 are P1 and should all pass before a full PASS gate.
• User Story 4 can be PASS WITH CONDITIONS only when residual retention decisions are safe, documented, and not P0/P1 for high-risk artifacts.
• Browser proof and Human Product Sanity must complete before close-out when rendered behavior changed.

Parallel Execution Examples

• T007 through T012 can run in parallel by artifact family.
• T016 through T019 can run in parallel by test family after matrix rows are drafted.
• T023 through T026 can run in parallel by action/audit/authorization concern.
• T032 through T035 can run in parallel by controller/customer-safe path.

Recommended Implementation Strategy

Start with the lifecycle matrix and only implement defects that are classified as P0/P1 or required to satisfy high-risk artifact proof. Keep hold/delete/export behavior family-local and current-owner based. If the implementation discovers an irreversible purge, export-before-delete, or customer-portal requirement, split it into a follow-up instead of widening Spec 406.