TenantAtlas/specs/406-governance-artifact-lifecycle-retention/implementation-report.md

# Spec 406 Implementation Report - Governance Artifact Lifecycle & Retention

## 1. Candidate Gate Result

Result: `PASS WITH CONDITIONS` candidate selected by operator.

Spec 406 is approved as a bounded lifecycle hardening slice over existing governance artifacts. It does not approve a generic artifact registry, new portal, export center, legal/eDiscovery claim, purge platform, new navigation entry, or broad lifecycle framework.

## 2. Dirty State

- Branch: `406-governance-artifact-lifecycle-retention`
- Baseline HEAD: `686947d2 feat: harden json to jsonb data layer for trust payloads (#476)`
- Initial working tree: untracked `specs/406-governance-artifact-lifecycle-retention/`; no tracked file modifications before implementation edits.
- Initial `git diff --check`: pass.
- Completed-spec rewrite assertion: Specs 158, 262, 267, 400, 403, 404, and 405 are read-only context. Their completed task markers, implementation reports, browser proof, and validation history were not edited.

## 3. Spec 404/405 Carry-Forward

- Spec 404 remains `PASS WITH CONDITIONS` for external Staging/Dokploy validation. Spec 406 may prove local management-report PDF lifecycle/download behavior, but it does not claim Staging/Dokploy readiness.
- Spec 405 remains `PASS WITH CONDITIONS` for external Staging/Dokploy validation. Spec 406 touches no JSON/JSONB conversion path and carries no storage-engine readiness claim beyond existing local test proof.
- Neither remaining condition blocks the narrow Spec 406 local hardening of review-pack download consistency, review-pack lifecycle action authorization/audit, and matrix/report truth.

## 4. Governance Artifact Lifecycle Matrix

| Family | Current owner/source | File dependency | Customer-safe boundary | Lifecycle/file rules | Hold/delete support | Status | Risk/follow-up |
|---|---|---|---|---|---|---|---|
| Review packs | `ReviewPack`, `ReviewPackService`, `ReviewPackDownloadController`, `ReviewPackRenderedReportController`, `ReviewPackResource`, `PruneReviewPacksCommand` | Private `exports` disk, `file_disk`, `file_path`, `file_size`, `sha256` | `CustomerOutputGate` plus signed download/rendered report routes | Ready/non-expired/customer-safe packs may download or render only after current `exports`-disk existence, positive size, size match, and SHA-256 match. Expired/queued/failed/missing/tampered/wrong-disk files fail closed. Spec 406 hardens size/SHA/wrong-disk checks and action audit. | Expire supported now. Hard-delete via prune exists after grace. Hold remains `PRODUCT_DECISION_REQUIRED`; no hold columns/actions added. | `PASS WITH CONDITIONS` | Follow-up required for legal hold/export-before-delete/purge governance. |
| Stored reports / management PDFs | `StoredReport`, `ManagementReportPdfService`, `ManagementReportPdfDownloadController`, `StoredReportResource`, `PruneStoredReportsCommand` | Private `exports` disk, PDF bytes, `file_size`, `sha256` | Source review pack must be current, released, customer-safe, and downloadable by actor | Existing controller validates ready metadata, review-pack state/currentness, file existence, size, valid PDF bytes, and SHA before streaming. | Delete via retention prune exists. Hold is `PRODUCT_DECISION_REQUIRED`; no hold columns/actions added. | `PASS WITH CONDITIONS` | Local lifecycle/download proof exists; external Spec 404 Staging/Dokploy condition carries forward. |
| Evidence snapshots | `EvidenceSnapshot`, `EvidenceSnapshotService`, `EvidenceSnapshotResource`, evidence currentness/anchor services | Database-backed evidence rows; no downloadable artifact file in this slice | Customer-facing review output consumes summarized/released evidence, not raw evidence by default | Existing service supports expiration and audit; currentness remains separate from review-pack release proof. No file-download lifecycle added. | Expire supported now. Delete/hold/purge are `DEFERRED`. | `PASS WITH EXCEPTION` | Follow-up only if evidence deletion/hold becomes a product decision. |
| Customer review retained output | `CustomerReviewWorkspace`, review-pack rendered report/download routes, `CustomerOutputGate` | Review pack ZIP and management PDF when available | Customer/read-only surface must hide raw evidence, OperationRun internals, source keys, fingerprints, and provider payloads | Existing tests cover released/customer-safe visibility, unsafe/internal denial, and customer-safe copy boundaries. Spec 406 inherits this and adds review-pack file consistency proof. | No mutation surface. Hold/delete N/A on customer surface. | `PASS WITH CONDITIONS` | Browser proof still required for representative rendered path. |
| OperationRun proof | `OperationRun`, operation detail/resources, OperationRun UX contracts | No artifact file by default | Internal proof only unless an existing product contract exposes derived artifact output | Execution status/outcome remains execution truth and must not become artifact lifecycle truth. No lifecycle mutation implemented here. | Delete/hold/purge `DEFERRED`; not an artifact owner in this slice. | `DEFERRED` | Retain current internal proof posture; no new customer exposure. |
| Finding exceptions / accepted risks / governance inbox artifacts | `FindingException`, `FindingExceptionDecision`, finding exception services/resources, customer review summaries | Database-backed decisions and evidence references | Customer review output may show customer-safe accepted-risk summary only; internal rationale remains hidden | Existing workflows authorize lifecycle decisions and audit request/approve/reject/renew/revoke actions. No file-backed download lifecycle in this slice. | Decision lifecycle supported. Delete/hold/purge `DEFERRED`. | `PASS WITH EXCEPTION` | Follow-up only if accepted-risk deletion/retention semantics need dedicated product behavior. |

