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

Feature Specification: Spec 347 - Review Pack Output Contract & Readiness Semantics

Feature Branch: 347-review-pack-output-contract-readiness-semantics
Created: 2026-06-02
Status: Draft
Type: Contract-first hardening / review-pack output semantics / customer-safe export productization
Runtime posture: Narrow runtime hardening over existing review-derived Review Pack exports and current Customer Review Workspace readiness heuristics. No generator rewrite, no new persistence, no new portal, and no broad review workflow rebuild.
Input: User-provided full Spec 347 draft + repo truth from Specs 109, 308, 337, 342, 343, 344, and current Spec 346 context.

Dependencies And Historical Context

This spec is a follow-up over already repo-real review, evidence, and customer-safe productization work:

• Spec 109 - Review Pack Export
• Spec 308 - Decision Register Summary / Review Pack Inclusion
• Spec 337 - Evidence / Review Pack Product Process Flow Alignment
• Spec 342 - Customer Review Workspace Final Consumption Productization
• Spec 343 - Customer Review Attestation / Accepted Risk Lifecycle
• Spec 344 - Customer Review Workspace Density / Audience Polish
• Spec 346 - Governance Inbox Final Operator Workflow (active adjacent context only; not a prerequisite to reopen or complete here)

Repo-truth adjustment against the user draft:

• Current review-derived ZIP section detail files are generated under sections/%02d-%s.json, not as root-level 10-...json files.
• The current review-derived delivery contract already exists as auditor_ready_executive_export.v1 in App\Services\ReviewPackService::REVIEW_DERIVED_DELIVERY_CONTRACT.
• metadata.json already carries delivery_bundle.entrypoint, appendix, review identity, evidence identity, options, and redaction integrity.
• EnvironmentReview.summary.has_ready_export already exists, but the Customer Review Workspace does not use it as a first-class output-readiness contract.
• CustomerReviewWorkspace currently derives Ready to share, Shareable with follow-up, and Follow-up required before sharing from page-local heuristics over findings, accepted-risk follow-up, evidence availability, mapped review data, and download availability.
• The existing UI audit page report for this surface is docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md; this spec must not invent a new page-report identity unless repo truth later proves it necessary.

Spec Candidate Check (mandatory - SPEC-GATE-001)

• Problem: TenantPilot already produces structured review-pack ZIPs, but the product contract for those files and the customer-share/readiness semantics remain ambiguous.
• Today's failure: Operators can see that a review is published, a ZIP exists, and section files are present, while evidence completeness, section completeness, has_ready_export, and customer-safe sharing semantics can still disagree. The UI can therefore imply "ready to share" more strongly than the bundle contract proves.
• User-visible improvement: Review Pack output becomes self-explanatory and trustworthy. Operators can tell whether a package exists, whether it is output-contract complete, whether evidence is incomplete, whether sections are missing by source truth rather than by file absence, whether PII is included, and whether the package is customer-safe, internal-only, or limitations-bearing.
• Smallest enterprise-capable version: Keep the current review-derived ZIP shape, add a narrow derived output-readiness contract, harden required metadata/section semantics, add limitations/disclosure output, and qualify Customer Review Workspace labels and download affordances.
• Explicit non-goals: No review-pack generator rewrite, no new evidence pipeline, no portal, no PSA/ITSM handoff, no PDF replacement, no new legal attestation workflow, no new queue family, no new table, no broad customer-review redesign, no Governance Inbox rewrite, and no new GRC framework.
• Permanent complexity imported: One repo-truth map, three spec-local contract documents, one narrow readiness mapper or presenter if needed, focused Feature tests, one bounded Browser smoke file, and screenshots. No new persisted entity, no new public status family, and no new runtime framework.
• Why now: Specs 337 and 342-344 made evidence/review-pack/customer-safe consumption repo-real, but the remaining trust gap is no longer raw data generation. It is the output contract and the readiness semantics at the export boundary.
• Why not local: Copy-only changes would leave metadata.json, summary.json, section files, and workspace UI heuristics semantically misaligned. A narrow contract-first hardening slice is the smallest honest fix.
• Approval class: Core Enterprise.
• Red flags triggered: Strategic customer-safe surface, output/readiness trust language, export semantics, and cross-surface contract alignment. Defense: the slice reuses existing truth, forbids new persistence, explicitly avoids a generator rewrite, and scopes new semantics to derived contract mapping plus focused tests.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve.

