Dev

.gc/plan-rules.md

@@ -34,6 +34,16 @@ These encode the hard rules previously in `AGENTS.md` prose.
   aligned with changed code and tests.
 - Plans with a user-visible change MUST add a fragment under
   `changelog.d/<issue>.<type>.md` (or `changelog.d/+<slug>.<type>.md`
-  for issue-free entries), where `<type>` is one of `security`, `added`,
-  `changed`, `deprecated`, `removed`, `fixed`; do not edit `CHANGELOG.md`
-  directly outside release-collation commits.
+  for issue-free entries), where `<type>` is one of `breaking`, `security`,
+  `added`, `changed`, `deprecated`, `removed`, `fixed`. The fragment `<type>`
+  drives the release version bump (`tools/release.py`): `removed` → major (once
+  ≥ 1.0; pre-1.0 it is a minor), `added`/`changed`/`deprecated` → minor,
+  `security`/`fixed` → patch; `breaking` is recorded in the changelog but does
+  NOT auto-bump (force a major with `release.py --version 1.0.0`). Do not edit
+  `CHANGELOG.md` directly outside release-collation commits.
+- Plans MUST NOT hand-edit the version. It is a single committed literal,
+  `__version__` in `implementations/python/src/aces/__init__.py`, bumped only by
+  `tools/release.py` from the pending changelog fragments at release time (#684).
+  The PR title must still pass the `title-guard` conventional-shape / no-branding
+  gate (`tools/check_pr_title.py`), but the PR title does NOT drive the version —
+  only the changelog fragment types do.

.github/dependabot.yml

@@ -0,0 +1,26 @@
+# Dependabot keeps the SHA-pinned GitHub Actions (and Python deps) patched, so
+# the pins in .github/workflows/*.yml do not silently rot (#684 release hardening).
+version: 2
+updates:
+  # GitHub Actions used across all workflows (release.yml pins are publishing-
+  # critical: they run in a job with id-token: write). Grouped so a batch of pin
+  # bumps arrives as one reviewable PR.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    groups:
+      github-actions:
+        patterns: ["*"]
+
+  # Python package dependencies for the aces-sdl distribution.
+  - package-ecosystem: "pip"
+    directory: "/implementations/python"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    groups:
+      python-minor-patch:
+        patterns: ["*"]
+        update-types: ["minor", "patch"]

.github/workflows/ci.yml

@@ -101,6 +101,31 @@ jobs:
         if: steps.runtime.outputs.available == 'true'
         run: uv tool run --from 'nox[uv]==2026.4.10' nox -f noxfile.py -s integration_docker
 
+  # Advisory OSV-scanner sweep over the Python dependency lockfile (issue #34).
+  # Non-gating: CVE findings surface as an uploaded JSON artifact and never fail
+  # the build. The `osv_scan` nox session is kept out of the hermetic `verify`
+  # graph; genuine scanner/setup failures still fail this job's step (visible as
+  # a soft failure) so the advisory posture never hides a broken scan.
+  supply-chain:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.12"
+      - name: Install uv
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8
+      - name: Run OSV-scanner (advisory)
+        run: uv tool run --from 'nox[uv]==2026.4.10' nox -f noxfile.py -s osv_scan
+      - name: Upload OSV-scanner report
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: osv-scanner-report
+          path: implementations/python/osv-scanner-report.json
+          if-no-files-found: warn
+
   sonar:
     runs-on: ubuntu-latest
     needs: [verify]

.github/workflows/pr-title-lint.yml

@@ -0,0 +1,46 @@
+name: PR Title Lint
+
+# Repository-side guard against agent-branded PR titles (e.g. `[codex] ...`)
+# and a check that titles follow the conventional shape Ground Control
+# documents for /implement Step 9. Enforced by repo automation, not only by
+# agent workflow instructions (issue #567).
+#
+# The PR title is untrusted event data, so it is read from $GITHUB_EVENT_PATH
+# by the checker (never shell-interpolated), the token is read-only, and this
+# uses `pull_request` (never `pull_request_target`). There is no exemption for
+# PRs targeting `dev`.
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pr-title-lint-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  title-guard:
+    runs-on: ubuntu-latest
+    steps:
+      # Check out the BASE ref, not the PR head, so the policy executable is
+      # the trusted already-merged copy. A PR that edits or removes
+      # tools/check_pr_title.py must not be able to weaken its own required
+      # check (codex review finding, issue #567). The shared validator is still
+      # exercised against the PR's own code by the test suite in ci.yml.
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ github.event.pull_request.base.sha }}
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.12"
+      - name: Validate PR title
+        # The checker reads the title from $GITHUB_EVENT_PATH (set automatically
+        # by the runner). It is stdlib-only, so no dependency install is needed.
+        run: |
+          if [ ! -f tools/check_pr_title.py ]; then
+            echo "::notice::tools/check_pr_title.py is not on the base ref yet; skipping (bootstrap for the PR that introduces the guard). Enforcement is active for every subsequent PR."
+            exit 0
+          fi
+          python tools/check_pr_title.py

