# 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:

```bash
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

```bash
python3 scripts/build_archive.py
```

The builder:

1. runs the validator;
2. regenerates `FILE_INDEX.txt` and `PACK_MANIFEST.sha256`;
3. runs validation again;
4. writes files in sorted order with fixed ZIP metadata;
5. 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:

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

## Archive verification

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