@entro314labs/release-kit 2.7.0 → 2.9.0

package/release.mjs

@@ -37,6 +37,7 @@ import {
   existsSync,
   mkdirSync,
   mkdtempSync,
+  readdirSync,
   readFileSync,
   writeFileSync,
 } from 'node:fs'
@@ -61,9 +62,16 @@ import { createInterface } from 'node:readline/promises'
  *   versionFile     string|object|null  where the project's version lives. Detected from
  *                            the repository when unset; null when it versions by tag alone
  *   versionFiles    array    further files whose version is kept in sync; each is a path
- *                            or { path, pattern }
- *   publish         string   publish command. Detected from the version source when unset,
- *                            and only where it is unambiguous; null to publish nothing
+ *                            or { path, pattern }. Written even where versionFile is null,
+ *                            which is how a language with no version of its own — a Go
+ *                            module — keeps one in source. When neither this nor
+ *                            versionFile is configured, a second root manifest and a
+ *                            conventional version constant already on the same version are
+ *                            detected and kept in step
+ *   publish         string|string[]  publish command, or several for a project that
+ *                            releases to more than one registry. Detected from the version
+ *                            sources when unset, and only where unambiguous; null to
+ *                            publish nothing
  *   commitMessage   string   release commit subject
  *   releaseTitle    string   GitHub release title
  *   assets          string[] files attached to the GitHub release
@@ -77,6 +85,9 @@ import { createInterface } from 'node:readline/promises'
  *                            release commits, merges, work-in-progress, autosquash markers
  *   versioning      string   how `auto` derives a bump: "conventional", or
  *                            always-patch / always-minor / always-major to never infer
+ *   verify          string   command run during preflight — a project's own gate (tests,
+ *                            build). Non-zero aborts before anything mutates, instead of a
+ *                            prepublishOnly hook failing after the commit, tag and push
  *   assistant       string|object  drafting CLI for commit messages and notes. A key of
  *                            ASSISTANTS, "auto" for the first available, or null. The
  *                            object form { tool, model, effort } also pins which model and
@@ -88,11 +99,11 @@ import { createInterface } from 'node:readline/promises'
  * committing, is a mistake the tool should not let you express.
  *
  *   commit     commit a dirty working tree (opt-in; touches work that predates the release)
- *   version    write the version into package.json and versionFiles
+ *   version    write the version into the version source and versionFiles
  *   changelog  roll [Unreleased] into the version, or add drafted notes
  *   tag        annotated git tag carrying the release notes
  *   push       push the branch and the tag together
- *   publish    run the configured publish command
+ *   publish    run the configured publish command(s), in order
  *   release    create the GitHub release
  *
  * `version` and `changelog` write files; those writes are persisted by a release commit
@@ -130,8 +141,25 @@ const DEFAULTS = {
     '^wip\\b',
     '^(fixup|squash)!',
   ],
+  verify: null,
+  hooks: {},
 }
 
+/**
+ * The points a project can hang its own commands on, in the order they run.
+ *
+ * `verify` already covers the one gate that matters most — the project's own tests, run
+ * during preflight before anything mutates. What it cannot express is work that has to
+ * happen *between* the release's own steps: regenerating a file derived from the version,
+ * building an artefact the publish command expects to find, telling something downstream
+ * that a release landed.
+ *
+ * They are command lines rather than callbacks because the config is JSON, and they take
+ * the same `%v` `%t` `%n` `%d` tokens the publish command does. A non-zero exit aborts the
+ * release exactly where it happened, which is the point of running them there.
+ */
+const HOOKS = ['beforeVersion', 'afterVersion', 'beforePublish', 'afterPublish', 'afterRelease']
+
 /**
  * Prerelease identifiers that map to their own npm dist-tag. An identifier outside this
  * set has no safe home, so `distTagFor` refuses rather than letting a prerelease fall
@@ -161,6 +189,17 @@ Target (optional; defaults to the version already in package.json):
 Steps, in the fixed order they run. All but "commit" run by default:
   ${STEPS.join('  ')}
 
+Subcommands (they check, print or copy, and never start a release):
+  next [<version>|<bump>]
+                       print the version that target would release, and stop.
+                       Only the version reaches stdout, so it substitutes:
+                       VERSION=$(release-kit next auto)
+  lint-commits [<range>]
+                       check commit subjects against Conventional Commits
+                       (default range: since the last tag)
+  lint-commits --subject <text>
+                       check one subject — a pull request title before it is squashed
+
 Flags:
   --only <steps>       run only these steps, comma-separated
   --skip <steps>       run every step except these
@@ -199,9 +238,20 @@ const yellow = (s) => paint('33', s)
 
 let stepNumber = 0
 const step = (title) => console.log(`\n${bold(`[${++stepNumber}] ${title}`)}`)
-const ok = (message) => console.log(`  ${green('ok')}   ${message}`)
-const warn = (message) => console.log(`  ${yellow('warn')} ${message}`)
-const note = (message) => console.log(`  ${dim(message)}`)
+/**
+ * `next` exists to be substituted into a shell command, so its stdout must carry the
+ * version and nothing else. Everything the release would narrate still gets said — on
+ * stderr, where a human reads it and `$(...)` does not.
+ */
+const PRINT_ONLY = process.argv[2] === 'next'
+const say = (line) => {
+  if (PRINT_ONLY) process.stderr.write(`${line}\n`)
+  else console.log(line)
+}
+
+const ok = (message) => say(`  ${green('ok')}   ${message}`)
+const warn = (message) => say(`  ${yellow('warn')} ${message}`)
+const note = (message) => say(`  ${dim(message)}`)
 const indent = (text) =>
   text
     .split('\n')
@@ -223,8 +273,8 @@ const formatStatus = (porcelain) =>
     })
     .join('\n')
 
-function abort(message) {
-  console.log(`\n${red(bold('RELEASE ABORTED'))} — ${message}\n`)
+function abort(message, title = 'RELEASE ABORTED') {
+  console.log(`\n${red(bold(title))} — ${message}\n`)
   process.exit(1)
 }
 
@@ -400,29 +450,120 @@ function runAssistant(prompt) {
   }
 }
 
