chore: add PyPI release workflow

[kaiitunnz]

Purpose

Add the release automation needed to publish FlowMesh's lightweight PyPI distributions and its GHCR container images from immutable release tags. The release pipeline builds and verifies every published distribution, validates synchronized versions and internal pins, smoke-tests the umbrella extras, publishes through PyPI Trusted Publishing, then verifies the matching container images and retags them as :latest with downgrade protection.

Changes

• PyPI release workflow (.github/workflows/release.yml) — build/verify and publish jobs, manual TestPyPI/PyPI dispatch, package_pattern filter for staggered Trusted Publisher onboarding, twine check distribution metadata validation, and a tag-reachability guard that aborts unless the release tag is an ancestor of origin/main.
• Image release workflow (.github/workflows/release-images.yml) — verify-and-retag pipeline for the six GHCR images: anonymous read of each published ref, multi-arch manifest + OCI version/revision label assertions against the release tag and commit SHA, then a :latest retag with downgrade-protection (overrideable via force_latest dispatch input). Idempotently appends a digest table to the GitHub Release body via sentinel markers.
• Release helpers (scripts/ci/, scripts/dev/) — check_release_version.py (synchronized versions + internal pin agreement), check_image_release.py (manifest/label verifier), retag_image_release.py (downgrade-protected :latest retag, accepts OCI indexes and legacy Docker manifest lists), append_release_digests.py (Release-body digest table writer with null-body normalization), and bump_version.py (synchronized version + pin bump helper).
• CLI override flags (cli/stack/src/flowmesh_cli_stack/stack.py, docs/CLI.md) — --image-tag and --build-ref on flowmesh stack build / stack push, applied after load_env so they actually override the .env value. Matches the pre-existing --image-tag pattern on pull / up / down.
• Release docs (docs/RELEASE.md, CONTRIBUTING.md) — PyPI Trusted Publishing setup, release prep, TestPyPI rehearsal, PyPI publishing, image push from the build host, GHCR first-time setup (visibility + repo link + ghcr environment), install verification, and an "If a release goes wrong" recovery section (PyPI immutability, yank, next-patch, .postN, image-only re-run).
• Tests (tests/scripts/test_append_release_digests.py) — regression coverage for _read_current_body's null / empty / whitespace normalization and the sentinel strip-and-replace contract.
• Packaging metadata (root + sdk/, sdk/stack/, cli/, cli/stack/, hook/ pyproject.toml, plus LICENSE copies under each sub-package) — bump [build-system].requires to setuptools>=77, switch to SPDX-string license = "Apache-2.0", declare license-files = ["LICENSE"]. Each published wheel now carries its own Apache-2.0 text under *.dist-info/licenses/LICENSE and declares License-Expression: Apache-2.0 instead of License: UNKNOWN.

Design

• Tag-driven, immutable inputs. Both workflows check out the release tag and refuse to proceed if it isn't reachable from origin/main. PyPI versions and GHCR image refs are derived from the tag, never from main.
• Publishing split from PR validation. package-build.yml still smoke-tests PRs; release.yml owns tag-based artifacts and PyPI upload. release-images.yml is the post-publish auditor for the GHCR image set built from a GPU build host outside CI (no self-hosted runners on the public repo).
• Trusted Publishing via OIDC. GitHub pypi / testpypi environments host the OIDC claim; production publishing can require manual approval without static upload tokens. A ghcr environment gates :latest retag with the same approval model.
• Synchronized version policy, explicit. check_release_version.py fails if any of the six package versions diverge from the vX.Y.Z tag or if any first-party dependency pin still points at an older version. bump_version.py applies the same policy locally so prep is mechanical.
• PEP 440-aware :latest policy. _is_release (in check_image_release.py) gates :latest to non-prerelease, non-dev, non-local versions; .postN is eligible. retag_image_release.py parses the existing :latest's OCI image.version label and refuses to retag when it points at a newer or equal version (overrideable with --force). A transient inspect failure aborts rather than silently disabling the guard.
• Per-distribution license metadata. flowmesh[sdk] / flowmesh[cli] / flowmesh[hook] resolve to multiple separately-published wheels; each declares Apache-2.0 and ships LICENSE text for Apache § 4 redistribution and so PyPI / audit tools don't report License: UNKNOWN.

Test Plan

uv run python scripts/ci/check_release_version.py --tag v0.1.0
uv run python scripts/dev/bump_version.py 0.1.0 --check
uv run pre-commit run --all-files
uv run pytest tests --ignore=tests/worker/test_mp_executor_cleanup_gpu.py
uv build --all-packages --out-dir /tmp/flowmesh-release-dist
uv run python scripts/ci/check_package_build.py --dist /tmp/flowmesh-release-dist
uvx twine==6.2.0 check /tmp/flowmesh-release-dist/*
for w in /tmp/flowmesh-release-dist/*.whl; do
  unzip -l "$w" | grep "licenses/LICENSE"
  unzip -p "$w" "*/METADATA" | grep -E '^License(-Expression|-File)?:'
done

Test Result

• check_release_version.py --tag v0.1.0 → exit 0, "Release package versions are synchronized at 0.1.0".
• bump_version.py 0.1.0 --check → exit 0, "Package versions are already set to 0.1.0".
• pre-commit run --all-files → all hooks pass.
• pytest tests --ignore=tests/worker/test_mp_executor_cleanup_gpu.py → 759 passed.
• uv build --all-packages → produced all six distributions (flowmesh, flowmesh-sdk, flowmesh-sdk-stack, flowmesh-cli, flowmesh-cli-stack, flowmesh-hook) as .whl + .tar.gz.
• check_package_build.py --dist <dist> → smoke tests pass for flowmesh[sdk], flowmesh[hook], flowmesh[cli]; flowmesh --help runs from the built CLI wheel.
• twine check dist/* → all distributions pass metadata validation.
• License audit: every wheel ships *.dist-info/licenses/LICENSE (11351 bytes, root Apache-2.0 text) and declares License-Expression: Apache-2.0 + License-File: LICENSE in METADATA.

---

Pre-submission Checklist

• I have read the contribution guidelines.
• I have run pre-commit run --all-files and fixed any issues.
• I have added or updated tests covering my changes (if applicable).
• I have verified that uv run pytest tests/ passes locally.
• If I changed shared schemas or proto definitions, I have checked downstream compatibility across Server and Worker.
• If I changed the SDK or CLI, I have verified the affected packages work (uv sync --all-packages --group ci --frozen).
• If this is a breaking change, I have prefixed the PR title with [BREAKING] and described migration steps above.
• I have updated documentation or config examples if user-facing behavior changed.

[timzsu]

Two inline comments, plus this test coverage issue:

The release script tests cover the helper predicates well, but the main release-safety paths are still lightly tested. It would be useful to add mocked tests for check_image_release._check_target() and retag_image_release._plan_retags(), especially around missing labels, platform mismatch, and newer/equal/older :latest behavior. That would also make the builder-label issue easier to catch in unit tests.

[timzsu]

LGTM.