@entro314labs/release-kit 2.9.3 → 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` |
 | ------------------------------------ | ------------------------------------------------ | ------------------- |
@@ -185,20 +186,22 @@ Prerelease bumps need `--preid` unless the current version already carries one t
 
 ### Flags
 
-| Flag                         | Effect                                                                     |
-| ---------------------------- | -------------------------------------------------------------------------- |
-| `--only <steps>`             | Run only these steps, comma-separated.                                     |
-| `--skip <steps>`             | Run every step except these.                                               |
-| `--commit`                   | Force the `commit` step on when a `steps` config removed it.               |
-| `--dry-run`                  | Print every step, execute nothing. Preflight still runs and still reports. |
-| `--yes`, `-y`                | Skip the confirmation prompt.                                              |
-| `--preid <id>`               | Prerelease identifier: `alpha`, `beta`, `rc`, `next`, `nightly`, `canary`. |
-| `--dist-tag <name>`          | Override the npm dist-tag. Always wins over the derived one.               |
-| `--assistant <name>`         | Drafting CLI: `auto`, `none`, `claude`, `codex`.                           |
-| `--assistant-model <name>`   | Model the assistant runs with.                                             |
-| `--assistant-effort <level>` | Reasoning effort the assistant runs with.                                  |
-| `--sync <dir>...`            | Copy this script into other projects and exit. Touches no git state.       |
-| `--help`, `-h`               | Full flag list.                                                            |
+| Flag                         | Effect                                                                        |
+| ---------------------------- | ----------------------------------------------------------------------------- |
+| `--only <steps>`             | Run only these steps, comma-separated.                                        |
+| `--skip <steps>`             | Run every step except these.                                                  |
+| `--commit`                   | Force the `commit` step on when a `steps` config removed it.                  |
+| `--dry-run`                  | Print every step, execute nothing. Preflight still runs and still reports.    |
+| `--yes`, `-y`                | Skip the confirmation prompt.                                                 |
+| `--preid <id>`               | Prerelease identifier: `alpha`, `beta`, `rc`, `next`, `nightly`, `canary`.    |
+| `--dist-tag <name>`          | Override the npm dist-tag. Always wins over the derived one.                  |
+| `--notes <source>`           | Where notes come from: `auto`, `changelog`, `assistant`, `commits`, `github`. |
+| `--notes-file <path>`        | Write the resolved notes to a file for the next tool — see `notesFile`.       |
+| `--assistant <name>`         | Drafting CLI: `auto`, `none`, `claude`, `codex`.                              |
+| `--assistant-model <name>`   | Model the assistant runs with.                                                |
+| `--assistant-effort <level>` | Reasoning effort the assistant runs with.                                     |
+| `--sync <dir>...`            | Copy this script into other projects and exit. Touches no git state.          |
+| `--help`, `-h`               | Full flag list.                                                               |
 
 ### Linting commits
 
@@ -225,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
@@ -286,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
@@ -297,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
@@ -306,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
@@ -350,6 +374,13 @@ rather than stopping at the first problem.
 
 - The target version is greater than the current one — and for `auto`, which bump the
   commits imply and why
+- The version step will write the target, when the target differs from what the files say
+  — a tag naming one version over a manifest carrying another is refused, since
+  `npm publish` sends the manifest
+- A relative bump is not counting from a version a dead run wrote and never committed
+  (the file says one thing on disk and another at `HEAD`), and not skipping past a release
+  tagged at `HEAD` that never reached the registry — both are refused with the command that
+  finishes the earlier release instead
 - Working tree is clean, or listed for commit when the `commit` step runs
 - On the configured branch, and not on a detached HEAD
 - The remote exists, is reachable, and the branch is not behind it
@@ -357,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
@@ -369,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:
@@ -393,6 +478,13 @@ last tag, and after a failed publish there are none — the tag it would read fr
 the dead run made. Rather than aborting with "no releasable commits", it finishes that
 release: same version, same tag, the steps that remain.
 
+A relative bump is the one target that cannot be re-run as-is, because it counts from the
+version the dead run already wrote: `minor` after a dead `minor` would release `1.2.0`
+from the commit `v1.1.0` already tags. Preflight refuses both shapes of that — the bump
+written but never committed, and the tag at `HEAD` that never reached the registry — and
+names the command that finishes the earlier release: `release-kit 1.1.0`, or no target, or
+`auto`.
+
 ### A release that was never published
 
 A tag is not a release. The tag and the push happen before the publish, so a publish that
@@ -563,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
@@ -639,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.
@@ -666,23 +766,28 @@ execution is not wired up yet.
 `release.config.json`, beside `package.json`. Every key is optional; unknown keys abort
 rather than being silently ignored.
 
-| Key             | Default                | Meaning                                                               |
-| --------------- | ---------------------- | --------------------------------------------------------------------- |
-| `steps`         | all but `commit`       | Which steps run; the order is fixed                                   |
-| `tagPrefix`     | `"v"`                  | Prepended to the version to form the tag                              |
-| `branch`        | `"main"`               | The only branch a release may run from; `null` allows any             |
-| `remote`        | `"origin"`             | Git remote to push to                                                 |
-| `changelog`     | `"CHANGELOG.md"`       | Changelog path; `null` for a project without one                      |
-| `versionFile`   | detected               | Where the version lives; `null` versions by tag alone                 |
-| `versionFiles`  | detected               | Further files kept in sync; a path or `{ path, pattern }`             |
-| `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 |
-| `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                                                |
-| `releaseTitle`  | `"%t"`                 | GitHub release title                                                  |
-| `assets`        | `[]`                   | Files attached to the GitHub release                                  |
+| Key             | Default                | Meaning                                                                 |
+| --------------- | ---------------------- | ----------------------------------------------------------------------- |
+| `steps`         | all seven              | Which steps run; the order is fixed. `commit` no-ops on a clean tree    |
+| `tagPrefix`     | `"v"`                  | Prepended to the version to form the tag                                |
+| `branch`        | `"main"`               | The only branch a release may run from; `null` allows any               |
+| `remote`        | `"origin"`             | Git remote to push to                                                   |
+| `changelog`     | `"CHANGELOG.md"`       | Changelog path; `null` for a project without one                        |
+| `versionFile`   | detected               | Where the version lives; `null` versions by tag alone                   |
+| `versionFiles`  | detected               | Further files kept in sync; a path or `{ path, pattern }`               |
+| `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                                                  |
+| `releaseTitle`  | `"%t"`                 | GitHub release title                                                    |
+| `assets`        | `[]`                   | Files attached to the GitHub release                                    |
+| `notes`         | `"auto"`               | Notes source; or force `changelog` / `assistant` / `commits` / `github` |
+| `notesFile`     | `null`                 | Write the resolved notes here for the tool that runs next               |
+| `hiddenTypes`   | `[]`                   | Commit types left out of commit-derived notes                           |
+| `ignoreCommits` | release, merge, wip…   | Regexes for commits that are bookkeeping rather than change             |
 
 Command and message strings expand four tokens: `%v` version, `%t` tag, `%n` package
 name, `%d` npm dist-tag. In the `publish` command line the substituted values are
