@williamthorsen/release-kit 11.0.0 → 13.0.0

package/dist/esm/validateConfig.js

@@ -30,8 +30,12 @@ function preprocessDeprecatedKeys(raw) {
         return { cleaned: raw, deprecationErrors: [] };
     const errors = [];
     const cleaned = { ...raw };
+    if (Object.hasOwn(cleaned, 'cliffConfigPath')) {
+        errors.push('cliffConfigPath is no longer supported. release-kit reads changelog history from git directly and does not use any external config file. Remove this field from the config, and delete the file that it names.');
+        delete cleaned['cliffConfigPath'];
+    }
     if (isRecord(cleaned['releaseNotes']) && Object.hasOwn(cleaned['releaseNotes'], 'shouldCreateGithubRelease')) {
-        errors.push('releaseNotes.shouldCreateGithubRelease is no longer supported. Adoption is now signaled by installing the create-github-release workflow, which `release-kit init` scaffolds. Remove this field from your config.');
+        errors.push('releaseNotes.shouldCreateGithubRelease is no longer supported. Adoption is now signaled by installing the create-github-release workflow, which `release-kit init` scaffolds. Remove this field from the config.');
         const releaseNotesCopy = { ...cleaned['releaseNotes'] };
         delete releaseNotesCopy['shouldCreateGithubRelease'];
         cleaned['releaseNotes'] = releaseNotesCopy;

package/dist/esm/validateOnlyExcludesStrandedDependents.d.ts

@@ -4,32 +4,34 @@ import type { WorkspaceConfig } from './types.js';
 export interface CommitsProbeResult {
     /** Whether the workspace has any commits since its last tag (excluding `release:` commits). */
     has: boolean;
-    /** The baseline tag the commits were measured from; `undefined` when no prior tag exists. */
+    /**
+     * The baseline tag from which the commits were measured; `undefined` when the workspace does not have a prior tag.
+     */
     tag: string | undefined;
 }
 /** A single excluded workspace whose changes would be stranded by the `--only` invocation. */
 export interface StrandedDependentViolation {
     /** The excluded workspace's `dir`. */
     dir: string;
-    /** The released workspace's `dir` whose release would have triggered D's republication. */
+    /** The `dir` of the released (or anticipated-release) dependency whose release republishes this workspace. */
     downstreamOf: string;
-    /** The baseline tag from which D's commits were counted; `undefined` if no prior tag. */
+    /**
+     * The baseline tag from which this workspace's commits were counted; `undefined` if the workspace does not have a
+     * prior tag.
+     */
     tag: string | undefined;
 }
 /** Probe callback that returns whether a workspace has commits since its last tag. */
 type CommitsProbe = (workspace: WorkspaceConfig) => CommitsProbeResult;
 /**
- * Detect `--only` invocations that would silently strand changes in excluded internal dependents.
+ * Detects `--only` invocations that would silently strand changes in excluded internal dependents.
  *
- * Runs in two steps. First, compute the released `--only` set R via fixpoint: start with `--only`
- * workspaces that have own commits, then iteratively add `--only` workspaces whose `workspace:`
- * deps land in R (those will release via propagation). Second, BFS through the reverse-dep graph
- * starting from R, recording each excluded workspace with own commits as a violation. The walk
- * continues *through* such workspaces (anticipating that the user will add them to `--only`,
- * surfacing deeper footguns in one pass), but stops at excluded workspaces with no commits
- * (case-3 barriers — they don't republish, so their downstream dependents aren't affected by R).
+ * First computes R, the `--only` workspaces that will release, then walks the reverse-dependency graph breadth-first
+ * from R and records each excluded workspace with its own commits as a violation. The walk continues through a
+ * violation, as though the user had added it to `--only`, which reports deeper violations in the same pass. It stops
+ * at an excluded workspace without commits, which does not republish, so its dependents are unaffected by R.
  *
- * Returns `undefined` when no violations are found, or a sorted list otherwise.
+ * Returns `undefined` when the walk does not find any violation, or the violations sorted by `dir`.
  */
 export declare function validateOnlyExcludesStrandedDependents(workspaces: readonly WorkspaceConfig[], only: readonly string[], graph: DependencyGraph, hasCommits: CommitsProbe): StrandedDependentViolation[] | undefined;
 export {};

package/dist/esm/validateOverridesCommand.d.ts

@@ -1,16 +1,18 @@
 import { type OutputStyle, type StreamStyles } from '@williamthorsen/nmr-core';
+import { type ReleaseHistoryConfig } from './buildChangelogEntries.js';
 import { type ValidateAllChangelogOverridesInputs, type ValidateAllChangelogOverridesResult } from './changelogOverrides.js';
 import { type WorkspaceDiscovery } from './discoverWorkspaces.js';
+import { type GenerateChangelogOptions } from './generateChangelogs.js';
 import { type LoadValidatedConfigResult } from './loadValidatedConfig.js';
-import type { ChangelogEntry, ReleaseConfig } from './types.js';
+import type { ChangelogEntry } from './types.js';
 /**
- * Result of {@link validateOverridesCommand}: tiered exit code paired with a human-readable
- * message, which keeps the CLI dispatch layer thin.
+ * Result of {@link validateOverridesCommand}: a tiered exit code paired with a human-readable message.
  *
  * Exit codes:
- * - `0` — clean: no errors, no warnings.
- * - `1` — only stale-key warnings.
- * - `2` — schema/parse or ambiguous-prefix errors (errors dominate when both classes exist).
+ * - `0`: clean, with no errors and no warnings.
+ * - `1`: only stale-key warnings.
+ * - `2`: schema or parse errors, or keys that fail to match (an ambiguous prefix, overlapping keys, or a bare key
+ *   that sets fields on several items). Errors take precedence when both classes exist.
  */
 export interface ValidateOverridesCommandResult {
     exitCode: 0 | 1 | 2;
@@ -21,30 +23,26 @@ export interface ValidateOverridesCommandDependencies {
     discoverWorkspaces?: () => WorkspaceDiscovery;
     loadValidatedConfig?: () => Promise<LoadValidatedConfigResult>;
     /**
-     * Build changelog entries for a scope. Defaults to `buildChangelogEntries`, the same path
-     * `release-kit prepare` uses — anchoring `validate`'s hash universe to `prepare`'s by
-     * construction. `tagPattern` and `includePaths` are passed straight through to git-cliff.
+     * Builds changelog entries for a scope. Defaults to `buildChangelogEntries`, which `release-kit prepare` also
+     * uses, so that `validate` sees the same items as `prepare`.
      */
-    buildEntries?: (config: Pick<ReleaseConfig, 'cliffConfigPath' | 'changelogJson'>, tagPattern?: string, includePaths?: string[]) => ChangelogEntry[];
-    /** Pluggable validator (default: the production library function). Tests use this to drive specific result shapes through the formatter. */
+    buildEntries?: (config: ReleaseHistoryConfig, options: GenerateChangelogOptions) => ChangelogEntry[];
+    /** Validator; defaults to `validateAllChangelogOverrides`. Tests use it to feed specific results to the formatter. */
     validate?: (inputs: ValidateAllChangelogOverridesInputs) => ValidateAllChangelogOverridesResult;
 }
 /**
- * Validate every changelog override file across the project and per-workspace scopes, and
- * return a tiered exit-code-plus-message result. Performs workspace discovery, config load,
- * and per-scope hash collection, then delegates the actual validation to
+ * Validates every changelog override file across the project and per-workspace scopes, and
+ * returns a tiered exit-code-plus-message result. Performs workspace discovery, config load,
+ * and per-scope item collection, then delegates the actual validation to
  * {@link validateAllChangelogOverrides}.
  *
- * Single-package and monorepo modes are handled uniformly: single-package collapses to one
- * project scope; monorepo expands to a project scope plus one scope per workspace. A workspace declaring
- * patterns that resolve to no package is neither, and exits `2`.
+ * Single-package and monorepo modes are handled uniformly: Single-package collapses to one
+ * project scope; monorepo expands to a project scope plus one scope per workspace. A workspace that doesn't resolve
+ * to any package is neither, and the command returns exit code `2` for it.
  *
  * `configPath` names the config file to read, relative to the working directory; it defaults to
  * `CONFIG_FILE_PATH`.
  */
 export declare function validateOverridesCommand(styles: StreamStyles, configPath?: string, dependencies?: ValidateOverridesCommandDependencies): Promise<ValidateOverridesCommandResult>;
-/**
- * Pure formatter — take an aggregated validation result, return the tiered exit code and a
- * rendered message. Exported for unit testing without going through the full discovery path.
- */
+/** Returns the tiered exit code and rendered message for an aggregated validation result. */
 export declare function formatValidateOverridesResult(result: ValidateAllChangelogOverridesResult, style: OutputStyle): ValidateOverridesCommandResult;

package/dist/esm/validateOverridesCommand.js

@@ -3,7 +3,7 @@ import { describeError } from '@williamthorsen/toolbelt.errors';
 import { buildChangelogEntries } from "./buildChangelogEntries.js";
 import { resolveOverridePath, validateAllChangelogOverrides, } from "./changelogOverrides.js";
 import { describeEmptyWorkspace, discoverWorkspaces } from "./discoverWorkspaces.js";
-import { buildTagPattern, getAllTagPrefixes } from "./generateChangelogs.js";
+import { getAllTagPrefixes } from "./generateChangelogs.js";
 import { mergeMonorepoConfig, mergeSinglePackageConfig, readRootPackageVersion } from "./loadConfig.js";
 import { loadValidatedConfig } from "./loadValidatedConfig.js";
 const SYNTHETIC_VALIDATE_TAG = 'validate-only';
@@ -68,28 +68,21 @@ 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 formatConfigProblem(problem) {
     return problem.kind === 'load'
@@ -98,19 +91,19 @@ function formatConfigProblem(problem) {
 }
 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, workspaceDir: workspace.dir };
         return {
             filePath: resolveOverridePath(workspace.workspacePath),
-            hashes: flattenEntriesToHashes(buildEntries(config, tagPattern, workspace.paths)),
+            items: flattenEntriesToItems(buildEntries(config, options)),
         };
     });
     const project = config.project;
@@ -118,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/api.md

@@ -4,7 +4,7 @@ How to build a release config by hand with `deriveWorkspaceConfig()`, the script
 
 ## Using `deriveWorkspaceConfig()` for manual configuration
 
-If you need to build a `MonorepoReleaseConfig` manually (e.g., for the legacy script-based approach), the exported `deriveWorkspaceConfig()` helper creates a `WorkspaceConfig` from a workspace-relative path. It reads the workspace's `package.json` to derive the tag prefix from the package name:
+For a `MonorepoReleaseConfig` built manually (e.g., for the legacy script-based approach), the exported `deriveWorkspaceConfig()` helper creates a `WorkspaceConfig` from a workspace-relative path. It reads the workspace's `package.json` to derive the tag prefix from the package name:
 
 ```typescript
 import { deriveWorkspaceConfig } from '@williamthorsen/release-kit';
@@ -22,9 +22,9 @@ deriveWorkspaceConfig('packages/arrays');
 // }
 ```
 
-`dir` is the basename of the workspace path and is the stable internal identifier used by `--only`, `WorkspaceOverride.dir`, and the dependency graph. `tagPrefix` is derived from the unscoped `package.json` `name` — any leading `@scope/` is stripped — so tags reflect the package identity rather than the directory layout. For example, a workspace at `packages/core` with `"name": "@williamthorsen/nmr-core"` produces `tagPrefix: 'nmr-core-v'`, yielding tags like `nmr-core-v1.3.0`.
+`dir` is the basename of the workspace path and is the stable internal identifier used by `--only`, `WorkspaceOverride.dir`, and the dependency graph. `tagPrefix` is derived from the unscoped `package.json` `name` (with any leading `@scope/` stripped), so tags reflect the package identity rather than the directory layout. For example, a workspace at `packages/core` with `"name": "@williamthorsen/nmr-core"` produces `tagPrefix: 'nmr-core-v'`, yielding tags like `nmr-core-v1.3.0`.
 
-The workspace's `package.json` must declare a non-empty `name` field; `deriveWorkspaceConfig()` throws otherwise. If two workspaces produce the same `tagPrefix` (because their unscoped names collide), `mergeMonorepoConfig()` throws and names the colliding workspaces so you can rename one.
+The workspace's `package.json` must declare a non-empty `name` field; `deriveWorkspaceConfig()` throws otherwise. If two workspaces produce the same `tagPrefix` (because their unscoped names collide), `mergeMonorepoConfig()` throws and names the colliding workspaces so that the developer can rename one.
 
 ## Legacy script-based approach
 
@@ -49,7 +49,7 @@ import { config } from './release.config.ts';
 runReleasePrepare(config);
 ```
 
-The key difference: the script-based approach requires manually listing every workspace, while the CLI auto-discovers them from `pnpm-workspace.yaml`.
+The key difference: The script-based approach requires manually listing every workspace, while the CLI auto-discovers them from `pnpm-workspace.yaml`.
 
 ## `resolveReleaseTags` takes workspaces; `WorkspaceConfig` requires `workspacePath`
 
@@ -58,7 +58,7 @@ Tag resolution is now driven by workspace records rather than a caller-supplied
 - `resolveReleaseTags` signature changed from `(workspaceMap?: Map<string, string>)` to `(workspaces?: readonly WorkspaceConfig[])`.
 - `WorkspaceConfig` gained a required `workspacePath: string` field.
 
-Replace direct `Map`-based calls with `deriveWorkspaceConfig()`, which now populates `workspacePath` for you:
+Replace direct `Map`-based calls with `deriveWorkspaceConfig()`, which now populates `workspacePath`:
 
 ```diff
 -import { resolveReleaseTags } from '@williamthorsen/release-kit';
@@ -70,4 +70,4 @@ Replace direct `Map`-based calls with `deriveWorkspaceConfig()`, which now popul
 +resolveReleaseTags([deriveWorkspaceConfig('packages/core')]);
 ```
 
-If you construct `WorkspaceConfig` objects directly, add `workspacePath` alongside the other required fields.
+When constructing `WorkspaceConfig` objects directly, add `workspacePath` alongside the other required fields.

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 a published tarball includes, what each `.meta/changelog.json` item contains, which commits appear in a changelog, how a merge commit's change-record block becomes items, and how release notes are written into 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.
+npm doesn't include either `CHANGELOG.md` or `.meta/changelog.json` in a published tarball on its own. npm stopped including `CHANGELOG` automatically in npm 7, so a package that declares a `files` field publishes a changelog only when 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` has 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` when the commit subject had 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:`. When one is present, `migration` contains that paragraph with the label stripped. An item derived from a change-record entry takes `migration` from the entry instead, and doesn't have a `body`.
+
+A title-derived item looks like this:
 
 ```jsonc
 {
@@ -32,32 +35,91 @@ A commit body states a migration step as a paragraph opening with the literal la
 
 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.
+- **It is independent of `breaking`.** A `deprecate` cannot have `!` 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 that an override file can set (see [File shape](editorial-overrides.md#file-shape)). On a title-derived item, overriding `body` changes the migration text: release-kit re-derives `migration` from whatever `body` an override installs, and clears it when that body doesn't contain a labeled paragraph. 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
+## Which commits appear in 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 appears in 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 appear in a changelog, whether or not they contain a block. A commit that fails a check doesn't yield an item or raise a bump, so a window without an item doesn't call for a release. A release forced by `--force` or `--set-version` whose window doesn't yield an item records a "Forced version bump." entry under Notes for its version, whether or not the window has commits. Because history does not yield that entry again, `release-kit prepare` keeps it by merging each release's entries with the `changelog.json` on disk. 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.
+
+### Existing `CHANGELOG.md` sections
+
+`prepare` also reads the `CHANGELOG.md` that it regenerates, so a version recorded only there, such as history written by hand before release-kit was adopted, survives. The first SemVer token in a `##` heading names the section's version: `## 1.2.0`, `## v1.2.0`, and `## [1.2.0] - 2024-01-01` all name 1.2.0, and so does `## Upgrading from 1.2.0`.
+
+- **A version that neither the release windows nor `changelog.json` contain** keeps its section verbatim, placed among the rendered sections in version order.
+- **A version that either contains** is rendered from its entries, and its old text is discarded.
+- **A section whose heading doesn't name a version**, such as `## Unreleased`, is dropped.
+
+The header above the first section and the footer comment are regenerated. The prepare report lists the versions kept for each changelog and warns about each section dropped. Kept sections never enter `changelog.json`.
+
+### Routing to workspaces
+
+A workspace's window contains every commit that touches the workspace's paths. An item derived from a title is routed to every workspace whose window contains its commit. An item derived from a change-record entry is routed to a workspace in that window only when the entry's `scopes` route it there:
+
+- **A scope that names the workspace's `dir`** routes the item to that workspace. release-kit resolves each scope through [`scopeAliases`](configuration.md) before it compares the scope with the `dir`.
+- **`*`, or an empty or absent `scopes`,** routes the item to every workspace in the window.
+- **`root`** doesn't name a workspace, so it routes the item nowhere and is not reported. A workspace whose `dir` is `root` is the exception: `root` then names that workspace.
+
+A scope narrows the window and never widens it: A scope that names a workspace whose window does not contain the commit doesn't route the item to any workspace, and `prepare` reports it (see [Reported diagnostics](#reported-diagnostics)). The project changelog and a single-package repo take every entry, whatever its scopes.
+
+A workspace's bump reads the items routed to it, so a breaking entry scoped to one workspace does not raise a major bump in another that the same commit touched. A workspace whose window has commits but lacks a routed item doesn't call for a release.
+
+Each `prepare` rebuilds a workspace's released windows with the same routing. When an earlier release recorded an item under a workspace that the item's scopes do not name, the rebuild removes the item from that workspace's past section. A path window does not follow a renamed directory, and legacy identities do not rename scopes: An entry scoped to a workspace's old directory name is routed to the workspace only through a `scopeAliases` entry from the old name to the new one, and until one exists, `prepare` reports the scope for each such commit in the unreleased window.
+
+## 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. They decide which workspaces receive the entry's item; see [Routing to workspaces](#routing-to-workspaces). |
+| `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 routed to the workspace being read yields one item, whether or not the commit subject has 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. The item doesn't have a `body`.
+- **`hash`** and **`entry`**: The commit's hash, and the entry's 1-based position among all the block's entries, including those that don't yield an item.
+
+An entry whose type is excluded from the changelog doesn't yield an 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 [Which commits appear in a changelog](#which-commits-appear-in-a-changelog) describes, when it doesn't have a 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 aren't in any earlier release:
 
-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 doesn't yield an 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.
+- **An entry scope that doesn't name a workspace in its commit's window**, with the commit's hash, the entry's position, and the scope as the entry declares it. release-kit reports it under every workspace whose window contains the commit. A scope that names nothing, or a workspace whose window does not contain the commit, is reported; `*`, `root`, and a scope that names a workspace in the window are not. Under `--only`, a scope that names a configured workspace left out of the run is not reported either. A workspace excluded with `shouldExclude: true` is not a configured workspace, so a scope that names one is reported.
 
-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 includes these as `malformedBlocks`, `undeclaredEntryTypes`, `policyViolations` entries whose `surface` is `'entry'`, and `unroutedEntryScopes`, whether the target releases or is skipped. Because a block whose entries are all undeclared or excluded doesn't yield an item, the commit doesn't raise a bump.
 
 ## Release-notes injection
 
@@ -67,4 +129,4 @@ With `releaseNotes.shouldInjectIntoReadme` set to `true`, `release-kit publish`
 <!-- section:release-notes --><!-- /section:release-notes -->
 ```
 
-A README without the marker pair receives the notes at its top, above its title, and release-kit's readyup kit reports a README that lacks the markers. Injection is skipped with a warning when `changelogJson.enabled` is `false`, when the version has no entry, or when the entry has no all-audience content. `release-kit prepare --with-release-notes` writes the same injected README as a [preview](releasing.md#previewing-release-notes-with---with-release-notes).
+A README without the marker pair receives the notes at its top, above its title, and release-kit's readyup kit reports a README that lacks the markers. Injection is skipped with a warning when `changelogJson.enabled` is `false`, when the version doesn't have an entry, or when the entry doesn't have any all-audience content. `release-kit prepare --with-release-notes` writes the same injected README as a [preview](releasing.md#previewing-release-notes-with---with-release-notes).

package/docs/configuration.md

@@ -6,30 +6,29 @@ 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.
+release-kit reads `.config/release-kit.config.ts`, resolved against the repo root, which release-kit locates from the directory from which it was invoked. A run reads a different file when the subcommand is given `--config <path>`, which is resolved against the invocation directory rather than the root, so that a relative path means what it means in the caller's shell.
 
-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 flag is accepted by every subcommand that reads a config: `prepare`, `push`, `publish`, `create-github-release`, `show-tag-prefixes`, `overrides validate`, `sync-labels init`, and `sync-labels generate`. `commit`, `tag`, and `sync-labels sync` don't read a config, and they reject the flag.
 
-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.
+The two paths differ in what an absent file means. An absent default path means that the repo doesn't declare a 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.
+`--config` names a file to read, never a write target. `release-kit init --with-config` scaffolds to `.config/release-kit.config.ts` and doesn't take `--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                                                                                                                                        |
-| `scopeAliases`     | `Record<string, string>`                                  | Maps shorthand scope names to canonical names in commits                                                                                                                                      |
-| `workTypes`        | `Record<string, WorkTypeConfig>`                          | Work type definitions, merged with defaults by key                                                                                                                                            |
-| `breakingPolicies` | `Record<string, 'forbidden' \| 'optional' \| 'required'>` | Per-type `!`-policy lookup. Defaults to `DEFAULT_BREAKING_POLICIES`. Replaces the default entirely when provided. Set to `{}` to disable enforcement                                          |
-| `retiredPackages`  | `RetiredPackage[]`                                        | Packages that once lived in this repo but have been extracted or removed; suppresses undeclared-tag-prefix warnings                                                                           |
-| `project`          | `ProjectConfig`                                           | Opt-in project-level release block. Declaring `project: {}` (even empty) enables a project-release stage in `prepare`                                                                         |
-| `repoLabels`       | `RepoLabelsConfig`                                        | Declares the repository's label registry for `sync-labels`; see [Label configuration](labels.md#label-configuration)                                                                          |
-| `changelogJson`    | `ChangelogJsonConfig`                                     | Controls `.meta/changelog.json`: `enabled` (default `true`), `outputPath` (default `'.meta/changelog.json'`), and `devOnlySections`; see [Custom work types](work-types.md#custom-work-types) |
-| `releaseNotes`     | `ReleaseNotesConfig`                                      | `shouldInjectIntoReadme` (default `false`) injects release notes into each package's README while it publishes; see [Release-notes injection](changelogs.md#release-notes-injection)          |
+| Field              | Type                                        | Description                                                                                                                                                                                                                                               |
+| ------------------ | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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                                                                                                                                                                                                    |
+| `scopeAliases`     | `Record<string, string>`                    | Maps shorthand scope names to canonical names in commit titles and in change-record entry `scopes`, which [route items to workspaces](changelogs.md#routing-to-workspaces). A renamed workspace directory needs an entry from its old name to its new one |
+| `workTypes`        | `Record<string, WorkTypeConfig>`            | Work type definitions, merged with defaults by key                                                                                                                                                                                                        |
+| `breakingPolicies` | `Record<string, 'forbidden' \| 'optional'>` | Per-type `!`-policy lookup. Defaults to `DEFAULT_BREAKING_POLICIES`. Replaces the default entirely when provided. Set to `{}` to disable enforcement                                                                                                      |
+| `retiredPackages`  | `RetiredPackage[]`                          | Packages that once lived in this repo but have been extracted or removed; suppresses undeclared-tag-prefix warnings                                                                                                                                       |
+| `project`          | `ProjectConfig`                             | Opt-in project-level release block. Declaring `project: {}` (even empty) enables a project-release stage in `prepare`                                                                                                                                     |
+| `repoLabels`       | `RepoLabelsConfig`                          | Declares the repository's label registry for `sync-labels`; see [Label configuration](labels.md#label-configuration)                                                                                                                                      |
+| `changelogJson`    | `ChangelogJsonConfig`                       | Controls `.meta/changelog.json`: `enabled` (default `true`), `outputPath` (default `'.meta/changelog.json'`), and `devOnlySections`; see [Custom work types](work-types.md#custom-work-types)                                                             |
+| `releaseNotes`     | `ReleaseNotesConfig`                        | `shouldInjectIntoReadme` (default `false`) injects release notes into each package's README while it publishes; see [Release-notes injection](changelogs.md#release-notes-injection)                                                                      |
 
 All fields are optional.
 
@@ -48,7 +47,9 @@ interface LegacyIdentity {
 }
 ```
 
-`legacyIdentities` captures prior identities of a workspace as complete `(name, tagPrefix)` snapshots. The union of the current `tagPrefix` and each identity's `tagPrefix` is consulted when release-kit searches for the most recent baseline tag and when generating changelogs. Use it when a workspace's historical tags were published under a different npm name, a different tag prefix, or both — typically across a package rename. Both fields are required per identity: each entry must be a complete historical snapshot that stays valid regardless of subsequent renames. Run `release-kit show-tag-prefixes` to detect undeclared candidates and produce a paste-ready config snippet. Listing the current identity (full `(name, tagPrefix)` match) is rejected as a no-op duplicate; an identity whose `tagPrefix` matches the current but whose `name` differs is valid and documents a prior rename that reused the same tag shape. If the workspace no longer exists in this repo at all (the package was extracted or removed), use [`retiredPackages`](#retiredpackage) instead.
+`prepare` never versions or tags an excluded workspace. A tag of one found on HEAD anyway, made by hand or before the exclusion, is skipped with a warning by `push`, `publish`, and `create-github-release`.
+
+`legacyIdentities` captures prior identities of a workspace as complete `(name, tagPrefix)` snapshots. The union of the current `tagPrefix` and each identity's `tagPrefix` is consulted when release-kit searches for the most recent baseline tag and when generating changelogs. Use it when a workspace's historical tags were published under a different npm name, a different tag prefix, or both, typically across a package rename. Both fields are required per identity: Each entry must be a complete historical snapshot that stays valid regardless of subsequent renames. Run `release-kit show-tag-prefixes` to detect undeclared candidates and produce a paste-ready config snippet. Listing the current identity (full `(name, tagPrefix)` match) is rejected as a no-op duplicate; an identity whose `tagPrefix` matches the current but whose `name` differs is valid and documents a prior rename that reused the same tag shape. If the workspace no longer exists in this repo at all (the package was extracted or removed), use [`retiredPackages`](#retiredpackage) instead.
 
 ## `RetiredPackage`
 
@@ -60,9 +61,9 @@ interface RetiredPackage {
 }
 ```
 
-`retiredPackages` is the repo-level complement to `legacyIdentities`. Use `legacyIdentities` when the workspace still exists in this repo under a new identity; use `retiredPackages` when no workspace for this package exists in this repo anymore — the package was extracted to another repo or removed outright. Retired entries are inert: release-kit never consults them for baseline lookup or changelog attribution. Their declared `tagPrefix` values are recognized as historical, so `show-tag-prefixes` stops flagging them under "Undeclared tag prefixes."
+`retiredPackages` is the repo-level complement to `legacyIdentities`. Use `legacyIdentities` when the workspace still exists in this repo under a new identity; use `retiredPackages` when this repo no longer contains a workspace for this package, because the package was extracted to another repo or removed outright. Retired entries are inert: release-kit never consults them for baseline lookup or changelog attribution. Their declared `tagPrefix` values are recognized as historical, so `show-tag-prefixes` stops flagging them under "Undeclared tag prefixes."
 
-Worked example — `preflight` was extracted from this monorepo and continues as the standalone `readyup` project. Its tags stay in this repo as historical anchors:
+Worked example: `preflight` was extracted from this monorepo and continues as the standalone `readyup` project. Its tags stay in this repo as historical anchors:
 
 ```typescript
 import { defineConfig } from '@williamthorsen/release-kit/config';
@@ -77,7 +78,7 @@ Validation rules:
 - `name` and `tagPrefix` are required per entry and must be non-empty strings.
 - `successor` is optional; if present, it must be a non-empty string.
 - Full-tuple `(name, tagPrefix)` duplicates within `retiredPackages` are rejected.
-- Two entries sharing the same `tagPrefix` but different `name`s are accepted — this documents a package renamed within the repo before being retired.
+- Two entries sharing the same `tagPrefix` but different `name`s are accepted: Such a pair documents a package renamed within the repo before being retired.
 
 `show-tag-prefixes` currently does not render a dedicated "Retired packages" section (deferred). Declaring a retired entry is verifiable by confirming that its `tagPrefix` stops appearing under "Undeclared tag prefixes" in the `show-tag-prefixes` output.
 
@@ -89,23 +90,23 @@ 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.
+Because release-kit matches a tag to a prefix when the tag name starts with the prefix and continues with a digit, 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`, whose shorter prefix can't match any tag of the longer one.
 
 The rule is enforced at config load; the resulting error identifies both colliding declarations.
 
 ## `release-kit show-tag-prefixes`
 
-Print a per-workspace table of derived tag prefixes, tag counts, and declared legacy prefixes. Also surfaces any release-shaped tag prefix in the repo that is neither a derived prefix nor declared via `legacyIdentities`, along with a copy-pasteable `workspaces: [...]` config snippet. The snippet uses a `TODO-fill-in-legacy-npm-name` placeholder for each identity's `name`; replace it with the package's prior npm name before pasting.
+Prints a per-workspace table of derived tag prefixes, tag counts, and declared legacy prefixes. Also reports any release-shaped tag prefix in the repo that is neither a derived prefix nor declared via `legacyIdentities`, along with a copy-pasteable `workspaces: [...]` config snippet. The snippet uses a `TODO-fill-in-legacy-npm-name` placeholder for each identity's `name`; replace it with the package's prior npm name before pasting.
 
-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.
+Exits `0` when every workspace derives a prefix and the workspaces' prefixes don't collide; exits `1` on any derivation failure or collision. Undeclared candidates do not affect the exit code; the `legacy tag prefixes are declared` readyup check reports them as a warning.
 
-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.
+When a config file exists and either fails to load or fails schema validation, the command reports the failure on stderr and exits `1` without printing a preview, because a config that cannot be read leaves the declared-versus-undeclared verdict wrong in the one dimension on which the command exists to report. 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 {
@@ -134,6 +135,6 @@ The variable outranks detection. Under `auto`, release-kit defers to detection,
 
 1. `CI` is set to anything other than an empty string or `false`.
 2. The stream is not a terminal, as when its output is piped or redirected.
-3. `TERM` is `linux`, the Linux virtual console, which draws no emoji.
+3. `TERM` is `linux`, the Linux virtual console, which doesn't draw emoji.
 
-The style governs emoji alone. Changelog section emoji are file content rather than terminal output, and they are unaffected.
+The style affects only emoji. Changelog section emoji are file content rather than terminal output, and they are unaffected.