Candidate Source And Completed-Spec Guardrail

• Candidate source:
  • direct user-provided Spec 347 draft
  • roadmap lane: customer-safe review consumption and evidence/review-pack productization
  • spec-candidate alignment: open gap adjacent to customer-review-workspace-v1-completion, localization-v1-customer-facing-surfaces, and review/evidence follow-through
• Completed-spec guardrail result:
  • no specs/347-* package existed before this prep
  • Specs 109, 308, 312, 337, 342, 343, and 344 contain completed-task, validation, smoke, close-out, or implementation-history signals and are treated as historical context only
  • Spec 346 is active adjacent context and must not be rewritten, normalized, or treated as completed by this prep
• Close alternatives deferred:
  • provider readiness / onboarding productization
  • broader customer-facing localization hardening
  • sellable smoke matrix
  • customer portal boundary contract
• Smallest viable implementation slice: existing review-derived ZIP output plus existing Customer Review Workspace output-readiness surfaces only: required file contract, metadata/section semantics, explicit limitations/disclosure, qualified workspace labels, qualified download affordances, and focused tests/browser smoke.

Spec Scope Fields (mandatory)

• Scope: workspace canonical-view plus environment-owned review/evidence/export artifacts.
• Primary Routes:
  • /admin/reviews/workspace (App\Filament\Pages\Reviews\CustomerReviewWorkspace)
  • existing Environment Review and Review Pack detail/download destinations only where required for truth-preserving handoff
  • signed download route /admin/review-packs/{reviewPack}/download
• Data Ownership:
  • EnvironmentReview remains released-review truth
  • EnvironmentReviewSection remains section truth
  • EvidenceSnapshot remains anchored evidence-basis truth
  • ReviewPack remains generated export artifact truth
  • OperationRun remains generation/download proof linkage only
  • output-readiness stays derived; no new persisted readiness entity is introduced
• RBAC:
  • workspace membership and managed-environment entitlement remain mandatory
  • existing capabilities remain authoritative, especially REVIEW_PACK_VIEW, ENVIRONMENT_REVIEW_VIEW, and evidence/report capabilities
  • non-members and cross-workspace or cross-environment access remain deny-as-not-found
  • no new public route family or legacy query alias may be introduced

For canonical-view specs:

• Default filter behavior when tenant-context is active: keep environment_id as the only page-local filter contract; do not inherit hidden environment shell state or revive /admin/t semantics.
• Explicit entitlement checks preventing cross-tenant leakage: all review, evidence, pack, and download destinations must continue to resolve through existing workspace/environment scoped routes and policies.

UI Surface Impact (mandatory - UI-COV-001)

Does this spec add, remove, rename, or materially change any reachable UI surface?

• No UI surface impact
• Existing page changed
• New page/route added
• Navigation changed
• Filament panel/provider surface changed
• New modal/drawer/wizard/action added
• New table/form/state added
• Customer-facing surface changed
• Dangerous action changed
• Status/evidence/review presentation changed
• Workspace/environment context presentation changed

UI/Productization Coverage (mandatory when UI Surface Impact is not "No UI surface impact")

• Route/page/surface: CustomerReviewWorkspace, the signed Review Pack download affordance as reached from that workspace surface, and review-derived review-pack output files.
• Current or new page archetype: existing strategic customer-safe review surface plus existing artifact/download proof surfaces; no new route archetype.
• Design depth: Strategic Surface for CustomerReviewWorkspace; Domain Pattern Surface for Review Pack detail/download truth.
• Repo-truth level: repo-verified existing runtime surface plus existing ZIP contract.
• Existing pattern reused: Specs 337 and 342-344 customer-safe evidence/review readiness patterns, existing Review Pack generation/download contracts, existing disclosure and diagnostics collapse pattern.
• New pattern required: a bounded output-readiness contract over existing truth; no new global UI framework.
• Screenshot required: yes, under specs/347-review-pack-output-contract-readiness-semantics/artifacts/screenshots/.
• Page audit required: update docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md. Do not invent a new page-report identity unless implementation proves the current report cannot absorb the contract.
• Customer-safe review required: yes. This spec directly governs customer-safe, internal-only, and limitations-bearing output semantics.
• Dangerous-action review required: no new destructive action is expected. Existing regenerate/expire actions remain out of scope.
• Coverage files updated or explicitly not needed:
  • docs/ui-ux-enterprise-audit/route-inventory.md
  • docs/ui-ux-enterprise-audit/design-coverage-matrix.md
  • docs/ui-ux-enterprise-audit/page-reports/...
  • docs/ui-ux-enterprise-audit/strategic-surfaces.md
  • docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md
  • docs/ui-ux-enterprise-audit/unresolved-pages.md
  • N/A - no reachable UI surface impact
