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

docs/development/ci.md

@@ -4,22 +4,18 @@ title: CI
 
 # CI
 
-`ci.yml` runs on every pull request: it builds, unit-tests, and drives three
-small web fixtures through headless Chrome (`test/browser/testdata`). It never
-runs sanderling against a real app.
+`ci.yml` runs on every pull request and every push to master. The `Check`
+jobs build, unit-test, and drive three small web fixtures through headless
+Chrome (`test/browser/testdata`). The `Folio` and `Replay UI` jobs in the same
+workflow do run sanderling against real apps, on emulators and simulators, and
+they are what make a run take the better part of an hour.
 
-Two other workflows do, and both are `workflow_dispatch` only. They boot devices,
-build apps and take minutes, which is not what you want on every push, and
-neither is a merge gate.
+`All checks passed` is the one status check to point branch protection at, and
+it is what gates a release: `release.yml` cuts one only after a whole ci run
+went green. See [Releases](#releases) at the bottom.
 
 ## folio
 
-Actions -> folio -> Run workflow. Inputs pick the legs (`all`, `android`, `ios`,
-`web`), and override the seed, the step budget and the wall-clock budget. Seed
-and step budget take `0` to mean "use the calibrated value in the workflow"; the
-wall-clock budget has no such sentinel and is passed through as written, so
-every leg gets whatever you type there.
-
 Each leg builds `examples/folio` for its platform, builds the CLI with only the
 tags that platform needs (`make sanderling-android` and friends), and runs
 `examples/folio/sanderling/spec.ts` through `.github/scripts/folio-run.sh`. That
@@ -181,7 +177,7 @@ run's automation session bound to a bundle the simulator no longer knows.
 
 ## replay-ui
 
-Actions -> replay-ui -> Run workflow. This one is dogfooding: it records a trace
+This one is dogfooding: it records a trace
 from `test/browser/testdata/throwing` (violations and uncaught exceptions, so
 every panel has something to render), serves it with `sanderling replay`, and
 fuzzes that UI with `replay-ui/sanderling/spec.ts`.
@@ -253,3 +249,91 @@ because the window the counting invariant had to judge it in was 117 steps wide.
 Sweeping selects for a seed that reaches the bug. It cannot select for one whose
 walk also closes the window, so when a property needs a window, check what the
 window looked like and not only that the conviction happened.
+
+
+## Releases
+
+**Every merge to master cuts a patch.** The `Tag`, `Release (npm)` and
+`Release (cli)` jobs sit in `ci.yml` alongside everything else, waiting on
+`Checks`, `Folio` and `Replay UI`, so nothing reaches a registry that the
+emulators and the simulator have not agreed on. `0.1.4` becomes `0.1.5`:
+published to npm, and to GitHub Releases with the CLI binaries.
+
+**A milestone consolidates them.** Actions -> ci -> Run workflow, set `promote`
+to `minor` or `major`, and the patches you have been shipping become `0.2.0`.
+Leaving `promote` on `none` is an ordinary ci run that publishes nothing, which
+is what stops a dispatch meant to re-run the tests from cutting a release.
+
+A promotion runs the whole suite, device legs included. It is the same pipeline
+either way, and a release that skipped the checks would be the only release
+nobody checked. Both paths release the commit the run tested rather than
+whatever master drifted to while it ran. Afterwards the patch line continues
+from the milestone: the next merge counts off `0.2.0` and cuts `0.2.1`.
+
+**The tags are the version.** Nothing in the tree holds it:
+`pkg/spec/package.json` stays at `0.0.0-dev` and CI stamps the real version in
+before it publishes. So there is no version-bump commit to land on master,
+nothing to conflict on, and no second record to hold in step with the tags.
+`.github/scripts/next-version.sh` is the whole rule, and it counts off stable
+tags only, because `v0.0.1-rc4` is a candidate for `0.0.1` and a patch counted
+off it would skip the version it was a candidate for. Run it anywhere to see
+what the next release would be:
+
+```
+BUMP=minor .github/scripts/next-version.sh
+```
+
+The tag is pushed before anything is published, because npm is the half of a
+release that cannot be taken back and a tag is the half that can.
+
+### How far back the notes reach
+
+GoReleaser builds its changelog from the commits between the previous tag and
+this one, and works that previous tag out on its own. For a patch that is
+exactly right. For a milestone it is not: the notes on a `0.2.0` consolidating
+six patches would describe the one merge that happened to be last.
+
+So the resolver also emits `previous_tag`, which the release passes as
+`GORELEASER_PREVIOUS_TAG`: the last release at the level being cut. A minor
+reaches back to the last `vX.Y.0`, counting a major as one, and a major reaches
+back to the last `vX.0.0`. The first milestone of its kind has nothing at its own
+level, so it reaches back to the first release there has ever been. A patch emits
+nothing, and an empty value leaves GoReleaser on the default that was already
+right for it.
+
+The boundary is exclusive, the way a changelog always is: the notes cover what
+landed *after* that tag. So the one release this shortchanges is the first
+milestone of its kind, whose notes start after the first release rather than at
+it. That is one merge, once, and it is not worth a special case.
+
+### Why the release is not its own workflow
+
+It reads like it should be. The reason it is not is npm.
+
+npm publishes over OIDC here, against a trusted publisher configured for
+`@sanderling/spec`, so CI holds no npm credential at all. That is not a
+preference: npm disabled classic token creation in November 2025, revoked every
+classic token on 9 December 2025, and caps a granular token at 90 days. A token
+in CI would now expire quarterly, which is exactly the failure this replaced.
+The August 2026 outage was an expired granular token, and npm answers a publish
+it will not authorise with `404`, so it read as "package does not exist" while
+`@sanderling/spec` sat in the registry the whole time.
+
+A package carries exactly one trusted publisher, and npm matches it against the
+filename of the workflow that *starts* the run. A reusable workflow does not
+help, because npm sees the caller's name, not the callee's. So every publish has
+to enter through one file, and since a merge's release has to run inside ci, that
+file is `ci.yml`.
+
+Setting it up again, or moving the package, means npmjs.com -> the package ->
+trusted publisher: repository `priyanshujain/sanderling`, workflow `ci.yml`. Or
+from a shell, which needs an interactive 2FA challenge:
+
+```
+npm trust github @sanderling/spec --file ci.yml --repo priyanshujain/sanderling --allow-publish
+npm trust list @sanderling/spec
+```
+
+The job installs npm 11.5.1 or newer before publishing, because
+`actions/setup-node` writes an empty `_authToken` line into `.npmrc` and an older
+npm reads that as "auth is configured" and never asks for an OIDC token.