Release train PR 1: release.py core (offline stamp, rc versions, CHANGELOG sync/fold, blocker gate)

.github/workflows/ci.yml

@@ -176,16 +176,22 @@ jobs:
           done
 
       - name: Shell — shellcheck the release scripts
-        run: shellcheck scripts/version-sync.sh scripts/bump-version.sh scripts/release-lint.sh scripts/dispatch-publish.sh
+        run: shellcheck scripts/version-sync.sh scripts/release-lint.sh scripts/dispatch-publish.sh
 
   # Release-readiness gate (scripts/release-lint.sh — the same checks the
   # Release workflow's `version` job runs before publishing anything):
   #   - every PR/push: version coherence — version-sync.sh must be a no-op,
   #     so a hand-edited version in any single packaging site fails CI here
   #     instead of surfacing mid-release;
-  #   - PRs that bump the workspace version (release/vX.Y.Z bump PRs): the
-  #     full gate — CHANGELOG has a dated, non-empty section for the new
-  #     version and the tag doesn't already exist.
+  #   - the release train's rolling `release-sync` PR (docs/release-train/
+  #     DESIGN.md §3.7), which moves main to the newest cut tag (rc or
+  #     stable): CHANGELOG has a non-empty section for that version and the
+  #     tag already exists. Only a same-repo `release-sync` branch targeting
+  #     main gets this path; the same branch name from a fork (or aimed at
+  #     another base) gets the full gate below;
+  #   - any other PR that bumps the workspace version: the full gate —
+  #     CHANGELOG has a dated, non-empty section for the new version and the
+  #     tag doesn't already exist.
   release-readiness:
     runs-on: ubuntu-latest
     steps:
@@ -198,7 +204,16 @@ jobs:
         env:
           EVENT_NAME: ${{ github.event_name }}
           BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_REF: ${{ github.head_ref }}
+          BASE_REF: ${{ github.base_ref }}
+          HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
+          REPO: ${{ github.repository }}
         run: |
+          if [ "$EVENT_NAME" = "pull_request" ] && [ "$HEAD_REF" = "release-sync" ] \
+              && [ "$HEAD_REPO" = "$REPO" ] && [ "$BASE_REF" = "main" ]; then
+            bash scripts/release-lint.sh --tag-exists
+            exit 0
+          fi
           if [ "$EVENT_NAME" = "pull_request" ]; then
             # Compare the workspace version against the PR base to detect a
             # version bump. The shallow checkout doesn't have the base

.github/workflows/publish-npm.yml

@@ -197,10 +197,10 @@ jobs:
         # script, which compiles the `./schema` export with tsc — the
         # `typescript` devDependency must be installed for that build.
         #
-        # NOT `npm ci`: version-sync.sh refreshes package-lock.json while the
-        # release's platform packages are not yet on the registry, so npm
-        # records the optionalDependencies as hollow stubs ("optional": true,
-        # no version/resolved/integrity) and `npm ci` refuses that lockfile
+        # NOT `npm ci`: version-sync.sh (the offline stamp) drops the lock's
+        # platform-package entries for any other version, and the release's
+        # platform packages are not yet on the registry when it runs, so the
+        # lock has no entries for them and `npm ci` refuses it
         # ("lock file's ...@ does not satisfy ...@X.Y.Z"). `npm install`
         # tolerates the stubs and skips unresolvable optional platform
         # packages (verified for both the published and unpublished-version

.github/workflows/release.yml

@@ -70,13 +70,17 @@ jobs:
       - name: Release-readiness gate
         # scripts/release-lint.sh is the single source of truth for the
         # version chores, shared with CI's release-readiness job (which runs
-        # it on the version-bump PR, so failures surface at PR time, not
-        # here). Checks: version coherence (version-sync.sh is a no-op),
-        # CHANGELOG has a non-empty section for this version, and — via
-        # --tag-check, asked of the remote since this checkout is shallow
-        # and tagless — the tag doesn't exist at a different commit (a tag
-        # already at $GITHUB_SHA is a retry of a previous run and passes).
-        run: bash scripts/release-lint.sh --tag-check
+        # it on the PR that bumps the version, so failures surface at PR
+        # time, not here). Checks: version coherence (the offline stamp,
+        # scripts/release.py stamp, is a no-op), CHANGELOG has a non-empty
+        # section for this version, and — via --tag-check, asked of the
+        # remote since this checkout is shallow and tagless — the tag doesn't
+        # exist at a different commit (a tag already at $GITHUB_SHA is a
+        # retry of a previous run and passes). --stable-only: this legacy
+        # pipeline publishes as GitHub Latest / npm latest, so it must never
+        # see an X.Y.Z-rc.N version; rcs ship only through the release train
+        # (docs/release-train/DESIGN.md), which replaces this workflow.
+        run: bash scripts/release-lint.sh --stable-only --tag-check
 
   build:
     needs: version

CHANGELOG.md

@@ -9,11 +9,15 @@ Pre-v3.0 entries are concise summaries derived from each tag's commit
 history. For full per-release detail, see the
 [GitHub releases page](https://github.com/SocketDev/socket-patch/releases).
 
-The `Release` workflow refuses to publish a version that does not appear
-in this file — see `scripts/release-lint.sh` (run by the `version` job in
-`.github/workflows/release.yml` and by CI on version-bump PRs). Bump PRs
-are opened by `scripts/bump-version.sh`, which rolls `[Unreleased]` over
-into the new version's section — see docs/releasing.md.
+Add entries under `[Unreleased]`; its `###` headings set the next version's
+bump (Breaking/Removed → major, Added/Changed/Deprecated → minor, anything
+else → patch). Releases are cut by the release train
+([docs/release-train/DESIGN.md](docs/release-train/DESIGN.md)) with
+`scripts/release.py`: a release candidate's `[Unreleased]` entries become a
+`## [X.Y.Z-rc.N]` section, the rolling `release-sync` PR brings each cut
+section and version back to main, and promoting an rc folds its rc sections
+into one `## [X.Y.Z]` section. `scripts/release-lint.sh` refuses to release
+a version without a non-empty section in this file.
 
 ## [Unreleased]
 

crates/socket-patch-cli/CLI_CONTRACT.md

@@ -1600,6 +1600,7 @@ scripts/version-sync.sh <new-version>
 This syncs the workspace package version into:
 
 - `Cargo.toml` (workspace version and the exact `socket-patch-core` dependency pin)
+- `Cargo.lock` (the workspace members' own entries)
 - `npm/socket-patch/package.json` (and its `optionalDependencies`) and `package-lock.json`
 - every per-platform `npm/socket-patch-*/package.json`