.github/workflows/release.yml

@@ -1,65 +1,114 @@
 name: Release
 
-# Cut a release by pushing a version tag, e.g. `git tag v0.3.0 && git push origin v0.3.0`.
-# Builds the corpus-bundled wheel + sdist and publishes a GitHub Release with the
-# artifacts attached, so downstream backends can pin a real version instead of a
-# `dev` commit SHA. See docs/explain/releasing.md for the full runbook.
+# Committed-literal release (#684), built on the corpus-bundled wheel (#537).
 #
-# Release integrity (issue #537 codex review):
-#   * The only trigger is a `v*` tag push — there is no `workflow_dispatch`, so a
-#     manual run can never publish a Release named after a branch from untagged
-#     code.
-#   * The build job checks the tag commit is reachable from the protected default
-#     branch (`main`) BEFORE it runs any repository-controlled build code
-#     (`uv build` runs the hatch build hook), and checks out with
-#     `persist-credentials: false` so no write-scoped token sits in the git config
-#     while that build code executes.
-#   * Publishing happens in a separate job that only consumes the already-built
-#     artifacts. The `contents: write` token is scoped to that job alone and is
-#     used only by `gh release create`, so tag-controlled build hooks never run in
-#     a context that holds the write token.
+# The version is the single committed literal `__version__` in
+# src/aces/__init__.py. `tools/release.py` bumps it from the pending towncrier
+# changelog fragments and collates CHANGELOG.md on a `release/vX.Y.Z` branch; that
+# opens a PR to `main`. Merging it (a normal human-reviewed PR merge) is the only
+# thing that puts a new version on `main` — this workflow never commits to `main`,
+# it only reads the literal and creates a tag, so no bot/PAT/deploy-key/bypass is
+# needed.
+#
+# On push to `main` the `decide` job publishes iff:
+#   * the changelog fragments have been collated (none pending) — a real release
+#     always collates first, so a plain `dev`->`main` promotion with pending
+#     fragments never publishes a half-baked version; and
+#   * no tag exists yet for the current `__version__`.
+# The `release` job then builds the corpus-bundled wheel/sdist, verifies the
+# corpus payload and that the built version matches, attaches a CycloneDX SBOM,
+# publishes to PyPI via OIDC trusted publishing, and cuts a GitHub Release whose
+# notes are the CHANGELOG.md section. First release + PyPI setup:
+# docs/explain/releasing.md.
 on:
   push:
-    tags: ["v*"]
+    branches: [main]
+  workflow_dispatch:
 
 permissions:
   contents: read
 
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+env:
+  VERSION_FILE: implementations/python/src/aces/__init__.py
+
 jobs:
