549a9a0004
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 1m0s
Implemented the output contract and readiness semantics for review packs. Also added spec 348. Includes changes to ChooseEnvironment, CustomerReviewWorkspace, GenerateReviewPackJob and related blade views. Added comprehensive tests.
177 lines
4.5 KiB
Markdown
177 lines
4.5 KiB
Markdown
# 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.
|