Add package release smoke

Author: marcofortina

README.md

@@ -493,3 +493,6 @@ reach the Python 3.9 matrix job:
 ```bash
 python scripts/check-python39-compat.py
 ```
+
+
+Release packages can be validated with `scripts/package-release-smoke.sh --output-dir dist/package-release-smoke`.

docs/guides/package-release-smoke.md

@@ -0,0 +1,27 @@
+<!--
+Copyright (C) 2026 Marco Fortina
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Package release smoke
+
+The package release smoke verifies that the published artifacts can be built and installed from the wheel.
+
+```bash
+scripts/package-release-smoke.sh --output-dir dist/package-release-smoke
+```
+
+The smoke builds the source distribution and wheel, runs `twine check` when `twine` is installed, installs the wheel in a temporary virtual environment and executes deterministic CLI checks from the installed package.
+
+The output directory contains:
+
+```text
+summary.txt
+manifest.json
+SHA256SUMS
+logs/
+*.tar.gz
+*.whl
+```
+
+Use `--skip-twine` only when running in a minimal environment without the release validation dependencies.

docs/reference/release.md

@@ -31,6 +31,12 @@ Run the full local gate before tagging:
 scripts/release-check.sh
 ```
 
+For package-only release validation:
+
+```bash
+scripts/package-release-smoke.sh --output-dir dist/package-release-smoke
+```
+
 The script verifies:
 
 - the `CHANGELOG.md` section for the package version;
@@ -44,7 +50,7 @@ The script verifies:
 - unit and documentation regression tests;
 - `automax plugins coverage --strict`;
 - strict MkDocs build;
-- source distribution and wheel package smoke.
+- source distribution and wheel package release smoke.
 
 For a metadata-only pass while debugging documentation or CI wiring:
 

mkdocs.yml

@@ -74,6 +74,7 @@ nav:
     - Policy and Risk Preflight: guides/policy-risk-preflight.md
     - Approval Gates: guides/approval-gates.md
     - Runtime Evidence Index: guides/runtime-evidence-index.md
+    - Package Release Smoke: guides/package-release-smoke.md
     - Run Event Stream: guides/run-event-stream.md
     - Publishing Documentation: guides/publishing-docs.md
   - Reference:

scripts/package-release-smoke.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# Copyright (C) 2026 Marco Fortina
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+OUTPUT_DIR="${AUTOMAX_PACKAGE_RELEASE_SMOKE_OUTPUT_DIR:-${ROOT}/dist/package-release-smoke}"
+SKIP_TWINE="${AUTOMAX_PACKAGE_RELEASE_SMOKE_SKIP_TWINE:-0}"
+KEEP_WORK="${AUTOMAX_PACKAGE_RELEASE_SMOKE_KEEP_WORK:-0}"
+
+usage() {
+  cat <<'EOF'
+Usage: scripts/package-release-smoke.sh [--output-dir DIR] [--skip-twine]
+
+Build source/wheel distributions, verify metadata when twine is available,
+install the wheel into a temporary virtualenv and run deterministic CLI smoke
+commands from the installed package.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --output-dir)
+      OUTPUT_DIR="$2"
+      shift 2
+      ;;
+    --skip-twine)
+      SKIP_TWINE=1
+      shift
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+WORK_DIR="$(mktemp -d "${TMPDIR:-/tmp}/automax-package-release-smoke.XXXXXX")"
+cleanup() {
+  if [[ "${KEEP_WORK}" != "1" ]]; then
+    rm -rf "${WORK_DIR}"
+  else
+    echo "Kept work directory: ${WORK_DIR}"
+  fi
+}
+trap cleanup EXIT
+
+DIST_DIR="${WORK_DIR}/dist"
+VENV_DIR="${WORK_DIR}/venv"
+LOG_DIR="${OUTPUT_DIR}/logs"
+mkdir -p "${DIST_DIR}" "${LOG_DIR}"
+rm -f "${OUTPUT_DIR}/summary.txt" "${OUTPUT_DIR}/manifest.json" "${OUTPUT_DIR}/SHA256SUMS"
+
+cd "${ROOT}"
+
+run_step() {
+  local name="$1"
+  shift
+  echo "== ${name} =="
+  "$@" >"${LOG_DIR}/${name}.log" 2>&1
+}
+
+run_step build python -m build --sdist --wheel --outdir "${DIST_DIR}"
+
+if [[ "${SKIP_TWINE}" != "1" ]]; then
+  if python -m twine --version >/dev/null 2>&1; then
+    run_step twine-check python -m twine check "${DIST_DIR}"/*
+  else
+    echo "twine not available; set up dev dependencies to enable metadata check" >"${LOG_DIR}/twine-check.log"
+  fi
+else
+  echo "skipped by --skip-twine" >"${LOG_DIR}/twine-check.log"
+fi
+
+run_step venv python -m venv "${VENV_DIR}"
+# shellcheck source=/dev/null
+. "${VENV_DIR}/bin/activate"
+python -m pip install --upgrade pip >"${LOG_DIR}/pip-upgrade.log" 2>&1
+run_step install-wheel python -m pip install "${DIST_DIR}"/*.whl
+run_step cli-version automax --version
+run_step cli-doctor automax doctor
+run_step cli-plugins automax plugins list
+run_step cli-schema automax schema export --kind job
+
+deactivate
+
+cp "${DIST_DIR}"/* "${OUTPUT_DIR}/"
+(
+  cd "${OUTPUT_DIR}"
+  sha256sum ./*.{tar.gz,whl} > SHA256SUMS
+)
+
+python - <<PY
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+out = Path(${OUTPUT_DIR@Q})
+artifacts = []
+for path in sorted(list(out.glob("*.tar.gz")) + list(out.glob("*.whl"))):
+    artifacts.append({"name": path.name, "size": path.stat().st_size})
+manifest = {
+    "format": "automax-package-release-smoke-v1",
+    "ok": True,
+    "artifacts": artifacts,
+    "logs": sorted(path.name for path in (out / "logs").glob("*.log")),
+}
+(out / "manifest.json").write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+lines = ["Package release smoke: OK", f"artifacts={len(artifacts)}"]
+lines.extend(f"- {item['name']} ({item['size']} bytes)" for item in artifacts)
+(out / "summary.txt").write_text("\n".join(lines) + "\n", encoding="utf-8")
+PY
+
+cat "${OUTPUT_DIR}/summary.txt"

scripts/release-check.sh

@@ -110,7 +110,7 @@ if [[ "${AUTOMAX_RELEASE_CHECK_SKIP_DOCS:-0}" != "1" ]]; then
 fi
 
 if [[ "${AUTOMAX_RELEASE_CHECK_SKIP_PACKAGE:-0}" != "1" ]]; then
-  scripts/package-smoke.sh
+  scripts/package-release-smoke.sh --output-dir "${TMP_DIR}/package-release-smoke"
 fi
 
 echo "Release check passed"

tests/test_documentation_and_regressions.py

@@ -2097,6 +2097,26 @@ def test_runtime_evidence_suite_is_documented_and_optional():
     assert "set AUTOMAX_SSH_HOST and AUTOMAX_SSH_USER" in result.stderr
 
 
+def test_package_release_smoke_script_is_documented_and_release_wired():
+    script = Path("scripts/package-release-smoke.sh").read_text(encoding="utf-8")
+    release = Path("scripts/release-check.sh").read_text(encoding="utf-8")
+    docs = "\n".join(
+        path.read_text(encoding="utf-8")
+        for path in [
+            Path("docs/guides/package-release-smoke.md"),
+            Path("docs/reference/release.md"),
+            Path("mkdocs.yml"),
+        ]
+    )
+
+    assert "automax-package-release-smoke-v1" in script
+    assert "python -m build --sdist --wheel" in script
+    assert "python -m twine check" in script
+    assert "automax schema export --kind job" in script
+    assert "scripts/package-release-smoke.sh" in release
+    assert "Package Release Smoke: guides/package-release-smoke.md" in docs
+
+
 def test_database_smoke_script_runs_sqlite_and_lists_engines(tmp_path: Path):
     script = Path("scripts/database-smoke.sh")
 
@@ -2179,7 +2199,7 @@ def test_release_check_script_covers_public_release_guardrails():
     assert "docs generate-plugins" in text
     assert "examples/runbooks/RUNBOOK_INDEX.md is stale" in text
     assert "plugins coverage --strict" in text
-    assert "scripts/package-smoke.sh" in text
+    assert "scripts/package-release-smoke.sh" in text
     assert "AUTOMAX_RELEASE_CHECK_SKIP_DOCS" in text
     assert "AUTOMAX_RELEASE_CHECK_SKIP_PACKAGE" in text
     assert "Check release metadata guardrails" in ci