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

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

- [x] T001 Read `specs/406-governance-artifact-lifecycle-retention/spec.md`, `plan.md`, `tasks.md`, and `checklists/requirements.md`.
- [x] 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`.
- [x] 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`.
- [x] 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.
- [x] T005 Confirm completed Spec 267 implementation close-out, checked task history, browser proof, and deferred mutation decision are not edited, normalized, unchecked, or removed.
- [x] 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.

- [x] 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.
- [x] 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.
- [x] 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.
- [x] 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.
- [x] 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.
- [x] T012 Inventory finding, risk exception, accepted-risk decision, and governance inbox artifact behavior in `FindingException`, `FindingExceptionDecision`, related resources/services, and findings tests.
- [x] 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.
- [x] 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`.
- [x] 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

- [x] 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.
- [x] 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.
- [x] 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.
- [x] T025 [P] [US2] Add failing Filament action tests for destructive/high-impact lifecycle actions proving `requiresConfirmation`, disabled/hidden state, and server-side denial.
- [x] 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.
- [x] T028 [US2] Implement bounded lifecycle transition services/actions on existing artifact owners; do not create a generic artifact registry or workflow engine.
- [x] 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.
- [x] 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

- [x] 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.
- [x] 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

- [x] 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.
- [x] T038 [US3] Ensure deleted/failed/missing-file artifacts return safe denial or not-found responses and never stream partial/internal bytes.
- [x] 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.

- [x] T046 Run focused browser proof for authorized review-pack detail/download state.
- [x] 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.
- [x] 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.
- [x] 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.
- [x] 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.

- [x] T053 Run `git diff --check` from repo root and record result.
- [x] T054 Run `cd apps/platform && ./vendor/bin/sail pint --dirty` or repo-equivalent formatting for changed PHP files.
- [x] T055 Run focused Spec406 test command, e.g. `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec406`, and record result.
- [x] T056 Run targeted existing family tests for ReviewPack, StoredReport/management PDF, Evidence, CustomerReviewWorkspace, OperationRun, and Findings touched by the implementation.
- [x] T057 Run PostgreSQL lane if migrations/indexes/constraints are added, and record exact command/result.
- [x] T058 Run focused browser proof and record exact command/result, or exact blocker without claiming proof.
- [x] 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.
- [x] 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.
- [x] 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.
- [x] 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

- [x] NT001 Do not add a new customer portal, artifact portal, export center, panel, navigation entry, or broad product module.
- [x] NT002 Do not introduce legal compliance claims such as GDPR-compliant retention, legally defensible deletion, audit-certified archive, or regulatory-grade lifecycle.
- [x] NT003 Do not create a generic artifact registry table, universal lifecycle framework, purge platform, or workflow engine.
- [x] 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.
- [x] NT005 Do not change Graph/provider integration, backup/restore semantics, authorization model, global search posture, or panel/provider registration unless this spec is updated.
- [x] NT006 Do not remove, uncheck, normalize, or rewrite completed historical specs or implementation reports.
- [x] 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.