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

Author: claude

.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

scripts/check-adr-0087-registration.mjs

@@ -347,6 +347,32 @@ const ADR_0087 = 'docs/adr/0087-metadata-protocol-upgrade-contract.md';
 /** `.changeset/README.md` is documentation, never a changeset. */
 const isChangesetFile = (p) => p.startsWith('.changeset/') && p.endsWith('.md') && !p.endsWith('/README.md');
 
+/**
+ * `.changeset/pre/NAME.md` is a CONSUMED prerelease changeset, not pending stock.
+ *
+ * New in `@changesets/cli` v3 (changesets#2190): a pre-mode `changeset version`
+ * MOVES every changeset it consumes out of `.changeset/` and into
+ * `.changeset/pre/`, verbatim, instead of leaving it in place and recording it in
+ * `pre.json` the way v2 did. Measured on a v3 cut of this repo (209 pending
+ * changesets, 17.0.0 -> 17.1.0-rc.0): all 209 move, git scores every one `R100`,
+ * and `git ls-tree -r ... -- .changeset` at the cut lists all 209 under `pre/`.
+ *
+ * That `-r` is why this predicate exists. `changesetDirAt` below lists the
+ * directory RECURSIVELY, so from the first v3 cut onwards the entire consumed
+ * stock of the open RC window would flow into `--list` and `--audit-stock` — two
+ * surfaces whose whole subject is the PENDING stock ("this gate judges diffs, not
+ * stock"), and whose numbers a reader takes as the size of the backlog. Every one
+ * of those changesets was judged by the diff scan on the PR that introduced it;
+ * re-listing them daily for the length of a window is noise that grows.
+ *
+ * WHERE THIS DELIBERATELY DOES NOT APPLY: the enforcing scan. It reads the diff
+ * through `isChangesetFile`, NOT through this predicate, so a changeset ADDED
+ * under `.changeset/pre/` in a PR is still judged like any other. Filtering the
+ * audit surfaces is a readability fix; filtering the verdict would be a bypass,
+ * and `PRE2` in the self-test pins the difference.
+ */
+const isConsumedPrerelease = (p) => p.startsWith('.changeset/pre/');
+
 /**
  * Split a changeset into its frontmatter bump entries and its body.
  *
@@ -1376,24 +1402,36 @@ export function mergeBase(base, head, cwd) {
 
 /**
  * Everything under `.changeset/` at a rev, split into "any entry at all" and
- * "actual changesets", or `null` when the tree itself cannot be listed.
+ * "actual PENDING changesets", or `null` when the tree itself cannot be listed.
  *
  * The split is what lets `assertInputs` tell an EMPTY STOCK (zero pending
  * changesets — the legitimate state of main right after a release cut, #8658)
  * apart from a MISSING DIRECTORY (not even the tracked README.md/config.json
  * found — unreadable input, still a #4690 refusal).
  *
+ * `entries` stays UNFILTERED on purpose: it answers "is this directory readable
+ * at all", and a tree whose changesets have all moved into `.changeset/pre/` is a
+ * perfectly readable one. Narrowing it would turn the ordinary post-cut state of
+ * main into a #4690 refusal — the exact confusion #8658 removed. `changesets` is
+ * the narrowed half (see `isConsumedPrerelease`).
+ *
  * @returns {{ entries: string[], changesets: string[] } | null}
  */
 function changesetDirAt(rev, cwd) {
   let out;
   try { out = git(['ls-tree', '-r', '--name-only', rev, '--', '.changeset'], cwd); } catch { return null; }
   const entries = out.split('\n').map((s) => s.trim()).filter(Boolean);
-  return { entries, changesets: entries.filter(isChangesetFile) };
+  return { entries, changesets: entries.filter((p) => isChangesetFile(p) && !isConsumedPrerelease(p)) };
 }
 
