feat(ci): PyPI publish workflow on tag via OIDC Trusted Publisher

[cipher813]

Summary

Adds .github/workflows/release.yml so future PyPI releases happen automatically on tag push instead of needing manual twine upload.

Trigger: push of a tag matching v* (e.g. v0.5.0rc3, v0.5.0, v0.6.0). Manual workflow_dispatch with a ref input is included as a re-publish fallback.

Pipeline:

1. build — checkout → setup Python 3.12 → install build + twine → python -m build → twine check → verify tag version matches built wheel version (catches a forgotten __init__.py / pyproject.toml bump) → upload artifact.
2. publish — download artifact → pypa/gh-action-pypi-publish@release/v1 with id-token: write. OIDC token exchange handles auth; no API token in repo secrets.

The publish job runs under a pypi GitHub environment so a manual approval gate can be added later (Settings → Environments → pypi → Required reviewers) without changing the workflow.

One-time PyPI-side setup (required before the workflow can publish)

1. Visit https://pypi.org/manage/project/flow-doctor/settings/publishing/
2. Add a new pending publisher:
   • PyPI Project Name: flow-doctor
   • Owner: cipher813
   • Repository name: flow-doctor
   • Workflow filename: release.yml
   • Environment name: pypi

After that, the release flow is just:

# bump version in __init__.py + pyproject.toml + CHANGELOG, commit, merge PR
git checkout main && git pull
git tag -a v0.5.0rc3 -m "..."
git push origin v0.5.0rc3
# → release.yml fires → wheel + sdist on PyPI

Test plan

• YAML syntax + structure valid (commit + push succeeded; GitHub Actions parser will catch real errors on first dispatch).
• First end-to-end exercise: next rc bump after merge.
• Sanity: tag-vs-version mismatch path — push a tag that disagrees with __init__.py; the build job should fail loudly.

🤖 Generated with Claude Code