# Tasks: Spec 347 - Review Pack Output Contract & Readiness Semantics **Input**: Design documents from `/specs/347-review-pack-output-contract-readiness-semantics/` **Prerequisites**: `spec.md`, `plan.md`, `repo-truth-map.md`, and the three contract documents under `contracts/` **Tests**: Required. This is a runtime output-contract and customer-safe trust-surface change on existing review-pack and Customer Review Workspace paths. ## Test Governance Checklist - [x] Lane assignment is explicit and narrow: Feature for ZIP/workspace contract, Browser for first-screen trust proof. - [x] New or changed tests stay in the smallest honest family, and the browser addition is explicit. - [x] Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default. - [x] Planned validation commands cover the change without pulling in unrelated lane cost. - [x] The declared surface profile (`global-context-shell` + customer-safe strategic review surface + artifact contract) is explicit. - [x] Any unreachable state is documented in the active spec package rather than faked. ## Phase 1: Preparation And Repo Truth **Purpose**: Confirm current output truth and keep the runtime implementation bounded to the existing review-derived export and workspace surfaces. - [x] T001 Re-read `specs/347-review-pack-output-contract-readiness-semantics/spec.md`, `plan.md`, `repo-truth-map.md`, and all three contract docs before runtime changes. - [x] T002 Re-read related historical context only: Specs 109, 308, 312, 337, 342, 343, 344, and active Spec 346. Do not modify their artifacts. - [x] T003 Re-verify current runtime truth in: - `apps/platform/app/Jobs/GenerateReviewPackJob.php` - `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewComposer.php` - `apps/platform/app/Services/ReviewPackService.php` - `apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php` - `apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php` - `apps/platform/app/Http/Controllers/ReviewPackDownloadController.php` - [x] T004 Keep `specs/347-review-pack-output-contract-readiness-semantics/repo-truth-map.md` updated if implementation-time code differs from the prepared truth. - [x] T005 Confirm no migration, package, env var, queue family, scheduler change, storage-topology change, or Filament asset change is required. - [x] T006 Confirm Filament v5 / Livewire v4.0+ compliance and avoid legacy Filament or Livewire APIs. - [x] T007 Confirm panel provider registration remains `apps/platform/bootstrap/providers.php`. - [x] T008 Confirm no new global-search behavior is introduced for review/evidence/review-pack resources. ## Phase 2: Finalize Contract Docs **Purpose**: Lock the implementation against one explicit contract instead of allowing page-local drift. - [x] T009 Finalize `specs/347-review-pack-output-contract-readiness-semantics/contracts/review-pack-output-contract.md`. - [x] T010 Finalize `specs/347-review-pack-output-contract-readiness-semantics/contracts/readiness-semantics.md`. - [x] T011 Finalize `specs/347-review-pack-output-contract-readiness-semantics/contracts/customer-safe-output-boundary.md`. - [x] T012 Record repo-truth deviations from the user draft explicitly: - section-detail files currently live under `sections/` - current delivery contract is `auditor_ready_executive_export.v1` - current UI audit page report is `docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md` - [x] T013 Confirm the contract keeps semantics derived-only and does not introduce a new persisted readiness family. ## Phase 3: Tests First **Purpose**: Lock required file/field/label semantics before runtime refactor. - [x] T014 Add `apps/platform/tests/Feature/ReviewPack/Spec347ReviewPackOutputContractTest.php`. - [x] T015 Add `apps/platform/tests/Feature/ReviewPack/Spec347ReviewPackReadinessSemanticsTest.php`. - [x] T016 Add `apps/platform/tests/Feature/Filament/Spec347CustomerReviewWorkspaceOutputReadinessTest.php`. - [x] T017 Add `apps/platform/tests/Browser/Spec347ReviewPackOutputReadinessSmokeTest.php`. - [x] T018 Add assertions for required root files: `executive-summary.md`, `metadata.json`, `summary.json`, `sections.json`. - [x] T019 Add assertions for required metadata fields: bundle contract, artifact family, review-pack id, released-review state, evidence-basis state, entrypoint, appendix, options, and redaction integrity. - [x] T020 Add assertions for required summary/readiness fields, including review status, review completeness, evidence resolution, section state counts, publish blockers, delivery bundle, and any contract-backed readiness flag inputs. - [x] T021 Add assertions that a section marked `missing` may still have a section-detail file and that the semantics are explicit. - [x] T022 Add assertions that the workspace does not show unqualified `Ready to share` when evidence, section, export, or customer-safe readiness is incomplete. - [x] T023 Add assertions that `include_pii=true` or equivalent repo-backed PII truth results in an operator-visible review warning before sharing. - [x] T024 Add assertions that executive summary output contains limitations and non-certification disclosure when contract-backed limitations exist. - [x] T025 Reuse or extend existing tests such as `EnvironmentReviewDerivedReviewPackTest.php`, `EnvironmentReviewExecutivePackTest.php`, `ReviewPackDownloadTest.php`, `Spec342CustomerReviewWorkspaceConsumptionTest.php`, `Spec342CustomerReviewWorkspaceConsumptionSmokeTest.php`, and `CustomerReviewSurfaceLocalizationTest.php` only where more proportional than duplicating all setup. ## Phase 4: Derived Output-Readiness Mapper **Purpose**: Replace scattered heuristics with one bounded derived contract. - [x] T026 Choose the narrowest implementation home for derived output readiness: - page-local helper inside `CustomerReviewWorkspace` - or one bounded support-layer mapper shared with review-pack output generation/tests - [x] T027 Derive a contract that exposes label, reason, impact, primary action, evidence basis state, section completeness summary, PII/redaction visibility, and customer-safe/internal-only/limitations state. - [x] T028 Reuse current review summary, review-pack summary, and existing `delivery_bundle` / `evidence_resolution` data before adding any new payload keys. - [x] T029 Keep any added payload keys narrow and review-pack-output-specific; do not create a generic governance output engine. ## Phase 5: Review-Derived ZIP Contract Hardening **Purpose**: Keep the current generator shape while removing contract ambiguity. - [x] T030 Update `apps/platform/app/Jobs/GenerateReviewPackJob.php` so review-derived ZIP generation always emits the required root files and required contract fields. - [x] T031 Preserve the current review-derived contract constant in `apps/platform/app/Services/ReviewPackService.php` unless a repo-justified version bump is necessary. - [x] T032 Decide and implement the canonical section-detail contract: - add `section_key`, `required`, and `sort_order` to each `sections/*.json` file, or - explicitly keep `sections.json` as the canonical section index and document the thinner subordinate detail-file shape - [x] T033 Ensure `metadata.json` and `summary.json` expose consistent review, evidence, section, and bundle semantics. - [x] T034 Ensure file-to-section consistency is testable: every detail file corresponds to a `sections.json` entry and does not silently drift in key/title/state. - [x] T035 Keep review-pack download safety unchanged; do not weaken signed-route, capability, expiry, or file-existence checks in `apps/platform/app/Http/Controllers/ReviewPackDownloadController.php`. ## Phase 6: Executive Summary And Disclosure Hardening **Purpose**: Make the human entrypoint honest without leaking internal detail. - [x] T036 Update review-derived executive-summary generation in `apps/platform/app/Jobs/GenerateReviewPackJob.php` to add a dedicated `## Limitations` block when evidence completeness, section completeness, export readiness, or PII/customer-safe boundary limits sharing. - [x] T037 Keep or strengthen the existing non-certification disclosure in the executive summary. - [x] T038 Explicitly explain in the executive summary when section files are present but the corresponding section completeness is `missing`. - [x] T039 Keep internal-only/raw/support detail out of the markdown entrypoint. ## Phase 7: Customer Review Workspace Remap **Purpose**: Make the first screen reflect the same contract as the ZIP. - [x] T040 Update `apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php` to use qualified output-readiness labels when the package contract is incomplete. - [x] T041 Update `apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php` so the first screen surfaces evidence basis state, section completeness summary, PII/redaction visibility, and limitations-aware next action. - [x] T042 Qualify download labels and affordances on the workspace surface based on repo-backed state, for example internal-only or limitations-bearing package wording where justified by the contract. - [x] T043 Keep exactly one dominant next action in the decision card. - [x] T044 Keep diagnostics collapsed and secondary. - [x] T045 Avoid broader Customer Review Workspace redesign outside bounded readiness/disclosure hardening. ## Phase 8: Copy, Audit, And Browser Proof **Purpose**: Align user-facing wording and proof artifacts with the hardened contract. - [x] T046 Update only the required output-readiness and disclosure keys in: - `apps/platform/lang/en/localization.php` - `apps/platform/lang/de/localization.php` - [x] T047 Update `docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md` with the output contract/readiness mapping, limitations behavior, and deferred follow-ups. - [x] T048 Keep the existing page-report identity and do not invent `ui-009-*` unless runtime review proves the current report cannot absorb the output-contract scope. - [x] T049 Capture browser screenshots under `specs/347-review-pack-output-contract-readiness-semantics/artifacts/screenshots/`. ## Phase 9: Validation **Purpose**: Prove the contract and preserve current safety. - [x] T050 Run `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/ReviewPack/Spec347ReviewPackOutputContractTest.php tests/Feature/ReviewPack/Spec347ReviewPackReadinessSemanticsTest.php tests/Feature/Filament/Spec347CustomerReviewWorkspaceOutputReadinessTest.php --compact`. - [x] T051 Run `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/EnvironmentReview/EnvironmentReviewExecutivePackTest.php tests/Feature/Localization/CustomerReviewSurfaceLocalizationTest.php tests/Feature/Filament/Spec342CustomerReviewWorkspaceConsumptionTest.php --compact`. - [x] T052 Run `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec347ReviewPackOutputReadinessSmokeTest.php tests/Browser/Spec342CustomerReviewWorkspaceConsumptionSmokeTest.php --compact`. - [x] T053 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ReviewPack`. - [x] T054 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=CustomerReviewWorkspace`. - [x] T055 Run `cd apps/platform && ./vendor/bin/sail pint --dirty`. - [x] T056 Run `git diff --check`. - [x] T057 Report any unrelated broader-suite failures honestly if they remain out of scope. ## Non-Goals Checklist - [x] NT001 Do not rebuild Review Pack generation from scratch. - [x] NT002 Do not add a new persisted readiness entity, table, or status family. - [x] NT003 Do not add a portal, PSA/ITSM handoff, or broader artifact-lifecycle framework. - [x] NT004 Do not redesign Governance Inbox or broadly redesign Customer Review Workspace. - [x] NT005 Do not add legal/compliance approval, certification, or attestation semantics. - [x] NT006 Do not weaken signed-download safety. - [x] NT007 Do not invent a legacy-compatible root-level section-file layout if repo truth remains `sections/*.json`. - [x] NT008 Do not expand this slice into Review Pack Resource detail/header productization unless a minimal contradiction fix is proven unavoidable.