• No-impact rationale when applicable: N/A.

Cross-Cutting / Shared Pattern Reuse (mandatory)

• Cross-cutting feature?: yes
• Interaction class(es): status messaging, evidence/review/export readiness labels, action links, evidence/report viewers, review-pack proof and download affordances, customer-safe disclosure.
• Systems touched:
  • CustomerReviewWorkspace
  • EnvironmentReviewComposer
  • GenerateReviewPackJob
  • ReviewPackService
  • ReviewPackDownloadController
  • existing Review Pack and Environment Review resources/tests
• Existing pattern(s) to extend: Spec 337 evidence/review-pack state truth, Spec 342 customer-safe first-screen truth, existing disclosure rules, existing delivery_bundle and evidence_resolution payloads.
• Shared contract / presenter / builder / renderer to reuse: existing EnvironmentReview.summary, governance_package, delivery_bundle, ArtifactTruthPresenter, and current Review Pack metadata/summary structures wherever sufficient.
• Why the existing shared path is sufficient or insufficient: current structures already hold most raw facts, but they do not yet define one coherent output-readiness contract or one trustworthy mapping into workspace labels.
• Allowed deviation and why: one bounded page-local or support-layer readiness mapper is allowed if it avoids duplicating heuristics across page, ZIP, and tests. It must remain local to review-pack output semantics and not become a generic review framework.
• Consistency impact: ZIP files, Review Pack summary/metadata, workspace readiness labels, PII/redaction visibility, disclosure wording, and download labels must describe the same readiness state.
• Review focus: block any new persisted readiness entity, new legal/certification semantics, or a second independent readiness dialect.

OperationRun UX Impact (mandatory)

• Touches OperationRun start/completion/link UX?: existing proof and download audit context only
• Shared OperationRun UX contract/layer reused: existing OperationRunLinks, current generation flow, current audit/download proof handling
• Delegated start/completion UX behaviors: unchanged
• Local surface-owned behavior that remains: readiness explanation, limitations copy, and primary action selection
• Queued DB-notification policy: unchanged
• Terminal notification path: unchanged
• Exception required?: none

Provider Boundary / Platform Core Check (mandatory)

• Shared provider/platform boundary touched?: no new provider seam
• Boundary classification: platform-core output/readiness semantics over existing review artifacts
• Seams affected: none beyond existing review/evidence/export artifact truth
• Neutral platform terms preserved or introduced: review pack, evidence basis, output contract, customer-safe, internal package, limitations, export readiness
• Provider-specific semantics retained and why: only where existing stored report or review content already contains provider-backed labels
• Why this does not deepen provider coupling accidentally: no new Graph, provider, or identity contract is introduced
• Follow-up path: none

UI / Surface Guardrail Impact

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Customer Review Workspace decision card/readiness labels	yes	Native Filament page plus existing Blade composition	customer-safe review readiness, evidence/proof, download affordance	page, URL-query, derived payload	no	Existing route only
Customer Review Workspace review-pack panel	yes	Native Filament page plus existing Blade composition	package status, export readiness, evidence basis, PII warning	page payload	no	Derived only
Review-derived ZIP output files	yes	existing export file contract	metadata, section detail, executive entrypoint disclosure	artifact payload	no	No route change
Review Pack Resource detail/header wording	no by default	existing Filament resource/detail	artifact proof remains existing behavior	none unless repo truth later proves a contradiction on the signed download path	yes if unexpectedly touched	keep out of scope for Spec 347 unless a minimal consistency patch becomes unavoidable

Decision-First Surface Role

