# Tasks: Spec 366 - Management Report Layout & Branded Report Themes v1 **Input**: Design documents from `/specs/366-management-report-layout-branded-report-themes-v1/` **Prerequisites**: `spec.md`, `plan.md`, `checklists/requirements.md` **Tests**: Required. This feature changes an existing customer-facing rendered report surface. Use Pest 4 Unit, Feature, and one bounded Browser smoke. Keep Browser proof explicit and limited to Spec 366. **Operations**: No new `OperationRun` start/completion/link behavior is in scope. Existing Review Pack generation behavior must remain unchanged. **RBAC**: Existing Review Pack rendered-report authorization remains authoritative. Preserve workspace/environment entitlement, deny-as-not-found for non-members/out-of-scope records, and 403 for members missing `REVIEW_PACK_VIEW`. **UI / Surface Guardrails**: This is a customer-facing report viewer surface. The implementation must update UI/productization coverage docs or record a proportional no-update rationale in close-out. **Filament v5 / Livewire v4**: No panel provider change is planned. Livewire v4.0+ compliance must be preserved; do not introduce Livewire v3 APIs. ## 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 the Browser smoke addition is explicit. - [x] Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented. - [x] Planned validation commands cover the change without pulling in unrelated lane cost. - [x] The declared surface test profile is `report-viewer / customer-facing artifact surface`. - [x] Any material budget, baseline, trend, or escalation note is recorded in the active spec or close-out. ## Phase 1: Setup and Repo Verification **Purpose**: Re-confirm the baseline and keep the implementation from reopening completed report foundations. - [x] T001 Re-read `specs/366-management-report-layout-branded-report-themes-v1/spec.md`, `specs/366-management-report-layout-branded-report-themes-v1/plan.md`, and `specs/366-management-report-layout-branded-report-themes-v1/checklists/requirements.md` before runtime changes. - [x] T002 [P] Re-read completed context only in `specs/356-review-pack-pdf-html-renderer-v1/spec.md`, `specs/356-review-pack-pdf-html-renderer-v1/plan.md`, `specs/357-report-profiles-disclosure-policy-v1/spec.md`, and `specs/357-report-profiles-disclosure-policy-v1/plan.md`; do not rewrite those packages. - [x] T003 Confirm branch/worktree intent with `git status --short --branch` and record the baseline commit in `specs/366-management-report-layout-branded-report-themes-v1/repo-truth-map.md`. - [x] T004 [P] Inspect current report seams in `apps/platform/app/Http/Controllers/ReviewPackRenderedReportController.php`, `apps/platform/resources/views/review-packs/rendered-report.blade.php`, and `apps/platform/app/Services/ReviewPackService.php`. - [x] T005 [P] Inspect current profile/disclosure seams in `apps/platform/app/Support/ReviewPacks/ReportProfileRegistry.php`, `apps/platform/app/Support/ReviewPacks/ReportDisclosurePolicy.php`, `apps/platform/app/Support/ReviewPacks/ReviewPackOutputReadiness.php`, and `apps/platform/app/Support/ReviewPacks/ReviewPackOutputResolutionGuidance.php`. - [x] T006 [P] Inspect current owner-surface rendered-report links in `apps/platform/app/Filament/Resources/EnvironmentReviewResource.php`, `apps/platform/app/Filament/Resources/EnvironmentReviewResource/Pages/ViewEnvironmentReview.php`, `apps/platform/app/Filament/Resources/ReviewPackResource.php`, and `apps/platform/app/Filament/Resources/ReviewPackResource/Pages/ViewReviewPack.php`. - [x] T007 Record current report layout gaps, existing repo-backed metrics, optional branding fields, and fields that are not repo-backed in `specs/366-management-report-layout-branded-report-themes-v1/repo-truth-map.md`. - [x] T008 If current rendered-report screenshots are needed for implementation decisions, create `specs/366-management-report-layout-branded-report-themes-v1/current-report-layout-audit.md`; otherwise record in `repo-truth-map.md` why the audit artifact is not needed. - [x] T009 Confirm no migration, package, env var, queue family, scheduler change, storage-topology change, panel/provider change, global-search change, native PDF package, upload UI, customer portal, scheduled delivery, or AI/runtime work is required. - [x] T010 Confirm Filament v5 / Livewire v4.0+ compliance and that panel providers remain registered in `apps/platform/bootstrap/providers.php`. ## Phase 2: Foundational Tests and Guardrails **Purpose**: Add failing proof for theme/layout, report safety, profile behavior, print behavior, and screenshot smoke before implementation. - [x] T011 [P] Add `apps/platform/tests/Unit/Support/ReviewPacks/Spec366ReportThemeContractTest.php` covering prepared-by/prepared-for/generated-by fallbacks, generated-at formatting input, default accent/logo behavior, profile layout-mode mapping, and no persistence requirement. - [x] T012 [P] Add `apps/platform/tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php` covering rendered report cover/state/KPI/executive-summary order, semantic heading order, readable labels, mandatory disclosures, profile/audience metadata, toolbar-before-canvas, print CSS, and no localization key leakage. - [x] T013 [P] Add `apps/platform/tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php` cases proving limited/internal/PII reports never render as customer-safe or externally approved. - [x] T014 [P] Add `apps/platform/tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php` cases proving Review Pack ZIP/download behavior, current-export guard, expiry guard, and rendered-report authorization remain unchanged. - [x] T015 [P] Add `apps/platform/tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php` assertions that report render performs no Graph/provider calls by binding a fail-hard `GraphClientInterface`. - [x] T016 [P] Add `apps/platform/tests/Browser/Spec366ManagementReportLayoutSmokeTest.php` using existing Spec357 browser helper conventions where practical. - [x] T017 [P] Add browser flows in `apps/platform/tests/Browser/Spec366ManagementReportLayoutSmokeTest.php` for customer executive ready, customer executive limited, internal MSP, customer technical, auditor appendix, print-view class/CSS behavior, keyboard/focus basics, and mobile-ish width. - [x] T018 Add local Spec366 fixture/helper functions inside `apps/platform/tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php` and `apps/platform/tests/Browser/Spec366ManagementReportLayoutSmokeTest.php`; reuse Spec356/Spec357 patterns without introducing broad shared test defaults. ## Phase 3: User Story 1 - Management-Ready First Screen (Priority: P1) **Goal**: The report first screen answers who prepared it, who it is for, whether it is shareable, what the governance state is, what top metrics matter, and what should happen next. **Independent Test**: The Feature test renders ready and limited reports and asserts the cover/state/KPI/executive-summary hierarchy appears before appendix/detail content. - [x] T019 [P] [US1] Add customer-executive ready-state assertions to `apps/platform/tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php`. - [x] T020 [P] [US1] Add limited-state and internal-state assertions to `apps/platform/tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php`. - [x] T021 [US1] Update `apps/platform/app/Http/Controllers/ReviewPackRenderedReportController.php` to expose a stable management first-screen payload: hero, report identity, profile/audience, KPI/decision strip, executive story, evidence basis, top risks/decisions, and next action. - [x] T022 [US1] Ensure `apps/platform/app/Http/Controllers/ReviewPackRenderedReportController.php` derives KPI/decision strip values only from existing Review Pack summary, Environment Review, Evidence Snapshot, profile, and disclosure-policy data. - [x] T023 [US1] Update `apps/platform/resources/views/review-packs/rendered-report.blade.php` so the cover/state/KPI/executive summary render before limitations/evidence/appendix sections. - [x] T024 [US1] In `apps/platform/resources/views/review-packs/rendered-report.blade.php`, render unsupported metrics as omitted or "not measured" / "not available"; do not fake zero counts. - [x] T025 [US1] In `apps/platform/resources/views/review-packs/rendered-report.blade.php`, ensure default-visible report copy avoids raw state keys, implementation field names, provider payload terms, and localization keys. - [x] T026 [US1] Keep mandatory disclosure data from `apps/platform/app/Support/ReviewPacks/ReportDisclosurePolicy.php` visible in the report after first-screen changes. - [x] T027 [US1] Preserve existing source metadata, review id, review-pack id, profile, audience, generated timestamp, and TenantPilot-generated marker in `apps/platform/resources/views/review-packs/rendered-report.blade.php`. ## Phase 4: User Story 2 - Profile-Aware Report Hierarchy (Priority: P1) **Goal**: Existing Spec357 profiles produce visibly different report hierarchy while preserving disclosure and fail-closed behavior. **Independent Test**: Feature and Browser tests render all implemented profiles and verify section order, appendix prominence, and safety copy. - [x] T028 [P] [US2] Add profile-order assertions for `customer_executive` and `customer_technical` to `apps/platform/tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php`. - [x] T029 [P] [US2] Add profile-order assertions for `internal_msp_review` and `auditor_appendix` to `apps/platform/tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php`. - [x] T030 [P] [US2] Add fallback assertions for unknown or placeholder profile requests to `apps/platform/tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php`. - [x] T031 [US2] Update `apps/platform/app/Http/Controllers/ReviewPackRenderedReportController.php` to derive profile layout mode and section order from `apps/platform/app/Support/ReviewPacks/ReportProfileRegistry.php`. - [x] T032 [US2] If partialization improves reviewability, split profile sections from `apps/platform/resources/views/review-packs/rendered-report.blade.php` into `apps/platform/resources/views/review-packs/partials/report-cover.blade.php`, `report-state-hero.blade.php`, `report-kpi-strip.blade.php`, `report-executive-summary.blade.php`, `report-appendix.blade.php`, and `report-disclosure-footer.blade.php`. - [x] T033 [US2] Keep `customer_executive` appendix minimal in `apps/platform/resources/views/review-packs/rendered-report.blade.php` or the new report partials. - [x] T034 [US2] Make `auditor_appendix` evidence basis, section completeness, source metadata, and appendix content more prominent in `apps/platform/resources/views/review-packs/rendered-report.blade.php` or the new report partials. - [x] T035 [US2] Ensure `internal_msp_review` renders internal warning and operator limitations clearly in `apps/platform/resources/views/review-packs/rendered-report.blade.php`. - [x] T036 [US2] Preserve `ReportProfileRegistry` fail-closed behavior in `apps/platform/app/Support/ReviewPacks/ReportProfileRegistry.php`; do not broaden implemented profiles or add framework-report semantics. ## Phase 5: User Story 3 - Controlled Co-Branding and Theme Contract (Priority: P2) **Goal**: Text-only report co-branding uses existing workspace/environment truth and never weakens report safety or disclosure. **Independent Test**: Unit and Feature tests verify theme derivation, fallback behavior, and absence of upload/persistence/theme-editor behavior. - [x] T037 [P] [US3] Add unit assertions in `apps/platform/tests/Unit/Support/ReviewPacks/Spec366ReportThemeContractTest.php` for workspace name, environment name, missing-name fallback, generated-by, null logo, and default accent. - [x] T038 [P] [US3] Add feature assertions in `apps/platform/tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php` that branding does not hide state hero, limitations, profile/audience, source metadata, or non-certification disclosure. - [x] T039 [US3] Create `apps/platform/app/Support/ReviewPacks/ReportThemeResolver.php` only if implementation confirms a derived resolver is narrower and safer than controller-local theme data. - [x] T040 [US3] If `ReportThemeResolver.php` is created, keep it derived-only: no model, no table, no config write, no upload, no cache across requests. - [x] T041 [US3] If `ReportThemeResolver.php` is not created, document the narrower controller-local decision in `specs/366-management-report-layout-branded-report-themes-v1/repo-truth-map.md` and point `Spec366ReportThemeContractTest.php` at the actual derived shape. - [x] T042 [US3] Update `apps/platform/app/Http/Controllers/ReviewPackRenderedReportController.php` to resolve `prepared_by`, `prepared_for`, `generated_by`, `generated_at`, `accent`, and `logo` from existing workspace/environment/report truth or safe defaults. - [x] T043 [US3] In `apps/platform/resources/views/review-packs/rendered-report.blade.php`, render co-branding slots as text-first identity; do not add logo upload, image storage, or theme editor UI. - [x] T044 [US3] Verify optional logo/accent support in `apps/platform/app/Http/Controllers/ReviewPackRenderedReportController.php` stays null/default unless safe repo-backed fields already exist. - [x] T045 [US3] Ensure `apps/platform/resources/views/review-packs/rendered-report.blade.php` keeps TenantPilot generated metadata visible even when workspace/MSP branding is present. ## Phase 6: User Story 4 - Print, Screenshot, and Responsive Smoke (Priority: P2) **Goal**: The report can be printed and screenshotted without app/admin toolbar artifacts or visual overlap. **Independent Test**: Browser smoke captures profile and print-view screenshots, verifies toolbar-hidden print behavior, and asserts no JS/console errors. - [x] T046 [P] [US4] Add browser assertion in `apps/platform/tests/Browser/Spec366ManagementReportLayoutSmokeTest.php` that `data-testid="rendered-report-toolbar"` appears before `data-testid="rendered-report-canvas"` on screen and toolbar controls are keyboard-focusable. - [x] T047 [P] [US4] Add browser assertion in `apps/platform/tests/Browser/Spec366ManagementReportLayoutSmokeTest.php` that print-preview class or print CSS hides toolbar/screen-only controls while keeping report canvas and disclosure footer visible. - [x] T048 [P] [US4] Add browser screenshot capture for `01-customer-executive-report.png` and `02-customer-executive-limited-report.png` under `specs/366-management-report-layout-branded-report-themes-v1/artifacts/screenshots/`. - [x] T049 [P] [US4] Add browser screenshot capture for `03-internal-msp-report.png`, `04-customer-technical-report.png`, and `05-auditor-appendix-report.png` under `specs/366-management-report-layout-branded-report-themes-v1/artifacts/screenshots/`. - [x] T050 [P] [US4] Add browser screenshot capture for `06-print-view.png` and `07-report-toolbar-hidden-print.png` under `specs/366-management-report-layout-branded-report-themes-v1/artifacts/screenshots/`. - [x] T051 [US4] Update print CSS in `apps/platform/resources/views/review-packs/rendered-report.blade.php` or report partials so toolbar/screen-only controls are hidden and disclosure/source metadata remain visible. - [x] T052 [US4] Update report canvas CSS in `apps/platform/resources/views/review-packs/rendered-report.blade.php` or report partials to prevent text overlap and keep small/mobile-ish viewport stacking readable. - [x] T053 [US4] In `apps/platform/tests/Browser/Spec366ManagementReportLayoutSmokeTest.php`, assert `assertNoJavaScriptErrors()` and `assertNoConsoleLogs()` for all profile flows. ## Phase 7: Localization and Copy **Purpose**: Add only the required dominant report copy and keep EN/DE output free of raw keys. - [x] T054 [P] Add or update EN keys in `apps/platform/lang/en/localization.php` for prepared by, prepared for, generated by, report profile, governance status, KPI/decision strip, evidence coverage, open decisions, key risks, supporting appendix, not measured, not available, internal report, and external sharing warning. - [x] T055 [P] Add or update DE keys in `apps/platform/lang/de/localization.php` for the same keys added in `apps/platform/lang/en/localization.php`. - [x] T056 Update `apps/platform/tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php` to assert no `localization.` key appears in rendered output. - [x] T057 Update `apps/platform/tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php` to assert the report does not show "Certified report", "Approved compliance report", or "Share with customer" unless a future spec explicitly permits those terms. ## Phase 8: UI Coverage and Documentation Artifacts **Purpose**: Keep UI/Productization Coverage in sync without adding broad docs. - [x] T058 Inspect `docs/ui-ux-enterprise-audit/page-reports/ui-099-rendered-review-report.md` and update it if Spec 366 materially changes rendered-report hierarchy, profile behavior, or screenshot expectations. - [x] T059 Inspect `docs/ui-ux-enterprise-audit/design-coverage-matrix.md` and `docs/ui-ux-enterprise-audit/route-inventory.md`; update only if rendered-report classification or route coverage changes. - [x] T060 If coverage docs are not changed, record a proportional no-update rationale in `specs/366-management-report-layout-branded-report-themes-v1/repo-truth-map.md` or implementation close-out notes. - [x] T061 Do not create general documentation files outside required Spec Kit/UI coverage artifacts unless the implementation proves a specific existing registry artifact must be updated. ## Phase 9: Validation and Close-Out **Purpose**: Prove Spec 366 and adjacent report regressions before handoff. - [x] T062 Run `cd apps/platform && ./vendor/bin/sail artisan test tests/Unit/Support/ReviewPacks/Spec366ReportThemeContractTest.php --compact`. - [x] T063 Run `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php --compact`. - [x] T064 Run `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec366ManagementReportLayoutSmokeTest.php --compact`. - [x] T065 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec356`. - [x] T066 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec357`. - [x] T067 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ReviewPack`. - [x] T068 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=EnvironmentReview`. - [x] T069 Run `cd apps/platform && ./vendor/bin/sail pint --dirty`. - [x] T070 Run `git diff --check`. - [x] T071 Review the final diff for migrations, packages, env vars, queues, scheduler changes, storage topology changes, panel provider changes, global search changes, registered Filament assets, native PDF, upload UI, customer portal, scheduled delivery, AI, and compliance framework scope. - [x] T072 Confirm no new Filament assets were registered; if assets were registered unexpectedly, update `specs/366-management-report-layout-branded-report-themes-v1/plan.md` with the `filament:assets` deployment impact before merge. - [x] T073 Confirm Livewire v4.0+ compliance remains unchanged and no Livewire v3 APIs were introduced in changed files under `apps/platform/`. - [x] T074 Confirm globally searchable resources were not enabled or changed; if global search was touched unexpectedly, document View/Edit page safety or keep global search disabled. - [x] T075 Confirm no destructive/high-impact report action was added; report toolbar actions remain read-only navigation/download/print. - [x] T076 Confirm `specs/366-management-report-layout-branded-report-themes-v1/artifacts/screenshots/` contains required screenshots or a repo-based reason for any missing screenshot state. - [x] T077 Record implementation close-out notes in `specs/366-management-report-layout-branded-report-themes-v1/tasks.md` or the final implementation response: changed files, no-migration status, no-asset status, test results, browser smoke result, coverage-doc decision, and deferred follow-up candidates. ## Explicit Non-Goals - [x] NT001 Do not rebuild the Review Pack renderer. - [x] NT002 Do not create a second report renderer. - [x] NT003 Do not change Review Pack ZIP/download contracts. - [x] NT004 Do not add a native PDF package or dependency. - [x] NT005 Do not build report profile CRUD or persisted report themes. - [x] NT006 Do not add logo upload, image storage, or a theme editor. - [x] NT007 Do not add customer portal, public sharing links, scheduled delivery, email/Teams delivery, or approval workflow. - [x] NT008 Do not add AI-generated narratives or HITL AI review. - [x] NT009 Do not add NIS2, BSI, CIS, or other framework-specific report semantics. - [x] NT010 Do not hide or weaken mandatory disclosures, readiness, limitations, evidence state, internal-only warning, PII warning, or TenantPilot source metadata. ## Dependencies - Phase 1 must finish before tests and implementation. - Phase 2 tests should be added before Phase 3-6 implementation. - US1 and US2 are the MVP path and should land before US3/US4 refinements. - US3 depends on the theme/layout contract decision from Phase 2 and Phase 3. - US4 depends on the report canvas and section hierarchy from US1/US2. - Phase 7 localization can run alongside US1-US4 after new copy is known. - Phase 8 coverage close-out should happen after the runtime diff is known. - Phase 9 runs last. ## Parallel Execution Examples After Phase 1 verification: ```text T011, T012, T016 can run in parallel because they create different test files. T054 and T055 can run in parallel after copy keys are identified. T058 and T059 can run in parallel after runtime/UI changes are known. ``` ## Implementation Strategy 1. MVP first: US1 + US2 with route/feature tests proving management-ready and profile-aware layout. 2. Add co-branding/theme derivation only if it stays derived, local, and testable. 3. Add print/browser screenshot proof after the report layout is stable. 4. Keep every deferred idea as a follow-up spec rather than hidden scope. ## Expected Task Count - Total implementation tasks: 77 - Non-goal guardrails: 10 - MVP tasks: T001-T036 plus required validation subset T062-T070 ## Implementation Close-Out - Runtime changes stayed bounded to the existing rendered report route, derived report theme/layout support, localization copy, and one adjacent resolution-action mapping guard. - No migrations, packages, env vars, queues, scheduler changes, storage topology changes, panel provider changes, global-search changes, registered Filament assets, native PDF runtime, upload UI, customer portal, scheduled delivery, AI, or framework-specific report semantics were added. - UI coverage artifacts were updated for UI-099 and screenshot evidence was generated under `artifacts/screenshots/`. - Adjacent regression fixes were applied only where validation exposed stale or conflicting repo truth: - Spec347 browser fixture now stores the non-certification disclosure on the generated review pack summary. - `export_not_ready` no longer maps to `create_next_review`, preserving `export_executive_pack` as the primary published-review header action. - Validation completed: - `cd apps/platform && ./vendor/bin/sail artisan test tests/Unit/Support/ReviewPacks/Spec366ReportThemeContractTest.php --compact` - `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php --compact` - `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec366ManagementReportLayoutSmokeTest.php --compact` - `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec347ReviewPackOutputReadinessSmokeTest.php --compact` - `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament/EnvironmentReviewHeaderDisciplineTest.php --compact` - `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/EnvironmentReview/Spec351EnvironmentReviewResolveActionTest.php --compact` - `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/EnvironmentReview/Spec350EnvironmentReviewResolutionGuidanceTest.php --compact` - `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec357` - `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ReviewPack` - `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=EnvironmentReview` - `cd apps/platform && ./vendor/bin/sail pint --dirty` - `git diff --check` - `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec356` returned `No tests found`; the active adjacent rendered-report coverage is exercised through Spec357 and the new Spec366 browser/feature tests.