TenantAtlas/specs/347-review-pack-output-contract-readiness-semantics/repo-truth-map.md

Spec 347 - Repo Truth Map

Status: prepared
Created: 2026-06-02
Scope: Review Pack output contract and Customer Review Workspace readiness semantics

This map records the repo-backed truth that Spec 347 is allowed to harden. It must be updated if runtime inspection during implementation reveals a narrower or broader truth boundary.

Classification Vocabulary

• repo-verified: directly observed in runtime code, tests, routes, or current spec history
• derived from existing truth: can be computed safely from current models or payloads
• foundation-real: existing foundation exists, but final contract semantics are still open
• not available: no repo-backed truth exists today
• deferred: intentionally out of scope for Spec 347

Current Review-Derived ZIP Shape

Data point	Classification	Repo evidence	Spec 347 handling
Review-derived ZIP exists	repo-verified	apps/platform/app/Jobs/GenerateReviewPackJob.php, apps/platform/tests/Feature/ReviewPack/EnvironmentReviewDerivedReviewPackTest.php	Keep as baseline; do not rewrite the generator
Required root files	repo-verified	metadata.json, summary.json, sections.json, executive-summary.md created in buildReviewDerivedFileMap()	Treat as required contract root files
Section-detail files live under sections/	repo-verified	buildReviewDerivedFileMap() writes sections/%02d-%s.json	Preserve repo truth; document deviation from user draft
Delivery contract constant	repo-verified	App\Services\ReviewPackService::REVIEW_DERIVED_DELIVERY_CONTRACT = auditor_ready_executive_export.v1	Preserve unless a narrow version bump is justified
Executive entrypoint filename	repo-verified	ReviewPackService::EXECUTIVE_ENTRYPOINT_FILENAME	Preserve

Current Metadata / Summary Truth

Data point	Classification	Repo evidence	Spec 347 handling
metadata.json.delivery_bundle.entrypoint	repo-verified	deliveryBundleMetadata()	Keep required
metadata.json.delivery_bundle.appendix	repo-verified	deliveryBundleMetadata()	Keep required
metadata.json.delivery_bundle.artifact_family	repo-verified	deliveryBundleMetadata()	Keep required
metadata.json.delivery_bundle.review_pack_id	repo-verified	deliveryBundleMetadata()	Keep required
metadata.json.delivery_bundle.released_review.*	repo-verified	deliveryBundleMetadata()	Keep required
metadata.json.delivery_bundle.evidence_basis.*	repo-verified	deliveryBundleMetadata()	Keep required
metadata.json.options.include_pii / include_operations	repo-verified	buildReviewDerivedFileMap()	Keep required
metadata.json.redaction_integrity.protected_values_hidden	repo-verified	buildReviewDerivedFileMap()	Keep required
summary.json.review_status / review_completeness_state	repo-verified	review-derived summary payload in buildReviewDerivedFileMap()	Keep required
summary.json.section_state_counts	repo-verified in review summary, not guaranteed in pack summary	EnvironmentReviewComposer writes it into EnvironmentReview.summary; summary.json currently merges the review summary	Verify and keep explicit
summary.json.has_ready_export	repo-verified in EnvironmentReview.summary; not guaranteed as a contract input in all consumers	EnvironmentReviewComposer seeds false; GenerateReviewPackJob sets true on successful generation	Keep explicit and consume honestly
summary.json.delivery_bundle	repo-verified	review-derived summary payload	Keep required

Current Section Truth

Data point	Classification	Repo evidence	Spec 347 handling
sections.json contains section_key, title, sort_order, required, completeness_state, summary_payload, render_payload	repo-verified	buildReviewDerivedFileMap()	Treat as canonical section index
Section-detail files include only title, completeness_state, summary_payload, render_payload	repo-verified	buildReviewDerivedFileMap()	Gap: detail files do not currently repeat key/required/order
Section files are generated even when section completeness is missing	derived from existing truth	every included section gets a detail file regardless of completeness state	Define and test this semantics explicitly
Section-file absence meaning	not available as explicit contract	no current doc/test explains absence semantics	Add contract documentation and focused tests

Current Review / Evidence / Export Readiness Truth