Surface	Decision Role	Human-in-the-loop Moment	Immediately Visible for First Decision	On-Demand Detail / Evidence	Why This Is Primary or Why Not	Workflow Alignment	Attention-load Reduction
Customer Review Workspace	Primary Decision Surface	Operator decides whether the current package can be shared, must be reviewed, or is internal-only	readiness label, reason, impact, evidence state, section state summary, PII/redaction state, primary next action	review detail, section detail, operation proof, diagnostics, download	Primary because it is the first customer-safe consumption screen	follows handoff/export decision workflow	removes guesswork from ZIP existence alone
Review-derived executive entrypoint	Secondary Context	Reader opens the package and decides what it is and what its limitations are	review status, evidence basis, limitations, disclosure, next action	structured appendix JSON, section detail files	Secondary because it explains the already generated artifact	supports handoff and archive consumption	removes ambiguity from raw file names
Review Pack detail/download	Secondary Context	Operator verifies artifact truth and authorized download path	artifact status, download availability, timestamps	file metadata, operation proof	Secondary because it is artifact detail, not the first sharing decision surface	supports artifact verification	keeps detail out of the first screen

Audience-Aware Disclosure

Surface	Audience Modes In Scope	Decision-First Default-Visible Content	Operator Diagnostics	Support / Raw Evidence	One Dominant Next Action	Hidden / Gated By Default	Duplicate-Truth Prevention
Customer Review Workspace	operator-MSP, customer-safe review consumer, support where authorized	readiness label, reason, impact, package state, evidence basis state, section completeness summary, PII/redaction visibility	operation proof, review detail, evidence link, section detail	raw payloads, fingerprints, internal-only diagnostics	review limitations or download qualified package	raw/support detail hidden or secondary	page states the readiness decision once; lower sections add proof
Executive summary	customer-safe or internal package reader	what the package is, evidence basis, limitations, disclosure, next action	none by default	JSON appendix only	review limitations or read appendix	internal-only/raw detail absent from markdown	limitations are explicit instead of implied by other files

UI/UX Surface Classification

Surface	Action Surface Class	Surface Type	Likely Next Operator Action	Primary Inspect/Open Model	Row Click	Secondary Actions Placement	Destructive Actions Placement	Canonical Collection Route	Canonical Detail Route	Scope Signals	Canonical Noun	Critical Truth Visible by Default	Exception Type / Justification
Customer Review Workspace	Utility / Workspace Decision	Read-only strategic review hub	decide whether to review limitations or download the package	explicit primary action in decision card	forbidden	secondary links and proof panels	none in scope	/admin/reviews/workspace	existing review or pack routes only	workspace shell, visible environment filter, package state	Customer Review Workspace	readiness, evidence basis, section limits, PII/redaction	none
Review Pack detail	Utility / Artifact Detail	Read-only artifact proof	verify package and download	existing detail affordance	current repo-real behavior only	secondary proof/actions stay in detail	existing regenerate/expire actions stay out of scope	existing review-pack collection route	existing review-pack detail route	workspace/environment context and artifact status	Review pack	artifact truth and download state	none

Operator Surface Contract

Surface	Primary Persona	Decision / Operator Action Supported	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
Customer Review Workspace	MSP/workspace operator	decide whether a current review package is customer-safe, limitations-bearing, or internal-only	workspace review hub	Can I rely on this package, can I share it, and what needs review first?	readiness label, evidence completeness, section completeness, PII/redaction, disclosure, next action	operation proof, lower-level evidence/report links, debug/support detail	review publication, review completeness, evidence completeness, package availability, output readiness, customer-safe boundary	none by default	review limitations, open review, qualified download	none in scope

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no
• New persisted entity/table/artifact?: no
• New abstraction?: maybe one bounded readiness mapper/presenter only
• New enum/state/reason family?: no persisted family; any labels stay derived
• New cross-domain UI framework/taxonomy?: no
• Current operator problem: published review, existing ZIP, and section files do not yet produce one trustworthy statement about output readiness and customer-safe sharing.
• Existing structure is insufficient because: metadata, review summary, section files, and workspace heuristics are not yet contract-aligned, so each can imply a different state.
• Narrowest correct implementation: derive one output-readiness contract from existing review/pack/evidence truth, harden the ZIP fields/files already present, and remap workspace labels to that contract.
• Ownership cost: spec-local contract docs, one bounded mapper, focused tests/browser smoke, and one UI audit update.
• Alternative intentionally rejected: new persisted readiness entity, new review-pack engine, new customer portal, or a full generator rewrite.
• Release truth: current-release truth.

