TenantAtlas/specs/356-review-pack-pdf-html-renderer-v1/tasks.md

description
Task list for Review Pack PDF/HTML Renderer v1

Tasks: Review Pack PDF/HTML Renderer v1

Input: Design documents from specs/356-review-pack-pdf-html-renderer-v1/
Prerequisites: spec.md, plan.md, and checklists/requirements.md

Tests: REQUIRED (Pest). Keep proof bounded to existing Feature families around EnvironmentReview, ReviewPack including ReviewPackResourceTest.php, and Reviews, plus one bounded browser smoke over the current customer-review workspace handoff path. Operations: Reuse the existing ReviewPackGenerate OperationRun path only. Preview/download of rendered output remains read-only. No new run type, queue family, or renderer-specific lifecycle is allowed. RBAC: Workspace/environment non-members remain 404; current in-scope review/review-pack view denials remain 403 where the existing contract already does so. No new capability family may be introduced. Shared Pattern Reuse: Reuse ReviewPackService, GenerateReviewPackJob, ReviewPackDownloadController, CustomerReviewWorkspace, ViewEnvironmentReview, ReviewPackResource, current artifact-truth/report disclosure, and current localization files. Do not create a second artifact family or a second report engine. Filament / Panel Guardrails: Filament remains v5 on Livewire v4. Provider registration remains unchanged in apps/platform/bootstrap/providers.php. No new panel, no new global-search surface, and no new asset strategy are allowed. Organization: Tasks are grouped by user story so the rendered-report contract, the printable-delivery boundary, and the authorization/audit boundaries stay independently implementable and testable.

Test Governance Checklist

• Lane assignment stays confidence plus one explicit browser smoke and remains the narrowest sufficient proof.
• New or changed tests stay in the smallest honest family, and any browser addition beyond one bounded smoke is explicit.
• Shared helpers, factories, seeds, and context defaults stay cheap by default.
• Planned validation commands cover the slice without pulling unrelated lane cost.
• The affected surfaces remain the current review/review-pack owner surfaces plus one bounded rendered report.
• Any material PDF-support gap resolves as document-in-feature or follow-up-spec, not as hidden dependency growth.

Productization Patch Addendum (2026-06-05)

Status: Complete. Validation and screenshots are complete, and no P0/P1/P2 report-productization findings remain open.

• P356-001 Move report actions into an external toolbar and hide toolbar/app controls from print CSS.
• P356-002 Add readiness-aware hero states for customer-safe ready, limitations, internal/PII, and not-ready output.
• P356-003 Add a management-readable Executive Summary with overall state, reason, impact, next action, and top limitations.
• P356-004 Replace dominant raw limitation/evidence state copy with human report language and move technical details to the supporting appendix.
• P356-005 Add EN/DE localization keys and fallback handling so rendered reports do not expose localization.* keys.
• P356-006 Compact empty/zero-heavy findings, accepted-risk, decision, and next-action sections.
• P356-007 Move the appendix to the end and label it as supporting/auditor context without raw JSON dump presentation.
• P356-008 Improve accepted-risk display with status, expiry/review state, customer-safe summary, safe owner display, and internal-rationale guardrails.
• P356-009 Improve evidence-basis copy so missing/partial/stale/complete states explain shareability and operator next action.
• P356-010 Add controlled repo-backed MSP co-branding slots from workspace/environment names and TenantPilot generated-by copy only.
• P356-011 Make rendered report and download labels readiness-aware without forbidden customer-ready/certified/approved/share labels.
• P356-012 Prove the rendered report uses stored DB-local truth and no Graph/provider calls during render.
• P356-013 Preserve existing ZIP review-pack download/export behavior alongside the rendered HTML/print report.
• P356-014 Complete full requested validation, browser screenshots, and final productization analysis before any close recommendation.

Phase 1: Setup (Shared Context)

Purpose: Confirm the current review-pack contract, current delivery seams, and current PDF-support reality before implementation changes begin.

• T001 Review specs/356-review-pack-pdf-html-renderer-v1/spec.md, plan.md, tasks.md, and checklists/requirements.md together with specs/263-auditor-pack-executive-export/spec.md, specs/347-review-pack-output-contract-readiness-semantics/spec.md, specs/349-customer-review-workspace-output-resolution-guidance/spec.md, specs/351-review-output-resolve-actions-v1/spec.md, and specs/355-platform-sellable-smoke-matrix/spec.md.
• T002 [P] Confirm the current review-derived delivery contract in apps/platform/app/Services/ReviewPackService.php and apps/platform/app/Jobs/GenerateReviewPackJob.php.
• T003 [P] Confirm the current read-only customer-safe delivery seams in apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php, apps/platform/app/Filament/Resources/EnvironmentReviewResource/Pages/ViewEnvironmentReview.php, apps/platform/app/Filament/Resources/ReviewPackResource.php, apps/platform/app/Http/Controllers/ReviewPackDownloadController.php, and apps/platform/routes/web.php.
• T004 [P] Confirm current PDF/render support reality in apps/platform/composer.json, apps/platform/composer.lock, apps/platform/package.json, and any existing render-related runtime code. Record whether PDF can be supported without a new package.

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Lock the bounded renderer contract before owner-surface changes begin.

