TenantAtlas/specs/349-customer-review-workspace-output-resolution-guidance/repo-truth-map.md

Spec 349 - Repo Truth Map

Status: implemented
Created: 2026-06-03
Scope: Customer Review Workspace output resolution guidance and Environment Review detail output-guidance separation

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

Implementation Update

• Shared derived guidance now lives in apps/platform/app/Support/ReviewPacks/ReviewPackOutputResolutionGuidance.php.
• Workspace top-card rendering consumes that shared mapping in CustomerReviewWorkspace.php and customer-review-workspace.blade.php.
• Environment Review detail consumes the same mapping through EnvironmentReviewResource::outputGuidanceState() and filament/infolists/entries/review-pack-output-guidance.blade.php.

Classification Vocabulary

• repo-verified: directly observed in runtime code, tests, routes, or completed adjacent specs
• derived from existing truth: can be computed safely from current models or payloads
• gap: no current operator-guidance contract exists even though raw truth exists
• deferred: intentionally out of scope for Spec 349

Current Output-Readiness Truth

Data point	Classification	Repo evidence	Spec 349 handling
ReviewPackOutputReadiness exists	repo-verified	apps/platform/app/Support/ReviewPacks/ReviewPackOutputReadiness.php	Reuse as the raw readiness source
Current readiness states are customer_safe_ready, published_with_limitations, internal_review_package_available, export_not_ready	repo-verified	same class constants	Reuse; any extra display state must remain derived-only
Current limitation codes include export_not_ready, evidence-basis codes, required_sections_incomplete, publish_blockers_present, contains_pii, and disclosure_missing	repo-verified	same class	Reuse as source for grouped guidance
Current readiness already exposes primary_reason, primary_action, limitations, and section_summary	repo-verified	same class return payload	Prefer reuse before adding new fields
Current readiness is derived-only and not persisted	repo-verified	same class plus current data model	Preserve; no new persisted truth

Current Customer Review Workspace Truth

Data point	Classification	Repo evidence	Spec 349 handling
Strategic decision card already exists	repo-verified	apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php	Keep as the first decision surface
Workspace already derives label, reason, impact, primary action, and secondary action from readiness truth	repo-verified	workspaceReadinessLabel(), workspaceReadinessReason(), workspaceReadinessImpact(), workspaceReadinessActions() in CustomerReviewWorkspace.php	Consolidate into calmer grouped guidance
Effective state already folds finding follow-up and accepted-risk follow-up into published_with_limitations	repo-verified	effectiveWorkspaceReadinessState()	Preserve honest customer-safe logic
Workspace already has proof/detail panels and diagnostics sections	repo-verified	Blade view + page payload methods	Keep proof secondary; do not redesign the page broadly
Workspace does not yet expose a compact grouped limitation list tied to one dominant blocker	gap	current decision card and proof panel structure	Primary gap to close
Workspace does not yet expose a dedicated technical-details disclosure contract for output guidance	gap	current payload/view structure	Add bounded disclosure only

Current Environment Review Detail Truth

Data point	Classification	Repo evidence	Spec 349 handling
Detail surface is Filament infolist-driven	repo-verified	EnvironmentReviewResource::infolist()	Do not invent a custom detail page unless repo truth later forces it
Customer-workspace mode narrows header actions on review detail	repo-verified	ViewEnvironmentReview::getHeaderActions()	Preserve current access/handoff behavior
Detail surface already shows artifact truth, review fields, executive posture, and sections	repo-verified	EnvironmentReviewResource::infolist()	Reorder or refine only as needed for clearer status separation
Detail surface does not yet expose an explicit "review status vs output readiness vs sharing/publication state" summary	gap	current infolist sections and labels	Primary gap to close

Current Route And Scope Truth

Data point	Classification	Repo evidence	Spec 349 handling
Workspace route is /admin/reviews/workspace	repo-verified	route list	Keep unchanged
Environment Review detail route is workspace/environment scoped	repo-verified	route list for environment-reviews/{record}	Keep unchanged
Review Pack routes are workspace/environment scoped plus one signed download route	repo-verified	route list for review-packs and admin/review-packs/{reviewPack}/download	Keep unchanged
Evidence overview and detail routes already exist	repo-verified	route list for /admin/evidence/overview and scoped evidence detail	Reuse for guidance links where needed
Workspace surface uses explicit environment_id query filtering	repo-verified	CustomerReviewWorkspace::environmentFilterUrl() and current tests	Preserve; no hidden shell-state fallback

Current Documentation Truth

Data point	Classification	Repo evidence	Spec 349 handling
Durable workspace page report exists as ui-006-customer-review-workspace.md	repo-verified	docs audit file	Update this report
No ui-009-review-pack-output-contract.md exists	repo-verified	docs audit inventory; ui-009 is Provider Connections	Record this user-draft conflict explicitly; do not invent or overwrite ui-009

Current Test Truth

Test surface	Classification	Repo evidence	Spec 349 handling
Output-readiness contract and workspace wording already have Spec 347 coverage	repo-verified	Spec347ReviewPackOutputContractTest.php, Spec347ReviewPackReadinessSemanticsTest.php, Spec347CustomerReviewWorkspaceOutputReadinessTest.php	Reuse as regression base
Customer Review Workspace already has broader page and pack-access tests	repo-verified	CustomerReviewWorkspacePageTest.php, CustomerReviewWorkspacePackAccessTest.php	Extend or reuse proportionally
Environment Review detail already has UI contract coverage	repo-verified	EnvironmentReviewUiContractTest.php	Extend or reuse proportionally

Primary Repo-Truth Gaps To Close

1. No grouped output-resolution guidance object exists yet over the raw readiness truth.
2. No one-primary-blocker + one-primary-action contract is enforced across workspace and detail surfaces.
3. Review detail does not yet distinguish review publication/completeness from output-readiness/sharing truth clearly enough.
4. The user-draft audit-doc target conflicts with existing repo numbering and must be corrected explicitly.