x.y.z releases, cut on merge and on demand (#83)

* feat(ci): resolve the release version from the tags the repo carries

The tags are the record of what has been released, so nothing in the tree
holds the version and no commit has to land on master to advance one.

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* feat(ci): cut a release on every green master run, and on demand

A merge advances the patch. Actions -> release -> Run workflow takes a
major/minor/patch dropdown, or a version named outright.

The publish authenticates to npm over OIDC against a trusted publisher, so
the job holds no token. npm matches that publisher against the filename of
the workflow that starts the run, which is why the merge path arrives here
as a workflow_run rather than as a job at the end of ci.

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* refactor(ci): move the release out of ci.yml

release.yml is the only thing that publishes now, and it is what creates the
tags, so ci no longer triggers on them.

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* docs(ci): describe how a release is cut

Also corrects the opening: folio and replay-ui became jobs inside ci.yml and
are no longer dispatch-only workflows of their own.

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* feat(ci): report the release a version follows

The manual pipeline promotes the commit that release was cut from, so it
needs the tag as well as the next version.

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* fix(ci): resolve reusable workflow refs in the ref check

A reusable workflow is named by its file, not by a directory holding an
action.yml, so every `uses: ./.github/workflows/*.yml` was reported missing.

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* feat(ci): share the publish between both release pipelines

Tagging, the npm publish and GoReleaser live here. Two copies of a publish
drift, and the drift only shows up on a release.

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* feat(ci): patch release on merge, manual promotion to a milestone

Release goes back in the ci graph, behind Checks, Folio and Replay UI.
release.yml is independent of it and runs no checks: it republishes the
commit the last release was cut from under a minor or major version.

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* docs(ci): describe the two release pipelines

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* feat(ci): reach a milestone's release notes back over its patches

A promotion tags a commit that is already tagged, so GoReleaser's own
previous tag makes the notes on a release consolidating six patches
describe one merge. Emits the last release at the level being cut instead.

Also drops the named-version path: the manual pipeline no longer offers one.

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* feat(ci): pass the notes boundary to GoReleaser, and make promotion strict

minor or major, nothing else. A manual patch would republish an identical
commit under the next patch number, and a version typed by hand is the one
way to get a release that does not follow from the tag before it.

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* docs(ci): describe how far back a milestone's notes reach

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* docs(ci): say that the notes boundary is exclusive

Measured against goreleaser 2.15.3: a first milestone's notes start after the
first release rather than at it.

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* refactor(ci): one workflow publishes, because npm allows one trusted publisher

npm revoked every classic token in December 2025 and caps a granular one at
90 days, so a token in CI would expire quarterly. OIDC is the only option
left, and it matches a package's single trusted publisher against the
filename of the workflow that starts the run. So the release lives in ci.yml
and nowhere else: release.yml and release-publish.yml are gone, along with
the released_tag the promotion used to re-cut an older commit.

Actions -> ci -> Run workflow, promote=minor|major cuts a milestone, and it
runs the whole suite first like a merge does.

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

* docs(ci): explain why the release is not its own workflow

Claude-Session: https://claude.ai/code/session_01ShuAy8q8ZfPi8KHxwc8JpQ

.github/scripts/next-version-test.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# Drives next-version.sh against repositories whose tags are planted by hand.
+# Run under the flags GitHub Actions uses for a `run:` block, because that is
+# where a swallowed failure hides.
+set -euo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+script="$here/next-version.sh"
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+
+failed=0
+outputs=""
+status=0
+stderr=""
+
+resolve() { # <case> <bump> <tag>...
+  local name="$1" bump="$2"
+  shift 2
+  local repo="$work/$name"
+  rm -rf "$repo"
+  mkdir -p "$repo"
+  git -C "$repo" init -q
+  git -C "$repo" -c user.email=t@t -c user.name=t commit -q --allow-empty -m base
+  local tag
+  for tag in "$@"; do git -C "$repo" tag "$tag"; done
+  outputs="$work/$name.out"
+  stderr="$work/$name.err"
+  : > "$outputs"
+  status=0
+  (cd "$repo" && BUMP="$bump" GITHUB_OUTPUT="$outputs" \
+    bash -eo pipefail "$script") >/dev/null 2>"$stderr" || status=$?
+}
+
+fail() {
+  echo "FAIL: $*" >&2
+  failed=1
+}
+
+expect_version() { # <want> <case>
+  local want="version=$1"
+  grep -qxF -- "$want" "$outputs" || fail "$2: resolved $(tr '\n' ' ' <"$outputs"), want $want"
+  grep -qxF -- "tag=v$1" "$outputs" || fail "$2: tag does not match the version it resolved"
+  [ "$status" = 0 ] || fail "$2: exit $status, want 0"
+}
+
+
+# How far back GoReleaser reaches for the notes. Empty leaves it on its own
+# default, which is the release immediately before this one.
+expect_previous_tag() { # <want, empty for none> <case>
+  grep -qxF -- "previous_tag=$1" "$outputs" \
+    || fail "$2: $(grep '^previous_tag=' "$outputs" || echo 'no previous_tag'), want previous_tag=$1"
+}
+
+expect_refused() { # <case> <message fragment>
+  [ "$status" != 0 ] || fail "$1: exit 0, want a refusal"
+  grep -q -- "$2" "$stderr" || fail "$1: refused with '$(cat "$stderr")', want it to mention '$2'"
+  [ ! -s "$outputs" ] || fail "$1: refused but still wrote an output"
+}
+
+# A repository with nothing released yet starts the line at 0.0.1 rather than
+# reissuing 0.0.0, and has no earlier release to write notes against.
+resolve first patch
+expect_version 0.0.1 first
+expect_previous_tag "" first
+
+# The rc tags this repository carries are candidates for 0.0.1, so the first
+# stable release is 0.0.1 and not 0.0.2.
+resolve rcs patch v0.0.1-rc1 v0.0.1-rc4
+expect_version 0.0.1 rcs
+
+resolve patch patch v1.2.3
+expect_version 1.2.4 patch
+# A patch already follows the release before it, so GoReleaser is left alone.
+expect_previous_tag "" patch
+
+resolve minor minor v1.2.3
+expect_version 1.3.0 minor
+
+resolve major major v1.2.3
+expect_version 2.0.0 major
+
+# Lexically 0.9.0 sorts above 0.10.0, so a version-blind sort would count the
+# next patch off the wrong release and hand back 0.9.1.
+resolve ordering patch v0.9.0 v0.10.0
+expect_version 0.10.1 ordering
+
+# A tag that is not a release is not a base to count from.
+resolve noise patch v1.2.3 nightly v2.0.0-rc1 vfoo
+expect_version 1.2.4 noise
+
+# A bump counts off the highest release, so releasing twice in a row advances
+# twice rather than landing on the tag the first one just cut.
+resolve consecutive patch v1.2.3 v1.2.4
+expect_version 1.2.5 consecutive
+
+resolve bad-bump sideways v1.2.3
+expect_refused bad-bump "is not a bump"
+
+# --- how far back a milestone's notes reach ----------------------------------
+# The whole point of consolidating: 0.2.0's notes have to cover every patch
+# since 0.1.0, not just the merge that happened to be last before it.
+resolve minor-notes minor v0.1.0 v0.1.1 v0.1.2
+expect_version 0.2.0 minor-notes
+expect_previous_tag v0.1.0 minor-notes
+
+# The last release at this level, not the first one ever seen at it.
+resolve minor-notes-latest minor v0.1.0 v0.2.0 v0.2.1
+expect_version 0.3.0 minor-notes-latest
+expect_previous_tag v0.2.0 minor-notes-latest
+
+# A major counts as a milestone for a minor's notes: 1.0.0 is where the patches
+# being consolidated started.
+resolve minor-notes-major minor v0.9.0 v1.0.0 v1.0.1
+expect_version 1.1.0 minor-notes-major
+expect_previous_tag v1.0.0 minor-notes-major
+
+# The same version-aware ordering the base needs.
+resolve minor-notes-ordering minor v0.9.0 v0.10.0 v0.10.1
+expect_version 0.11.0 minor-notes-ordering
+expect_previous_tag v0.10.0 minor-notes-ordering
+
+# A major reaches back to the last major, not to the last minor.
+resolve major-notes major v1.0.0 v1.1.0 v1.1.3
+expect_version 2.0.0 major-notes
+expect_previous_tag v1.0.0 major-notes
+
+# The first milestone of its kind has nothing at its own level to reach back to,
+# so it reaches back to the first release there has ever been.
+resolve minor-notes-firstever minor v0.0.1 v0.0.2 v0.0.3
+expect_version 0.1.0 minor-notes-firstever
+expect_previous_tag v0.0.1 minor-notes-firstever
+
+resolve major-notes-firstever major v0.1.0 v0.2.0 v0.2.1
+expect_version 1.0.0 major-notes-firstever
+expect_previous_tag v0.1.0 major-notes-firstever
+
+if [ "$failed" = 0 ]; then
+  echo "next-version-test: ok"
+else
+  echo "next-version-test: failures above" >&2
+  exit 1
+fi