@1aboveio/skills 0.10.0

package/skills/engineering/resolve-release/scripts/version.mjs

@@ -0,0 +1,1199 @@
+// version — the mechanized versioning / tagging / CHANGELOG helper for the release lane.
+//
+// Versioning is a load-bearing release step, and a prose-described load-bearing step
+// degrades to a lookalike: an agent that "computes the next version" from memory picks
+// a minor for a breaking change, re-points a tag to a new SHA to "fix" it, or reuses the
+// version of a rolled-back release. Each of those is unrecoverable once pushed — a tag
+// is a public promise about an immutable SHA. So the invariants live here, mechanically:
+//
+//   1. PRODUCTION ONLY. Versions, tags and CHANGELOG cuts exist only on the production
+//      branch. A dev/staging release is unversioned and identified by its SHA. `plan`,
+//      `changelog`, `rc` and `tag` refuse (exit 3, a NORMAL outcome) when --target-branch is
+//      not the production branch — the release loop calls them unconditionally and branches on
+//      3. The gate FAILS CLOSED: both branch flags are required (exit 2 without them), or
+//      an agent could skip the guard by simply omitting a flag.
+//   2. TAGS ARE IMMUTABLE. `tag` never moves, deletes, or force-writes a tag. Re-tagging
+//      the same SHA is a resume-safe no-op; re-tagging a DIFFERENT SHA is exit 1. There is
+//      deliberately no --force: a version that reached a remote is burned, and the next
+//      attempt takes the next patch (references/versioning.md, "the invariant, the trigger,
+//      and the burn").
+//      The rc tags `rc` mints obey the same rule — a given rc number names one SHA forever.
+//      They are cheap because they are NUMBERED, not because they move: the next attempt
+//      takes the next rc, and the VERSION survives, because the final `v<version>` tag is
+//      minted only after production verification. That is the point of rc tags — a burn is
+//      then possible only on the legacy shape where the final tag itself triggers the
+//      deploy (references/versioning.md, "the invariant, the trigger, and the burn").
+//   3. THE CHANGELOG IS APPEND-ONLY. A rolled-back release's section is never deleted —
+//      `withdraw` annotates it. Deleting it would erase the only public record that the
+//      version existed and was withdrawn.
+//
+//   For the authoritative subcommand / flag / exit-code list, run `node version.mjs --help`
+//   (or read the USAGE const below, right beside the dispatch it describes). That help text is
+//   the SINGLE source of truth: restating the case list here would give it a second copy to
+//   drift against, which is the exact footgun this pointer removes — one list can't contradict
+//   itself. What stays here is the doctrine `--help` does not encode: the three invariants
+//   above, plus this one rule about the codes it prints — each exit code carries exactly ONE
+//   meaning, because an agent branches on them, so an overloaded code (3 meaning both "skip
+//   versioning" and "already cut") would make a resuming run silently ship production untagged.
+//   The policy behind all of it: references/versioning.md.
+
+import fs from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+// ---- semver ----
+
+const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/
+
+export function parseSemver(input) {
+  const m = SEMVER_RE.exec(String(input).trim())
+  if (!m) return null
+  return {
+    major: Number(m[1]),
+    minor: Number(m[2]),
+    patch: Number(m[3]),
+    prerelease: m[4] || null,
+  }
+}
+
+export function formatVersion(v) {
+  return `${v.major}.${v.minor}.${v.patch}`
+}
+
+export function compareVersions(a, b) {
+  for (const k of ['major', 'minor', 'patch']) {
+    if (a[k] !== b[k]) return a[k] < b[k] ? -1 : 1
+  }
+  // A prerelease sorts BEFORE its release (semver §11.3). The lane mints these itself now
+  // (`rc`), so this ordering is load-bearing rather than defensive.
+  if (a.prerelease && !b.prerelease) return -1
+  if (!a.prerelease && b.prerelease) return 1
+  return 0
+}
+
+// The latest RELEASE tag: a prerelease is never a release baseline. A `v1.5.0-rc.2` means a
+// candidate for 1.5.0 that has NOT been verified in production — 1.5.0 is still unreleased,
+// so baselining on it would propose 1.5.1 and skip a version that never shipped.
+export function latestReleaseTag(tags) {
+  const parsed = tags
+    .map((t) => ({ tag: t, v: parseSemver(t) }))
+    .filter((x) => x.v && !x.v.prerelease)
+  if (parsed.length === 0) return null
+  parsed.sort((a, b) => compareVersions(a.v, b.v))
+  return parsed[parsed.length - 1]
+}
+
+// ---- change classification (conventional commits, then labels) ----
+
+const TITLE_RE = /^\s*([a-zA-Z]+)(?:\(([^)]*)\))?(!)?:\s*(.+)$/
+const BREAKING_LABELS = new Set(['breaking', 'breaking-change', 'semver-major'])
+
+// Conventional type → CHANGELOG section. Types absent here are internal: excluded from
+// the CHANGELOG unless --include-internal, because a changelog records notable changes,
+// not every commit.
+export const SECTION_BY_TYPE = {
+  feat: 'Added',
+  fix: 'Fixed',
+  perf: 'Changed',
+  refactor: 'Changed',
+  revert: 'Removed',
+  security: 'Security',
+}
+export const INTERNAL_TYPES = ['build', 'chore', 'ci', 'docs', 'style', 'test']
+export const SECTION_ORDER = ['Breaking', 'Added', 'Changed', 'Removed', 'Fixed', 'Security', 'Internal']
+
+export function classifyChange(change) {
+  const title = String(change.title || '')
+  const labels = (change.labels || []).map((l) => String(l).toLowerCase())
+  const m = TITLE_RE.exec(title)
+
+  let type = m ? m[1].toLowerCase() : null
+  if (!type) type = labels.find((l) => l in SECTION_BY_TYPE || INTERNAL_TYPES.includes(l)) || 'other'
+
+  const breaking =
+    Boolean(m && m[3]) ||
+    /(^|\n)BREAKING[ -]CHANGE:/.test(String(change.body || '')) ||
+    labels.some((l) => BREAKING_LABELS.has(l))
+
+  const internal = INTERNAL_TYPES.includes(type)
+  const section = breaking ? 'Breaking' : internal ? 'Internal' : SECTION_BY_TYPE[type] || 'Changed'
+
+  return {
+    ...change,
+    type,
+    breaking,
+    internal,
+    section,
+    scope: m ? m[2] || null : null,
+    summary: m ? m[4] : title,
+  }
+}
+
+// The bump the release CONTENT demands. Under 0.x (`--strict` disables this), breaking
+// changes land as a minor because the public contract is still unstable. Non-breaking
+// features remain minor releases so version numbers communicate new capability.
+export function bumpFor(changes, current, { strict = false } = {}) {
+  const classified = changes.map(classifyChange)
+  const zeroVer = !strict && current.major === 0
+
+  if (classified.some((c) => c.breaking)) {
+    return { bump: zeroVer ? 'minor' : 'major', reason: 'breaking change in the release content' }
+  }
+  if (classified.some((c) => c.type === 'feat')) {
+    return { bump: 'minor', reason: 'new feature in the release content' }
+  }
+  return { bump: 'patch', reason: 'fixes and internal changes only' }
+}
+
+export function nextVersion(current, bump) {
+  if (bump === 'major') return { major: current.major + 1, minor: 0, patch: 0, prerelease: null }
+  if (bump === 'minor') return { major: current.major, minor: current.minor + 1, patch: 0, prerelease: null }
+  return { major: current.major, minor: current.minor, patch: current.patch + 1, prerelease: null }
+}
+
+export function tagName(version, prefix = 'v') {
+  return `${prefix}${typeof version === 'string' ? version : formatVersion(version)}`
+}
+
+// The rc tags belonging to ONE exact version tag, ascending by number. Matching is exact,
+// not prefix-wise: `v1.5.0` must not collect `v1.5.0-rc.1-hotfix` or anything under a
+// neighbouring version, or the next rc number would be computed from a foreign series.
+export function rcTags(tags, base) {
+  const re = new RegExp(`^${base.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}-rc\\.(\\d+)$`)
+  return tags
+    .map((t) => ({ tag: t, n: Number((re.exec(t) || [])[1]) }))
+    .filter((x) => Number.isInteger(x.n))
+    .sort((a, b) => a.n - b.n)
+}
+
+// The rc tags a REMOTE holds for one version, each with the commit it names.
+//
+// Numbering an rc from local tags alone is wrong whenever the two can disagree, and they
+// disagree in the most ordinary case there is: a fresh clone has no local tags, so the next
+// number computes as rc.1 while the remote is already on rc.3. What makes that worse than a
+// bad number is the ORDER it fails in — `git tag` succeeds locally, then `git push` is
+// rejected, leaving a stale local tag pointing at the wrong commit and a non-zero exit that
+// looks like a crash. Since it is the remote that fires the production pipeline, the remote
+// is the authority on which numbers are spent. Same deref subtlety as remoteTagSha: an
+// annotated tag's commit appears only on the `^{}` line, so prefer it when both are present.
+export function remoteRcTags(remote, base, run = git) {
+  const out = run(['ls-remote', '--tags', remote, `refs/tags/${base}-rc.*`], { allowFail: true }).stdout
+  if (!out) return []
+  const shaByTag = new Map()
+  for (const line of out.split('\n').filter(Boolean)) {
+    const [sha, ref] = line.split(/\s+/)
+    if (!ref) continue
+    const isDeref = ref.endsWith('^{}')
+    const name = ref.replace(/^refs\/tags\//, '').replace(/\^\{\}$/, '')
+    if (isDeref || !shaByTag.has(name)) shaByTag.set(name, sha)
+  }
+  return rcTags([...shaByTag.keys()], base).map((x) => ({ ...x, sha: shaByTag.get(x.tag) }))
+}
+
+// ---- CHANGELOG rendering ----
+
+const SCAFFOLD = `# Changelog
+
+All notable changes to this project are documented in this file. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+`
+
+function prLink(change, repo) {
+  if (!change.pr) return ''
+  const n = String(change.pr).replace(/^#/, '')
+  return repo ? ` ([#${n}](https://github.com/${repo}/pull/${n}))` : ` (#${n})`
+}
+
+function issueRefs(change) {
+  const issues = change.issues || []
+  if (issues.length === 0) return ''
+  return ` — closes ${issues.map((i) => `#${String(i).replace(/^#/, '')}`).join(', ')}`
+}
+
+// A release section (and the [Unreleased] body) is just `### Section` groups of bullets.
+// Parsing back to that shape is what lets the cut MERGE hand-staged notes with derived
+// ones instead of one clobbering the other.
+export function parseGroups(body) {
+  const groups = new Map()
+  let current = null
+  for (const line of String(body).split('\n')) {
+    const heading = /^###\s+(.+?)\s*$/.exec(line)
+    if (heading) {
+      current = heading[1]
+      if (!groups.has(current)) groups.set(current, [])
+      continue
+    }
+    if (/^\s*[-*]\s+/.test(line)) {
+      const key = current || 'Changed' // a bare bullet under no heading still counts
+      if (!groups.has(key)) groups.set(key, [])
+      groups.get(key).push(line.trim().replace(/^\*\s+/, '- '))
+    }
+  }
+  return groups
+}
+
+// Staged notes first (a human wrote them), then derived entries; exact duplicates collapse.
+export function mergeGroups(staged, derived) {
+  const out = new Map()
+  const keys = [...SECTION_ORDER, ...[...staged.keys(), ...derived.keys()].filter((k) => !SECTION_ORDER.includes(k))]
+  for (const key of keys) {
+    if (out.has(key)) continue
+    const items = [...(staged.get(key) || []), ...(derived.get(key) || [])]
+    const seen = new Set()
+    const deduped = items.filter((i) => (seen.has(i) ? false : seen.add(i)))
+    if (deduped.length > 0) out.set(key, deduped)
+  }
+  return out
+}
+
+export function renderGroups(version, date, groups) {
+  const lines = [`## [${version}] — ${date}`, '']
+  if (groups.size === 0) return `${lines.join('\n')}_No user-facing changes._\n`
+  for (const [section, items] of groups) {
+    lines.push(`### ${section}`, '', ...items, '')
+  }
+  return lines.join('\n')
+}
+
+export function groupsFromChanges(changes, { repo = null, includeInternal = false } = {}) {
+  const groups = new Map()
+  for (const c of changes.map(classifyChange)) {
+    if (!includeInternal && c.internal) continue
+    if (!groups.has(c.section)) groups.set(c.section, [])
+    const scope = c.scope ? `**${c.scope}**: ` : ''
+    groups.get(c.section).push(`- ${scope}${c.summary}${prLink(c, repo)}${issueRefs(c)}`)
+  }
+  // Emit in SECTION_ORDER so Breaking leads.
+  const ordered = new Map()
+  for (const s of SECTION_ORDER) if (groups.has(s)) ordered.set(s, groups.get(s))
+  return ordered
+}
+
+export function renderChangelogSection({ version, date, changes, repo = null, includeInternal = false }) {
+  return renderGroups(version, date, groupsFromChanges(changes, { repo, includeInternal }))
+}
+
+const headingRe = (version) => new RegExp(`^## \\[${version.replace(/\./g, '\\.')}\\]`)
+
+function bodyAfter(lines, headingIdx) {
+  let end = headingIdx + 1
+  while (end < lines.length && !/^## /.test(lines[end])) end++
+  return { body: lines.slice(headingIdx + 1, end).join('\n'), end }
+}
+
+// Cut the release: the [Unreleased] body — the unversioned zone where changes accumulate
+// as they merge to dev — is CARRIED into a new versioned heading, merged with the entries
+// derived from the release's PRs, and [Unreleased] is left empty for the next cycle. This
+// is the whole reason dev needs no version: `Unreleased` IS the absence of one, and the
+// version is assigned once, here, to the set of changes being promoted.
+//
+// Carrying (never discarding) is the invariant: a hand-written note that a PR title did
+// not capture must survive the cut. Idempotent — re-cutting a version already present is
+// a resume, not a double-cut.
+export function insertSection(md, section, version) {
+  const text = md && md.trim() ? md : SCAFFOLD
+  const lines = text.split('\n')
+
+  if (lines.some((l) => headingRe(version).test(l))) return { text, noop: true }
+
+  const sectionLines = section.trimEnd().split('\n')
+  const heading = sectionLines[0]
+  const derived = parseGroups(sectionLines.slice(1).join('\n'))
+  const unreleasedAt = lines.findIndex((l) => /^## \[Unreleased\]/i.test(l))
+
+  const finish = (out) => ({ text: `${out.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd()}\n`, noop: false })
+
+  if (unreleasedAt === -1) {
+    // No Unreleased section: nothing to carry. Insert above the first release heading.
+    const firstRelease = lines.findIndex((l) => /^## /.test(l))
+    const at = firstRelease === -1 ? lines.length : firstRelease
+    lines.splice(at, 0, ...renderGroups(version, heading.split('—').pop().trim(), derived).split('\n'))
+    return finish(lines)
+  }
+
+  const { body, end } = bodyAfter(lines, unreleasedAt)
+  const merged = mergeGroups(parseGroups(body), derived)
+  const cut = [heading, '', ...renderGroups(version, 'x', merged).split('\n').slice(2)]
+
+  return finish([...lines.slice(0, unreleasedAt + 1), '', ...cut, '', ...lines.slice(end)])
+}
+
+export function extractSection(md, version) {
+  const lines = String(md).split('\n')
+  const start = lines.findIndex((l) => headingRe(version).test(l))
+  if (start === -1) return null
+  let end = start + 1
+  while (end < lines.length && !/^## /.test(lines[end])) end++
+  return lines.slice(start, end).join('\n').trim()
+}
+
+// A rolled-back version is annotated, never deleted (invariant 3). The note is what tells
+// a reader the tag exists but the version never served production.
+export function markWithdrawn(md, version, incident) {
+  const lines = String(md).split('\n')
+  const at = lines.findIndex((l) => headingRe(version).test(l))
+  if (at === -1) return { text: md, noop: true, reason: `no [${version}] section` }
+  if (lines.slice(at, at + 4).some((l) => /^> \*\*Withdrawn\*\*/.test(l))) {
+    return { text: md, noop: true, reason: 'already withdrawn' }
+  }
+  const ref = incident ? ` See ${String(incident).startsWith('#') ? incident : `#${incident}`}.` : ''
+  // Wording covers BOTH doors to a burn: a failed build (never deployed) and a failed
+  // verification (deployed, rolled back). "Never served production traffic" is the claim
+  // that holds either way; "was rolled back" would be false for the build-failure case.
+  const note = `> **Withdrawn** — this release never served production traffic.${ref}`
+  lines.splice(at + 1, 0, '', note)
+  return { text: `${lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd()}\n`, noop: false }
+}
+
+// ---- git ----
+
+export function git(args, { allowFail = false, cwd } = {}) {
+  const r = spawnSync('git', args, { encoding: 'utf8', cwd })
+  if (r.status !== 0 && !allowFail) {
+    throw new Error(`git ${args.join(' ')} failed: ${(r.stderr || '').trim()}`)
+  }
+  return { status: r.status, stdout: (r.stdout || '').trim(), stderr: (r.stderr || '').trim() }
+}
+
+export function tagExists(tag, run = git) {
+  return run(['rev-parse', '-q', '--verify', `refs/tags/${tag}`], { allowFail: true }).status === 0
+}
+
+export function shaForTag(tag, run = git) {
+  return run(['rev-list', '-n', '1', tag]).stdout
+}
+
+// Resolve a caller-supplied commit-ish, or null. Never throws.
+//
+// Every `--sha` here arrives from a human or a half-finished script in the middle of a
+// release: a typo, a branch this clone never fetched, a SHA copied from another checkout.
+// Letting git throw turns all of those into an identical stack trace, which at that moment
+// reads as "the release tool is broken" rather than "that ref isn't in this repo" — and the
+// difference decides whether the operator retries or starts debugging the wrong thing.
+export function resolveSha(ref, run = git) {
+  const r = run(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], { allowFail: true })
+  return r.status === 0 && r.stdout ? r.stdout : null
+}
+
+// The COMMIT a remote tag names, or null if the remote has no such tag.
+//
+// An ANNOTATED tag is an object in its own right, so `ls-remote refs/tags/v1.5.0` returns
+// the tag object's SHA, not the commit's. The commit only appears on the `^{}` deref line,
+// and an exact-ref pattern does not match it — so both patterns must be requested. Compare
+// the wrong one and every resume looks like a SHA conflict ("that version is burned") on a
+// tag that is in fact correct. A lightweight tag has no deref line; its row is the commit.
+export function remoteTagSha(remote, tag, run = git) {
+  const out = run(['ls-remote', '--tags', remote, `refs/tags/${tag}`, `refs/tags/${tag}^{}`], { allowFail: true }).stdout
+  if (!out) return null
+  const rows = out.split('\n').filter(Boolean).map((l) => l.split(/\s+/))
+  const deref = rows.find(([, ref]) => ref === `refs/tags/${tag}^{}`)
+  const exact = rows.find(([, ref]) => ref === `refs/tags/${tag}`)
+  const row = deref || exact
+  return row ? row[0] : null
+}
+
+// Push ONE annotated tag ref, hook-safe.
+//
+// Tags are not stack commits. A Mergify stacks pre-push hook that rewrites `git push` into
+// `mergify stack push` is correct for branch heads and wrong for `refs/tags/*` — the tag is
+// an immutable release artifact, not a stack-managed commit, and identity-v0.4.1's production
+// cut stalled until the operator rediscovered `git push --no-verify origin refs/tags/…`.
+// Always push the fully-qualified tag ref with `--no-verify` so a tag mint never depends on
+// that rediscovery. Branch pushes are outside this helper on purpose.
+export function pushTag(remote, tag, run = git) {
+  return run(['push', '--no-verify', remote, `refs/tags/${tag}`], { allowFail: true })
+}
+
+// Resolve the production branch against a FRESH remote tip before ancestry checks.
+//
+// `rc`/`tag` ask "is this the ship SHA?" by testing ancestry of the production branch. A
+// local `main` that has not been fetched since the promotion landed is the wrong answer to
+// that question — identity-v0.4.1 refused a SHA that was already on `origin/main` because the
+// local tip was stale. When a remote is configured: fetch `<remote> <branch>` first and
+// resolve against `origin/<branch>` (or the already-qualified remote-tracking form the
+// operator passed). Never use a potentially stale local branch tip for the ship-SHA check
+// in a clone that has a remote. A failed fetch fails closed — a pre-existing remote-tracking
+// ref is not a fresh tip, so returning it with `fetched: false` is the same class of wrong
+// answer. A remote-less throwaway clone (unit tests) falls back to the local ref only
+// because there is no remote tip to prefer.
+export function resolveProductionAncestryRef(production, remote = 'origin', run = git) {
+  if (typeof production !== 'string' || production.length === 0) {
+    return { error: 'production branch is required for the ancestry check' }
+  }
+  const remotePrefix = `${remote}/`
+  const branch = production.startsWith(remotePrefix)
+    ? production.slice(remotePrefix.length)
+    : production.startsWith('refs/remotes/' + remotePrefix)
+      ? production.slice(('refs/remotes/' + remotePrefix).length)
+      : production
+  if (!branch || branch.includes('..')) {
+    return { error: `production branch "${production}" is not a usable ref name` }
+  }
+  const remotes = (run(['remote'], { allowFail: true }).stdout || '')
+    .split('\n')
+    .map((s) => s.trim())
+    .filter(Boolean)
+  const hasRemote = remotes.includes(remote)
+  const remoteRef = `${remote}/${branch}`
+
+  if (hasRemote) {
+    // `git fetch origin main` only writes FETCH_HEAD — it does NOT update origin/main. The
+    // explicit refspec is what makes the remote-tracking tip the one we then ancestry-check.
+    // `--no-tags` is load-bearing: without it, fetch auto-follows remote tags that happen to
+    // point at commits already in the local object store (e.g. a burned vX.Y.Z on another
+    // SHA), which would re-create a local tag the burn path just deleted and then mint past.
+    const fetch = run(
+      ['fetch', '--quiet', '--no-tags', remote, `refs/heads/${branch}:refs/remotes/${remote}/${branch}`],
+      { allowFail: true },
+    )
+    // Fail closed on a failed fetch. A pre-existing origin/<branch> tip may be stale, and
+    // shipping against it is exactly the class of wrong answer this helper exists to stop
+    // (identity-v0.4.1). Never return { ref: remoteRef, fetched: false }.
+    if (fetch.status !== 0) {
+      return {
+        error:
+          `could not fetch ${remote} ${branch}: ${fetch.stderr || 'fetch failed'}. ` +
+          `Refusing to mint against a potentially stale remote-tracking "${remoteRef}" — ` +
+          `fetch ${remote} ${branch} (or pass --production-branch ${remoteRef}) and re-run.`,
+      }
+    }
+    const remoteOk = run(['rev-parse', '--verify', '--quiet', `${remoteRef}^{commit}`], { allowFail: true })
+    if (remoteOk.status === 0 && remoteOk.stdout) {
+      return { ref: remoteRef, branch, fetched: true }
+    }
+    // Fetch claimed success but the remote-tracking tip is still unusable — refuse rather
+    // than fall through to a local tip that is exactly the stale state we stop trusting.
+    return {
+      error:
+        `remote-tracking ref "${remoteRef}" does not resolve after fetch. ` +
+        `Refusing to mint against a potentially stale local "${production}" — ` +
+        `fetch ${remote} ${branch} (or pass --production-branch ${remoteRef}) and re-run.`,
+    }
+  }
+
+  // No remote configured: only the local ref exists. Unit-test clones hit this path.
+  const localOk = run(['rev-parse', '--verify', '--quiet', `${production}^{commit}`], { allowFail: true })
+  if (localOk.status === 0 && localOk.stdout) {
+    return { ref: production, branch, fetched: false, localOnly: true }
+  }
+  return {
+    error:
+      `production branch "${production}" does not resolve, and no remote "${remote}" is configured ` +
+      `to fetch from. Pass a resolvable ref (e.g. ${remoteRef}) after fetching.`,
+  }
+}
+
+// Push the tag unless the remote already agrees. Returns {pushed, error}.
+//
+// The local tag existing is NOT evidence the remote has it: `git tag` then `git push` is
+// two steps, and a run interrupted between them leaves a local-only tag. A resume that
+// short-circuits on "local tag exists" would never push — and a later `gh release create`
+// would then mint the remote tag at the default branch's HEAD, a DIFFERENT commit. So the
+// resume path reconciles the remote rather than assuming it.
+export function ensureRemoteTag(remote, tag, sha, run = git) {
+  const remoteSha = remoteTagSha(remote, tag, run)
+  if (remoteSha === sha) return { pushed: false }
+  if (remoteSha != null) {
+    return { error: `${tag} exists on ${remote} at ${remoteSha.slice(0, 8)}, not ${sha.slice(0, 8)} — that version is burned; take the next patch.` }
+  }
+  const pushed = pushTag(remote, tag, run)
+  if (pushed.status !== 0) {
+    return { error: `could not push ${tag} to ${remote}: ${pushed.stderr}` }
+  }
+  return { pushed: true }
+}
+
+// ---- CLI ----
+
+function parseArgs(argv) {
+  const opts = {}
+  const positional = []
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith('--')) {
+      const key = a.slice(2)
+      const next = argv[i + 1]
+      if (next === undefined || next.startsWith('--')) opts[key] = true
+      else {
+        opts[key] = next
+        i++
+      }
+    } else positional.push(a)
+  }
+  return { opts, positional }
+}
+
+function emitTagResult(opts, { tag, sha, pushed = false, resumed = false }) {
+  const result = { tag, sha, pushed, resumed }
+  console.log(opts.json ? JSON.stringify(result, null, 2) : tag)
+}
+
+function emitChangelogPlan(opts, { version, file, noop, markdown }) {
+  if (opts.format === 'json') {
+    console.log(JSON.stringify({ version, file, noop, markdown }, null, 2))
+  } else {
+    process.stdout.write(markdown)
+  }
+}
+
+// Every parse here is a place an operator hands us text, so every one is a place they can hand us
+// the wrong text. Bare `JSON.parse` reported that as a V8 stack trace: pi session 019faea6 hit
+// `SyntaxError: Unexpected end of JSON input at readChanges (version.mjs:439)`, which names the
+// line that threw and nothing anyone can act on. It does not say WHICH input was bad (file,
+// literal, stdin), what its path was, or that "empty" is the likely cause. Mid-release that reads
+// as "the release tooling is broken" rather than "your --changes file is empty", and the
+// difference decides whether the next move is a one-line fix or an escalation.
+//
+// So each source names itself in the refusal — the same reason `preflight-probes.mjs` quotes a
+// tool's own refusal id rather than paraphrasing it: the diagnosis has to survive to the person
+// reading the error.
+export function parseChangesJson(text, source) {
+  const trimmed = String(text ?? '').trim()
+  if (trimmed.length === 0) {
+    throw new Error(`version: ${source} is empty — expected a JSON array of changes ('[]' means none, which is not the same as an empty file)`)
+  }
+  let parsed
+  try {
+    parsed = JSON.parse(trimmed)
+  } catch (error) {
+    throw new Error(`version: ${source} is not valid JSON (${error.message}); expected a JSON array of changes`)
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error(`version: ${source} parsed as ${parsed === null ? 'null' : typeof parsed}, not an array — --changes takes a JSON array of changes`)
+  }
+  return parsed
+}
+
+function readChanges(opts) {
+  const raw = opts.changes
+  if (!raw || raw === true) return []
+  if (raw === '-' || opts.stdin) return parseChangesJson(fs.readFileSync(0, 'utf8'), 'stdin (--changes -)')
+  if (raw.trim().startsWith('[')) return parseChangesJson(raw, 'the --changes literal')
+  let text
+  try {
+    text = fs.readFileSync(raw, 'utf8')
+  } catch (error) {
+    // A missing or unreadable path is its own diagnosis; reporting it as bad JSON sends the
+    // operator to inspect a file that is not there.
+    throw new Error(`version: --changes file ${JSON.stringify(raw)} could not be read (${error.code || error.message})`)
+  }
+  return parseChangesJson(text, `--changes file ${JSON.stringify(raw)}`)
+}
+
+// An RC tag invokes an external production trigger. The preflight artifact is deliberately
+// checked again at the mutation boundary: a release transcript that mentions a probe is not a
+// guard if `rc` can still run without its successful record.
+export function validateRcTopologyProbe(file) {
+  if (typeof file !== 'string' || file.length === 0) {
+    return { error: 'missing --topology-probe <preflight-probes JSON>; run the tag-trigger topology probe before minting an RC' }
+  }
+  let report
+  try {
+    report = JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch (error) {
+    return { error: `could not read topology probe ${JSON.stringify(file)} (${error.code || error.message})` }
+  }
+  const topology = Array.isArray(report && report.probes)
+    ? report.probes.find((p) => p && p.id === 'rc-tag-topology')
+    : null
+  if (!report || report.ready !== true || !topology || topology.state !== 'ok') {
+    return { error: 'topology probe does not contain a ready rc-tag-topology result' }
+  }
+  for (const [field, expected] of Object.entries({
+    prodBuildTrigger: 'tag-trigger',
+    versionSource: 'TAG_NAME',
+    candidateTagSource: 'TAG_NAME',
+  })) {
+    if (topology[field] !== expected) {
+      return { error: `topology probe ${field} must be ${expected}, got ${JSON.stringify(topology[field])}` }
+    }
+  }
+  const substitutions = topology.substitutions
+  const tagMatch = substitutions && /^v?(\d+\.\d+\.\d+)-rc\.[1-9]\d*$/.exec(String(substitutions.TAG_NAME || ''))
+  if (!tagMatch || substitutions._DEPLOYED_VERSION !== tagMatch[1] || substitutions._CANDIDATE_TAG !== substitutions.TAG_NAME) {
+    return { error: 'topology probe substitutions do not prove TAG_NAME -> _DEPLOYED_VERSION (final SemVer) and _CANDIDATE_TAG (RC tag)' }
+  }
+  return { topology }
+}
+
+// Invariant 1, mechanized. Exit 3 is NORMAL — a dev release legitimately has no version.
+//
+// This FAILS CLOSED: both flags are required. A guard that is skipped by simply not
+// passing a flag is not a guard — an agent that forgets them would otherwise tag a
+// dev-only SHA, minting a version that names a commit production will never run.
+function requireProductionTarget(opts, command) {
+  const target = opts['target-branch']
+  const production = opts['production-branch']
+  if (typeof production !== 'string' || typeof target !== 'string') {
+    console.error(
+      `version: ${command} requires --target-branch <b> --production-branch <b>. ` +
+      'They decide whether this release may be versioned at all (only a production ' +
+      'promotion may), so they are never optional.',
+    )
+    return 2
+  }
+  if (target !== production) {
+    console.log(
+      JSON.stringify({
+        applicable: false,
+        target,
+        production,
+        reason:
+          `"${target}" is not the production branch ("${production}") — dev/staging releases are ` +
+          'unversioned and untagged, identified by SHA. No version, no tag, no CHANGELOG cut.',
+      }, null, 2),
+    )
+    return 3
+  }
+  return null
+}
+
+// The synopsis `--help` prints and references/versioning.md points at — the SINGLE
+// source of truth for subcommands, flags, and exit codes. The file-header contract
+// above points HERE rather than restating them, so there is no second list to drift
+// against; this text is the one that must stay accurate against the commands `main`
+// dispatches below (the doc's "run --help" pointer is only true if this exists and
+// is correct).
+const USAGE = `version — mechanized versioning / tagging / CHANGELOG helper for the release lane.
+
+Usage:
+  version plan       <branch-flags> [--changes <json>] [--current <v>] [--strict]
+  version changelog  <branch-flags> --version <v> --date <iso> [--changes <json>] [--repo owner/name] [--include-internal] [--file CHANGELOG.md] [--dry-run --format markdown|json]
+  version rc         <branch-flags> --version <v> --sha <sha> [--push] [--remote origin] [--message <msg>] [--dry-run] [--json]
+  version tag        <branch-flags> --version <v> --sha <sha> [--push] [--remote origin] [--message <msg>] [--dry-run] [--json]
+  version verify     --version <v> --sha <sha> [--live-sha <sha>]
+  version notes      --version <v> [--file CHANGELOG.md]
+  version withdraw   --version <v> [--incident <ref>] [--file CHANGELOG.md] [--dry-run]
+
+  <branch-flags>   --target-branch <b> --production-branch <b>   (both REQUIRED on plan|changelog|rc|tag)
+  --changes <json> JSON array of { pr, title, labels?, body?, issues? }; "-" reads stdin.
+                   Optional: absent means an empty change set (plan then bumps a patch; changelog
+                   cuts a section from only the accumulated Unreleased body).
+  --include-internal  keep internal-typed entries (chore/docs/…) in the cut, normally excluded.
+  --message <msg>  annotation for the tag object minted by rc|tag (default "Release[ candidate] <tag>").
+  --retry-from <rc-tag>  mint the next immutable RC after this exact failed RC, even when it
+                   names the same SHA. A repeated invocation resumes the resulting retry tag.
+  --topology-probe <file> required on rc: JSON output from preflight-probes check, proving the
+                   production tag trigger derives final SemVer and candidate tag from TAG_NAME.
+  --tag-prefix <p> default "v"     --strict  disable the 0.x bump convention
+  --json           rc|tag: emit {tag, sha, pushed, resumed}; default stdout is only the tag.
+  --dry-run        supported on changelog|rc|tag|withdraw: print the declared result, touch nothing.
+  --format <mode>  changelog --dry-run output: markdown emits the complete planned file; json emits
+                   {version, file, noop, markdown}. Payloads use stdout; diagnostics use stderr.
+                   A changelog dry-run requires an explicit format; --file - reads stdin and is
+                   rejected outside dry-run mode.
+
+Exit codes (each has exactly one meaning — an agent branches on them):
+  0  desired state reached, including idempotent no-ops (re-cut, same-SHA re-tag, already-withdrawn)
+  1  violation or error — tag collision, immutable-tag conflict, a SHA not an ancestor of production,
+     unresolvable production ref, an invalid baseline (--current is not a semver tag), a verify against
+     a tag that does not exist, tag/live-SHA mismatch, notes/withdraw with no CHANGELOG file,
+     notes requested for a version never cut, or a rejected rc push (lost race; the local tag is rolled back)
+  2  usage — a required flag is missing (both branch flags fail closed), an unknown command,
+     or a --sha that resolves to no commit in this repo
+  3  not a production promotion — no version, tag, or CHANGELOG cut to make (normal on a dev release)
+
+Doctrine (bump rules, the CHANGELOG's two zones, the burn case): references/versioning.md.`
+
+export function main(argv) {
+  const { opts, positional } = parseArgs(argv)
+  const cmd = positional[0]
+  const prefix = typeof opts['tag-prefix'] === 'string' ? opts['tag-prefix'] : 'v'
+  const file = typeof opts.file === 'string' ? opts.file : 'CHANGELOG.md'
+
+  if (cmd === 'help' || cmd === '-h' || opts.help || opts.h) {
+    console.log(USAGE)
+    return 0
+  }
+  if (opts.json && !['rc', 'tag'].includes(cmd)) {
+    console.error('version: --json is only valid for rc|tag.')
+    return 2
+  }
+  if (opts.format && (cmd !== 'changelog' || !opts['dry-run'])) {
+    console.error('version: --format is only valid with changelog --dry-run.')
+    return 2
+  }
+
+  switch (cmd) {
+    case 'plan': {
+      const gate = requireProductionTarget(opts, 'plan')
+      if (gate !== null) return gate
+
+      const changes = readChanges(opts)
+      let currentTag = typeof opts.current === 'string' ? opts.current : null
+      if (!currentTag) {
+        // The baseline is the highest release tag reachable from the PRODUCTION branch —
+        // never from HEAD. `plan` runs at the pre-flight gate, where HEAD is whatever the
+        // human had checked out (often a feature branch forked before the last release).
+        // Reading HEAD there silently misses the released tags and proposes a version
+        // BELOW one that already exists — and the collision check cannot catch it, because
+        // the too-low version is genuinely free. Version numbers would go backwards.
+        const branch = opts['production-branch']
+        if (git(['rev-parse', '--verify', '--quiet', `${branch}^{commit}`], { allowFail: true }).status !== 0) {
+          // Silence here is the same regression by another route: an unresolvable ref makes
+          // `--merged` find no tags, and a 0.0.0 baseline looks exactly like a first release.
+          console.error(`version: production branch "${branch}" does not resolve. Fetch it, or pass the ref that exists (e.g. origin/main).`)
+          return 1
+        }
+        const tags = git(['tag', '--list', `${prefix}*`, '--merged', branch], { allowFail: true }).stdout
+        const latest = latestReleaseTag(tags ? tags.split('\n').filter(Boolean) : [])
+        currentTag = latest ? latest.tag : `${prefix}0.0.0`
+      }
+      const current = parseSemver(currentTag)
+      if (!current) {
+        console.error(`version: "${currentTag}" is not a semver release tag.`)
+        return 1
+      }
+
+      const { bump, reason } = bumpFor(changes, current, { strict: Boolean(opts.strict) })
+      const next = nextVersion(current, bump)
+      const tag = tagName(next, prefix)
+      // Deliberately an EXACT-ref check, so `v1.5.0-rc.3` does not block `v1.5.0`. The rcs
+      // are this release's own deploy triggers — the candidates for exactly this version.
+      // Treating them as a collision would make every retried release skip a version.
+      const collision = tagExists(tag)
+
+      console.log(
+        JSON.stringify({
+          applicable: true,
+          current: formatVersion(current),
+          bump,
+          reason,
+          next: formatVersion(next),
+          tag,
+          collision,
+          changes: changes.map(classifyChange).map((c) => ({
+            pr: c.pr, type: c.type, breaking: c.breaking, section: c.section, summary: c.summary,
+          })),
+        }, null, 2),
+      )
+      // A collision means this version already reached the repo — burned, or already cut.
+      // Never silently bump past it: the human decides (resume vs. next patch).
+      return collision ? 1 : 0
+    }
+
+    case 'changelog': {
+      const gate = requireProductionTarget(opts, 'changelog')
+      if (gate !== null) return gate
+      if (typeof opts.version !== 'string' || typeof opts.date !== 'string') {
+        console.error('version: changelog requires --version <v> --date <YYYY-MM-DD>')
+        return 2
+      }
+      if (opts['dry-run'] && !['markdown', 'json'].includes(opts.format)) {
+        console.error('version: changelog --dry-run requires --format markdown|json.')
+        return 2
+      }
+      const section = renderChangelogSection({
+        version: opts.version,
+        date: opts.date,
+        changes: readChanges(opts),
+        repo: typeof opts.repo === 'string' ? opts.repo : null,
+        includeInternal: Boolean(opts['include-internal']),
+      })
+      if (file === '-' && !opts['dry-run']) {
+        console.error('version: changelog --file - requires --dry-run.')
+        return 2
+      }
+      const existing = file === '-'
+        ? fs.readFileSync(0, 'utf8')
+        : (fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '')
+      const { text, noop } = insertSection(existing, section, opts.version)
+      if (noop) {
+        if (opts['dry-run']) emitChangelogPlan(opts, { version: opts.version, file, noop, markdown: text })
+        // Exit 0, not 3: the desired state is already reached, exactly like a same-SHA
+        // re-tag. Exit 3 means ONLY "not a production promotion" — overloading it here
+        // would make a resuming agent read "already cut" as "skip versioning entirely".
+        console.error(`version: [${opts.version}] already in ${file} — nothing to cut (resume).`)
+        return 0
+      }
+      if (opts['dry-run']) emitChangelogPlan(opts, { version: opts.version, file, noop, markdown: text })
+      else fs.writeFileSync(file, text)
+      return 0
+    }
+
+    case 'notes': {
+      if (typeof opts.version !== 'string') {
+        console.error('version: notes requires --version <v>')
+        return 2
+      }
+      if (!fs.existsSync(file)) {
+        console.error(`version: no ${file}`)
+        return 1
+      }
+      const section = extractSection(fs.readFileSync(file, 'utf8'), opts.version)
+      if (!section) {
+        // An error, not "nothing to do": the caller is about to publish release notes and
+        // there are none. Better to fail than to create an empty GitHub Release.
+        console.error(`version: no [${opts.version}] section in ${file}`)
+        return 1
+      }
+      console.log(section)
+      return 0
+    }
+
+    case 'withdraw': {
+      if (typeof opts.version !== 'string') {
+        console.error('version: withdraw requires --version <v> [--incident <ref>]')
+        return 2
+      }
+      if (!fs.existsSync(file)) {
+        console.error(`version: no ${file}`)
+        return 1
+      }
+      const { text, noop, reason } = markWithdrawn(fs.readFileSync(file, 'utf8'), opts.version, opts.incident)
+      if (noop) {
+        // Already withdrawn → desired state, exit 0. No such section → nothing was ever
+        // cut for that version (the tag-after-verify path), which is also correct: exit 0.
+        console.error(`version: not withdrawn (${reason}).`)
+        return 0
+      }
+      if (opts['dry-run']) console.log(text)
+      else fs.writeFileSync(file, text)
+      return 0
+    }
+
+    case 'rc': {
+      const gate = requireProductionTarget(opts, 'rc')
+      if (gate !== null) return gate
+      if (typeof opts.version !== 'string' || typeof opts.sha !== 'string') {
+        console.error('version: rc requires --version <v> --sha <sha>')
+        return 2
+      }
+      const base = tagName(opts.version, prefix)
+      const sha = resolveSha(opts.sha)
+      if (sha == null) {
+        console.error(`version: --sha "${opts.sha}" does not resolve to a commit in this repo.`)
+        return 2
+      }
+      const topologyProbe = validateRcTopologyProbe(opts['topology-probe'])
+      if (topologyProbe.error) {
+        console.error(`version: refusing to mint an RC: ${topologyProbe.error}`)
+        return 1
+      }
+      const remote = typeof opts.remote === 'string' ? opts.remote : 'origin'
+      const listed = git(['tag', '--list', `${base}-rc.*`], { allowFail: true }).stdout
+      const existing = rcTags(listed ? listed.split('\n').filter(Boolean) : [], base)
+      const retryFrom = typeof opts['retry-from'] === 'string' ? opts['retry-from'] : null
+      const retryFromShape = retryFrom == null ? null : rcTags([retryFrom], base)[0] || null
+      if (retryFrom != null && retryFromShape == null) {
+        console.error(`version: --retry-from ${JSON.stringify(retryFrom)} is not an RC tag for ${base}.`)
+        return 2
+      }
+
+      // Resume safety. Pushing an rc FIRES the production pipeline, so "have I already
+      // minted one?" is not a cosmetic question: a resumed session that minted rc.4, rc.5,
+      // rc.6 for one unchanged SHA would deploy the same artifact three more times. An rc
+      // already naming this exact SHA is the desired state — say so and stop. The exception
+      // is an explicit retry of a terminal failed attempt: it receives a fresh immutable RC.
+      const at = existing.filter((x) => shaForTag(x.tag) === sha)
+      const localRetryFrom = retryFrom == null ? null : existing.find((x) => x.tag === retryFrom) || null
+      if (localRetryFrom != null && shaForTag(localRetryFrom.tag) !== sha) {
+        console.error(`version: --retry-from ${retryFrom} does not name ${sha.slice(0, 8)} — refusing to retry a different candidate.`)
+        return 1
+      }
+      const localRetry = localRetryFrom == null
+        ? null
+        : at.filter((x) => x.n > localRetryFrom.n).sort((a, b) => a.n - b.n)[0] || null
+      if (localRetry != null) {
+        const tag = localRetry.tag
+        let pushed = false
+        // Same convergence as `tag`: a local rc that was never pushed never deployed.
+        if (opts.push && !opts['dry-run']) {
+          const remoteSha = remoteTagSha(remote, tag)
+          if (remoteSha != null && remoteSha !== sha) {
+            console.error(
+              `version: ${tag} exists on ${remote} at ${remoteSha.slice(0, 8)}, not ${sha.slice(0, 8)}. ` +
+              'rc tags are immutable too — that number is spent; give this SHA the next one.',
+            )
+            return 1
+          }
+          if (remoteSha == null) {
+            const push = pushTag(remote, tag)
+            if (push.status !== 0) {
+              console.error(`version: could not push ${tag} to ${remote}: ${push.stderr}`)
+              return 1
+            }
+            pushed = true
+          }
+        }
+        emitTagResult(opts, { tag, sha, pushed, resumed: true })
+        console.error(`version: ${tag} already names ${sha.slice(0, 8)} — no-op (retry resume).`)
+        return 0
+      }
+      if (at.length > 0 && retryFrom == null) {
+        const tag = at[at.length - 1].tag
+        let pushed = false
+        // Same convergence as `tag`: a local rc that was never pushed never deployed.
+        if (opts.push && !opts['dry-run']) {
+          const remoteSha = remoteTagSha(remote, tag)
+          if (remoteSha != null && remoteSha !== sha) {
+            console.error(
+              `version: ${tag} exists on ${remote} at ${remoteSha.slice(0, 8)}, not ${sha.slice(0, 8)}. ` +
+              'rc tags are immutable too — that number is spent; give this SHA the next one.',
+            )
+            return 1
+          }
+          if (remoteSha == null) {
+            const push = pushTag(remote, tag)
+            if (push.status !== 0) {
+              console.error(`version: could not push ${tag} to ${remote}: ${push.stderr}`)
+              return 1
+            }
+            pushed = true
+          }
+        }
+        emitTagResult(opts, { tag, sha, pushed, resumed: true })
+        console.error(`version: ${tag} already names ${sha.slice(0, 8)} — no-op (resume).`)
+        return 0
+      }
+
+      // An rc must name a SHA that is already on the production branch — the same guard `tag`
+      // applies, and for a sharper reason. Both topologies require the merge to happen first
+      // (GitFlow merges the promotion, GitHub Flow merges the rebased release branch), so an
+      // unmerged SHA here means the order was broken. Without this, minting on an unmerged
+      // branch fires a real production build and deploys a candidate that `tag` will later
+      // refuse — the contradiction surfacing only at step 5, with traffic already shifted,
+      // live on an artifact that cannot be tagged. Fail now, while it is still a no-op.
+      // Resolve against a freshly-fetched remote tip — a stale local main is not "the ship SHA".
+      {
+        const production = opts['production-branch']
+        if (typeof production === 'string') {
+          const resolved = resolveProductionAncestryRef(production, remote)
+          if (resolved.error) {
+            console.error(`version: ${resolved.error}`)
+            return 1
+          }
+          const ok = git(['merge-base', '--is-ancestor', sha, resolved.ref], { allowFail: true }).status === 0
+          if (!ok) {
+            console.error(
+              `version: ${sha.slice(0, 8)} is not an ancestor of ${resolved.ref} — refusing to mint an rc. ` +
+              'Merge the promotion first; the rc names the SHA that will ship, not one that might.',
+            )
+            return 1
+          }
+        }
+      }
+
+      // Everything below only matters when we intend to push, because only a pushed rc
+      // fires a deploy. Without --push this stays a purely local operation.
+      const willPush = Boolean(opts.push) && !opts['dry-run']
+      const remoteRcs = willPush ? remoteRcTags(remote, base) : []
+
+      // The same resume the local branch above handles, but across clones: a session that
+      // died after pushing rc.2 resumes on a machine whose checkout never fetched it. The
+      // artifact for this SHA is already built and already deployed — minting rc.3 would
+      // deploy it a second time, which is exactly what the resume guard exists to prevent.
+      const remoteAt = remoteRcs.filter((x) => x.sha === sha)
+      const remoteRetryFrom = retryFrom == null ? null : remoteRcs.find((x) => x.tag === retryFrom) || null
+      if (retryFrom != null && localRetryFrom == null && remoteRetryFrom == null) {
+        console.error(`version: --retry-from ${retryFrom} does not exist locally or on ${remote}.`)
+        return 1
+      }
+      if (remoteRetryFrom != null && remoteRetryFrom.sha !== sha) {
+        console.error(`version: --retry-from ${retryFrom} on ${remote} does not name ${sha.slice(0, 8)} — refusing to retry a different candidate.`)
+        return 1
+      }
+      const remoteRetry = remoteRetryFrom == null
+        ? null
+        : remoteAt.filter((x) => x.n > remoteRetryFrom.n).sort((a, b) => a.n - b.n)[0] || null
+      if (remoteRetry != null) {
+        emitTagResult(opts, { tag: remoteRetry.tag, sha, resumed: true })
+        console.error(`version: ${remoteRetry.tag} already names ${sha.slice(0, 8)} on ${remote} — no-op (retry resume from another clone).`)
+        return 0
+      }
+      if (remoteAt.length > 0 && retryFrom == null) {
+        const tag = remoteAt[remoteAt.length - 1].tag
+        emitTagResult(opts, { tag, sha, resumed: true })
+        console.error(`version: ${tag} already names ${sha.slice(0, 8)} on ${remote} — no-op (resume from another clone).`)
+        return 0
+      }
+
+      const highest = Math.max(0, ...existing.map((x) => x.n), ...remoteRcs.map((x) => x.n))
+      const tag = `${base}-rc.${highest + 1}`
+      const message = typeof opts.message === 'string' ? opts.message : `Release candidate ${tag}`
+      if (opts['dry-run']) {
+        emitTagResult(opts, { tag, sha })
+        console.error(`version: would tag ${sha.slice(0, 8)} as ${tag}${opts.push ? ` and push to ${remote}` : ''}.`)
+        return 0
+      }
+
+      // Belt and braces over the union numbering above: check this exact tag before writing
+      // anything local. A rejected push after a successful `git tag` is the failure mode that
+      // strands a wrong-SHA tag in the working clone, and it surfaces as a stack trace rather
+      // than a diagnosis. Fail here instead, with a sentence that says what to do.
+      if (willPush) {
+        const remoteSha = remoteTagSha(remote, tag)
+        if (remoteSha != null && remoteSha !== sha) {
+          console.error(
+            `version: ${tag} exists on ${remote} at ${remoteSha.slice(0, 8)}, not ${sha.slice(0, 8)}. ` +
+            'rc tags are immutable too — that number is spent; re-run to take the next one.',
+          )
+          return 1
+        }
+      }
+
+      git(['tag', '-a', tag, sha, '-m', message])
+      if (opts.push) {
+        const pushed = pushTag(remote, tag)
+        if (pushed.status !== 0) {
+          // Lost a race, or the remote moved between the check and the push. Undo the local
+          // tag so the clone does not keep a candidate the remote never accepted — a stale
+          // local rc silently poisons the NEXT run's numbering.
+          git(['tag', '-d', tag], { allowFail: true })
+          console.error(`version: could not push ${tag} to ${remote}: ${pushed.stderr}`)
+          return 1
+        }
+      }
+      emitTagResult(opts, { tag, sha, pushed: Boolean(opts.push) })
+      return 0
+    }
+
+    case 'tag': {
+      const gate = requireProductionTarget(opts, 'tag')
+      if (gate !== null) return gate
+      if (typeof opts.version !== 'string' || typeof opts.sha !== 'string') {
+        console.error('version: tag requires --version <v> --sha <sha>')
+        return 2
+      }
+      const tag = tagName(opts.version, prefix)
+      const sha = resolveSha(opts.sha)
+      if (sha == null) {
+        console.error(`version: --sha "${opts.sha}" does not resolve to a commit in this repo.`)
+        return 2
+      }
+      const remote = typeof opts.remote === 'string' ? opts.remote : 'origin'
+
+      // Invariant 2: a tag is immutable. Same SHA → resume-safe no-op. Different SHA → stop.
+      if (tagExists(tag)) {
+        const at = shaForTag(tag)
+        if (at !== sha) {
+          console.error(
+            `version: ${tag} already exists at ${at.slice(0, 8)}, not ${sha.slice(0, 8)}. ` +
+            'Tags are immutable and are never moved or deleted. If that release was rolled back, ' +
+            'the version is burned — take the next patch (references/versioning.md).',
+          )
+          return 1
+        }
+        // Resume, but CONVERGE: a local tag is no evidence the remote has it.
+        if (opts.push && !opts['dry-run']) {
+          const { pushed, error } = ensureRemoteTag(remote, tag, sha)
+          if (error) {
+            console.error(`version: ${error}`)
+            return 1
+          }
+          emitTagResult(opts, { tag, sha, pushed, resumed: true })
+          return 0
+        }
+        emitTagResult(opts, { tag, sha, resumed: true })
+        console.error(`version: ${tag} already points at ${sha.slice(0, 8)} — no-op (resume).`)
+        return 0
+      }
+
+      // A tag must name a SHA that is actually on the production branch — against a freshly
+      // fetched remote tip, never a potentially stale local branch (identity-v0.4.1).
+      const production = opts['production-branch']
+      if (typeof production === 'string') {
+        const resolved = resolveProductionAncestryRef(production, remote)
+        if (resolved.error) {
+          console.error(`version: ${resolved.error}`)
+          return 1
+        }
+        const ok = git(['merge-base', '--is-ancestor', sha, resolved.ref], { allowFail: true }).status === 0
+        if (!ok) {
+          console.error(`version: ${sha.slice(0, 8)} is not an ancestor of ${resolved.ref} — refusing to tag.`)
+          return 1
+        }
+      }
+
+      const message = typeof opts.message === 'string' ? opts.message : `Release ${tag}`
+      if (opts['dry-run']) {
+        emitTagResult(opts, { tag, sha })
+        console.error(`version: would tag ${sha.slice(0, 8)} as ${tag}${opts.push ? ` and push to ${remote}` : ''}.`)
+        return 0
+      }
+
+      // The remote is the source of truth for "was this version published?" — check before
+      // minting a local tag that could never be pushed anyway.
+      if (opts.push) {
+        const remoteSha = remoteTagSha(remote, tag)
+        if (remoteSha != null && remoteSha !== sha) {
+          console.error(`version: ${tag} exists on ${remote} at ${remoteSha.slice(0, 8)} — that version is burned; take the next patch.`)
+          return 1
+        }
+      }
+
+      git(['tag', '-a', tag, sha, '-m', message])
+      if (opts.push) {
+        const pushed = pushTag(remote, tag)
+        if (pushed.status !== 0) {
+          git(['tag', '-d', tag], { allowFail: true })
+          console.error(`version: could not push ${tag} to ${remote}: ${pushed.stderr}`)
+          return 1
+        }
+      }
+      emitTagResult(opts, { tag, sha, pushed: Boolean(opts.push) })
+      return 0
+    }
+
+    case 'verify': {
+      if (typeof opts.version !== 'string' || typeof opts.sha !== 'string') {
+        console.error('version: verify requires --version <v> --sha <shipped-sha>')
+        return 2
+      }
+      const tag = tagName(opts.version, prefix)
+      if (!tagExists(tag)) {
+        console.error(`version: ${tag} does not exist.`)
+        return 1
+      }
+      const at = shaForTag(tag)
+      const sha = resolveSha(opts.sha)
+      if (sha == null) {
+        console.error(`version: --sha "${opts.sha}" does not resolve to a commit in this repo.`)
+        return 2
+      }
+      const live = typeof opts['live-sha'] === 'string' ? git(['rev-parse', opts['live-sha']], { allowFail: true }).stdout || opts['live-sha'] : null
+
+      const tagMatches = at === sha
+      const liveMatches = live == null ? null : live === sha
+      console.log(JSON.stringify({ tag, tagSha: at, shippedSha: sha, liveSha: live, tagMatches, liveMatches }, null, 2))
+      if (!tagMatches) {
+        console.error(`version: ${tag} names ${at.slice(0, 8)}, but the shipped SHA is ${sha.slice(0, 8)}.`)
+        return 1
+      }
+      if (liveMatches === false) {
+        console.error(`version: the live revision (${live.slice(0, 8)}) is not the promoted SHA (${sha.slice(0, 8)}).`)
+        return 1
+      }
+      return 0
+    }
+
+    default:
+      console.error('version: unknown command. Use plan|changelog|notes|withdraw|rc|tag|verify (see --help).')
+      return 2
+  }
+}
+
+// Only run the CLI when invoked directly (so tests can import the pure functions).
+//
+// The catch is not decoration. A refusal thrown out of `main` reaches the operator as a V8 stack
+// trace with the message buried in the middle of it, which is what pi session 019faea6 saw and
+// read as "the release tooling is broken". A refusal is a designed outcome of this tool, so it
+// exits like one: the message on stderr, exit 2, no stack. Genuine bugs are the other case and
+// still owe their stack, so an error carrying no message — or one raised before the operator's
+// input was even read — prints in full rather than being flattened into a tidy one-liner that
+// hides where it came from.
+if (isMainModule(import.meta.url)) {
+  try {
+    process.exit(main(process.argv.slice(2)))
+  } catch (error) {
+    const message = error && typeof error.message === 'string' ? error.message : ''
+    if (message.startsWith('version: ')) {
+      console.error(message)
+      process.exit(2)
+    }
+    throw error
+  }
+}