## 5. Runtime Changes

- `ReviewPackService` now owns review-pack file-download validation through `resolveDownloadableArtifact()` / `hasDownloadableArtifact()`. The rule requires `ready`, non-expired lifecycle state, `exports` disk, a present file path, positive stored size, present SHA-256, private-disk existence, exact size match, and SHA-256 byte match before any surface treats a ZIP as downloadable.
- `ReviewPackDownloadController` delegates byte validation to `ReviewPackService` and streams only the already validated bytes. Signed URLs continue to re-check current lifecycle, authorization, customer-output gate, file presence, size, disk, and hash at request time.
- `ReviewPackRenderedReportController` and `CustomerOutputGate` now use the same downloadable-artifact validation before rendering customer/internal report views or offering the toolbar download URL, so rendered-report signed URLs also fail closed after tampering, missing bytes, wrong disk, or expiry.
- `ReviewPackService::expire()` centralizes the ReviewPack expire transition. It requires tenant scope, `REVIEW_PACK_MANAGE`, actor tenant access, ready status, private-file delete verification, and audit proof through `review_pack.expired`.
- `ReviewPackResource` and `ViewReviewPack` now hide review-pack download actions when the private artifact fails validation and share the same customer-output/internal-preview URL parameter logic, so visible table downloads do not point at a server-denied stream mode. The destructive expire action remains a Filament action with confirmation, server-side capability enforcement, file delete, and audit logging.
- `CustomerReviewWorkspace` now uses the same downloadable-artifact validation for customer-safe download URLs and review-pack availability state, so a ready record with missing/tampered/wrong-disk bytes is not shown as a valid customer download.
- `AuditActionId` includes `review_pack.expired` labels/summaries.
- No database migrations, new tables, new lifecycle framework, new navigation, new panel, new assets, or new runtime dependencies were added.

## 6. Tests Added Or Updated

