ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
c1f4ebaa05
TenantAtlas/specs/263-auditor-pack-executive-export/tasks.md
ahmido b05d5c52d4 spec(263): auditor-pack executive export - automated PR (#319) 
Automated PR: commit workspace changes for spec 263 (auditor-pack executive export). Created by Copilot automation.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #319
2026-05-02 10:02:07 +00:00

20 KiB
Raw Blame History

description
Task list for Auditor Pack Delivery & Executive Export v1

Tasks: Auditor Pack Delivery & Executive Export v1

Input: Design documents from specs/263-auditor-pack-executive-export/
Prerequisites: specs/263-auditor-pack-executive-export/spec.md, specs/263-auditor-pack-executive-export/plan.md, specs/263-auditor-pack-executive-export/checklists/requirements.md

Tests: REQUIRED (Pest). Keep proof bounded to existing Feature families around TenantReview, Reviews, and ReviewPack, plus the current CustomerReviewWorkspace browser smoke only. Operations: Reuse the existing ReviewPackGenerate OperationRun path and signed review-pack download route. No new run type, no new queue family, and no new export artifact family are allowed. RBAC: Workspace or tenant non-members remain 404; current in-scope review/export/download denials remain 403 where the existing review-pack contract already uses them. No new capability family may be introduced. Shared Pattern Reuse: Reuse CustomerReviewWorkspace, TenantReviewResource, ViewTenantReview, ReviewPackService, GenerateReviewPackJob, ReviewPackDownloadController, TenantReviewComposer, TenantReviewSectionFactory, ArtifactTruthPresenter, current localization files, and current audit IDs. Do not create a new AuditorPack or reporting subsystem. Filament / Panel Guardrails: Filament remains v5 on Livewire v4. Provider registration remains unchanged in apps/platform/bootstrap/providers.php. No new panel, no new globally searchable resource, and no new asset strategy are allowed. Organization: Tasks are grouped by user story so the bundle contract, the delivery disclosure, and the entitlement/audit boundaries stay independently implementable and testable. This package is a delta follow-up over Specs 258-260 and current code; broader customer-safe workspace/detail behavior is inherited unless a task explicitly changes it to explain the new bundle contract.

Test Governance Checklist

  • Lane assignment stays confidence plus the existing bounded browser smoke and remains the narrowest sufficient proof.
  • New or changed tests stay in the existing apps/platform/tests/Feature/TenantReview/, apps/platform/tests/Feature/Reviews/, and apps/platform/tests/Feature/ReviewPack/ families plus apps/platform/tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php.
  • Shared helpers, released-review fixtures, review-pack fixtures, and evidence fixtures stay cheap by default.
  • Planned validation commands cover bundle contents, disclosure, download continuity, and entitlement behavior without widening into unrelated lanes.
  • The declared surface test profile remains shared-detail-family.
  • Any drift toward a second artifact family, a PDF engine, or recurring delivery automation is handled as reject-or-split or follow-up-spec, not hidden inside this feature.

Phase 1: Setup (Shared Context)

Purpose: Confirm the current review-pack bundle, delivery wording, and entitlement seams before any implementation change.

  • T001 Review specs/263-auditor-pack-executive-export/spec.md, specs/263-auditor-pack-executive-export/plan.md, specs/263-auditor-pack-executive-export/checklists/requirements.md, specs/109-review-pack-export/spec.md, specs/153-evidence-domain-foundation/spec.md, specs/155-tenant-review-layer/spec.md, specs/258-customer-review-productization/spec.md, specs/259-compliance-evidence-mapping/spec.md, and specs/260-governance-service-packaging/spec.md together so the slice stays on the current bundle and delivery foundations.
  • T002 [P] Confirm the current operator export initiation seam in apps/platform/app/Filament/Resources/TenantReviewResource.php and apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php.
  • T003 [P] Confirm the current bundle generation and download seams in apps/platform/app/Services/ReviewPackService.php, apps/platform/app/Jobs/GenerateReviewPackJob.php, and apps/platform/app/Http/Controllers/ReviewPackDownloadController.php.
  • T004 [P] Confirm the current customer-safe delivery surfaces in apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php, apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php, and apps/platform/resources/views/filament/infolists/entries/tenant-review-summary.blade.php.

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Lock the bounded delivery contract before surface-level changes begin.

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

  • T005 [P] Extend apps/platform/tests/Feature/ReviewPack/TenantReviewDerivedReviewPackTest.php and apps/platform/tests/Feature/TenantReview/TenantReviewExecutivePackTest.php to require one human-readable executive entrypoint plus explicit delivery metadata inside the current review-derived pack while preserving the current ZIP baseline entries metadata.json, summary.json, and sections.json.
  • T006 [P] Extend apps/platform/tests/Feature/TenantReview/TenantReviewExportOperationsUxTest.php and apps/platform/tests/Feature/ReviewPack/ReviewPackDownloadTest.php to prove the feature still reuses the current ReviewPackGenerate path and the current signed download route rather than introducing a second artifact or download flow. Existing tests already covered this seam; the validation lane confirmed them unchanged.
  • T007 [P] Extend apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php, apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php, apps/platform/tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php, and apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php to lock delivery-readiness wording, one dominant action per surface, and the absence of raw/internal detail in the customer-safe default path. New wording/default-disclosure assertions landed in CustomerReviewWorkspacePageTest and TenantReviewExplanationSurfaceTest; existing pack-access and UI-contract tests remained the action-hierarchy guard.
  • T008 Implement the bundle-contract change in apps/platform/app/Services/ReviewPackService.php and apps/platform/app/Jobs/GenerateReviewPackJob.php, keeping the current ReviewPack family and the ZIP baseline entries metadata.json, summary.json, and sections.json intact while adding one executive entrypoint and explicit delivery metadata.
  • T009 [P] Add or update the executive-entrypoint presentation layer under apps/platform/resources/views/review-packs/ only if the current bundle generation cannot render the executive export cleanly from existing summary truth. Not needed: the current job renders a bounded Markdown entrypoint directly from existing review summary truth.

Checkpoint: The current bundle, current run path, and current customer-safe surfaces are all locked to the new delivery contract before broader wording changes begin.

Phase 3: User Story 1 - Deliver One Stakeholder-Ready Bundle From A Released Review (Priority: P1)

Goal: A published review can generate or reuse one current export bundle that is ready to hand over externally.

Independent Test: Export a published review, complete the current generation job, and download the resulting current pack to verify that one executive entrypoint and the existing structured appendix coexist in the same bundle.

Tests for User Story 1

  • T010 [P] [US1] Extend apps/platform/tests/Feature/TenantReview/TenantReviewExecutivePackTest.php to assert that the current pack remains review-anchored and now exposes the executive entrypoint plus delivery metadata.
  • T011 [P] [US1] Extend apps/platform/tests/Feature/TenantReview/TenantReviewExportOperationsUxTest.php to assert that export initiation still uses the existing ReviewPackGenerate path, dedupes correctly, and stays on the current operator-side action. Existing coverage already proved the unchanged run path and dedupe behavior.
  • T012 [P] [US1] Extend apps/platform/tests/Feature/ReviewPack/TenantReviewDerivedReviewPackTest.php and apps/platform/tests/Feature/ReviewPack/ReviewPackDownloadTest.php to verify the new bundle contents and signed-download continuity. New bundle assertions landed in TenantReviewDerivedReviewPackTest; existing download continuity coverage remained unchanged and passed.

Implementation for User Story 1

  • T013 [US1] Update apps/platform/app/Services/ReviewPackService.php and apps/platform/app/Jobs/GenerateReviewPackJob.php so review-derived packs produce one executive entrypoint and explicit delivery metadata while preserving current appendix files and current current_export_review_pack_id behavior.
  • T014 [US1] Update apps/platform/app/Filament/Resources/TenantReviewResource.php and apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php so published-review export continues to generate or reuse the current pack without introducing a second delivery action or a second artifact family. No code update was needed; repo truth already used the current action and run seam, and tests confirmed it.
  • T015 [US1] Update apps/platform/app/Http/Controllers/ReviewPackDownloadController.php only as needed to carry the same current pack through the signed download path with delivery metadata intact. No controller update was needed; signed download continuity stayed on the existing pack file and passed validation.

Checkpoint: One released review can produce and deliver one stakeholder-ready current bundle without any second export system.

Phase 4: User Story 2 - Show The Executive Story First And The Appendix Second (Priority: P1)

Goal: The in-app delivery surfaces and the exported bundle both make the executive narrative the default entrypoint while keeping appendix detail secondary.

Independent Test: Open a released review in customer-workspace mode and confirm that the default visible package block and the downloaded current bundle both present executive-first delivery framing without raw internal diagnostics.

Tests for User Story 2

  • T016 [P] [US2] Extend apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php and apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php to cover only the delivery-readiness wording changes required by the new bundle contract, evidence-basis messaging, and the absence of peer download actions on the workspace list. New wording assertions landed in CustomerReviewWorkspacePageTest; existing pack-access tests remained the peer-action guard.
  • T017 [P] [US2] Extend apps/platform/tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php and apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php to cover executive-first default content, appendix-secondary wording, and hidden raw/internal detail by default. New disclosure assertions landed in TenantReviewExplanationSurfaceTest; existing UI-contract tests remained the one-action guard.
  • T018 [P] [US2] Extend apps/platform/tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php to prove the released-review path still centers the customer-safe package summary and dominant download action after the wording changes.

Implementation for User Story 2

  • T019 [US2] Update apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php and apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php only where needed so workspace rows keep delivery readiness informational and Open review remains the only dominant row action. No PHP/Blade structure change was needed on the workspace list; localized intro copy now frames executive-ready package status while existing row action tests guard Open review.
  • T020 [US2] Update apps/platform/app/Services/TenantReviews/TenantReviewComposer.php, apps/platform/app/Services/TenantReviews/TenantReviewSectionFactory.php, and apps/platform/resources/views/filament/infolists/entries/tenant-review-summary.blade.php only where needed so the released-review detail block explains executive-first delivery, evidence basis, and appendix-secondary meaning without reopening broader customer-safe package semantics already owned by Spec 260. Composer/factory already exposed the required truth; the detail entry now presents entrypoint and appendix wording.
  • T021 [US2] Update apps/platform/lang/en/localization.php and apps/platform/lang/de/localization.php so delivery-readiness, executive-entrypoint, appendix, and non-certification copy stay consistent across workspace, detail, and download paths.

Checkpoint: The delivery story is obvious and customer-safe before the bundle is opened, and the workspace/detail surfaces stay calm and non-duplicative.

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

Goal: The sellability improvement remains on the current entitlement, audit, and observability seams.

Independent Test: Verify that export and download stay tenant-safe, audit-visible, and free of any second package domain or new delivery workflow state.

Tests for User Story 3

  • T022 [P] [US3] Extend apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php and apps/platform/tests/Feature/ReviewPack/ReviewPackDownloadTest.php to confirm non-members remain 404 and current in-scope download permissions remain authoritative. Existing authorization/download coverage remained valid and passed.
  • T023 [P] [US3] Extend apps/platform/tests/Feature/TenantReview/TenantReviewExportOperationsUxTest.php and apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php to confirm operator export generation remains the only current initiation path and no competing customer-surface generation action appears. Existing UX-contract coverage remained valid and passed.
  • T024 [P] [US3] Extend apps/platform/tests/Feature/TenantReview/TenantReviewAuditLogTest.php and apps/platform/tests/Feature/ReviewPack/ReviewPackDownloadTest.php to confirm current audit metadata still records export and download activity without a new audit family. Existing audit/download coverage remained valid and passed.

Implementation for User Story 3

  • T025 [US3] Reuse or minimally extend current audit metadata in apps/platform/app/Services/Audit/WorkspaceAuditLogger.php and apps/platform/app/Support/Audit/AuditActionId.php only if the current export/download events need explicit delivery-role metadata. No audit-family or action-id change was needed; existing metadata remains authoritative.
  • T026 [US3] Review apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php and current delivery availability mapping so available, partial, unavailable, expired, and blocked remain truthful after the new bundle entrypoint is added.
  • T027 [US3] Confirm the implementation does not add a new panel, new global search entry, new asset registration, second artifact family, or recurring delivery workflow. If any of those become necessary, stop and split the scope.

Checkpoint: Delivery remains attributable, tenant-safe, and bounded to the current export/download seams.

Phase 6: Polish & Cross-Cutting Validation

Purpose: Validate the bounded slice and stop without widening scope.

  • T028 [P] Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantReview/TenantReviewExecutivePackTest.php tests/Feature/TenantReview/TenantReviewExportOperationsUxTest.php tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php tests/Feature/TenantReview/TenantReviewUiContractTest.php tests/Feature/TenantReview/TenantReviewAuditLogTest.php tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php tests/Feature/ReviewPack/TenantReviewDerivedReviewPackTest.php tests/Feature/ReviewPack/ReviewPackDownloadTest.php - passed, 41 tests / 326 assertions.
  • T029 [P] Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php - passed, 1 test / 42 assertions.
  • T030 [P] Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent - passed.
  • T031 [P] Review touched code to confirm Filament stays on Livewire v4, provider registration remains unchanged in apps/platform/bootstrap/providers.php, no globally searchable resource contract changes, and no new asset strategy appears.
  • T032 [P] Review touched code to confirm the bundle stays on the current ReviewPack family and the current ReviewPackGenerate run path.
  • T033 [P] Record the final guardrail, smoke, and scope-boundary outcomes in the active feature close-out without reopening branding, PDF, scheduling, or second-artifact follow-up work. Outcome: no new panel, provider, global search, asset strategy, run type, artifact family, PDF/reporting engine, branding, scheduling, or second delivery workflow; browser smoke passed on the existing Customer Review Workspace handoff.

Dependencies & Execution Order

Phase Dependencies

  • Phase 1 (Setup): no dependencies; start immediately.
  • Phase 2 (Foundational): depends on Phase 1 and blocks all user stories.
  • Phase 3 (US1): depends on Phase 2 and establishes the current bundle contract.
  • Phase 4 (US2): depends on Phase 2 and should land with US1 so the new bundle contract and the in-app delivery language stay aligned.
  • Phase 5 (US3): depends on Phase 2 and hardens audit and entitlement behavior after the bundle contract exists.
  • Phase 6 (Polish): depends on all desired user stories being complete.

User Story Dependencies

  • US1 (P1): independently testable after Phase 2 and delivers the core stakeholder-ready bundle.
  • US2 (P1): independently testable after Phase 2 and should ship with US1 so the delivered bundle and in-app delivery language do not drift apart.
  • US3 (P2): independently testable after Phase 2 and hardens the bounded delivery path.

Within Each User Story

  • Write the listed Pest coverage first and make it fail for the intended gap.
  • Keep implementation inside the current review-pack, review, download, localization, and audit seams named above.
  • Re-run the narrowest relevant validation command after each story checkpoint before moving on.

Implementation Strategy

Suggested MVP Scope

  • MVP = US1 + US2 together. The feature is only useful when the current bundle becomes stakeholder-ready and the current in-app delivery surfaces explain it correctly.

Incremental Delivery

  1. Complete Phase 1 and Phase 2.
  2. Deliver US1 and US2 together on the current ReviewPack family.
  3. Add US3 to confirm audit and entitlement continuity.
  4. Finish with the focused validation and drift-review tasks in Phase 6.

Team Strategy

  1. Settle the bundle contract first.
  2. Parallelize failing tests within each story before runtime edits.
  3. Serialize merges around ViewTenantReview, CustomerReviewWorkspace, and shared localization keys so delivery wording stays coherent.

Deferred Follow-Ups / Non-Goals

  • PDF tooling or richer print/export rendering
  • recurring delivery or scheduled distribution
  • branded or customer-specific delivery variants
  • multi-review or multi-tenant delivery batches
  • a second artifact family or a standalone auditor-portal surface