@williamthorsen/release-kit 11.0.0 → 12.0.0

package/docs/changelogs.md

@@ -1,26 +1,29 @@
 # Changelogs
 
-What reaches a published tarball, what each `.meta/changelog.json` item contains, how the git-cliff config is resolved, and how release notes reach a README.
+What reaches a published tarball, what each `.meta/changelog.json` item contains, which commits reach a changelog, how a merge commit's change-record block becomes items, and how release notes reach a README.
 
 Neither `CHANGELOG.md` nor `.meta/changelog.json` reaches a published tarball on its own. npm stopped including `CHANGELOG` automatically in npm 7, so a package that declares a `files` field ships a changelog only where that field names `CHANGELOG.md` and `.meta/changelog.json`. release-kit's readyup kit reports a publishable workspace whose `files` field omits either.
 
 ## `changelog.json` item schema
 
-Each item under a section in `.meta/changelog.json` carries one required field and four optional ones:
+Each item under a section in `.meta/changelog.json` carries one required field and five optional ones:
 
-| Field         | Type      | Meaning                                                                                                                                                                         |
-| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `description` | `string`  | The bullet headline, taken from the commit subject with the ticket ID and type prefix stripped.                                                                                 |
-| `body`        | `string`  | The commit body, with trailing trailer metadata stripped.                                                                                                                       |
-| `breaking`    | `boolean` | Present and `true` where the commit subject carried the `!` prefix and the commit's type permits it. See [`!` (breaking change) policy](work-types.md#-breaking-change-policy). |
-| `migration`   | `string`  | The migration step for a consumer. See below.                                                                                                                                   |
-| `hash`        | `string`  | The full commit SHA, and the key on which an override entry matches. Absent on synthetic propagation entries.                                                                   |
+| Field         | Type      | Meaning                                                                                                                                                                                                                  |
+| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `description` | `string`  | The bullet headline, taken from the commit subject with the ticket ID and type prefix stripped, or from a change-record entry's `text` (see [Change-record blocks](#change-record-blocks)).                              |
+| `body`        | `string`  | The commit body, with trailing trailer metadata and any `change-record` block stripped. Absent on an item derived from a change-record entry.                                                                            |
+| `breaking`    | `boolean` | Present and `true` where the commit subject carried the `!` prefix, or the change-record entry set `breaking: true`, and the type permits it. See [`!` (breaking change) policy](work-types.md#-breaking-change-policy). |
+| `migration`   | `string`  | The migration step for a consumer. See below.                                                                                                                                                                            |
+| `hash`        | `string`  | The full commit SHA, which an override key matches by prefix. Absent on synthetic propagation entries.                                                                                                                   |
+| `entry`       | `number`  | The 1-based position of the change-record entry from which the item derives, which an override key `<hash>:<n>` matches. Absent on an item derived from the commit's title.                                              |
 
 Every optional field is omitted rather than emitted as `null`, so a consumer tests for presence.
 
 ### The `migration` field
 
-A commit body states a migration step as a paragraph opening with the literal label `Migration:`. Where one is present, `migration` carries that paragraph with the label stripped:
+A commit body states a migration step as a paragraph opening with the literal label `Migration:`. Where one is present, `migration` carries that paragraph with the label stripped. An item derived from a change-record entry takes `migration` from the entry instead, and has no `body`.
+
+A title-derived item looks like this:
 
 ```jsonc
 {
@@ -34,30 +37,66 @@ Three properties are worth knowing:
 
 - **It is independent of `breaking`.** A `deprecate` cannot carry `!` under the default breaking policy, and a `deprecate` still calls for a migration. Filter on `migration` to find every step; filter on `breaking` to find every breaking change.
 - **`body` keeps the paragraph.** The field is an extraction, not a move, so `CHANGELOG.md` and `.meta/changelog.json` go on agreeing.
-- **It is derived, not authored.** `migration` is not a field an override file can set (see [File shape](editorial-overrides.md#file-shape)); it is re-derived from whatever `body` an override installs, and cleared where that body carries no labeled paragraph. To change the migration text, override `body`.
+- **An override cannot set it.** `migration` is not a field an override file can set (see [File shape](editorial-overrides.md#file-shape)). On a title-derived item it is re-derived from whatever `body` an override installs, and cleared where that body carries no labeled paragraph, so overriding `body` changes the migration text. An entry-derived item keeps its entry's `migration` whatever `body` an override installs.
 
 The label match is exact: `migration:` and `**Migration:**` are not recognized.
 
-## cliff.toml setup
+## What reaches a changelog
+
+release-kit splits the history reachable from `HEAD` into one window per release tag that matches the scope's tag prefixes, restricted to commits that touch the scope's `paths`. The bump reads the same items: Its level is the highest that the unreleased window's items call for, so a commit that bumps is one that the changelog lists.
+
+A commit whose last `change-record` block records entries yields its items from those entries, as [Change-record blocks](#change-record-blocks) describes. Any other commit in a window reaches the changelog when its subject passes three checks:
+
+- **A ticket-ID prefix**, such as `#42 `, `TOOL-123 `, or `## `.
+- **A declared work type**, resolved against the merged [work types](work-types.md).
+- **A type not excluded from the changelog** by `excludedFromChangelog: true`.
+
+`release:` commits and merge commits whose subject git wrote (`Merge …`) never reach a changelog, whether or not they carry a block. A commit that fails a check yields no item and raises no bump, and a release left with no surviving commit gets no changelog entry. The prepare report lists a commit of the unreleased window that fails the first or the second check as unparseable, unless a malformed-block warning already reports it; it lists none that fails the third. The commit's type decides the section under which its item appears.
+
+Every item of a commit reaches every workspace whose window contains the commit, because windows are selected by the paths that the commit touches.
+
+## Change-record blocks
+
+A squash-merge commit composed from a pull request can end with a fenced block whose info string is exactly `change-record`. Its payload is YAML, with the grammar that codeassembly's `change-record.md` specifies. release-kit reads these keys and ignores any other:
+
+| Key                   | Type     | Meaning                                                                         |
+| --------------------- | -------- | ------------------------------------------------------------------------------- |
+| `entries`             | list     | The change entries, one per outcome of the change, in the order that they read. |
+| `entries[].type`      | `string` | A work type, resolved through the declared types and their aliases. Required.   |
+| `entries[].text`      | `string` | The sentence that reports the outcome. Required.                                |
+| `entries[].breaking`  | boolean  | Whether the outcome breaks consumers.                                           |
+| `entries[].scopes`    | list     | The scopes that the outcome touched, each a string. Validated but not yet used. |
+| `entries[].migration` | `string` | The migration step for a consumer.                                              |
+| `pr_number`           | integer  | The merged pull request's number, a positive integer.                           |
+| `ticket_ref`          | `string` | The ticket that the change serves. Validated but not yet used.                  |
+
+release-kit reads the **last** `change-record` fence in the message. A key whose value is null reads as absent.
+
+### Items from entries
+
+Each entry yields one item, whether or not the commit subject carries a ticket-ID prefix or a declared type:
+
+- **Section**: the header of the entry's `type`, so the section order and the audience follow as for a title.
+- **`description`**: the entry's `text` as written, followed by ` (#N)` when the block records `pr_number`.
+- **`breaking`**: set when the entry's `breaking` is `true` and the type's breaking policy permits it.
+- **`migration`**: the entry's `migration`, when present. There is no `body`.
+- **`hash`** and **`entry`**: the commit's hash, and the entry's 1-based position among all the block's entries, including those that yield no item.
+
+An entry whose type is excluded from the changelog yields no item. An override targets one of these items by the key `<hash>:<n>`, where `n` is the item's `entry`. A bare `<hash>` key matches every item of the commit, and it fails when it sets `description` or `body` on a commit with several items; see [Keys](editorial-overrides.md#keys).
 
-The package includes a bundled `cliff.toml.template` that is used automatically when no custom config is found. The resolution order:
+### Fallback to the title
 
-| Priority | Path                          | Notes                                           |
-| -------- | ----------------------------- | ----------------------------------------------- |
-| 1        | `cliffConfigPath` in config   | Explicit path, returned without existence check |
-| 2        | `.config/git-cliff.toml`      | Project-level override                          |
-| 3        | `cliff.toml`                  | Repo root fallback                              |
-| 4        | Bundled `cliff.toml.template` | Automatic fallback                              |
+A commit is read from its title, as [What reaches a changelog](#what-reaches-a-changelog) describes, when it has no block, when the block's `entries` is absent or empty, or when the block is malformed. A block is malformed when it never closes, when its payload is not valid YAML or not a mapping, when `entries` is not a list, when an entry is not a mapping, when an entry's `type` or `text` is missing, blank, or not a string, when `breaking` is not a boolean, when `scopes` is not a list of strings, when `migration` or `ticket_ref` is not a string, or when `pr_number` is not a positive integer. One defect makes the whole block malformed.
 
-The bundled template provides a generic git-cliff configuration that:
+### Reported diagnostics
 
-- Strips issue-ticket prefixes matching `^[A-Z]+-\d+\s+` (e.g., `TOOL-123 `, `AFG-456 `)
-- Handles both `type: description` and `workspace|type: description` commit formats
-- Groups commits by work type via `[git].commit_parsers`
+`release-kit prepare` reports these as warnings for the release being prepared, from the commits that no earlier release contains:
 
-The body template is intentionally empty: release-kit reads cliff's `--context` JSON output and renders `CHANGELOG.md` in-process via `renderChangelogMarkdown` (see [How it works](../README.md#how-it-works) for the rationale). The `[git].commit_parsers` section remains load-bearing for `--context` group assignment.
+- **A malformed block**, with the defect that stopped the read.
+- **An entry whose type is not declared**, with its position. It yields no item.
+- **An entry that violates its type's breaking policy**, as a policy violation at the entry's position. Its item is not marked breaking.
 
-To customize, scaffold a local copy with `release-kit init --with-config` and edit `.config/git-cliff.toml`. Edit only the `[git]` section — body-template changes have no effect.
+The result that `prepare` returns carries these as `malformedBlocks`, `undeclaredEntryTypes`, and `policyViolations` entries whose `surface` is `'entry'`, whether the target releases or is skipped. A block whose entries are all undeclared or excluded yields no item, so the commit raises no bump.
 
 ## Release-notes injection
 

package/docs/configuration.md

@@ -18,7 +18,6 @@ The two paths differ in what an absent file means. An absent default path means
 
 | Field              | Type                                                      | Description                                                                                                                                                                                   |
 | ------------------ | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cliffConfigPath`  | `string`                                                  | Explicit path to cliff config. If omitted, resolved automatically: `.config/git-cliff.toml` → `cliff.toml` → bundled template                                                                 |
 | `workspaces`       | `WorkspaceOverride[]`                                     | Override or exclude discovered workspaces (matched by `dir`)                                                                                                                                  |
 | `formatCommand`    | `string`                                                  | Shell command to run after changelog generation; modified file paths are appended as arguments                                                                                                |
 | `versionPatterns`  | `VersionPatterns`                                         | Rules for which commit types trigger major/minor bumps                                                                                                                                        |
@@ -89,7 +88,7 @@ Tag prefixes from distinct owners must not be identical or be a strict prefix of
 - A `retiredPackages[]` entry (one owner per entry).
 - The `project` block, when configured.
 
-release-kit resolves baseline tags via `git describe --match=<prefix>*`, so a strict-prefix overlap between distinct owners would cause that glob to return cross-matches against the wrong owner's history. For example, a project prefix of `v` collides with a workspace prefix of `vue-helpers-v`, since `git describe --match=v*` would return both project tags and `vue-helpers` tags.
+release-kit matches a tag to a prefix when the tag name starts with the prefix and continues with a digit, so a strict-prefix overlap between distinct owners can match the wrong owner's tags. For example, a project prefix of `v` collides with a workspace prefix of `v11y-check-v`, since `v11y-check-v1.0.0` starts with `v` followed by a digit. The rule rejects every strict-prefix overlap, including one such as `v` and `vue-helpers-v` that no tag of the longer prefix can reach.
 
 The rule is enforced at config load; the resulting error identifies both colliding declarations.
 
@@ -105,7 +104,7 @@ In single-package mode, prints a single row with `workspacePath = .` and `derive
 
 ## `VersionPatterns`
 
-Defines which commit types trigger major or minor bumps. Any recognized type not listed defaults to a patch bump.
+Defines which work types trigger major or minor bumps. `prepare` applies it to each changelog item of the unreleased window and takes the highest level. An item of a type not listed bumps patch.
 
 ```typescript
 interface VersionPatterns {

package/docs/editorial-overrides.md

@@ -1,10 +1,10 @@
 # Editorial overrides
 
-How to correct a generated changelog entry without rewriting history: where override files live, how they compose, what an entry may set, and how to validate the files.
+How to correct a generated changelog entry without rewriting history: where override files live, how they compose, how a key targets items, what an entry may set, and how to validate the files.
 
 Generated changelogs occasionally need editorial correction — typos, redacted scope, reworded entries, or historical commits whose bodies carry verbatim PR-template scaffolding (`## What`, `## Why`, etc.) that renders as literal text in user-facing release notes. Rewriting git history is not viable, and any in-place edit to `CHANGELOG.md` or `.meta/changelog.json` is overwritten on the next release because release-kit regenerates both artifacts from scratch.
 
-Override files are the supported escape hatch. Drop a checked-in JSON file at the conventional path for the scope you want to influence, keyed by commit hash, and `release-kit prepare` applies the overrides between `buildChangelogEntries` and serialization. Both `CHANGELOG.md` and `.meta/changelog.json` reflect the post-override view, so downstream consumers (the GitHub Release body, the in-app release-notes page, etc.) see the same content.
+Override files are the supported escape hatch. Drop a checked-in JSON file at the conventional path for the scope you want to influence, keyed by commit hash or by commit hash and entry position, and `release-kit prepare` applies the overrides between `buildChangelogEntries` and serialization. Both `CHANGELOG.md` and `.meta/changelog.json` reflect the post-override view, so downstream consumers (the GitHub Release body, the in-app release-notes page, etc.) see the same content.
 
 ## File-location convention
 
@@ -22,8 +22,8 @@ When a workspace's changelog is rendered, both files are consulted:
 
 - The root file's overrides apply globally.
 - The workspace file's overrides apply only to that workspace.
-- When the **same hash key** (string-equal, byte-for-byte) appears in both files, the **workspace entry wins entirely** for that workspace's changelog — no field-level merge, the workspace entry replaces the root entry.
-- Different prefix strings that happen to resolve to the same commit do **not** shadow; they fall through to the existing ambiguous-prefix error so you can correct your override file.
+- When the **same key** (string-equal, byte-for-byte) appears in both files, the **workspace entry wins entirely** for that workspace's changelog — no field-level merge, the workspace entry replaces the root entry.
+- Non-identical keys that match the same item, such as a root `abc1234` beside a workspace `abc1234:2`, or two prefixes of one commit, do **not** shadow. The run fails with the [overlapping-keys error](#conflicting-keys), which names both keys.
 - Other keys in the root file still apply for that workspace.
 
 The project-level changelog applies only the root file. Per-workspace files describe per-workspace editorial intent and have no meaning at the aggregated project tier.
@@ -39,9 +39,13 @@ A key that doesn't match any commit gets a stale-reference warning. The warning'
 
 ```json
 {
+  "$schema": "https://github.com/williamthorsen/node-monorepo-tools/raw/release-kit-v<version>/packages/release-kit/schemas/changelog-overrides.json",
   "82962311": {
     "audience": "skip"
   },
+  "3f0c9a1:2": {
+    "description": "Reworded headline for the second change-record entry"
+  },
   "abc1234d": {
     "body": "Cleaned-up prose without the original PR-template scaffolding."
   },
@@ -52,7 +56,7 @@ A key that doesn't match any commit gets a stale-reference warning. The warning'
 }
 ```
 
-Per-entry fields are all optional, but at least one must be present per entry:
+The top-level `$schema` key is optional and names the [published JSON Schema](#published-json-schema) for editor support; it is not an override. Per-entry fields are all optional, but at least one must be present per entry:
 
 | Field         | Type                       | Effect                                                                                                                            |
 | ------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
@@ -61,15 +65,44 @@ Per-entry fields are all optional, but at least one must be present per entry:
 | `body`        | `string`                   | Replaces the entry's body (the prose that renders below the bullet). Other fields are preserved.                                  |
 | `breaking`    | `boolean`                  | Toggles the `🚨 **Breaking:** ` marker on the bullet.                                                                             |
 
-There is no `migration` key: the field is derived from `body`, so an override that replaces `body` re-derives it. See [The `migration` field](changelogs.md#the-migration-field).
+There is no `migration` key: On a title-derived item the field is derived from `body`, so an override that replaces `body` re-derives it, and an item derived from a change-record entry keeps its entry's `migration`. See [The `migration` field](changelogs.md#the-migration-field).
+
+## Keys
+
+A key takes one of two forms. In both, the hash part is lowercase hex and matches as a prefix of the commit hash.
+
+| Key          | Targets                                                          |
+| ------------ | ---------------------------------------------------------------- |
+| `<hash>`     | Every item of the commit                                         |
+| `<hash>:<n>` | The one item derived from the commit's `n`th change-record entry |
+
+`n` counts from 1 over the `entries` of the commit's [change-record block](changelogs.md#change-record-blocks), in the order in which the PR lists them, including entries that yield no item. An item derived from the commit's title has no entry position, so `<hash>:<n>` never matches it. Any other key fails loading.
+
+The hash part can be the full 40-character SHA or a prefix. `prepare` resolves it against the distinct commit hashes in the changelog:
+
+- **One commit** — the override applies to the items that the key targets. A 7-character prefix is usually unambiguous within a single repo's history; longer prefixes are always safe.
+- **No commit** — the override is treated as a stale reference (probably from a rebase or branch deletion) and prepare reports a warning. The release continues. An ordinal key whose commit has no item at position `n` is stale in the same way.
+- **Several commits** — the release aborts with an error naming the key and the matching hashes. Lengthen the prefix or use the full SHA.
+
+### Conflicting keys
 
-## Hash-prefix matching
+Two further conditions abort the release. Each counts the items within one changelog.
 
-Keys can be either the full 40-character commit SHA or a non-ambiguous prefix. The matcher walks every `ChangelogItem.hash` value present in the entry tree and resolves each override key to its set of matching hashes:
+- **A bare key that sets `description` or `body` on a commit with several items.** One headline or body cannot replace several different ones, so the error names the ordinal keys to use instead: `Override key 'abc1234' sets description on a commit with several items; use abc1234:1, abc1234:2`. `audience` and `breaking` on a bare key still apply to every item.
+- **Two non-identical keys that match the same item.** The error names both keys, such as `Override keys 'abc1234' and 'abc1234:2' both match the item at abc1234:2; keep one`. Neither override applies to the item.
+
+### Example: one commit, several items
+
+Suppose commit `3f0c9a1` merged a PR whose change record lists three entries. Its changelog contains three items, and each key below targets one of them:
+
+```json
+{
+  "3f0c9a1:2": { "description": "Reworded headline for the second entry" },
+  "3f0c9a1:3": { "audience": "skip" }
+}
+```
 
-- **Exact prefix match (1 hit)** — the override applies. A 7-character prefix is usually unambiguous within a single repo's history; longer prefixes are always safe.
-- **No matches (0 hits)** — the override is treated as a stale reference (probably from a rebase or branch deletion) and prepare reports a warning. The release continues.
-- **Ambiguous prefix (2+ hits)** — the release aborts with an error naming the key and the matching hashes. Lengthen the prefix or use the full SHA.
+A bare `"3f0c9a1": { "audience": "skip" }` would skip all three items instead. Adding it beside the keys above fails the run, because it overlaps each of them.
 
 Override application errors abort the run with a non-zero exit; warnings (zero-match keys) are non-fatal and surface on `PrepareResult.warnings`.
 
@@ -79,12 +112,16 @@ The override file is validated when `release-kit prepare` loads it. Each error n
 
 - Missing file → empty map, no error (the no-op default — projects that do not need overrides skip the file entirely).
 - Malformed JSON → error.
+- A key that is neither `<hash>` nor `<hash>:<n>` (uppercase hex, non-hex characters, `:0`, a leading zero in `n`) → error.
+- A top-level `$schema` that is not a string → error.
 - Wrong top-level shape (e.g., array, primitive) → error.
 - Unknown fields on an entry → error.
 - Wrong field types (e.g., `description` as a number) → error.
 - An entry with no fields set → error (a copy-paste mistake more often than not).
 - `audience: 'all'` or `audience: 'dev'` → error in the current release: only `'skip'` is supported (see below).
 
+Applying the overrides then aborts the run on an ambiguous prefix and on either of the [conflicting-key conditions](#conflicting-keys): a bare key setting `description` or `body` on a commit with several items, and two keys matching the same item.
+
 ### Standalone validation: `release-kit overrides validate`
 
 For a focused overrides-only health check (locally or as a CI gate), run:
@@ -95,16 +132,38 @@ pnpm exec release-kit overrides validate
 
 This walks every `.meta/changelog-overrides.json` file across the project tier and per-workspace tier, reporting three classes of finding:
 
-| Class               | Examples                                                                                    | Exit code |
-| ------------------- | ------------------------------------------------------------------------------------------- | --------- |
-| Schema/parse errors | malformed JSON, unknown fields, wrong field types, no-field entries, unsupported `audience` | `2`       |
-| Ambiguous-prefix    | an override key resolves to 2+ commit hashes                                                | `2`       |
-| Stale-key warnings  | an override key resolves to no commit in its applicable scope                               | `1`       |
+| Class               | Examples                                                                                                    | Exit code |
+| ------------------- | ----------------------------------------------------------------------------------------------------------- | --------- |
+| Schema/parse errors | malformed JSON, malformed keys, unknown fields, wrong field types, no-field entries, unsupported `audience` | `2`       |
+| Ambiguous-prefix    | an override key resolves to 2+ commit hashes                                                                | `2`       |
+| Conflicting keys    | a bare key sets `description` or `body` on a commit with several items; two keys match the same item        | `2`       |
+| Stale-key warnings  | an override key resolves to no item in its applicable scope                                                 | `1`       |
 
 Tier-aware stale-key semantics match `release-kit prepare`'s match-set exactly: a workspace-tier key is stale if it does not match in its own workspace's history; a root-tier key is stale only if it matches in **no** scope (no workspace AND not the project release window).
 
+Conflicting keys are found within one file and across the root and workspace files, as `prepare` composes them. An overlap between a root key and a workspace key is reported against the workspace file.
+
 The same logic is also exposed programmatically via the `validateAllChangelogOverrides` function exported from `@williamthorsen/release-kit`, for callers that want to integrate the check into their own tooling.
 
+## Published JSON Schema
+
+release-kit publishes a JSON Schema for the override file. The schema lives at `packages/release-kit/schemas/changelog-overrides.json` in this repo and is reachable via the stable raw URL:
+
+```
+https://github.com/williamthorsen/node-monorepo-tools/raw/release-kit-v<version>/packages/release-kit/schemas/changelog-overrides.json
+```
+
+An override file references it from its top-level `$schema` key:
+
+```json
+{
+  "$schema": "https://github.com/williamthorsen/node-monorepo-tools/raw/release-kit-v<version>/packages/release-kit/schemas/changelog-overrides.json",
+  "82962311": { "audience": "skip" }
+}
+```
+
+The schema states the key form and the entry fields. It accepts `audience` values `'all'` and `'dev'`, which the file format declares; the loader still rejects them (see below).
+
 ## Audience semantics: v1 supports `'skip'` only
 
 The on-disk format declares the full `'all' | 'dev' | 'skip'` audience vocabulary so the file format will not need to change when the v2 reclassification feature ships. In the current release, only `'skip'` is supported at runtime; `'all'` and `'dev'` are rejected with an explicit "not yet supported" error.

package/docs/project-releases.md

@@ -19,7 +19,7 @@ When configured, each `release-kit prepare` run additionally:
 
 - Computes commits since the last project tag (`<tagPrefix><version>`), filtered to `paths` (by default, the union of every contributing workspace's paths).
 - Bumps the root `package.json`'s `version` field using the same bump-derivation rules as workspaces (or the `--bump=...` override).
-- Regenerates the root `./CHANGELOG.md` from the structured `ChangelogEntry[]` produced by `git-cliff --context` (scoped to the project's `tagPrefix` and the same `paths`) and any matching editorial overrides.
+- Regenerates the root `./CHANGELOG.md` from the structured `ChangelogEntry[]` built from the project's release history (scoped to the project's `tagPrefix` and the same `paths`) and any matching editorial overrides.
 - Emits `./.meta/changelog.json` (when `changelogJson.enabled`).
 - With `--with-release-notes`, additionally emits `./docs/RELEASE_NOTES.v<version>.md`.
 - Appends the project tag to `tmp/.release-tags` so `release-kit commit` and `release-kit tag` pick it up alongside per-workspace tags.
@@ -42,7 +42,7 @@ interface ProjectConfig {
 
 By default the contributing workspaces are implicit: every non-excluded discovered workspace contributes its `<dir>/**` glob, and the project release considers commits under their union.
 
-Declare `paths` to choose the window yourself. Each entry reaches two matchers: `git log` as a pathspec, and `git-cliff --include-path` as a glob. A declared value **replaces** the workspace union rather than extending it: `paths: ['docs/**']` drops every workspace commit from the project release.
+Declare `paths` to choose the window yourself. Each entry is a git pathspec, which both the bump and the changelog read. A declared value **replaces** the workspace union rather than extending it: `paths: ['docs/**']` drops every workspace commit from the project release.
 
 A repo whose content lives at the root — where no commit matches any `<dir>/**` glob, so the project release would skip every run — declares the whole tree:
 
@@ -54,13 +54,13 @@ const config: ReleaseKitConfig = {
 
 `'**'` is the whole-tree pattern, matching root-level files, dotfiles, and nested paths alike.
 
-Terminate a directory scope with `/**`. The two matchers agree on `'aws/**'` but diverge on a bare `'aws'`, which git reads as the whole subtree and git-cliff matches against nothing; `'.'` is the same trap for the repo root. A release under such an entry finds commits, bumps the version, and writes the tag, while its changelog gains no entry for them — and nothing reports an error.
+A bare directory such as `'aws'` selects its whole subtree, as `'aws/**'` does.
 
 Validation rules:
 
 - The root `package.json` must exist and declare a `version` field. release-kit reports an error at config-load time if either is missing.
 - The `project` block is rejected in single-package mode (the package's own release already covers the whole repo, so a project tier would only duplicate it).
-- `paths`, when declared, must hold at least one non-empty string. An empty array is rejected: it reaches git and git-cliff as no filter at all, which is the inverse of how it reads.
+- `paths`, when declared, must hold at least one non-empty string. An empty array is rejected: it reaches git as no filter at all, which is the inverse of how it reads.
 - Unknown fields inside `project` are rejected.
 
 CLI flag interactions:

package/docs/releasing.md

@@ -14,7 +14,6 @@ Scaffolded files:
 - `.github/workflows/publish.yaml` — workflow that delegates to a reusable publish workflow
 - `.github/workflows/release.yaml` — workflow that delegates to a reusable release workflow
 - `.config/release-kit.config.ts` — starter config with commented-out customization examples (with `--with-config`)
-- `.config/git-cliff.toml` — copied from the bundled template (with `--with-config`)
 
 ## `release-kit prepare`
 
@@ -22,22 +21,28 @@ Run release preparation with automatic workspace discovery.
 
 Workspace names for `--only` match the package directory name (e.g., `arrays`, `release-kit`).
 
-`--bump` and `--force` are orthogonal: `--bump` is purely a level chooser; `--force` is purely a release trigger. Examples:
+`prepare` reads each target's history once and builds the changelog items of its unreleased commits. The bump is the highest level that those items call for, under [`versionPatterns`](configuration.md#versionpatterns), so the bump and the changelog describe the same release: A `feat` entry in a [change-record block](changelogs.md#change-record-blocks) bumps minor under a `docs:` title, and a breaking item bumps major.
+
+- A commit that yields no item bumps nothing: one without a ticket-ID prefix, one of a type excluded from the changelog (such as `fmt`), and one whose change-record entries are all undeclared or excluded.
+- A `BREAKING CHANGE:` footer raises no major bump. Only a subject's `!` and an entry's `breaking: true` mark an item breaking; on a type whose policy forbids `!`, the footer is reported as a [policy violation](work-types.md#policy-enforcement).
+- A target whose commits yield no item is skipped. The prepare report lists the commits that could not be parsed and the change-record diagnostics, skipped targets included.
+
+`--bump` and `--force` are orthogonal in every mode, single-package included: `--bump` is purely a level chooser; `--force` is purely a release trigger. Examples:
 
 ```sh
 # Release every target at its natural bump level (no flags).
 release-kit prepare
 
-# Force a release even when no bump-worthy commits exist; defaults to patch
-# per target, with each target keeping its natural bump if one is derivable.
+# Force a release even when no commit yields a changelog item; defaults to
+# patch per target, with each target keeping its natural bump if it has one.
 release-kit prepare --force
 
 # Force a release at a uniform level across every releasing target.
 release-kit prepare --force --bump=minor
 
-# --bump=X alone is a level chooser, NOT a trigger. If a target has no
-# bump-worthy commits, it skips with a "Pass --force..." reason. If it has
-# bump-worthy commits, the override applies.
+# --bump=X alone is a level chooser, NOT a trigger. If no commit of a target
+# yields a changelog item, it skips with a "Pass --force..." reason. Otherwise
+# the override applies.
 release-kit prepare --bump=minor
 ```
 
@@ -64,7 +69,7 @@ docs/*.v*.md
 
 ### Setting an explicit version with `--set-version`
 
-The `--set-version` flag is a first-class escape hatch for the cases where commit-derived bump logic produces the wrong version — most notably, promoting a pre-1.0 package to 1.0.0. Pre-1.0 packages collapse a `feat!` breaking change to a minor bump (matching semantic-release's `initialMajor: false` and release-please's `bump-minor-pre-major`), so a deliberate promotion to 1.0.0 must be requested explicitly.
+The `--set-version` flag is a first-class escape hatch for the cases where the derived bump produces the wrong version — most notably, promoting a pre-1.0 package to 1.0.0. Pre-1.0 packages collapse a `feat!` breaking change to a minor bump (matching semantic-release's `initialMajor: false` and release-please's `bump-minor-pre-major`), so a deliberate promotion to 1.0.0 must be requested explicitly.
 
 The flag validates that:
 

package/docs/work-types.md

@@ -28,7 +28,11 @@ release-kit bundles a copy of the codeassembly canonical taxonomy in `packages/r
 - **`internal`** — dev-only. `internal`-tier sections appear in dev changelogs but not in public-facing release notes.
 - **`process`** — dev-only. Same audience treatment as `internal`.
 
-Section render order is **tier order (`public` → `internal` → `process`), then row order within tier**. The bundled `cliff.toml.template` encodes this order via hidden `<!-- NN -->` HTML-comment prefixes on each parser's `group` value; tera's `group_by` filter sorts groups lexicographically (now monotonic by row number), and the body template's `striptags` filter erases the prefix from rendered headings.
+Section render order is **tier order (`public` → `internal` → `process`), then row order within tier**. It comes from the declaration order of `work-types.json`: `CANONICAL_SECTION_ORDER` in `buildChangelogEntries.ts` indexes each header by its row, and `transformReleases` sorts a release's sections by that index whatever order the commits arrived in.
+
+## Subject forms
+
+`classifyChangelogCommit` resolves a commit's type through `parseCommitMessage`, so a subject reaches its section under any form that parser accepts: `type:`, `scope|type:`, and the conventional-commit `type(scope):`. The type is matched case-insensitively, so `Feat:` and `FEAT:` resolve like `feat:`. The ticket-ID prefix is still required, and an alias resolves before the section is chosen. A commit whose [change-record block](changelogs.md#change-record-blocks) records entries takes its sections from the entries' types instead of from its subject.
 
 ## `utility` alias
 
@@ -44,11 +48,11 @@ Each work-type carries a `breakingPolicy` value:
 
 ### Policy enforcement
 
-`parseCommitMessage` enforces the `!` policy at release time and treats a violation as a warning. Commits already in the log cannot be rewritten, so a policy-violating commit is parsed using its canonical type with `breaking: false` (the `!` is dropped from the parse) and an `onPolicyViolation` callback fires. Callers (`decideRelease` etc.) can collect these warnings and surface them in the release report. A single legacy `internal!` in a year-old log does not block releases.
+`parseCommitMessage` enforces the `!` policy at release time and treats a violation as a warning. Commits already in the log cannot be rewritten, so a policy-violating commit is parsed using its canonical type with `breaking: false` (the `!` is dropped from the parse) and an `onPolicyViolation` callback fires. `readReleaseHistory` collects these warnings while it builds the items of the unreleased window, and the release report lists them. A single legacy `internal!` in a year-old log does not block releases.
 
-A `BREAKING CHANGE:` body footer on a `forbidden`-policy type triggers the same warning path as the prefix `!` does: A type that cannot be breaking is parsed as non-breaking whichever surface carries the signal.
+A `BREAKING CHANGE:` body footer on a `forbidden`-policy type triggers the same warning path as the prefix `!` does: A type that cannot be breaking is parsed as non-breaking whichever surface carries the signal. The warning is all that a footer triggers; it raises no bump (see [`🚨 **Breaking:**` bullet marker](#-breaking-bullet-marker)).
 
-The release-prepare orchestrators (`releasePrepare`, `releasePrepareMono`, `releasePrepareProject`) apply `DEFAULT_BREAKING_POLICIES` automatically. Violations encountered while parsing each workspace's or project's commit window are collected onto the corresponding result's `policyViolations` field and rendered under the section in the prepare report:
+The release-prepare orchestrators (`releasePrepare`, `releasePrepareMono`, `releasePrepareProject`) apply `DEFAULT_BREAKING_POLICIES` automatically. Violations in the titles and change-record entries of each workspace's or project's unreleased window are collected onto the corresponding result's `policyViolations` field, on a skipped result as on a released one, and rendered under the section in the prepare report:
 
 ```
 arrays
@@ -73,9 +77,9 @@ The marker agrees with the version bump:
 
 - A `forbidden`-policy type carrying `!`, such as `refactor!`, gets no marker, just as its `!` raises no bump; the prepare report lists it as a policy violation. An [editorial override](editorial-overrides.md) that sets `breaking: true` restores the marker for one entry.
 - The configured `breakingPolicies` map, `{}` included, decides which types permit the marker.
-- A commit whose type the parser cannot resolve has no policy, so its `!` prefix alone decides.
+- A commit whose type the parser cannot resolve reaches no changelog at all, so no marker question arises.
 
-A `BREAKING CHANGE:` body footer on its own does **not** retroactively mark a changelog item as breaking, even on a type whose policy permits `!`; the changelog signal is tied to the commit prefix. This avoids surprise breaking-marker appearances for older commits written under earlier conventions.
+A `BREAKING CHANGE:` body footer on its own does **not** retroactively mark a changelog item as breaking, even on a type whose policy permits `!`; the changelog signal is tied to the commit prefix. This avoids surprise breaking-marker appearances for older commits written under earlier conventions. The bump follows the items, so a footer raises no major bump either: A consumer that marks breaking changes with the footer alone gets the bump of the commit's type.
 
 The emoji and label of this marker are sourced from the `markers.breaking` entry in `work-types.json` (see [Section markers](#section-markers)) so consumers that render their own breaking-changes section draw from the same SSOT.
 
@@ -95,13 +99,13 @@ Entries store plain text only — the SSOT is format-agnostic, so consumers appl
 
 ## `fmt`
 
-`fmt:` commits are recognized by `parseCommitMessage` (they contribute to a patch bump) but `fmt` carries `excludedFromChangelog: true`. The bundled `cliff.toml.template` skips `fmt:` commits at the parser level, so they never appear in `CHANGELOG.md`, `changelog.json`, or release notes. The label and emoji are present in `work-types.json` for schema parity with the codeassembly upstream but never render.
+`fmt:` commits are recognized by `parseCommitMessage`, but `fmt` carries `excludedFromChangelog: true`, which `DEFAULT_WORK_TYPES` carries onto its `WorkTypeConfig`. `classifyChangelogCommit` excludes a commit whose type sets the flag, so a `fmt:` commit never appears in `CHANGELOG.md`, `changelog.json`, or release notes. It yields no item, so it raises no bump, and the release report does not list it as unparseable. The label and emoji are present in `work-types.json` for schema parity with the codeassembly upstream but never render.
 
 ## Custom work types
 
-Work types from your config are merged with these defaults by key — your entries override or extend, they don't replace the full set. Release-notes sections are rendered in the declaration order of the merged work-types record, with any unknown titles trailing the known ones.
+Work types from a config are merged with these defaults by key: a consumer entry overrides or extends, it does not replace the full set. `classifyChangelogCommit` reads the merged record, so an added type reaches the changelog under the `header` it declares, and an entry setting `excludedFromChangelog: true` keeps its commits out of the changelog and the bump. Release-notes sections are rendered in the declaration order of the merged work-types record, with any unknown titles trailing the known ones.
 
-The default `devOnlySections` (excluded from public release notes but still written to `CHANGELOG.md`) are derived from the `internal` and `process` tiers (excluding `fmt`). Override via `changelogJson.devOnlySections` in your config; matching is decorator-tolerant, so a bare-name override like `['Internal features']` keeps working against the emoji-prefixed and prefix-decorated default titles.
+The default `devOnlySections` (excluded from public release notes but still written to `CHANGELOG.md`) are derived from the `internal` and `process` tiers (excluding `fmt`). Override via `changelogJson.devOnlySections`; matching is decorator-tolerant, so a bare-name override like `['Internal features']` keeps working against the emoji-prefixed default titles.
 
 ## Maintaining the bundled taxonomy
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/release-kit",
-  "version": "11.0.0",
+  "version": "12.0.0",
   "description": "Version-bumping and changelog-generation toolkit for release workflows",
   "keywords": [
     "changelog",
@@ -43,7 +43,6 @@
     ".readyup/manifest.json",
     "CHANGELOG.md",
     "bin",
-    "cliff.toml.template",
     "dist/*",
     "docs",
     "!docs/*.v*.md",

package/schemas/changelog-overrides.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "changelog-overrides",
+  "description": "Editorial overrides that release-kit applies to generated changelog items. Each key is a lowercase hex commit hash or prefix, which targets every item of the commit, optionally followed by `:<n>`, which targets the item derived from the commit's `n`th change-record entry.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference for editor support."
+    }
+  },
+  "patternProperties": {
+    "^[0-9a-f]+(:[1-9][0-9]*)?$": {
+      "type": "object",
+      "description": "Override for the items that the key targets. At least one field must be set.",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "audience": {
+          "enum": ["all", "dev", "skip"],
+          "description": "`skip` removes the items. `all` and `dev` are reserved and not yet supported."
+        },
+        "description": {
+          "type": "string",
+          "description": "Replaces the item's headline."
+        },
+        "body": {
+          "type": "string",
+          "description": "Replaces the item's body."
+        },
+        "breaking": {
+          "type": "boolean",
+          "description": "Sets whether the item is marked as breaking."
+        }
+      }
+    }
+  }
+}

package/cliff.toml.template

@@ -1,65 +0,0 @@
-# git-cliff configuration
-# Generates changelogs from conventional-ish commit messages.
-#
-# Commit format: [ticket-prefix ]scope|type[!]: description [#PR]
-# Examples:
-#   #19 rdy|feat: Add utility functions for common check patterns (#26)
-#   AFG-42 panel|fix: Fix button layout (#73)
-#   ## feat: Quick utility added during interactive session
-#
-# Only ticketed commits (leading #NN, PROJ-NN, or ##) are included.
-# Unticketed maintenance commits (deps upgrades, tooling tweaks) are skipped.
-# Use ## as a synthetic ticket prefix for ad-hoc commits that belong in the changelog.
-#
-# Section order: each `group` value carries a hidden `<!-- NN -->` HTML-comment
-# prefix encoding the canonical row position. tera's `group_by` filter sorts
-# groups lexicographically by string, and the body template's `striptags`
-# filter erases the comment from the rendered heading. Numbering is per
-# unique group (not per parser entry) — all parsers routing to the same group
-# share the same prefix.
-
-# Markdown rendering is handled in-process by `renderChangelogMarkdown.ts`. cliff is invoked
-# only for `--context` JSON output (see `buildChangelogEntries.ts`), so no `[changelog]` block
-# is needed. The `[git].commit_parsers` section below remains load-bearing for group
-# assignment in the `--context` payload.
-
-[git]
-conventional_commits = false
-filter_unconventional = false
-split_commits = false
-commit_preprocessors = []
-# Require a ticket-ID prefix for inclusion.
-# Supported prefixes: "#123 ", "#123-1 ", "#123.1 ", "TOOL-123 ", "## "
-commit_parsers = [
-  { message = "^release:", skip = true },
-  { message = "^Merge", skip = true },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?feat(!)?:", group = "<!-- 01 -->🎉 Features" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?feature(!)?:", group = "<!-- 01 -->🎉 Features" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?drop(!)?:", group = "<!-- 02 -->🪦 Removed" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?deprecate(!)?:", group = "<!-- 03 -->🗑️ Deprecated" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?fix(!)?:", group = "<!-- 04 -->🐛 Bug fixes" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?bugfix(!)?:", group = "<!-- 04 -->🐛 Bug fixes" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?sec(!)?:", group = "<!-- 05 -->🔒 Security" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?security(!)?:", group = "<!-- 05 -->🔒 Security" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?perf(!)?:", group = "<!-- 06 -->⚡ Performance" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?performance(!)?:", group = "<!-- 06 -->⚡ Performance" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?internal(!)?:", group = "<!-- 07 -->🏗️ Internal features" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?utility(!)?:", group = "<!-- 07 -->🏗️ Internal features" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?refactor(!)?:", group = "<!-- 08 -->♻️ Refactoring" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?tests?(!)?:", group = "<!-- 09 -->🧪 Tests" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?tooling(!)?:", group = "<!-- 10 -->⚙️ Tooling" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?ci(!)?:", group = "<!-- 11 -->👷 CI" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?deps?(!)?:", group = "<!-- 12 -->📦 Dependencies" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?ai(!)?:", group = "<!-- 13 -->🤖 Agentic support" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?docs?(!)?:", group = "<!-- 14 -->📚 Documentation" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?fmt(!)?:", skip = true },
-  # Skip unticketed commits (maintenance, deps, initial scaffolding, etc.)
-  { message = ".*", skip = true },
-]
-protect_breaking_commits = false
-filter_commits = true
-tag_pattern = "v[0-9].*"
-skip_tags = ""
-ignore_tags = ""
-topo_order = false
-sort_commits = "oldest"