@williamthorsen/release-kit 11.0.0 → 13.0.0

package/.readyup/manifest.json

@@ -8,12 +8,12 @@
       "esbuildVersion": "0.28.2",
       "inputs": [
         {
-          "hash": "a20ce64b",
+          "hash": "91bc3638",
           "kind": "module",
           "path": "kits/default.ts"
         },
         {
-          "hash": "e9aadbb2",
+          "hash": "7f9ab854",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -21,22 +21,22 @@
           ]
         },
         {
-          "hash": "850b703f",
+          "hash": "43bb0452",
           "kind": "module",
           "path": "../src/init/detectRepoType.ts"
         },
         {
-          "hash": "b6873aba",
+          "hash": "68354f97",
           "kind": "module",
           "path": "../src/init/parseJsonRecord.ts"
         },
         {
-          "hash": "b798d024",
+          "hash": "1c9cbce9",
           "kind": "module",
           "path": "../src/packsPath.ts"
         },
         {
-          "hash": "646fe51b",
+          "hash": "1424b343",
           "kind": "module",
           "path": "../src/typeGuards.ts"
         }
@@ -45,8 +45,8 @@
       "path": "kits/default.js",
       "readyupVersion": "0.38.0",
       "source": "kits/default.ts",
-      "sourceHash": "a20ce64b",
-      "targetHash": "b3fd135a"
+      "sourceHash": "91bc3638",
+      "targetHash": "2fdeff1f"
     },
     {
       "checklists": [
@@ -56,17 +56,22 @@
       "esbuildVersion": "0.28.2",
       "inputs": [
         {
-          "hash": "c2d2d375",
+          "hash": "d9910d60",
           "kind": "module",
           "path": "kits/npm-auto-publish.ts"
+        },
+        {
+          "hash": "d360febf",
+          "kind": "module",
+          "path": "../src/init/hasProvenance.ts"
         }
       ],
       "name": "npm-auto-publish",
       "path": "kits/npm-auto-publish.js",
       "readyupVersion": "0.38.0",
       "source": "kits/npm-auto-publish.ts",
-      "sourceHash": "c2d2d375",
-      "targetHash": "9d2d224b"
+      "sourceHash": "d9910d60",
+      "targetHash": "8bdbefef"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,104 @@
 
 All notable changes to this project will be documented in this file.
 
+## 13.0.0 — 2026-10-01
+
+### 🎉 Features
+
+- Adds the `--config <path>` flag to `release-kit push`, which now reads the config as `publish` and `create-github-release` do and fails when the file exists but is invalid. (#895)
+- Makes `release-kit` add an item derived from a change-record entry to a workspace's changelog and version bump only when the entry's `scopes`, after `scopeAliases` resolution, name the workspace's `dir`, are empty, or contain `*`, and extends that rule to the sections of earlier releases that `release-kit prepare` rebuilds. (#896)
+- Adds a warning to the `release-kit prepare` report that lists each change-record entry scope matching no workspace in its commit's window, such as a misspelled scope or the old name of a renamed directory that has no `scopeAliases` entry. (#896)
+- Makes `release-kit overrides validate` check a workspace's overrides against only the entries routed to that workspace, so that an override keyed to an entry routed elsewhere is reported as stale. (#896)
+- Adds `release-kit update-templates`, which writes each scaffolded workflow that is missing or differs from the installed template, prints a diff of each updated file, refreshes `sync-labels.yaml` only when it exists, keeps `publish.yaml`'s provenance setting, and never reads or writes the config files. (#952)
+- Changes the readyup kits' fix messages for a workflow that differs from its template, or that references a deprecated tag, to recommend `update-templates` rather than `init --force`. (#952)
+
+### 🪦 Removed
+
+- 🚨 **Breaking:** Removes `required` as a `breakingPolicies` value, making `drop` default to `optional` so that an unmarked `drop:` commit no longer reports a policy violation. (#905)
+- Stops `release-kit` from parsing a commit subject that combines a pipe scope with a parenthesized scope, such as `web|feat(other): ...`, or that lacks a space and a title after the colon, because subjects are now read through `@williamthorsen/change-grammar`. (#905)
+- Stops publishing `schemas/label-map.json` from `release-kit`, whose identical schema `@williamthorsen/change-grammar` now publishes; URLs under existing `release-kit-v*` tags keep resolving. (#905)
+
+### 🐛 Bug fixes
+
+- Record a changelog entry for a forced release whose commits yield no item (#887)
+
+  Makes `release-kit prepare` record the "Forced version bump." changelog entry for any release forced by `--force` or `--set-version` whose commits yield no changelog item, instead of only for a release with no commits at all. It also stops a monorepo's project release from dropping the forced-release entries that earlier releases recorded.
+
+- Stops `release-kit prepare` from reporting `commitCount` 0 and dropping the unparseable commits and change-record and policy diagnostics of a workspace released only because a dependency was bumped, and makes `prepare` list that workspace's commits in the release commit summary under its tag. (#888)
+- Stops `release-kit prepare` from labeling a direct release that has no commits as bumped via a dependency, by marking a propagation-only release with the new `propagatedOnly` result field, whose report line now reads `Bumped via dependency: …` in place of `0 commits (bumped via dependency: …)`. (#888)
+- Stops a `release-kit` command run from inside a package from releasing that package as a single-package repo with its own tag and changelog, by running every command from the repo root: the nearest directory that contains `pnpm-workspace.yaml`, or else the working directory when it contains a `package.json`. (#893)
+- Stops `sync-labels generate` from writing the `--config` path into the `.github/labels.yaml` header as typed, which made the header and the result of `generate --check` depend on the directory from which the command ran; the header now names the config by its path relative to the repo root. (#893)
+- Stops `push`, `publish`, and `create-github-release` from pushing, publishing, or creating a GitHub Release for a tag on HEAD whose workspace the config excludes with `shouldExclude: true`, which each command now skips with a warning, including when `--tags` names the tag or when every tag on HEAD is excluded. (#895)
+- Stops `release-kit prepare` from silently deleting a `CHANGELOG.md` section whose version is absent from both the release windows and `changelog.json`, such as history written by hand before release-kit was adopted; `prepare` now keeps that section verbatim in version order, lists the kept versions in its report, and warns about each `##` section that names no version and is dropped. (#897)
+- Stops `release-kit prepare` from folding every earlier commit into the new version, and deriving the bump from all of them, when the current version was released and recorded in the changelog but never tagged; `prepare` now fails before any write, under `--force` and `--set-version` too, and names each target and the tag to create. (#897)
+- Adds the missing `removal` and `formatting` labels to the `common` preset by defining a label for every work type in change-grammar's taxonomy, and keeps the names, colors, and descriptions of the existing type labels. (#906)
+- Fixes the `release.yaml` generated by `release-kit init`, which `actionlint` rejected because its `bump` choice input listed an empty string as the auto-detect option, by offering `auto` as the default option and passing it to the reusable release workflow as an empty `bump`. (#936)
+- Rewords the error messages, `prepare` report lines, command help, and readyup kit fix strings of `release-kit` that addressed the reader as "your", separated a detail from its subject with an em-dash, or stated an absence with "no", such as "No workspaces had release-worthy changes." (#937)
+- Fixes the issue that the `release.yaml` and `sync-labels.yaml` workflows generated by `release-kit init` and `release-kit sync-labels init` contained unclear wording in two comments and in the `force` input description, which the change rewrites without altering any job, trigger, or input; the release-kit kit check reports a copy generated before this change as stale until `release-kit init --force` or `release-kit sync-labels init --force` regenerates it. (#946)
+- Fixes the issue that `release-kit` titled a propagation-only bump's changelog section `Dependency updates` rather than with the resolved `deps` work type's header, `📦 Dependencies` by default or a consumer's `workTypes.deps.header` override, which broke the heading convention and left the section outside the section order. (#950)
+- Fixes the issue that `release-kit init`'s next steps told a public repo to set `provenance: true` in `publish.yaml`, which the template already sets, and now tells a private repo to remove it instead. (#952)
+
+### ♻️ Refactoring
+
+- Narrows the config accepted by `releasePrepare`, `releasePrepareMono`, `releasePrepareProject`, and the helpers that they pass it to, to the new `PrepareConfig` and `MonorepoPrepareConfig` aliases, which omit `releaseNotes` so that typecheck rejects any read of release-notes configuration on the prepare path. (#890)
+- Derives `DEFAULT_WORK_TYPES`, `DEFAULT_BREAKING_POLICIES`, the default `devOnlySections`, and the release-notes breaking marker from change-grammar's `CANONICAL_TAXONOMY`, removing release-kit's taxonomy copy and its `work-types:check` and `work-types:sync` scripts. (#905)
+- Replaces every `.sort()` call that suppressed `unicorn/no-array-sort` with `toSorted()` and drops the spread copy wherever the source was already an array. (#925)
+
+### 🧪 Tests
+
+- Extends the `changelogJson.enabled` tests of `releasePrepareMono` to configure a format command and assert that `formatCommand.files` includes the workspace's `changelog.json` when the feature is enabled and excludes it when the feature is disabled, where the disabled case also requires a format command to exist so that the exclusion cannot pass vacuously. (#889)
+- Replaces the inline copies of the fixture in which `app` depends on `core` in `releasePrepareMono.unit.test.ts` with `stubPropagationWorkspaces`, a helper that stubs both manifests at their exact paths and returns the two-workspace config. (#951)
+
+### 📦 Dependencies
+
+- Upgrades all dependencies to the latest versions allowed by the ceilings in `taze.config.ts` and the release quarantine, including pnpm to 12.6.0. (#944)
+- Adds `esbuild` 0.28.2 to the pnpm catalog and declares it as a devDependency of `nmr`, `release-kit`, and `v11y-check`, because `readyup` declares it only as an optional peer and `rdy compile` failed in those packages once a regenerated lockfile stopped installing it. (#944)
+
+### 📚 Documentation
+
+- Revises the comments in `packages/release-kit/src` and the `default` and `npm-auto-publish` readyup kits against the comment-discipline rules, correcting comments that misstated the code, such as the `releasePrepareProject` description that said it returns `undefined` where it throws and the `renderChangelogMarkdown` note that said no logic reads the footer. (#922)
+- Rewrites the prose of the `release-kit` README, the pages under `docs/`, and the package's source comments and test names in plain, literal wording. (#937)
+
+## 12.0.0 — 2026-09-23
+
+### 🎉 Features
+
+- Assign changelog sections from the work-type taxonomy (#877)
+
+  - Adds `excludedFromChangelog` to a `workTypes` entry, which keeps commits of that type out of every changelog while they still count toward the version bump.
+  - Fixes the silent omission of a ticketed commit written as `type(scope):` or with a capitalized type such as `FEAT:`, which counted toward the version bump but reached no changelog.
+  - Documents that a scaffolded `.config/git-cliff.toml` may vary its enumeration keys alone: a `commit_parsers` entry that skips or narrows drops the commit before classification, with no error.
+
+- Build changelog items from a merge commit's change-record block (#882)
+
+  Builds `release-kit` changelog items from a commit's `change-record` block, the fenced YAML block at the end of a squash-merge commit that lists the change's outcomes, so that a merge with several outcomes of different types yields one item per outcome, each under its own type's section. Makes `release-kit prepare` warn about a block that cannot be read, an entry whose type is undeclared, and an entry that violates its type's breaking policy. Keeps reading a commit with no usable block from its title, as before.
+
+- 🚨 **Breaking:** Derive the version bump from the changelog items (#885)
+
+  Derives the version bump in every `release-kit prepare` path (single-package, project, and monorepo) from the changelog items of the unreleased commits, so that the bump and the changelog describe the same release. A commit that yields no changelog item no longer bumps, and a `BREAKING CHANGE:` footer no longer raises a major bump. Single-package mode now follows the monorepo rules for `--bump` and `--force`, and the `prepare` report shows the diagnostics of a skipped target.
+
+  Migration: Mark a breaking change with a `!` on the commit subject or with `breaking: true` on its change-record entry, because a `BREAKING CHANGE:` footer alone now gets the bump of the commit's type. Give each commit that should bump a ticket-ID prefix and a type that the changelog does not exclude. In single-package mode, add `--force` to a release that used `--bump=X` alone, or that relied on the patch floor, when no commit yields a changelog item; without it, `prepare` skips the release.
+
+- 🚨 **Breaking:** Key an editorial override to one of several items on a commit (#886)
+
+  Adds the `<hash>:<n>` key to `.meta/changelog-overrides.json`. It targets one of the several changelog items that a commit's change-record block yields, while a bare `<hash>` key still targets all of them. Also makes `release-kit prepare` and `release-kit overrides validate` fail when override keys conflict on an item, and publishes a JSON Schema for the override file.
+
+  Migration: Replace a bare key that sets `description` or `body` on a commit with several items with one `<hash>:<n>` key per item, as listed by the error message. Where two keys match the same item, such as `abc1234` beside `abc1234:2`, remove one of them. This includes a root-file key that overlaps a workspace-file key, which now fails even though the two files are separate. In each scope passed to `validateAllChangelogOverrides`, rename `hashes` to `items` and pass `OverrideTargetItem` objects (`{ hash, entry? }`) instead of hash strings.
+
+### 🪦 Removed
+
+- 🚨 **Breaking:** Build changelogs from release-kit's own enumeration and remove git-cliff (#880)
+
+  Removes git-cliff from `@williamthorsen/release-kit`: `prepare` now builds every changelog from the same commit history that decides each version bump, and no longer fetches a git-cliff binary through `npx`. A config that still sets `cliffConfigPath` now fails validation. Two ways in which the changelog and the bump read different commits are gone, affecting single-package repositories with a tag prefix other than `v` and `paths` entries that name a bare directory.
+
+  Migration: Remove `cliffConfigPath` from `.config/release-kit.config.ts`, and delete `.config/git-cliff.toml` or `cliff.toml` if the repository has one. Any customization in that file, such as `tag_pattern` or its tag-skipping keys, no longer has an effect: `release-kit` now splits the changelog on the configured tag prefixes alone.
+
+### 🏗️ Internal features
+
+- Enumerate release windows and read them on the bump path (#879)
+
+  Adds `enumerateReleaseWindows`, which splits the history reachable from HEAD into release windows from tag prefixes and a path list, and rebuilds `getCommitsSinceTarget` on the newest of those windows in place of its `git describe` baseline lookup. Leaves the changelog on git-cliff's enumeration.
+
 ## 11.0.0 — 2026-09-22
 
 ### 🎉 Features

package/README.md

@@ -4,56 +4,45 @@
 
 Version-bumping and changelog-generation toolkit for release workflows.
 
-Provides a self-contained CLI that auto-discovers workspaces from `pnpm-workspace.yaml`, parses conventional commits, determines version bumps, updates `package.json` files, and generates changelogs from `git-cliff --context` output rendered in-process (with optional [editorial overrides](docs/editorial-overrides.md)).
+Provides a self-contained CLI that auto-discovers workspaces from `pnpm-workspace.yaml`, parses conventional commits, determines version bumps, updates `package.json` files, and generates changelogs from the same commit history that decides each bump (with optional [editorial overrides](docs/editorial-overrides.md)).
 
 <!-- section:release-notes -->
-## Release notes — v11.0.0 (2026-09-22)
+## Release notes — v13.0.0 (2026-10-01)
 
 ### 🎉 Features
 
-- 🚨 **Breaking:** Return the provenance check's remediation as the outcome's fix (#855)
+- Adds the `--config <path>` flag to `release-kit push`, which now reads the config as `publish` and `create-github-release` do and fails when the file exists but is invalid. (#895)
+- Makes `release-kit` add an item derived from a change-record entry to a workspace's changelog and version bump only when the entry's `scopes`, after `scopeAliases` resolution, name the workspace's `dir`, are empty, or contain `*`, and extends that rule to the sections of earlier releases that `release-kit prepare` rebuilds. (#896)
+- Adds a warning to the `release-kit prepare` report that lists each change-record entry scope matching no workspace in its commit's window, such as a misspelled scope or the old name of a renamed directory that has no `scopeAliases` entry. (#896)
+- Makes `release-kit overrides validate` check a workspace's overrides against only the entries routed to that workspace, so that an override keyed to an entry routed elsewhere is reported as stale. (#896)
+- Adds `release-kit update-templates`, which writes each scaffolded workflow that is missing or differs from the installed template, prints a diff of each updated file, refreshes `sync-labels.yaml` only when it exists, keeps `publish.yaml`'s provenance setting, and never reads or writes the config files. (#952)
+- Changes the readyup kits' fix messages for a workflow that differs from its template, or that references a deprecated tag, to recommend `update-templates` rather than `init --force`. (#952)
 
-  - Moves the remediation of the `npm-auto-publish` kit's `Provenance setting matches repo visibility` check from the failing outcome's `detail` into its `fix`, so that readyup marks it as a remedy, lists it in the `Fixes` recap, and reports it under `rdy run --json --detail summary` instead of printing it as a plain reason line.
-  - Declares `minReadyupVersion: '0.37.0'` on the kit, the readyup release that introduced `CheckOutcome.fix`, which retires the kit's `version-skew` advisory and makes an older runner fail to load the kit.
+### 🪦 Removed
 
-  Migration: Upgrade readyup to 0.37.0 or later before consuming this release of the `npm-auto-publish` kit.
-
-- Accept a --config argument on every config-reading subcommand (#857)
-
-  - Adds `--config <path>` to `prepare`, `publish`, `create-github-release`, `show-tag-prefixes`, `overrides validate`, `sync-labels init`, and `sync-labels generate`, each of which then reads the named file in place of `.config/release-kit.config.ts`.
-  - Requires a named `--config` file to exist, failing if it does not; an absent default path continues to mean that the repo declares no config.
-  - Confines scaffolding to the default path: `release-kit init` and `sync-labels init` still write `.config/release-kit.config.ts`, and `sync-labels init --config` reads the named file and fails when it is absent.
-
-- 🚨 **Breaking:** Adopt the shared workspace resolver in release-kit, honoring exclusions (#865)
-
-  - 🚨 **Breaking:** Narrows `no-pattern` in `@williamthorsen/nmr-core`'s `EmptyWorkspaceCause`, moving an absent or empty `packages` list onto `no-packages-list` and a value that is not a list of strings onto `unreadable-packages`.
-  - Stops `release-kit` from tagging, publishing, and label-syncing a package that a `!` entry in `pnpm-workspace.yaml` excludes, which its previous `glob`-based resolution could not remove from the match.
-  - Replaces the release of the root package alone with a failure naming the condition that emptied the workspace, when `pnpm-workspace.yaml` does not hold valid YAML or declares a workspace that does not resolve to a package.
-  - Replaces the `no-pattern` remedy that `nmr` printed for a `pnpm-workspace.yaml` declaring no `packages` list, and for one declaring a `packages` value that is not a list of strings.
-  - Raises `engines.node` to `>=24.16.0` in `@williamthorsen/nmr-core` and `@williamthorsen/release-kit`, because Node 24.0 through 24.15 ignores the `followSymlinks` option that the workspace matcher passes to `globSync` and drops a symlinked package directory from the resolution without reporting it.
-
-  Migration: Add a `no-packages-list` arm and an `unreadable-packages` arm to any `switch` that covers `EmptyWorkspaceCause` exhaustively. `no-pattern` now names only a list that the resolver read in full and whose entries all failed to become a positive pattern, so move the handling of an absent `packages` key, an empty list, and a value that is not a list of strings out of the `no-pattern` arm into the two new ones. Route `no-packages-list` to single-package behavior rather than to a failure path: pnpm resolves such a manifest to the root package alone.
+- 🚨 **Breaking:** Removes `required` as a `breakingPolicies` value, making `drop` default to `optional` so that an unmarked `drop:` commit no longer reports a policy violation. (#905)
+- Stops `release-kit` from parsing a commit subject that combines a pipe scope with a parenthesized scope, such as `web|feat(other): ...`, or that lacks a space and a title after the colon, because subjects are now read through `@williamthorsen/change-grammar`. (#905)
+- Stops publishing `schemas/label-map.json` from `release-kit`, whose identical schema `@williamthorsen/change-grammar` now publishes; URLs under existing `release-kit-v*` tags keep resolving. (#905)
 
 ### 🐛 Bug fixes
 
-- Truncate release-kit commit subjects by display column (#840)
-
-  - Fixes the issue that the `release-kit` prepare report cut a commit subject at 69 UTF-16 code units instead of at display columns, so a subject of CJK characters printed about twice the intended 72-column width and a cut inside an emoji left a broken character that a terminal drew as a replacement glyph.
-  - Replaces the `...` marker on a truncated subject with `…`, the default of the width-aware truncation that now does the cutting.
-  - Exports `truncateToWidth` and `measureWidth` from `@williamthorsen/nmr-core`, which measure and cut text by display width without splitting a grapheme cluster.
-
-- Abort show-tag-prefixes on an unusable config (#861)
-
-  - Fixes the issue that `release-kit show-tag-prefixes` silently ignored a config file that failed schema validation, which left the preview reading no `legacyIdentities` and no `retiredPackages` and reporting already-declared and retired tag prefixes as undeclared candidates; the command now prints those validation errors and exits 1 with no preview.
-
-- Abort every config-reading command on an unusable default config (#869)
-
-  - Fixes `publish` proceeding on derived defaults when the default config file exists and fails to load, which silently dropped a configured `releaseNotes.shouldInjectIntoReadme`, `changelogJson.outputPath`, or `workTypes`; it now reports the failure and exits 1, as every other config-reading subcommand does.
-  - Fixes `publish` and `create-github-release` ignoring a broken or invalid default config when every requested tag names a private package, a case in which both commands return before any loader runs.
-
-- Strip trailing Change trailers from changelog item bodies (#870)
-
-  - Fixes a changelog item body that kept a commit's trailing `Change:` trailers, which then appeared verbatim in the rendered release notes, including the notes injected into a README.
+- Record a changelog entry for a forced release whose commits yield no item (#887)
+
+  Makes `release-kit prepare` record the "Forced version bump." changelog entry for any release forced by `--force` or `--set-version` whose commits yield no changelog item, instead of only for a release with no commits at all. It also stops a monorepo's project release from dropping the forced-release entries that earlier releases recorded.
+
+- Stops `release-kit prepare` from reporting `commitCount` 0 and dropping the unparseable commits and change-record and policy diagnostics of a workspace released only because a dependency was bumped, and makes `prepare` list that workspace's commits in the release commit summary under its tag. (#888)
+- Stops `release-kit prepare` from labeling a direct release that has no commits as bumped via a dependency, by marking a propagation-only release with the new `propagatedOnly` result field, whose report line now reads `Bumped via dependency: …` in place of `0 commits (bumped via dependency: …)`. (#888)
+- Stops a `release-kit` command run from inside a package from releasing that package as a single-package repo with its own tag and changelog, by running every command from the repo root: the nearest directory that contains `pnpm-workspace.yaml`, or else the working directory when it contains a `package.json`. (#893)
+- Stops `sync-labels generate` from writing the `--config` path into the `.github/labels.yaml` header as typed, which made the header and the result of `generate --check` depend on the directory from which the command ran; the header now names the config by its path relative to the repo root. (#893)
+- Stops `push`, `publish`, and `create-github-release` from pushing, publishing, or creating a GitHub Release for a tag on HEAD whose workspace the config excludes with `shouldExclude: true`, which each command now skips with a warning, including when `--tags` names the tag or when every tag on HEAD is excluded. (#895)
+- Stops `release-kit prepare` from silently deleting a `CHANGELOG.md` section whose version is absent from both the release windows and `changelog.json`, such as history written by hand before release-kit was adopted; `prepare` now keeps that section verbatim in version order, lists the kept versions in its report, and warns about each `##` section that names no version and is dropped. (#897)
+- Stops `release-kit prepare` from folding every earlier commit into the new version, and deriving the bump from all of them, when the current version was released and recorded in the changelog but never tagged; `prepare` now fails before any write, under `--force` and `--set-version` too, and names each target and the tag to create. (#897)
+- Adds the missing `removal` and `formatting` labels to the `common` preset by defining a label for every work type in change-grammar's taxonomy, and keeps the names, colors, and descriptions of the existing type labels. (#906)
+- Fixes the `release.yaml` generated by `release-kit init`, which `actionlint` rejected because its `bump` choice input listed an empty string as the auto-detect option, by offering `auto` as the default option and passing it to the reusable release workflow as an empty `bump`. (#936)
+- Rewords the error messages, `prepare` report lines, command help, and readyup kit fix strings of `release-kit` that addressed the reader as "your", separated a detail from its subject with an em-dash, or stated an absence with "no", such as "No workspaces had release-worthy changes." (#937)
+- Fixes the issue that the `release.yaml` and `sync-labels.yaml` workflows generated by `release-kit init` and `release-kit sync-labels init` contained unclear wording in two comments and in the `force` input description, which the change rewrites without altering any job, trigger, or input; the release-kit kit check reports a copy generated before this change as stale until `release-kit init --force` or `release-kit sync-labels init --force` regenerates it. (#946)
+- Fixes the issue that `release-kit` titled a propagation-only bump's changelog section `Dependency updates` rather than with the resolved `deps` work type's header, `📦 Dependencies` by default or a consumer's `workTypes.deps.header` override, which broke the heading convention and left the section outside the section order. (#950)
+- Fixes the issue that `release-kit init`'s next steps told a public repo to set `provenance: true` in `publish.yaml`, which the template already sets, and now tells a private repo to remove it instead. (#952)
 <!-- /section:release-notes -->
 
 ## Installation
@@ -77,7 +66,7 @@ npx @williamthorsen/release-kit prepare --dry-run
 Example output from `prepare --dry-run` in a monorepo whose `arrays` workspace has two commits since its last release:
 
 ```
-🔍 DRY RUN — no files will be modified
+🔍 DRY RUN: release-kit will not modify any files
 
 ━━━ arrays ━━━
   Found 2 commits since arrays-v1.2.0
@@ -86,7 +75,7 @@ Example output from `prepare --dry-run` in a monorepo whose `arrays` workspace h
   📦 1.2.0 → 1.3.0 (minor)
     [dry-run] Would bump packages/arrays/package.json
   Generating changelogs...
-    [dry-run] Would run: npx --prefer-offline --yes git-cliff@<version> ... --output packages/arrays/CHANGELOG.md
+    [dry-run] Would generate changelog: packages/arrays/CHANGELOG.md
   🔖 arrays-v1.3.0
 
 ✅ Release preparation complete.
@@ -102,17 +91,21 @@ gh workflow run release.yaml                  # every workspace with release-wor
 gh workflow run release.yaml -f only=arrays   # the named workspaces alone
 ```
 
-The CLI applies defaults to every discovered workspace and uses the bundled `cliff.toml.template` unless the repository provides a git-cliff config of its own. [Releasing](docs/releasing.md) covers `prepare`'s flags, release-notes previews, and the workflow's inputs.
+After upgrading release-kit, run `release-kit update-templates` to update the scaffolded workflows to its templates; it leaves the config files alone.
+
+The CLI applies defaults to every discovered workspace. [Releasing](docs/releasing.md) covers `prepare`'s flags, release-notes previews, and the workflow's inputs.
 
 ## How it works
 
-1. **Workspace discovery**: reads `pnpm-workspace.yaml` and resolves its `packages` patterns to find workspace directories, applying pnpm's semantics — a `!`-prefixed entry excludes what it matches, wherever it appears in the list. Each directory containing a `package.json` becomes a workspace. The repo is treated as a single-package project when it holds no workspace file, and when the workspace file declares no `packages` list — a file kept for `catalog:` or `overrides:` alone, which pnpm likewise resolves to the root package. A workspace file that declares patterns resolving to no package is an error naming the condition that emptied it.
-2. **Config loading**: loads `.config/release-kit.config.ts` (if present), or the file named by `--config`, and merges it with discovered defaults.
-3. **Commit analysis**: for each workspace, finds commits since the last version tag, parses them for type and scope, and determines the appropriate version bump.
-4. **Version bump + changelog**: bumps `package.json` versions, builds structured `ChangelogEntry[]` from `git-cliff --context`, applies any [editorial overrides](docs/editorial-overrides.md) from per-scope `.meta/changelog-overrides.json` files, and renders both `CHANGELOG.md` and `.meta/changelog.json` from that single source. `git-cliff` is invoked only for its `--context` JSON; markdown rendering happens in-process so `.meta/changelog.json` and `CHANGELOG.md` always agree.
-5. **Release tags file**: writes computed tags to `tmp/.release-tags` for the release workflow to read when tagging and pushing.
+Every command other than `--version` and `--help` first locates the repo root and runs from it, so it can be invoked from any directory in the repo. The root is the nearest directory at or above the invocation directory that contains `pnpm-workspace.yaml`, or else the invocation directory itself when it contains a `package.json`; when neither exists, the command fails. Because a `pnpm-workspace.yaml` takes precedence wherever it is, as it does for pnpm, a single-package repo checked out below a pnpm workspace resolves to that outer workspace.
+
+1. **Workspace discovery**: Reads `pnpm-workspace.yaml` and resolves its `packages` patterns to find workspace directories, applying pnpm's semantics: A `!`-prefixed entry excludes what it matches, wherever it appears in the list. Each directory containing a `package.json` becomes a workspace. The repo is treated as a single-package project when it doesn't contain a workspace file, and when the workspace file doesn't declare a `packages` list: a file kept for `catalog:` or `overrides:` alone, which pnpm likewise resolves to the root package. A workspace file that declares patterns that don't resolve to any package is an error naming the condition that emptied it.
+2. **Config loading**: Loads `.config/release-kit.config.ts` (if present) from the repo root, or the file named by `--config` relative to the invocation directory, and merges it with discovered defaults.
+3. **Commit analysis**: For each workspace, reads the history once, builds the changelog items of the commits since the last version tag, and takes the bump as the highest level that those items call for.
+4. **Version bump + changelog**: Bumps `package.json` versions, builds structured `ChangelogEntry[]` from the commits between each pair of release tags, applies any [editorial overrides](docs/editorial-overrides.md) from per-scope `.meta/changelog-overrides.json` files, and renders both `CHANGELOG.md` and `.meta/changelog.json` from that single source, so the two always agree.
+5. **Release tags file**: Writes computed tags to `tmp/.release-tags` for the release workflow to read when tagging and pushing.
 
-[Changelogs](docs/changelogs.md) covers what reaches a published tarball, the `changelog.json` item schema, and the git-cliff config.
+[Changelogs](docs/changelogs.md) covers what a published tarball includes, the `changelog.json` item schema, and which commits appear in a changelog.
 
 ## Commit format
 
@@ -127,15 +120,15 @@ scope|type!: description       # scoped breaking change
 type(scope)!: description      # conventional scoped breaking change
 ```
 
-The `scope|type:` format scopes a commit to a specific workspace in a monorepo. Use `scopeAliases` in your config to map shorthand names to canonical scope names.
+The `scope|type:` format scopes a commit to a specific workspace in a monorepo. Use `scopeAliases` in the config to map shorthand names to canonical scope names.
 
 [Work types and tiers](docs/work-types.md) lists the recognized types and how each one affects the bump and the changelog.
 
 ## Configuration
 
-Configuration is optional. The CLI works out of the box by auto-discovering workspaces and applying defaults. Create `.config/release-kit.config.ts` only when you need to customize behavior.
+Configuration is optional. The CLI works out of the box by auto-discovering workspaces and applying defaults. Create `.config/release-kit.config.ts` only to customize behavior.
 
-Every subcommand that reads a config accepts `--config <path>` to read a file elsewhere. An absent default path means "no config"; an absent `--config` path fails the command. See [Config file location](docs/configuration.md#config-file-location).
+Every subcommand that reads a config accepts `--config <path>` to read a file elsewhere. An absent default path means that the repo doesn't declare a config; an absent `--config` path fails the command. See [Config file location](docs/configuration.md#config-file-location).
 
 ```typescript
 import { defineConfig } from '@williamthorsen/release-kit/config';
@@ -155,18 +148,15 @@ export default defineConfig({
 });
 ```
 
-`defineConfig` is a type-safe identity function: it gives the config object validation and completion in `.ts` files and full inference in `.js` ones. The loader also accepts a plain `export default config` or `export const config = { ... }`.
+`defineConfig` is a type-safe identity function: It gives the config object validation and completion in `.ts` files and full inference in `.js` ones. The loader also accepts a plain `export default config` or `export const config = { ... }`.
 
-Node loads the file directly, so a relative import inside it needs an explicit file extension — `./work-types.ts`, not `./work-types`.
+Node loads the file directly, so a relative import inside it needs an explicit file extension: `./work-types.ts`, not `./work-types`.
 
 [Configuration](docs/configuration.md) lists every field and covers legacy identities, retired packages, and tag prefixes. [Project releases](docs/project-releases.md) covers releasing a monorepo as one combined deliverable.
 
 ## External dependencies
 
-This package shells out to two external tools:
-
-- **`git`** — must be available on `PATH`. Used to find tags and retrieve commit history.
-- **`git-cliff`** — pinned to an exact version and fetched via `npx` on first invocation, then served from npx's cache. No need to install it as a dev dependency. The pin moves only when a new release-kit version names a newer git-cliff, so two releases cut months apart run the same changelog generator.
+release-kit shells out to `git`, which must be available on `PATH`, to find tags and read commit history.
 
 ## Readiness checks
 
@@ -185,7 +175,7 @@ export default defineRdyConfig({
 rdy run --packages
 ```
 
-`rdy run` needs `readyup` 0.23 or later, and `@williamthorsen/release-kit` as a _direct_ devDependency: a strict pnpm layout links nothing else into the project; therefore, a transitive copy is unreachable.
+`rdy run` needs `readyup` 0.23 or later, and `@williamthorsen/release-kit` as a _direct_ devDependency: A strict pnpm layout links nothing else into the project; therefore, a transitive copy is unreachable.
 
 [Readiness checks](docs/readiness-checks.md) covers running each kit alone and what `npm-auto-publish` needs from the npm session.
 
@@ -195,20 +185,18 @@ rdy run --packages
 2. Remove `@changesets/cli` from dev dependencies. The [default readyup kit](#readiness-checks) reports a repo that still declares it.
 3. Delete the `.changeset/` directory.
 4. Run `npx @williamthorsen/release-kit init` to scaffold the release workflows.
-5. Remove `changeset:*` scripts from `package.json` (no replacement needed — the CLI handles everything).
+5. Remove `changeset:*` scripts from `package.json` (they don't need a replacement, because the CLI handles everything).
 6. Create an initial version tag for each package (e.g., `git tag v1.0.0` or `git tag arrays-v1.0.0`).
 
-No cliff config copy is needed — the bundled template is used automatically. To customize, run `release-kit init --with-config`.
-
 ## Documentation
 
 - [Configuration](docs/configuration.md): `ReleaseKitConfig` fields, workspace overrides and legacy identities, retired packages, tag prefixes, and version patterns
-- [Project releases](docs/project-releases.md): the `project` block, and how a project release interacts with `prepare`'s flags
-- [Releasing](docs/releasing.md): `init`, `prepare`'s flags and release-notes previews, and the release workflow
+- [Project releases](docs/project-releases.md): The `project` block, and how a project release interacts with `prepare`'s flags
+- [Releasing](docs/releasing.md): `init`, `update-templates`, `prepare`'s flags and release-notes previews, and the release workflow
 - [Publishing](docs/publishing.md): `publish`, the publishability filter, and `create-github-release`
-- [Changelogs](docs/changelogs.md): the `changelog.json` item schema, the git-cliff config, and release-notes injection
-- [Editorial overrides](docs/editorial-overrides.md): correcting generated changelog entries, and `overrides validate`
-- [Work types and tiers](docs/work-types.md): tiers, the `!` policy, markers, custom work types, and maintenance of the bundled taxonomy
-- [Labels](docs/labels.md): `sync-labels`, label configuration, the workflow's triggers, and the `label-map.json` schema
-- [Readiness checks](docs/readiness-checks.md): both readyup kits, and how to run each
+- [Changelogs](docs/changelogs.md): The `changelog.json` item schema, which commits appear in a changelog, and release-notes injection
+- [Editorial overrides](docs/editorial-overrides.md): Correcting generated changelog entries, and `overrides validate`
+- [Work types and tiers](docs/work-types.md): Tiers, the `!` policy, markers, and custom work types
+- [Labels](docs/labels.md): `sync-labels`, label configuration, the workflow's triggers, and where the `label-map.json` schema is published
+- [Readiness checks](docs/readiness-checks.md): Both readyup kits, and how to run each
 - [Programmatic API](docs/api.md): `deriveWorkspaceConfig()`, the script-based approach, and `resolveReleaseTags`

package/bin/release-kit.js

@@ -3,7 +3,7 @@ try {
   await import('../dist/esm/bin/release-kit.js');
 } catch (error) {
   if (error.code === 'ERR_MODULE_NOT_FOUND') {
-    process.stderr.write('release-kit: build output not found — run `nmr build` first\n');
+    process.stderr.write('release-kit: build output not found; run `nmr build` first\n');
   } else {
     process.stderr.write(`release-kit: failed to load: ${error.message}\n`);
   }

package/dist/esm/assertCleanWorkingTree.d.ts

@@ -1,6 +1,2 @@
-/**
- * Verify that the git working tree has no uncommitted changes.
- *
- * @throws If `git status --porcelain` reports any changes.
- */
+/** Throws if `git status --porcelain` reports any uncommitted change in the working tree. */
 export declare function assertCleanWorkingTree(): void;

package/dist/esm/assertTaggedBaseline.d.ts

@@ -0,0 +1,29 @@
+import type { ReleaseConfig } from './types.js';
+/** A release target whose history `prepare` has read, as the baseline check sees it. */
+export interface BaselineTarget {
+    /** How the error names the target, such as `workspace 'core'`. */
+    label: string;
+    packageFiles: readonly string[];
+    changelogPaths: readonly string[];
+    /** The prefixes under which the history was read; a missing tag is named under the first. */
+    tagPrefixes: readonly string[];
+    previousTag: string | undefined;
+}
+/** A target whose current version is recorded in its changelog but is not its previous reachable tag. */
+export interface UntaggedBaseline {
+    label: string;
+    version: string;
+    /** The tag to create at the commit that released `version`. */
+    tag: string;
+}
+/**
+ * Throws when any finding is an untagged baseline, naming each one's missing tag. Without that tag, the unreleased
+ * window extends back to the start of history, so the new version would include every earlier commit.
+ */
+export declare function assertTaggedBaseline(findings: ReadonlyArray<UntaggedBaseline | undefined>): void;
+/**
+ * Returns the target's untagged baseline: its current version appears in one of its `CHANGELOG.md` or
+ * `changelog.json` files, and its previous tag is not that version under any of its prefixes. A first release has
+ * none, because its changelogs do not record its version yet.
+ */
+export declare function findUntaggedBaseline(target: BaselineTarget, config: Pick<ReleaseConfig, 'changelogJson'>): UntaggedBaseline | undefined;

package/dist/esm/assertTaggedBaseline.js

@@ -0,0 +1,41 @@
+import { join } from 'node:path';
+import { resolveChangelogJsonPath } from "./changelogJsonFile.js";
+import { readChangelogEntries } from "./changelogJsonUtils.js";
+import { readCurrentVersion } from "./planVersionBump.js";
+import { readChangelogSections } from "./readChangelogSections.js";
+export function assertTaggedBaseline(findings) {
+    const untagged = findings.filter((finding) => finding !== undefined);
+    if (untagged.length === 0)
+        return;
+    const lines = untagged.map(({ label, version, tag }) => `  - ${label}: ${version} (create tag ${tag})`);
+    throw new Error([
+        'The current version is recorded in the changelog, but its tag is not the previous tag reachable from HEAD:',
+        ...lines,
+        'Tag the commit that released each version, then run prepare again.',
+    ].join('\n'));
+}
+export function findUntaggedBaseline(target, config) {
+    const recordedVersions = readRecordedVersions(target.changelogPaths, config);
+    if (recordedVersions.size === 0) {
+        return undefined;
+    }
+    const version = readCurrentVersion(target.packageFiles);
+    if (!recordedVersions.has(version)) {
+        return undefined;
+    }
+    if (target.tagPrefixes.some((prefix) => target.previousTag === `${prefix}${version}`)) {
+        return undefined;
+    }
+    return { label: target.label, version, tag: `${target.tagPrefixes[0] ?? ''}${version}` };
+}
+function readRecordedVersions(changelogPaths, config) {
+    const versions = new Set();
+    for (const changelogPath of changelogPaths) {
+        const { versioned } = readChangelogSections(join(changelogPath, 'CHANGELOG.md'));
+        const entries = readChangelogEntries(resolveChangelogJsonPath(config, changelogPath)) ?? [];
+        for (const { version } of [...versioned, ...entries]) {
+            versions.add(version);
+        }
+    }
+    return versions;
+}

package/dist/esm/attachChangelogDiagnostics.d.ts

@@ -0,0 +1,4 @@
+import type { ChangelogDiagnostics } from './buildChangelogEntries.js';
+import type { ReleasedWorkspaceResult } from './types.js';
+/** Attaches a history's diagnostics to a released or skipped result, omitting each empty list. */
+export declare function attachChangelogDiagnostics(result: Pick<ReleasedWorkspaceResult, 'malformedBlocks' | 'policyViolations' | 'undeclaredEntryTypes' | 'unroutedEntryScopes'>, diagnostics: ChangelogDiagnostics): void;

package/dist/esm/attachChangelogDiagnostics.js

@@ -0,0 +1,14 @@
+export function attachChangelogDiagnostics(result, diagnostics) {
+    if (diagnostics.malformedBlocks.length > 0) {
+        result.malformedBlocks = diagnostics.malformedBlocks;
+    }
+    if (diagnostics.undeclaredEntryTypes.length > 0) {
+        result.undeclaredEntryTypes = diagnostics.undeclaredEntryTypes;
+    }
+    if (diagnostics.policyViolations.length > 0) {
+        result.policyViolations = diagnostics.policyViolations;
+    }
+    if (diagnostics.unroutedEntryScopes.length > 0) {
+        result.unroutedEntryScopes = diagnostics.unroutedEntryScopes;
+    }
+}