@entro314labs/release-kit 2.9.4 → 2.10.0

package/README.md

@@ -97,7 +97,7 @@ release-kit minor
 No global state to drift, no install step, and the version is explicit in the command.
 
 ```sh
-npx @entro314labs/release-kit@2.3.0 minor --yes
+npx @entro314labs/release-kit@2.9.4 minor --yes
 ```
 
 ### Vendored — no registry at release time
@@ -164,7 +164,8 @@ footer) is a major, a `feat:` is a minor, anything else is a patch. Below `1.0.0
 softened — a breaking change bumps the minor rather than jumping to `1.0.0`. A commit body
 containing `Release-As: 2.0.0` pins the version outright. It always prints what it inferred
 and why before doing anything. Set `"versioning"` to `always-patch`, `always-minor` or
-`always-major` to never infer.
+`always-major` to never infer. A `Notes:` line in a body sets what the release notes say
+about that commit — see [Release notes](#release-notes).
 
 | Target                               | From `1.2.3`                                     | From `2.0.0-beta.1` |
 | ------------------------------------ | ------------------------------------------------ | ------------------- |
@@ -227,7 +228,7 @@ commit released is the **pull request title**, which no hook ever sees — check
 - name: Lint the pull request title
   env:
     TITLE: ${{ github.event.pull_request.title }}
-  run: npx @entro314labs/release-kit@2.8.0 lint-commits --subject "$TITLE"
+  run: npx @entro314labs/release-kit@2.9.4 lint-commits --subject "$TITLE"
 ```
 
 Pass the title through `env`, never through `${{ }}` inside `run:` — a pull request title is
@@ -288,8 +289,11 @@ Notes resolve in this order:
 2. The `## [Unreleased]` section, if the version has no section of its own — this is the
    same content that step 2 above is about to promote.
 3. The commits grouped by Conventional Commit type — Features, Bug Fixes, Performance
-   Improvements, Reverts, with breaking changes first and chores, CI and docs hidden. Each
-   bullet links to its commit, and `closes #12` / `fixes #34` in a message becomes a link to
+   Improvements, Reverts, Dependencies, Documentation, Code Refactoring, Build System,
+   Continuous Integration, Tests, Styles, Miscellaneous Chores — with breaking changes
+   first. Every type is reported, since a changelog is a record; list the ones to leave out
+   in `hiddenTypes` — `["chore", "ci", "docs"]`, say, for a shorter list. A type outside
+   the table, such as `security:`, lands under Other Changes. Each bullet links to its commit, and `closes #12` / `fixes #34` in a message becomes a link to
    the issue. A `BREAKING CHANGE:` footer is used in place of the subject, since it explains
    the break. A commit reverted within the same release drops out along with its revert.
    A **New Contributors** section names anyone whose first commit to the repository is in
@@ -299,6 +303,20 @@ Notes resolve in this order:
    rather than something that requires an assistant.
 4. Otherwise GitHub generates them from the commits since the previous tag.
 
