TenantAtlas/specs/263-auditor-pack-executive-export/plan.md

Implementation Plan: Auditor Pack Delivery & Executive Export v1

Branch: 263-auditor-pack-executive-export | Date: 2026-05-02 | Spec: spec.md Input: Feature specification from /specs/263-auditor-pack-executive-export/spec.md

Summary

This is an explicit delta follow-up over Specs 258-260 and the current review-package code path. The existing customer-safe workspace/detail delivery semantics, current operator export initiation, current signed download route, and current governance-package availability states are inherited. The implementation scope is only to make the existing current bundle externally deliverable by adding one human-readable executive entrypoint inside that bundle, making appendix roles explicit, and applying the minimal wording changes needed to explain that new bundle contract. The implementation must stay on current released-review, review-pack, evidence, and interpretation truth with no new artifact family, no new panel, and no new recurring-delivery workflow.

Inherited Baseline / Explicit Delta

Inherited baseline

• CustomerReviewWorkspace already owns the calm workspace delivery-selection surface.
• released-review detail already owns the customer-safe governance-package summary and signed download action.
• published operator review detail already owns export_executive_pack and current ReviewPackGenerate initiation.
• the current review-derived ZIP baseline already contains metadata.json, summary.json, and sections.json.

Explicit delta in this plan

• preserve the existing ZIP baseline entries and add one executive-first entrypoint file
• extend delivery metadata so the preserved ZIP entries are explicitly framed as the structured appendix
• update only the wording on the inherited workspace/detail surfaces that is required to describe the new bundle contract

Technical Context

Language/Version: PHP 8.4, Laravel 12, Filament v5, Livewire v4
Primary Dependencies: Filament admin surfaces, current ReviewPackService, GenerateReviewPackJob, ReviewPackDownloadController, TenantReviewComposer, ArtifactTruthPresenter
Storage: PostgreSQL plus private exports disk for the existing ReviewPack ZIP artifact
Testing: Pest feature tests plus one bounded browser smoke
Validation Lanes: confidence, browser
Target Platform: Existing Laravel admin runtime under apps/platform
Project Type: Laravel monolith with Filament admin surfaces
Performance Goals: No new provider calls, no second generation flow, and no additional queue family beyond the current ReviewPackGenerate run
Constraints: No new persisted delivery domain, no new panel/provider/assets, no raw internal diagnostics in the executive entrypoint, preserve current 404/403 semantics, preserve current signed download path
Scale/Scope: One released review at a time, one current export bundle per released review

UI / Surface Guardrail Plan

• Guardrail scope: changed surfaces
• Native vs custom classification summary: native Filament surfaces plus one bounded export entrypoint rendered from existing product truth
• Shared-family relevance: review-pack delivery, governance-package wording, detail-summary disclosure, download actions
• State layers in scope: page, detail, disclosure state
• Audience modes in scope: operator-MSP, customer-admin, customer-read-only, auditor-read-only
• Decision/diagnostic/raw hierarchy plan: decision-first delivery readiness and executive summary first, diagnostics second, raw/support detail last
• Raw/support gating plan: raw provider payloads, fingerprints, and internal reason semantics stay hidden from the executive entrypoint and customer-safe default surfaces
• One-primary-action / duplicate-truth control: workspace rows keep Open review only; released-review detail keeps one dominant safe download action; operator detail keeps the existing export initiation action
• Handling modes by drift class or surface: report-only for unchanged operator-only pack detail surfaces; review-mandatory for any change that would add a second delivery action or a second package domain
• Repository-signal treatment: review-mandatory
• Special surface test profiles: shared-detail-family
• Required tests or manual smoke: focused feature coverage plus the existing bounded browser smoke for CustomerReviewWorkspace
• Exception path and spread control: none; any proposal for a new artifact family, new panel, or PDF engine is a scope split, not an in-feature exception
• Active feature PR close-out entry: Smoke Coverage

Shared Pattern & System Fit