@@ -695,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 }}"
 ```
 
@@ -710,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
@@ -774,7 +945,13 @@ Two npm behaviours are handled automatically:
   at all.** In GitHub Actions with
   `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.
+  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`. 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.
 
 ### Examples
 
@@ -887,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.
 
@@ -933,11 +1128,15 @@ release themselves, with the artifacts attached. That is their job. release-kit'
 at the pushed tag:
 
 ```json
-{ "steps": ["commit", "version", "changelog", "tag", "push"], "notesFile": "dist-notes.md" }
+{ "steps": ["commit", "version", "changelog", "tag", "push"] }
 ```
 
 Nothing after `push` — no `publish`, no `release`. The tag push is the handoff, and it is
-what triggers the build workflow:
+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:
 
 ```yaml
 on:
@@ -947,8 +1146,12 @@ 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: |
+          git tag -l --format='%(contents)' "$GITHUB_REF_NAME" \
+            | sed '/^-----BEGIN [A-Z ]*SIGNATURE-----$/,$d' > dist-notes.md
       - run: goreleaser release --clean --release-notes dist-notes.md
 ```
 
@@ -968,10 +1171,11 @@ generated by different code from the same commits, and they drift.
 release-kit has already created one for that tag, goreleaser fails. Exactly one of them
 should own it, and it should be the one attaching the binaries.
 
-`notesFile` exists for this handoff: goreleaser's `--release-notes` takes a file and skips
-its own changelog generation. The notes are also in the annotated tag, but reading them back
-with `git tag --format='%(contents)'` embeds the signature when tags are signed, which then
-appears in your published release notes. `notesFile` writes the text itself.
+`notesFile` is the same handoff for a build tool that runs next **on the same machine**:
+`release-kit auto && goreleaser release --release-notes dist-notes.md`. It writes the text
+itself, with no signature to strip. It is written after the release commit and is not part
+of it, so a workflow on another machine never sees it — that is what the tag read above is
+for.
 
 ### Both at once
 

package/TRAIN.md

@@ -12,7 +12,11 @@ readable, vendorable, zero dependencies.
 **Status: prototype.** Discovery, graph derivation, registry-aware change detection,
 cascade, planning, whole-train preflight, `seed-tags`, and the train summary work.
 Execution (running release-kit per package) is not implemented yet — `train` without
-`--dry-run` says so and exits.
+`--dry-run` says so and exits. Three things the design below describes are not built
+either, and the plan does not claim them: taking `packages` from `pnpm-workspace.yaml` /
+`workspaces` when the config omits it (the config must list them today), and the two
+per-package authentication checks in the preflight table (publish CLI and `gh`), which
+each package's own release-kit run performs when execution lands.
 
 ```sh
 release-train graph                  # print the derived dependency graph and topo order

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entro314labs/release-kit",
-  "version": "2.9.3",
+  "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",
@@ -49,11 +49,11 @@
     "release": "node release.mjs"
   },
   "devDependencies": {
-    "oxfmt": "^0.65.0",
-    "oxlint": "^1.80.0",
+    "oxfmt": "^0.67.0",
+    "oxlint": "^1.82.0",
     "semver": "^7.8.5"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   }
 }