Compatibility posture

This feature assumes a pre-production environment.

Compatibility shims, legacy ZIP aliases, dual file layouts, or fallback route/query aliases are out of scope unless repo truth later proves they are required.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Feature, Browser
• Validation lane(s): confidence, browser
• Why this classification and these lanes are sufficient: the core work is deterministic payload/file contract hardening plus server-rendered workspace/readiness semantics. Focused Feature tests can assert JSON fields, ZIP contents, section consistency, qualified labels, and authorization. One bounded Browser smoke is required because this is a strategic customer-safe first-screen surface.
• New or expanded test families:
  • apps/platform/tests/Feature/ReviewPack/Spec347ReviewPackOutputContractTest.php
  • apps/platform/tests/Feature/ReviewPack/Spec347ReviewPackReadinessSemanticsTest.php
  • apps/platform/tests/Feature/Filament/Spec347CustomerReviewWorkspaceOutputReadinessTest.php
  • apps/platform/tests/Browser/Spec347ReviewPackOutputReadinessSmokeTest.php
• Relevant existing regressions to rerun:
  • apps/platform/tests/Feature/EnvironmentReview/EnvironmentReviewExecutivePackTest.php
  • apps/platform/tests/Feature/Localization/CustomerReviewSurfaceLocalizationTest.php
  • apps/platform/tests/Feature/Filament/Spec342CustomerReviewWorkspaceConsumptionTest.php
  • apps/platform/tests/Browser/Spec342CustomerReviewWorkspaceConsumptionSmokeTest.php
• Fixture / helper cost impact: reuse existing review-pack, customer-review, and evidence snapshot helpers. No new heavy default fixture family should be introduced.
• Heavy-family visibility / justification: one explicit browser smoke only
• Special surface test profile: global-context-shell + customer-safe strategic review surface + artifact contract
• Standard-native relief or required special coverage: special coverage required for no-false-ready claims, limitations copy, and qualified download labels
• Reviewer handoff: reviewers must confirm no new persistence, no revived legacy file layout assumptions, no false customer-safe/export-ready/certification claims, and no weakened signed-download controls
• Budget / baseline / trend impact: none expected beyond one explicit browser smoke addition
• Escalation needed: document-in-feature for unreachable states; follow-up-spec only if repo truth reveals a broader governance-artifact lifecycle gap
• Active feature PR close-out entry: Guardrail / Smoke Coverage
• Planned validation commands:

cd apps/platform
./vendor/bin/sail artisan test tests/Feature/ReviewPack/Spec347ReviewPackOutputContractTest.php tests/Feature/ReviewPack/Spec347ReviewPackReadinessSemanticsTest.php tests/Feature/Filament/Spec347CustomerReviewWorkspaceOutputReadinessTest.php --compact
./vendor/bin/sail artisan test tests/Feature/EnvironmentReview/EnvironmentReviewExecutivePackTest.php tests/Feature/Localization/CustomerReviewSurfaceLocalizationTest.php tests/Feature/Filament/Spec342CustomerReviewWorkspaceConsumptionTest.php --compact
./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec347ReviewPackOutputReadinessSmokeTest.php tests/Browser/Spec342CustomerReviewWorkspaceConsumptionSmokeTest.php --compact
./vendor/bin/sail artisan test --compact --filter=ReviewPack
./vendor/bin/sail artisan test --compact --filter=CustomerReviewWorkspace
./vendor/bin/sail pint --dirty
git diff --check

Summary

TenantPilot already produces a structured review-derived Review Pack ZIP. The current strength is not file generation itself; it is the existing mix of:

• executive-summary.md
• metadata.json
• summary.json
• sections.json
• one JSON file per review section under sections/

The current gap is semantic trust, not missing basic output. Spec 347 therefore hardens:

1. the Review Pack file contract
2. readiness semantics across review, evidence, section, export, and customer-safe states
3. qualified workspace/download wording
4. explicit limitations and disclosure
5. tests that block false ready-to-share claims and protect existing workspace/executive-pack/localization behavior

Goals

1. Define the Review Pack file contract over the current review-derived ZIP shape.
2. Make review status, review completeness, evidence completeness, section completeness, export readiness, and customer-safe boundaries explicit and non-conflated.
3. Ensure a section file may exist while the section completeness state is missing, and explain that semantics clearly.
4. Surface PII/redaction and internal-vs-customer-safe boundaries explicitly.
5. Prevent unqualified Ready to share or similar claims when the repo-backed contract says otherwise.
6. Preserve signed-download safety and non-certification disclosure.