• Cross-cutting feature marker: yes
• Systems touched: CustomerReviewWorkspace, TenantReviewResource, ViewTenantReview, ReviewPackService, GenerateReviewPackJob, ReviewPackDownloadController, TenantReviewComposer, TenantReviewSectionFactory, ArtifactTruthPresenter, localization files, and current audit IDs
• Shared abstractions reused: ReviewPackService, current ReviewPackGenerate OperationRun contract, current signed download controller, ArtifactTruthPresenter, TenantReviewComposer, TenantReviewSectionFactory, and WorkspaceAuditLogger
• New abstraction introduced? why?: none required by default. If implementation needs one helper to assemble delivery metadata or executive-export markup, it must stay local to current review-pack generation and not become a new export framework.
• Why the existing abstraction was sufficient or insufficient: current seams already solve entitlement, review anchoring, and bundle generation. They are only missing an explicit stakeholder-ready entrypoint and explicit appendix framing.
• Bounded deviation / spread control: none

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: yes
• Central contract reused: existing ReviewPackGenerate start UX and terminal notification flow
• Delegated UX behaviors: queued toast, dedupe-or-reuse handling, current run completion semantics, and current signed download follow-up stay delegated to existing review-pack infrastructure
• Surface-owned behavior kept local: internal published review detail decides when the export action is offered; customer-safe released-review detail remains download-only
• Queued DB-notification policy: unchanged from the current review-pack contract
• Terminal notification path: unchanged
• Exception path: none

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: no
• Provider-owned seams: existing provider-specific report names remain appendix-only and secondary
• Platform-core seams: delivery wording, evidence-basis wording, and customer-safe summary semantics remain platform-owned
• Neutral platform terms / contracts preserved: governance package, released review, evidence basis, delivery readiness, accepted risks, governance decisions
• Retained provider-specific semantics and why: provider-specific report or evidence names can remain in the appendix because the appendix is secondary and evidence-oriented, not the primary executive narrative
• Bounded extraction or follow-up path: none

Constitution Check

GATE: Must pass before implementation begins and again before merge.

• Inventory-first: unchanged; all delivery content stays derived from current review, evidence snapshot, stored reports, and current review-pack truth
• Read/write separation: write path remains only the current review-pack generation flow; customer-safe delivery remains read-only
• Graph contract path: no Graph calls are added
• Deterministic capabilities: current review and review-pack capability derivation stays authoritative
• RBAC-UX: workspace membership and tenant/review entitlement remain 404 boundaries; current in-scope capability denials remain 403
• Workspace isolation: unchanged
• Tenant isolation: unchanged
• Run observability: current ReviewPackGenerate OperationRun path remains the only generation run path; no new run type or queue family is introduced
• OperationRun start UX: existing shared review-pack start UX remains authoritative
• Ops-UX lifecycle and summary counts: unchanged
• Test governance: keep proof bounded to current review, review-pack, and customer-workspace test families plus one existing browser smoke
• Proportionality / persistence / bloat: no new table, new artifact family, or delivery workflow state is allowed
• Shared pattern first: current review-pack export and download paths must be extended instead of bypassed
• Provider boundary: unchanged
• V1 explicitness / few layers: prefer direct extension of current bundle generation and current UI disclosure
• Badge semantics: reuse the current governance-package availability and artifact-truth badge mapping
• Filament-native UI: keep current native Filament pages and detail surfaces; no new custom dashboard shell
• UI/UX surface taxonomy and decision-first operating model: workspace remains registry-first; released-review detail remains package-owning context
• Audience-aware disclosure: executive-ready summary first, appendix second, raw/internal detail hidden by default
• Action-surface discipline: workspace rows keep one open action, released-review detail keeps one dominant download action, operator detail keeps one dominant export action

Test Governance Check

• Test purpose / classification by changed surface: Feature, Browser
• Affected validation lanes: confidence, browser
• Why this lane mix is the narrowest sufficient proof: the slice changes bundle contents, delivery wording, and existing actions on current review surfaces. Focused feature coverage plus the current browser smoke are sufficient without widening into heavy-governance or new browser families.
• Narrowest proving command(s):
  • 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
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php
• Fixture / helper / factory / seed / context cost risks: reuse current released-review, evidence, and review-pack fixtures only; avoid new seeded report families or provider setup
• Expensive defaults or shared helper growth introduced?: no
• Heavy-family additions, promotions, or visibility changes: none
• Surface-class relief / special coverage rule: shared-detail-family
• Closing validation and reviewer handoff: reviewers should confirm that one current ReviewPack bundle still drives the entire delivery path and that the browser smoke remains bounded to the existing workspace flow
• Budget / baseline / trend follow-up: none
• Review-stop questions: lane fit, bundle truth staying on current artifact family, raw-detail leakage, and accidental second-delivery-domain drift
• Escalation path: none
• Active feature PR close-out entry: Smoke Coverage

