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
163 lines
4.8 KiB
Markdown
163 lines
4.8 KiB
Markdown
# Review Pack Output Contract
|
|
|
|
Status: prepared
|
|
Created: 2026-06-02
|
|
Scope: Review-derived Review Pack ZIP contract
|
|
|
|
This document defines the current contract that Spec 347 is allowed to harden. It is intentionally repo-based and preserves the current review-derived ZIP shape unless implementation proves a narrower correction is required.
|
|
|
|
## 1. Required Root Files
|
|
|
|
A valid review-derived Review Pack ZIP must contain these root files:
|
|
|
|
- `executive-summary.md`
|
|
- `metadata.json`
|
|
- `summary.json`
|
|
- `sections.json`
|
|
|
|
These files already exist in current repo truth and remain the baseline contract.
|
|
|
|
## 2. Section-Detail Files
|
|
|
|
Current repo truth generates one JSON detail file per included review section under:
|
|
|
|
- `sections/%02d-%s.json`
|
|
|
|
Examples under current section ordering:
|
|
|
|
- `sections/10-executive_summary.json`
|
|
- `sections/15-control_interpretation.json`
|
|
- `sections/20-open_risks.json`
|
|
- `sections/30-accepted_risks.json`
|
|
- `sections/40-permission_posture.json`
|
|
- `sections/50-baseline_drift_posture.json`
|
|
- `sections/60-operations_health.json`
|
|
|
|
Important:
|
|
|
|
- the current repo truth uses a `sections/` directory, not root-level numbered files
|
|
- section-detail files may exist even when the corresponding section completeness is `missing`
|
|
- `sections.json` is the canonical section index unless implementation safely promotes more keys into each detail file
|
|
|
|
## 3. Required Metadata Fields
|
|
|
|
`metadata.json` must expose at least:
|
|
|
|
- `version`
|
|
- `generated_at`
|
|
- `delivery_bundle.contract`
|
|
- `delivery_bundle.artifact_family`
|
|
- `delivery_bundle.review_pack_id`
|
|
- `delivery_bundle.released_review.id`
|
|
- `delivery_bundle.released_review.status`
|
|
- `delivery_bundle.released_review.completeness_state`
|
|
- `delivery_bundle.evidence_basis.snapshot_id`
|
|
- `delivery_bundle.evidence_basis.snapshot_fingerprint`
|
|
- `delivery_bundle.evidence_basis.completeness_state`
|
|
- `delivery_bundle.entrypoint.file`
|
|
- `delivery_bundle.entrypoint.role`
|
|
- `delivery_bundle.appendix[]`
|
|
- `environment_review.id`
|
|
- `environment_review.status`
|
|
- `environment_review.completeness_state`
|
|
- `evidence_snapshot.id`
|
|
- `evidence_snapshot.fingerprint`
|
|
- `evidence_snapshot.completeness_state`
|
|
- `options.include_pii`
|
|
- `options.include_operations`
|
|
- `redaction_integrity.protected_values_hidden`
|
|
|
|
If implementation keeps the current contract constant and current file layout, missing fields should be added in place rather than by introducing a parallel contract layer.
|
|
|
|
## 4. Required Summary Fields
|
|
|
|
`summary.json` must expose at least:
|
|
|
|
- `environment_review_id`
|
|
- `review_status`
|
|
- `review_completeness_state`
|
|
- `evidence_resolution`
|
|
- `section_count`
|
|
- `section_state_counts`
|
|
- `publish_blockers`
|
|
- `delivery_bundle`
|
|
- `governance_package`
|
|
|
|
Strongly preferred for explicit readiness mapping:
|
|
|
|
- `has_ready_export`
|
|
- any derived label or reason fields only if they remain clearly derived and non-canonical
|
|
|
|
## 5. Required Section Fields
|
|
|
|
Every entry in `sections.json` must expose:
|
|
|
|
- `section_key`
|
|
- `title`
|
|
- `sort_order`
|
|
- `required`
|
|
- `completeness_state`
|
|
- `summary_payload`
|
|
- `render_payload`
|
|
|
|
Each section completeness state must remain derived from repo-backed review section truth.
|
|
|
|
Current section-detail files already expose:
|
|
|
|
- `title`
|
|
- `completeness_state`
|
|
- `summary_payload`
|
|
- `render_payload`
|
|
|
|
Spec 347 implementation must choose one of two valid contracts:
|
|
|
|
1. **Promoted detail-file contract**
|
|
Add `section_key`, `required`, and `sort_order` to each detail file.
|
|
|
|
2. **Canonical-index contract**
|
|
Keep `sections.json` as the canonical index and explicitly document that detail files are subordinate payloads keyed by filename plus `sections.json`.
|
|
|
|
## 6. File-To-Section Consistency Rules
|
|
|
|
For every section listed in `sections.json`:
|
|
|
|
- a corresponding detail file may exist under `sections/`
|
|
- if the detail file exists, its title and completeness state must not contradict `sections.json`
|
|
- if a section is marked `missing`, the detail file may still exist
|
|
- `missing` refers to source/evidence completeness, not to file absence by default
|
|
|
|
The implementation must not leave this semantics implicit.
|
|
|
|
## 7. Executive Entrypoint Rules
|
|
|
|
`executive-summary.md` is the human entrypoint and must:
|
|
|
|
- state review status
|
|
- state evidence-basis context
|
|
- include limitations when sharing is constrained
|
|
- include non-certification disclosure
|
|
- point to the structured appendix (`metadata.json`, `summary.json`, `sections.json`)
|
|
|
|
It must not:
|
|
|
|
- imply certification
|
|
- imply legal attestation
|
|
- imply guaranteed compliance
|
|
- leak raw/internal-only diagnostics
|
|
|
|
## 8. Backward-Compatibility Posture
|
|
|
|
This repo is still pre-production lean.
|
|
|
|
Therefore Spec 347 favors:
|
|
|
|
- hardening current file shapes in place
|
|
- documenting repo-truth deviations explicitly
|
|
- avoiding compatibility shims or parallel ZIP layouts
|
|
|
|
It does not favor:
|
|
|
|
- dual root-vs-sections layouts
|
|
- legacy alias files
|
|
- broad export-version migration machinery
|