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.
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
|