# Spec 342 - Repo Truth Map

Status: implemented  
Created: 2026-06-01  
Scope: Customer Review Workspace final customer-safe consumption

This map is the implementation guardrail for Spec 342. Runtime work must update this file before changing code when it discovers additional truth, unsupported states, or deferred concepts.

## Classification Vocabulary

- `repo-verified`: observed in current application code, tests, specs, or routes.
- `derived from existing model`: available by deriving from existing persisted model fields or relationships.
- `foundation-real`: foundation exists, but the final customer-consumption behavior may still need wiring or productization.
- `not available`: no repo-backed truth or action exists in the current codebase.
- `deferred`: intentionally out of scope for Spec 342.

## Core Surface Truth

| Data point | Classification | Repo evidence | Spec 342 handling |
|---|---|---|---|
| Customer Review Workspace page | repo-verified | `apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php` | Existing route and page remain the target. |
| Customer Review Workspace Blade view | repo-verified | `apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php` | Productize existing view; do not add a new route. |
| Canonical route | repo-verified | Page slug `reviews/workspace`; Filament admin panel route | Keep `/admin/reviews/workspace`. |
| Environment filter | repo-verified | `environmentFilterUrl()` emits `environment_id`; workspace hub filter helpers exist | Keep `environment_id` as page filter only. |
| Legacy `/admin/t` context | not available | Spec 341 cleanup and current roadmap boundary | Do not reintroduce. |
| Page-open audit event | repo-verified | `WorkspaceAuditLogger` usage in `CustomerReviewWorkspace` | Preserve safe audit metadata. |
| First-screen decision card | repo-verified | Current Blade renders `customer-review-decision-card`; Spec 342 tests assert one primary action and false-claim prevention | Final consumption decision card is implemented on the existing page. |
| Review package index/table | repo-verified | Existing Filament table in `CustomerReviewWorkspace` | Keep secondary to first-screen decision/proof content. |
| Diagnostics section | repo-verified | Current Blade has diagnostics/disclosure payload; Spec 342 feature/browser tests assert collapsed default and hidden raw payloads | Kept collapsed by default. |

## Review Truth

| Data point | Classification | Repo evidence | Spec 342 handling |
|---|---|---|---|
| Review record | repo-verified | `EnvironmentReview` model | Use as review source. |
| Published/released review | derived from existing model | `EnvironmentReviewStatus::Published`, `published_at` | Use for latest released review. |
| Review completeness | repo-verified | `EnvironmentReviewCompletenessState`, `completeness_state` | Render as readiness dimension. |
| Review summary | repo-verified | `EnvironmentReview.summary` cast | Use only customer-safe fields; avoid raw payload. |
| Current export review pack | repo-verified | `current_export_review_pack_id`, `currentExportReviewPack()` | Use for current export/pack state. |
| Review sections | repo-verified | `EnvironmentReviewSection` relationship | Use for customer-safe content only if already productized. |
| Customer acknowledgement/attestation | not available | No attestation model or workflow identified in current truth map | Do not implement; optional unavailable copy only. |

## Evidence And Review Pack Truth

| Data point | Classification | Repo evidence | Spec 342 handling |
|---|---|---|---|
| Evidence snapshot | repo-verified | `EvidenceSnapshot` model and relation from `EnvironmentReview` | Use as evidence availability/proof source. |
| Evidence status/completeness | repo-verified | `EvidenceSnapshotStatus`, `EvidenceCompletenessState` | Render evidence states truthfully. |
| Evidence items | repo-verified | `EvidenceSnapshotItem` relationship | Use as proof count/detail only when customer-safe. |
| Stored report | repo-verified | `StoredReport` model and Evidence Overview references | Link/show only when repo-backed for selected review context. |
| Review pack | repo-verified | `ReviewPack` model | Use as review-pack state source. |
| Review pack status | repo-verified | `ReviewPackStatus`, model constants | Render queued/generating/ready/failed/expired. |
| Review pack file metadata | repo-verified | `file_disk`, `file_path`, `file_size`, `sha256`, `generated_at`, `expires_at` | Download/export available only when ready and authorized. |
| Signed download route | repo-verified | `ReviewPackDownloadController`, route `admin.review-packs.download` | Use only when existing authorization and file truth permit. |
| External delivery/email/PSA | not available | No repo-backed delivery mechanism for this surface | Show unavailable/deferred only if useful. |

