TenantAtlas/specs/379-management-report-pdf-runtime/tasks.md

Tasks: Spec 379 - Management Report PDF Runtime Validation & Generation Completion

Input: specs/379-management-report-pdf-runtime/spec.md, specs/379-management-report-pdf-runtime/plan.md Prerequisites: Spec and plan are complete. Spec 378 renderer/gateway baseline is merged and treated as read-only context. Spec 379 is the sole active implementation package for post-G012 runtime validation and downstream Management Report PDF generation completion; unchecked Spec 378 downstream tasks are historical baseline signals only. Tests: Required. Use Pest 4 Unit, Feature, Filament/Livewire action tests, Browser/content smoke, and PostgreSQL lane if schema/indexes are introduced.

Test Governance Checklist

• Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
• New or changed tests stay in the smallest honest family, and any browser addition is explicit.
• Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default.
• Planned validation commands cover the change without pulling in unrelated lane cost.
• The high-impact artifact action and report-viewer surface profiles are explicit.
• Any material budget, baseline, trend, or escalation note is recorded in the active spec or PR.

Phase 1: Setup And Repo Verification

Purpose: Confirm baseline and stop before unsafe generation work.

• T001 Record branch, HEAD, dirty state, and Spec 379 touched-file baseline in specs/379-management-report-pdf-runtime/artifacts/runtime-validation.md.
• T002 Re-read specs/378-management-report-pdf-v1/spec.md, specs/378-management-report-pdf-v1/plan.md, specs/378-management-report-pdf-v1/tasks.md, and renderer artifacts without editing Spec 378.
• T003 [P] Verify Spec 378 runtime files exist: docker-compose.yml, apps/platform/config/tenantpilot.php, and apps/platform/app/Services/Pdf/PdfRenderingGateway.php.
• T004 [P] Verify Spec 378 gateway regression coverage in apps/platform/tests/Unit/Pdf/Spec378PdfRenderingGatewayTest.php.
• T005 [P] Verify current report source paths in apps/platform/app/Http/Controllers/ReviewPackRenderedReportController.php, apps/platform/resources/views/review-packs/rendered-report.blade.php, and apps/platform/app/Support/ReviewPacks/ReportProfileRegistry.php.
• T006 [P] Verify current disclosure/theme paths in apps/platform/app/Support/ReviewPacks/ReportDisclosurePolicy.php and apps/platform/app/Support/ReviewPacks/ReportThemeResolver.php.
• T007 [P] Verify current Review Pack readiness/download paths in apps/platform/app/Services/ReviewPackService.php, apps/platform/app/Jobs/GenerateReviewPackJob.php, and the Review Pack download controller.
• T008 Verify current apps/platform/app/Models/StoredReport.php and StoredReportResource posture before choosing artifact storage.
• T009 Verify current OperationRunService, OperationRunType, OperationCatalog, OperationRunLinks, and OperationUxPresenter before adding or mapping report generation.
• T010 Verify current audit action ID/logger patterns for review pack generation/download and decide whether distinct management PDF generation/download IDs are required; if existing IDs would obscure PDF-vs-ZIP semantics, plan distinct stable AuditActionId entries before audit implementation.
• T011 Decide the first owner surface for v1 generation and record the decision in specs/379-management-report-pdf-runtime/artifacts/storage-operationrun-decision.md.

Phase 2: Runtime Validation Gate

Purpose: Validate existing Gotenberg runtime controls before generation enablement.

• T012 Confirm the pinned Gotenberg service image, no-public-port posture, health check, timeout/body-limit/concurrency controls, and outbound/file-access posture from docker-compose.yml.
• T013 Validate staging/Dokploy runtime controls using the deployed container/runtime path and record pass/fail evidence in specs/379-management-report-pdf-runtime/artifacts/runtime-validation.md.
• T014 If staging/Dokploy runtime validation cannot be completed, add a blocked-generation implementation note and ensure generation remains disabled or unavailable until validation passes.
• T015 Confirm docs/deployment-checklist.md remains accurate for PDF renderer runtime validation or update it during implementation if runtime controls changed.

Phase 3: Tests First

Purpose: Add focused failing or pending proof before implementation.