-  build:
+  decide:
+    if: github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
+    outputs:
+      release: ${{ steps.decide.outputs.release }}
+      version: ${{ steps.decide.outputs.version }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           fetch-depth: 0
-          persist-credentials: false
-      - name: Verify the tag is reachable from the protected default branch
+      - name: Decide whether to release
+        id: decide
         run: |
           set -euo pipefail
-          git fetch --no-tags origin main:refs/remotes/origin/main
-          tag_sha="$(git rev-parse HEAD)"
-          if ! git merge-base --is-ancestor "${tag_sha}" origin/main; then
-            echo "::error::tag ${GITHUB_REF_NAME} (${tag_sha}) is not reachable from origin/main; refusing to build or publish a release from unreviewed code"
-            exit 1
+          version="$(grep -oP '^__version__\s*=\s*"\K[^"]+' "${VERSION_FILE}")"
+          if [ -z "${version}" ]; then
+            echo "::error::no __version__ literal in ${VERSION_FILE}"; exit 1
+          fi
+          # Guard: uncollated fragments mean this is not a prepared release
+          # (release.py collates before opening the release PR). Never publish a
+          # version whose changelog has not been collated.
+          if find changelog.d -type f -name '*.md' ! -name '_*' ! -name 'README.md' | grep -q .; then
+            echo "::notice::changelog fragments are still pending; run tools/release.py to prepare a release. Skipping."
+            echo "release=false" >> "$GITHUB_OUTPUT"; exit 0
           fi
-          echo "tag ${GITHUB_REF_NAME} (${tag_sha}) is an ancestor of origin/main"
+          if git rev-parse -q --verify "refs/tags/v${version}" >/dev/null; then
+            echo "::notice::v${version} already tagged; nothing to release"
+            echo "release=false" >> "$GITHUB_OUTPUT"; exit 0
+          fi
+          echo "::notice::releasing v${version}"
+          echo "release=true" >> "$GITHUB_OUTPUT"
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
+
+  release:
+    needs: decide
+    if: needs.decide.outputs.release == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: write   # create the release tag + the GitHub Release
+      id-token: write   # OIDC trusted publishing to PyPI (no stored token)
+    env:
+      VERSION: ${{ needs.decide.outputs.version }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          fetch-depth: 0
+
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
           python-version: "3.12"
+
       - name: Install uv
         uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8
-      - name: Build wheel + sdist
+
+      - name: Build the corpus-bundled wheel + sdist
         run: uv build --out-dir dist implementations/python
-      - name: Verify the contract corpus is bundled in the wheel
+
+      - name: Verify built version matches and the corpus is bundled
         run: |
           python - <<'PY'
           import glob
+          import os
           import sys
           import zipfile
 
+          expected = os.environ["VERSION"]
           wheels = glob.glob("dist/aces_sdl-*.whl")
           if len(wheels) != 1:
               sys.exit(f"expected exactly one wheel, found {wheels}")
+          built = wheels[0].split("/")[-1].split("-")[1]
+          if built != expected:
+              sys.exit(f"built version {built!r} != __version__ {expected!r}")
           names = zipfile.ZipFile(wheels[0]).namelist()
           required = [
               "aces_contracts/_corpus/profiles/backend/provisioning-only.json",
@@ -70,31 +119,59 @@ jobs:
           missing = [r for r in required if not any(n == r or n.startswith(r) for n in names)]
           if missing:
               sys.exit(f"wheel is missing corpus payload: {missing}")
-          print(f"corpus payload present: {sum(n.startswith('aces_contracts/_corpus/') for n in names)} files")
+          print(f"v{expected}: corpus payload present ({sum(n.startswith('aces_contracts/_corpus/') for n in names)} files)")
           PY
-      - name: Upload built artifacts
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
-        with:
-          name: release-dist
-          path: dist/*
-          if-no-files-found: error
 
-  publish:
-    needs: build
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - name: Download built artifacts
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+      - name: Generate CycloneDX SBOM
+        run: |
+          set -euo pipefail
+          python -m pip install --upgrade pip
+          python -m pip install dist/*.whl cyclonedx-bom
+          mkdir -p sbom
+          cyclonedx-py environment --output-format JSON --output-file sbom/aces-sdl.cdx.json
+
+      - name: Extract the changelog section for the release notes
+        run: |
+          python - <<'PY' > notes.md
+          import os
+          import pathlib
+          import re
+
+          ver = os.environ["VERSION"]
+          lines = pathlib.Path("CHANGELOG.md").read_text(encoding="utf-8").splitlines()
+          out, capturing = [], False
+          header = re.compile(r"^##\s*\[" + re.escape(ver) + r"\]")
+          any_header = re.compile(r"^##\s*\[")
+          for line in lines:
+              if header.match(line):
+                  capturing = True
+                  continue
+              if capturing and any_header.match(line):
+                  break
+              if capturing:
+                  out.append(line)
+          body = "\n".join(out).strip()
+          print(body if body else f"Release v{ver}")
+          PY
+
+      - name: Create + push the release tag (tag-only; main is never committed to)
+        run: |
+          set -euo pipefail
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git -c tag.gpgSign=false tag -a "v${VERSION}" -m "v${VERSION}"
+          git push origin "v${VERSION}"
+
+      - name: Publish to PyPI (OIDC trusted publishing)
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
         with:
-          name: release-dist
-          path: dist
-      - name: Publish GitHub Release
+          packages-dir: dist
+
+      - name: Create the GitHub Release (notes from the changelog)
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          gh release create "${GITHUB_REF_NAME}" dist/* \
+          gh release create "v${VERSION}" dist/* sbom/aces-sdl.cdx.json \
             --repo "${GITHUB_REPOSITORY}" \
-            --title "${GITHUB_REF_NAME}" \
-            --generate-notes
+            --title "v${VERSION}" \
+            --notes-file notes.md

.gitignore

@@ -218,3 +218,6 @@ __marimo__/
 # .gc/plan-rules.md and other authored .gc files stay tracked.
 .gc/sonar/
 .gc/telemetry/
+
+# OSV-scanner advisory report (generated by the `osv_scan` nox session; issue #34).
+implementations/python/osv-scanner-report.json

.ground-control.yaml

@@ -6,6 +6,12 @@ workflow:
   completion_command: uv tool run --from 'nox[uv]==2026.4.10' nox -f noxfile.py -s verify
   lint_command: uv tool run --from 'nox[uv]==2026.4.10' nox -f noxfile.py -s lint
   format_command: uv tool run --from 'nox[uv]==2026.4.10' nox -f noxfile.py -s hygiene
+  review_disposition:
+    enabled: true
+    mode: authoritative
+    max_auto_overrides: 1
+    judge:
+      enabled: true
 docs:
   adr_dir: docs/decisions/adrs/
 example_paths:

.pre-commit-config.yaml

@@ -6,14 +6,14 @@ repos:
     hooks:
       - id: nox-pre-commit
         name: nox pre-commit gate
-        entry: bash -c 'uv tool run --from "nox[uv]==2026.4.10" nox -f noxfile.py -s hook-pre-commit -- "$@"' --
+        entry: bash -c 'unset $(git rev-parse --local-env-vars); uv tool run --from "nox[uv]==2026.4.10" nox -f noxfile.py -s hook-pre-commit -- "$@"' --
         language: system
         pass_filenames: true
         require_serial: true
         stages: [pre-commit]
       - id: nox-pre-push
         name: nox pre-push verify
-        entry: bash -c 'uv tool run --from "nox[uv]==2026.4.10" nox -f noxfile.py -s hook-pre-push'
+        entry: bash -c 'unset $(git rev-parse --local-env-vars); uv tool run --from "nox[uv]==2026.4.10" nox -f noxfile.py -s hook-pre-push'
         language: system
         pass_filenames: false
         require_serial: true