@@ -8,12 +8,21 @@
 # published until a maintainer publishes a GitHub Release (`release.yml`).
 #
 # The PR targets the branch the workflow was dispatched on, which is `v2/main`
-# in the normal flow.
+# in the normal flow. It is one of a release's preparation PRs, so it follows
+# the same rules as any other PR here: its body opens with `Closes #N` for the
+# milestone's release issue (the `issue` input), its branch is named for that
+# issue, and it is labeled `v2`. The link is only a cross-reference on
+# `v2/main`; the release issue stays open until the Release is published.
 
 name: Prepare Python Release
 
 on:
   workflow_dispatch:
+    inputs:
+      issue:
+        description: "The release issue this PR belongs to (its number, e.g. 4930)"
+        required: true
+        type: string
 
 jobs:
   prepare:
@@ -56,16 +65,24 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           BASE: ${{ github.ref_name }}
+          ISSUE: ${{ inputs.issue }}
         run: |
+          # The input is free text; only a bare issue number may reach the
+          # branch name and the PR body.
+          case "$ISSUE" in
+            '' | *[!0-9]*) echo "issue must be a number, got: '$ISSUE'" >&2; exit 1 ;;
+          esac
           DATE=$(date -u +%Y.%-m.%-d)
-          BRANCH="release/python-$DATE"
+          BRANCH="v2/chore/$ISSUE-python-calver-$DATE"
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git checkout -b "$BRANCH"
           git add -u
           git commit -m "chore: stamp Python CalVer versions for $DATE"
           git push --force origin "$BRANCH"
           {
+            echo "Closes #$ISSUE"
+            echo
             echo "Stamps today's CalVer date onto the Python packages that changed since their last version bump:"
             echo
             sed 's/^/- /' "$RUNNER_TEMP/stamped.txt"
 
@@ -23,6 +23,11 @@
 # registry tokens. Each trusted publisher is bound to this workflow's filename
 # (`release.yml`) and the `release` environment, so the publish jobs must stay
 # in this file and keep that environment.
+#
+# Only a commit that is on `main` is published. A Release can be created for
+# any tag on any commit, and the environment approval shows a reviewer a tag
+# name, not what it points at, so `detect-packages` checks the released commit
+# against `main` and every publish job needs it.
 
 name: Release
 
@@ -40,8 +45,22 @@ jobs:
       pypi_packages: ${{ steps.find-packages.outputs.pypi_packages }}
     steps:
       # On a release event the default ref is the release's tag: the exact
-      # commit the maintainer released.
+      # commit the maintainer released. Full history, for the check below.
       - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      # `main` only receives reviewed milestone merges, so "on main" is what
+      # makes the released code reviewed code. A tag cut from `v2/main`, a
+      # feature branch or a fork's commit fails here, before any publish job
+      # is eligible to run.
+      - name: Refuse a release whose commit is not on main
+        run: |
+          git fetch --no-tags origin main
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" FETCH_HEAD; then
+            echo "::error::The released commit $GITHUB_SHA is not on main. Publish the Release from a tag on main (see RELEASING.md)."
+            exit 1
+          fi
 
       - name: Find all packages
         id: find-packages
 
@@ -9,6 +9,11 @@
 # so it has to exist on the develop branch before the milestone merge carries
 # it to `main`. A bump made downstream of `v2/main` would never flow back.
 #
+# The action rewrites the PR's title and body on every run, so that PR cannot
+# carry a `Closes #N` line the way every other PR here does; `AGENTS.md` names
+# it as an exception and says how it is tied to its release issue instead. The
+# `v2` label does survive an update, and this workflow applies it.
+#
 # This workflow only ever opens a PR. It gives the action no publish script, so
 # it never publishes, tags or creates a Release; that is `release.yml`, on a
 # maintainer-published GitHub Release.
@@ -43,6 +48,7 @@ jobs:
         run: npm ci --ignore-scripts
 
       - name: Create or update the Version Packages PR
+        id: changesets
         uses: changesets/action@v2
         with:
           version-script: npm run version-packages
@@ -53,3 +59,12 @@ jobs:
           # the CHANGELOG entries. The action itself authenticates through its
           # `github-token` input, which defaults to this same token.
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      # Every PR in this repository is labeled `v2`. Adding a label that is
+      # already there is a no-op, so this runs on every update.
+      - name: Label the Version Packages PR
+        if: steps.changesets.outputs.pr-number != ''
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR: ${{ steps.changesets.outputs.pr-number }}
+        run: gh pr edit "$PR" --add-label v2
@@ -241,6 +241,20 @@ holds for a maintainer's own one-line fix as much as for a feature.
   slug**. It still targets `v2/main`, and it is reviewed inside the fork. The
   flow is the `security-advisory` skill.
 
+- **Exception: the two version PRs that automation opens.** Each changes
+  version metadata only, so neither answers the template checklist, and each
+  is tied to its milestone's **release issue** rather than to an issue of its
+  own.
+  - The **Prepare Python Release** PR follows the rest of the rules: the
+    workflow takes the release issue's number, writes `Closes #N` as the
+    body's first line, names the branch `v2/chore/<N>-python-calver-<date>`
+    and labels it `v2`.
+  - The changesets **"Version Packages"** PR cannot carry a `Closes` line: the
+    action rewrites its body on every push to `v2/main`, and its branch is the
+    action's own (`changeset-release/v2/main`). The workflow labels it `v2`.
+    Tie it to the release issue with a **comment** (`Part of #N`), which an
+    update does not overwrite.
+
 No other PR is exempt.
 
 Every PR answers the checklist in
 
@@ -28,7 +28,7 @@ The semver line starts at **`1.0.0`** for all four packages. Their earlier relea
 
 `fetch`, `git` and `time` use **CalVer** (`2026.8.1`). pip and uv have no dist-tags and always install the numerically highest version, so the existing `2026.x` line on PyPI has to keep climbing.
 
-A maintainer dispatches the **Prepare Python Release** workflow ([`prepare-python-release.yml`](.github/workflows/prepare-python-release.yml)) on `v2/main`. It runs [`scripts/prepare-python-release.mjs`](scripts/prepare-python-release.mjs), which stamps today's date onto each Python package with a shipped change since its last version bump, refreshes its `uv.lock`, and opens a normal PR. A package with no such change is left alone.
+A maintainer dispatches the **Prepare Python Release** workflow ([`prepare-python-release.yml`](.github/workflows/prepare-python-release.yml)) on `v2/main`, giving it the number of the milestone's release issue. It runs [`scripts/prepare-python-release.mjs`](scripts/prepare-python-release.mjs), which stamps today's date onto each Python package with a shipped change since its last version bump, refreshes its `uv.lock`, and opens a PR whose body starts with `Closes #<release issue>`. A package with no such change is left alone.
 
 GitHub only lists a `workflow_dispatch` workflow that exists on the default branch (`main`). Until the first milestone merge carries this one there, run the same script locally on a branch cut from `origin/v2/main` and open the PR by hand:
 
@@ -39,11 +39,11 @@ node scripts/prepare-python-release.mjs    # prints one "name: old -> new" line
 ### PRs opened by these workflows
 
 > [!NOTE]
-> Both workflows open their PR with the workflow token, and GitHub does not start CI for a PR opened that way. Close and reopen the PR to run CI before merging. The repository setting **Settings → Actions → General → Allow GitHub Actions to create and approve pull requests** must be on, or the workflows fail at the step that opens the PR.
+> Both workflows open their PR with the workflow token, and GitHub does not start CI for a PR opened that way. Close and reopen the PR to run CI before merging. The Version Packages PR's body is rewritten on every push to `v2/main`, so it is tied to the release issue by a comment (`Part of #N`) instead of a body line. The repository setting **Settings → Actions → General → Allow GitHub Actions to create and approve pull requests** must be on, or the workflows fail at the step that opens the PR.
 
 ## How publishing works
 
-Publishing is triggered by a maintainer **publishing a GitHub Release** whose tag is on `main`. There is no scheduled or merge-triggered release. The release tag is only a label: it carries no version, and nothing compares it with one.
+Publishing is triggered by a maintainer **publishing a GitHub Release** whose tag is on `main`. There is no scheduled or merge-triggered release. The release tag is only a label: it carries no version, and nothing compares it with one. What the workflow does check is where the tag points: a Release whose commit is not on `main` fails before any publish job can start, since `main` only receives reviewed milestone merges.
 
 [`release.yml`](.github/workflows/release.yml) runs on `release: published`, gated by the `release` environment (a required reviewer must approve each deployment). It runs every package as an independent matrix job (`fail-fast: false`, so one package's failure never blocks another), checked out at the release tag. Each job: registry-diff guard → install → **run the package's tests** (plus `pyright` for Python) → build → publish.