• T016 [P] Add coverage for runtime validation decision mapping in apps/platform/tests/Feature/ReviewPack/Spec379ManagementReportPdfTest.php.
• T017 [P] Add coverage for management report payload chapters in apps/platform/tests/Feature/ReviewPack/Spec379ManagementReportPdfTest.php.
• T018 [P] Add coverage proving customer_executive disclosure excludes raw/internal content in apps/platform/tests/Feature/ReviewPack/Spec379ManagementReportPdfTest.php.
• T019 [P] Add Unit coverage for readiness blockers: missing source, non-current pack, expired pack, invalid profile, disclosure blocker, renderer unavailable, and storage unavailable.
• T020 [P] Add Feature coverage for authorized generation from a ready source in apps/platform/tests/Feature/ReviewPack/Spec379ManagementReportPdfTest.php.
• T021 [P] Add Feature coverage for artifact metadata/storage provenance in apps/platform/tests/Feature/ReviewPack/Spec379ManagementReportPdfTest.php.
• T022 [P] Add Feature coverage for generation audit and failed/blocked generation evidence in apps/platform/tests/Feature/ReviewPack/Spec379ManagementReportPdfTest.php.
• T023 [P] Add Feature coverage for download audit and private file response in apps/platform/tests/Feature/ReviewPack/Spec379ManagementReportPdfTest.php.
• T024 [P] Add authorization coverage for wrong workspace, wrong environment, and no membership returning deny-as-not-found.
• T025 [P] Add authorization coverage for scoped member without ENVIRONMENT_REVIEW_MANAGE or REVIEW_PACK_MANAGE on generation and without REVIEW_PACK_VIEW on download returning 403 after scope is established.
• T026 Add Filament/Livewire action coverage for the selected owner surface action visibility, disabled reason, confirmation, queued/run link, and download state.
• T027 Add Browser/content smoke coverage in apps/platform/tests/Browser/Spec379ManagementReportPdfSmokeTest.php, creating or reusing the narrow fixture needed to generate/download one customer-executive PDF artifact.
• T028 Add content assertions that generated PDF text includes required management chapters and excludes forbidden strings including SQLSTATE, access token, client secret, raw Graph payload, internal_msp_review, serialized job markers, and signed URLs.

Phase 4: Payload, Readiness, And Disclosure

Goal: Build customer-safe PDF content from existing source truth only. Independent Test: Unit tests prove required chapters, blockers, and disclosure behavior without storage or UI.

• T029 [US2] Implement a bounded management report payload builder under apps/platform/app/Support/ReviewPacks/ or the closest existing report namespace.
• T030 [US2] Build payload only from existing ReviewPack, EnvironmentReview, review sections, evidence summaries, findings/accepted-risk summaries, and rendered-report support truth.
• T031 [US2] Resolve profile through ReportProfileRegistry and default to the repo-canonical customer-executive profile.
• T032 [US2] Apply ReportDisclosurePolicy before rendering and fail closed for unknown or unsupported profile input.
• T033 [US2] Add readiness/blocked mapping for source missing, not current, expired, not ready, evidence limitation, disclosure blocker, runtime validation missing, renderer unavailable, storage unavailable, and unauthorized actor.
• T034 [US2] Ensure payload building performs no Graph/provider calls and no Blade/PDF template database queries.
• T035 [US2] Keep next actions derived from existing review/finding/evidence/report data; do not invent AI or unsupported recommendations.

Phase 5: Artifact Storage And Idempotency

Goal: Persist or reference the generated PDF without a new report center. Independent Test: Feature tests prove source/profile/file provenance and no partial-ready artifact exposure.

• T036 [US2] Decide whether existing artifact/report storage can represent the PDF; record the decision in specs/379-management-report-pdf-runtime/artifacts/storage-operationrun-decision.md.
• T037 [US2] If current fields are insufficient, add a narrow reversible migration under apps/platform/database/migrations/ for existing artifact/report substrate fields only.
• T038 [US2] If extending StoredReport, add only required fields/constants/casts/relationships in apps/platform/app/Models/StoredReport.php; if StoredReportResource is touched, keep global search disabled unless the spec is updated first.
• T039 [US2] Ensure newly persisted tenant-owned artifact truth carries constitution-compliant workspace and managed-environment scope, and tenant scope where required by current table ownership rules.
• T040 [US2] Store PDF files on a private disk/path with safe generated filenames.
• T041 [US2] Implement source/profile/fingerprint idempotency or explicitly document separate-artifact generation behavior.
• T042 [US2] Prevent ready/downloadable artifact exposure when rendering or storage fails before commit.
• T043 [US2] Run PostgreSQL lane if migrations, JSONB indexes, or constraints are added.

