ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/366-management-report-layout-branded-report-themes-v1/tasks.md
ahmido f37056e1de feat: implement management report layout branded report themes (#437) 
Implemented management report layout branded report themes as requested.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #437
2026-06-08 03:35:20 +00:00

24 KiB
Raw Permalink Blame History

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

  • 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 the Browser smoke addition is explicit.
  • Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented.
  • Planned validation commands cover the change without pulling in unrelated lane cost.
  • The declared surface test profile is report-viewer / customer-facing artifact surface.
  • 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.

  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.

  • 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.
  • 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.
  • T013 [P] Add apps/platform/tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php cases proving limited/internal/PII reports never render as customer-safe or externally approved.
  • 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.
  • 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.
  • T016 [P] Add apps/platform/tests/Browser/Spec366ManagementReportLayoutSmokeTest.php using existing Spec357 browser helper conventions where practical.
  • 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.
  • 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.

  • T019 [P] [US1] Add customer-executive ready-state assertions to apps/platform/tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php.
  • T020 [P] [US1] Add limited-state and internal-state assertions to apps/platform/tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • T026 [US1] Keep mandatory disclosure data from apps/platform/app/Support/ReviewPacks/ReportDisclosurePolicy.php visible in the report after first-screen changes.
  • 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.

  • T028 [P] [US2] Add profile-order assertions for customer_executive and customer_technical to apps/platform/tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php.
  • T029 [P] [US2] Add profile-order assertions for internal_msp_review and auditor_appendix to apps/platform/tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php.
  • T030 [P] [US2] Add fallback assertions for unknown or placeholder profile requests to apps/platform/tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php.
  • 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.
  • 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.
  • T033 [US2] Keep customer_executive appendix minimal in apps/platform/resources/views/review-packs/rendered-report.blade.php or the new report partials.
  • 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.
  • T035 [US2] Ensure internal_msp_review renders internal warning and operator limitations clearly in apps/platform/resources/views/review-packs/rendered-report.blade.php.
  • 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.

  • 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.
  • 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.
  • 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.
  • T040 [US3] If ReportThemeResolver.php is created, keep it derived-only: no model, no table, no config write, no upload, no cache across requests.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.

  • 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.
  • 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.
  • 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/.
  • 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/.
  • 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/.
  • 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.
  • 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.
  • 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.

  • 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.
  • 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.
  • T056 Update apps/platform/tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php to assert no localization. key appears in rendered output.
  • 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.

  • 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.
  • 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.
  • 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.
  • 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.

  • T062 Run cd apps/platform && ./vendor/bin/sail artisan test tests/Unit/Support/ReviewPacks/Spec366ReportThemeContractTest.php --compact.
  • T063 Run cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php --compact.
  • T064 Run cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec366ManagementReportLayoutSmokeTest.php --compact.
  • T065 Run cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec356.
  • T066 Run cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec357.
  • T067 Run cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ReviewPack.
  • T068 Run cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=EnvironmentReview.
  • T069 Run cd apps/platform && ./vendor/bin/sail pint --dirty.
  • T070 Run git diff --check.
  • 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.
  • 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.
  • T073 Confirm Livewire v4.0+ compliance remains unchanged and no Livewire v3 APIs were introduced in changed files under apps/platform/.
  • 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.
  • T075 Confirm no destructive/high-impact report action was added; report toolbar actions remain read-only navigation/download/print.
  • 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.
  • 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

  • NT001 Do not rebuild the Review Pack renderer.
  • NT002 Do not create a second report renderer.
  • NT003 Do not change Review Pack ZIP/download contracts.
  • NT004 Do not add a native PDF package or dependency.
  • NT005 Do not build report profile CRUD or persisted report themes.
  • NT006 Do not add logo upload, image storage, or a theme editor.
  • NT007 Do not add customer portal, public sharing links, scheduled delivery, email/Teams delivery, or approval workflow.
  • NT008 Do not add AI-generated narratives or HITL AI review.
  • NT009 Do not add NIS2, BSI, CIS, or other framework-specific report semantics.
  • 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:

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.