# Spec 342 - Customer Review Consumption State Contract

Status: implemented  
Created: 2026-06-01  
Scope: Customer Review Workspace first-screen consumption states

This contract defines display states for Customer Review Workspace. These states are presentation labels derived from existing repo truth. They are not a new enum, lifecycle family, persisted status, or platform workflow framework.

## Universal Rules

- Default-visible content must answer: status, reason, impact, and primary next action.
- Primary next action must be singular per rendered state.
- Diagnostics default is `Collapsed` or `Unavailable`.
- Raw provider JSON, raw OperationRun payload, fingerprints, stack traces, internal IDs as primary labels, and platform reason families are hidden by default.
- Customer-safe, auditor-ready, evidence-backed, export-ready, healthy, complete, or compliant claims appear only when repo-backed.
- OperationRun proof is not evidence output, review-pack output, or customer-safe readiness.
- External delivery and attestation are unavailable unless implementation discovers repo-backed truth and updates this contract/spec first.

## Implementation Notes

- Spec 342 implemented these states as presentation-only, page-local derived payloads on the existing Customer Review Workspace.
- Open findings block a ready-to-share claim even when evidence and review-pack truth are available; the pack/export state remains visible but customer-safe output is `Needs review`.
- Accepted-risk summaries are visible by default when repo-backed; full accepted-risk records remain collapsed.
- Findings and accepted-risk follow-up states use concrete decision-card copy based on repo-backed counts, owners, rationale, and review-date context instead of generic issue text.
- The prior repeated readiness summary cards are absorbed into the six-step consumption flow and right-rail proof panels to reduce duplicate status surfaces.
- `Download review pack` appears only as the primary action when the review is actually ready to share; follow-up states keep review-pack availability as status context and route the primary action to the review.
- Diagnostics remain collapsed by default, and raw provider/support payloads, stack traces, fingerprints, and raw OperationRun JSON are not rendered in the default customer-safe surface.

## Flow Steps

The review readiness flow uses these steps:

1. Review data
2. Evidence
3. Findings triaged
4. Accepted risks reviewed
5. Review pack
6. Customer-safe output

## Presentation Vocabulary

- `Available`
- `Missing`
- `Required`
- `Generating`
- `Failed`
- `Ready`
- `Needs review`
- `Not ready`
- `Unavailable`
- `Collapsed`
- `Deferred`

## State Contracts

### 1. Review Not Ready

| Field | Contract |
|---|---|
| Visible status | Review not ready |
| Reason | Required review data or evidence is missing. |
| Impact | This review should not be shared as customer-ready yet. |
| Primary next action | Complete review preparation, only if repo-supported and authorized; otherwise show unavailable. |
| Findings summary | Unavailable or deferred unless repo-backed review/finding data exists. |
| Accepted risks state | Unavailable or deferred unless repo-backed exception data exists. |
| Evidence state | Missing or unavailable. |
| Review pack state | Unavailable. |
| Customer-safe output state | Not ready. |
| Export state | Unavailable. |
| Diagnostics default | Collapsed/unavailable. |

### 2. Review Ready, Evidence Missing

| Field | Contract |
|---|---|
| Visible status | Review ready, evidence missing |
| Reason | Review summary exists, but supporting evidence is not available. |
| Impact | Findings can be discussed, but the review is not evidence-backed yet. |
| Primary next action | Open review or generate/open evidence only when repo-supported and authorized. |
| Findings summary | Available when review-derived or finding data is repo-backed. |
| Accepted risks state | Available when exception data is repo-backed. |
| Evidence state | Missing. |
| Review pack state | Required or unavailable. |
| Customer-safe output state | Needs review or not ready; never evidence-backed. |
| Export state | Unavailable unless a repo-backed review pack file is independent and valid. |
| Diagnostics default | Collapsed. |

### 3. Review Ready With Evidence

| Field | Contract |
|---|---|
| Visible status | Review ready with evidence |
| Reason | Review summary and supporting evidence are available. |
| Impact | Customer stakeholders can consume the review and inspect evidence. |
| Primary next action | Review findings or open evidence, based on repo-backed attention state. |
| Findings summary | Open/attention counts where repo-backed. |
| Accepted risks state | Visible if accepted risks exist. |
| Evidence state | Available. |
| Review pack state | Required, generating, failed, or available from `ReviewPack` truth. |
| Customer-safe output state | Needs review or ready only when review/pack truth supports it. |
| Export state | Available only from ready non-expired pack file truth. |
| Diagnostics default | Collapsed. |

