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

- [X] Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
- [X] New or changed tests stay in the smallest honest family, and any browser addition is explicit.
- [X] Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default.
- [X] Planned validation commands cover the change without pulling in unrelated lane cost.
- [X] The high-impact artifact action and report-viewer surface profiles are explicit.
- [X] 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.

- [X] T001 Record branch, HEAD, dirty state, and Spec 379 touched-file baseline in `specs/379-management-report-pdf-runtime/artifacts/runtime-validation.md`.
- [X] 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.
- [X] T003 [P] Verify Spec 378 runtime files exist: `docker-compose.yml`, `apps/platform/config/tenantpilot.php`, and `apps/platform/app/Services/Pdf/PdfRenderingGateway.php`.
- [X] T004 [P] Verify Spec 378 gateway regression coverage in `apps/platform/tests/Unit/Pdf/Spec378PdfRenderingGatewayTest.php`.
- [X] 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`.
- [X] T006 [P] Verify current disclosure/theme paths in `apps/platform/app/Support/ReviewPacks/ReportDisclosurePolicy.php` and `apps/platform/app/Support/ReviewPacks/ReportThemeResolver.php`.
- [X] 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.
- [X] T008 Verify current `apps/platform/app/Models/StoredReport.php` and `StoredReportResource` posture before choosing artifact storage.
- [X] T009 Verify current `OperationRunService`, `OperationRunType`, `OperationCatalog`, `OperationRunLinks`, and `OperationUxPresenter` before adding or mapping report generation.
- [X] 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.
- [X] 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.

- [X] 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`.
- [X] 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.
- [X] 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.

- [X] T016 [P] Add coverage for runtime validation decision mapping in `apps/platform/tests/Feature/ReviewPack/Spec379ManagementReportPdfTest.php`.
- [X] T017 [P] Add coverage for management report payload chapters in `apps/platform/tests/Feature/ReviewPack/Spec379ManagementReportPdfTest.php`.
- [X] T018 [P] Add coverage proving `customer_executive` disclosure excludes raw/internal content in `apps/platform/tests/Feature/ReviewPack/Spec379ManagementReportPdfTest.php`.
- [X] T019 [P] Add Unit coverage for readiness blockers: missing source, non-current pack, expired pack, invalid profile, disclosure blocker, renderer unavailable, and storage unavailable.
- [X] T020 [P] Add Feature coverage for authorized generation from a ready source in `apps/platform/tests/Feature/ReviewPack/Spec379ManagementReportPdfTest.php`.
- [X] T021 [P] Add Feature coverage for artifact metadata/storage provenance in `apps/platform/tests/Feature/ReviewPack/Spec379ManagementReportPdfTest.php`.
- [X] T022 [P] Add Feature coverage for generation audit and failed/blocked generation evidence in `apps/platform/tests/Feature/ReviewPack/Spec379ManagementReportPdfTest.php`.
- [X] T023 [P] Add Feature coverage for download audit and private file response in `apps/platform/tests/Feature/ReviewPack/Spec379ManagementReportPdfTest.php`.
- [X] T024 [P] Add authorization coverage for wrong workspace, wrong environment, and no membership returning deny-as-not-found.
- [X] 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.
- [X] T026 Add Filament/Livewire action coverage for the selected owner surface action visibility, disabled reason, confirmation, queued/run link, and download state.
- [X] 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.
- [X] 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.

- [X] T029 [US2] Implement a bounded management report payload builder under `apps/platform/app/Support/ReviewPacks/` or the closest existing report namespace.
- [X] T030 [US2] Build payload only from existing `ReviewPack`, `EnvironmentReview`, review sections, evidence summaries, findings/accepted-risk summaries, and rendered-report support truth.
- [X] T031 [US2] Resolve profile through `ReportProfileRegistry` and default to the repo-canonical customer-executive profile.
- [X] T032 [US2] Apply `ReportDisclosurePolicy` before rendering and fail closed for unknown or unsupported profile input.
- [X] 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.
- [X] T034 [US2] Ensure payload building performs no Graph/provider calls and no Blade/PDF template database queries.
- [X] 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.

- [X] 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`.
- [X] T037 [US2] If current fields are insufficient, add a narrow reversible migration under `apps/platform/database/migrations/` for existing artifact/report substrate fields only.
- [X] 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.
- [X] 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.
- [X] T040 [US2] Store PDF files on a private disk/path with safe generated filenames.
- [X] T041 [US2] Implement source/profile/fingerprint idempotency or explicitly document separate-artifact generation behavior.
- [X] T042 [US2] Prevent ready/downloadable artifact exposure when rendering or storage fails before commit.
- [X] 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.

- [X] T044 [US2] Add or map a canonical operation type for management report PDF generation only if no existing type honestly fits.
- [X] T045 [US2] Update `OperationCatalog`, labels, actionability, and tests if a new operation type is added.
- [X] T046 [US2] Queue generation through `OperationRunService` and the shared OperationRun start UX path.
- [X] T047 [US2] Dispatch generation work to an existing or new bounded job under `apps/platform/app/Jobs/` with identifiers only, no raw payload secrets.
- [X] T048 [US2] Mark success, renderer failure, storage failure, blocked source, and unauthorized cases through `OperationRunService` with safe reason codes/messages.
- [X] T049 [US2] Keep `summary_counts` flat numeric-only and use existing keys where counts are needed.
- [X] 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.
- [X] 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.
- [X] 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.

- [X] T053 [US2] Add `Generate management PDF` to the selected owner surface using `Action::make(...)->action(...)`.
- [X] 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.
- [X] T055 [US2] Add explicit Filament confirmation with clear copy explaining durable customer-facing artifact creation.
- [X] 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.
- [X] T057 [US2] If generation is queued/running, show only the canonical `View operation` link through existing helpers.
- [X] T058 [US3] If a ready PDF already exists, prefer `Download management PDF` or equivalent over duplicate generation.
- [X] 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.
- [X] 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.
- [X] T061 [US3] Set safe PDF response headers and filenames without making internal IDs the primary label.
- [X] 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.

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

- [X] 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.
- [X] T074 If no material coverage artifact change is needed, record the checked no-update rationale in implementation close-out.
- [X] T075 Store browser screenshots/content evidence under `specs/379-management-report-pdf-runtime/artifacts/screenshots/` if captured.
- [X] 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.

- [X] T077 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec379`.
- [X] T078 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec378`.
- [X] T079 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec357`.
- [X] T080 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec366`.
- [X] T081 Run focused Review Pack/resource regressions selected from touched owner surface files.
- [X] T082 Run `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec379ManagementReportPdfSmokeTest.php --compact`.
- [X] T083 Run PostgreSQL lane if migrations, JSONB indexes, constraints, or artifact storage fields require it.
- [X] T084 Run `cd apps/platform && ./vendor/bin/sail pint --dirty`.
- [X] T085 Run `git diff --check`.
- [X] T086 Static scan changed runtime files for Livewire v3 APIs and confirm none were introduced.
- [X] T087 Static scan changed runtime files for Graph/provider calls during render/generation/download and confirm none were introduced.
- [X] T088 Static scan changed runtime files for duplicate PDF renderer/client/config/service/package additions and confirm none were introduced.
- [X] 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

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