Critical: No user-story work should begin until this phase is complete.

• T005 [P] Extend apps/platform/tests/Feature/EnvironmentReview/EnvironmentReviewExecutivePackTest.php and apps/platform/tests/Feature/ReviewPack/EnvironmentReviewDerivedReviewPackTest.php to require a rendered HTML report contract over the current review-derived pack truth.
• T006 [P] Extend apps/platform/tests/Feature/EnvironmentReview/EnvironmentReviewExplanationSurfaceTest.php, apps/platform/tests/Feature/EnvironmentReview/EnvironmentReviewUiContractTest.php, apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php, and apps/platform/tests/Feature/ReviewPack/ReviewPackResourceTest.php to lock rendered-output disclosure, one dominant action, and truthful readiness wording across owner surfaces.
• T007 [P] Extend apps/platform/tests/Feature/ReviewPack/ReviewPackDownloadTest.php, apps/platform/tests/Feature/ReviewPack/ReviewPackResourceTest.php, and any new focused render-route test only if needed to prove rendered preview/download authorization and audit continuity.
• T008 [P] Extend apps/platform/tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php or add one bounded equivalent browser smoke proving the current workspace -> released review -> rendered report handoff.
• T009 Lock the render seam as one new read-only controller/view route under the current /admin/review-packs/{reviewPack}/... family while the existing signed route stays ZIP-download-only.
• T010 Lock the HTML-first / PDF-conditional boundary in code comments, tests, and task notes: if current repo support cannot produce PDF without a new package, the implementation must stay HTML-first and keep PDF unavailable honestly.

Checkpoint: The current ReviewPack family, current run path, and current customer-safe owner surfaces are all locked to the bounded renderer contract before surface-level implementation begins.

---

Phase 3: User Story 1 - Open A Calm Rendered Review Report (Priority: P1)

Goal: An entitled user can open one calm rendered HTML report from the current released review/current pack context without unzipping JSON first.

Independent Test: From the current customer-review workspace/released-review flow, open the rendered output and verify it presents executive story, evidence basis, limitations, key findings, accepted risks, and non-certification disclosure without raw diagnostics by default.

Tests for User Story 1

• T011 [P] [US1] Extend apps/platform/tests/Feature/EnvironmentReview/EnvironmentReviewExecutivePackTest.php to prove rendered-report content matches current review/review-pack truth.
• T012 [P] [US1] Extend apps/platform/tests/Feature/EnvironmentReview/EnvironmentReviewExplanationSurfaceTest.php, apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php, and apps/platform/tests/Feature/ReviewPack/ReviewPackResourceTest.php to prove customer-safe rendered-report launch wording and appendix disclosure.

Implementation for User Story 1

• T013 [US1] Update apps/platform/app/Services/ReviewPackService.php and/or apps/platform/app/Jobs/GenerateReviewPackJob.php to expose one deterministic HTML rendered-report contract over the current review-derived EnvironmentReview/EnvironmentReviewSection/ReviewPack truth without adding a second artifact family or requiring archive re-parsing as the primary source.
• T014 [US1] Add a bounded rendered-report view under apps/platform/resources/views/review-packs/ or an equivalent current view seam so the executive story, evidence basis, limitations, key findings, accepted risks, governance decisions, next actions, and non-certification disclosure are human-readable.
• T015 [US1] Update apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php, apps/platform/app/Filament/Resources/EnvironmentReviewResource/Pages/ViewEnvironmentReview.php, apps/platform/app/Filament/Resources/ReviewPackResource.php, and any related Blade/infolist entries only where needed so one dominant rendered-output affordance is visible and current readiness wording stays truthful.

Checkpoint: The current review/review-pack surfaces can open one calm rendered HTML report without introducing a second delivery domain.

---

Phase 4: User Story 2 - Keep Printable Delivery Honest And Bounded (Priority: P1)

Goal: The same rendered contract supports a printable handoff path only when the repo can do so honestly; otherwise the product remains HTML-first without false PDF claims.

Independent Test: Verify that HTML is always available through the current owner surfaces and that PDF is either served from the same contract or explicitly unavailable without dependency growth.

Tests for User Story 2

• T016 [P] [US2] Extend apps/platform/tests/Feature/ReviewPack/ReviewPackDownloadTest.php, apps/platform/tests/Feature/ReviewPack/ReviewPackResourceTest.php, and any focused render-route test to prove HTML preview/download continuity and honest PDF availability semantics.
• T017 [P] [US2] Extend apps/platform/tests/Feature/EnvironmentReview/EnvironmentReviewUiContractTest.php and apps/platform/tests/Feature/ReviewPack/ReviewPackResourceTest.php to prove current owner surfaces do not expose a false PDF affordance.