Data point	Classification	Repo evidence	Spec 347 handling
Review publication state	repo-verified	EnvironmentReview.status, published_at	Keep as distinct from export readiness
Review completeness state	repo-verified	EnvironmentReview.completeness_state	Keep distinct from evidence/export/customer-safe readiness
Evidence completeness state	repo-verified	EvidenceSnapshot.completeness_state, summary.evidence_basis, summary.evidence_resolution	Keep distinct
Review summary publish_blockers	repo-verified	EnvironmentReviewComposer	Keep distinct
Review summary has_ready_export	repo-verified	EnvironmentReviewComposer + GenerateReviewPackJob	Use as explicit signal, not implied magic
Review Pack artifact readiness	repo-verified	ReviewPack.status, file_path, file_disk, expires_at, signed download route	Keep distinct from customer-safe sharing
Customer-safe readiness	foundation-real	current workspace heuristics in CustomerReviewWorkspace::reviewReadinessForTenant()	Replace heuristic-only phrasing with contract-backed mapping
Internal-only / limitations-bearing label	not available as explicit contract	no current dedicated state label exists	Add derived contract only
PII visibility in package metadata	repo-verified	metadata.json.options.include_pii	Surface in UI/readiness mapping
PII visibility in workspace UI	not available	current workspace does not surface it	Gap to address

Current Customer Review Workspace Truth

Data point	Classification	Repo evidence	Spec 347 handling
Strategic first-screen decision card exists	repo-verified	customer-review-workspace.blade.php, Spec 342 tests	Keep as first decision surface
Current primary labels: Ready to share, Shareable with follow-up, Follow-up required before sharing	repo-verified	CustomerReviewWorkspace::reviewReadinessForTenant() and localization keys	Candidate wording to harden
Package availability states: available, evidence_incomplete, not_available, preparing, expired, unavailable	repo-verified	CustomerReviewWorkspace::governancePackageAvailability()	Reuse where possible; map more explicitly to output contract
Readiness does not explicitly consume include_pii	repo-verified absence	no PII branch in workspace readiness methods	Gap to address
Readiness does not explicitly consume a section completeness summary	repo-verified absence	section counts not surfaced on the decision card	Gap to address
Diagnostics remain collapsed	repo-verified	current Blade/tests	Preserve

Current Executive Summary Truth

Data point	Classification	Repo evidence	Spec 347 handling
Non-certification disclosure exists	repo-verified	buildExecutiveEntrypoint()	Preserve
Dedicated limitations section does not exist	repo-verified absence	executive summary currently has Executive story / Evidence basis / Key findings / Accepted risks / Governance decisions / Next actions / Non-certification disclosure / Structured auditor appendix	Add explicit limitations block when needed
Executive summary does not explicitly explain section-file-present + section-missing semantics	repo-verified absence	no such wording in buildExecutiveEntrypoint()	Gap to address

Current Download Safety Truth

Data point	Classification	Repo evidence	Spec 347 handling
Signed route required	repo-verified	ReviewPackDownloadController, ReviewPackDownloadTest	Preserve unchanged
Capability required	repo-verified	Capabilities::REVIEW_PACK_VIEW check	Preserve unchanged
Ready status required	repo-verified	controller check	Preserve unchanged
Expiry required	repo-verified	controller check	Preserve unchanged
File existence required	repo-verified	controller check	Preserve unchanged
Audit event on download	repo-verified	controller audit log	Preserve unchanged

Existing Proof Tests

Test surface	Classification	Repo evidence	Spec 347 handling
Review-derived ZIP contract basics	repo-verified	apps/platform/tests/Feature/ReviewPack/EnvironmentReviewDerivedReviewPackTest.php	Extend or complement
Review-derived executive entrypoint and section-order contract	repo-verified	apps/platform/tests/Feature/EnvironmentReview/EnvironmentReviewExecutivePackTest.php	Re-run and extend where Spec 347 changes the executive entrypoint or delivery-bundle semantics
Download safety	repo-verified	apps/platform/tests/Feature/ReviewPack/ReviewPackDownloadTest.php	Preserve and re-run
Review Pack generation	repo-verified	apps/platform/tests/Feature/ReviewPack/ReviewPackGenerationTest.php	Reuse helpers
Customer Review Workspace false-claim prevention	repo-verified	apps/platform/tests/Feature/Filament/Spec342CustomerReviewWorkspaceConsumptionTest.php	Extend or complement
Customer Review Workspace smoke	repo-verified	apps/platform/tests/Browser/Spec342CustomerReviewWorkspaceConsumptionSmokeTest.php	Use as pattern or overlap regression
Customer Review Workspace localization contract	repo-verified	apps/platform/tests/Feature/Localization/CustomerReviewSurfaceLocalizationTest.php	Re-run when readiness vocabulary changes

Primary Repo-Truth Gaps To Close

1. No explicit documented contract for section-detail files vs sections.json.
2. No explicit dedicated limitations block in the executive summary.
3. No first-class output-readiness contract that aligns ZIP payloads with workspace wording.
4. No explicit PII/redaction visibility on the workspace first screen.
5. Existing ready/share labels are stronger than the currently explicit bundle contract.