Non-Goals

• rebuild the Review Pack generator from scratch
• add new persistence
• add a portal
• add legal attestation or certification workflow
• replace JSON with PDF
• redesign Governance Inbox
• redesign Customer Review Workspace beyond bounded output-readiness wording and proof hierarchy
• change OperationRun semantics
• change EvidenceSnapshot generation semantics
• add new GRC/control taxonomies

User Scenarios & Testing (mandatory)

User Story 1 - Interpret A Generated Package (Priority: P1)

As an MSP operator, I need a generated Review Pack to explain whether it is ready, limited, or internal-only so I can decide whether to share it safely.

Why this priority: This is the core trust gap. A ZIP existing is not enough.

Independent Test: Generate or inspect a review-derived ZIP and assert that required files, required metadata fields, limitations/disclosure, and section semantics are present and non-contradictory.

Acceptance Scenarios:

1. Given a review-derived package with missing evidence completeness, When the ZIP is inspected, Then it still contains required files but explicitly reports incomplete evidence basis and limitations.
2. Given a section marked missing, When its file exists, Then the contract explains that source completeness is missing rather than the file being absent.

---

User Story 2 - Read Output Readiness In The Workspace (Priority: P1)

As an operator viewing Customer Review Workspace, I need qualified output-readiness labels so the UI does not imply customer-safe sharing when the package contract is incomplete.

Why this priority: The workspace is the first decision surface for handoff/share decisions.

Independent Test: Render the workspace with repo-backed incomplete-evidence, missing-section, PII-included, and ready states and assert qualified labels and primary actions.

Acceptance Scenarios:

1. Given has_ready_export is false or evidence completeness is missing, When the workspace renders, Then it does not show unqualified Ready to share.
2. Given PII is included, When the workspace renders, Then it shows operator-visible sharing caution and does not imply customer-safe external sharing without review.

---

User Story 3 - Preserve Safe Download And Honest Disclosure (Priority: P2)

As an authorized operator, I need downloads to remain safe while the package itself clearly states what it does and does not claim.

Why this priority: Export/download safety must remain intact while wording changes.

Independent Test: Re-run signed-download tests and confirm executive-summary disclosure/limitations are present.

Acceptance Scenarios:

1. Given a ready pack with valid signed URL, When it is downloaded, Then current authorization and signed-link behavior remain unchanged.
2. Given an executive summary is generated, When evidence or section readiness is limited, Then it includes a limitations note and non-certification disclosure.

Functional Requirements

• FR-001: The review-derived Review Pack output contract MUST document required root files, current section-detail file placement, required metadata fields, required summary fields, and required section fields.
• FR-002: Required root files for a valid review-derived package MUST remain executive-summary.md, metadata.json, summary.json, and sections.json.
• FR-003: Section-detail files MAY remain under sections/, but the contract MUST explain that repo truth and MUST require consistency with sections.json.
• FR-004: metadata.json MUST expose bundle contract identity, artifact family, review-pack identity, released-review identity/state, evidence-basis identity/state, entrypoint declaration, appendix declaration, options, and redaction integrity.
• FR-005: summary.json MUST expose review status, review completeness, evidence resolution, section state counts, publish blockers, delivery-bundle summary, and enough state to derive export readiness honestly.
• FR-006: Every entry in sections.json MUST expose section key, title, sort order, required flag, completeness state, summary payload, and render payload.
• FR-007: Section-detail files MUST either carry the same key/required/state contract directly or be explicitly documented as legacy shape if the implementation keeps the current thinner file payload.
• FR-008: The contract MUST define the meaning of published, review_completeness_state, evidence completeness, section completeness, has_ready_export, and customer-safe/internal-only boundaries so they are not treated as synonyms.
• FR-009: Customer Review Workspace MUST not show unqualified share-ready language when the repo-backed contract says evidence is incomplete, required sections are incomplete, export is not ready, or PII/customer-safe review still needs operator review.
• FR-010: Workspace output-readiness copy MUST explicitly surface evidence basis state, section limitations summary, and PII/redaction visibility when relevant.
• FR-011: executive-summary.md MUST include an explicit limitations section whenever evidence completeness, required section completeness, export readiness, or PII/customer-safe boundaries limit sharing.
• FR-012: Non-certification disclosure MUST remain present in the executive summary and remain visible in the customer-safe workspace/output context where share-ready language appears.
• FR-013: Existing signed download authorization, expiry, and file-existence checks MUST remain unchanged in behavior.
• FR-014: Focused tests MUST verify required files, required fields, section/file consistency, qualified readiness mapping, PII visibility, disclosure presence, and preserved download safety.

