chore(release): migrate the release toolchain to @changesets/cli v3 (#9560)

* chore(release): bump @changesets/cli to v3 and migrate .changeset/config.json

- privatePackages: {version:true, tag:false} (U4)
- drop ___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH (U2)
- $schema -> @changesets/config@4.0.0 (the version v3 resolves)

* chore(release): model v3's pre-mode semantics in the gates, workflows and docs

- check-adr-0087-registration.mjs: exclude .changeset/pre/ from the audit
  surfaces (--list / --audit-stock) while the enforcing diff scan keeps
  judging it; PRE1-PRE3 fixtures
- check-changeset-no-major.mjs: header only — v3 numbers, and the stale
  claim that both siblings pass --diff-filter=AM (they pass AMR since #7045)
- cut-rc.yml / pr-automation.yml / docs/releases-maintenance.md: the prose
  asserting consumed changesets are recorded in .changeset/pre.json

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-project-manager

.changeset/config.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
+  "$schema": "https://unpkg.com/@changesets/config@4.0.0/schema.json",
   "changelog": [
     "@changesets/cli/changelog",
     {
@@ -84,7 +84,5 @@
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
   "ignore": [],
-  "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
-    "onlyUpdatePeerDependentsWhenOutOfRange": true
-  }
+  "privatePackages": { "version": true, "tag": false }
 }

.github/workflows/cut-rc.yml

@@ -486,17 +486,39 @@ jobs:
       # cut: the pin bump and the version output are one atomic unit, and there is
       # never a main commit carrying a bumped pin but an unversioned tree.
       #
-      # WHAT MAY BE IN IT — re-measured on the 17.0.0 -> 18.0.0-rc.0 train (a full
-      # local `pnpm run version` in a throwaway clone over 199 pending changesets),
-      # not assumed. 160 paths:
-      #   77 modified package.json, 76 modified CHANGELOG.md,
-      #   .changeset/pre.json, the 3 major-boundary paths below, and the 3 doc
-      #   surfaces below. Zero deletions. `.changeset/pre.json` is UNTRACKED on the
-      #   first cut of a train (`changeset pre enter` just created it) and modified
-      #   on later ones; `git add -A` covers both. In PRE mode `changeset version`
-      #   does NOT delete the consumed changesets — it records them in pre.json and
-      #   they are removed at `changeset pre exit` — so a cut never races a lane PR
-      #   over a `.changeset/*.md` file it wants to keep.
+      # WHAT MAY BE IN IT — re-measured under @changesets/cli v3 on the
+      # 17.0.0 -> 17.1.0-rc.0 train (a full local `pnpm run version` in a throwaway
+      # clone over 209 pending changesets), not assumed. 365 staged paths:
+      #   76 modified package.json, 76 modified CHANGELOG.md, 209 changesets MOVED
+      #   into `.changeset/pre/`, `.changeset/pre.json`, and the 3 doc surfaces
+      #   below. `.changeset/pre.json` is UNTRACKED on the first cut of a train
+      #   (`changeset pre enter` just created it) and modified on later ones;
+      #   `git add -A` covers both.
+      #   The 3 major-boundary paths below did NOT appear on this train and are
+      #   allowed for the train that does move the major — as is the blank
+      #   template's own package.json, which is why the v2 measurement this block
+      #   used to carry counted 77 package.json against this one's 76: that train
+      #   was 17.0.0 -> 18.0.0-rc.0, so `sync-template-versions.mjs` had to rewrite
+      #   the template's `^17.0.0` pins. On a minor train it logs "already pins" and
+      #   writes nothing. The counts move with the SHAPE of the train; the
+      #   allowlist below is what does not have to.
+      #
+      #   THE CONSUMED CHANGESETS MOVE — new in v3 (changesets#2190), and the one
+      #   thing about a cut that this file's prose used to get wrong. v2 left every
+      #   consumed `.changeset/*.md` on disk and recorded it in `pre.json`; v3 moves
+      #   it to `.changeset/pre/NAME.md` VERBATIM (measured: a moved file diffs
+      #   identical to its original, and git reports all 209 as `R100` renames), and
+      #   `pre.json` is `{"mode","tag"}` only — `changeset version` never rewrites
+      #   it. So in the worktree a cut is 209 deletions plus a new untracked
+      #   `.changeset/pre/` directory, and the claim this block used to make — "a
+      #   cut never races a lane PR over a `.changeset/*.md` file it wants to keep"
+      #   — is FALSE under v3. The cut moves tracked changeset paths, so a lane PR
+      #   that edits or deletes one of them conflicts; the rebase guard further down
+      #   is what catches it, and it already names `.changeset` in its conflict
+      #   surface. What does NOT change is this allowlist: `^\.changeset/` covers
+      #   `.changeset/pre/…` and `git add -A -- … .changeset …` stages the deletions
+      #   and the new directory together (measured: all 365 staged paths accepted,
+      #   nothing tracked left unstaged).
       # Three more paths can appear at a major boundary and are allowed for that
       # reason, all written by `sync-protocol-version.mjs` /
       # `sync-template-versions.mjs`: packages/spec/src/kernel/protocol-version.ts
@@ -848,7 +870,7 @@ jobs:
             echo "### Two things that are expected, not defects"
             echo
             echo "1. **The standing \`chore: version packages (rc)\` PR (#6208) may look stale.**"
-            echo "   Its changesets were consumed by this cut and are recorded in \`.changeset/pre.json\`."
+            echo "   Its changesets were consumed by this cut and moved to \`.changeset/pre/\` (v3)."
             echo "   Whether it refreshes now depends on the push credential: pushes made with the"
             echo "   Actions \`GITHUB_TOKEN\` trigger no workflow runs (GitHub's recursion guard), so"
             echo "   \`version-pr\` does not fire until some later push to main; with a"

.github/workflows/pr-automation.yml

@@ -383,12 +383,25 @@ jobs:
           fi
           # Count changesets THIS PR adds (diff against the base commit), NOT
           # the whole .changeset directory. A global `find | wc -l` is unsound:
-          # in pre-release (RC) mode `changeset version` RETAINS every consumed
-          # .md file, so the directory is permanently non-empty and the gate can
-          # never go red. #3373 merged a real spec/api-surface fix with no
-          # changeset while this step happily reported "Found 104 changeset(s)".
-          # Diffing against the merge base ignores that residue and sees only
-          # what the PR itself introduced. It has to be the MERGE BASE and not
+          # it counts main's pending stock, which has nothing to do with what this
+          # PR wrote. #3373 merged a real spec/api-surface fix with no changeset
+          # while this step happily reported "Found 104 changeset(s)".
+          # Diffing against the merge base ignores that stock and sees only what
+          # the PR itself introduced.
+          #
+          # That argument used to be stated in terms of pre-mode RESIDUE — under
+          # @changesets/cli v2, `changeset version` in pre mode retained every
+          # consumed .md file, so `.changeset/` was permanently non-empty for the
+          # whole RC window. v3 moves consumed changesets into `.changeset/pre/`
+          # instead (changesets#2190), so the root directory is no longer
+          # permanently non-empty. The unsoundness is unchanged and so is this
+          # step: a stock count is the wrong question in EVERY repo phase, not just
+          # a polluted one. What the migration did have to be checked against is
+          # the counter itself, because a cut now MOVES 209 tracked changeset
+          # paths: measured on a real v3 cut commit, git reports them as `R100`
+          # renames, so `--diff-filter=A` credits this PR with 0 of them (still 0
+          # with `diff.renameLimit=1` forced; only `--no-renames` turns them into
+          # 209 `A` rows, and nothing here passes it). It has to be the MERGE BASE and not
           # the payload's frozen `base.sha` -- see the base-resolution step above
           # (#6129); with the frozen sha this count silently included every
           # changeset main gained while the PR was open.
@@ -827,12 +840,19 @@ jobs:
         # same #6129 reason one defect along (#7005). This script used to read
         # the whole `.changeset` directory with no branch point, so its verdict
         # was a function of what main carried rather than of what the author
-        # wrote. That was invisible while pre-mode held and would have become
-        # visible all at once at `changeset pre exit`: 171 consumed-but-undeleted
-        # major changesets sit on main until the post-exit `changeset version`
-        # removes them, so every unlabelled PR open in that window would have
-        # gone red listing files it never touched, with `allow-major` -- a label
-        # meaning "a whole-stack major is intended HERE" -- as its only way out.
+        # wrote. Under @changesets/cli v2 that was invisible while pre-mode held
+        # and would have become visible all at once at `changeset pre exit`: 171
+        # consumed-but-undeleted major changesets sat on main until the post-exit
+        # `changeset version` removed them, so every unlabelled PR open in that
+        # window would have gone red listing files it never touched, with
+        # `allow-major` -- a label meaning "a whole-stack major is intended HERE"
+        # -- as its only way out. v3 retires that particular detonation: each cut
+        # moves its consumed changesets into `.changeset/pre/`, which the gate's
+        # root-only reader does not enumerate, so the root stock stays bounded to
+        # the unconsumed residue. It retires no line of the fix. `--base` is
+        # correct because a verdict about what a PR INTRODUCED cannot be computed
+        # without the fork -- #6129's argument, which never depended on how big
+        # the stock was.
         if: >-
           steps.labels.outputs.skip != 'true'
           && steps.labels_settled.outputs.skip != 'true'

docs/releases-maintenance.md

@@ -303,11 +303,14 @@ rediscovered at 2am:
   by itself.
 
 **A stale #6208 after an rc cut is EXPECTED AND HARMLESS — do not "fix" it by hand.**
-Its changesets were consumed by the cut and are recorded in `.changeset/pre.json`; the
-PR is bookkeeping, it carries no publish capability by construction (`release.yml`
-passes the changesets action no `publish:` script), and it regenerates correctly at
-the next push to `main` or the next GA cut. Editing or force-refreshing it manually
-only risks putting a version commit somewhere the publish lane can reach.
+Its changesets were consumed by the cut and MOVED into `.changeset/pre/` — under
+`@changesets/cli` v3 that move is what "consumed" looks like on disk, and
+`.changeset/pre.json` carries `{"mode","tag"}` and nothing else, so it is not a
+record of what was consumed (it was, under v2). The PR is bookkeeping, it carries no
+publish capability by construction (`release.yml` passes the changesets action no
+`publish:` script), and it regenerates correctly at the next push to `main` or the
+next GA cut. Editing or force-refreshing it manually only risks putting a version
+commit somewhere the publish lane can reach.
 
 **The runtime image is not built here.** `release.yml`'s `release-integrity` lane runs
 on every push to `main` and requests the image once the version is on npm, so it

package.json

@@ -117,7 +117,7 @@
   "author": "ObjectStack",
   "license": "Apache-2.0",
   "devDependencies": {
-    "@changesets/cli": "^2.31.1",
+    "@changesets/cli": "^3.0.0",
     "@types/node": "^26.1.2",
     "@typescript-eslint/parser": "^8.65.0",
     "eslint": "^10.8.0",