ci: dogfood with conventional-commits and document release conventions

.github/workflows/semvertag.yml

@@ -1,7 +1,7 @@
 name: semvertag
 
 # Dogfood the local composite action against this repo in DRY-RUN: on every
-# push to main it computes the planned bump (exercising action.yml + the
+# push to main it computes the head commit's bump (exercising action.yml + the
 # published semvertag) but never pushes a tag. This keeps action.yml honest —
 # a breaking change fails the run before it can affect external users.
 #
@@ -10,9 +10,6 @@ name: semvertag
 # Release + v0). Dry-run is load-bearing: it guarantees the only tags in the
 # repo are deliberate release tags — do not give this job a push token or
 # remove `dry-run: true`.
-#
-# This repo's branch convention uses `feat/...`, so SEMVERTAG_BRANCH_PREFIX__MINOR
-# overrides the default `feature/` mapping.
 
 on:
   push:
@@ -32,6 +29,5 @@ jobs:
       - uses: actions/checkout@v6
       - uses: ./
         with:
+          strategy: conventional-commits
           dry-run: true
-        env:
-          SEMVERTAG_BRANCH_PREFIX__MINOR: '["feat/"]'

AGENTS.md

@@ -23,12 +23,20 @@ A human at a shell, the GitHub Action, and the GitLab CI component all invoke th
 
 ## Cutting a release (maintainers)
 
-Push a bare semver tag off green `main` — `git tag 0.9.0 && git push origin 0.9.0`;
+Push a signed, annotated bare semver tag off green `main` —
+`git tag -s 0.9.0 -m "semvertag 0.9.0" origin/main && git push origin 0.9.0`;
 [`release.yml`](.github/workflows/release.yml) does the rest and its comments say in what order and
-why. Two things that file cannot tell you: the tag is the commitment point, cut by convention only
-off a green `main` with no in-workflow CI gate; and if `just publish` succeeds but a later step
-fails, do **not** re-push the tag — PyPI rejects re-uploading an existing version, so create the
-Release and move `v0` by hand, or cut a new patch tag.
+why. What that file cannot tell you:
+
+- The tag is the commitment point, cut by convention only off a green `main` with no in-workflow CI
+  gate.
+- Version: bump the minor (`0.9.0`) when the release carries a `feat:` or any behaviour change, the
+  patch otherwise.
+- The Release body is generated from the squashed PR titles. When a change alters behaviour on
+  upgrade, prepend a `## Upgrading` section with `gh release edit`.
+- If `just publish` succeeds but a later step fails, do **not** re-push the tag — PyPI rejects
+  re-uploading an existing version, so create the Release and move `v0` by hand, or cut a new patch
+  tag.
 
 ## Workflow