@williamthorsen/release-kit 10.9.0 → 12.0.0

package/dist/esm/validateOverridesCommand.js

@@ -2,43 +2,40 @@ import { formatErrorLine, formatStatusLine } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { buildChangelogEntries } from "./buildChangelogEntries.js";
 import { resolveOverridePath, validateAllChangelogOverrides, } from "./changelogOverrides.js";
-import { discoverWorkspaces } from "./discoverWorkspaces.js";
-import { buildTagPattern, getAllTagPrefixes } from "./generateChangelogs.js";
-import { loadConfig, mergeMonorepoConfig, mergeSinglePackageConfig, readRootPackageVersion } from "./loadConfig.js";
-import { validateConfig } from "./validateConfig.js";
+import { describeEmptyWorkspace, discoverWorkspaces } from "./discoverWorkspaces.js";
+import { getAllTagPrefixes } from "./generateChangelogs.js";
+import { mergeMonorepoConfig, mergeSinglePackageConfig, readRootPackageVersion } from "./loadConfig.js";
+import { loadValidatedConfig } from "./loadValidatedConfig.js";
 const SYNTHETIC_VALIDATE_TAG = 'validate-only';
-export async function validateOverridesCommand(styles, dependencies = {}) {
+export async function validateOverridesCommand(styles, configPath, dependencies = {}) {
     const discover = dependencies.discoverWorkspaces ?? discoverWorkspaces;
-    const load = dependencies.loadConfig ?? loadConfig;
+    const load = dependencies.loadValidatedConfig ?? (() => loadValidatedConfig(configPath));
     const buildEntries = dependencies.buildEntries ?? defaultBuildEntries;
     const validate = dependencies.validate ?? validateAllChangelogOverrides;
-    let rawConfig;
-    try {
-        rawConfig = await load();
-    }
-    catch (error) {
-        return { exitCode: 2, message: formatErrorLine(`Failed to load config: ${describeError(error)}`) };
-    }
-    let userConfig;
-    try {
-        userConfig = validateLoadedConfig(rawConfig);
-    }
-    catch (error) {
-        return { exitCode: 2, message: describeError(error) };
+    const configResult = await load();
+    if (configResult.status === 'invalid') {
+        return { exitCode: 2, message: formatConfigProblem(configResult.problem) };
     }
-    let discoveredPaths;
+    const userConfig = configResult.status === 'ok' ? configResult.config : undefined;
+    let workspace;
     try {
-        discoveredPaths = await discover();
+        workspace = discover();
     }
     catch (error) {
         return { exitCode: 2, message: formatErrorLine(`Failed to discover workspaces: ${describeError(error)}`) };
     }
+    if (workspace.kind === 'empty') {
+        return {
+            exitCode: 2,
+            message: formatErrorLine(`No workspace package to validate. ${describeEmptyWorkspace(workspace)}`),
+        };
+    }
     let inputs;
     try {
         inputs =
-            discoveredPaths === undefined
+            workspace.kind === 'single-package'
                 ? buildSinglePackageInputs(userConfig, buildEntries)
-                : buildMonorepoInputs(discoveredPaths, userConfig, buildEntries);
+                : buildMonorepoInputs(workspace.packageDirs, userConfig, buildEntries);
     }
     catch (error) {
         return { exitCode: 2, message: formatErrorLine(`Failed to resolve overrides scope: ${describeError(error)}`) };
@@ -71,54 +68,42 @@ function formatSummaryLine(errorCount, warningCount) {
 function pluralize(count, noun) {
     return count === 1 ? `${count} ${noun}` : `${count} ${noun}s`;
 }
-function defaultBuildEntries(config, tagPattern, includePaths) {
-    const options = {};
-    if (tagPattern !== undefined) {
-        options.tagPattern = tagPattern;
-    }
-    if (includePaths !== undefined) {
-        options.includePaths = includePaths;
-    }
-    return buildChangelogEntries(config, SYNTHETIC_VALIDATE_TAG, options);
+function defaultBuildEntries(config, options) {
+    return buildChangelogEntries(config, SYNTHETIC_VALIDATE_TAG, options).entries;
 }
-function flattenEntriesToHashes(entries) {
-    const hashes = [];
+function flattenEntriesToItems(entries) {
+    const items = [];
     for (const entry of entries) {
         for (const section of entry.sections) {
-            for (const item of section.items) {
-                if (item.hash !== undefined) {
-                    hashes.push(item.hash);
-                }
+            for (const { hash, entry: position } of section.items) {
+                if (hash === undefined)
+                    continue;
+                items.push(position === undefined ? { hash } : { hash, entry: position });
             }
         }
     }
-    return hashes;
+    return items;
 }
-function validateLoadedConfig(rawConfig) {
-    if (rawConfig === undefined) {
-        return undefined;
-    }
-    const { config, errors } = validateConfig(rawConfig);
-    if (errors.length > 0) {
-        throw new Error(`Invalid config:\n  - ${errors.join('\n  - ')}`);
-    }
-    return config;
+function formatConfigProblem(problem) {
+    return problem.kind === 'load'
+        ? formatErrorLine(`Failed to load config: ${problem.message}`)
+        : `Invalid config:\n  - ${problem.errors.join('\n  - ')}`;
 }
 function buildSinglePackageInputs(userConfig, buildEntries) {
     const config = mergeSinglePackageConfig(userConfig);
-    const hashes = flattenEntriesToHashes(buildEntries(config));
+    const items = flattenEntriesToItems(buildEntries(config, { tagPrefixes: [config.tagPrefix] }));
     return {
-        project: { filePath: resolveOverridePath('.'), hashes },
+        project: { filePath: resolveOverridePath('.'), items },
     };
 }
 function buildMonorepoInputs(discoveredPaths, userConfig, buildEntries) {
     const rootPackage = readRootPackageVersion();
     const config = mergeMonorepoConfig(discoveredPaths, userConfig, rootPackage);
     const workspaces = config.workspaces.map((workspace) => {
-        const tagPattern = buildTagPattern(getAllTagPrefixes(workspace));
+        const options = { tagPrefixes: getAllTagPrefixes(workspace), paths: workspace.paths };
         return {
             filePath: resolveOverridePath(workspace.workspacePath),
-            hashes: flattenEntriesToHashes(buildEntries(config, tagPattern, workspace.paths)),
+            items: flattenEntriesToItems(buildEntries(config, options)),
         };
     });
     const project = config.project;
@@ -126,8 +111,8 @@ function buildMonorepoInputs(discoveredPaths, userConfig, buildEntries) {
         filePath: resolveOverridePath('.'),
     };
     if (project !== undefined) {
-        const projectTagPattern = buildTagPattern([project.tagPrefix]);
-        projectScope.hashes = flattenEntriesToHashes(buildEntries(config, projectTagPattern, project.paths));
+        const options = { tagPrefixes: [project.tagPrefix], paths: project.paths };
+        projectScope.items = flattenEntriesToItems(buildEntries(config, options));
     }
     return { project: projectScope, workspaces };
 }

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

@@ -4,11 +4,20 @@ The fields of `.config/release-kit.config.ts`, how a workspace declares its prio
 
 A minimal config file is in the [README](../README.md#configuration).
 
+## Config file location
+
+release-kit reads `.config/release-kit.config.ts`, resolved against the working directory. A run reads a different file when the subcommand is given `--config <path>`, which is also resolved against the working directory.
+
+The flag is accepted by every subcommand that reads a config: `prepare`, `publish`, `create-github-release`, `show-tag-prefixes`, `overrides validate`, `sync-labels init`, and `sync-labels generate`. `commit`, `tag`, `push`, and `sync-labels sync` read no config and reject it.
+
+The two paths differ in what an absent file means. An absent default path means the repo declares no config, and the run proceeds on discovered defaults. An absent `--config` path fails the command with an error naming the resolved path, because a caller who names a file expects that file to be read. A file that exists and fails validation is an error on both paths alike, and so is one that exists and fails to load.
+
+`--config` names a file to read, never a write target. `release-kit init --with-config` scaffolds to `.config/release-kit.config.ts` and takes no `--config`, and `sync-labels init` writes its seeded `repoLabels` block to that same path.
+
 ## `ReleaseKitConfig` reference
 
 | 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                                                                                                                                        |
@@ -79,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.
 
@@ -89,11 +98,13 @@ Print a per-workspace table of derived tag prefixes, tag counts, and declared le
 
 Exits `0` when every workspace derives a prefix and there are no cross-workspace collisions; exits `1` on any derivation failure or collision. Undeclared candidates do not affect the exit code — they surface as a warning via the `legacy tag prefixes are declared` readyup check.
 
+A config file that exists and either fails to load or fails schema validation reports the failure on stderr and exits `1`, printing no preview, because a config that cannot be read leaves the declared-versus-undeclared verdict wrong in the one dimension the command exists to report on. That holds on the default path and under `--config`, and in single-package mode as well as monorepo mode. An absent default config is a supported state and still previews against derived defaults.
+
 In single-package mode, prints a single row with `workspacePath = .` and `derivedPrefix = v`; legacy entries and undeclared-candidate scanning are not applicable.
 
 ## `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/labels.md

@@ -8,6 +8,8 @@ Manage GitHub label definitions via the `repoLabels` block of `.config/release-k
 
 `init` scaffolds the `.github/workflows/sync-labels.yaml` caller workflow and seeds a `repoLabels` block with scope labels discovered from workspaces and declared `retiredPackages`. When `.config/release-kit.config.ts` does not exist, `init` writes it; when it does, `init` prints the block for manual paste — a hand-authored config is never rewritten. `generate` resolves the block and writes `.github/labels.yaml`; with `--check` it regenerates in memory and exits non-zero if the committed file is stale or missing, writing nothing. `sync` triggers the workflow remotely — it requires the `gh` CLI and an existing workflow file.
 
+`init` and `generate` accept `--config <path>` to read a config elsewhere; `sync` reads none and rejects the flag. Under `--config`, `init` reads the named file and prints the block for manual paste, and fails when that file does not exist rather than scaffolding one, so its write target stays `.config/release-kit.config.ts`. See [Config file location](configuration.md#config-file-location).
+
 Every `sync-labels` subcommand refuses to run while the retired `.config/sync-labels.config.ts` is present, so custom labels cannot be silently dropped mid-migration, and the refusal names what to move and where.
 
 ### Label configuration

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: