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](./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)

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

### Source Code (expected implementation surfaces)

```text
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.