Publish aces-sdl to PyPI and auto-release on merge to main (conventional-commit model, per aces-scenario-packs ADR 0006)

[Brad-Edwards]

Proposal

Publish aces-sdl to PyPI and make releases an automatic consequence of
promoting dev→main, adopting the conventional-commit-driven release model
defined in aces-scenario-packs ADR 0006 (docs/decisions/adrs/0006-conventional-commit-releases.md).
That ADR is written as a reusable blueprint — copy its four building blocks and
swap the repo-specific names.

Current state / gap

#537 (merged as #543) already did the hard part: the wheel bundles the
contract corpus and builds cleanly from implementations/python, and there is a
.github/workflows/release.yml. But that workflow:

• triggers only on a manual v* tag push (no auto-release on merge to main), and
• cuts a GitHub Release only — it does not publish to PyPI, and has no SBOM.

aces-sdl is unclaimed on PyPI (404), there are no v* tags in the repo,
and the version is a static version = "0.3.0" in
implementations/python/pyproject.toml. So the specific capability — PyPI +
push-to-main auto-release — is untracked. This issue closes that gap on top of
#537's foundation.

Target model (ADR 0006)

Releases become inescapable and governed by a mechanical rubric: merge freely
into dev; promoting dev→main is the release act, and
python-semantic-release (PSR) inspects the Conventional Commit messages since the
last tag, computes the next SemVer, creates the tag + GitHub Release, builds
dist, attaches an SBOM, and publishes to PyPI via OIDC trusted publishing (no
stored token). main stays branch-protected — PSR is tag-only (commit = false),
it never pushes a commit back to main.

Work (four building blocks + monorepo wrinkles)

1. Tag-driven versioning via hatch-vcs

Migrate implementations/python/pyproject.toml off the static version = "0.3.0":

• build-system.requires = ["hatchling", "hatch-vcs"]
• [project] dynamic = ["version"] (drop the static version)
• [tool.hatch.version] source = "vcs" and a gitignored version-file
• src/aces/__init__.py already reads __version__ from installed metadata
  (package_version("aces-sdl", ...)) — keep that; just align the fallback.

Monorepo wrinkle: the package lives in implementations/python, but git tags
are repo-global. Confirm hatch-vcs resolves the repo-root tag correctly for the
subdir build (uv build implementations/python), and that PSR's build_command
runs in / targets that subdirectory (dist must land where the publish + corpus
check expect it).

2. PSR config (tag-only, no commit-back)

Add to pyproject.toml:

[tool.semantic_release]
tag_format = "v{version}"
commit = false
allow_zero_version = true
major_on_zero = false
build_command = "..."   # build the implementations/python dist

[tool.semantic_release.branches.main]
match = "main"

3. Rewrite release.yml to the ADR-0006 shape

