# 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