TenantAtlas/specs/347-review-pack-output-contract-readiness-semantics/tasks.md

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

• Lane assignment is explicit and narrow: Feature for ZIP/workspace contract, Browser for first-screen trust proof.
• New or changed tests stay in the smallest honest family, and the browser addition is explicit.
• Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default.
• Planned validation commands cover the change without pulling in unrelated lane cost.
• The declared surface profile (global-context-shell + customer-safe strategic review surface + artifact contract) is explicit.
• 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.

• 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.
• T002 Re-read related historical context only: Specs 109, 308, 312, 337, 342, 343, 344, and active Spec 346. Do not modify their artifacts.
• 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
• T004 Keep specs/347-review-pack-output-contract-readiness-semantics/repo-truth-map.md updated if implementation-time code differs from the prepared truth.
• T005 Confirm no migration, package, env var, queue family, scheduler change, storage-topology change, or Filament asset change is required.
• T006 Confirm Filament v5 / Livewire v4.0+ compliance and avoid legacy Filament or Livewire APIs.
• T007 Confirm panel provider registration remains apps/platform/bootstrap/providers.php.
• 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.

• T009 Finalize specs/347-review-pack-output-contract-readiness-semantics/contracts/review-pack-output-contract.md.
• T010 Finalize specs/347-review-pack-output-contract-readiness-semantics/contracts/readiness-semantics.md.
• T011 Finalize specs/347-review-pack-output-contract-readiness-semantics/contracts/customer-safe-output-boundary.md.
• 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
• 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.

• T014 Add apps/platform/tests/Feature/ReviewPack/Spec347ReviewPackOutputContractTest.php.
• T015 Add apps/platform/tests/Feature/ReviewPack/Spec347ReviewPackReadinessSemanticsTest.php.
• T016 Add apps/platform/tests/Feature/Filament/Spec347CustomerReviewWorkspaceOutputReadinessTest.php.
• T017 Add apps/platform/tests/Browser/Spec347ReviewPackOutputReadinessSmokeTest.php.
• T018 Add assertions for required root files: executive-summary.md, metadata.json, summary.json, sections.json.
• 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.
• 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.
• T021 Add assertions that a section marked missing may still have a section-detail file and that the semantics are explicit.
• T022 Add assertions that the workspace does not show unqualified Ready to share when evidence, section, export, or customer-safe readiness is incomplete.
• T023 Add assertions that include_pii=true or equivalent repo-backed PII truth results in an operator-visible review warning before sharing.
• T024 Add assertions that executive summary output contains limitations and non-certification disclosure when contract-backed limitations exist.
• 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.

• 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
• 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.
• T028 Reuse current review summary, review-pack summary, and existing delivery_bundle / evidence_resolution data before adding any new payload keys.
• 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.

• T030 Update apps/platform/app/Jobs/GenerateReviewPackJob.php so review-derived ZIP generation always emits the required root files and required contract fields.
• T031 Preserve the current review-derived contract constant in apps/platform/app/Services/ReviewPackService.php unless a repo-justified version bump is necessary.
• 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
• T033 Ensure metadata.json and summary.json expose consistent review, evidence, section, and bundle semantics.
• 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.
• 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.

• 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.
• T037 Keep or strengthen the existing non-certification disclosure in the executive summary.
• T038 Explicitly explain in the executive summary when section files are present but the corresponding section completeness is missing.
• 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.

• T040 Update apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php to use qualified output-readiness labels when the package contract is incomplete.
• 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.
• 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.
• T043 Keep exactly one dominant next action in the decision card.
• T044 Keep diagnostics collapsed and secondary.
• 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.

• T046 Update only the required output-readiness and disclosure keys in:
  • apps/platform/lang/en/localization.php
  • apps/platform/lang/de/localization.php
• 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.
• 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.
• 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.

• 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.
• 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.
• T052 Run cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec347ReviewPackOutputReadinessSmokeTest.php tests/Browser/Spec342CustomerReviewWorkspaceConsumptionSmokeTest.php --compact.
• T053 Run cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ReviewPack.
• T054 Run cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=CustomerReviewWorkspace.
• T055 Run cd apps/platform && ./vendor/bin/sail pint --dirty.
• T056 Run git diff --check.
• T057 Report any unrelated broader-suite failures honestly if they remain out of scope.

Non-Goals Checklist

• NT001 Do not rebuild Review Pack generation from scratch.
• NT002 Do not add a new persisted readiness entity, table, or status family.
• NT003 Do not add a portal, PSA/ITSM handoff, or broader artifact-lifecycle framework.
• NT004 Do not redesign Governance Inbox or broadly redesign Customer Review Workspace.
• NT005 Do not add legal/compliance approval, certification, or attestation semantics.
• NT006 Do not weaken signed-download safety.
• NT007 Do not invent a legacy-compatible root-level section-file layout if repo truth remains sections/*.json.
• NT008 Do not expand this slice into Review Pack Resource detail/header productization unless a minimal contradiction fix is proven unavoidable.