-/** Every changeset path present at a rev. */
-function changesetsAt(rev, cwd) {
+/**
+ * Every PENDING changeset path at a rev — the consumed prerelease stock under
+ * `.changeset/pre/` excluded (`isConsumedPrerelease`).
+ *
+ * Exported for `--self-test` S6/S8: the two consumers below print counts, and a
+ * count is the one thing an exit code cannot tell apart from "nothing ran".
+ */
+export function changesetsAt(rev, cwd) {
   return changesetDirAt(rev, cwd)?.changesets ?? [];
 }
 
@@ -3475,6 +3513,63 @@ function selfTest() {
     assert(cls(CS({ body: TABLE_PRESCRIPTION })) === 'residue', 'S7: THE #6497 SHAPE -- published break + arrowless rewrite TABLE -- is RESIDUE');
   }
 
+  // ---- PRE1-PRE3: `.changeset/pre/` is CONSUMED stock, not pending stock -----
+  //
+  // `@changesets/cli` v3 MOVES every changeset it consumes into `.changeset/pre/`
+  // at the cut that consumes it, and `changesetDirAt` lists `.changeset`
+  // RECURSIVELY (`ls-tree -r`). Without `isConsumedPrerelease` the entire consumed
+  // stock of an open RC window flows into `--list` and `--audit-stock`, two
+  // surfaces whose subject is the PENDING backlog. Measured on a real v3 cut of
+  // this repo's stock: 209 consumed changesets, every one of them returned by
+  // `git ls-tree -r --name-only <cut> -- .changeset`.
+  //
+  // PRE2 is the half that must NOT hold, and it is why the filter lives in
+  // `changesetsAt` rather than in `isChangesetFile`: the enforcing scan reads the
+  // diff through `isChangesetFile`, so a changeset ADDED under `.changeset/pre/`
+  // by a PR is judged like any other. Filter the verdict instead of the audit and
+  // `.changeset/pre/` becomes the place to put a breaking change you do not want
+  // read.
+  {
+    const { dir } = mk({
+      files: {
+        '.changeset/pre/consumed-one.md': CS({ body: 'consumed at the last cut\n\n**BREAKING** something\n' }),
+        '.changeset/pre/consumed-two.md': CS({ body: 'consumed at the last cut\n\n**BREAKING** something else\n' }),
+      },
+    });
+    const stock = changesetsAt('HEAD', dir);
+    assert(
+      stock.length === 1 && stock[0] === '.changeset/stock-breaking.md',
+      `PRE1: the audit surfaces read PENDING stock only -- two consumed changesets under .changeset/pre/ must not appear -- got ${JSON.stringify(stock)}`,
+    );
+  }
+
+  red('PRE2 a breaking changeset ADDED under .changeset/pre/ is still judged', run(mk({
+    files: { '.changeset/pre/smuggled.md': SIX048 },
+    pkgs: { '@objectstack/runtime': { dir: 'packages/runtime', private: false }, '@objectstack/spec': { dir: 'packages/spec', private: false } },
+  })), [/smuggled/, /no `adr-0087:` disposition marker/]);
+
+  {
+    // PRE3: `entries` stays UNFILTERED. A tree whose changesets have all moved
+    // into `.changeset/pre/` is the ordinary state of main mid-window; narrowing
+    // the readability probe as well would turn it into a #4690 refusal and undo
+    // #8658 by a different route. Pending stock is legitimately zero there.
+    const { dir } = mk({
+      files: {
+        '.changeset/stock-breaking.md': null,
+        '.changeset/pre/consumed.md': CS({ body: 'consumed\n\n**BREAKING** something\n' }),
+      },
+    });
+    const probs = assertInputs({ cwd: dir, head: 'HEAD' });
+    assert(
+      probs.length === 0,
+      `PRE3: a tree holding ONLY consumed changesets under .changeset/pre/ is readable input, not a #4690 refusal -- got: ${probs.join('|')}`,
+    );
+    assert(
+      changesetsAt('HEAD', dir).length === 0,
+      `PRE3: ...and its PENDING stock is legitimately zero -- got ${JSON.stringify(changesetsAt('HEAD', dir))}`,
+    );
+  }
+
   assert(breakingDeclaration(parseChangeset(CS({ body: 'feat(spec)!: x\n' }))).breaking, 'P6: a conventional-commit bang is a declaration');
   assert(!breakingDeclaration(parseChangeset(CS({ bumps: [['a', 'patch']], body: 'plain\n' }))).breaking, 'P7: a plain patch is not');