Publish DevRunbook source

docs/37-build-pack-tooling.md

@@ -0,0 +1,63 @@
+# 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.