Non-Functional Requirements

• NFR-001: Output must be self-explanatory to an operator or stakeholder without requiring source-code knowledge.
• NFR-002: No new persisted readiness entity or public status family may be introduced unless repo truth proves a derived contract is insufficient.
• NFR-003: Customer-safe wording must remain conservative and must not imply certification, audit opinion, or guaranteed compliance.
• NFR-004: Backward-compatibility expectations remain pre-production lean. Current contract hardening may replace weaker wording/shape directly rather than adding compatibility shims.
• NFR-005: Diagnostics, raw payloads, fingerprints, and support-only details remain hidden or secondary on customer-safe default paths.

Acceptance Criteria

• AC-001: specs/347-review-pack-output-contract-readiness-semantics/contracts/review-pack-output-contract.md exists and documents the current file contract, required fields, and file-to-section consistency.
• AC-002: specs/347-review-pack-output-contract-readiness-semantics/contracts/readiness-semantics.md exists and defines the derived readiness vocabulary without introducing a new persisted state family.
• AC-003: specs/347-review-pack-output-contract-readiness-semantics/contracts/customer-safe-output-boundary.md exists and defines customer-safe, internal-only, PII/redaction, and disclosure boundaries.
• AC-004: Focused Feature tests verify required root files and required metadata/summary fields for review-derived packs.
• AC-005: Focused Feature tests verify that missing section completeness can coexist with a present section file and that the semantics are explicit.
• AC-006: Focused Feature/Livewire tests verify the workspace does not show unqualified share-ready language when the output contract is incomplete.
• AC-007: Focused tests verify visible PII/redaction/customer-safe warnings when include_pii is true or when the package is not customer-safe ready.
• AC-008: Executive summary output contains a limitations block when contract-backed limitations exist.
• AC-009: Signed-download behavior remains gated and functional.
• AC-010: One bounded Browser smoke proves the qualified readiness labels and download wording on the strategic workspace surface.

Risks

• Risk 1 - readiness language becomes a second hidden framework
  Mitigation: keep the contract derived-only; prefer one bounded mapper and explicit docs over a generic workflow engine.
• Risk 2 - package truth and workspace truth drift again
  Mitigation: make tests assert the same state vocabulary across ZIP files and workspace rendering.
• Risk 3 - user draft expectations conflict with current file layout
  Mitigation: preserve repo truth (sections/ detail files) and document the deviation explicitly instead of inventing a compatibility layer.
• Risk 4 - customer-safe wording becomes over-optimistic
  Mitigation: prefer conservative labels and require explicit disclosure for evidence gaps, missing sections, and PII.

Assumptions And Open Questions

Assumptions

• Current review-derived ZIP layout remains the baseline.
• The narrowest correct implementation is derived-contract hardening, not a file-layout rewrite.
• Existing review-pack and workspace tests can be extended rather than replaced wholesale.

Open Questions

• Should section-detail files gain section_key, required, and sort_order directly, or should the contract treat sections.json as the canonical section index and keep section-detail files thinner?
  Current bias: prefer adding the missing keys if it is low-risk, but keep the contract honest either way.
• Should the qualified download labels live only on the workspace first-screen path, or also in Review Pack Resource detail/header copy?
  Current bias: workspace first. Review Pack Resource detail/header copy stays out of scope unless implementation finds a strict signed-download contradiction that cannot be solved on the workspace surface alone.

Follow-up Spec Candidates

• Spec 348 - Provider readiness / evidence refresh follow-through if output-readiness blockers need clearer operational remediation.
• Spec 349 - Customer-facing localization and copy hardening for review/output semantics.
• Spec 350 - Sellable smoke matrix for governance, review, evidence, and export flows.
• Spec 351 - Customer portal output-boundary contract after platform output semantics are stable.