@entro314labs/release-kit 2.9.4 → 2.11.0

package/release.mjs

@@ -42,6 +42,7 @@ import {
   mkdtempSync,
   readdirSync,
   readFileSync,
+  statSync,
   writeFileSync,
 } from 'node:fs'
 import { homedir, tmpdir } from 'node:os'
@@ -92,6 +93,9 @@ import { fileURLToPath } from 'node:url'
  *   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
+ *   requireGreen    boolean  refuse to release a HEAD that GitHub does not report green:
+ *                            pushed, every check run and commit status finished, none of
+ *                            them failed. See `checkHeadIsGreen`
  *   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
@@ -147,6 +151,7 @@ const DEFAULTS = {
     '^(fixup|squash)!',
   ],
   verify: null,
+  requireGreen: false,
   hooks: {},
 }
 
@@ -215,6 +220,8 @@ Flags:
                        drafted Conventional Commits message instead of refusing to release
   --preid <id>         prerelease identifier (alpha, beta, rc, next, nightly, canary)
   --dist-tag <name>    override the npm dist-tag (default: derived from the version)
+  --package            release the package in this directory, one of several in the
+                       repository: its own tag (<name>@<version>), commits and publish
   --dry-run            print every step and execute nothing
   --yes, -y            skip the confirmation prompt
   --notes-file <path>  write the resolved release notes to a file for the next tool
@@ -281,7 +288,9 @@ const formatStatus = (porcelain) =>
     .join('\n')
 
 function abort(message, title = 'RELEASE ABORTED') {
-  console.log(`\n${red(bold(title))} — ${message}\n`)
+  // Through `say`: under `next`, stdout carries the version alone, and an abort captured by
+  // `$(...)` would otherwise become the "version".
+  say(`\n${red(bold(title))} — ${message}\n`)
   process.exit(1)
 }
 
