ahmido
12ea7f9924
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. Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #419
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.
|