feat: release tooling (version bump, changelog, tag, GitHub release) - #17

Summary

Release tooling for projects built from this starter, while the starter itself stays at 0.1.0. Four commits, one concern each.

scripts/release.py (standard library only)

• prepare patch|minor|major|X.Y.Z: refuses off a clean, up-to-date main or when the tag exists; runs pytest; writes the version into pyproject.toml (the only place it lives, APP_VERSION reads the installed metadata); moves the changelog's Unreleased section under the version, or renders one from Conventional Commit subjects since the last tag (security maps to a Security heading); commits chore(release): vX.Y.Z; creates an annotated tag with the notes; pushes branch and tag atomically after confirmation. --dry-run, --skip-tests, --no-push, --yes, --allow-branch.
• Reads the project name from pyproject.toml: a renamed clone changes nothing in it.
• Refuses while [tool.release] starter = true, which this PR sets in the starter. A clone flips it once (added to the "Adapting this starter" list).
• After the release commit, runs poetry install --only-root so a running dev server reports the new version (editable installs write the metadata at install time).
• Tags are created with --cleanup=verbatim: git otherwise strips the ### Heading lines of the notes as comments. The reference script this is ported from has that latent bug; the end-to-end test caught it here.
• check-version, notes, version serve the workflow.

.github/workflows/release.yml on v* tags and manual runs: verify (tag vs pyproject.toml, notes exist; nothing installed), ci (reuses ci.yml through a new workflow_call trigger: lint, mypy, pip-audit, the suite with PostgreSQL), build (poetry build, wheel and sdist as an artifact), publish (gh release create with the changelog section as notes and the archives attached, --prerelease for a suffixed version). A manual run stops after build. No third-party release action.

Docs: docs/releasing.md (how a release is put together, choosing the version for an HTTP API, step by step, the starter and its clones, writing the notes, troubleshooting, hotfixes); setup, index, README, AGENTS and the changelog header updated. black, flake8 and mypy now cover scripts/ too.

Verification

• tests/test_release_script.py (pure, 26 tests): bumps and pre-release ordering, pyproject.toml reading and writing (other tables untouched, marker present/absent/false), generated notes incl. breaking and skipped housekeeping, changelog splitting and insertion, and full prepare runs in a throwaway repository with a bare remote: commit, verbatim tag message, empty Unreleased, check-version pass and fail, notes, version, dry run changes nothing, the starter guard, refusals off main, with a dirty tree and when behind.
• On this repository: prepare minor --dry-run stops with the starter message and the tree stays clean; version prints 0.1.0; check-version v0.1.0 passes.
• Locally: black, flake8, mypy (incl. scripts/) clean; 88 pure tests pass. CI runs the full suite.
• The release workflow cannot run on a tag in the starter by design; after merging, a manual Run workflow on main exercises verify, ci and build without publishing.

🤖 Generated with Claude Code