### 4. Review Pack Required

| Field | Contract |
|---|---|
| Visible status | Review pack required |
| Reason | Review data exists, but no review pack is available. |
| Impact | Customer-safe export/download is not ready yet. |
| Primary next action | Generate review pack only when existing repo action is supported and authorized; otherwise open review/evidence. |
| Findings summary | Available if repo-backed. |
| Accepted risks state | Available if repo-backed. |
| Evidence state | Available or missing from evidence truth. |
| Review pack state | Required. |
| Customer-safe output state | Not ready or needs review. |
| Export state | Unavailable. |
| Diagnostics default | Collapsed. |

### 5. Review Pack Available

| Field | Contract |
|---|---|
| Visible status | Review pack available |
| Reason | A review pack is available for this review. |
| Impact | The review can be consumed and exported according to workspace policy if the pack is repo-backed as customer-safe and authorized. |
| Primary next action | Open review pack or download review pack when authorized and file metadata supports it. |
| Findings summary | Still visible; pack availability must not hide findings needing attention. |
| Accepted risks state | Still visible; accepted risks must not be hidden in diagnostics. |
| Evidence state | Available or needs review based on linked evidence. |
| Review pack state | Available. |
| Customer-safe output state | Ready only when repo-backed; otherwise needs review. |
| Export state | Available only for ready, non-expired pack with file metadata and authorization. |
| Diagnostics default | Collapsed. |

### 6. Findings Need Attention

| Field | Contract |
|---|---|
| Visible status | Findings need attention |
| Reason | One or more findings require customer review or operator follow-up. |
| Impact | Review should not be treated as complete until findings are assigned, accepted, resolved, or otherwise addressed. |
| Primary next action | Review findings. |
| Findings summary | Required; show repo-backed counts and customer-safe row preview. |
| Accepted risks state | Visible separately if accepted risks also exist. |
| Evidence state | Available/missing from evidence truth. |
| Review pack state | Available/required/generating/failed from pack truth. |
| Customer-safe output state | Needs review unless repo truth proves no action remains. |
| Export state | Available only when file truth supports it; export does not suppress findings attention. |
| Diagnostics default | Collapsed. |

### 7. Accepted Risks Present

| Field | Contract |
|---|---|
| Visible status | Accepted risks present |
| Reason | Some findings have accepted risk decisions. |
| Impact | Customer stakeholders should review owner, rationale, and expiry/review date where available. |
| Primary next action | Review accepted risks. |
| Findings summary | Shows related finding context where repo-backed. |
| Accepted risks state | Required; show owner/rationale/expiry/review date if present and missing-date copy if not. |
| Evidence state | Available/missing from evidence truth. |
| Review pack state | Available/required/generating/failed from pack truth. |
| Customer-safe output state | Needs review or ready depending on validity and review-pack truth. |
| Export state | Available only when file truth supports it. |
| Diagnostics default | Collapsed. |

### 8. No Findings Requiring Action

| Field | Contract |
|---|---|
| Visible status | No findings requiring action |
| Reason | This review has no open findings requiring customer action. |
| Impact | Review can be consumed or exported if evidence and review pack are available. |
| Primary next action | Open review pack or open evidence when authorized and repo-backed. |
| Findings summary | Shows zero-action state only if repo-backed. |
| Accepted risks state | Shows none/current state only if repo-backed. |
| Evidence state | Available/missing from evidence truth. |
| Review pack state | Available/required/generating/failed from pack truth. |
| Customer-safe output state | Ready only when evidence/review-pack truth supports it. |
| Export state | Available only when file truth supports it. |
| Diagnostics default | Collapsed. |

## Unavailable Or Deferred Concepts

| Concept | Default Contract |
|---|---|
| Customer acknowledgement / attestation | Do not implement in Spec 342. Show unavailable/deferred copy only if useful. |
| External delivery / email / PSA handoff | Do not implement in Spec 342. Show unavailable/deferred copy only if useful. |
| Auditor-ready certification | Do not claim unless future repo truth supports certification semantics. |
| Compliance/healthy claim | Do not claim from absence of findings alone. |
| Generic customer portal | Deferred follow-up outside Spec 342. |