• on: push: branches: [main] + workflow_dispatch (with force input for bootstrap).
• concurrency: { group: release, cancel-in-progress: false }.
• One release job, environment: pypi, permissions: { contents: write, id-token: write }.
• Steps: checkout fetch-depth: 0 → python-semantic-release@v10 (id: release)
  → if released: build SBOM (CycloneDX) + gh release upload
  → if released: pypa/gh-action-pypi-publish@release/v1 (OIDC)
  → if released: python-semantic-release/publish-action@v10 (attach dist/*).
• Preserve #537's corpus guarantee: keep the "verify the contract corpus is
  bundled in the wheel" check (fail the release if the corpus payload is missing).

4. Conventional-commit enforcement (make it inescapable)

The repo already has pr-title-lint.yml + tools/check_pr_title.py. Verify it
enforces Conventional Commit types strictly enough to drive PSR (feat/fix/…),
or add amannn/action-semantic-pull-request. Ensure the PR-title check is
required on dev and main, squash_merge_commit_title = PR_TITLE, feature
PRs squash-merge into dev, and dev→main uses merge/rebase (never squash, so
per-change conventional history survives for PSR to read).

One-time setup

• PyPI trusted publisher: register a pending publisher for aces-sdl on
  PyPI before the first upload — owner Brad-Edwards, repo aces, workflow
  filename release.yml, environment pypi. (A filename mismatch 403s only the
  PyPI step.)
• Version continuity / bootstrap: the package is at 0.3.0 but there is no
  v0.3.0 tag. Seed the baseline so PSR continues sensibly (e.g. create the
  v0.3.0 tag as the baseline, then let PSR compute the next bump), or bootstrap
  the first release via workflow_dispatch force=minor. Decide and document the
  starting version in the release runbook (docs/explain/releasing.md).

Acceptance criteria

• Merging dev→main with at least one feat:/fix: since the last tag
  auto-creates the tag + GitHub Release and publishes the wheel + sdist to
  PyPI with no stored token (OIDC).
• A dev→main promotion containing only docs:/chore:/etc. releases
  nothing (no tag, no PyPI upload).
• The published wheel still bundles the contract corpus (the #537 check is
  retained and gates the release).
• pip install aces-sdl from PyPI yields a working aces CLI whose
  aces conformance backend --profile provisioning-only passes (the
  #537 end goal, now from a real PyPI version).
• A CycloneDX SBOM is attached to each GitHub Release.
• main is never committed to by automation (PSR tag-only); the PR-title
  Conventional-Commit gate is required on dev and main.
• docs/explain/releasing.md updated to the new model, referencing
  aces-scenario-packs ADR 0006 as the source pattern.

References

• Blueprint: aces-scenario-packs ADR 0006 (conventional-commit releases),
  building on ADR 0003 (build/release model), ADR 0004 (SBOM/supply chain),
  ADR 0005 (auto-release on merge, superseded by 0006).
• Foundation in this repo: #537 / #543 (corpus-bundled wheel + release line),
  program #648 (Packaging & Supply Chain).

[Brad-Edwards]

Baked the versioning discipline into the local /implement customization so agents can't miss it: added a Conventional-Commit plan-rule to .gc/plan-rules.md (wired via .ground-control.yaml plan_rules).

The rule (matches building block 4 above):

Plans MUST use a Conventional Commit type in the PR title and squashed commit — feat: (minor), fix: (patch), or feat!:/fix!:/a BREAKING CHANGE: footer (major; pre-1.0 → minor) for consumer-visible changes, and docs:/chore:/test:/ci:/refactor:/build:/style: for repo-internal changes that must NOT release. The release and SemVer bump are DERIVED from these by python-semantic-release; plans MUST NOT hand-edit any version string — the version is the git tag via hatch-vcs (ADR 0006; tracked in #684). Pick the type by the one-line rule: release when a consumer of the package would observe the change; hold when it is repo-internal.

Deliberately not a manual __version__ bump — under the ADR-0006 tag-driven model there is no version string to edit; the Conventional Commit type is the signal PSR reads to decide release + bump. This plan-rule and the required PR-title Conventional-Commit gate (building block 4) are what make the release inescapable from the agent side.

Note: the edit is in the working tree on dev, not yet committed.

[Brad-Edwards]

Release-hardening status (PR #686)

Reviewed four supply-chain items for the PyPI/OIDC release path:

1. SHA-pin publishing-critical actions — done. Every uses: in release.yml is a full commit SHA, including the two that run with id-token: write: python-semantic-release@37a30a7987cfebb6d49240bf1c4e9cd9817d0673, pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b, plus checkout/setup-python/setup-uv. (# v10.6.0 / # release/v1 are comments, not the ref.)
2. Dependabot — added (.github/dependabot.yml): weekly github-actions (grouped) + pip (/implementations/python) updates, so the SHA-pins stay patched.
3. CI dependency vuln scan — already present. ci.yml runs an OSV-scanner sweep over the lockfile (osv_scan session, Add OSV-scanner to CI #34) and uploads the report. It is advisory (non-blocking) by that issue's design; flipping it to gate the build is a separate one-line decision.
4. pypi environment scoped to main — done. Configured with an explicit custom branch policy allowing only main (chosen over the protected-branches flag because main is protected via a ruleset, merge-policy-main, which the flag handles unreliably). Belt-and-suspenders with the workflow's if: github.ref == 'refs/heads/main' job guard.

Net: 1, 2, 4 are in place; 3 pre-existed. Only open call is whether to make the OSV scan blocking.