37 — Build-pack validation and archive tooling

Purpose

The specification must be reproducible as an artifact rather than depending on an ad hoc manual ZIP. BUILD_PACK.json is the machine-readable release identity and count contract. The scripts in scripts/ are part of the build-pack contract.

Environment

Python 3.11 or newer;
dependencies pinned in scripts/requirements-validate.txt;
no network access is required after those dependencies are installed.

Example isolated setup:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r scripts/requirements-validate.txt
python scripts/validate_pack.py

On Windows PowerShell, activate with .venv\Scripts\Activate.ps1.

Validator

python3 scripts/validate_pack.py checks schemas, semantic playbook rules, package inventories, examples, catalog delivery state, digests, OpenAPI references, SQL coverage, documentation references, 28 golden prompt fixtures, archive integrity files when present and common secret-like material.

It must run before and after changes to any schema, package, fixture, catalog, API, SQL or core specification document.

Deterministic archive build

python3 scripts/build_archive.py

The builder:

runs the validator;
regenerates FILE_INDEX.txt and PACK_MANIFEST.sha256;
runs validation again;
writes files in sorted order with fixed ZIP metadata;
invokes the independent archive verifier.

The SHA-256 manifest covers every regular file except the manifest itself. The file index includes both generated integrity files. Symlinks are rejected.

A custom output outside the package directory can be selected with:

python3 scripts/build_archive.py --output ../DevRunbook_Autonomous_Build_Pack_v1_2.zip

Archive verification

python3 scripts/verify_archive.py ../DevRunbook_Autonomous_Build_Pack_v1_2.zip

Verification checks ZIP paths, duplicate entries, symlinks, CRCs, file-index completeness, embedded SHA-256 values and the extracted specification validator. A successful unzip -t alone is not enough because it does not prove cross-file contracts or embedded hashes.

Golden prompt generation

python3 scripts/reference_compose.py regenerates the 28 canonical composed prompt fixtures. python3 scripts/reference_compose.py --check verifies byte equality without modifying files. The main validator runs the check automatically. See document 39.

2.4 KiB Raw Blame History