# Readiness Semantics

Status: prepared  
Created: 2026-06-02  
Scope: Derived readiness vocabulary for review-derived Review Pack output and Customer Review Workspace mapping

This contract defines derived semantics only. It does not introduce a new persisted state family.

## 1. Distinct Truth Dimensions

The following must remain distinct:

- review publication state
- review completeness state
- evidence completeness state
- section completeness state
- export artifact availability
- output-readiness / limitations state
- customer-safe vs internal-only boundary

None of these may silently stand in for the others.

## 2. Current Repo-Backed Inputs

Current repo truth already exposes inputs for derived readiness:

- `EnvironmentReview.status`
- `EnvironmentReview.completeness_state`
- `EnvironmentReview.summary.publish_blockers`
- `EnvironmentReview.summary.section_state_counts`
- `EnvironmentReview.summary.has_ready_export`
- `EvidenceSnapshot.completeness_state`
- `ReviewPack.status`
- `ReviewPack.file_path`
- `ReviewPack.file_disk`
- `ReviewPack.expires_at`
- `ReviewPack.options.include_pii`

## 3. Semantic Rules

### 3.1 Published

`published` means:

- the environment review has been released/published

It does **not** automatically mean:

- evidence complete
- export ready
- customer-safe ready
- limitation-free

### 3.2 Review Completeness

`review_completeness_state` means:

- review composition truth according to current review logic

It does **not** automatically mean:

- every required section is complete
- evidence basis is complete
- the generated package is ready to share

### 3.3 Evidence Completeness

Evidence completeness means:

- the anchored evidence basis behind the released review

If evidence completeness is partial, stale, or missing:

- a package may still exist
- the output must be labeled as limited or review-required
- unqualified share-ready wording is forbidden

### 3.4 Section Completeness

Section completeness describes:

- whether the required source truth for that section is complete enough

It does **not** describe:

- whether a section-detail file exists

Therefore:

- a detail file may exist while completeness is `missing`
- the UI and executive summary must explain that the section structure exists but the source basis is incomplete

### 3.5 Ready Export

`has_ready_export` means:

- the current review summary believes a ready export artifact is available

It does **not** automatically mean:

- customer-safe ready
- PII-free
- no limitations

### 3.6 Customer-Safe

Customer-safe readiness is derived only when repo truth supports all of:

- released review exists
- evidence basis is sufficiently complete for the current contract
- required section limitations are visible or absent
- non-certification disclosure is present
- no internal-only/raw/support detail is exposed by default
- PII/redaction state is explicit

If those conditions are not met, the package may still be:

- available with limitations
- internal package available
- export not ready
- review required before sharing

## 4. Preferred Derived Vocabulary

Presentation labels remain derived, not persisted.

Preferred vocabulary:

- `Customer-safe review pack ready`
- `Published with limitations`
- `Internal review package available`
- `Export not ready`
- `Evidence basis incomplete`
- `Required sections incomplete`
- `Contains PII`
- `Protected values hidden`
- `Review limitations before customer sharing`

Discouraged vocabulary unless the contract truly proves it:

- `Ready to share`
- `Customer-ready`
- `Auditor-ready`
- `Certified`
- `Compliant`

## 5. Qualified Download Semantics

Download affordances should follow contract-backed semantics:

- `Download customer-safe review pack` only when the contract truly supports it
- `Download review pack with limitations` when the export exists but is limited
- `Download internal review pack` when the package is useful but not clearly customer-safe

The implementation may keep shorter wording only if the same state is clearly explained adjacent to the action.

## 6. Limitations Trigger Conditions

An explicit limitations state is required when any of these are true:

- evidence completeness is not complete
- required sections are partial, stale, blocked, or missing
- `has_ready_export` is false
- PII is included and customer-safe external sharing still needs review
- publish blockers are present

## 7. Explicit Non-Claims

No readiness label may imply:

- certification
- legal attestation
- full audit opinion
- guaranteed compliance

Those remain forbidden unless a future spec intentionally introduces that product truth.