Review complete on f43c3e36; ready to merge as-is from this review. 339 successful checks, 6 skipped, and all six workflows successful. Bugbot is clear on this commit; no unresolved review threads or new actionable findings. Four release-lint assertions now handle both terminal stderr and GitHub Actions stdout annotations. The complete Python suite passes with Actions settings: 214 passed and one platform-specific skip. Independent source review and 48 additional changelog scenarios are clear.

Release train PR 1: release.py core, offline stamp, rc-aware release-lint

Summary

This is the first of the four PRs in docs/release-train/DESIGN.md §7. It adds the tested core that the weekly release train is built on. No workflow publishes anything new yet.

• scripts/release.py (stdlib Python, one file). Subcommands:
  • semver: the X.Y.Z / X.Y.Z-rc.N grammar and precedence.
  • stamp: an offline, byte-deterministic version stamp of Cargo.toml, Cargo.lock, the 15 npm manifests and the npm wrapper lock.
  • npm-lock-check
  • next-version: derived from git tags and burned release/* branches, never from main's own version.
  • changelog cut|promote|sync-main|check
  • sync-main
  • notes
  • blockers: the §3.5 release-blocker gate.
• scripts/version-sync.sh is now a thin wrapper over release.py stamp. The networked npm install --package-lock-only is gone, which ends the fix(maven): send the official Maven CLI user agent to the maven2 registry; refresh npm wrapper lock for published 4.0.0 platform packages #233/test(e2e): demote the cargo production legs to canary status — free cargo tier is unpublished #235 lock-drift class.
• scripts/release-lint.sh:
  • accepts X.Y.Z-rc.N;
  • check 2 is now the offline stamp --check plus npm-lock-check;
  • check 3 is rc-aware;
  • new --stable-only and --tag-exists flags.
• ci.yml release-readiness: a same-repo release-sync PR into main runs release-lint.sh --tag-exists. Every other PR behaves as before.
• Deleted: version-bump.yml and scripts/bump-version.sh. Every reference is fixed (release.yml comments, docs/releasing.md, the CHANGELOG header, the ci.yml shellcheck list).
• Tests: scripts/tests/test_release.py plus fixtures, which include a recorded #454/#456 PR-merge close. CI's existing unittest discover already runs them.

Design decisions (maintainer decisions D1–D4 applied)

• D2: version and CHANGELOG reach main on every rc.
  • sync-main brings main to the newest cut tag, rc or stable. It inserts each pending rc's ## [X.Y.Z-rc.N] section from the tag and removes exactly those blocks from [Unreleased].
  • At promotion, changelog promote --rc K folds rc.1..rc.K into one ## [X.Y.Z] section. When that stable is synced, every rc section of the core is dropped, and its blocks that did not ship go back to [Unreleased], oldest rc first and in their original chronological place. That covers an abandoned rc.K+1 and a train rc cut beside a hotfix.
  • Blocks are matched exactly and counted as a multiset everywhere:
    • the fold keeps every occurrence;
    • removal takes one occurrence per shipped block;
    • rc sections on main are charged against the stable's blocks before [Unreleased] is touched.
  • So next-version and changelog cut give byte-identical results whether or not the release-sync PR merged.
  • Version selection reads only tags and release/* branches. An unmerged sync PR never changes what gets cut.
  • release-lint accepts main at an rc.
• D4: APPROVED_MAJORS = (5,), so the first train cut is 5.0.0-rc.1. A breaking heading that would open an unapproved major is refused, and a major is never skipped.
• D3: blocker gate.
  • mikolalysenko is a routine actor, so he is never trusted to clear a blocker.
  • Config lists are parsed strictly, and an empty or degenerate config fails closed.
  • A PR-merge auto-close (commit_id: null) resolves only through a PR merged by the close actor whose merge commit is in the base.
  • since comes from merge-base(L, base) (never a tag's date) and is never later than base − 35 days, so a forged tag cannot shrink the window further.
  • A missing or renamed label, a vanished label, and a deleted or transferred issue all block. Any API error blocks.
• D1 (App + tag ruleset) is implemented in PR 3. Until the ruleset (S9) is live, the 35-day lookback bounds what a forged tag can hide. S9 is a hard prerequisite for any live gate run.
• CRLF: a Windows core.autocrlf checkout works. CHANGELOG transforms keep CRLF, and every stamped file keeps its own line endings, so stamp --check is a byte no-op there.
• No half-synced trees: sync-main computes the CHANGELOG and every stamped file before it writes any of them.

Acceptance results (DESIGN.md §7 PR 1, run end to end on this branch)

End-to-end script on the worktree (the tree was restored afterwards and git status is clean):

PASS  version-sync.sh 4.0.0 -> no diff (Synced version to 4.0.0)
PASS  release-lint.sh passes on main at 4.0.0
PASS  stamp 5.0.0-rc.1 x2 offline: identical bytes (18 files changed, digest 4c0128e8f32d3674)
PASS  stamp --check 5.0.0-rc.1 is a no-op after the stamp
PASS  stamp diff is inside the release allowlist
PASS  release-lint.sh passes at 5.0.0-rc.1: release-lint: all checks passed for 5.0.0-rc.1
PASS  release-lint --stable-only refuses 5.0.0-rc.1
PASS  cargo build --locked -j4 -p socket-patch-cli on the stamped tree (socket-patch 5.0.0-rc.1)
PASS  npm install --no-save --ignore-scripts in npm/socket-patch (added 4 packages in 4s)
PASS  npm install --no-save left the stamped files as stamped
PASS  5.0.0-rc.1 < 5.0.0
PASS  next-version on this branch's CHANGELOG + real tags = 5.0.0-rc.1
PASS  sync-main --check: main is in sync with the real tags (no train tags yet)
PASS  tree restored, git status clean

Unit tests (python3 -B -m unittest discover -s scripts/tests -v, as CI runs them): Ran 215 tests in 766.415s — OK (skipped=1); 82 of them are in test_release.py, all passing.

Accept-list items covered by scripts/tests/test_release.py:

• Versions and the main CHANGELOG snapshot:
  • version selection on the main CHANGELOG snapshot gives 5.0.0-rc.1 (test_first_train_on_the_main_snapshot_is_5_0_0_rc_1);
  • rc.2 while rc.1 is pending, with the sync PR merged or not;
  • after v5.0.0 with the sync PR unmerged, 5.0.1-rc.1 or 5.1.0-rc.1;
  • burned branches are skipped;
  • an unapproved major is refused, and a major is never skipped.
• Blocker fixtures:
  • a missing or renamed label, and case variants of the label;
  • a label that vanished without an unlabeled event, and a deleted, converted or transferred issue;
  • an empty, unset or malformed actor config, and the newline-, space- and @-separated forms;
  • since comes from the merge-base, a forged high tag cannot move it past the lookback, and a since after the base fails closed;
  • a PR-merge close resolves through the merge commit only, and a manual close after an unrelated mentioning PR does not;
  • an open issue untouched for 200 days blocks;
  • closed by a commit that is not in the base blocks, and closed by an ancestor commit passes;
  • closed by a trusted human after t blocks;
  • unlabelled or closed by a routine actor (mik included) blocks;
  • a trusted unlabel passes;
  • an API error blocks.
• D2 scenarios:
  • an rc syncs to main, and release-lint passes on that rc;
  • a stable fold with an abandoned later rc gives the same end state whether or not the sync PR merged;
  • sync-main is idempotent;
  • byte-identical cuts with the sync PR merged or unmerged, including:
    • a repeated identical entry (also repeated across folded rcs, and re-added after a promotion);
    • abandoned later rcs;
    • subsection order left over from shipped history;
  • a hotfix promoted beside a train rc of the same core;
  • CRLF CHANGELOG transforms and a CRLF stamp;
  • sync-main writes nothing when the stamp refuses;
  • release-lint (no flags and --tag-exists) on a sync-mained rc tree;
  • hermetic stamp tests (baselines 4.0.0 and an rc);
  • npm dependency drift caught offline.

What PRs 2–4 do next

• PR 2, release-qa.yml + smoke:
  • one workflow_dispatch run at release/v<V> builds the 14 archives and 15 npm tarballs once, smokes those bytes, and calls ci.yml plus the 9 compat workflows through workflow_call;
  • adds release_smoke.py (Tier 0/1), the verify-qa verdict, and the Tier 0 step in the ci.yml e2e-build leg;
  • must pass probes P1 and P2 first.
• PR 3, release.yml rc path:
  • plan (blocker gate, green-SHA window, version), then cut (a signed createCommitOnBranch stamp commit with a tree assertion), then QA with reruns and a fallback, then publish in env publish (the App mints the tag, then crates → npm next → GitHub prerelease), then verify-channels and report;
  • adds the Latest-release audit;
  • deletes publish-*.yml and dispatch-publish.sh;
  • needs P3, S8 and S9 before merge, and S3 and S4 at merge.
• PR 4, stable + hotfix + docs:
  • the approve environment gate;
  • stable plan/cut (rc commit + stamp + changelog promote), re-finding the rc's full-QA run;
  • hotfix mode with waive_soak;
  • cancelling parked runs;
  • docs/releasing.md runbook, ROUTINE.md and the CHANGELOG header.
  • After that, the daily release-train routine maintains the rolling release-sync PR.

Phase 0 manual checklist (DESIGN.md §6)

Setup

• S1 Routine identity: mikolalysenko for now (D3). Set RELEASE_ROUTINE_ACTORS to every account any Claude routine runs as (today mikolalysenko). Add the bot when it exists, and remove mik only once no routine runs as him.
• S2 Team socket-patch-release-approvers with at least 2 humans, none of them in RELEASE_ROUTINE_ACTORS. Mirror it in RELEASE_APPROVERS.
• S3 Environments:
  • release: reviewers = the team, branch main, admin bypass off, self-review prevention off;
  • publish: no reviewers, branch main, admin bypass off;
  • delete pypi and rubygems.
• S4 Trusted publishers: 15 npm packages and 2 crates → SocketDev/socket-patch / release.yml / env publish. Do this when PR 3 merges; it is an atomic cutover for npm. Confirm the org policy allows direct OIDC publish.
• S5 Repository setup:
  • enable immutable releases;
  • create the labels release-blocker (exact name; the gate fails closed with label: until it exists), release, release:train and release:sync;
  • add the secrets NTFY_TOPIC and SLACK_WEBHOOK_URL (optional);
  • pin the "Release train" issue.
• S6 Human triage of release-blocker on remove <purl> garbage-collects the beforeHash blobs of every other patch still in the manifest, so a later offline rollback of those patches fails missing_blob #559, scan/get --json drop the agent-mode apply failure: exit 1 with failed: 0, the patch shown as "added", and no error anywhere (e.g. a read-only global ~/.m2) #424, npm VEX attests not_affected while a bundled (inBundle) copy of the same package@version stays unpatched #325/npm agent-mode apply never patches an npm-aliased install (lp@npm:left-pad), yet VEX attests the package not_affected #356/In a yarn classic Plug'n'Play project, vex attests a hosted patch as not_affected while the copy .pnp.js loads is still unpatched #519/npm vendored vex and vendor --check pass while a second registry copy of the patched package@version in the same package-lock.json stays unwired and installs unpatched #588 and Perf regression: bun/hosted wall +110% (1169ae68, #472) #578/Perf regression: vlt/hosted wall +127% (1169ae68, #472) #579.
• S7 Run e2e_npm, e2e_pypi, e2e_gem and e2e_scan --ignored by hand on main. Drop any suite that is chronically red because of the public proxy from live-e2e, and document why.
• S8 Create the GitHub App socket-patch-release (D1):
  • permission contents: write only, no webhooks;
  • installed on SocketDev/socket-patch only;
  • RELEASE_APP_ID and RELEASE_APP_PRIVATE_KEY stored as secrets of env publish.
• S9 Tag ruleset on refs/tags/v*:
  • creations, updates and deletions restricted;
  • bypass list = the App only.
  • It needs an enterprise/org admin. Schedule it before PR 3 merges. It is a hard prerequisite for any live blocker-gate run.

Must-run probes

• P1 On scratch release/v0.0.0-rc.1, GITHUB_TOKEN can POST /git/refs and createCommitOnBranch, and the result is a verified commit that ruleset 14265462 accepts.
• P2 release-qa.yml runs ci + 9 compat as one run. Check that:
  • the job count is accepted;
  • no concurrency group stalls;
  • e2e-docker and hosted-e2e (force) execute;
  • artifact names don't collide;
  • rerun-failed-jobs works.
  • Also measure p95 wall time.
• P3 With immutable releases and the tag ruleset on:
  • the App token can create a scratch v0.0.0-rc.1 tag that GITHUB_TOKEN cannot;
  • a draft created on that existing tag accepts uploads;
  • publishing the draft keeps the tag at its SHA.

🤖 Generated with Claude Code

Generated by Claude Code
CI follow-up: one PDM 2.6.1 Ubuntu job initially stopped on an API HTTP 504 before patching. Its single targeted retry passed: 34 supported/expected-refusal cases and two documented unsupported PEP582 cases, with no failed checks. The fresh artifact digest and source revision were verified.