## Findings And Accepted Risk Truth

| Data point | Classification | Repo evidence | Spec 342 handling |
|---|---|---|---|
| Finding records | repo-verified | `Finding` model | Use for customer-safe finding summaries. |
| Finding status/severity | repo-verified | `Finding` constants and fields | Show counts/labels where repo-backed. |
| Owner/assignee/due fields | repo-verified | `owner_user_id`, `assignee_user_id`, `due_at` | Show only if loaded and customer-safe. |
| Accepted risk / exception records | repo-verified | `FindingException` model | Summarize accepted risks visibly. |
| Exception status | repo-verified | `FindingException` status constants | Use shared badge/status semantics. |
| Exception validity | repo-verified | `current_validity_state`, validity constants | Surface expired/expiring/missing-support states. |
| Owner/rationale/expiry/review date | repo-verified | `owner_user_id`, `request_reason`, `expires_at`, `review_due_at`, decision records; Spec 342 tests assert owner, rationale, next review, and missing review-date copy | Visible in the accepted-risk summary when repo-backed. |
| Exception decision history | repo-verified | `FindingExceptionDecision` relationship | Use as proof only when customer-safe and authorized. |
| Accepted risk lifecycle beyond current exception truth | deferred | Follow-up candidate in user draft | Do not add lifecycle backend in Spec 342. |

## Audit And Operation Proof

| Data point | Classification | Repo evidence | Spec 342 handling |
|---|---|---|---|
| OperationRun proof | repo-verified | `OperationRun` model and links from review/evidence/pack | Show as secondary proof only. |
| Operation status/outcome | repo-verified | `OperationRunStatus`, `OperationRunOutcome` | Do not collapse into evidence or customer-safe output truth. |
| OperationRun raw payload/context | repo-verified but diagnostics-only | `OperationRun.context`, `summary_counts`, `failure_summary` | Hidden by default; capability-gated if shown. |
| Audit log | repo-verified | `AuditLog`, `WorkspaceAuditLogger`, page-open event | Preserve and link only if repo-backed/authorized. |
| Customer-visible audit export | deferred | Not required by Spec 342 | Leave to follow-up if needed. |

## RBAC And Context Truth

| Data point | Classification | Repo evidence | Spec 342 handling |
|---|---|---|---|
| Workspace membership | repo-verified | `WorkspaceContext`, workspace membership models | Required for page access. |
| Managed environment entitlement | repo-verified | `EnvironmentReviewRegisterService::authorizedTenants()` and policies | Required before rendering environment-bound records. |
| Capability-aware actions | repo-verified | `Capabilities`, policies, `UiEnforcement` patterns | Use existing action visibility/authorization. |
| Cross-workspace `environment_id` | repo-verified guard expectation | Spec 341 and existing navigation/filter tests | Return safe no-access/404. |
| Diagnostics capability | repo-verified | Existing capability/policy patterns; customer workspace diagnostics remain collapsed and raw/support data hidden by default | Hide/unavailable when not authorized. |

## Implementation Close-Out

- No new persisted entity, enum/status family, generic readiness framework, migration, package, env var, queue, scheduler, Graph scope, route, or Filament asset was introduced.
- No standalone presenter class was added. The existing `CustomerReviewWorkspace` page now exposes bounded page-local derived payload helpers for the decision card, six-step flow, findings panel, accepted-risk panel, and proof separation.
- Browser screenshots cover not-ready/evidence-incomplete, ready-with-evidence, review-pack-available, findings-need-attention, accepted-risks-present, diagnostics-collapsed, and dark-mode states under `artifacts/screenshots/`.
- The explicit "evidence missing" screenshot name from planning was represented by the repo-backed evidence-incomplete/not-ready state; no backend truth was faked to manufacture a separate missing-evidence path.
- UI coverage docs were not changed because this spec productizes the existing `/admin/reviews/workspace` route and does not add navigation, a new route, or a new archetype.