# 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.