Phase 6: OperationRun And Audit

Goal: Make generation observable and accountable. Independent Test: Feature tests prove queued/running/succeeded/blocked/failed outcomes and audit metadata.

• T044 [US2] Add or map a canonical operation type for management report PDF generation only if no existing type honestly fits.
• T045 [US2] Update OperationCatalog, labels, actionability, and tests if a new operation type is added.
• T046 [US2] Queue generation through OperationRunService and the shared OperationRun start UX path.
• T047 [US2] Dispatch generation work to an existing or new bounded job under apps/platform/app/Jobs/ with identifiers only, no raw payload secrets.
• T048 [US2] Mark success, renderer failure, storage failure, blocked source, and unauthorized cases through OperationRunService with safe reason codes/messages.
• T049 [US2] Keep summary_counts flat numeric-only and use existing keys where counts are needed.
• T050 [US2] Record generation audit with a stable management-PDF action ID, actor, workspace, managed environment, source review/pack, artifact/report id, operation run id, profile, format, generated time, and redacted metadata; add AuditActionId case/label/summary when no exact existing ID fits.
• T051 [US3] Record download audit with a stable management-PDF action ID, actor, workspace, managed environment, artifact/report id, source review/pack, profile, format, downloaded time, and redacted request metadata; add AuditActionId case/label/summary when no exact existing ID fits.
• T052 [US2] Verify audit metadata excludes secrets, signed URLs, raw provider payloads, raw operation context, stack traces, and SQL errors.

Phase 7: Owner Action And Download Route

Goal: Expose one clear, safe generation/download flow. Independent Test: Filament/Feature tests prove action state, confirmation, authorization, download, and scope denial.

• T053 [US2] Add Generate management PDF to the selected owner surface using Action::make(...)->action(...).
• T054 [US2] Apply server-side authorization inside the action handler using ENVIRONMENT_REVIEW_MANAGE for an Environment Review owner surface or REVIEW_PACK_MANAGE for a Review Pack owner surface; UI state is not security.
• T055 [US2] Add explicit Filament confirmation with clear copy explaining durable customer-facing artifact creation.
• T056 [US2] Show disabled/blocked reasons for source not ready, expired, not current, profile/disclosure blocked, runtime validation missing, renderer unavailable, storage unavailable, unauthorized, or already running.
• T057 [US2] If generation is queued/running, show only the canonical View operation link through existing helpers.
• T058 [US3] If a ready PDF already exists, prefer Download management PDF or equivalent over duplicate generation.
• T059 [US3] Implement a signed and/or server-authorized PDF download route/controller only if existing routes cannot safely represent PDF format/profile/artifact identity.
• T060 [US3] In the download route/controller, re-resolve workspace, managed environment, source review/pack, artifact status, and REVIEW_PACK_VIEW capability before returning bytes.
• T061 [US3] Set safe PDF response headers and filenames without making internal IDs the primary label.
• T062 [US3] Keep existing Review Pack ZIP download behavior unchanged.

Phase 8: PDF Rendering And Localization

Goal: Render a customer-safe PDF through the approved gateway only. Independent Test: Content smoke proves required chapters and forbidden-content absence.

• T063 [US2] Implement the management PDF renderer adapter through PdfRenderingGateway only.
• T064 [US2] Render cover, executive summary, governance posture, key decisions, top risks/findings, accepted risks, evidence readiness, limitations, next actions, provenance, and method summary.
• T065 [US2] Include generated timestamp, source review/pack metadata, profile, and classification/confidentiality marker.
• T066 [US2] Include header/footer and page numbering where supported by the approved renderer.
• T067 [US2] Avoid remote fonts, external assets, public images, and network-dependent resources.
• T068 [US2] Limit management-safe findings and defer deep tables/appendices to future Technical/Auditor report specs.
• T069 [US2] Ensure renderer errors produce safe results that map to OperationRun blocked/failed outcomes.
• T070 [US2] Add EN localization keys for action labels, notifications, blocked reasons, chapter titles, limitations, and provenance labels.
• T071 [US2] Add DE localization keys for the same report/action labels.
• T072 [US2] Use existing locale-aware date/time/number conventions where available.

