@@ -86,6 +86,52 @@ Deeper reading: `LIVE_PRECOMPILE_TESTING.md` (cross-validation architecture), `d
 - CI on every PR: `forge build`, `forge test`, `forge fmt --check`,
   `python3 script/check-coverage.py`, coverage comment. Live-precompile tests run in a separate workflow.
 
+## Cutting releases
+
+### Major vs. minor
+
+Versioning is `vMAJOR.MINOR.PATCH`, decided by the breaking change test below — not by hardfork
+boundaries. Hardforks here are additive by design, so most land as MINOR:
+
+- **MAJOR**: an actual breaking change. Rare.
+- **MINOR**: a hardfork's frozen interface, once it's additive (the common case) — increments once
+  per hardfork, matching `changelog/README.md`'s [Hardfork ordinals](changelog/README.md#hardfork-ordinals)
+  shifted down by one (`01` Beryl → `1.0`, `02` Cobalt → `1.1`, ...). Also covers any other additive
+  change. Freezing happens at tag time, which can be before on-chain activation.
+- **PATCH**: no interface change — tooling, harness, docs, or CI fixes (e.g. `v1.0.1`'s fork-profile
+  pin).
+
+If a hardfork's interface does contain a breaking change, that bumps MAJOR instead (resetting
+MINOR/PATCH to `0`).
+
+### Breaking change test
+
+This repo's invariant is slot-for-slot storage parity with the Rust precompiles plus a stable
+public ABI — a change is breaking if it violates either.
+
+Fix an already-shipped selector and its inputs. If the outcome can differ from what it is today —
+succeeds where it reverted, reverts where it succeeded, reverts with a different error, or
+returns/emits something different — it's breaking, regardless of whether the ABI itself gained or
+lost anything. A new error or event isn't automatically non-breaking; check what it's reachable from.
+
+### Drafting a release
+
+There is one ongoing release branch per MAJOR line, `releases/vN.x`, fast-forwarded to `main` at
+each freeze point — no per-hardfork or per-minor branch. A new `releases/v(N+1).x` only gets cut the
+day a breaking change actually ships.
+
+1. Land the frozen interface, its `changelog/<ordinal>_<Hardfork>_*.md` entries, and the
+   `CHANGELOG.md` summary on `main`.
+2. Fast-forward `releases/vN.x` to that commit: `git push origin main:releases/vN.x`.
+3. Tag from that branch, draft first: `git tag vN.M.P && git push origin vN.M.P`, then
+   `gh release create vN.M.P --draft --notes-file <notes>` — a draft anchored to a real, pushed tag
+   (GitHub shows a synthetic `untagged-<hash>` URL for drafts; expected, resolves on publish).
+4. Write notes via `--notes-file` and proofread the rendered draft (`gh release view vN.M.P`) before
+   leaving it — title/body follow `v1.0.0`/`v1.0.1`: compatibility statement, one bullet per
+   changelog entry, link the aligned base/base tag if one exists.
+5. Keep at most one open draft per version. If the branch moves before publishing, delete
+   (`gh release delete vN.M.P --yes`) and re-tag rather than leaving a stale draft around.
+
 ## Boundaries
 
 - **Don't change the precompile addresses** in `src/StdPrecompiles.sol` or the feature IDs in