ahmido 12ea7f9924 feat: review pack output contract and readiness semantics (spec 347/348) (#419 )

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

2026-06-02 23:17:08 +00:00

4.8 KiB

Raw Blame History

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:

Promoted detail-file contract
Add section_key, required, and sort_order to each detail file.
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

4.8 KiB Raw Blame History