+**A `Notes:` line in a commit body is the author's wording for the entry.** Commit-derived
+notes use it in place of the subject (and in place of a `BREAKING CHANGE:` footer), and an
+[assistant](#-assistant-optional) is handed it with the commit and told to keep it.
+`Notes: no-notes` leaves the commit out of the notes entirely — both kinds — for work that
+has to be a `fix:` or `feat:` for the version bump but is not news to anyone upgrading. The
+bump itself is unaffected: the trailer decides what is said about a change, not whether it
+counts.
+
+```text
+fix(ui): raise the badge z-index above the progress bar
+
+Notes: The pull request badge stays visible while a push is in progress
+```
+
 **Which tag the history is read from** is the highest version tag carrying the configured
 prefix that is reachable from `HEAD` — not the nearest tag. A repository carrying tags that
 are not releases (a rolling `latest-beta` marker, a `nightly`) is unaffected by them, and a
@@ -308,7 +326,11 @@ patch tagged on top of a later minor does not drag the baseline backwards.
 `2.0.0-rc.1` and `-rc.2` reads history from the last _stable_ tag, so the notes describe
 everything the release ships rather than the gap between the last two candidates — which
 is usually just the release commit. Releasing a candidate is unchanged: each one's notes
-say what changed in that candidate.
+say what changed in that candidate. The candidates' own changelog sections are not a source
+for the stable release: its notes are generated from those commits, so wording edited into
+a `[2.0.0-rc.1]` section does not carry over. The sections stay in the file, preflight warns
+when it finds them, and writing the `2.0.0` notes into `[Unreleased]` before releasing is
+how hand-written wording reaches the stable release.
 
 `--notes <source>` forces one instead of walking that list: `changelog`, `assistant`,
 `commits`, or `github`. A named source that produces nothing is an error rather than a
@@ -366,9 +388,13 @@ rather than stopping at the first problem.
 - `gh` is installed and authenticated
 - Commit and tag signing can actually sign, and the key is one GitHub will accept
 - The publishing CLI is authenticated, and the version is not already published
+- A crate that `cargo publish` will upload packages cleanly (`cargo package`) and fits
+  crates.io's 10 MiB upload limit — see [below](#crates-are-packaged-in-preflight)
 - The previous release actually reached the registry — one that did not is either finished
   by this run or absorbed into it _(warning)_
 - Configured release assets exist
+- With `"requireGreen": true`, HEAD is on the remote and GitHub reports it green — see
+  [below](#requiring-a-green-head)
 - The configured `verify` command passes — the project's own gate (tests, build) runs
   before anything mutates, instead of a `prepublishOnly` hook failing after the commit,
   tag and push
@@ -378,10 +404,60 @@ rather than stopping at the first problem.
   previous tag reachable it passes, without one it fails `auto` (the bump would be inferred
   from partial history) and warns otherwise
 - A changelog section for the version exists _(warning — it falls back to generated notes)_
+- Notes drafted by an [assistant](#-assistant-optional) carry no entry it marked `[???]`
+  as unsure — refused under `--yes` or without a terminal, listed for review at the prompt
+  otherwise
 
 Under `--dry-run` the failures are reported and then the remaining steps are shown anyway,
 so you can see the whole plan without fixing the blockers first.
 
+### Crates are packaged in preflight
+
+`cargo publish` packages and verifies the crate as its first act, so a file your
+`include`/`exclude` left out, metadata crates.io refuses, a crate that does not build from
+its own archive, or an archive over crates.io's 10 MiB limit used to surface only after the
+release was tagged and pushed. When a `cargo publish` command is going to run, preflight
+runs `cargo package` with the same arguments first — `-p`, `--workspace`,
+`--manifest-path`, `--features` and `--no-verify` carry over, so a workspace packages each
+crate it will publish — and refuses on a failure or an oversized `.crate`.
+
+- It packages the tree before the version bump. That is enough because the bump writes
+  the version into `Cargo.toml` _and_ `Cargo.lock` together, so the tree `cargo publish`
+  sees differs only in the version number, which changes neither the file list nor the
+  size. A `Cargo.lock` left on the old version would dirty the tree after the push instead:
+  it is detected beside a `Cargo.toml` version source, and a configured `versionFiles` that
+  writes `Cargo.toml` without it is refused while a `cargo publish` is going to run.
+- `--locked` is added when the repository has a `Cargo.lock`; `--allow-dirty` only when the
+  tree is dirty (which preflight reports on its own, or the `commit` step is about to fix).
+- Like `cargo publish`, it compiles the crate, so preflight takes a build longer. Put
+  `--no-verify` on the publish command if you want neither to compile.
+- A publish command that is not a plain `cargo publish …` — a pipeline, quoting, an
+  environment prefix — is left alone, since what it uploads cannot be read off it.
+- The 10 MiB is crates.io's default; it can raise the limit for a single crate on request.
+
+### Requiring a green HEAD
+
+`verify` runs your gate locally. `"requireGreen": true` asks GitHub instead, before anything
+is bumped: the release is refused unless the commit being released is on the remote (a
+local commit has no checks, so HEAD must not be ahead of `origin/<branch>`) and its checks
+passed. A dirty tree the `commit` step would fold in is refused too — CI never saw it.
+
+- **Failed** — any check run concluding `failure`, `cancelled`, `timed_out`,
+  `action_required` or `stale`, or a commit status of `failure` or `error`. The failing
+  checks are named.
+- **Not finished** — any check run still queued or in progress, or a status still
+  `pending`: wait for it and re-run.
+- **Nothing checked** — no check run or status reporting `success`. Zero checks, or only
+  skipped ones, means nothing verified the commit, which is not the same as green.
+
+Both of GitHub's systems are read — check runs (`commits/{sha}/check-runs`, what Actions
+and GitHub Apps report) and commit statuses (`commits/{sha}/status`, what external CI such
+as Buildkite or Jenkins still posts) — because either one alone can call a commit green
+while the other has it red. It needs `gh`, authenticated, even with the `release` step off.
+Run inside GitHub Actions, the check runs of the current workflow run are ignored: the job
+doing the release is itself an unfinished check on that commit. Ordering against other jobs
+in the same workflow is what `needs:` is for.
+
 ## ♻️ Recovering from a failed run
 
 Re-run the same command. Every step is idempotent:
@@ -579,6 +655,12 @@ too, and are refreshed by the tool that owns them rather than rewritten by patte
 version sits in more than one place and the formats change shape between tool versions.
 Each is scoped to its manifest, so a `uv.lock` for a component this release is not
 versioning stays out of the release commit, and a missing tool warns rather than aborting.
+
+A `Cargo.lock` beside a detected `Cargo.toml` is kept in step without being listed, whether
+`Cargo.toml` is the version source (a plain crate) or a companion manifest. A configured
+`versionFiles` is never extended, so list the lockfile there yourself; when a `cargo publish`
+is going to run and a written `Cargo.toml` would leave its `Cargo.lock` on the old version,
+preflight refuses rather than letting `cargo publish` fail on the dirty tree after the push.
 `pnpm-lock.yaml` records no root version, so it never goes stale.
 
 ### Marking the line instead of writing a pattern
@@ -655,7 +737,9 @@ later — and the overlays that carry no `version` of their own are skipped rath
 failing the release.
 
 Stopping at `push` because the tag is what triggers the build pipeline — see
-[Libraries versus apps](#-libraries-versus-apps).
+[Libraries versus apps](#-libraries-versus-apps). When release-kit itself runs in CI, the
+push must not use `GITHUB_TOKEN`, or the tag triggers nothing — see
+[Continuous integration](#continuous-integration).
 
 The project name comes from the manifest when there is one (`name` in `package.json`,
 `Cargo.toml` or `pyproject.toml`), and falls back to the repository directory.
@@ -694,6 +778,7 @@ rather than being silently ignored.
 | `publish`       | detected               | Publish command, or an array of them; `null` publishes nothing          |
 | `versioning`    | `"conventional"`       | How `auto` infers; or `always-patch` / `-minor` / `-major`              |
 | `verify`        | `null`                 | Command run during preflight; non-zero aborts before anything mutates   |
+| `requireGreen`  | `false`                | Refuse a HEAD that is not pushed and green on GitHub                    |
 | `hooks`         | `{}`                   | Commands run between the steps — see [Hooks](#-hooks)                   |
 | `assistant`     | `null`                 | Drafting CLI: a name, `"auto"`, or `{ tool, model, effort }`            |
 | `commitMessage` | `"chore(release): %t"` | Release commit subject                                                  |
@@ -715,13 +800,19 @@ Non-interactive by default: the confirmation prompt is skipped when stdin is not
 `gh` picks up `GITHUB_TOKEN` on its own. Pass `--yes` to be explicit.
 
 ```yaml
-- uses: actions/checkout@v5
+- uses: actions/create-github-app-token@v3
+  id: app-token
+  with:
+    client-id: ${{ vars.RELEASE_APP_CLIENT_ID }}
+    private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+- uses: actions/checkout@v7
   with:
     fetch-depth: 0 # release notes and the last-tag lookup need real history
+    token: ${{ steps.app-token.outputs.token }} # the push below is made with this token
 - id: release
-  run: npx @entro314labs/release-kit@2.3.0 minor --yes
+  run: npx @entro314labs/release-kit@2.9.4 minor --yes
   env:
-    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
 - run: echo "shipped ${{ steps.release.outputs.tag }} ${{ steps.release.outputs.release-url }}"
 ```
 
@@ -730,11 +821,71 @@ re-deriving it: `version`, `tag`, `name`, `dist-tag`, `steps`, `published`, `rel
 Nothing is written on a dry run, and an unwritable `$GITHUB_OUTPUT` never fails a release
 that already completed.
 
+**A tag pushed with `GITHUB_TOKEN` triggers nothing.** GitHub deliberately does not start
+workflows from events caused by the job's own `GITHUB_TOKEN`, so an `on: push: tags` build
+workflow never runs for a tag release-kit pushed with it — the release is tagged and the
+build that was supposed to follow it silently does not happen. The push uses whatever token
+`actions/checkout` persisted, which is why the example gives checkout a
+[GitHub App](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow)
+installation token (`actions/create-github-app-token`) — a fine-grained personal access
+token with `contents: write` works the same way. Leave `persist-credentials` on for this
+job: the push has nothing to authenticate with otherwise. The alternative that needs no
+second identity is not to rely on the tag event at all: run the build in the same workflow
+after the release job (`needs: release`), or call it as a reusable workflow
+(`on: workflow_call`) with the tag from `steps.release.outputs.tag`. With `GITHUB_TOKEN`
+alone, the example above still releases correctly; only the tag-triggered follow-up is lost.
+
 Two upstream habits make commit-derived notes trustworthy, and neither is release-kit's job:
 
 - **Gate the release on CI, and guard against forks.** Trigger on `workflow_run` after your
-  check workflow succeeds, with `if: github.repository_owner == 'your-org'` so a fork never
-  tries to release.
+  check workflow completes — but that event fires for _every_ completed run of it, including
+  pull request runs and failed ones, so the condition has to say which run may release.
+  `workflow_run` also checks out the default branch's latest commit, not the commit that
+  was checked, so check out `head_sha` explicitly:
+
+  ```yaml
+  on:
+    workflow_run:
+      workflows: [check]
+      types: [completed]
+      branches: [main]
+
+  jobs:
+    release:
+      # A push to main that passed, in this repository — not a fork's copy of the workflow.
+      if: >-
+        github.repository_owner == 'your-org' &&
+        github.event.workflow_run.event == 'push' &&
+        github.event.workflow_run.head_branch == 'main' &&
+        github.event.workflow_run.conclusion == 'success'
+      runs-on: ubuntu-latest
+      steps:
+        - uses: actions/create-github-app-token@v3
+          id: app-token
+          with:
+            client-id: ${{ vars.RELEASE_APP_CLIENT_ID }}
+            private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+        - uses: actions/checkout@v7
+          with:
+            ref: ${{ github.event.workflow_run.head_sha }}
+            fetch-depth: 0
+            token: ${{ steps.app-token.outputs.token }} # so the tag push triggers workflows
+        # Checking out a SHA leaves a detached HEAD, which release-kit refuses — there is no
+        # branch to push. Put main back at the commit CI checked; if main has moved on
+        # since, preflight refuses as "behind origin/main" instead of releasing it unchecked.
+        - run: git switch -C main
+        - run: npx @entro314labs/release-kit@2.9.4 auto --yes
+          env:
+            GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
+  ```
+
+  [`requireGreen`](#requiring-a-green-head) is the same gate inside release-kit, for a
+  release run by hand or from a workflow that does not know which checks passed.
+
+  `branches: [main]` narrows the trigger to runs on `main`, but a pull request from a fork
+  whose branch is named `main` matches it too; `event == 'push'` is what rules pull request
+  runs out. The owner check stops a fork's own copy of the workflow from trying to release.
+
 - **Validate pull request titles.** A squash-merge takes its subject from the PR title, so
   that title becomes the commit the notes are built from. Check it with
   [`lint-commits`](#linting-commits), which uses this tool's own parser rather than a second
@@ -795,7 +946,10 @@ Two npm behaviours are handled automatically:
   `id-token: write`, or GitLab CI/CircleCI with `NPM_ID_TOKEN`, `whoami` fails while
   `publish` succeeds. That environment is detected and the auth check is skipped, so a
   valid CI release is not aborted over a missing token it does not need. That covers the
-  CLIs that exchange the OIDC token themselves — npm, pnpm, bun and `uv publish`. cargo is
+  CLIs that exchange the OIDC token themselves — npm, pnpm, bun and `uv publish`. npm
+  only learned to in 11.5.1, and an older one fails the publish after the tag and push, so
+  under OIDC an older `npm` is a preflight failure (`npm install -g npm@latest` fixes it).
+  pnpm and bun document no minimum and are not checked. cargo is
   not one of them: crates.io's trusted publishing goes through an action that turns the
   token into `CARGO_REGISTRY_TOKEN`, so the cargo credential check still applies in CI.
 
@@ -910,6 +1064,24 @@ downgrade, so a configured pipeline fails loudly; `"auto"` degrades quietly by d
   annotation, and posted as the GitHub release body — the same "written once, lands in three
   places" path a hand-written section takes.
 
+The prompt asks for notes written for someone upgrading: internal chores (CI, formatting,
+version and dependency bumps) are left out, except a dependency that ships inside the
+product — a bundled runtime, a sidecar binary, an embedded engine — since users run that
+code; a fix is described as what works now rather than what was broken; and a commit's
+[`Notes:` line](#release-notes) is kept in the author's words.
+
+**An entry the model is unsure of is flagged, not guessed.** The prompt lets it start a
+bullet with `[???]` when it cannot tell whether a change is user-facing or what it means for
+someone upgrading. Flagged entries are listed at the confirmation prompt, and answering `y`
+releases them as shown with the marker removed — your answer is the review. With `--yes`,
+or with no terminal to ask on (CI), there is nobody to review them, so preflight refuses
+before anything mutates: re-run in a terminal, or write the notes into `[Unreleased]` with
+the entries resolved, since a hand-written section wins over a draft. When a dirty tree
+defers drafting past the prompt, the check runs right after the working-tree commit instead
+and asks again (or, non-interactively, stops there with only that commit made). This applies
+to drafted notes only — commit-derived and hand-written notes are never checked for the
+marker.
+
 With `--commit`, notes are drafted _after_ that commit lands, so they describe the change it
 just made. Merge, release, `WIP` and `fixup!`/`squash!` commits are excluded from the prompt.
 
@@ -960,7 +1132,9 @@ at the pushed tag:
 ```
 
 Nothing after `push` — no `publish`, no `release`. The tag push is the handoff, and it is
-what triggers the build workflow. The notes travel in the annotated tag, which is the one
+what triggers the build workflow — unless it was pushed with `GITHUB_TOKEN` from another
+workflow, which triggers nothing ([Continuous integration](#continuous-integration) has the
+fix). The notes travel in the annotated tag, which is the one
 thing that reaches a fresh checkout on another machine; the signature block a signed tag
 appends is stripped before the file is handed over:
 
@@ -972,7 +1146,7 @@ on:
 jobs:
   build:
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
         with: { fetch-depth: 0 }
       - name: Read the release notes off the tag
         run: |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entro314labs/release-kit",
-  "version": "2.9.4",
+  "version": "2.10.0",
   "description": "Single-file, zero-dependency release mechanism for JS/TS/Node projects: version bump, changelog roll, commit, annotated tag, push, publish, GitHub release",
   "keywords": [
     "changelog",

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: {},
 }
 
@@ -657,11 +662,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 +703,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 +713,8 @@ function parseCommit(subject, body = '', hash = '') {
     releaseAs,
     closes: [...new Set(closes)],
     breakingNote,
+    notes: trailer.text,
+    noNotes: trailer.excluded,
   }
 }
 
@@ -727,7 +753,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 +773,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 +797,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 +809,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 +1095,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 +1141,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. */
@@ -1396,6 +1464,32 @@ 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)
 
@@ -1425,9 +1519,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}`
@@ -1611,6 +1709,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.
@@ -2166,6 +2311,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 })
@@ -2898,6 +3047,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) {
@@ -3008,6 +3182,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 +3418,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 +3482,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 +3574,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 +3627,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 +3679,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 +3732,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`,
@@ -3371,7 +3804,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')
@@ -3417,19 +3851,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 +3909,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}`)
+      }
+    }
   }
 }