TenantAtlas/specs/347-review-pack-output-contract-readiness-semantics/contracts/readiness-semantics.md

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.