- `ReviewPackDownloadTest` covers invalid file metadata/bytes (`zero-byte`, size mismatch, SHA mismatch, missing SHA, wrong disk), verifies old signed download URLs re-check current lifecycle before streaming bytes, and verifies rendered-report signed URLs re-check artifact integrity before rendering.
- `ReviewPackRbacTest` covers owner expire behavior, confirmation state, export-disk file deletion, wrong-disk non-deletion, audit metadata, and direct service denial for a read-only actor.
- `ReviewPackResourceTest` now creates realistic export-disk fixtures for positive download UI tests, covers the table download URL for internal previews, and covers hidden list/detail download actions when a ready pack fails hash validation.
- `CustomerReviewWorkspacePackAccessTest` now creates realistic customer-safe artifact fixtures and covers a ready customer-safe pack with tampered bytes being shown as not configured without a download action.
- Fixtures remain feature-local. No global artifact matrix harness or broad artifact registry test framework was introduced.

## 7. Browser Proof

- Command: `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec379ManagementReportPdfSmokeTest.php`
- Result: `1 passed (18 assertions)`, re-run after the ReviewPack table download URL/internal-preview fix.
- Surface: existing ReviewPack detail / management-report PDF smoke path.
- Actor/role: authorized admin test user from the existing browser smoke.
- Artifact type/state: ready ReviewPack detail surface with management-report PDF action state.
- Expected/actual: rendered surface remained available and action layout remained valid after ReviewPack download visibility was tightened.
- Console/runtime/network: no failing browser assertions; no screenshot artifact emitted on pass.
- Held artifact browser proof: `N/A` for Spec 406 implementation. Hold support for review packs, stored reports, OperationRun proof, evidence snapshots, and accepted-risk/finding decision artifacts remains `PRODUCT_DECISION_REQUIRED` or `DEFERRED`; no hold/delete UI was added.
- Missing/tampered-file browser proof: covered by Feature/Livewire tests rather than an additional browser proof in this slice; no new visible surface was introduced, only existing download/rendered-report affordances are hidden or denied.

## 8. Product Surface Close-Out

- Runtime UI files changed: `ReviewPackResource`, `ViewReviewPack`, and `CustomerReviewWorkspace`.
- UI impact: existing ReviewPack download actions and rendered-report toolbar downloads become stricter and disappear when the private artifact is not actually downloadable. Existing customer workspace package availability now fails closed for tampered/missing/wrong-disk ZIPs.
- Product Surface exceptions: none.
- Human Product Sanity: pass. Purpose remains clear, the dominant next action is unchanged, technical diagnostics remain demoted, and canonical customer labels remain `Ready`, `Running`, `Failed`, `Expired`, `Blocked`, `Needs attention`, and `Not configured`.
- Visible complexity outcome: neutral. No new page, navigation entry, panel, card stack, portal, export center, or extra customer-facing action was added.
- No-legacy posture: canonical lifecycle hardening over current pre-production behavior.
- Route inventory / design coverage matrix: no update. Existing routes/surfaces were tightened; no new rendered route or page archetype was introduced.

## 9. Filament / Livewire / Deployment Close-Out

- Livewire v4 compliance: Livewire 4.1.4 confirmed by Laravel Boost application info.
- Provider registration location: Laravel 12 panel providers remain in `apps/platform/bootstrap/providers.php`; no provider registration changes.
- Global search posture: no new globally searchable resource. `ReviewPackResource` remains `$isGloballySearchable = false`; it has a View page, but global search stays disabled.
- Destructive/high-impact actions: `expire` remains `Action::make(...)->action(...)` with `requiresConfirmation()`, `REVIEW_PACK_MANAGE` authorization, tenant access checks, file delete verification, and audit proof. No destructive URL-only action was added.
- Asset strategy: no new assets, no `FilamentAsset::register()`, and no new on-demand asset. No additional `filament:assets` requirement beyond the existing deployment baseline.
- Deployment impact: code-only. No migrations, env vars, queues, scheduler changes, storage volume changes, reverse proxy changes, or Dokploy configuration changes. Existing private `exports` disk must remain persistent and private.

## 10. Validation Commands