Phase 9: UI Coverage And Documentation-In-Feature

Purpose: Satisfy UI-COV without broad docs churn.

• T073 Apply UI coverage rules: update route inventory for any new PDF route, UI-099 for PDF/report content changes, UI-042 for Review Pack action/download changes, UI-048 for StoredReport exposure, and design coverage matrix for material action/artifact changes.
• T074 If no material coverage artifact change is needed, record the checked no-update rationale in implementation close-out.
• T075 Store browser screenshots/content evidence under specs/379-management-report-pdf-runtime/artifacts/screenshots/ if captured.
• T076 Record final storage substrate, OperationRun type, owner surface, runtime validation, and UI coverage decisions in specs/379-management-report-pdf-runtime/artifacts/storage-operationrun-decision.md.

Phase 10: Validation

Purpose: Prove Spec 379 and prevent adjacent report/runtime regressions.

• T077 Run cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec379.
• T078 Run cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec378.
• T079 Run cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec357.
• T080 Run cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec366.
• T081 Run focused Review Pack/resource regressions selected from touched owner surface files.
• T082 Run cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec379ManagementReportPdfSmokeTest.php --compact.
• T083 Run PostgreSQL lane if migrations, JSONB indexes, constraints, or artifact storage fields require it.
• T084 Run cd apps/platform && ./vendor/bin/sail pint --dirty.
• T085 Run git diff --check.
• T086 Static scan changed runtime files for Livewire v3 APIs and confirm none were introduced.
• T087 Static scan changed runtime files for Graph/provider calls during render/generation/download and confirm none were introduced.
• T088 Static scan changed runtime files for duplicate PDF renderer/client/config/service/package additions and confirm none were introduced.
• T089 Complete final close-out with Livewire v4 compliance, provider registration location, global-search status, high-impact action status, asset strategy, tests, and deployment impact.

Non-Goals

• NT001 Do not create a second PDF renderer, second Gotenberg service, second PDF config, or second PDF client/gateway.
• NT002 Do not add Composer/NPM PDF packages, Puppeteer, Browsershot, dompdf, wkhtmltopdf, Playwright production rendering, or browser binaries in Laravel containers.
• NT003 Do not redo package-governance for Gotenberg unless the approved renderer changes.
• NT004 Do not build Technical Evidence Report or Auditor Evidence Report.
• NT005 Do not build Report Delivery Center, scheduled delivery, email/Teams delivery, public links, or customer portal.
• NT006 Do not build invoice, billing, XRechnung, ZUGFeRD, tax, or legal archive functionality.
• NT007 Do not redesign Customer Review Workspace, dashboard, or navigation.
• NT008 Do not add AI-generated summaries or AI report drafting.
• NT009 Do not change Review Pack ZIP download behavior.
• NT010 Do not add a broad artifact lifecycle/retention framework.
• NT011 Do not call Microsoft Graph/provider APIs during PDF render, generation, or download.
• NT012 Do not rewrite completed historical specs or remove close-out/validation evidence from related specs.

Dependencies And Ordering

• T001-T011 must complete before runtime edits.
• T012-T015 must complete before generation can be enabled.
• Tests in Phase 3 should be added before or alongside implementation.
• Payload/readiness/disclosure must complete before rendering.
• Artifact storage and OperationRun/audit must complete before download exposure.
• Browser/content smoke runs after owner action and download route are usable.
• Validation and close-out run last.

Parallel Opportunities

• T003-T007 can run in parallel during verification.
• T016-T025 can be developed in parallel once fixture shape is known.
• T070-T072 can run after visible labels are known.
• T077-T080 can run in parallel once implementation is stable.

Implementation Strategy

1. Validate existing runtime first.
2. Prove behavior with tests before implementation.
3. Reuse existing rendered-report/profile/disclosure truth.
4. Use the approved PDF gateway only.
5. Keep artifact persistence narrow and private.
6. Use OperationRun and audit as generation/download accountability.
7. Expose one owner-surface action and one safe download path.
8. Validate content, leakage boundaries, and no infrastructure duplication.