Implementation for User Story 2

• T018 [US2] Update apps/platform/routes/web.php and the narrowest read-only controller seam to serve rendered HTML and, only when current repo support allows it, PDF from the same contract.
• T019 [US2] Update apps/platform/app/Services/ReviewPackService.php, apps/platform/app/Jobs/GenerateReviewPackJob.php, and localization copy only where needed so delivery metadata and copy say whether HTML only or HTML plus PDF are available.
• T020 [US2] If current repo support cannot produce PDF without a new package, keep HTML as the shipped v1 floor and record the bounded PDF follow-up instead of widening scope.

Checkpoint: Printable delivery remains honest and bounded to current repo truth.

---

Phase 5: User Story 3 - Keep Delivery Tenant-Safe, Auditable, And Derived (Priority: P2)

Goal: The rendered report stays on the current entitlement, audit, and derived-truth seams.

Independent Test: Non-members remain 404, in-scope viewers stay on current read-only permission paths, and rendered preview/download does not create a new run or audit family.

Tests for User Story 3

• T021 [P] [US3] Extend apps/platform/tests/Feature/ReviewPack/ReviewPackDownloadTest.php, apps/platform/tests/Feature/ReviewPack/ReviewPackResourceTest.php, and any focused render-route authorization test to confirm non-members and wrong-environment targets remain 404.
• T022 [P] [US3] Extend apps/platform/tests/Feature/EnvironmentReview/EnvironmentReviewUiContractTest.php, apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php, and apps/platform/tests/Feature/ReviewPack/ReviewPackResourceTest.php to prove owner surfaces stay on the current export/view authority model.
• T023 [P] [US3] Extend current audit-focused review-pack/review tests only if needed to confirm rendered preview/download stays on the existing audit family.

Implementation for User Story 3

• T024 [US3] Reuse or minimally extend current audit metadata in the current audit/review-pack seams only if rendered preview/download needs additional source-surface context; do not add a new audit family.
• T025 [US3] Reuse current review-pack/review entitlement checks for rendered preview/download and confirm no renderer-specific OperationRun, capability family, or persistence family appears.
• T026 [US3] Confirm the implementation does not add a new panel, new global-search surface, new asset strategy, new package, or second artifact family. If any of those become necessary, stop and split the scope.

Checkpoint: Rendered delivery remains attributable, tenant-safe, and derived from current truth only.

---

Phase 6: Polish & Cross-Cutting Validation

Purpose: Validate the bounded slice, complete required UI audit follow-through, and stop without widening scope.

• T027 [P] Update docs/ui-ux-enterprise-audit/route-inventory.md, docs/ui-ux-enterprise-audit/design-coverage-matrix.md, docs/ui-ux-enterprise-audit/strategic-surfaces.md, docs/ui-ux-enterprise-audit/unresolved-pages.md, and the relevant docs/ui-ux-enterprise-audit/page-reports/... entries so the changed Review Pack detail surface and the new rendered-report route are coverage-consistent and UI-042 no longer remains falsely unresolved.
• T028 [P] Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/EnvironmentReview/EnvironmentReviewExecutivePackTest.php tests/Feature/EnvironmentReview/EnvironmentReviewExplanationSurfaceTest.php tests/Feature/EnvironmentReview/EnvironmentReviewUiContractTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php tests/Feature/ReviewPack/EnvironmentReviewDerivedReviewPackTest.php tests/Feature/ReviewPack/ReviewPackDownloadTest.php tests/Feature/ReviewPack/ReviewPackResourceTest.php.
• T029 [P] Run one bounded browser smoke for the current customer-review workspace -> released review -> rendered report handoff.
• T030 [P] Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Localization/CustomerReviewSurfaceLocalizationTest.php if rendered-output copy or localized labels change.
• T031 [P] Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent.
• T032 [P] Run git diff --check.
• T033 [P] Review touched code to confirm Filament stays on Livewire v4, provider registration remains unchanged in apps/platform/bootstrap/providers.php, no global-search contract changes appear, and no new asset strategy is introduced.
• T034 [P] Record explicitly whether PDF landed from current repo support or whether the slice shipped HTML-first with a documented follow-up.

---

Non-Goals Checklist

• NT001 Do not add a customer portal, public share links, or email delivery.
• NT002 Do not add a new AuditorPack, RenderedReport, or other second artifact family.
• NT003 Do not add a PDF dependency or a second rendering engine.
• NT004 Do not add a new queue family, OperationRun, capability family, or audit family.
• NT005 Do not recompose review truth from live provider calls or raw provider APIs during render.
• NT006 Do not widen the slice into localization-wide cleanup, governance inbox work, or workspace-shell redesign.