- `php -l apps/platform/app/Services/ReviewPackService.php` - pass.
- `php -l apps/platform/app/Http/Controllers/ReviewPackDownloadController.php` - pass.
- `php -l apps/platform/app/Http/Controllers/ReviewPackRenderedReportController.php` - pass.
- `php -l apps/platform/app/Support/ReviewPacks/CustomerOutputGate.php` - pass.
- `php -l apps/platform/app/Filament/Resources/ReviewPackResource.php` - pass.
- `php -l apps/platform/app/Filament/Resources/ReviewPackResource/Pages/ViewReviewPack.php` - pass.
- `php -l apps/platform/tests/Feature/ReviewPack/ReviewPackDownloadTest.php` - pass.
- `php -l apps/platform/tests/Feature/ReviewPack/ReviewPackRbacTest.php` - pass.
- `php -l apps/platform/tests/Feature/ReviewPack/ReviewPackResourceTest.php` - pass.
- `php -l apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php` - pass.
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPack/ReviewPackDownloadTest.php --filter=Spec406` - `7 passed (14 assertions)`.
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPack/ReviewPackRbacTest.php --filter=Spec406` - `1 passed (6 assertions)`.
- `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec406` - `8 passed (20 assertions)`.
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPack/ReviewPackResourceTest.php --filter='shows the download action for a ready pack'` - `1 passed (6 assertions)`.
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPack/ReviewPackResourceTest.php` - `23 passed (121 assertions)`.
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPack/ReviewPackDownloadTest.php tests/Feature/ReviewPack/ReviewPackRbacTest.php tests/Feature/ReviewPack/ReviewPackResourceTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php` - `67 passed (352 assertions)`.
- Earlier focused runs before post-review hardening: `ReviewPackDownloadTest` - `22 passed (129 assertions)`, `ReviewPackResourceTest` - `23 passed (117 assertions)`, `CustomerReviewWorkspacePackAccessTest` - `8 passed (55 assertions)`, `ReviewPackRbacTest` - `12 passed (39 assertions)`, `--filter=Spec406` - `6 passed (12 assertions)`.
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec379ManagementReportPdfSmokeTest.php` - `1 passed (18 assertions)`.
- `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` - pass.
- `git diff --check` - pass.
- PostgreSQL lane: `N/A`; no migrations, indexes, or constraints were added.

## 11. Findings And Gate Result

- Final gate result: `PASS WITH CONDITIONS`.
- Confirmed defect fixed: ready ReviewPack records with missing/tampered/wrong-disk/zero-byte artifacts could still be treated as downloadable by some UI paths or rendered-report signed URLs after URL creation. Runtime now fails closed and UI does not offer those as valid downloads or rendered reports.
- Confirmed defect fixed: ReviewPack list downloads for internal-only packs could render a visible action without the required `internal_preview=1` signed URL parameter. List and detail downloads now share the same stream-mode URL logic.
- Confirmed defect fixed: ReviewPack expire action logic was page-local and did not emit a dedicated lifecycle audit action. Runtime now uses a service transition with authorization, file delete verification, and `review_pack.expired` audit metadata.
- Local residual risk closed: focused browser proof was re-run after the final table-link fix and remains passing.
- Remaining condition: legal hold, export-before-delete, broad purge, and cross-family deletion governance remain product decisions. No hold columns/actions were added.
- Remaining condition: Spec 404 and Spec 405 external Staging/Dokploy validation conditions carry forward; Spec 406 does not claim production deployment proof.
- `PASS` without conditions is intentionally not claimed because SC-406-002 and T061 require `PASS WITH CONDITIONS` when high-risk artifact families remain `DEFERRED` / `PRODUCT_DECISION_REQUIRED` for hold/delete or when Spec 404/405 carry-forward conditions remain unresolved.
- Reports/logs/generated artifacts review: no secrets, tokens, raw credential payloads, sensitive provider payloads, private URLs, customer data, or stack traces were added to report/test fixtures.
- Post-implementation analysis: changes stayed bounded to existing ReviewPack/customer-workspace surfaces, avoided a generic artifact registry/workflow engine, preserved customer-safe boundaries, and did not rewrite completed historical specs.