[v3 migration 2/4] Land the v3 migration as one atomic PR — bump, gates, workflows and config together

[os-project-manager]

Sub-issue of #9465.

Blocked-by: #9497

Do not start before #9497's measurements are on #9465. The scope of this card is those measurements; starting early means writing the migration against a guessed shape, which is the failure this epic is structured to avoid.

Ruling — one PR, not a sequence

Both half-states are broken, and each is broken silently until the next release:

• bump alone → v3 installed while the gates and cut-rc.yml still model v2's pre-mode semantics;
• migration alone → gates expecting .changeset/pre/ while v2 never creates it.

So this PR carries @changesets/cli: ^3.0.0 in the root package.json and every consequential change. #9217 (Dependabot's raw bump) closes itself once main carries ^3.0.0.

Expected surface — re-derive it from #9497's verdicts, do not copy this list

package.json (the bump; and the version script is a && chain — changeset version && sync-protocol-version.mjs && sync-template-versions.mjs && sync-docs-image-tags.mjs — so v3's exit-1 behaviour reaches all of it) · .changeset/config.json ($schema, privatePackages per U4, the experimental key per U2) · scripts/check-changeset-no-major.mjs (the pre/RC exemption, per U5) · scripts/objectui-changeset-digest.mjs (reads .changeset/pre.json, and its self-test fixtures write {"mode":"pre","tag":"rc"}) · scripts/check-empty-changeset.mjs (only if U1 measured exact coverage; the default is that this gate stays) · .github/workflows/cut-rc.yml (the enforced allowlist and the prose describing v2 semantics) · .github/workflows/pr-automation.yml (prose referencing pre.json behaviour and #4898).

Non-negotiable

• The allowlist follows the measurement, never the reverse. If a v3 changeset version produces a file set cut-rc.yml would reject, the allowlist is updated to the measured truth — you do not massage the tool's output to fit a list written under v2.
• A self-test that still asserts v2 semantics is a failed run, not a passing one. Every touched script's --self-test must model v3 and pass.
• Perform no release. No changeset publish, no version tags, no release-workflow dispatch, no merging of a Version Packages PR, and no pre-mode transition on origin. Releases are human-only here and this card does not change that.
• Do not weaken a gate to accommodate v3 before [v3 migration 1/4] Rehearse @changesets/cli v3 in a throwaway clone and answer U1–U6 with measurements — no repo changes #9497 measured what v3 actually does.

Acceptance

• One PR, first body line Fixes #<this card>, carrying the bump and every consequential change together.
• PR body carries the rehearsal record from [v3 migration 1/4] Rehearse @changesets/cli v3 in a throwaway clone and answer U1–U6 with measurements — no repo changes #9497 (measured file set vs the allowlist) and states which of U1–U6 drove which change.
• Every touched script's --self-test passes and models v3; gates re-derived for the actual diff with node scripts/pm/dispatch-gates.mjs and run.
• Changeset decision stated and justified: a root devDependency change reaches no consumer, so skip-changeset may be correct here — decide from the diff and say why.
• pnpm changeset, changeset status and a dry pnpm run version all exercised after the change, with output quoted.

[os-project-manager]

Decision required before this card can be written — the migration changes the release number

#9497's rehearsal measured it on both CLIs from identical stock, with no changeset declaring a major:

	computed next RC
@changesets/cli 2.31.1 (today)	18.0.0-rc.0
@changesets/cli 3.0.0	17.1.0-rc.0

Traced by ablation, not inferred: deleting @objectstack/cli's peerDependencies block flips v2's plan from {"major":69,"patch":7,"none":1} to {"minor":69,...}. The major digit today comes from one optional peer edge on @objectstack/driver-turso interacting with "a prerelease never satisfies a non-prerelease range" — not from anything an author wrote.

This is blocking rather than cosmetic: cut-rc.yml asserts the computed version equals the dispatched one, so the first cut after this card lands refuses a dispatch written from the old expectation.

Not adjudicable by this seat. Release numbering is a maintainer call under the release guardrail, and it is exactly the class where the mechanical test says escalate: it changes a published version's meaning, and it is not reversible once a train ships under it.

Options

• A — accept 17.1.0. Treat v2's 18.0.0 as the artifact it is, and let the convention already enforced in check-changeset-no-major.mjs mean what it says: a major is declared deliberately or not at all.
• B — preserve 18.0.0. Land a deliberate major-declaring changeset (or an explicit version input) in this same PR, so the number the last several trains were built on carries forward.
• C — defer to [v3 migration 4/4] Verify the migrated release path inside the next real RC window #9500, settling numbering inside the next real RC window.

Four prongs

• Platform long-term coherence — A shrinks a special case: the version stops being a function of a dependency-graph detail no author can see. B keeps that coupling alive, which is the exact class of hidden mechanism this epic exists to remove.
• Measured business pull — nothing downstream was found consuming the major digit as a promise. v2's 18.0.0 was never anyone's decision. "Preserving" it preserves an accident.
• AI-agent error-resistance — under A, "what version does this cut produce" is derivable from changesets a human or agent can read. Under B the trap stays armed and undocumented, and the next person to hit it has no way to see why.
• Startup scope discipline — A costs nothing to adopt; B costs a fabricated major-declaring changeset whose stated reason would be "because the old tool computed it that way".

PM recommendation: A, with the ruling recorded here before #9498 is written. C is the weakest of the three — it defers a decision that changes what this card's own tests must assert, and #9500 cannot run until a real window opens.

This card is needs-user-decision until that ruling lands. Its other blocker (Blocked-by: #9497) is now cleared — the rehearsal is done and the scope is on #9465.

---

Generated by Claude Code

[os-project-manager]

Ruling: option A — the next train is 17.1.0

Maintainer's decision, quoted verbatim:

接受 17.1.0

Recorded as binding on this card and on #9500. What it settles, so nobody re-derives it later:

• The next RC computes 17.1.0-rc.0 under v3, from the same stock that computes 18.0.0-rc.0 under v2. That difference is expected and accepted, not a defect to chase.
• v2's major digit is understood as an artifact — one optional peerDependency from @objectstack/cli onto @objectstack/driver-turso, interacting with "a prerelease never satisfies a non-prerelease range". No changeset declared it and no downstream was found consuming it as a promise.
• The repo's existing convention now means what it says: a major is declared, not inferred. No compensating major-declaring changeset is to be written to preserve 18.0.0 — that was explicitly rejected.

Consequences this card must carry:

1. The PR states the expected next computed version and shows it — a changeset status reading under v3 on the migrated tree, so the number is evidence rather than a claim.
2. Whatever this card's tests assert about versioning must assert 17.1.0, not the old expectation.
3. cut-rc.yml asserts computed == dispatched, so the first dispatch after this lands must be written from the new number. That is a note for whoever runs the next cut, and it belongs in the PR body where they will look.

needs-user-decision is cleared; this card returns to the queue.

Sequencing, decided now rather than discovered later: this card edits cut-rc.yml's staging/allowlist block, and #9518 is in flight on that exact block (a p0 defect that blocks the next cut on today's v2, independent of this migration). Same-file work serializes: #9518 lands first, this card rebases onto it. Being unblocked by the ruling does not make it dispatchable while a sibling holds the file.

---

Generated by Claude Code