@@ -292,9 +301,15 @@ function abort(message, title = 'RELEASE ABORTED') {
  * the real cause under a Node stack trace.
  */
 function abortMidRelease(commandLine) {
+  // A relative bump re-run as-is would count from the version this run already wrote, and
+  // preflight refuses it; what finishes the release is the version itself, or no target.
+  const rerun =
+    target && target !== 'auto' && BUMPS.has(target)
+      ? 're-run with no target (or `auto`)'
+      : 're-run the same command'
   abort(
     `\`${commandLine}\` failed — see its output above.\n\n` +
-      '  The release stopped partway through. Fix the cause and re-run the same command:\n' +
+      `  The release stopped partway through. Fix the cause and ${rerun}:\n` +
       '  the steps that already completed are detected and skipped.',
   )
 }
@@ -573,7 +588,7 @@ function commitsSinceLastTag(options) {
   // separator keeps multi-line messages parseable when splitting the log back apart.
   // %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 raw = tryRead('git', ['log', `--format=%h%x1f%an%x1f%ae%x1f%B%x1e`, range, ...SCOPE]) ?? ''
   const commits = raw
     .split('\u001E')
     .map((entry) => entry.trim())
@@ -657,11 +672,29 @@ const CHANGELOG_SECTIONS = [
   { type: 'chore', section: 'Miscellaneous Chores' },
 ]
 
+/**
+ * The `Notes:` trailer in a commit body: the author's own wording for the release-notes
+ * entry, which beats anything derived from the subject. `Notes: no-notes` keeps the commit
+ * out of the notes altogether — a refactor that has to be a `fix:` for the version bump but
+ * that no reader upgrading needs to hear about. GitHub Desktop runs its notes this way.
+ *
+ * The version bump is not affected either way: the trailer decides what is said about a
+ * change, not whether it happened.
+ *
+ * @returns {{text: string|null, excluded: boolean}}
+ */
+function notesTrailer(body = '') {
+  const text = /^Notes:[ \t]*(\S.*)$/im.exec(body)?.[1]?.trim() ?? null
+  const excluded = !!text && /^no-notes$/i.test(text)
+  return { text: excluded ? null : text, excluded }
+}
+
 /**
  * Parse a commit into the parts a release cares about.
  *
  * @returns {{type: string, scope: string|null, breaking: boolean, subject: string,
- *   releaseAs: string|null} | null} null when the subject is not Conventional Commits
+ *   releaseAs: string|null, notes: string|null, noNotes: boolean} | null} null when the
+ *   subject is not Conventional Commits
  */
 function parseCommit(subject, body = '', hash = '') {
   // Conventional Commits does not restrict the type to letters — `i18n:` and `a11y:` are
@@ -680,6 +713,7 @@ function parseCommit(subject, body = '', hash = '') {
   // A BREAKING CHANGE footer usually explains the break far better than the subject does.
   const breakingNote =
     /^BREAKING[ -]CHANGE:\s*([\s\S]+?)(?=\n\n|$)/m.exec(body)?.[1]?.trim() ?? null
+  const trailer = notesTrailer(body)
   return {
     type: type.toLowerCase(),
     scope: scope ?? null,
@@ -689,6 +723,8 @@ function parseCommit(subject, body = '', hash = '') {
     releaseAs,
     closes: [...new Set(closes)],
     breakingNote,
+    notes: trailer.text,
+    noNotes: trailer.excluded,
   }
 }
 
@@ -727,7 +763,9 @@ function inferBump(commits, currentVersion, strategy = 'conventional') {
  * @returns {string | null} markdown body, or null when nothing visible changed
  */
 function changelogFromCommits(commits, links = null, hidden = [], contributors = []) {
-  const parsed = commits.map((c) => parseCommit(c.subject, c.body, c.hash)).filter(Boolean)
+  const parsed = commits
+    .map((c) => parseCommit(c.subject, c.body, c.hash))
+    .filter((c) => c && !c.noNotes)
   const lines = []
 
   /** One bullet: scope, text, a link to the commit, and any issues it closes. */
@@ -745,8 +783,9 @@ function changelogFromCommits(commits, links = null, hidden = [], contributors =
   const breaking = parsed.filter((c) => c.breaking)
   if (breaking.length) {
     lines.push('### ⚠ BREAKING CHANGES', '')
-    // The footer explains the break; the subject only says what changed.
-    for (const c of breaking) lines.push(bullet(c, c.breakingNote ?? c.subject))
+    // The footer explains the break; the subject only says what changed. A `Notes:`
+    // trailer beats both: it is the author's wording written for exactly this list.
+    for (const c of breaking) lines.push(bullet(c, c.notes ?? c.breakingNote ?? c.subject))
     lines.push('')
   }
 
@@ -768,7 +807,7 @@ function changelogFromCommits(commits, links = null, hidden = [], contributors =
     )
     if (!inSection.length) continue
     lines.push(`### ${section}`, '')
-    for (const c of inSection) lines.push(bullet(c, c.subject))
+    for (const c of inSection) lines.push(bullet(c, c.notes ?? c.subject))
     lines.push('')
   }
 
@@ -780,7 +819,7 @@ function changelogFromCommits(commits, links = null, hidden = [], contributors =
   )
   if (other.length) {
     lines.push('### Other Changes', '')
-    for (const c of other) lines.push(bullet(c, c.subject))
+    for (const c of other) lines.push(bullet(c, c.notes ?? c.subject))
     lines.push('')
   }
 
@@ -1066,13 +1105,41 @@ function linkCitedCommits(notes, commits, links) {
   })
 }
 
+/**
+ * The marker a drafting model puts on an entry it is not sure of — whether the change is
+ * user-facing, or what it means for someone upgrading. The alternative is a confident guess
+ * published as fact; a flagged entry is a question for the human cutting the release.
+ */
+const UNSURE = '[???]'
+
+/**
+ * Drafted entries the model flagged as unsure, as the lines it wrote them on. Drafts are
+ * validated, not trusted: like an invented commit hash, a flagged entry must not reach a
+ * tag, a changelog or a release page without someone having looked at it.
+ *
+ * @returns {string[]}
+ */
+function uncertainEntries(notes) {
+  return (notes ?? '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.includes(UNSURE))
+}
+
+/** The notes with the marker removed, once a human has reviewed the flagged entries. */
+const withoutUnsureMarkers = (notes) => notes.replaceAll(`${UNSURE} `, '').replaceAll(UNSURE, '')
+
 /**
  * Draft release notes from the commit log.
  *
  * @returns {string | null} markdown body (no version heading), or null
  */
 function draftReleaseNotes(version, commits, lastTag, links) {
-  if (!commits.length) return null
+  // `Notes: no-notes` is the author saying this commit is not news; the model never sees it.
+  const listed = commits
+    .map((c) => ({ ...c, trailer: notesTrailer(c.body) }))
+    .filter((c) => !c.trailer.excluded)
+  if (!listed.length) return null
 
   const prompt = [
     `Write release notes for version ${version}.`,
@@ -1084,20 +1151,31 @@ function draftReleaseNotes(version, commits, lastTag, links) {
     '- End every bullet with the short hashes it covers, in parentheses: `(abc1234)` or',
     '  `(abc1234, def5678)` when merged. Copy them exactly from the list below and invent',
     '  nothing — a hash that is not in the list will be removed.',
-    '- Omit internal chores: CI, linting, formatting, dependency bumps, version bumps.',
+    '- Omit internal chores: CI, linting, formatting, version bumps and dependency bumps —',
+    '  except a component that ships inside the product (a bundled runtime, a sidecar',
+    '  binary, an embedded engine or database). Users run that code, so its update is a',
+    '  user-visible change: name the component and the version it moved to.',
+    '- For bug fixes, describe what works now, not what was broken.',
+    '- If you cannot tell whether a change is user-facing, or what it means for someone',
+    `  upgrading, start that bullet with ${UNSURE} — a person will resolve it. Do not guess.`,
+    "- A commit with a `Notes:` line carries its author's wording for the entry: use that",
+    '  text as written, changing it only to fit the heading or to merge it with related work.',
     '- Write for someone upgrading: say what changed for them, not which files moved.',
     '- Plain, factual language. No hype, no emoji, no concluding summary.',
     '- Output only the markdown body: no version heading, no code fences, no attribution.',
     '- Do NOT explain your reasoning or add any commentary before or after the notes.',
     '',
     `Commits since ${lastTag ?? 'the start of the project'}:`,
-    ...commits.map((c) => `- ${(c.hash ?? '').slice(0, 7)} ${c.subject}`),
+    ...listed.flatMap((c) => [
+      `- ${(c.hash ?? '').slice(0, 7)} ${c.subject}`,
+      ...(c.trailer.text ? [`  Notes: ${c.trailer.text}`] : []),
+    ]),
   ].join('\n')
 
   const drafted = runAssistant(prompt)
   if (!drafted) return null
   const cleaned = cleanNotes(drafted)
-  return cleaned ? linkCitedCommits(cleaned, commits, links) : null
+  return cleaned ? linkCitedCommits(cleaned, listed, links) : null
 }
 
 /** One-line rendering of an argv, so a multi-line arg (release notes) stays readable. */
@@ -1213,7 +1291,9 @@ function pushBranchAndTag(branchRef) {
   } catch (err) {
     const stderr = `${err.stderr ?? ''}`
     process.stderr.write(stderr)
-    if (!/atomic/i.test(stderr)) abortMidRelease(line)
+    // Only the capability refusal falls back. git's rejection of a ref also names atomic
+    // ("atomic push failed"), and that one must stop here.
+    if (!/does not support --atomic/i.test(stderr)) abortMidRelease(line)
   }
   warn(
     `${config.remote} does not support atomic pushes — sending the branch and tag in one ` +
@@ -1396,9 +1476,39 @@ function changelogOutOfOrder(text) {
   return versions.filter((v, i) => i > 0 && compareVersions(versions[i - 1], v) < 0)
 }
 
+/**
+ * The release candidates of a stable version that the changelog has sections for: for
+ * `2.0.0`, the `2.0.0-rc.1` and `2.0.0-beta.3` headings.
+ *
+ * A stable release reads history from the last stable tag and generates its notes from
+ * those commits, so wording someone edited into a candidate's section does not carry over.
+ * The sections stay in the file; this is how the release notices they exist.
+ *
+ * @returns {string[]} the candidate versions, in file order
+ */
+function candidateSections(text, version) {
+  const base = parseVersion(version)
+  if (!base || base.pre.length) return []
+  return [...text.matchAll(/^## \[?v?(\d+\.\d+\.\d+-[\w.]+)\]?/gm)]
+    .map((m) => m[1])
+    .filter((v) => {
+      const parsed = parseVersion(v)
+      return (
+        parsed &&
+        parsed.major === base.major &&
+        parsed.minor === base.minor &&
+        parsed.patch === base.patch
+      )
+    })
+}
+
 /** The `## ` heading offsets in a changelog, in file order. */
 const sectionOffsets = (text) => [...text.matchAll(/^## .*$/gm)].map((m) => m.index)
 
+/** True when the changelog already has a `## [version]` heading, empty body or not. */
+const hasVersionHeading = (text, version) =>
+  new RegExp(`^##\\s+\\[?v?${escapeRe(version)}\\]?(?![\\w.-])`, 'm').test(text)
+
 /**
  * Place a version's section where it belongs: above the first section whose version is
  * lower, rather than wherever the file happens to start.
@@ -1425,9 +1535,13 @@ function insertChangelogSection(text, version, date, body) {
   }
   // Falling out of the loop means every version section is newer, so the release belongs
   // at the foot. With nothing to compare against it belongs at the head instead: appending
-  // to a date-headed changelog would file the release below its oldest entry.
-  if (!comparable && offsets.length) {
-    return `${text.slice(0, offsets[0])}${entry}\n${text.slice(offsets[0])}`
+  // to a date-headed changelog would file the release below its oldest entry. The head is
+  // below [Unreleased], though, which stays the first section — a first release drafted into
+  // a changelog holding only an empty [Unreleased] used to land above it.
+  if (!comparable) {
+    const unreleased = /^## \[?Unreleased\]?/i
+    const first = offsets.find((offset) => !unreleased.test(text.slice(offset)))
+    if (first !== undefined) return `${text.slice(0, first)}${entry}\n${text.slice(first)}`
   }
   const trimmed = text.trimEnd()
   return `${trimmed}\n\n${entry}`
@@ -1503,7 +1617,7 @@ function withChangelogLinks(text, links, tagPrefix = '') {
 function rollUnreleased(text, version, date) {
   // A heading for this version already exists — possibly with an empty body, which
   // `changelogSection` reports as absent. Rolling again would duplicate the heading.
-  if (new RegExp(`^##\\s+\\[?v?${escapeRe(version)}\\]?(?![\\w.-])`, 'm').test(text)) return null
+  if (hasVersionHeading(text, version)) return null
 
   const heading = /^##\s+\[?Unreleased\]?[^\n]*$/im
   const match = heading.exec(text)
@@ -1611,6 +1725,53 @@ function expandPaths(pattern) {
   return current
 }
 
+/**
+ * crates.io's default ceiling on an uploaded `.crate`, in bytes: `10 * 1024 * 1024` in
+ * crates.io's src/config/publish_limits.rs. The registry can raise it for one crate on
+ * request, but a crate over it is otherwise refused at upload — after the tag and the push.
+ */
+const CRATES_IO_MAX_BYTES = 10 * 1024 * 1024
+
+/**
+ * The `cargo package` argv that builds exactly what a `cargo publish` command would upload,
+ * so preflight can find a missing file or an oversized archive before anything is tagged.
+ *
+ * Deriving it from the publish command rather than guessing keeps the selection the same:
+ * `-p`, `--workspace`, `--manifest-path`, `--features` and `--no-verify` mean the same thing
+ * to both subcommands, so a workspace packages each crate it will publish. Only the flags
+ * `cargo package` does not take are dropped (`--dry-run`, `--token`).
+ *
+ * `--locked` is added when the repository has a `Cargo.lock`: publishing verifies against
+ * it, and a stale one is a failure better found now. Without a lockfile it would refuse
+ * outright, and plenty of libraries do not commit one. `--allow-dirty` is added only when
+ * the tree is dirty — preflight reports that on its own, or the commit step is about to
+ * make it clean — so the package check still says something useful.
+ *
+ * A command that is not a plain `cargo publish …` (a pipeline, quoting, an env prefix) is
+ * not taken apart: there is no reliable way to know what it uploads.
+ *
+ * @returns {string[] | null} args for `cargo`, or null when it cannot be derived
+ */
+function cargoPackageArgs(command, { dirty = false, lockfile = false } = {}) {
+  if (!/^cargo\s+publish(?:\s|$)/.test(command.trim()) || /[;&|<>`$()'"\\]/.test(command)) {
+    return null
+  }
+  const words = command.trim().split(/\s+/).slice(2)
+  const args = ['package']
+  for (let i = 0; i < words.length; i += 1) {
+    const word = words[i]
+    if (word === '--dry-run' || word === '-n' || word.startsWith('--token=')) continue
+    if (word === '--token') {
+      i += 1
+      continue
+    }
+    args.push(word)
+  }
+  if (lockfile && !args.includes('--locked')) args.push('--locked')
+  if (dirty && !args.includes('--allow-dirty')) args.push('--allow-dirty')
+  return args
+}
+
 /**
  * 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.
@@ -2042,7 +2203,16 @@ const VALUE_OPTIONS = new Set([
 ])
 
 /** Flags that take no value. With VALUE_OPTIONS, the whole vocabulary this file accepts. */
-const BOOLEAN_FLAGS = new Set(['--dry-run', '--yes', '-y', '--commit', '--help', '-h', '--sync'])
+const BOOLEAN_FLAGS = new Set([
+  '--dry-run',
+  '--yes',
+  '-y',
+  '--commit',
+  '--package',
+  '--help',
+  '-h',
+  '--sync',
+])
 
 /** The version or bump target: the only argument that is neither a flag nor a flag's value. */
 const positionals = []
@@ -2077,6 +2247,14 @@ if (positionals.length > 1) {
     : ''
   abort(`unexpected argument${extras.length > 1 ? 's' : ''}: ${extras.join(' ')}${hint}`)
 }
+// Only a pre* bump reads --preid. Anywhere else it was accepted and dropped, so
+// `auto --preid beta` released a stable version to the `latest` dist-tag.
+if (requestedPreid !== undefined && !target?.startsWith('pre')) {
+  abort(
+    `--preid only applies to prepatch, preminor, premajor and prerelease, not ${target ? `"${target}"` : 'a release with no target'}.\n` +
+      `  For a ${requestedPreid} prerelease: release-kit prerelease --preid ${requestedPreid}`,
+  )
+}
 
 // ─────────────────────────────────────────────────────────────────────────────
 // SETUP
@@ -2085,26 +2263,89 @@ if (positionals.length > 1) {
 const root = tryRead('git', ['rev-parse', '--show-toplevel'])
 if (!root) abort('not inside a git repository')
 
-// A release is scoped to the repository: the version, the tag and the push all belong to
-// one git history, so the package released is the one at the git root. Refuse when invoked
-// from a nested package instead — silently releasing the parent is the worse outcome.
+/**
+ * A release is scoped to the repository: the version, the tag and the push all belong to
+ * one git history, so the package released is the one at the git root. `--package` scopes
+ * it to the working directory instead — one package among several in the repository, as
+ * release-train runs it. Its config, manifest, changelog, verify and publish are that
+ * directory's; the commits it reads and the working tree it checks are limited to the
+ * directory; and it tags `<name>@<version>` unless its config names a `tagPrefix`, so
+ * packages sharing a history keep separate tags.
+ */
+const packageMode = flag('--package')
+
+// Without --package, refuse a nested package rather than silently releasing the parent.
 const localManifest = resolve('package.json')
 const rootManifest = join(root, 'package.json')
-if (existsSync(localManifest) && localManifest !== rootManifest) {
+if (!packageMode && existsSync(localManifest) && localManifest !== rootManifest) {
   abort(
     `${relative(root, localManifest)} is a nested package, but a release covers the whole ` +
       `repository.\n\n  Running here would release ${
         existsSync(rootManifest) ? readJson(rootManifest).name : 'the repository root'
       } instead.\n` +
-      '  release-kit handles one package per repository; it does not release workspace members.',
+      '  To release this package on its own — its own tag, commits, changelog and publish —\n' +
+      '  run with --package (release-train does, for a repository holding several).',
   )
 }
-process.chdir(root)
+if (!packageMode) process.chdir(root)
+
+/** The pathspec a package release limits `git log`, `git status` and `git add` to. */
+const SCOPE = packageMode ? ['--', '.'] : []
 
 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(', ')}`)
+
+/**
+ * What each key has to hold. A known key with the wrong shape was accepted and then read as
+ * if it were right: `"steps": "tag,push"` ran no step at all and still reported a release,
+ * `"tagPrefix": null` tagged `null1.1.0`, and a string where an array belongs crashed with a
+ * TypeError after the tag was pushed.
+ */
+const isString = (value) => typeof value === 'string'
+const isStringOrNull = (value) => value === null || isString(value)
+const isStringArray = (value) => Array.isArray(value) && value.every(isString)
+const isObject = (value) => !!value && typeof value === 'object' && !Array.isArray(value)
+const CONFIG_SHAPES = {
+  steps: [isStringArray, 'an array of step names'],
+  tagPrefix: [isString, 'a string'],
+  branch: [isStringOrNull, 'a string, or null'],
+  remote: [isString, 'a string'],
+  changelog: [isStringOrNull, 'a string, or null'],
+  versionFile: [
+    (v) => v === undefined || isStringOrNull(v) || isObject(v),
+    'a path, an object, or null',
+  ],
+  versionFiles: [
+    (v) => Array.isArray(v) && v.every((f) => isString(f) || (isObject(f) && isString(f.path))),
+    'an array of paths or { path, pattern } objects',
+  ],
+  publish: [
+    (v) => v === undefined || isStringOrNull(v) || isStringArray(v),
+    'a command, an array of commands, or null',
+  ],
+  commitMessage: [isString, 'a string'],
+  releaseTitle: [isString, 'a string'],
+  assets: [isStringArray, 'an array of paths'],
+  assistant: [(v) => isStringOrNull(v) || isObject(v), 'a name, an object, or null'],
+  notesFile: [isStringOrNull, 'a path, or null'],
+  versioning: [
+    (v) => ['conventional', 'always-patch', 'always-minor', 'always-major'].includes(v),
+    'one of conventional, always-patch, always-minor, always-major',
+  ],
+  notes: [isString, 'a string'],
+  hiddenTypes: [isStringArray, 'an array of commit types'],
+  ignoreCommits: [isStringArray, 'an array of regexes'],
+  verify: [isStringOrNull, 'a command, or null'],
+  requireGreen: [(v) => typeof v === 'boolean', 'true or false'],
+  hooks: [(v) => isObject(v) && Object.values(v).every(isString), 'an object of command strings'],
+}
+const misshapen = Object.entries(CONFIG_SHAPES)
+  .filter(([key, [valid]]) => !valid(config[key]))
+  .map(([key, [, expected]]) => `  ${key} must be ${expected}, not ${JSON.stringify(config[key])}`)
+if (misshapen.length)
+  abort(`release.config.json has keys of the wrong type:\n${misshapen.join('\n')}`)
 // 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))
@@ -2166,6 +2407,10 @@ const ECOSYSTEM_MANIFESTS = ['package.json', 'pyproject.toml', 'Cargo.toml']
  */
 function detectCompanionFiles(primaryPath, primaryVersion) {
   const companions = []
+  // The lockfile pins the crate's own version, so a bump leaves it stale — whether
+  // Cargo.toml is the version source or a manifest kept in step with one. A plain crate was
+  // the case missed: `cargo publish` then refused the dirty lockfile, after the push.
+  if (primaryPath === 'Cargo.toml' && existsSync('Cargo.lock')) companions.push('Cargo.lock')
   for (const candidate of ECOSYSTEM_MANIFESTS) {
     if (candidate === primaryPath || !existsSync(candidate)) continue
     const found = readVersionFrom({ path: candidate })
@@ -2281,6 +2526,19 @@ function versionFromLastTag() {
   return releaseTags()[0]?.version ?? null
 }
 
+// A package's tags are `<name>@<version>`, the scheme release-train reads, unless its
+// config names a prefix. Set before anything reads a tag.
+if (packageMode && !Object.hasOwn(userConfig, 'tagPrefix')) {
+  const name = manifest?.name ?? (versionFile ? readNameFrom(versionFile) : null)
+  if (!name) {
+    abort(
+      '--package tags a release <name>@<version>, and no package name was found here.\n' +
+        '  Set "tagPrefix" in this package\'s release.config.json.',
+    )
+  }
+  config.tagPrefix = `${name}@`
+}
+
 const currentVersion = versionFile ? readVersionFrom(versionFile) : versionFromLastTag()
 if (versionFile && !currentVersion) {
   abort(`could not read a version from ${versionFile.path}`)
@@ -2294,7 +2552,10 @@ const goModule = existsSync('go.mod')
   ? (/^module\s+(\S+)/m.exec(readFileSync('go.mod', 'utf8'))?.[1] ?? null)
   : null
 const projectName =
-  manifest?.name ?? (versionFile ? readNameFrom(versionFile) : null) ?? goModule ?? basename(root)
+  manifest?.name ??
+  (versionFile ? readNameFrom(versionFile) : null) ??
+  goModule ??
+  basename(process.cwd())
 
 /**
  * Manifests found beside the primary one that carry the same version. Detected only when
@@ -2567,9 +2828,35 @@ function versionShipped(v) {
  */
 function unfinishedRelease() {
   const [newest] = releaseTags()
-  if (!newest || versionShipped(newest.version) !== false) return null
+  if (!newest) return null
   const at = tryRead('git', ['rev-list', '-n', '1', newest.name])
-  return at && at === tryRead('git', ['rev-parse', 'HEAD']) ? newest : null
+  if (!at || at !== tryRead('git', ['rev-parse', 'HEAD'])) return null
+  const shipped = versionShipped(newest.version)
+  if (shipped === false) return { ...newest, missing: 'the registry' }
+  // With no registry to ask — `publish: null`, or one that could not answer — the push is
+  // the last step that leaves a mark to check. A tag at HEAD the remote does not have is a
+  // release that died before or during the push.
+  if (shipped === null && runs('push') && tagOnRemote(newest.name) === false) {
+    return { ...newest, missing: config.remote }
+  }
+  return null
+}
+
+/**
+ * Whether the remote has this tag: false only when it answered without it, null when it
+ * could not be asked.
+ *
+ * @param {string} name
+ * @returns {boolean | null}
+ */
+function tagOnRemote(name) {
+  try {
+    read('git', ['ls-remote', '--exit-code', '--tags', config.remote, `refs/tags/${name}`])
+    return true
+  } catch (err) {
+    // --exit-code exits 2 for "no matching refs"; anything else is the remote not answering.
+    return err.status === 2 ? false : null
+  }
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -2586,6 +2873,8 @@ let autoBump = null
 
 /** The tag of a previous release this run is finishing rather than starting. */
 let resuming = null
+/** What that release never reached: the registry, or the remote. */
+let resumingMissing = null
 
 /**
  * A release tagged at HEAD that never reached the registry, found while resolving a
@@ -2602,7 +2891,7 @@ let unfinishedAtHead = null
  * ship a tree the tag does not describe; that work belongs in the next version, which is
  * what the shipped-tag baseline makes sure it is released as.
  */
-const wouldCommitMore = !!tryRead('git', ['status', '--porcelain']) && runs('commit')
+const wouldCommitMore = !!tryRead('git', ['status', '--porcelain', ...SCOPE]) && runs('commit')
 
 let version
 if (!target) {
@@ -2622,7 +2911,7 @@ if (!target) {
   }
   const pending = wouldCommitMore ? null : unfinishedRelease()
   if (pending) {
-    ;({ name: resuming, version } = pending)
+    ;({ name: resuming, version, missing: resumingMissing } = pending)
   } else {
     const { commits, lastTag } = commitsSinceLastTag({ shipped: true })
     if (!commits.length) {
@@ -2731,12 +3020,15 @@ function runHook(name) {
  */
 function dirtyPaths() {
   return (
-    (tryRead('git', ['status', '--porcelain']) ?? '')
+    (tryRead('git', ['status', '--porcelain', ...SCOPE]) ?? '')
       .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))
+      // Porcelain paths are relative to the repository root; everything they are compared
+      // with and staged as is relative to the working directory, which --package moves.
+      .map((path) => relative(process.cwd(), join(root, path)))
   )
 }
 
@@ -2796,12 +3088,12 @@ if (autoBump) {
 }
 
 if (resuming) {
-  ok(`finishing ${resuming}: it was tagged and pushed, but never reached the registry`)
+  ok(`finishing ${resuming}: it was tagged, but never reached ${resumingMissing}`)
 }
 
 if (unfinishedAtHead) {
   fail(
-    `${unfinishedAtHead.name} is tagged at HEAD but never reached the registry, and a ` +
+    `${unfinishedAtHead.name} is tagged at HEAD but never reached ${unfinishedAtHead.missing}, and a ` +
       `${target} bump would release ${version} from the same commit and leave it that way.\n` +
       `       Finish it instead: re-run with no target, or with auto.`,
   )
@@ -2898,6 +3190,31 @@ if (bumping) {
   }
 }
 
+// A configured list is never extended, so a Cargo.toml written without the Cargo.lock beside
+// it leaves the lockfile on the old version. Publishing is where that breaks: `cargo publish`
+// refuses a dirty tree, after the tag and the push. Say so before either.
+if (bumping && publishTargets.some((target) => target.cli === 'cargo')) {
+  const written = new Set(versionTargets.map((source) => source.path))
+  for (const source of versionTargets) {
+    if (basename(source.path) !== 'Cargo.toml') continue
+    const lockPath = join(dirname(source.path), 'Cargo.lock')
+    if (written.has(lockPath) || !existsSync(lockPath)) continue
+    let recorded = null
+    try {
+      recorded = readVersionFrom({ path: lockPath })
+    } catch {
+      // A lockfile with nothing beside it to scope by: not this check's question.
+    }
+    if (recorded && recorded !== version) {
+      fail(
+        `${lockPath} records ${readNameFrom(source) ?? 'the crate'} ${recorded}, and nothing ` +
+          `will bump it — \`cargo publish\` would refuse the stale lockfile after the push.\n` +
+          `       Add "${lockPath}" to versionFiles in release.config.json.`,
+      )
+    }
+  }
+}
+
 if (bumping && currentVersion && compareVersions(version, currentVersion) <= 0) {
   fail(`${version} is not greater than the current version ${currentVersion}`)
 } else if (bumping && currentVersion) {
@@ -2922,7 +3239,7 @@ if (bumping && currentVersion && compareVersions(version, currentVersion) <= 0)
   ok(`releasing ${version} (no version file; the tag is the version)`)
 }
 
-const dirty = tryRead('git', ['status', '--porcelain'])
+const dirty = tryRead('git', ['status', '--porcelain', ...SCOPE])
 if (dirty === null) fail('could not read git status')
 else if (dirty && runs('commit')) {
   const entries = dirty.split('\n')
@@ -3008,6 +3325,123 @@ if (!succeeds('git', ['remote', 'get-url', config.remote])) {
   }
 }
 
+/**
+ * Check run conclusions that mean the commit is not fit to release. `stale` is GitHub giving
+ * up on a run that never finished, which is not a pass either.
+ */
+const RED_CONCLUSIONS = new Set(['failure', 'cancelled', 'timed_out', 'action_required', 'stale'])
+
+/**
+ * Whether GitHub reports the commit being released as green — the gate `requireGreen` opts
+ * into, so a release cannot be cut from a commit CI failed on or has not finished with.
+ *
+ * Both of GitHub's check systems are read. Check runs are what Actions and GitHub Apps
+ * report; commit statuses are the older API that external CI (Buildkite, Jenkins, older
+ * integrations) still posts to. Reading only one would call a commit green while the other
+ * system has it red. The combined status's own `state` is not used: it says `pending` for a
+ * commit with no statuses at all, so the individual statuses are what count.
+ *
+ * Only `success` counts as a pass. `neutral` and `skipped` are not failures, but a commit
+ * whose every check was skipped has not been verified by anything, and zero checks is the
+ * same answer — both are refused rather than read as green.
+ *
+ * When this runs inside GitHub Actions, the job running it is itself an unfinished check run
+ * on the same commit — the `workflow_run` recipe in the README releases exactly the commit
+ * it runs on — and waiting for it would wait forever. Check runs belonging to the current
+ * workflow run are therefore skipped; jobs in the same workflow are what `needs:` orders.
+ *
+ * `{owner}/{repo}` is filled in by gh from the checkout, the same way `gh release create`
+ * resolves the repository the release step publishes to.
+ */
+function checkHeadIsGreen(sha) {
+  const api = (path, jq) => tryRead('gh', ['api', '--paginate', path, '--jq', jq])
+  const checkRuns = api(
+    `repos/{owner}/{repo}/commits/${sha}/check-runs?per_page=100`,
+    '.check_runs[] | [.name, .status, (.conclusion // ""), (.details_url // "")] | @tsv',
+  )
+  const statuses = api(
+    `repos/{owner}/{repo}/commits/${sha}/status?per_page=100`,
+    '.statuses[] | [.context, .state] | @tsv',
+  )
+  if (checkRuns === null || statuses === null) {
+    fail(`requireGreen: could not read the checks on ${sha.slice(0, 8)} from GitHub (gh api)`)
+    return
+  }
+  const ownRun =
+    process.env.GITHUB_ACTIONS === 'true' && process.env.GITHUB_RUN_ID
+      ? `/actions/runs/${process.env.GITHUB_RUN_ID}/`
+      : null
+  const rows = (text) =>
+    text
+      .split('\n')
+      .filter((line) => line.trim())
+      .map((line) => line.split('\t'))
+
+  const red = []
+  const waiting = []
+  let passed = 0
+  for (const [name, status, conclusion, url = ''] of rows(checkRuns)) {
+    if (ownRun && url.includes(ownRun)) continue
+    if (status !== 'completed') waiting.push(`${name} (${status})`)
+    else if (RED_CONCLUSIONS.has(conclusion)) red.push(`${name} (${conclusion})`)
+    else if (conclusion === 'success') passed += 1
+  }
+  for (const [context, state] of rows(statuses)) {
+    if (state === 'failure' || state === 'error') red.push(`${context} (${state})`)
+    else if (state === 'pending') waiting.push(`${context} (pending)`)
+    else if (state === 'success') passed += 1
+  }
+
+  const at = `HEAD (${sha.slice(0, 8)})`
+  if (red.length) {
+    fail(`requireGreen: ${at} is not green — ${red.join(', ')}`)
+  } else if (waiting.length) {
+    fail(
+      `requireGreen: checks on ${at} have not finished — ${waiting.join(', ')}.\n` +
+        '       Wait for them to complete, then re-run.',
+    )
+  } else if (!passed) {
+    fail(
+      `requireGreen: no check has passed on ${at} — nothing has verified it.\n` +
+        '       Push it and wait for CI, or turn requireGreen off for a repository without CI.',
+    )
+  } else {
+    ok(`${at} is green (${passed} check${passed === 1 ? '' : 's'} passed)`)
+  }
+}
+
+// Opt-in: the commit being released has to be one CI has seen and passed. That means it is
+// on the remote — a local commit has no checks to read — and that what the commit step is
+// about to add is not part of the release, since CI never saw that either.
+if (config.requireGreen) {
+  const upstream = branch && !detached ? `${config.remote}/${branch}` : null
+  const sha = tryRead('git', ['rev-parse', 'HEAD'])
+  const onRemote =
+    upstream && succeeds('git', ['rev-parse', '--verify', '--quiet', `refs/remotes/${upstream}`])
+  const ahead = onRemote ? tryRead('git', ['rev-list', '--count', `${upstream}..HEAD`]) : null
+  if (dirty && runs('commit')) {
+    fail(
+      'requireGreen: the working tree would be committed and released without CI having ' +
+        'run on it.\n       Commit and push it, wait for the checks, then release.',
+    )
+  }
+  if (!succeeds('gh', ['--version']) || !succeeds('gh', ['auth', 'status'])) {
+    fail('requireGreen reads the checks with `gh`, which is not installed or not authenticated')
+  } else if (!onRemote) {
+    fail(
+      `requireGreen: ${upstream ?? 'this branch'} does not exist on ${config.remote}, so no ` +
+        'check has run on HEAD. Push it and wait for CI.',
+    )
+  } else if (ahead !== '0') {
+    fail(
+      `requireGreen: HEAD is ${ahead ?? 'an unknown number of'} commit(s) ahead of ` +
+        `${upstream}, so CI has not seen it. Push it and wait for the checks.`,
+    )
+  } else if (sha) {
+    checkHeadIsGreen(sha)
+  }
+}
+
 // 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
@@ -3127,10 +3561,32 @@ if (!runs('release')) {
  */
 const OIDC_CLIS = new Set([...NPM_CLIS, 'uv'])
 
+/**
+ * The oldest npm CLI that publishes over OIDC. An older one finds no token and fails the
+ * publish — after the tag and the push, since nothing before that step asks it anything.
+ * https://docs.npmjs.com/trusted-publishers states the minimum; pnpm and bun implement the
+ * exchange themselves and document no equivalent, so only npm is checked.
+ */
+const NPM_OIDC_MIN = '11.5.1'
+
 /** Whether one publish CLI can publish at all: OIDC, a token, or a live session. */
 function checkCredentials({ cli, registry, command }) {
   if (isTrustedPublishing && OIDC_CLIS.has(cli)) {
     ok(`${cli}: trusted publishing (OIDC) — no token needed`)
+    if (cli === 'npm') {
+      const npmVersion = tryRead('npm', ['--version'])
+      if (!npmVersion || !parseVersion(npmVersion)) {
+        warn(
+          `npm: could not read its version — trusted publishing needs npm ${NPM_OIDC_MIN} or later`,
+        )
+      } else if (compareVersions(npmVersion, NPM_OIDC_MIN) < 0) {
+        fail(
+          `npm ${npmVersion} cannot publish with trusted publishing, which needs npm ` +
+            `${NPM_OIDC_MIN} or later — the publish would fail after the tag and push.\n` +
+            '       Update it before releasing: npm install -g npm@latest',
+        )
+      }
+    }
     // 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,
@@ -3169,6 +3625,75 @@ function checkCredentials({ cli, registry, command }) {
   }
 }
 
+/**
+ * Package what `cargo publish` will upload, before the tag and the push rather than after.
+ *
+ * `cargo publish` packages and verifies as its first act, so a file left out by `include`
+ * or `exclude`, a manifest crates.io rejects, a crate that does not build from its own
+ * archive, or one over the upload limit is discovered only once the release is tagged and
+ * pushed. This runs the same packaging now. It builds the crate, as publishing does, so it
+ * costs a compile.
+ *
+ * It packages the tree as it is — the version is not bumped yet. The version number is the
+ * one thing that differs from what will be uploaded, and it changes neither the file list,
+ * the metadata, nor the size.
+ */
+function checkCratePackage(target) {
+  const args = cargoPackageArgs(target.command, {
+    dirty: !!dirty,
+    lockfile: existsSync('Cargo.lock'),
+  })
+  if (!args) {
+    note(`cargo: \`${target.command}\` is not a plain cargo publish — not packaging it first`)
+    return
+  }
+  const started = Date.now()
+  try {
+    // A verify build prints every crate it compiles; Node's 1 MiB default would overflow.
+    execFileSync('cargo', args, { stdio: 'pipe', encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
+  } catch (err) {
+    const tail = `${err.stdout ?? ''}${err.stderr ?? ''}`.trim().split('\n').slice(-12).join('\n')
+    fail(`\`cargo ${args.join(' ')}\` failed — \`${target.command}\` would too:\n${indent(tail)}`)
+    return
+  }
+  const metadata = tryRead('cargo', ['metadata', '--no-deps', '--format-version', '1'])
+  let targetDir = null
+  try {
+    targetDir = metadata ? JSON.parse(metadata).target_directory : null
+  } catch {
+    targetDir = null
+  }
+  const packageDir = targetDir ? join(targetDir, 'package') : null
+  // Only archives this run wrote: target/package keeps every earlier version too.
+  const crates =
+    packageDir && existsSync(packageDir)
+      ? readdirSync(packageDir)
+          .filter((name) => name.endsWith('.crate'))
+          .map((name) => {
+            const { size, mtimeMs } = statSync(join(packageDir, name))
+            return { name, size, mtimeMs }
+          })
+          .filter(({ mtimeMs }) => mtimeMs >= started - 1000)
+      : []
+  if (!crates.length) {
+    warn('cargo package passed, but no .crate it wrote was found to check against the size limit')
+    return
+  }
+  const limitMb = (CRATES_IO_MAX_BYTES / 1024 / 1024).toFixed(0)
+  for (const { name, size } of crates) {
+    const mb = (size / 1024 / 1024).toFixed(1)
+    if (size > CRATES_IO_MAX_BYTES) {
+      fail(
+        `${name} is ${mb} MiB, over crates.io's ${limitMb} MiB upload limit.\n` +
+          '       Trim it with `include`/`exclude` in Cargo.toml (`cargo package --list` shows ' +
+          'what goes in), or ask crates.io to raise the limit for this crate.',
+      )
+    } else {
+      ok(`cargo package: ${name} (${mb} MiB)`)
+    }
+  }
+}
+
 /** Commands whose version is already on the registry, so the publish step skips them. */
 const alreadyPublished = new Set()
 if (!publishTargets.length) {
@@ -3192,6 +3717,7 @@ if (!publishTargets.length) {
       alreadyPublished.add(target.command)
       note(`${target.name}@${version} is already published — will skip \`${target.command}\``)
     }
+    if (target.cli === 'cargo' && !alreadyPublished.has(target.command)) checkCratePackage(target)
   }
 }
 
@@ -3244,6 +3770,18 @@ const notesDeferred = !!(dirty && runs('commit'))
  */
 let notesPending = false
 
+/**
+ * Entries the assistant flagged as unsure in the notes it drafted — see `uncertainEntries`.
+ * Only a draft can carry them: hand-written and commit-derived notes are someone's words.
+ */
+let unsure = []
+
+/**
+ * Whether a person answers the confirmation prompt. Under --yes, or with no terminal to ask
+ * on, nobody reviews anything before it is tagged and published.
+ */
+const confirming = !assumeYes && !dryRun && !!process.stdin.isTTY
+
 /**
  * Notes for a version, in descending order of how much they can be trusted:
  * an assistant's prose when one is configured, otherwise the commits grouped by
@@ -3284,11 +3822,30 @@ function draftNotesFor(v) {
     )
   }
   note(`drafting notes from ${subjects.length} commit(s) with ${assistantName}...`)
+  const drafted = draftReleaseNotes(v, commits, lastTag, remoteLinks(config.remote))
+  unsure = uncertainEntries(drafted)
   return (
-    draftReleaseNotes(v, commits, lastTag, remoteLinks(config.remote)) ??
+    drafted ??
     changelogFromCommits(commits, remoteLinks(config.remote), config.hiddenTypes, contributors)
   )
 }
+
+/**
+ * The flagged entries, listed for whoever has to resolve them. Non-interactively nobody can,
+ * so preflight refuses; at the prompt the person answering is the review.
+ */
+const listUnsure = () => {
+  const one = unsure.length === 1
+  const what = `${unsure.length} drafted entr${one ? 'y' : 'ies'} ${UNSURE}`
+  return `${assistantName} marked ${what} — it could not tell what ${one ? 'it means' : 'they mean'} for users:\n${indent(unsure.join('\n'))}`
+}
+
+/** What to do about flagged entries when nobody is at the prompt to review them. */
+const handWritten = config.changelog
+  ? `, or write the notes into [Unreleased] in ${config.changelog} with them resolved — a hand-written section wins over a draft`
+  : ''
+const UNSURE_FIX = `       Re-run without --yes in a terminal to review them at the prompt${handWritten}.`
+
 const changelogText =
   config.changelog && existsSync(config.changelog) ? readFileSync(config.changelog, 'utf8') : null
 if (changelogText) reportChangelogOrder(changelogText)
@@ -3318,18 +3875,37 @@ if (notesSource === 'github') {
 
   // Generate, either because nothing was written or because a source was named.
   if (!notes) {
+    // Candidates' sections are not a source for the stable release: its notes come from all
+    // the commits since the last stable tag. Say so while there is still time to write the
+    // wording that should survive into [Unreleased] — nothing else would.
+    const candidates =
+      notesSource === 'auto' && changelogText ? candidateSections(changelogText, version) : []
+    if (candidates.length) {
+      warn(
+        `${config.changelog} has sections for ${candidates.join(', ')}, but ${version} ` +
+          'has none of its own, so its notes are generated from every commit since the last ' +
+          'stable release.\n       Anything edited into those sections is not carried over. ' +
+          `To release with it, write the ${version} notes into [Unreleased] and re-run.`,
+      )
+    }
     if (notesDeferred) {
       notesPending = true
       ok(`release notes will be ${assistant ? 'drafted' : 'generated'} after the commit`)
     } else {
       draftedNotes = draftNotesFor(version)
+      if (unsure.length) {
+        if (confirming) warn(`${listUnsure()}\n       They are shown again at the prompt.`)
+        else fail(`${listUnsure()}\n${UNSURE_FIX}`)
+      }
       if (draftedNotes) {
         notes = draftedNotes
-        ok(
-          notesSource === 'commits' || !assistant
-            ? 'release notes built from the commit log'
-            : `release notes drafted by ${assistantName}`,
-        )
+        // An "ok" under the failure above would contradict it: these notes are refused.
+        if (!unsure.length || confirming)
+          ok(
+            notesSource === 'commits' || !assistant
+              ? 'release notes built from the commit log'
+              : `release notes drafted by ${assistantName}`,
+          )
       } else if (notesSource === 'auto') {
         warn(
           `no ${config.changelog ?? 'changelog'} section and nothing to draft from — GitHub will generate the notes`,
@@ -3346,6 +3922,16 @@ for (const asset of config.assets) {
   else fail(`asset ${asset} does not exist`)
 }
 
+/**
+ * Whether drafted notes still have to be filed in the changelog. A named source (`commits`,
+ * `assistant`) drafts even when the section exists — a resume, or one written by hand — and
+ * filing it again would duplicate the heading and commit past a reused tag.
+ */
+const draftedSectionMissing = () =>
+  !!config.changelog &&
+  existsSync(config.changelog) &&
+  !hasVersionHeading(readFileSync(config.changelog, 'utf8'), version)
+
 // Reusing a tag is the resume path, and a resume writes nothing. If this run would still
 // produce a commit, that commit moves HEAD past the tag and the release ends up tagged at
 // the wrong revision — which is silent until someone checks out the tag, and worse for the
@@ -3356,6 +3942,7 @@ const wouldCommit = [
   // The roll is computed whenever [Unreleased] is populated, because the notes come from
   // it either way; it is only written — and only becomes a commit — when the step runs.
   rolledChangelog && runs('changelog') && 'a changelog entry',
+  draftedNotes && runs('changelog') && draftedSectionMissing() && 'a drafted changelog section',
 ].filter(Boolean)
 if (taggedCommit && runs('tag') && wouldCommit.length) {
   fail(
@@ -3371,7 +3958,8 @@ if (taggedCommit && runs('tag') && wouldCommit.length) {
 if (config.verify) {
   note(`running verify: ${config.verify}`)
   try {
-    execSync(config.verify, { stdio: 'pipe', encoding: 'utf8' })
+    // A test suite or a build can print far more than Node's 1 MiB default capture.
+    execSync(config.verify, { stdio: 'pipe', encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
     ok(`verify passed: ${config.verify}`)
   } catch (err) {
     const tail = `${err.stdout ?? ''}${err.stderr ?? ''}`.trim().split('\n').slice(-12).join('\n')
@@ -3401,7 +3989,7 @@ let commitMessage = null
 let didStage = false
 if (dirty && runs('commit') && !dryRun) {
   step('Stage the working tree')
-  mutate('git', ['add', '--all'])
+  mutate('git', ['add', '--all', ...SCOPE])
   didStage = true
   commitMessage = assistant ? draftCommitMessage() : null
   if (!commitMessage) {
@@ -3417,19 +4005,43 @@ if (dirty && runs('commit') && !dryRun) {
   console.log(indent(commitMessage))
 }
 
-if (!assumeYes && !dryRun && process.stdin.isTTY) {
-  if (notes) console.log(`\n${bold('Release notes')}\n${indent(notes)}`)
+/** Ask a yes/no question on the terminal; anything but yes is no. */
+async function ask(question) {
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   let answer = ''
   try {
-    answer = await rl.question(`\nRelease ${bold(tag)} of ${projectName}? [y/N] `)
+    answer = await rl.question(question)
   } catch {
     // Ctrl+C or Ctrl+D at the prompt rejects the question. That is a decline, not a
     // crash — without this it exits on an unhandled AbortError and a stack trace.
   } finally {
     rl.close()
   }
-  if (!/^y(es)?$/i.test(answer.trim())) {
+  return /^y(es)?$/i.test(answer.trim())
+}
+
+/**
+ * Show the notes, with the entries the assistant was unsure of called out, and ask. A yes is
+ * the review those entries were waiting for, so the marker comes off before anything is
+ * written: `[???]` in a tag or on a release page helps nobody.
+ */
+async function confirmRelease(question) {
+  if (notes) console.log(`\n${bold('Release notes')}\n${indent(notes)}`)
+  if (unsure.length) {
+    console.log(`\n${yellow(bold('Review these'))} — ${listUnsure()}`)
+    console.log(dim('  Answering y releases them as shown, without the marker.'))
+  }
+  const yes = await ask(question)
+  if (yes && unsure.length) {
+    notes = withoutUnsureMarkers(notes)
+    if (draftedNotes) draftedNotes = withoutUnsureMarkers(draftedNotes)
+    unsure = []
+  }
+  return yes
+}
+
+if (confirming) {
+  if (!(await confirmRelease(`\nRelease ${bold(tag)} of ${projectName}? [y/N] `))) {
     // Leave the index exactly as it was found.
     if (didStage) mutate('git', ['reset', '--quiet'])
     abort('cancelled')
@@ -3451,6 +4063,18 @@ if (dirty && runs('commit')) {
   if (notesPending && !dryRun) {
     draftedNotes = draftNotesFor(version)
     if (draftedNotes) notes = draftedNotes
+    // These notes were drafted after the prompt, so nobody has seen them. Flagged entries
+    // get the review preflight would have given them; the commit just made stays, and a
+    // re-run drafts from a clean tree — before the prompt, where they can be reviewed.
+    if (unsure.length) {
+      const committed =
+        '       The working tree is committed; nothing else has changed. Re-running drafts the ' +
+        'notes during preflight, before anything else happens.'
+      if (!confirming) abort(`${listUnsure()}\n${UNSURE_FIX}\n${committed}`)
+      if (!(await confirmRelease(`\nRelease ${bold(tag)} with these notes? [y/N] `))) {
+        abort(`cancelled\n${committed}`)
+      }
+    }
   }
 }
 
@@ -3481,7 +4105,7 @@ if (rolledChangelog && runs('changelog')) {
   if (dryRun) console.log(`  ${yellow('would write')} ${config.changelog}`)
   else writeFileSync(config.changelog, linked(rolledChangelog))
   staged.push(config.changelog)
-} else if (runs('changelog') && draftedNotes && config.changelog && existsSync(config.changelog)) {
+} else if (runs('changelog') && draftedNotes && draftedSectionMissing()) {
   step(`Add the drafted ${version} section to ${config.changelog}`)
   if (dryRun) console.log(`  ${yellow('would write')} ${config.changelog}`)
   else {