Release governance (manual next-tag checklist)

This document is the authoritative release gate for public version tags. It is not enforced by .cursor/commands/pre-release.md (local developer confidence only).

Do not create the next version tag until every item below is green.

Wave 0 eng criteria (closed)

Release hygiene A1–A10, Config 1.7 atomic apply, Config 1.8 curated to_dict, and docs/inventory parity are implemented in-tree (stocktake refreshed for 0.9.7). Remaining work before a public 1.0 tag is this checklist + evidence runbook, plus programme gates in pre_release_roadmap_1_0.md (human-testing wave, unfamiliar-user validation, severity triage, performance/trust owner sign-off, RTD go-live) — not missing Wave 0 code.

Hardening triage: classify findings with release_severity_triage_1_0.md before scheduling RC work.

Checklist

  1. All Wave 0 acceptance criteria green (release hygiene A1–A10 + Config 1.7 atomic apply + docs/inventory parity).

  2. Green CI on the exact intended release commit (full Python matrix 3.10–3.12 + compose-config + release-checks). Failed or cancelled matrix members block.

  3. pyproject.toml version matches the intended tag (v prefix aside).

  4. Dated Keep-a-Changelog section for that version in CHANGELOG.md.

  5. Clean worktree (git status --porcelain=v1 --untracked-files=all empty of unexpected paths).

  6. Fresh-clone installation evidence per docs/runtime/install_verification_matrix.md.

  7. Release-evidence bundle complete (see below).

  8. Fixable CVEs cleared or exceptional waiver fully filled + approved in docs/dev/dependency_audit.md.

  9. No denylist violations; scripts/secrets_check.sh green.

  10. Recommended (GUI primary surface): make test-gui-acceptance green on the intended commit, and the residual AppTest-blind items in gui_acceptance_residual_checklist.md recorded as pass/fail/skip in the evidence notes.

Humans (or an explicit user instruction outside the pre-release command) perform tag/push after this checklist is satisfied.

Release-evidence bundle

Attach (machine- or human-readable) at tag time:

  • Stale-reference sweep (scripts/release/stale_refs.sh)

  • Repo hygiene audit (scripts/release/repo_hygiene_audit.py — warn mode until promoted)

  • Dependency audit + installed-package inventory (clean-env and, where practical, image)

  • Documented-install matrix results

  • Tracked-data allowlist comparison (scripts/release/check_tracked_data.py)

  • Secrets and denylist results

  • Package-version check

  • Canonical Compose assertions (scripts/release/assert_compose_bind.sh)

  • Docker smoke result after fresh build

  • Config 1.7 inventory / parity evidence

  • (Recommended) GUI acceptance: make test-gui-acceptance result + residual checklist notes (gui_acceptance_residual_checklist.md)

Local evidence runbook (checklist item 7)

Run from the repository root on the intended release commit (clean worktree preferred). Record each outcome as pass / failure / skipped (with reason). Environment-dependent checks that cannot run must be skipped, never a silent pass. Write machine-readable artefacts under artifacts/pre-release/ when a script does so (that directory is gitignored).

A. Always-run hygiene (no Docker required)

bash scripts/release/stale_refs.sh
bash scripts/release/assert_compose_bind.sh
python3 scripts/release/check_tracked_data.py
bash scripts/secrets_check.sh
PYTHONPATH=src python3 -c "import re, pathlib, transcriptx; t=pathlib.Path('pyproject.toml').read_text(); m=re.search(r'^version\\s*=\\s*\"([^\"]+)\"', t, re.M); assert m and m.group(1)==transcriptx.__version__, (m.group(1) if m else None, transcriptx.__version__); print(transcriptx.__version__)"

Use PYTHONPATH=src so the check reads the tree under release, not a stale site-packages install.

Expected: each script prints OK / exits 0. Denylist may soft-warn on ignored forbidden paths; that is not a hard failure unless TRANSCRIPTX_STRICT_IGNORED_FORBIDDEN=1.

Unit coverage for helpers:

python -m pytest -q tests/release/test_wave0_release_hygiene.py

B. Config 1.7 / inventory parity evidence

python -m pytest -q \
  tests/core/config/test_file_overrides_atomicity.py \
  tests/core/config/test_registry_ownership.py \
  tests/core/config/test_nested_file_overrides_probe.py \
  tests/core/config/test_settings_file_load_pilots.py

Expected: green. Ownership invariant (authoritative): 47 pilots / 660 Pydantic leaves / 16 legacy (676 total) via test_ownership_invariant_counts. Behaviour matrix: docs/dev/../archive/plans/file_override_behaviour_matrix.md.

C. Dependency / clean-env audit (optional locally; required for tag when tooling available)

bash scripts/release/clean_env_audit.sh

Expected: pass, or skipped with reason (missing build / network / host blockers). Host pip install '.[full]' is not required for Wave 0 when platform blockers apply — see docs/dev/dependency_audit.md. Attach waiver rows for any accepted CVEs.

D. Docker smoke + image audit (optional locally; required for tag when Docker available)

docker compose -f docker-compose.yml build
make docker-smoke
bash scripts/release/image_pip_check.sh

Expected: pass, or skipped (Docker not available).

E. Install-matrix cells

Execute the cells claimed in docs/runtime/install_verification_matrix.md (core extras, Docker production-image proof, Python 3.10–3.12 as practical). Record pass/fail/skip per cell; do not claim a cell green without evidence.

F. CI on exact commit

Confirm GitHub Actions on the intended SHA: jobs tests (3.10–3.12), compose-config, and release-checks are green. Failed or cancelled matrix members block tagging.

Bundle contents checklist

Artefact

Command / source

Location / note

Stale refs

scripts/release/stale_refs.sh

stdout / CI log

Compose bind

scripts/release/assert_compose_bind.sh

stdout / CI log

Tracked data

scripts/release/check_tracked_data.py

stdout / CI log

Secrets + denylist

scripts/secrets_check.sh

stdout / CI log

Package version

pyproject ↔ transcriptx.__version__

stdout

Config atomicity + ownership

pytest commands in §B

pytest log

Clean-env audit

scripts/release/clean_env_audit.sh

artifacts/pre-release/ when produced

Image pip check

scripts/release/image_pip_check.sh

stdout / artefacts

Docker smoke

make docker-smoke

stdout

Install matrix

manual / scripted per matrix doc

notes attached at tag

CI

Actions on exact SHA

link or run IDs