Project Structure

Documentation (this feature)

specs/263-auditor-pack-executive-export/
├── spec.md
├── plan.md
├── tasks.md
└── checklists/
    └── requirements.md

Source Code (expected implementation surfaces)

apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php
apps/platform/app/Filament/Resources/TenantReviewResource.php
apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php
apps/platform/app/Services/ReviewPackService.php
apps/platform/app/Jobs/GenerateReviewPackJob.php
apps/platform/app/Http/Controllers/ReviewPackDownloadController.php
apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php
apps/platform/app/Services/TenantReviews/TenantReviewComposer.php
apps/platform/app/Services/TenantReviews/TenantReviewSectionFactory.php
apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php
apps/platform/resources/views/filament/infolists/entries/tenant-review-summary.blade.php
apps/platform/resources/views/review-packs/...
apps/platform/lang/en/localization.php
apps/platform/lang/de/localization.php
apps/platform/tests/Feature/Reviews/...
apps/platform/tests/Feature/TenantReview/...
apps/platform/tests/Feature/ReviewPack/...
apps/platform/tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php

Structure Decision: keep the implementation inside the existing admin-plane review and review-pack surfaces. If a dedicated executive-export Blade template is needed, add it under apps/platform/resources/views/review-packs/ and keep it local to current ReviewPack generation.

Data / Migration Implications

• Prefer extending current bundle contents and current JSON metadata over schema changes.
• Preserve the current review-derived ZIP baseline entries metadata.json, summary.json, and sections.json; the new contract adds one executive-first entrypoint and explicit appendix-role metadata over that baseline.
• No new ReviewPack table columns, no new delivery table, and no new artifact registry should be required for v1.
• If implementation cannot express delivery metadata inside the current pack contents or current JSON summary surfaces, stop and split rather than widening persistence scope.

Rollout Considerations

• Filament remains v5 on Livewire v4. No panel-provider change is required, and provider registration remains in apps/platform/bootstrap/providers.php.
• No global search change is required because the affected surfaces stay on existing pages and non-globally-searchable resources.
• No destructive action is added. Existing export generation and download paths remain the only user-triggered flows.
• No new asset registration is expected; any human-readable executive entrypoint should be rendered from existing server-side view capabilities and included in the current bundle.

Risk Controls

• Reject any implementation that introduces a second delivery artifact family or a new export registry.
• Reject any implementation that adds PDF/report-engine infrastructure or recurring delivery automation in this slice.
• Reject any implementation that exposes raw provider payloads or internal reason ownership in the executive entrypoint.
• Keep customer-safe read-only download semantics and current operator-side export initiation separate.

Implementation Phases

Phase 0 - Confirm Current Delivery Truth

• Verify the current review-derived pack contents and metadata contract in ReviewPackService, GenerateReviewPackJob, and current review-pack tests.
• Verify the current customer-workspace and released-review detail delivery semantics in CustomerReviewWorkspace, ViewTenantReview, and their tests.

Phase 1 - Extend The Current Bundle

• Add one human-readable executive entrypoint file to the current review-derived bundle.
• Extend bundle metadata so the executive entrypoint and appendix roles are explicit.
• Keep the current structured appendix files intact and secondary.

Phase 2 - Align Surfaces With The Delivery Contract

• Update workspace and released-review detail copy so readiness, evidence basis, and delivery wording reflect the new bundle contract.
• Keep Open review and Download governance package as the dominant safe actions in their existing contexts.

Phase 3 - Harden Audit, Permissions, And Download Continuity

• Reuse current audit events and signed download controller.
• Confirm export initiation and ready-pack download continue to follow current capability and entitlement rules.

Phase 4 - Validate And Stop

• Run the planned confidence proof and the existing browser smoke.
• Verify no new run type, no new artifact family, no new panel/provider/assets, and no raw-detail leakage.

Why This Plan Is Narrow Enough

The repo already has a generated review-pack artifact, an operator export action, a customer-safe download action, and shared governance-package meaning. This plan changes only the delivery contract of that existing artifact and the wording on the two existing review surfaces that expose it. Everything broader stays explicitly deferred.