@williamthorsen/release-kit 10.5.0 → 10.7.0

package/dist/esm/sync-labels/resolveLabels.js

@@ -1,22 +1,28 @@
 import { loadPreset } from "./presets.js";
 export function resolveLabels(config) {
+    const labelEntries = Object.entries(config.labels ?? {});
+    const caseVariantGroups = findCaseVariantGroups(labelEntries.map(([name]) => name));
+    if (caseVariantGroups.length > 0) {
+        const groupList = caseVariantGroups.map((group) => group.map((name) => `'${name}'`).join(' and ')).join('; ');
+        throw new Error(`Keys in 'labels' differ only in case, which GitHub treats as the same label: ${groupList}. Keep one entry per label.`);
+    }
     const resolved = new Map();
     const presetNames = config.extends ?? [];
     for (const presetName of presetNames) {
         for (const label of loadPreset(presetName)) {
-            resolved.set(label.name, label);
+            resolved.set(toLabelKey(label.name), label);
         }
     }
-    const labelEntries = Object.entries(config.labels ?? {});
     for (const [name, spec] of labelEntries) {
+        const key = toLabelKey(name);
         if (spec === null) {
-            if (!resolved.has(name)) {
+            if (!resolved.has(key)) {
                 throw new Error(`Label '${name}' is set to null (remove), but no preset in 'extends' defines it. Fix the name or delete the entry.`);
             }
-            resolved.delete(name);
+            resolved.delete(key);
         }
         else {
-            resolved.set(name, {
+            resolved.set(key, {
                 name,
                 color: spec.color,
                 ...(spec.description !== undefined && { description: spec.description }),
@@ -25,6 +31,15 @@ export function resolveLabels(config) {
     }
     return sortLabels(resolved.values().toArray());
 }
+function findCaseVariantGroups(names) {
+    return Map.groupBy(names, toLabelKey)
+        .values()
+        .filter((group) => group.length > 1)
+        .toArray();
+}
 function sortLabels(labels) {
-    return [...labels].sort((a, b) => a.name.localeCompare(b.name));
+    return labels.toSorted((a, b) => a.name.localeCompare(b.name));
+}
+function toLabelKey(name) {
+    return name.toLowerCase();
 }

package/dist/esm/types.d.ts

@@ -18,6 +18,15 @@ export interface ChangelogItem {
      * with the canonical SSOT values) to surface them prominently in release notes.
      */
     breaking?: boolean;
+    /**
+     * Migration instruction for a consumer, taken from the `Migration:` paragraph of `body`.
+     *
+     * Derived from `body` wherever `body` is set, and absent where the body carries no labeled
+     * paragraph. Independent of `breaking`: a `fix` that tightens validation cannot carry `!` under
+     * the default breaking policy and still imposes a migration. `body` keeps the paragraph, so
+     * `CHANGELOG.md` goes on rendering it in place.
+     */
+    migration?: string;
     /**
      * Full git commit SHA when known. Captured from git-cliff's `--context` output and
      * persisted in `changelog.json` so that override files can target items by hash. Synthetic
@@ -379,8 +388,10 @@ export type LabelSpec = z.infer<typeof labelSpecSchema>;
  * the GitHub repo, distinct from labels applied to PRs and issues).
  *
  * Resolution is an ordered fold with last-writer-wins: presets in `extends` order, then the `labels` record,
- * where an entry adds a label, replaces one an earlier layer defined, or removes it (`null`).
- * A `null` naming a label no earlier layer defined is a resolve-time error (`resolveLabels`), not a schema error.
+ * where an entry adds a label, replaces one an earlier layer defined, or removes it (`null`). Names match
+ * case-insensitively, as GitHub matches them, and the replacing layer's spelling wins.
+ * Two misstatements are resolve-time errors (`resolveLabels`), not schema errors: `labels` keys that differ only in
+ * case, and a `null` naming a label that no earlier layer defined.
  */
 export declare const repoLabelsSchema: z.ZodObject<{
     extends: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/esm/validateConfig.js

@@ -31,7 +31,7 @@ function preprocessDeprecatedKeys(raw) {
     const errors = [];
     const cleaned = { ...raw };
     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. Remove this field from your config; see README for the updated workflow.');
+        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.');
         const releaseNotesCopy = { ...cleaned['releaseNotes'] };
         delete releaseNotesCopy['shouldCreateGithubRelease'];
         cleaned['releaseNotes'] = releaseNotesCopy;

package/docs/api.md

@@ -0,0 +1,73 @@
+# Programmatic API
+
+How to build a release config by hand with `deriveWorkspaceConfig()`, the script-based approach that predates the CLI, and the workspace records that `resolveReleaseTags` takes.
+
+## 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:
+
+```typescript
+import { deriveWorkspaceConfig } from '@williamthorsen/release-kit';
+
+// packages/arrays/package.json contains `"name": "@scope/arrays"`
+deriveWorkspaceConfig('packages/arrays');
+// => {
+//   dir: 'arrays',
+//   name: '@scope/arrays',
+//   tagPrefix: 'arrays-v',
+//   workspacePath: 'packages/arrays',
+//   packageFiles: ['packages/arrays/package.json'],
+//   changelogPaths: ['packages/arrays'],
+//   paths: ['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`.
+
+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.
+
+## Legacy script-based approach
+
+The CLI-driven approach is recommended for new setups. The script-based approach (using `runReleasePrepare` with a manually maintained config) is still supported for backward compatibility.
+
+```typescript
+// .github/scripts/release.config.ts
+import type { MonorepoReleaseConfig } from '@williamthorsen/release-kit';
+import { deriveWorkspaceConfig } from '@williamthorsen/release-kit';
+
+export const config: MonorepoReleaseConfig = {
+  workspaces: [deriveWorkspaceConfig('packages/arrays'), deriveWorkspaceConfig('packages/strings')],
+  formatCommand: 'npx prettier --write',
+};
+```
+
+```typescript
+// .github/scripts/release-prepare.ts
+import { runReleasePrepare } from '@williamthorsen/release-kit';
+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`.
+
+## `resolveReleaseTags` takes workspaces; `WorkspaceConfig` requires `workspacePath`
+
+Tag resolution is now driven by workspace records rather than a caller-supplied directory map, so `resolveReleaseTags` can report both the workspace `dir` and its `workspacePath` for every resolved tag.
+
+- `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:
+
+```diff
+-import { resolveReleaseTags } from '@williamthorsen/release-kit';
+-
+-const workspaceMap = new Map([['core', 'packages/core']]);
+-resolveReleaseTags(workspaceMap);
++import { deriveWorkspaceConfig, resolveReleaseTags } from '@williamthorsen/release-kit';
++
++resolveReleaseTags([deriveWorkspaceConfig('packages/core')]);
+```
+
+If you construct `WorkspaceConfig` objects directly, add `workspacePath` alongside the other required fields.

package/docs/changelogs.md

@@ -0,0 +1,70 @@
+# 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.
+
+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:
+
+| 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. 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.                                  |
+
+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:
+
+```jsonc
+{
+  "description": "Rename the workspace field",
+  "body": "Renames `name` to `id`.\n\nMigration: Change any uses of `name` to `id`.",
+  "migration": "Change any uses of `name` to `id`.",
+}
+```
+
+Three properties are worth knowing:
+
+- **It is independent of `breaking`.** A `fix` cannot carry `!` under the default breaking policy, and a `fix` that tightens validation still imposes 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`.
+
+The label match is exact: `migration:` and `**Migration:**` are not recognized.
+
+## cliff.toml setup
+
+The package includes a bundled `cliff.toml.template` that is used automatically when no custom config is found. The resolution order:
+
+| 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                              |
+
+The bundled template provides a generic git-cliff configuration that:
+
+- 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`
+
+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.
+
+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.
+
+## Release-notes injection
+
+With `releaseNotes.shouldInjectIntoReadme` set to `true`, `release-kit publish` writes each package's release notes into its `README.md` for the duration of the publish, then restores the file. The notes are the all-audience sections of the released version's entry in `.meta/changelog.json`, under a `## Release notes — v<version> (<date>)` heading, and they replace whatever lies between the marker pair:
+
+```markdown
+<!-- 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).

package/docs/configuration.md

@@ -0,0 +1,105 @@
+# Configuration
+
+The fields of `.config/release-kit.config.ts`, how a workspace declares its prior identities or a retired package, the rule against colliding tag prefixes, and the patterns that decide a bump.
+
+A minimal config file is in the [README](../README.md#configuration).
+
+## `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)          |
+
+All fields are optional.
+
+## `WorkspaceOverride`
+
+```typescript
+interface WorkspaceOverride {
+  dir: string; // Package directory name (e.g., 'arrays')
+  shouldExclude?: boolean; // If true, exclude from release processing
+  legacyIdentities?: LegacyIdentity[]; // Prior `(name, tagPrefix)` identities for this workspace
+}
+
+interface LegacyIdentity {
+  name: string; // Full scoped npm name at the time (e.g., '@scope/pkg')
+  tagPrefix: string; // Tag prefix under which historical tags were published (e.g., 'core-v')
+}
+```
+
+`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`
+
+```typescript
+interface RetiredPackage {
+  name: string; // Final scoped npm name while the package lived in this repo
+  tagPrefix: string; // Tag prefix under which the package's historical tags were published
+  successor?: string; // Optional successor package name (e.g., 'readyup')
+}
+```
+
+`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."
+
+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';
+
+export default defineConfig({
+  retiredPackages: [{ name: '@scope/preflight', tagPrefix: 'preflight-v', successor: 'readyup' }],
+});
+```
+
+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.
+
+`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.
+
+## Tag prefix collisions
+
+Tag prefixes from distinct owners must not be identical or be a strict prefix of one another. An owner is one of:
+
+- An active workspace, comprising its derived `tagPrefix` plus any declared `legacyIdentities[].tagPrefix`. Identities of the same workspace are one owner, so their prefixes are allowed to overlap (this represents the same package across renames).
+- 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.
+
+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.
+
+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.
+
+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.
+
+```typescript
+interface VersionPatterns {
+  major: string[]; // Patterns triggering a major bump ('!' = any breaking change)
+  minor: string[]; // Commit types triggering a minor bump
+}
+```
+
+Default: `{ major: ['!'], minor: ['feat'] }`

package/docs/editorial-overrides.md

@@ -0,0 +1,144 @@
+# 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.
+
+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.
+
+## File-location convention
+
+| Scope               | Path                                           | Applies to                                              |
+| ------------------- | ---------------------------------------------- | ------------------------------------------------------- |
+| Project (root)      | `.meta/changelog-overrides.json`               | The project changelog and every workspace's changelog   |
+| Workspace           | `packages/<ws>/.meta/changelog-overrides.json` | Only that workspace's changelog                         |
+| Single-package mode | `.meta/changelog-overrides.json`               | The package's changelog (collapses to the project case) |
+
+Filenames have no leading dot — the `.meta/` directory already provides the visibility property and parallels its sibling artifacts (`changelog.json`, `label-map.json`).
+
+## Composition: per-key shadowing
+
+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.
+- 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.
+
+## Stale-key warnings
+
+A key that doesn't match any commit gets a stale-reference warning. The warning's scope mirrors the file's scope:
+
+- **Per-workspace files** are warned against their own apply context. A key in `packages/foo/.meta/changelog-overrides.json` that doesn't match any commit in foo's changelog is unambiguously stale and is warned immediately.
+- **Root file** keys are aggregated globally — a root key that matches in any workspace or in the project changelog is non-stale; a root key matched nowhere is warned exactly once after all batches complete.
+
+## File shape
+
+```json
+{
+  "82962311": {
+    "audience": "skip"
+  },
+  "abc1234d": {
+    "body": "Cleaned-up prose without the original PR-template scaffolding."
+  },
+  "ef567890": {
+    "description": "Rewritten headline that fixes the typo",
+    "body": "Optional replacement body."
+  }
+}
+```
+
+Per-entry fields are all optional, but at least one must be present per entry:
+
+| Field         | Type                       | Effect                                                                                                                            |
+| ------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `audience`    | `'all' \| 'dev' \| 'skip'` | `'skip'` removes the entry entirely. `'all'` and `'dev'` are reserved for a future audience-reclassification feature (see below). |
+| `description` | `string`                   | Replaces the entry's bullet headline. Other fields are preserved.                                                                 |
+| `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).
+
+## Hash-prefix matching
+
+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:
+
+- **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.
+
+Override application errors abort the run with a non-zero exit; warnings (zero-match keys) are non-fatal and surface on `PrepareResult.warnings`.
+
+## Validation
+
+The override file is validated when `release-kit prepare` loads it. Each error names the offending key so you can locate it in your file:
+
+- Missing file → empty map, no error (the no-op default — projects that do not need overrides skip the file entirely).
+- Malformed JSON → 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).
+
+### Standalone validation: `release-kit overrides validate`
+
+For a focused overrides-only health check (locally or as a CI gate), run:
+
+```sh
+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`       |
+
+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).
+
+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.
+
+## 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.
+
+The eventual v2 behavior will let an override move a single item to a different audience section (e.g., reclassifying a `Documentation` entry as `Internal features` to keep it out of public-facing release notes). v1 deliberately leaves that as a separate change so the override mechanism can ship now and the section-split logic can land additively later.
+
+## Worked example 1: cleaning up scaffolded historical commits (root file)
+
+Suppose a year-old commit `82962311` was authored from a PR template that left `## What` / `## Why` headings in the body, and that commit now appears in your in-app release notes as literal Markdown headings. Add an override at the project tier:
+
+```json
+// .meta/changelog-overrides.json
+{
+  "82962311": {
+    "body": "Add the in-app release-notes page with version-aware navigation."
+  }
+}
+```
+
+On the next `release-kit prepare` run, the matched item's body is replaced before the JSON and Markdown artifacts are written. The original git history is untouched.
+
+## Worked example 2: suppressing a cross-attribution spillover (workspace file)
+
+Release-kit attributes commits to workspaces by file path, so a commit that primarily belongs to one workspace can land in another's changelog if it touched files there. Suppose commit `1ce3d2f` renamed the `audit-deps` package to `v11y-check` (scope `v11y-check`) but also edited `packages/nmr/src/default-scripts.ts` and `packages/nmr/README.md`. The commit correctly appears in `packages/v11y-check/CHANGELOG.md`, but it also spills into `packages/nmr/CHANGELOG.md` where it isn't the right editorial framing.
+
+Drop a workspace-tier override at `packages/nmr/.meta/changelog-overrides.json`:
+
+```json
+// packages/nmr/.meta/changelog-overrides.json
+{
+  "1ce3d2f": {
+    "audience": "skip"
+  }
+}
+```
+
+The commit is now suppressed in nmr's changelog only — it still appears in v11y-check's, where it belongs. A root-tier `'skip'` would have removed it from both, which is the wrong outcome.

package/docs/labels.md

@@ -0,0 +1,83 @@
+# Labels
+
+How to declare the repository's labels in `.config/release-kit.config.ts`, how the scaffolded workflow applies them, and the published schema for `.meta/label-map.json`.
+
+## `release-kit sync-labels`
+
+Manage GitHub label definitions via the `repoLabels` block of `.config/release-kit.config.ts`.
+
+`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.
+
+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
+
+```typescript
+import { defineConfig } from '@williamthorsen/release-kit/config';
+
+export default defineConfig({
+  repoLabels: {
+    extends: ['common'],
+    labels: {
+      'scope:my-package': { color: '00ff96' }, // add, with no description
+      bug: { color: 'b60205', description: 'Something broken' }, // replace the preset's `bug`
+      wontfix: null, // remove the preset's `wontfix`
+    },
+  },
+});
+```
+
+The block declares the repository's label registry — the set of labels defined on the GitHub repo, distinct from labels applied to PRs and issues. Resolution is an ordered fold with last-writer-wins:
+
+1. Presets, in `extends` order — a later preset wins on a shared name.
+2. The `labels` record — an entry adds a label, replaces one an earlier layer defined, or removes it (`null`). Replacement is wholesale: an entry omitting `description` resolves to no description rather than inheriting the one an earlier layer supplied.
+
+Names match case-insensitively, as GitHub matches them: `Bug` in the `labels` record replaces a preset's `bug`, and `Bug: null` removes it. A label takes the spelling of the last layer to write it.
+
+`description` is optional throughout, in a preset as in the `labels` record, and `sync-labels init` generates none for a scope label. The generated file spells an absent description `''` because `github-label-sync` reads an omitted description as "leave the label's current one alone"; the empty form clears it.
+
+Overlaps between layers are never errors; order resolves them, and the committed `.github/labels.yaml` diff is where an unexpected change surfaces at review. Two misstatements are config errors, because neither is visible in the output diff: a dangling `null`, which removes a name that no preset defines, and `labels` keys that differ only in case, all but one of which the fold would discard.
+
+### When labels are applied
+
+The scaffolded workflow carries three triggers:
+
+| Trigger                                                   | Job     | Token           | Effect                            |
+| --------------------------------------------------------- | ------- | --------------- | --------------------------------- |
+| Push to the default branch touching `.github/labels.yaml` | `sync`  | `issues: write` | Applies the labels                |
+| Manual dispatch (`release-kit sync-labels sync`)          | `sync`  | `issues: write` | Applies the labels                |
+| Pull request touching `.github/labels.yaml`               | `check` | `issues: read`  | Logs the diff without applying it |
+
+Applying on merge closes the window in which a regenerated `.github/labels.yaml` sits unapplied — a window in which a later manual dispatch would apply a label set nobody reviewed.
+
+The `check` job runs the same sync in dry-run. Its **Label diff** log group lists every create, edit, rename, and deletion the sync would perform, including deletions of labels the file does not declare — the destructive edits a diff of `.github/labels.yaml` alone cannot show, because a label created by hand or by another workflow is absent from the file both before and after. Read that log; the check reports success whether or not the diff is destructive, so a green check is not evidence that nothing will be deleted.
+
+The two jobs are split because a job's permissions are fixed when the run is created and cannot vary by trigger. The split is what keeps a write-scoped token out of pull-request runs.
+
+The push trigger filters on the path alone; the `sync` job compares `github.ref_name` against the repository's default branch. The workflow therefore needs no per-repo edit whatever that branch is named — and a push touching `.github/labels.yaml` on any other branch produces a run whose jobs all skip.
+
+Manual dispatch is not a preview. It matches the `sync` job, so it applies the labels, deletions included; only the pull-request path runs in dry-run.
+
+### Dry-run checks on fork pull requests
+
+GitHub issues a read-only `GITHUB_TOKEN` to pull requests from forks, and by default holds runs from first-time contributors until a maintainer approves them. The dry-run reads labels and writes nothing, so the check normally runs once approved. A repo that disables workflows on fork pull requests gets no check at all; to preview such a change, push the branch to the base repo and open the pull request from there.
+
+### Published JSON Schema for `.meta/label-map.json`
+
+release-kit publishes a JSON Schema for `.meta/label-map.json` — a separate, generic data file that maps commit-prefix scopes and types to GitHub label names. The schema lives at `packages/release-kit/schemas/label-map.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/label-map.json
+```
+
+Consumers reference it from the top of their `.meta/label-map.json`:
+
+```json
+{
+  "$schema": "https://github.com/williamthorsen/node-monorepo-tools/raw/release-kit-v<version>/packages/release-kit/schemas/label-map.json",
+  "types": { "feat": "feature", "fix": "fix" },
+  "scopes": { "audit": "scope:audit" }
+}
+```
+
+release-kit publishes the schema only; it does not generate `.meta/label-map.json`. Generation requires commit-prefix knowledge that lives outside release-kit (in agent-conventions tooling), and is owned by those consumers.