-/** Commit subjects since the last tag, with release and merge commits filtered out. */
-function commitsSinceLastTag() {
+/**
+ * The repository's release tags that are reachable from HEAD, highest version first.
+ *
+ * `git describe --tags --abbrev=0` answers a different question — "the nearest tag of any
+ * kind" — and it is wrong in two ways that were both observed. A repository carrying tags
+ * that are not releases gets one of those as its baseline: a single rolling `latest-beta`
+ * marker, which tauri-release-kit maintains for its update channels, made a release abort
+ * with "no releasable commits since latest-beta". And "nearest ancestor" is not "latest
+ * release": a patch tagged on top of a later minor drags the baseline backwards.
+ *
+ * Only tags carrying the configured prefix and a parseable version count, and they are
+ * ordered by semver precedence rather than by position in the history. `--merged HEAD`
+ * keeps a tag made on another branch out of this branch's history, and degrades correctly
+ * in a shallow clone: a tag whose commit was not fetched is simply not listed.
+ *
+ * @returns {{name: string, version: string}[]}
+ */
+function releaseTags(prefix = config.tagPrefix ?? '') {
+  const listed = tryRead('git', ['tag', '--list', `${prefix}*`, '--merged', 'HEAD']) ?? ''
+  return listed
+    .split('\n')
+    .map((name) => name.trim())
+    .filter(Boolean)
+    .map((name) => ({ name, version: name.slice(prefix.length) }))
+    .filter(({ version }) => parseVersion(version))
+    .sort((a, b) => compareVersions(b.version, a.version))
+}
+
+/**
+ * The tag a release reads its history from.
+ *
+ * @param {{stable?: boolean}} [options] `stable` when the version being released has no
+ *   prerelease identifier, which rolls the release candidates leading to it up into it:
+ *   their work is what is shipping now, and reading from the last candidate describes only
+ *   the gap between the last two candidates. Promoting `2.0.0-rc.2` to `2.0.0` that way
+ *   produced empty notes, because the one commit in range was the release chore.
+ *   Releasing a candidate keeps the full ordering, so each candidate's notes say what
+ *   changed in that candidate rather than repeating the whole cycle.
+ * @returns {string | null}
+ */
+function lastReleaseTag({ stable = false, prefix } = {}) {
+  const tags = releaseTags(prefix)
+  const eligible = stable ? tags.filter(({ version }) => !parseVersion(version).pre.length) : tags
+  return eligible[0]?.name ?? null
+}
+
+/** Commit subjects since the last release tag, with release and merge commits filtered out. */
+function commitsSinceLastTag(options) {
   const ignored = (config.ignoreCommits ?? []).map((pattern) => new RegExp(pattern, 'i'))
-  const lastTag = tryRead('git', ['describe', '--tags', '--abbrev=0'])
+  const lastTag = lastReleaseTag(options)
   const range = lastTag ? `${lastTag}..HEAD` : 'HEAD'
   // %B is the whole message: bodies carry BREAKING CHANGE and Release-As footers. A record
   // separator keeps multi-line messages parseable when splitting the log back apart.
-  // %h first, then the message: the hash is what links each bullet back to its commit.
-  const raw = tryRead('git', ['log', `--format=%h%x1f%B%x1e`, range]) ?? ''
+  // %h first, then the author, then the message: the hash is what links each bullet back
+  // to its commit, and the author is what says who is new here.
+  const raw = tryRead('git', ['log', `--format=%h%x1f%an%x1f%ae%x1f%B%x1e`, range]) ?? ''
   const commits = raw
     .split('\u001E')
     .map((entry) => entry.trim())
     .filter(Boolean)
     .map((entry) => {
-      const [hash, message = ''] = entry.split('\u001F')
+      const [hash, author = '', email = '', message = ''] = entry.split('\u001F')
       const [subject, ...rest] = message.split('\n')
-      return { hash: hash.trim(), subject: subject.trim(), body: rest.join('\n').trim() }
+      return {
+        hash: hash.trim(),
+        author: author.trim(),
+        email: email.trim().toLowerCase(),
+        subject: subject.trim(),
+        body: rest.join('\n').trim(),
+      }
     })
     // Bookkeeping rather than change: the previous release's own commit, merges that
     // duplicate the branch they bring in, and markers meant to be autosquashed away.
     .filter(({ subject }) => subject && !ignored.some((re) => re.test(subject)))
   const kept = withoutRevertedCommits(commits)
-  return { lastTag, commits: kept, subjects: kept.map((c) => c.subject) }
+  return {
+    lastTag,
+    commits: kept,
+    subjects: kept.map((c) => c.subject),
+    contributors: newContributors(lastTag, kept),
+  }
+}
+
+/**
+ * The people whose first commit to this repository is in this release.
+ *
+ * git-cliff derives this from the forge's API, which needs a token, a network and a
+ * forge. The repository already knows: an author absent from every commit before the
+ * previous tag has not contributed before. That answer is exact, offline, and the same on
+ * GitHub, GitLab and a bare remote — and it degrades with a shallow clone exactly as the
+ * rest of the notes do, which is already warned about.
+ *
+ * The first release has no "before", so everyone would be new and the section would say
+ * nothing; it is skipped there.
+ *
+ * @returns {string[]} display names, GitHub handles where the email carries one
+ */
+function newContributors(lastTag, commits) {
+  if (!lastTag || !commits.length) return []
+  const before = new Set(
+    (tryRead('git', ['log', '--format=%ae', lastTag]) ?? '')
+      .split('\n')
+      .map((email) => email.trim().toLowerCase())
+      .filter(Boolean),
+  )
+  const seen = new Map()
+  for (const { author, email } of commits) {
+    if (!email || before.has(email) || seen.has(email)) continue
+    // A GitHub noreply address carries the account handle, which is what a reader can
+    // actually follow; anything else falls back to the name on the commit.
+    const handle = /^(?:\d+\+)?([^@]+)@users\.noreply\.github\.com$/.exec(email)?.[1]
+    seen.set(email, handle ? `@${handle}` : author)
+  }
+  return [...seen.values()].filter(Boolean)
 }
 
 /**
@@ -517,7 +658,7 @@ function inferBump(commits, currentVersion, strategy = 'conventional') {
  *
  * @returns {string | null} markdown body, or null when nothing visible changed
  */
-function changelogFromCommits(commits, links = null, hidden = []) {
+function changelogFromCommits(commits, links = null, hidden = [], contributors = []) {
   const parsed = commits.map((c) => parseCommit(c.subject, c.body, c.hash)).filter(Boolean)
   const lines = []
 
@@ -566,6 +707,14 @@ function changelogFromCommits(commits, links = null, hidden = []) {
     lines.push('')
   }
 
+  // Last, and only when there is something above it: a list of names is not release notes
+  // on its own, and a release with no described changes should still say so.
+  if (lines.length && contributors.length) {
+    lines.push('### New Contributors', '')
+    for (const name of contributors) lines.push(`- ${name} made their first contribution`)
+    lines.push('')
+  }
+
   return lines.length ? lines.join('\n').trim() : null
 }
 
@@ -575,11 +724,28 @@ function changelogFromCommits(commits, links = null, hidden = []) {
  * differ: Bitbucket uses /issue/ and /commits/ where GitHub uses /issues/ and /commit/.
  */
 const HOSTS = {
-  'github.com': { issue: 'issues', commit: 'commit' },
-  'gitlab.com': { issue: 'issues', commit: 'commit' },
-  'bitbucket.org': { issue: 'issue', commit: 'commits' },
+  'github.com': {
+    issue: 'issues',
+    commit: 'commit',
+    compare: 'compare/%f...%t',
+    tag: 'releases/tag/%t',
+  },
+  'gitlab.com': { issue: 'issues', commit: 'commit', compare: 'compare/%f...%t', tag: '-/tags/%t' },
+  // Bitbucket reverses the operands and separates them with two dots, and keeps tags under
+  // /commits/tag/ rather than a releases page it does not have.
+  'bitbucket.org': {
+    issue: 'issue',
+    commit: 'commits',
+    compare: 'branches/compare/%t..%f',
+    tag: 'commits/tag/%t',
+  },
+}
+const DEFAULT_HOST = {
+  issue: 'issues',
+  commit: 'commit',
+  compare: 'compare/%f...%t',
+  tag: 'releases/tag/%t',
 }
-const DEFAULT_HOST = { issue: 'issues', commit: 'commit' }
 
 /** Words that mark an issue reference as closed by the commit. */
 const CLOSES = /\b(?:close[sd]?|closing|fix(?:e[sd])?|fixing|resolve[sd]?|resolving)\s+#(\d+)/gi
@@ -600,10 +766,13 @@ function remoteLinks(remote) {
   const [, host, path] = web ?? scp ?? []
   if (!host || !path) return null
   const shape = HOSTS[host.toLowerCase()] ?? DEFAULT_HOST
+  const base = `https://${host}/${path}`
   return {
-    base: `https://${host}/${path}`,
-    issue: `https://${host}/${path}/${shape.issue}`,
-    commit: `https://${host}/${path}/${shape.commit}`,
+    base,
+    issue: `${base}/${shape.issue}`,
+    commit: `${base}/${shape.commit}`,
+    compare: (from, to) => `${base}/${shape.compare.replace('%f', from).replace('%t', to)}`,
+    tag: (name) => `${base}/${shape.tag.replace('%t', name)}`,
   }
 }
 
@@ -624,8 +793,104 @@ function withoutRevertedCommits(commits) {
   )
 }
 
-const CONVENTIONAL_TYPES = 'build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test'
-const CONVENTIONAL_RE = new RegExp(`^(${CONVENTIONAL_TYPES})(\\([^)]+\\))?!?: .+`)
+/**
+ * Semver strings a drafted message names that the staged changes never touch. The prompt
+ * forbids narrating versions, but a model can still read an unchanged `"version"` context
+ * line and describe it as work — a draft once claimed "release v1.4.5" for a commit that
+ * changed no version at all. Only added and removed lines are the change.
+ */
+function inventedVersions(message, changedLines) {
+  const versions = message.match(/\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/g) ?? []
+  return [...new Set(versions)].filter((version) => !changedLines.includes(version))
+}
+
+/**
+ * A repository URL reduced to what identifies the repository: `git+` and protocol
+ * prefixes, the `git@host:` shorthand, a trailing `.git` and letter case all vary between
+ * package.json and a git remote without meaning a different repo.
+ */
+function normalizeRepoUrl(url) {
+  if (!url) return null
+  return url
+    .trim()
+    .replace(/^git\+/, '')
+    .replace(/^git@([^:]+):/, 'https://$1/')
+    .replace(/^ssh:\/\/git@/, 'https://')
+    .replace(/^git:\/\//, 'https://')
+    .replace(/\.git$/, '')
+    .replace(/\/+$/, '')
+    .toLowerCase()
+}
+
+/**
+ * A deterministic Conventional Commits message built from the staged file list — the
+ * floor under the drafting assistant. A release is never blocked because a text
+ * generator was unavailable or produced an unusable answer: the honest fallback is a
+ * chore commit that names what it touches, with the full paths in the body.
+ */
+function fallbackCommitMessage(files) {
+  const named = `chore: update ${files.map((file) => basename(file)).join(' and ')}`
+  const subject =
+    files.length > 0 && files.length <= 2 && named.length <= 72
+      ? named
+      : `chore: update ${files.length} files`
+  const body = files.length > 2 ? files.map((file) => `- ${file}`).join('\n') : ''
+  return body ? `${subject}\n\n${body}` : subject
+}
+
+/**
+ * The types worth writing: every one has a changelog section of its own.
+ *
+ * Derived from CHANGELOG_SECTIONS rather than written out again, because the hand-kept
+ * copy had already drifted — it omitted `deps`, so the drafter could never produce a
+ * subject for the Dependencies section the changelog has always had.
+ */
+const CHANGELOG_TYPES = CHANGELOG_SECTIONS.map((s) => s.type)
+
+/** The drafter's types plus `feature`, the alias `changelogFromCommits` folds into feat. */
+const KNOWN_TYPES = new Set([...CHANGELOG_TYPES, 'feature'])
+const CONVENTIONAL_RE = new RegExp(`^(${[...KNOWN_TYPES].join('|')})(\\([^)]+\\))?!?: .+`)
+
+/**
+ * Check commit subjects against the grammar the rest of this file reads.
+ *
+ * Two severities, because the two failures do not cost the same:
+ *
+ *  - A subject `parseCommit` cannot read is invisible. It contributes nothing to the
+ *    inferred bump and never reaches the changelog, so the work simply disappears.
+ *  - A type outside CHANGELOG_SECTIONS is merely unfiled: `changelogFromCommits` still
+ *    prints it under "Other Changes". `security:` and `i18n:` warn rather than fail —
+ *    refusing them would make this stricter than the tool it is meant to protect.
+ *
+ * Case is not one of the failures: `parseCommit` folds the type, so `Feat:` bumps and files
+ * exactly as `feat:` does. The drafter is stricter about its own output than this is about
+ * anybody's commits, and deliberately so.
+ *
+ * @param {{subject: string, hash?: string}[]} commits
+ * @returns {{subject: string, hash: string, level: 'error'|'warn', reason: string}[]}
+ */
+function lintSubjects(commits) {
+  const findings = []
+  for (const { subject, hash = '' } of commits) {
+    const parsed = parseCommit(subject)
+    if (!parsed) {
+      findings.push({
+        subject,
+        hash,
+        level: 'error',
+        reason: `not Conventional Commits — expected "<type>(<scope>): <description>" with type one of ${CHANGELOG_TYPES.join(', ')}`,
+      })
+    } else if (!KNOWN_TYPES.has(parsed.type)) {
+      findings.push({
+        subject,
+        hash,
+        level: 'warn',
+        reason: `type "${parsed.type}" has no changelog section — it lands under "Other Changes"`,
+      })
+    }
+  }
+  return findings
+}
 
 /**
  * Draft a Conventional Commits message for the staged changes.
@@ -642,11 +907,15 @@ function draftCommitMessage() {
     'Write a Conventional Commits message for these staged changes.',
     '',
     'Rules:',
-    `- Subject: "<type>(<optional scope>): <description>" where type is one of ${CONVENTIONAL_TYPES.split('|').join(', ')}.`,
+    `- Subject: "<type>(<optional scope>): <description>" where type is one of ${CHANGELOG_TYPES.join(', ')}.`,
     '- Subject in the imperative mood, no trailing period, under 72 characters.',
     '- Add a body only if the change needs explanation; separate it with a blank line.',
     '- Output the raw commit message and nothing else: no markdown fences, no preamble.',
     '- Do NOT add Co-Authored-By, Signed-off-by, or any attribution or tool credit.',
+    '- Describe only lines that are added or removed in the diff. Unchanged context lines',
+    '  (including any version fields they show) are not part of this change.',
+    '- Never mention version numbers, releases, or version bumps: the release tooling',
+    '  handles versioning separately, and this commit is not the release.',
     '',
     'Files changed:',
     stat,
@@ -658,7 +927,19 @@ function draftCommitMessage() {
   const message = runAssistant(prompt)
   if (!message) return null
   const [subject] = message.split('\n')
-  return CONVENTIONAL_RE.test(subject) ? message : null
+  if (!CONVENTIONAL_RE.test(subject)) return null
+  // The prompt forbids narrating versions; this is the deterministic backstop — the same
+  // pattern as the citation check on drafted notes: validated, not trusted.
+  const changedLines = (tryRead('git', ['diff', '--cached', '--unified=0']) ?? '')
+    .split('\n')
+    .filter((line) => /^[+-](?![+-])/.test(line))
+    .join('\n')
+  const invented = inventedVersions(message, changedLines)
+  if (invented.length) {
+    note(`draft rejected: it names ${invented.join(', ')}, which the staged changes never touch`)
+    return null
+  }
+  return message
 }
 
 /**
@@ -748,6 +1029,103 @@ function mutate(command, args, options = {}) {
   }
 }
 
+/**
+ * Lockfiles that record the releasing project's own version, and the command that brings
+ * each back into step.
+ *
+ * A lockfile is not rewritten by pattern like a manifest is: `package-lock.json` carries
+ * the version in two places, `uv.lock` carries it inside the `[[package]]` block for the
+ * project among all its dependencies, and both formats change shape between tool versions.
+ * The tool that owns the file is the only thing that can be trusted to edit it, so each
+ * one is refreshed by running that tool.
+ *
+ * `manifest` scopes the refresh: a polyglot repository can hold a `uv.lock` for a Python
+ * component that this release is not versioning, and regenerating it would put an
+ * unrelated change in the release commit.
+ *
+ * pnpm and Cargo are deliberately absent. `pnpm-lock.yaml` records no root version, so it
+ * never goes stale; `Cargo.lock` does, and is already kept in step as a version file with
+ * a pattern scoped to the crate.
+ */
+const LOCKFILES = [
+  {
+    path: 'package-lock.json',
+    manifest: 'package.json',
+    command: ['npm', ['install', '--package-lock-only', '--ignore-scripts', '--silent']],
+  },
+  {
+    path: 'npm-shrinkwrap.json',
+    manifest: 'package.json',
+    command: ['npm', ['install', '--package-lock-only', '--ignore-scripts', '--silent']],
+  },
+  { path: 'uv.lock', manifest: 'pyproject.toml', command: ['uv', ['lock', '--quiet']] },
+]
+
+/**
+ * Bring every lockfile belonging to a manifest this release wrote back into step.
+ *
+ * A missing tool is a warning rather than an abort: the lockfile is left exactly as stale
+ * as it already was, which is the behaviour without this step at all, and no release
+ * should die because a lock tool is not installed on the machine cutting it.
+ *
+ * @param {string[]} written paths the version step wrote
+ */
+function refreshLockfiles(written) {
+  const done = new Set()
+  for (const { path, manifest, command } of LOCKFILES) {
+    if (!existsSync(path) || !written.includes(manifest)) continue
+    const [tool, args] = command
+    // npm writes whichever of the two lockfiles the project has; running it twice is one
+    // pointless install, not two different edits.
+    if (!done.has(tool)) {
+      if (!dryRun && !succeeds(tool, ['--version'])) {
+        warn(`${path} records the version and ${tool} is not installed — leaving it stale`)
+        continue
+      }
+      mutate(tool, args)
+      done.add(tool)
+    }
+    staged.push(path)
+  }
+}
+
+/**
+ * Push the release commit and its tag as one transaction.
+ *
+ * `--follow-tags` and `--atomic` answer different questions: the first decides *which*
+ * refs are sent, the second decides whether they land together. With only the first, a
+ * server is free to accept the branch and reject the tag — which is precisely the split
+ * this step exists to prevent, leaving a release commit on the remote with no tag, or a
+ * tag with no commit behind it.
+ *
+ * Not every server implements the atomic capability, so a refusal on those grounds falls
+ * back to the plain push. Nothing else does: a rejected non-fast-forward retried without
+ * `--atomic` would push one ref and not the other, which is worse than failing.
+ */
+function pushBranchAndTag(branchRef) {
+  const args = ['push', '--follow-tags', config.remote, branchRef]
+  const atomic = ['push', '--follow-tags', '--atomic', config.remote, branchRef]
+  const line = formatCommand('git', atomic)
+  if (dryRun) {
+    console.log(`  ${yellow('would run:')} ${line}`)
+    return
+  }
+  console.log(`  ${dim(`$ ${line}`)}`)
+  try {
+    execFileSync('git', atomic, { stdio: ['pipe', 'inherit', 'pipe'] })
+    return
+  } catch (err) {
+    const stderr = `${err.stderr ?? ''}`
+    process.stderr.write(stderr)
+    if (!/atomic/i.test(stderr)) abortMidRelease(line)
+  }
+  warn(
+    `${config.remote} does not support atomic pushes — sending the branch and tag in one ` +
+      'call, but not as one transaction',
+  )
+  mutate('git', args)
+}
+
 /**
  * Mutating shell command, for configured strings like `publish` that are written as a
  * whole command line rather than an argv. Shell metacharacters are the author's to own.
@@ -949,6 +1327,65 @@ function insertChangelogSection(text, version, date, body) {
   return `${trimmed}\n\n${entry}`
 }
 
+/**
+ * Write the link reference definitions a Keep a Changelog document's headings depend on.
+ *
+ * `## [1.2.3]` is a markdown link *reference*: without a matching `[1.2.3]: <url>` at the
+ * foot of the file it renders as literal bracketed text. Sections were being written in
+ * that shape and the definitions were never written at all, so every heading in every
+ * changelog this tool has ever rolled is a dead reference.
+ *
+ * Every bracketed heading in the document gets one, not only the version being released,
+ * so a changelog that never had them is repaired in one release rather than from here on.
+ * Each version links to the diff since the version below it; the oldest links to its own
+ * tag, having no predecessor to compare against. `[Unreleased]` compares the newest
+ * version against `HEAD`.
+ *
+ * Definitions for labels that are not headings are left exactly where they are — those are
+ * the author's own links, and this owns only what it can derive.
+ *
+ * @param {ReturnType<typeof remoteLinks>} links
+ * @returns {string} the document with its definitions rewritten
+ */
+function withChangelogLinks(text, links, tagPrefix = '') {
+  if (!links) return text
+  const labels = [...text.matchAll(/^## \[([^\]]+)\]/gm)].map((m) => m[1])
+  if (!labels.length) return text
+
+  const versions = labels
+    .filter((label) => parseVersion(label.replace(/^v/, '')))
+    .sort((a, b) => compareVersions(b.replace(/^v/, ''), a.replace(/^v/, '')))
+  const unreleased = labels.find((label) => /^unreleased$/i.test(label))
+
+  const tagged = (label) => `${tagPrefix}${label.replace(/^v/, '')}`
+  const definitions = []
+  if (unreleased && versions.length) {
+    definitions.push(`[${unreleased}]: ${links.compare(tagged(versions[0]), 'HEAD')}`)
+  }
+  versions.forEach((version, index) => {
+    const previous = versions[index + 1]
+    definitions.push(
+      `[${version}]: ${
+        previous ? links.compare(tagged(previous), tagged(version)) : links.tag(tagged(version))
+      }`,
+    )
+  })
+  if (!definitions.length) return text
+
+  // Drop the existing definitions for the labels being rewritten, wherever they sit, so
+  // running this twice produces the same document rather than a second copy.
+  const managed = new Set([...(unreleased ? [unreleased] : []), ...versions])
+  const body = text
+    .split('\n')
+    .filter((line) => {
+      const label = /^\[([^\]]+)\]:\s/.exec(line)?.[1]
+      return !(label && managed.has(label))
+    })
+    .join('\n')
+
+  return `${body.trimEnd()}\n\n${definitions.join('\n')}\n`
+}
+
 /**
  * Promote `## [Unreleased]` to a released version and reopen an empty one above it.
  *
@@ -987,6 +1424,10 @@ function rollUnreleased(text, version, date) {
 
 const readJson = (path) => JSON.parse(readFileSync(path, 'utf8'))
 
+/** The project's release.config.json, or {} when it has none. */
+const readUserConfig = () =>
+  existsSync('release.config.json') ? readJson('release.config.json') : {}
+
 /**
  * Where a project keeps its version. The format is inferred from the file name, so the
  * common cases need nothing but a path:
@@ -1025,6 +1466,73 @@ function readNameFrom(entry) {
 /** Normalise a versionFile / versionFiles entry to { path, pattern }. */
 const versionSource = (entry) => (typeof entry === 'string' ? { path: entry } : entry)
 
+/**
+ * Expand a path that may contain `*` segments into the paths that exist, in sorted order.
+ *
+ * A desktop app carries the same version in a per-platform config for every platform it
+ * ships, and a Cargo workspace lists its members as `crates/*`. Writing those out one by
+ * one is the config the glob replaces. `*` matches within a single path segment, which is
+ * what both of those shapes need and is all Go's `filepath.Glob` — the shape changie's
+ * `replacements` use — offers either.
+ *
+ * @returns {string[]} matching paths; a pattern with no `*` yields itself when it exists
+ */
+function expandPaths(pattern) {
+  if (!pattern.includes('*')) return existsSync(pattern) ? [pattern] : []
+  const absolute = pattern.startsWith('/')
+  let current = [absolute ? '/' : '.']
+  for (const segment of pattern.split('/').filter(Boolean)) {
+    const next = []
+    if (segment.includes('*')) {
+      const shape = new RegExp(`^${segment.split('*').map(escapeRe).join('[^/]*')}$`)
+      for (const dir of current) {
+        let entries
+        try {
+          entries = readdirSync(dir).sort()
+        } catch {
+          continue
+        }
+        for (const entry of entries) if (shape.test(entry)) next.push(join(dir, entry))
+      }
+    } else {
+      for (const dir of current) {
+        const joined = join(dir, segment)
+        if (existsSync(joined)) next.push(joined)
+      }
+    }
+    current = next
+  }
+  return current
+}
+
+/**
+ * The crates in a Cargo workspace whose version this bump owns: the members that inherit
+ * it with `version.workspace = true`, which is how a workspace keeps its crates in step.
+ *
+ * A member pinning its own number is versioned separately and is left out, the same rule
+ * the companion-manifest detection uses.
+ *
+ * @returns {string[]} crate names
+ */
+function workspaceCrates(manifestPath) {
+  const text = readFileSync(manifestPath, 'utf8')
+  const members = /^members\s*=\s*\[([\s\S]*?)\]/m.exec(text)?.[1]
+  if (!members) return []
+  const root = dirname(manifestPath)
+  const names = []
+  for (const entry of members.matchAll(/"([^"]+)"/g)) {
+    for (const dir of expandPaths(join(root, entry[1]))) {
+      const memberManifest = join(dir, 'Cargo.toml')
+      if (!existsSync(memberManifest)) continue
+      const member = readFileSync(memberManifest, 'utf8')
+      if (!/^version(?:\.workspace)?\s*=\s*\{?\s*workspace\s*=\s*true/m.test(member)) continue
+      const name = NAME_PATTERNS.toml.exec(member)?.[1]
+      if (name) names.push(name)
+    }
+  }
+  return names
+}
+
 /**
  * A lockfile records a version for every dependency — hundreds of them — so the first
  * `version = "…"` in the file belongs to whichever crate sorts first, not to this project.
@@ -1032,21 +1540,27 @@ const versionSource = (entry) => (typeof entry === 'string' ? { path: entry } :
  */
 function cargoLockPattern(lockPath) {
   const sibling = join(dirname(lockPath), 'Cargo.toml')
-  const crate = existsSync(sibling) ? readNameFrom({ path: sibling }) : null
-  if (!crate) {
+  // A workspace root carries no `[package]` of its own; what it owns is every member that
+  // inherits the version with `version.workspace = true`, and the lockfile records a
+  // block for each of them.
+  const crates = existsSync(sibling)
+    ? [...new Set([readNameFrom({ path: sibling }), ...workspaceCrates(sibling)].filter(Boolean))]
+    : []
+  if (!crates.length) {
     throw new Error(
       `${lockPath} lists every dependency's version, so it needs to know which package is ` +
-        `yours.\n  No Cargo.toml beside it to read the name from — give an explicit ` +
-        `pattern:\n  { "path": "${lockPath}", "pattern": "name = \\"<crate>\\"\\nversion = ` +
-        `\\"(.+)\\"" }`,
+        `yours.\n  No Cargo.toml beside it naming a crate or a workspace member that ` +
+        `inherits the version — give an explicit pattern:\n  { "path": "${lockPath}", ` +
+        `"pattern": "name = \\"<crate>\\"\\nversion = \\"(.+)\\"" }`,
     )
   }
-  return new RegExp(`\\[\\[package\\]\\]\\nname = "${escapeRe(crate)}"\\nversion = "([^"]*)"`)
+  const names = crates.map(escapeRe).join('|')
+  return new RegExp(`\\[\\[package\\]\\]\\nname = "(?:${names})"\\nversion = "([^"]*)"`, 'g')
 }
 
 /** The regex for a source, or null when the whole file is the version. */
-function patternFor({ path, pattern }) {
-  if (pattern) return new RegExp(pattern, 'm')
+function patternFor({ path, pattern, all = false }) {
+  if (pattern) return new RegExp(pattern, all ? 'mg' : 'm')
   if (basename(path) === 'Cargo.lock') return cargoLockPattern(path)
   if (path.endsWith('.json')) return VERSION_PATTERNS.json
   if (path.endsWith('.toml')) return VERSION_PATTERNS.toml
@@ -1057,31 +1571,176 @@ function patternFor({ path, pattern }) {
 function readVersionFrom(entry) {
   const source = versionSource(entry)
   const text = readFileSync(source.path, 'utf8')
-  const pattern = patternFor(source)
-  if (!pattern) return text.trim() || null
-  const match = pattern.exec(text)
+  const { kind, shape } = versionMode(source, text)
+  if (kind === 'bare') return text.trim() || null
+  if (kind === 'markers') {
+    // The first line under a `version` marker is the one that carries the whole version;
+    // a `major` or `date` marker carries only a piece of it.
+    let scope = null
+    for (const line of text.split('\n')) {
+      const starting = MARKER_START.exec(line)?.[1]
+      if (starting) {
+        scope = starting
+        continue
+      }
+      if (scope && MARKER_END.test(line)) {
+        scope = null
+        continue
+      }
+      const active = MARKER_INLINE.exec(line)?.[1] ?? scope
+      if (active === 'version') {
+        const found = MARKER_VERSION.exec(line)?.[0]
+        if (found) return found
+      }
+    }
+    return null
+  }
+  const match = shape.exec(text)
   return match ? match[1] : null
 }
 
+/**
+ * Version markers: a comment naming the version, put on the line that carries it.
+ *
+ * A `pattern` can already reach any file, but writing one is a regex per file, and the
+ * files that most want keeping in step — a README install line, a badge URL, a Dockerfile
+ * tag, a Helm chart — are exactly the ones where a regex is fiddliest to get right and
+ * easiest to get subtly wrong. release-please solved this with a marker comment on the
+ * line instead, and the convention travels: the file says which of its numbers is the
+ * version, so nothing outside it has to describe where that number sits.
+ *
+ *   npm i acme@1.2.3            <!-- x-release-kit-version -->
+ *   FROM acme:1.2               # x-release-kit-minor
+ *   Released 2026-08-20         <!-- x-release-kit-date -->
+ *
+ * A block form covers a run of lines, for a fenced example that should not carry a comment
+ * on every line:
+ *
+ *   <!-- x-release-kit-start-version -->
+ *   ```sh
+ *   npm i acme@1.2.3
+ *   ```
+ *   <!-- x-release-kit-end -->
+ */
+// `version-date` comes first: the alternation is ordered, and `version` would otherwise
+// match its prefix and leave the date alone.
+const SCOPES = 'version-date|major|minor|patch|version|date'
+const MARKER_INLINE = new RegExp(`x-release-kit-(${SCOPES})\\b`)
+const MARKER_START = new RegExp(`x-release-kit-start-(${SCOPES})\\b`)
+const MARKER_END = /x-release-kit-end\b/
+const MARKER_VERSION = /\d+\.\d+\.\d+(?:-[0-9a-z.-]+)?(?:\+[0-9a-z.-]+)?/i
+const MARKER_NUMBER = /\b\d+\b/
+const MARKER_DATE = /\d{4}-\d{2}-\d{2}/
+
+/** Whether a file opts into marker rewriting at all. */
+const hasVersionMarkers = (text) => MARKER_INLINE.test(text) || MARKER_START.test(text)
+
+/**
+ * Rewrite the marked numbers in a file.
+ *
+ * A marker whose line carries nothing to replace is left alone rather than guessed at: a
+ * heading above a block, or a comment on its own line, is a normal thing to find.
+ *
+ * @returns {string} the rewritten text
+ */
+function applyVersionMarkers(text, version, date) {
+  const { major, minor, patch } = parseVersion(version)
+  const replacements = {
+    version: [MARKER_VERSION, version],
+    major: [MARKER_NUMBER, String(major)],
+    minor: [MARKER_NUMBER, String(minor)],
+    patch: [MARKER_NUMBER, String(patch)],
+    date: [MARKER_DATE, date],
+  }
+  // One line carrying both, which is the shape of an AppStream <release> tag.
+  const versionAndDate = (line) => line.replace(MARKER_VERSION, version).replace(MARKER_DATE, date)
+  let scope = null
+  return text
+    .split('\n')
+    .map((line) => {
+      const inline = MARKER_INLINE.exec(line)?.[1]
+      const starting = MARKER_START.exec(line)?.[1]
+      // A start marker opens a block; its own line is not rewritten, since the marker
+      // comment is the whole content of it.
+      if (starting) {
+        scope = starting
+        return line
+      }
+      if (scope && MARKER_END.test(line)) {
+        scope = null
+        return line
+      }
+      const active = inline ?? scope
+      if (!active) return line
+      if (active === 'version-date') return versionAndDate(line)
+      const [shape, value] = replacements[active]
+      return line.replace(shape, value)
+    })
+    .join('\n')
+}
+
+/**
+ * Where a file keeps its version, most specific first: the `pattern` the entry was
+ * configured with, the markers the file carries, the shape its extension implies, and —
+ * for a plain `VERSION` file — being nothing but the version.
+ *
+ * Reading and writing both go through this, so they can never disagree about which of a
+ * file's numbers is the version.
+ *
+ * @returns {{kind: 'pattern'|'markers'|'bare', shape: RegExp|null}}
+ */
+function versionMode(source, text) {
+  if (source.pattern) return { kind: 'pattern', shape: patternFor(source) }
+  if (hasVersionMarkers(text)) return { kind: 'markers', shape: null }
+  const inferred = patternFor(source)
+  return inferred ? { kind: 'pattern', shape: inferred } : { kind: 'bare', shape: null }
+}
+
 /**
  * Replace the version in a source file, touching nothing else: only the captured range is
  * rewritten, so formatting, key order and comments all survive.
  *
- * @param {{dryRun?: boolean}} [options] report the change without making it
+ * Four ways a file says where its version is, most specific first: the `pattern` it was
+ * configured with, the markers it carries, the shape its extension implies, and — for a
+ * plain `VERSION` file — being nothing but the version.
+ *
+ * @param {{dryRun?: boolean, date?: string}} [options] report the change without making
+ *   it; the date written for a `x-release-kit-date` marker
  * @returns {boolean} whether the file needed changing
  */
-function writeVersionInto(entry, version, { dryRun = false } = {}) {
+function writeVersionInto(entry, version, { dryRun = false, date } = {}) {
   const source = versionSource(entry)
   const text = readFileSync(source.path, 'utf8')
-  const pattern = patternFor(source)
+  const { kind, shape } = versionMode(source, text)
 
   let updated
-  if (pattern) {
-    const match = pattern.exec(text)
-    if (!match) throw new Error(`${source.path} has no version matching ${pattern}`)
-    const start = match.index + match[0].indexOf(match[1])
-    updated = text.slice(0, start) + version + text.slice(start + match[1].length)
+  if (kind === 'pattern') {
+    if (!shape.test(text)) {
+      if (source.optional) return false
+      throw new Error(`${source.path} has no version matching ${shape}`)
+    }
+    shape.lastIndex = 0
+    // A global pattern rewrites every match rather than the first: a Cargo.lock records
+    // one block per crate, and a workspace bump owns all the members inheriting from it.
+    updated = text.replace(shape, (match, captured) => {
+      const at = match.indexOf(captured)
+      return match.slice(0, at) + version + match.slice(at + captured.length)
+    })
+  } else if (kind === 'markers') {
+    updated = applyVersionMarkers(text, version, date ?? new Date().toISOString().slice(0, 10))
   } else {
+    // The last resort overwrites the file with the version, which is right for a VERSION
+    // file and catastrophic for anything else. A file that is not already just a version
+    // was listed by mistake, or wants a marker or a pattern — say so rather than shred it.
+    const existing = text.trim()
+    if (existing && !parseVersion(existing)) {
+      throw new Error(
+        `${source.path} is not a file containing only a version, and carries no ` +
+          'x-release-kit-version marker.\n  Writing the version into it would replace ' +
+          'everything else in it. Mark the line that holds the version, or give the entry ' +
+          'a "pattern".',
+      )
+    }
     updated = `${version}\n`
   }
 
@@ -1094,7 +1753,9 @@ function writeVersionInto(entry, version, { dryRun = false } = {}) {
 // ARGUMENTS
 // ─────────────────────────────────────────────────────────────────────────────
 
-const argv = process.argv.slice(2)
+// `next` is a modifier on the ordinary target resolution, not a mode of its own: it takes
+// the same target argument and stops once the version is known.
+const argv = process.argv.slice(PRINT_ONLY ? 3 : 2)
 const BUMPS = new Set([
   'auto',
   'major',
@@ -1180,6 +1841,69 @@ if (flag('--sync')) {
   process.exit(0)
 }
 
+// lint-commits checks subjects and exits; like --sync it starts no release. It is handled
+// before the positional parsing below because it takes a range, and a second positional is
+// otherwise a mistake.
+if (argv[0] === 'lint-commits') {
+  const rest = argv.slice(1)
+  const subjectAt = rest.indexOf('--subject')
+  // This subcommand runs before `config` is bound, so it resolves its own.
+  const lintConfig = { ...DEFAULTS, ...readUserConfig() }
+  const ignored = lintConfig.ignoreCommits.map((pattern) => new RegExp(pattern, 'i'))
+
+  let subjects
+  let scope
+  if (subjectAt !== -1) {
+    // A squash merge takes its subject from the pull request title, which is therefore the
+    // commit this repository will parse — and the one no commit-msg hook ever sees.
+    const text = rest[subjectAt + 1]
+    if (text === undefined) abort('--subject needs the text to check', 'COMMIT LINT FAILED')
+    subjects = [{ hash: '', subject: text.trim() }]
+    scope = null
+  } else {
+    if (!tryRead('git', ['rev-parse', '--show-toplevel'])) abort('not inside a git repository')
+    const lastTag = lastReleaseTag({ prefix: lintConfig.tagPrefix ?? '' })
+    const range =
+      rest.find((arg) => !arg.startsWith('-')) ?? (lastTag ? `${lastTag}..HEAD` : 'HEAD')
+    // Merges carry no prose of their own, and %s is enough: nothing here reads the body.
+    const raw = tryRead('git', ['log', '--no-merges', '--format=%h%x1f%s', range])
+    if (raw === null) {
+      abort(
+        `\`git log ${range}\` failed — is that a range in this repository?`,
+        'COMMIT LINT FAILED',
+      )
+    }
+    subjects = raw
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => {
+        const [hash, subject = ''] = line.split('\u001F')
+        return { hash: hash.trim(), subject: subject.trim() }
+      })
+      // The bookkeeping `commitsSinceLastTag` drops for the same reason: a release commit,
+      // a merge or an autosquash marker is nobody's prose to fix.
+      .filter(({ subject }) => subject && !ignored.some((re) => re.test(subject)))
+    scope = range
+  }
+
+  const findings = lintSubjects(subjects)
+  for (const { hash, subject, level, reason } of findings) {
+    const label = level === 'error' ? red('error') : yellow('warn')
+    console.log(`  ${label} ${hash ? `${dim(hash)} ` : ''}${subject}\n        ${dim(reason)}`)
+  }
+  const errors = findings.filter((f) => f.level === 'error').length
+  if (errors) {
+    abort(
+      `${errors} subject${errors === 1 ? '' : 's'} the changelog and the version bump cannot read`,
+      'COMMIT LINT FAILED',
+    )
+  }
+  const counted = `${subjects.length} subject${subjects.length === 1 ? '' : 's'}`
+  const unfiled = findings.length ? `, ${findings.length} unfiled` : ''
+  ok(`${scope ? `${scope}: ` : ''}${counted} valid${unfiled}`)
+  process.exit(0)
+}
+
 /**
  * Options that consume the argument after them. Without this list a positional target is
  * found by guessing, and `--only tag,push` gets read as the version to release.
@@ -1240,10 +1964,18 @@ if (existsSync(localManifest) && localManifest !== rootManifest) {
 }
 process.chdir(root)
 
-const userConfig = existsSync('release.config.json') ? readJson('release.config.json') : {}
+const userConfig = readUserConfig()
 const config = { ...DEFAULTS, ...userConfig }
 const unknownKeys = Object.keys(config).filter((key) => !(key in DEFAULTS))
 if (unknownKeys.length) abort(`release.config.json has unknown keys: ${unknownKeys.join(', ')}`)
+// A misspelled hook name is a hook that silently never runs, which is the failure mode
+// this file refuses everywhere else it takes a name.
+const unknownHooks = Object.keys(config.hooks ?? {}).filter((key) => !HOOKS.includes(key))
+if (unknownHooks.length) {
+  abort(
+    `release.config.json has unknown hooks: ${unknownHooks.join(', ')}\n  Known: ${HOOKS.join(', ')}`,
+  )
+}
 
 /**
  * Which steps run: config provides the baseline, --only replaces it, --skip subtracts, and
@@ -1265,17 +1997,94 @@ const parseStepList = (value) =>
 const manifest = existsSync('package.json') ? readJson('package.json') : null
 
 /**
- * Where this project keeps its version, when the config does not say. Checked in order of
- * how definitively each file identifies a repository. `go.mod` resolves to null because Go
- * modules carry no version — the tag is the version.
+ * Files that identify a repository, most definitive first. The first one present is where
+ * the version is read from and written to. `go.mod` is absent because Go modules carry no
+ * version — the tag is the version.
  */
+const MANIFESTS = ['package.json', 'pyproject.toml', 'Cargo.toml', 'VERSION']
+
+/** Where this project keeps its version, when the config does not say. */
 function detectVersionFile() {
-  for (const candidate of ['package.json', 'pyproject.toml', 'Cargo.toml', 'VERSION']) {
-    if (existsSync(candidate)) return candidate
-  }
+  for (const candidate of MANIFESTS) if (existsSync(candidate)) return candidate
   return null
 }
 
+/**
+ * Manifests that name an ecosystem, so a second one present means a second registry. A
+ * bare VERSION file is deliberately not one: it names nothing, and a repository keeping an
+ * unrelated VERSION beside its manifest should not be told the two disagree.
+ */
+const ECOSYSTEM_MANIFESTS = ['package.json', 'pyproject.toml', 'Cargo.toml']
+
+/**
+ * Some repositories release one source tree to two ecosystems at once — a Tauri plugin is
+ * a crate and an npm package, a maturin project is a crate and a wheel — and carry the
+ * version in both manifests. Those bump together with no config.
+ *
+ * The safety rule is that they must already agree. Two manifests on different versions are
+ * two independent version lines, and dragging one to the other's number is a silent, wrong
+ * release; say so and touch nothing instead.
+ *
+ * @returns {string[]} further files to keep in step with the primary version source
+ */
+function detectCompanionFiles(primaryPath, primaryVersion) {
+  const companions = []
+  for (const candidate of ECOSYSTEM_MANIFESTS) {
+    if (candidate === primaryPath || !existsSync(candidate)) continue
+    const found = readVersionFrom({ path: candidate })
+    if (found !== primaryVersion) {
+      warn(
+        `${candidate} is at ${found ?? 'no readable version'} while ${primaryPath} is at ` +
+          `${primaryVersion}, so they are versioned separately — leaving ${candidate} alone.\n` +
+          '       Add it to "versionFiles" in release.config.json to bump them together.',
+      )
+      continue
+    }
+    companions.push(candidate)
+    // The lockfile pins the crate's own version too, so a bump leaves it stale.
+    if (candidate === 'Cargo.toml' && existsSync('Cargo.lock')) companions.push('Cargo.lock')
+  }
+  return companions
+}
+
+/**
+ * Where a language records no version of its own, a project that wants `--version` to work
+ * keeps one in source instead: a Go module has only `go.mod`, which carries no version at
+ * all, so the number lives in a `version.go` the tag is supposed to match.
+ *
+ * These mirror the tag rather than define it — `go get` resolves a tag, not a constant —
+ * so they are detected as files to keep in step, never as the source of truth.
+ *
+ * A candidate is adopted only when it already carries the current version, the same rule
+ * the companion manifests use. Here it does a second job: it rules out the `var Version =
+ * "dev"` placeholder that a build replaces with -ldflags, which is not a version to bump
+ * and is common enough that warning about it every release would be pure noise. Mismatches
+ * are therefore skipped silently, unlike a manifest on its own version line.
+ *
+ * Anything outside this table is three lines of `versionFiles` config with a `pattern`;
+ * this covers the convention that comes up without one.
+ */
+const VERSION_MIRRORS = [
+  {
+    // `const Version = "1.2.0"`, `var Version = "1.2.0"`, and the same inside a const
+    // block or with an explicit `string` type.
+    pattern: '^\\s*(?:const\\s+|var\\s+)?[Vv]ersion\\s*(?:string\\s*)?=\\s*"(.+)"',
+    paths: ['version.go', 'internal/version/version.go', 'pkg/version/version.go'],
+  },
+]
+
+/** @returns {{path: string, pattern: string}[]} source files already carrying `version` */
+function detectVersionMirrors(version) {
+  const found = []
+  for (const { paths, pattern } of VERSION_MIRRORS) {
+    for (const path of paths) {
+      if (!existsSync(path)) continue
+      if (readVersionFrom({ path, pattern }) === version) found.push({ path, pattern })
+    }
+  }
+  return found
+}
+
 /**
  * The publish command implied by a project's manifest, but only where one ecosystem
  * obviously owns it. Python has several publishers (uv, twine, poetry, flit) and Go has
@@ -1287,6 +2096,26 @@ const PUBLISH_BY_MANIFEST = {
   'Cargo.toml': 'cargo publish',
 }
 
+/**
+ * A manifest that must not be published says so in itself. Detection honours that: a
+ * private package or an unpublishable crate is one this repository releases by tag alone,
+ * and detecting a command for it would attempt the one thing the manifest forbids.
+ */
+function detectablePublish(path) {
+  if (basename(path) === 'package.json') return !readJson(path).private
+  if (basename(path) === 'Cargo.toml') {
+    const text = readFileSync(path, 'utf8')
+    if (/^publish\s*=\s*false/m.test(text)) return false
+    // A crate built only as a cdylib is a native extension module — what maturin and
+    // napi-rs compile into a wheel or a .node — not a library anyone depends on from
+    // crates.io. Its version travels with the package it is built into, which is why the
+    // two match; publishing it to crates.io is the one thing nobody asked for.
+    const crateTypes = /^crate-type\s*=\s*\[([^\]]*)\]/m.exec(text)?.[1]
+    if (crateTypes?.includes('cdylib') && !crateTypes.includes('rlib')) return false
+  }
+  return true
+}
+
 // An explicit `versionFile: null` means "versions by tag" and must not be re-detected, so
 // the distinction is between the key being absent and the key being set to null.
 const configuredVersionFile = Object.hasOwn(userConfig, 'versionFile')
@@ -1312,11 +2141,7 @@ if (versionFile && !existsSync(versionFile.path)) {
  * the version has to be typed out in full every time.
  */
 function versionFromLastTag() {
-  const tag = tryRead('git', ['describe', '--tags', '--abbrev=0'])
-  if (!tag) return null
-  const bare =
-    config.tagPrefix && tag.startsWith(config.tagPrefix) ? tag.slice(config.tagPrefix.length) : tag
-  return parseVersion(bare) ? bare : null
+  return releaseTags()[0]?.version ?? null
 }
 
 const currentVersion = versionFile ? readVersionFrom(versionFile) : versionFromLastTag()
@@ -1334,13 +2159,73 @@ const goModule = existsSync('go.mod')
 const projectName =
   manifest?.name ?? (versionFile ? readNameFrom(versionFile) : null) ?? goModule ?? basename(root)
 
+/**
+ * Manifests found beside the primary one that carry the same version. Detected only when
+ * the project has said nothing about either key: a project that listed its own
+ * `versionFiles` has already answered this question, and quietly appending to that answer
+ * would release files it deliberately left out.
+ */
+const detecting =
+  !!currentVersion &&
+  !Object.hasOwn(userConfig, 'versionFile') &&
+  !Object.hasOwn(userConfig, 'versionFiles')
+const companionFiles = detecting
+  ? [
+      ...(versionFile ? detectCompanionFiles(versionFile.path, currentVersion) : []),
+      ...detectVersionMirrors(currentVersion),
+    ]
+  : []
+if (companionFiles.length) {
+  config.versionFiles = companionFiles
+  note(
+    `also versioned in ${companionFiles.map((entry) => versionSource(entry).path).join(', ')} ` +
+      '(detected)',
+  )
+}
+
+/**
+ * Every file the version is written into: the source of truth first, then the files kept
+ * in step with it. A repository that versions by tag alone has no source of truth here and
+ * may still have mirrors to write — a Go module's `version.go` is exactly that — so this
+ * is what the version step works from, rather than `versionFile` being required.
+ */
+/**
+ * Every file the version is written into, with `*` in a `versionFiles` path expanded to
+ * the files it matches.
+ *
+ * A pattern matching nothing is an error rather than a quiet skip: it was written to keep
+ * files in step, and silently keeping none of them in step is the failure it was meant to
+ * prevent. `versionFile` is never globbed — the source of truth is one file, and a glob
+ * that resolved to two would make which one wins an accident of directory order.
+ */
+const versionTargets = [
+  ...(versionFile ? [versionSource(versionFile)] : []),
+  ...config.versionFiles.map(versionSource).flatMap((source) => {
+    if (!source.path.includes('*')) return [source]
+    const matched = expandPaths(source.path)
+    if (!matched.length) abort(`versionFiles pattern ${source.path} matched no files`)
+    // A glob says "every file of this shape", and some of them legitimately carry no
+    // version — a Tauri per-OS overlay holds only the keys it overrides. Being unable to
+    // write one is expected here, unlike a path someone named on purpose.
+    return matched.map((path) => Object.assign({}, source, { path, optional: true }))
+  }),
+]
+
 // Same rule as versionFile: an explicit `publish: null` means "publish nothing" and is
 // never re-detected. Unset means "work it out", and working it out can yield nothing.
 if (!Object.hasOwn(userConfig, 'publish')) {
   // Preflight already reports "no publish command configured" when the step runs, so
   // there is nothing to say here — and `runs` is not resolved this early.
-  config.publish =
-    (versionFile ? PUBLISH_BY_MANIFEST[basename(versionFile.path)] : undefined) ?? null
+  //
+  // Two manifests releasing in step means two registries: the npm command comes first
+  // because it is the recoverable one — npm allows an unpublish for 72 hours, crates.io
+  // never does — so a half-finished publish leaves the undoable half undone.
+  const detected = [versionFile, ...companionFiles]
+    .filter(Boolean)
+    .map((entry) => versionSource(entry).path)
+    .filter((path) => PUBLISH_BY_MANIFEST[basename(path)] && detectablePublish(path))
+    .map((path) => PUBLISH_BY_MANIFEST[basename(path)])
+  config.publish = detected.length ? detected : null
 }
 
 // Validate every name that was asked for, not just the ones that survive: a typo in
@@ -1399,7 +2284,7 @@ const assistant = assistantName ? ASSISTANTS[assistantName] : null
 // RESOLVE THE TARGET VERSION
 // ─────────────────────────────────────────────────────────────────────────────
 
-console.log(
+say(
   bold(`${projectName} release`) +
     (dryRun ? `  ${yellow('(dry run — nothing will execute)')}` : ''),
 )
@@ -1463,8 +2348,13 @@ if (!target) {
 }
 
 const tag = `${config.tagPrefix}${version}`
+if (PRINT_ONLY) {
+  console.log(version)
+  process.exit(0)
+}
+
 const isPrerelease = parseVersion(version).pre.length > 0
-const bumping = !!versionFile && version !== currentVersion && runs('version')
+const bumping = versionTargets.length > 0 && version !== currentVersion && runs('version')
 
 let distTag
 try {
@@ -1491,7 +2381,43 @@ const expand = (template) => expandWith(template, (value) => value)
 const shellQuote = (value) => `'${value.replaceAll("'", `'\\''`)}'`
 const expandShell = (template) => expandWith(template, shellQuote)
 
-const publishCommand = runs('publish') && config.publish ? expandShell(config.publish) : null
+/**
+ * Run a lifecycle hook, if the project configured one.
+ *
+ * Anything a hook leaves modified is staged for the release commit. Preflight has already
+ * established that the tree was clean (or that the `commit` step is committing all of it),
+ * so a file that is dirty now was produced by this release and belongs in it — which is
+ * what makes `afterVersion` useful for regenerating a file derived from the version.
+ *
+ * @param {string} name one of HOOKS
+ */
+function runHook(name) {
+  const configured = config.hooks?.[name]
+  if (!configured) return
+  const commands = Array.isArray(configured) ? configured : [configured]
+  step(`Hook ${name}`)
+  for (const command of commands) mutateShell(expandShell(command))
+  if (dryRun) return
+  for (const path of dirtyPaths()) if (!staged.includes(path)) staged.push(path)
+}
+
+/**
+ * Paths git reports as changed, whatever the change is.
+ *
+ * The status column cannot be sliced at a fixed offset: the capture is trimmed, which
+ * strips the leading space off the first entry only, so ` M file` arrives as `M file`
+ * while the rest keep theirs. Split on the gap after the code instead.
+ */
+function dirtyPaths() {
+  return (
+    (tryRead('git', ['status', '--porcelain']) ?? '')
+      .split('\n')
+      .map((line) => /^\s*\S{1,2}\s+(.+)$/.exec(line)?.[1]?.trim())
+      .filter(Boolean)
+      // A rename reads as "old -> new"; the new path is the one to stage.
+      .map((path) => path.split(' -> ').at(-1))
+  )
+}
 
 /**
  * Registries whose preflight can be run, keyed by the first word of the publish command.
@@ -1510,13 +2436,58 @@ const REGISTRIES = {
   // uv authenticates with a token from the environment rather than a logged-in session,
   // and skips duplicate uploads itself via --check-url, so there is no version lookup.
   uv: { env: ['UV_PUBLISH_TOKEN', 'UV_PUBLISH_PASSWORD'], login: 'set UV_PUBLISH_TOKEN' },
+  // cargo has no "who am I": crates.io auth is a token, either in the environment or in
+  // the credentials file `cargo login` writes. `cargo info` is the version lookup, and
+  // exits non-zero for a version the index does not carry (cargo 1.82+).
+  cargo: {
+    env: ['CARGO_REGISTRY_TOKEN', 'CARGO_REGISTRIES_CRATES_IO_TOKEN'],
+    credentials: [
+      join(homedir(), '.cargo', 'credentials.toml'),
+      join(homedir(), '.cargo', 'credentials'),
+    ],
+    login: 'run `cargo login`, or set CARGO_REGISTRY_TOKEN',
+    published: (name, v) => ['info', `${name}@${v}`],
+  },
   // For Go the tag is the release; `go list` warms the module proxy and doubles as the
   // check for whether this version is already resolvable.
   go: { published: (name, v) => ['list', '-m', `${name}@${v}`] },
 }
 
-const publishCli = publishCommand?.trim().split(/\s+/)[0]
-const registry = publishCli ? REGISTRIES[publishCli] : null
+/**
+ * Which manifest records the name a registry knows this project by, when it is not the one
+ * `projectName` came from. They are not always the same string: a Tauri plugin publishes as
+ * `@tauri-apps/plugin-x` on npm and `tauri-plugin-x` on crates.io, so looking the crate up
+ * under its npm name would report every version as unpublished.
+ */
+const NAME_MANIFEST_BY_CLI = { cargo: 'Cargo.toml' }
+
+function registryName(cli) {
+  const manifest = NAME_MANIFEST_BY_CLI[cli]
+  if (!manifest) return projectName
+  const source = versionTargets.find((entry) => basename(entry.path) === manifest)
+  return (source && readNameFrom(source)) ?? projectName
+}
+
+/**
+ * `publish` is one command or several, because one source tree can own a package in more
+ * than one ecosystem. They run in the configured order.
+ */
+const publishList = config.publish == null ? [] : [config.publish].flat()
+if (publishList.some((entry) => typeof entry !== 'string')) {
+  abort('publish must be a command string, an array of command strings, or null')
+}
+
+/** Each publish command with the CLI it drives, that CLI's preflight row, and its name. */
+const publishTargets = runs('publish')
+  ? publishList.map((template) => {
+      const command = expandShell(template)
+      const cli = command.trim().split(/\s+/)[0]
+      return { command, cli, registry: REGISTRIES[cli] ?? null, name: registryName(cli) }
+    })
+  : []
+
+/** npm-family commands are the ones a `"private": true` package.json forbids. */
+const NPM_CLIS = new Set(['npm', 'pnpm', 'bun'])
 
 /**
  * CI publishing over OIDC ("trusted publishing") carries no token at all: `whoami` fails
@@ -1561,10 +2532,35 @@ if (autoBump) {
   }
 }
 
-if (bumping && compareVersions(version, currentVersion) <= 0) {
+// Writing the version is the first mutating step, and it used to discover a file it
+// could not write *while writing the others* — aborting with a raw stack trace after
+// some of them had already changed. Every target is checked here instead.
+if (bumping) {
+  for (const source of versionTargets) {
+    if (!existsSync(source.path)) {
+      fail(`versionFiles entry ${source.path} does not exist`)
+      continue
+    }
+    if (source.optional) continue
+    const text = readFileSync(source.path, 'utf8')
+    const { kind, shape } = versionMode(source, text)
+    if (kind === 'pattern' && !shape.test(text)) {
+      fail(
+        `${source.path} has no version for release-kit to replace.\n` +
+          '       Remove it from versionFiles, mark the line with x-release-kit-version, ' +
+          'or give the entry a "pattern".',
+      )
+    }
+  }
+}
+
+if (bumping && currentVersion && compareVersions(version, currentVersion) <= 0) {
   fail(`${version} is not greater than the current version ${currentVersion}`)
-} else if (bumping) {
+} else if (bumping && currentVersion) {
   ok(`version ${currentVersion} → ${version}`)
+} else if (bumping) {
+  // No manifest and no tag to read a version from, but files to write one into.
+  ok(`writing ${version} into ${versionTargets.map((source) => source.path).join(', ')}`)
 } else if (versionFile) {
   ok(`releasing the version already in ${versionFile.path} (${version})`)
 } else {
@@ -1573,10 +2569,16 @@ if (bumping && compareVersions(version, currentVersion) <= 0) {
 
 const dirty = tryRead('git', ['status', '--porcelain'])
 if (dirty === null) fail('could not read git status')
-else if (dirty && runs('commit') && assistant) {
+else if (dirty && runs('commit')) {
   const entries = dirty.split('\n')
   ok(`working tree has ${entries.length} change(s) — will be committed first`)
   console.log(dim(indent(formatStatus(dirty))))
+  if (!assistant) {
+    note(
+      'no assistant configured: the commit message will name the files — ' +
+        '`--assistant auto` drafts a real one',
+    )
+  }
   // One commit gets one subject. A change set spanning several top-level directories is
   // usually several pieces of work, and no honest Conventional Commits subject covers it.
   const areas = new Set(
@@ -1592,12 +2594,6 @@ else if (dirty && runs('commit') && assistant) {
         'releasing with --skip commit.',
     )
   }
-} else if (dirty && runs('commit')) {
-  fail(
-    `working tree is not clean:\n${indent(formatStatus(dirty))}\n` +
-      '       Configure a drafting assistant (`--assistant auto`, or "assistant" in ' +
-      'release.config.json) to have these committed automatically, or commit them yourself.',
-  )
 } else if (dirty) {
   fail(`working tree is not clean:\n${indent(formatStatus(dirty))}`)
 } else ok('working tree clean')
@@ -1627,9 +2623,9 @@ else if (detached) {
   fail(`on '${branch}', expected '${config.branch}'`)
 } else ok(`on ${branch}`)
 
-// A shallow clone (CI checkouts default to depth 1) hides the history that release notes
-// and the last-tag lookup are derived from. It still releases correctly; the notes just
-// silently describe a fraction of the work, so say so before that happens.
+// A shallow clone (CI checkouts default to depth 1) is only a problem when it truncates
+// the history the release actually reads. Whether it does is checked after the fetch
+// below, where the answer is most accurate.
 const shallow = tryRead('git', ['rev-parse', '--is-shallow-repository']) === 'true'
 
 if (!succeeds('git', ['remote', 'get-url', config.remote])) {
@@ -1652,6 +2648,50 @@ if (!succeeds('git', ['remote', 'get-url', config.remote])) {
   }
 }
 
+// If the previous release tag is reachable from HEAD, a shallow clone hides nothing the
+// release reads — notes and `auto` see the whole span. No reachable tag means the history
+// is provably truncated: `auto` would infer the bump from a fraction of the commits, so
+// that is a failure; commit-derived notes merely come out partial, so that is a warning.
+let shallowHidesHistory = false
+if (shallow) {
+  const reachableTag = lastReleaseTag()
+  shallowHidesHistory = !reachableTag
+  if (reachableTag) {
+    ok(
+      `shallow clone, but history back to ${reachableTag} is visible — notes and auto are complete`,
+    )
+  } else if (autoBump) {
+    fail(
+      'shallow clone hides the history `auto` infers the bump from — no previous tag is ' +
+        'reachable.\n       Fetch full history: fetch-depth: 0 in CI, or git fetch --unshallow.',
+    )
+  } else {
+    warn(
+      'shallow clone: no previous tag is reachable, so notes drafted from commits will ' +
+        'describe only the visible history. Fetch full history (fetch-depth: 0, or ' +
+        'git fetch --unshallow).',
+    )
+  }
+}
+
+// The registry's "Repository" link comes from the manifest, not from git — a mismatch
+// ships a broken link with every publish, and npm only warns after the fact.
+if (existsSync('package.json')) {
+  const repoField = readJson('package.json').repository
+  const declared = typeof repoField === 'string' ? repoField : repoField?.url
+  const remoteUrl = tryRead('git', ['remote', 'get-url', config.remote])
+  if (declared && remoteUrl && /:\/\/|@/.test(declared)) {
+    if (normalizeRepoUrl(declared) !== normalizeRepoUrl(remoteUrl)) {
+      warn(
+        `package.json repository is ${declared}, but ${config.remote} is ${remoteUrl} — ` +
+          'the registry will link the wrong repository',
+      )
+    } else if (!/^git\+.*\.git$/.test(declared)) {
+      note(`npm normalizes repository.url on publish — \`npm pkg fix\` writes that form`)
+    }
+  }
+}
+
 // Signing is configured per repository and inherited, never managed here — git already
 // owns that. But a signing setup that cannot produce a signature fails at the commit step,
 // after the version has been written, so it is worth catching before anything mutates.
@@ -1719,37 +2759,70 @@ if (!runs('release')) {
   if (releaseExists) note(`a GitHub release for ${tag} already exists — will skip that step`)
 }
 
-let alreadyPublished = false
-if (!publishCommand) {
-  note(runs('publish') ? 'no publish command configured' : 'publish step not selected')
-} else if (manifest?.private) {
-  fail('package.json is private but a publish command is configured')
-} else if (!registry) {
-  ok(`publish: ${publishCommand}`)
-} else {
+/** Whether one publish CLI can publish at all: OIDC, a token, or a live session. */
+function checkCredentials({ cli, registry, command }) {
   if (isTrustedPublishing) {
-    ok('trusted publishing (OIDC) — no token needed')
-  } else if (registry.env) {
-    // Token-in-the-environment auth: there is no session to interrogate, only credentials.
+    ok(`${cli}: trusted publishing (OIDC) — no token needed`)
+    // Provenance is the other half of what OIDC makes possible: a signed attestation
+    // tying the published artefact to the workflow and commit that produced it. It is
+    // not added to the command here — npm generates it for a trusted publish on its own,
+    // and forcing the flag fails outright for a private package or a registry that
+    // cannot receive one. Saying so is what turns "available" into "used".
+    if (NPM_CLIS.has(cli) && !/--provenance\b/.test(command ?? '')) {
+      note(
+        `${cli}: OIDC also allows a signed provenance attestation — add --provenance to ` +
+          'the publish command if the registry accepts one and the package is public',
+      )
+    }
+    return
+  }
+  if (registry.env) {
+    // Token auth: there is no session to interrogate, only credentials to find.
     const found = registry.env.find((name) => process.env[name])
-    if (found) ok(`${publishCli} credentials found (${found})`)
-    else fail(`${publishCli} has no publish credentials — ${registry.login}`)
-  } else if (registry.whoami) {
-    const user = tryRead(publishCli, registry.whoami)
+    if (found) {
+      ok(`${cli} credentials found (${found})`)
+      return
+    }
+    const file = registry.credentials?.find((path) => existsSync(path))
+    if (file) ok(`${cli} credentials found (${file})`)
+    else fail(`${cli} has no publish credentials — ${registry.login}`)
+    return
+  }
+  if (registry.whoami) {
+    const user = tryRead(cli, registry.whoami)
     if (user === null) {
       // npm replaced long-lived tokens with two-hour sessions in December 2025, so the
       // usual cause is an expired session rather than a missing login.
       fail(
-        `${publishCli} is not authenticated — run \`${publishCli} login\`. ` +
+        `${cli} is not authenticated — run \`${cli} login\`. ` +
           'npm logins are two-hour sessions, so an earlier one may have expired.',
       )
-    } else ok(`${publishCli} authenticated (${user || 'unknown user'})`)
+    } else ok(`${cli} authenticated (${user || 'unknown user'})`)
   }
+}
 
-  if (registry.published) {
-    alreadyPublished = succeeds(publishCli, registry.published(projectName, version))
-    if (alreadyPublished) {
-      note(`${projectName}@${version} is already published — will skip the publish step`)
+/** Commands whose version is already on the registry, so the publish step skips them. */
+const alreadyPublished = new Set()
+if (!publishTargets.length) {
+  note(runs('publish') ? 'no publish command configured' : 'publish step not selected')
+} else if (manifest?.private && publishTargets.some((target) => NPM_CLIS.has(target.cli))) {
+  fail('package.json is private but an npm publish command is configured')
+} else {
+  // One CLI can appear more than once; interrogating it twice says the same thing twice.
+  const authenticated = new Set()
+  for (const target of publishTargets) {
+    ok(`publish: ${target.command}`)
+    if (!target.registry) continue
+    if (!authenticated.has(target.cli)) {
+      authenticated.add(target.cli)
+      checkCredentials(target)
+    }
+    if (
+      target.registry.published &&
+      succeeds(target.cli, target.registry.published(target.name, version))
+    ) {
+      alreadyPublished.add(target.command)
+      note(`${target.name}@${version} is already published — will skip \`${target.command}\``)
     }
   }
 }
@@ -1791,7 +2864,17 @@ let draftedNotes = null
  * True when --commit still has to create a commit. Notes drafted before that commit would
  * describe an incomplete release, so drafting waits until the working tree is committed.
  */
-const notesDeferred = !!(dirty && runs('commit') && assistant)
+const notesDeferred = !!(dirty && runs('commit'))
+
+/**
+ * Set only when preflight found nothing to release with and left the drafting to the
+ * post-commit step. Deferral has to be recorded rather than re-derived from `notesDeferred`
+ * there: a dirty tree is what makes drafting possible to defer, not what makes it necessary.
+ * A hand-written changelog section has already answered the question, and re-drafting over
+ * it would discard the notes the confirmation prompt showed and append a second section for
+ * the same version.
+ */
+let notesPending = false
 
 /**
  * Notes for a version, in descending order of how much they can be trusted:
@@ -1799,7 +2882,12 @@ const notesDeferred = !!(dirty && runs('commit') && assistant)
  * Conventional Commit type. Only when neither yields anything does GitHub generate them.
  */
 function draftNotesFor(v) {
-  const { lastTag, subjects, commits } = commitsSinceLastTag()
+  // A stable release absorbs the candidates that led to it: their commits are what it
+  // ships, and reading from the last candidate leaves the notes describing the gap
+  // between two candidates rather than the release.
+  const { lastTag, subjects, commits, contributors } = commitsSinceLastTag({
+    stable: !isPrerelease,
+  })
   if (!commits.length) return null
 
   // Notes are built from Conventional Commits, so anything not written that way is simply
@@ -1814,8 +2902,13 @@ function draftNotesFor(v) {
   }
   // An explicitly named source wins over the assistant being merely available.
   if (!assistant || notesSource === 'commits')
-    return changelogFromCommits(commits, remoteLinks(config.remote), config.hiddenTypes)
-  if (shallow) {
+    return changelogFromCommits(
+      commits,
+      remoteLinks(config.remote),
+      config.hiddenTypes,
+      contributors,
+    )
+  if (shallowHidesHistory) {
     warn(
       `shallow clone: only ${subjects.length} commit(s) are visible, so the notes will ` +
         'describe part of the release. Check out with full history (fetch-depth: 0).',
@@ -1824,7 +2917,7 @@ function draftNotesFor(v) {
   note(`drafting notes from ${subjects.length} commit(s) with ${assistantName}...`)
   return (
     draftReleaseNotes(v, commits, lastTag, remoteLinks(config.remote)) ??
-    changelogFromCommits(commits, remoteLinks(config.remote), config.hiddenTypes)
+    changelogFromCommits(commits, remoteLinks(config.remote), config.hiddenTypes, contributors)
   )
 }
 const changelogText =
@@ -1857,7 +2950,8 @@ if (notesSource === 'github') {
   // Generate, either because nothing was written or because a source was named.
   if (!notes) {
     if (notesDeferred) {
-      ok('release notes will be drafted after the commit')
+      notesPending = true
+      ok(`release notes will be ${assistant ? 'drafted' : 'generated'} after the commit`)
     } else {
       draftedNotes = draftNotesFor(version)
       if (draftedNotes) {
@@ -1895,6 +2989,19 @@ if (taggedCommit && runs('tag') && (bumping || rolledChangelog)) {
   )
 }
 
+// The project's own gate, run while nothing has mutated. Without this, a prepublishOnly
+// hook is the gate — and it fails at the publish step, after the commit, tag and push.
+if (config.verify) {
+  note(`running verify: ${config.verify}`)
+  try {
+    execSync(config.verify, { stdio: 'pipe', encoding: 'utf8' })
+    ok(`verify passed: ${config.verify}`)
+  } catch (err) {
+    const tail = `${err.stdout ?? ''}${err.stderr ?? ''}`.trim().split('\n').slice(-12).join('\n')
+    fail(`verify failed: ${config.verify}\n${indent(tail)}`)
+  }
+}
+
 if (problems.length) {
   const summary = `${problems.length} preflight check(s) failed:\n  - ${problems.join('\n  - ')}`
   if (!dryRun) abort(summary)
@@ -1919,13 +3026,16 @@ if (dirty && runs('commit') && !dryRun) {
   step('Stage the working tree')
   mutate('git', ['add', '--all'])
   didStage = true
-  commitMessage = draftCommitMessage()
+  commitMessage = assistant ? draftCommitMessage() : null
   if (!commitMessage) {
-    mutate('git', ['reset', '--quiet'])
-    abort(
-      `${assistantName} could not draft a Conventional Commits message for these changes.\n\n` +
-        '  Commit them yourself and re-run, or release with --skip commit.',
-    )
+    // No assistant, or its draft was unusable: never block on a text generator. The
+    // deterministic floor is a chore commit that names what it touches.
+    if (assistant) {
+      note(`${assistantName} produced no usable message — falling back to a generated one`)
+    }
+    const files =
+      tryRead('git', ['diff', '--cached', '--name-only'])?.split('\n').filter(Boolean) ?? []
+    commitMessage = fallbackCommitMessage(files)
   }
   console.log(indent(commitMessage))
 }
@@ -1961,33 +3071,38 @@ if (dirty && runs('commit')) {
   else mutate('git', ['commit', '-m', commitMessage])
 
   // Now that the commit exists it is part of the release, so the notes can describe it.
-  if (notesDeferred && !dryRun) {
+  if (notesPending && !dryRun) {
     draftedNotes = draftNotesFor(version)
     if (draftedNotes) notes = draftedNotes
   }
 }
 
+runHook('beforeVersion')
+
 if (bumping) {
   step(`Write version ${version}`)
-  for (const entry of [versionFile, ...config.versionFiles]) {
-    const source = versionSource(entry)
+  const releaseDate = new Date().toISOString().slice(0, 10)
+  for (const source of versionTargets) {
     if (!existsSync(source.path)) abort(`versionFiles entry ${source.path} does not exist`)
-    if (writeVersionInto(source, version, { dryRun })) {
+    if (writeVersionInto(source, version, { dryRun, date: releaseDate })) {
       staged.push(source.path)
       console.log(`  ${dryRun ? yellow('would write') : dim('wrote')} ${source.path}`)
     }
   }
-  // A package-lock.json embeds the root version twice, so it goes stale on a bump.
-  if (existsSync('package-lock.json')) {
-    mutate('npm', ['install', '--package-lock-only', '--ignore-scripts', '--silent'])
-    staged.push('package-lock.json')
-  }
+  refreshLockfiles(versionTargets.map((source) => source.path))
 }
 
+// After the version is on disk and before the release commit, so a file the hook
+// regenerates from the version rides in that commit rather than being left behind.
+runHook('afterVersion')
+
+/** The version headings a changelog carries are dead link references without these. */
+const linked = (text) => withChangelogLinks(text, remoteLinks(config.remote), config.tagPrefix)
+
 if (rolledChangelog && runs('changelog')) {
   step(`Roll ${config.changelog} to ${version}`)
   if (dryRun) console.log(`  ${yellow('would write')} ${config.changelog}`)
-  else writeFileSync(config.changelog, rolledChangelog)
+  else writeFileSync(config.changelog, linked(rolledChangelog))
   staged.push(config.changelog)
 } else if (runs('changelog') && draftedNotes && config.changelog && existsSync(config.changelog)) {
   step(`Add the drafted ${version} section to ${config.changelog}`)
@@ -1995,11 +3110,13 @@ if (rolledChangelog && runs('changelog')) {
   else {
     writeFileSync(
       config.changelog,
-      insertChangelogSection(
-        readFileSync(config.changelog, 'utf8'),
-        version,
-        new Date().toISOString().slice(0, 10),
-        draftedNotes,
+      linked(
+        insertChangelogSection(
+          readFileSync(config.changelog, 'utf8'),
+          version,
+          new Date().toISOString().slice(0, 10),
+          draftedNotes,
+        ),
       ),
     )
   }
@@ -2044,15 +3161,25 @@ if (runs('tag') && !taggedCommit) {
 
 if (runs('push')) {
   step(`Push branch and tag to ${config.remote}`)
-  // --follow-tags sends the commit and the tag in one call; pushing them separately is how
-  // a tag ends up on the remote without its commit, or a release without its tag.
-  mutate('git', ['push', '--follow-tags', config.remote, branch ?? 'HEAD'])
+  pushBranchAndTag(branch ?? 'HEAD')
 }
 
-if (publishCommand && !alreadyPublished) {
-  step(`Publish to the registry (dist-tag ${distTag})`)
-  mutateShell(publishCommand)
+// After the tag is pushed and before anything is published: the point where an artefact
+// the publish command expects to find has to exist.
+if (publishTargets.length) runHook('beforePublish')
+
+let publishedSomething = false
+for (const target of publishTargets) {
+  if (alreadyPublished.has(target.command)) continue
+  step(
+    `Publish ${target.name} (${target.cli}${NPM_CLIS.has(target.cli) ? `, dist-tag ${distTag}` : ''})`,
+  )
+  mutateShell(target.command)
+  publishedSomething = true
 }
+// Only when something was actually published: a re-run that skipped every already-published
+// target published nothing, and telling downstream otherwise is a lie it may act on.
+if (publishedSomething) runHook('afterPublish')
 
 if (runs('release') && !releaseExists) {
   step(`GitHub release ${tag}`)
@@ -2068,6 +3195,7 @@ if (runs('release') && !releaseExists) {
     ...config.assets,
   ]
   mutate('gh', args, notes ? { input: `${notes}\n` } : {})
+  runHook('afterRelease')
 }
 
 /**
@@ -2087,7 +3215,7 @@ function emitOutputs() {
     name: projectName,
     'dist-tag': distTag,
     steps: STEPS.filter(runs).join(','),
-    published: String(!!publishCommand && !alreadyPublished),
+    published: String(publishTargets.some((target) => !alreadyPublished.has(target.command))),
     'release-url': releaseUrl,
   }
   try {