@williamthorsen/release-kit 5.2.1 → 5.3.1

package/CHANGELOG.md

@@ -2,7 +2,57 @@
 
 All notable changes to this project will be documented in this file.
 
-## [release-kit-v5.2.1] - 2026-05-05
+## 5.3.1 — 2026-05-19
+
+### 🐛 Bug fixes
+
+- Validate overrides against the full release history (#401)
+
+  Fixes an issue where `release-kit overrides validate` reported overrides as stale when they targeted commits in past releases, even though `release-kit prepare` correctly matched them. The two commands now agree on which overrides are stale.
+
+### ♻️ Refactoring
+
+- Restructure tests and align core package directory with package name (#405)
+
+  Tests in every package are now typechecked alongside the code they cover, so type breakage in tests fails the build instead of slipping through. The `core` package's workspace directory is renamed to match its package name, so `nmr -F nmr-core ...` and `pnpm --filter nmr-core ...` now resolve where they previously failed.
+
+## 5.3.0 — 2026-05-10
+
+### 🎉 Features
+
+- Enable editorial overrides for changelog entries (#387)
+
+  Allows `release-kit` consumers to skip or correct historical changelog entries by means of an overrides file.
+
+- Decentralize changelog overrides to per-scope .meta/ files (#391)
+
+  Adds support for workspace-scoped editorial-override files for `release-kit`-generated changelogs. A repo-root file applies overrides to every workspace's changelog; a workspace-tier file applies only to that workspace.
+
+- Add section markers and authenticated upstream fetch (#393)
+
+  A new `markers` block in `work-types.json` describes the breaking-changes emoji and label, making them available for use by consumers.
+
+  `work-types check` and `work-types sync` now authenticate when `GITHUB_TOKEN` is set, so they can reach private upstream repositories.
+
+- Validate changelog overrides from the command line (#395)
+
+  Adds a `release-kit overrides validate` subcommand that audits every `.meta/changelog-overrides.json` file across the project root and per-workspace scopes in one pass. The command reports schema errors, ambiguous-prefix collisions, and stale-key warnings with tiered exit codes so CI can choose its own failure threshold. The same validation is also available via a library function exported by the package.
+
+### 🐛 Bug fixes
+
+- Suppress git-cliff stale-version warnings on prepare (#373)
+
+  Fixes an issue where `release-kit prepare` repeatedly printed git-cliff's "A new version of git-cliff is available" notice — twice per release unit, so 2 × N times for an N-package monorepo run — while never updating the locally cached git-cliff binary. Each `prepare` run now revalidates the npm cache once before any cliff work, so the binary stays current with upstream releases and the notice no longer surfaces on every per-workspace invocation.
+
+- Use synthetic changelogs for forced empty-range releases (#376)
+
+  Fixes an issue where `release-kit prepare` with `--force`, `--bump=X`, or `--set-version` would invoke git-cliff against units that had no commits since their last tag, surfacing confusing `WARN  git_cliff > There is already a tag (...)` lines (twice per affected unit) and silently leaving `CHANGELOG.md` and `.meta/changelog.json` stale. Empty-range bumps now write a synthetic `Notes / Forced version bump.` entry to both files instead of invoking git-cliff. Applies to all three release stages: single-package, per-workspace, and project. Prior changelog history is preserved on every path.
+
+- Accept `breakingPolicies` field in config files (#394)
+
+  Fixes an issue where setting `breakingPolicies` in `release-kit.config.ts` was rejected as an unknown field, leaving per-work-type breaking-policy configuration unreachable from the config file. Each entry accepts `'forbidden'`, `'optional'`, or `'required'`; an empty object opts out of enforcement.
+
+## 5.2.1 — 2026-05-05
 
 ### 🐛 Bug fixes
 
@@ -10,7 +60,7 @@ All notable changes to this project will be documented in this file.
 
   Fixes an issue where `release-kit create-github-release --tags <tag>` exited 1 — failing the calling CI workflow — when the requested tag had no changelog entry. Tooling-only releases (those whose changelog generator legitimately omits an entry) are now soft-skipped with an info-level summary, the same as releases skipped because their entry has no audience-relevant content. Typo protection is preserved: passing an unknown tag to `--tags` still exits 1.
 
-## [release-kit-v5.2.0] - 2026-05-04
+## 5.2.0 — 2026-05-04
 
 ### 🎉 Features
 
@@ -50,7 +100,7 @@ All notable changes to this project will be documented in this file.
 
   Fixes an issue where running `audit-deps`, `nmr`, or `release-kit` from the locally built `dist/esm/` after a `git pull` could report a stale version. Each CLI now reads its version directly from its `package.json` at startup, so version reads stay in sync with the installed source without requiring a fresh `pnpm install` or rebuild.
 
-## [release-kit-v5.1.0] - 2026-04-30
+## 5.1.0 — 2026-04-30
 
 ### 🎉 Features
 
@@ -110,7 +160,7 @@ All notable changes to this project will be documented in this file.
 
   Documents the strict-prefix tag-prefix collision rule as a general validation rule that applies to every release-kit consumer declaring more than one tag prefix: across active workspaces, declared legacy identities, retired packages, and the optional `project` block. Previously, the rule appeared only inside the `Project releases` validation list.
 
-## [release-kit-v5.0.0] - 2026-04-23
+## 5.0.0 — 2026-04-23
 
 ### 🎉 Features
 
@@ -122,11 +172,11 @@ All notable changes to this project will be documented in this file.
 
   Adds release-notes injection to the configs scaffolded by `release-kit init`, so newly-onboarded consumers get the feature without having to discover or toggle the flag. The release-kit readyup kit gains a check that warns when a consumer's README is missing the marker pair where injected notes should land — without those markers, injection silently prepends to the top of the file, pushing the README's title below the notes.
 
-- Split GitHub Release creation into its own workflow (#272)
+- 🚨 **Breaking:** Split GitHub Release creation into its own workflow (#272)
 
   Splits GitHub Release creation out of release-kit publish into a dedicated release-kit create-github-release CLI command and a matching reusable GitHub Actions workflow. Consumers that do not publish to npm can now create Releases independently, and the contents: write permission required to create a Release no longer leaks into the publish path.
 
-- Replace --only with --tags on release-kit publish and push (#273)
+- 🚨 **Breaking:** Replace --only with --tags on release-kit publish and push (#273)
 
   `release-kit publish` and `release-kit push` now filter by full tag name via `--tags=<tag1,tag2>` instead of workspace directory name via `--only=<dir>`, matching the shape already used by `create-github-release`. Callers pass the tag they care about (e.g., `core-v1.3.0`) directly, with no translation step back to the publishing workspace's directory name. The reusable workflow gains an optional `tags:` input, and the internal `publish.yaml` caller now passes `tags: ${{ github.ref_name }}`, making the publish scope explicit rather than relying on the single-tag fetch default of `actions/checkout@v6`.
 
@@ -142,13 +192,13 @@ All notable changes to this project will be documented in this file.
 
   Adds a one-shot migration tool, `migrate-tag-prefixes.sh`, shipped inside the release-kit package. The tool creates additive annotated-tag aliases under release-kit's new unscoped-package-name prefix that point at the same commits as the previous directory-basename tags, bridging the gap so post-migration `getCommitsSinceTarget` calls can resolve prior releases.
 
-- Add legacyTagPrefixes config field (#289)
+- 🚨 **Breaking:** Add legacyTagPrefixes config field (#289)
 
   Replaces the v4 → v5 tag-prefix migration mechanism (tag aliasing via `migrate-tag-prefixes.sh`) with a declarative `legacyTagPrefixes` config field. release-kit now searches for both legacy and modern prefixes when generating changelogs.
 
   Adds a companion `release-kit show-tag-prefixes` CLI command that renders a per-workspace table of derived and declared legacy prefixes, flags cross-workspace collisions, and surfaces undeclared candidate prefixes with a copy-pasteable config snippet. `release-kit prepare` gains a one-line hint pointing operators to `show-tag-prefixes` when a workspace has no baseline tag but the repo contains candidate-shaped tags.
 
-- Replace `legacyTagPrefixes` with `legacyIdentities` (#297)
+- 🚨 **Breaking:** Replace `legacyTagPrefixes` with `legacyIdentities` (#297)
 
   Replaces the per-workspace `legacyTagPrefixes: string[]` field with `legacyIdentities: LegacyIdentity[]`, a structured array of complete `(name, tagPrefix)` historical snapshots. Each legacy identity is now a self-consistent record of what a workspace used to be called and how its tags used to be prefixed, so a workspace that has been renamed (npm name change, tag-prefix change, or both) carries one entry per prior identity.
 
@@ -168,15 +218,15 @@ All notable changes to this project will be documented in this file.
 
 ### ♻️ Refactoring
 
-- Rename `component` to `workspace` in config API and internals (#296)
+- 🚨 **Breaking:** Rename `component` to `workspace` in config API and internals (#296)
 
   Renames release-kit's per-workspace vocabulary from "component" to "workspace" throughout the public API, internal types, validation messages, CLI help, init templates, and documentation. Behavior is unchanged; only identifiers, error-message strings, scaffolded template text, and prose have been changed.
 
-- Rename `node-monorepo-core` to `nmr-core` (#304)
+- 🚨 **Breaking:** Rename `node-monorepo-core` to `nmr-core` (#304)
 
   Renames the shared-utilities package from `@williamthorsen/node-monorepo-core` to `@williamthorsen/nmr-core`, aligning it with the repository's `nmr-*` naming convention. The package's functionality and version are unchanged; only the published name differs.
 
-## [release-kit-v4.8.0] - 2026-04-17
+## 4.8.0 — 2026-04-17
 
 ### 🎉 Features
 
@@ -190,7 +240,7 @@ All notable changes to this project will be documented in this file.
 
   Fixes silent swallowing of unexpected filesystem errors in `detectRepoType`. Previously, errors like `EACCES` (permission denied) or `EMFILE` (too many open files) when reading `package.json` were caught and discarded, causing the function to silently return `'single-package'` instead of surfacing the problem.
 
-## [release-kit-v4.7.0] - 2026-04-16
+## 4.7.0 — 2026-04-16
 
 ### 🎉 Features
 
@@ -198,7 +248,7 @@ All notable changes to this project will be documented in this file.
 
   Commits prefixed with `##` are now included in changelogs without requiring a ticket ID. This supports ad-hoc changes made during interactive sessions where creating a ticket and PR adds undesired overhead.
 
-## [release-kit-v4.6.0] - 2026-04-15
+## 4.6.0 — 2026-04-15
 
 ### 🎉 Features
 
@@ -232,7 +282,7 @@ All notable changes to this project will be documented in this file.
 
   Prepares the repository for reliable tag-triggered npm publishing by adding missing package metadata, standardizing licensing, and introducing a readyup kit that validates publish readiness across all packages.
 
-## [release-kit-v4.5.1] - 2026-04-10
+## 4.5.1 — 2026-04-10
 
 ### 🐛 Bug fixes
 
@@ -240,7 +290,7 @@ All notable changes to this project will be documented in this file.
 
   Fixes three issues in `release-kit sync-labels init` scaffolding output that cause immediate errors for consumers: adds missing workflow permissions, corrects config template indentation from 2 to 4 spaces, and switches YAML quoting from double to single quotes.
 
-## [release-kit-v4.4.0] - 2026-04-04
+## 4.4.0 — 2026-04-04
 
 ### 🎉 Features
 
@@ -268,7 +318,7 @@ All notable changes to this project will be documented in this file.
 
   Restructures the release-kit README to match the documentation standard established by the preflight README (#114). Reorders sections to follow the cross-package convention, converts CLI flag listings from code blocks to tables, adds representative `prepare --dry-run` output to the quick start, and condenses ~90 lines of inline workflow YAML into a summary with an inputs table and trigger examples. Fixes several accuracy gaps found by verifying documentation against source.
 
-## [release-kit-v4.0.0] - 2026-04-02
+## 4.0.0 — 2026-04-02
 
 ### 🎉 Features
 
@@ -276,11 +326,11 @@ All notable changes to this project will be documented in this file.
 
   Renames all three reusable GitHub Actions workflow files from the inconsistent `-workflow.yaml`/bare `.yaml` convention to a uniform `.reusable.yaml` suffix. Updates all references across caller workflows, release-kit templates, tests, preflight collection, and documentation. Scaffolds the sync-labels caller workflow and labels file for this repo. Deletes superseded legacy files.
 
-## [release-kit-v3.0.0] - 2026-03-29
+## 3.0.0 — 2026-03-29
 
 ### 🎉 Features
 
-- Support conventional-commit format in commit parsing (#85)
+- 🚨 **Breaking:** Support conventional-commit format in commit parsing (#85)
 
   Adds support for the conventional commits format (`type(scope): description`) alongside the existing pipe-prefixed format (`scope|type: description`) in release-kit's commit parser. Renames `workspace` to `scope` throughout release-kit types, config, validation, and consumers.
 
@@ -310,7 +360,7 @@ All notable changes to this project will be documented in this file.
 
   Restructures `releasePrepareMono` from a single-pass loop into a phased pipeline that automatically patch-bumps workspace dependents when a component is released. A reverse dependency graph is built from `workspace:` references in `dependencies` and `peerDependencies`, then BFS propagation walks upward from bumped components to their dependents. Propagated-only components receive synthetic changelog entries instead of git-cliff invocations.
 
-## [release-kit-v2.3.2] - 2026-03-28
+## 2.3.2 — 2026-03-28
 
 ### 🐛 Bug fixes
 
@@ -318,7 +368,7 @@ All notable changes to this project will be documented in this file.
 
   Prevents `releasePrepareMono` and `releasePrepare` from silently skipping components whose commits have unparseable messages. Adds ticket-prefix stripping to `parseCommitMessage` (mirroring cliff.toml's `commit_preprocessors`), a patch-floor safety net when commits exist but none parse, and unparseable-commit reporting in `reportPrepare`.
 
-## [release-kit-v2.3.0] - 2026-03-28
+## 2.3.0 — 2026-03-28
 
 ### 🎉 Features
 
@@ -346,7 +396,7 @@ All notable changes to this project will be documented in this file.
 
   Adds three unit tests to `releasePrepare.unit.test.ts` covering previously untested code paths: the `bumpOverride` bypass of commit-based bump detection, custom `tagPrefix` propagation into tags, and tag computation in dry-run mode.
 
-## [release-kit-v2.2.0] - 2026-03-27
+## 2.2.0 — 2026-03-27
 
 ### 🎉 Features
 
@@ -411,11 +461,11 @@ All notable changes to this project will be documented in this file.
 
   Replaces the legacy workspace script runner and ~25 root `package.json` scripts with `nmr`, the monorepo's own context-aware script runner. Root scripts are reduced to 4 (`prepare`, `postinstall`, `ci`, `bootstrap`), packages use direct build commands for bootstrap, and release-kit declares tier-3 test overrides for its integration test configs.
 
-## [release-kit-v2.1.0] - 2026-03-17
+## 2.1.0 — 2026-03-17
 
 ### 🎉 Features
 
-- Slim down release workflow by removing unnecessary pnpm install (#21)
+- 🚨 **Breaking:** Slim down release workflow by removing unnecessary pnpm install (#21)
 
   Make release-kit self-contained by invoking git-cliff via `npx --yes` instead of requiring it on PATH, and by appending modified file paths to the format command so lightweight formatters like `npx prettier --write` work without a full `pnpm install`. Update init templates, README, and consuming repo config/workflow to reference workflow v3.
 
@@ -423,7 +473,7 @@ All notable changes to this project will be documented in this file.
 
   Add a `--force` flag to `release-kit prepare` that bypasses the "no commits since last tag" check in monorepo mode, allowing version bumping and changelog generation to proceed even when no new commits are found since the last release tag. The flag requires `--bump` since there are no commits to infer bump type from. The local release workflow gains a `force` boolean input for future use.
 
-- Move reusable release workflow into repo (#26)
+- 🚨 **Breaking:** Move reusable release workflow into repo (#26)
 
   Moves the reusable release workflow from `williamthorsen/.github` into this repo as `release-workflow.yaml`, stripping all pnpm-related steps since release-kit now runs git-cliff and prettier via `npx` internally. Updates this repo's caller workflow to use a relative path and update init templates to reference the new location. Establishes a naming convention (`{name}-workflow.yaml` for reusable, `{name}.yaml` for callers) and independent versioning strategy (`{name}-workflow-v{major}` tags), documented in `.github/workflows/README.md`.
 
@@ -437,7 +487,7 @@ All notable changes to this project will be documented in this file.
 
   Addresses five code quality issues and a test coverage gap identified during the release-kit migration (#5). Extracts a duplicated `isRecord` type guard into a shared module, eliminates a double-read in `bumpAllVersions`, improves error handling in `usesPnpm` by replacing a silent catch with a structured error boundary, removes an unreachable `'feature'` pattern from version defaults, and adds an integration test for scaffold template path resolution.
 
-## [release-kit-v1.0.1] - 2026-03-14
+## 1.0.1 — 2026-03-14
 
 ### 🎉 Features
 
@@ -445,4 +495,4 @@ All notable changes to this project will be documented in this file.
 
   Migrates the complete `@williamthorsen/release-kit` package (v1.0.1) from `williamthorsen/toolbelt` into `packages/release-kit/`, adds shebang preservation to the shared esbuild plugin for CLI binaries, and sets up dogfooding infrastructure so this monorepo uses release-kit for its own releases.
 
-<!-- generated by git-cliff -->
+<!-- Generated by release-kit. Do not edit this file. Use .meta/changelog-overrides.json to override entries. -->

package/README.md

@@ -2,16 +2,16 @@
 
 Version-bumping and changelog-generation toolkit for release workflows.
 
-Provides a self-contained CLI that auto-discovers workspaces from `pnpm-workspace.yaml`, parses conventional commits, determines version bumps, updates `package.json` files, and generates changelogs with `git-cliff`.
+Provides a self-contained CLI that auto-discovers workspaces from `pnpm-workspace.yaml`, parses conventional commits, determines version bumps, updates `package.json` files, and generates changelogs from `git-cliff --context` output rendered in-process (with optional [editorial overrides](#editorial-overrides)).
 
 <!-- section:release-notes -->
-## Release notes — v5.2.1 (2026-05-05)
+## Release notes — v5.3.1 (2026-05-19)
 
 ### 🐛 Bug fixes
 
-- Soft-skip tags with no changelog entry under --tags (#366)
+- Validate overrides against the full release history (#401)
 
-  Fixes an issue where `release-kit create-github-release --tags <tag>` exited 1 — failing the calling CI workflow — when the requested tag had no changelog entry. Tooling-only releases (those whose changelog generator legitimately omits an entry) are now soft-skipped with an info-level summary, the same as releases skipped because their entry has no audience-relevant content. Typo protection is preserved: passing an unknown tag to `--tags` still exits 1.
+  Fixes an issue where `release-kit overrides validate` reported overrides as stale when they targeted commits in past releases, even though `release-kit prepare` correctly matched them. The two commands now agree on which overrides are stale.
 <!-- /section:release-notes -->
 
 ## Installation
@@ -42,7 +42,7 @@ Example output from `prepare --dry-run` in a monorepo:
   📦 1.2.0 → 1.3.0 (minor)
   [dry-run] Would bump packages/arrays/package.json
   Generating changelogs...
-  [dry-run] Would run: npx --yes git-cliff ... --output packages/arrays/CHANGELOG.md
+  [dry-run] Would write packages/arrays/CHANGELOG.md
   🏷️  arrays-v1.3.0
 
 ── strings ─────────────────────────────────────
@@ -52,7 +52,7 @@ Example output from `prepare --dry-run` in a monorepo:
   📦 0.5.1 → 0.5.2 (patch)
   [dry-run] Would bump packages/strings/package.json
   Generating changelogs...
-  [dry-run] Would run: npx --yes git-cliff ... --output packages/strings/CHANGELOG.md
+  [dry-run] Would write packages/strings/CHANGELOG.md
   🏷️  strings-v0.5.2
 
 ✅ Release preparation complete.
@@ -67,7 +67,7 @@ That's it for most repos. The CLI auto-discovers workspaces and applies sensible
 1. **Workspace discovery**: reads `pnpm-workspace.yaml` and resolves its `packages` globs to find workspace directories. Each directory containing a `package.json` becomes a workspace. If no workspace file is found, the repo is treated as a single-package project.
 2. **Config loading**: loads `.config/release-kit.config.ts` (if present) via [jiti](https://github.com/unjs/jiti) and merges it with discovered defaults.
 3. **Commit analysis**: for each workspace, finds commits since the last version tag, parses them for type and scope, and determines the appropriate version bump.
-4. **Version bump + changelog**: bumps `package.json` versions and generates changelogs via `git-cliff`.
+4. **Version bump + changelog**: bumps `package.json` versions, builds structured `ChangelogEntry[]` from `git-cliff --context`, applies any [editorial overrides](#editorial-overrides) from per-scope `.meta/changelog-overrides.json` files, and renders both `CHANGELOG.md` and `.meta/changelog.json` from that single source. `git-cliff` is invoked only for its `--context` JSON; markdown rendering happens in-process so `.meta/changelog.json` and `CHANGELOG.md` always agree.
 5. **Release tags file**: writes computed tags to `tmp/.release-tags` for the release workflow to read when tagging and pushing.
 
 ## Commit format
@@ -210,7 +210,7 @@ When configured, each `release-kit prepare` run additionally:
 
 - Computes commits since the last project tag (`<tagPrefix><version>`), filtered to the union of every contributing workspace's paths.
 - Bumps the root `package.json`'s `version` field using the same bump-derivation rules as workspaces (or the `--bump=...` override).
-- Regenerates the root `./CHANGELOG.md` via `git-cliff`, scoped to the project's `tagPrefix` and contributing paths.
+- Regenerates the root `./CHANGELOG.md` from the structured `ChangelogEntry[]` produced by `git-cliff --context` (scoped to the project's `tagPrefix` and contributing paths) and any matching editorial overrides.
 - Emits `./.meta/changelog.json` (when `changelogJson.enabled`).
 - With `--with-release-notes`, additionally emits `./docs/RELEASE_NOTES.v<version>.md`.
 - Appends the project tag to `tmp/.release-tags` so `release-kit commit` and `release-kit tag` pick it up alongside per-workspace tags.
@@ -284,33 +284,33 @@ The canonical taxonomy lives in `packages/release-kit/src/work-types.json` and i
 
 | Tier     | Key         | Header                    | Aliases       | `!` policy   |
 | -------- | ----------- | ------------------------- | ------------- | ------------ |
-| Public   | `feat`      | 🎉 Features               | `feature`     | optional     |
-| Public   | `drop`      | 🪦 Removed                |               | **required** |
-| Public   | `deprecate` | 🗑️ Deprecated             |               | forbidden    |
-| Public   | `fix`       | 🐛 Bug fixes              | `bugfix`      | forbidden    |
-| Public   | `sec`       | 🔒 Security               | `security`    | optional     |
-| Public   | `perf`      | ⚡ Performance            | `performance` | forbidden    |
-| Internal | `internal`  | 🏗️ Internal features      | `utility`     | forbidden    |
-| Internal | `refactor`  | ♻️ Refactoring            |               | forbidden    |
-| Internal | `tests`     | 🧪 Tests                  | `test`        | forbidden    |
-| Process  | `tooling`   | ⚙️ Tooling                |               | forbidden    |
-| Process  | `ci`        | 👷 CI                     |               | forbidden    |
-| Process  | `deps`      | 📦 Dependencies           | `dep`         | forbidden    |
-| Process  | `ai`        | 🤖 Agentic support        |               | forbidden    |
-| Process  | `docs`      | 📚 Documentation          | `doc`         | forbidden    |
-| Process  | `fmt`       | (excluded from changelog) |               | forbidden    |
+| public   | `feat`      | 🎉 Features               | `feature`     | optional     |
+| public   | `drop`      | 🪦 Removed                |               | **required** |
+| public   | `deprecate` | 🗑️ Deprecated             |               | forbidden    |
+| public   | `fix`       | 🐛 Bug fixes              | `bugfix`      | forbidden    |
+| public   | `sec`       | 🔒 Security               | `security`    | optional     |
+| public   | `perf`      | ⚡ Performance            | `performance` | forbidden    |
+| internal | `internal`  | 🏗️ Internal features      | `utility`     | forbidden    |
+| internal | `refactor`  | ♻️ Refactoring            |               | forbidden    |
+| internal | `tests`     | 🧪 Tests                  | `test`        | forbidden    |
+| process  | `tooling`   | ⚙️ Tooling                |               | forbidden    |
+| process  | `ci`        | 👷 CI                     |               | forbidden    |
+| process  | `deps`      | 📦 Dependencies           | `dep`         | forbidden    |
+| process  | `ai`        | 🤖 Agentic support        |               | forbidden    |
+| process  | `docs`      | 📚 Documentation          | `doc`         | forbidden    |
+| process  | `fmt`       | (excluded from changelog) |               | forbidden    |
 
 #### Tier semantics
 
-- **Public** — visible to all audiences. Public-tier sections appear in both public release notes and dev changelogs.
-- **Internal** — dev-only. Internal-tier sections appear in dev changelogs but not in public-facing release notes.
-- **Process** — dev-only. Same audience treatment as Internal.
+- **`public`** — visible to all audiences. `public`-tier sections appear in both public release notes and dev changelogs.
+- **`internal`** — dev-only. `internal`-tier sections appear in dev changelogs but not in public-facing release notes.
+- **`process`** — dev-only. Same audience treatment as `internal`.
 
-Section render order is **tier order (Public → Internal → Process), then row order within tier**. The bundled `cliff.toml.template` encodes this order via hidden `<!-- NN -->` HTML-comment prefixes on each parser's `group` value; tera's `group_by` filter sorts groups lexicographically (now monotonic by row number), and the body template's `striptags` filter erases the prefix from rendered headings.
+Section render order is **tier order (`public` → `internal` → `process`), then row order within tier**. The bundled `cliff.toml.template` encodes this order via hidden `<!-- NN -->` HTML-comment prefixes on each parser's `group` value; tera's `group_by` filter sorts groups lexicographically (now monotonic by row number), and the body template's `striptags` filter erases the prefix from rendered headings.
 
 #### `docs` reclassification
 
-`docs`/Documentation has moved from the all-audience tier (where it lived before this taxonomy was formalised) to the dev-only Process tier. **Documentation commits no longer appear in public-facing release notes.** They still appear in `CHANGELOG.md` and `changelog.json` under the `audience: 'dev'` classification.
+`docs`/Documentation has moved from the all-audience tier (where it lived before this taxonomy was formalised) to the dev-only `process` tier. **Documentation commits no longer appear in public-facing release notes.** They still appear in `CHANGELOG.md` and `changelog.json` under the `audience: 'dev'` classification.
 
 #### `utility` alias
 
@@ -356,6 +356,22 @@ Items whose commit subject carries the `!` prefix (e.g. `feat!`, `drop!`, `feat(
 
 Only the prefix `!` triggers this marker. A `BREAKING CHANGE:` body footer on its own does **not** retroactively mark a changelog item as breaking — the changelog signal is tied to the commit-prefix policy. This avoids surprise breaking-marker appearances for older commits written under earlier conventions.
 
+The emoji and label of this marker are sourced from the `markers.breaking` entry in `work-types.json` (see [Section markers](#section-markers)) so consumers that render their own breaking-changes section draw from the same SSOT.
+
+### Section markers
+
+Alongside `tiers` and `types`, `work-types.json` exposes a top-level `markers` object for cross-cutting section markers — visual indicators that aren't tied to a specific work type. Today the canonical entry is `breaking`; additional keys (e.g., security advisories, migration notices) can be added without a schema change.
+
+```jsonc
+{
+  "markers": {
+    "breaking": { "emoji": "🚨", "label": "Breaking" },
+  },
+}
+```
+
+Entries store plain text only — the SSOT is format-agnostic, so consumers apply their own emphasis (Markdown bold, ANSI escape, HTML `<strong>`) when constructing the rendered form. release-kit's own renderer constructs the per-bullet prefix as `${emoji} **${label}:** ` from this entry.
+
 #### `fmt`
 
 `fmt:` commits are recognized by `parseCommitMessage` (they contribute to a patch bump) but `fmt` carries `excludedFromChangelog: true`. The bundled `cliff.toml.template` skips `fmt:` commits at the parser level, so they never appear in `CHANGELOG.md`, `changelog.json`, or release notes. The label and emoji are present in `work-types.json` for schema parity with the codeassembly upstream but never render.
@@ -364,7 +380,169 @@ Only the prefix `!` triggers this marker. A `BREAKING CHANGE:` body footer on it
 
 Work types from your config are merged with these defaults by key — your entries override or extend, they don't replace the full set. Release-notes sections are rendered in the declaration order of the merged work-types record, with any unknown titles trailing the known ones.
 
-The default `devOnlySections` (excluded from public release notes but still written to `CHANGELOG.md`) are derived from the Internal and Process tiers (excluding `fmt`). Override via `changelogJson.devOnlySections` in your config; matching is decorator-tolerant, so a bare-name override like `['Internal features']` keeps working against the emoji-prefixed and prefix-decorated default titles.
+The default `devOnlySections` (excluded from public release notes but still written to `CHANGELOG.md`) are derived from the `internal` and `process` tiers (excluding `fmt`). Override via `changelogJson.devOnlySections` in your config; matching is decorator-tolerant, so a bare-name override like `['Internal features']` keeps working against the emoji-prefixed and prefix-decorated default titles.
+
+## Editorial overrides
+
+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.                                                                             |
+
+### 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 a warning is logged. 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`       |
+
+Exit code semantics:
+
+- `0` — clean (no errors, no stale keys).
+- `1` — only stale-key warnings.
+- `2` — schema/parse or ambiguous-prefix errors (errors dominate when both classes are present).
+
+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.
+
+### Rendering pipeline change
+
+Prior versions of release-kit shelled out to `git-cliff` for both structured `--context` JSON and rendered Markdown (cliff's body template). After this change, `git-cliff` is invoked only for `--context` JSON; release-kit's in-process `renderChangelogMarkdown` produces `CHANGELOG.md` from the same `ChangelogEntry[]` that drives `.meta/changelog.json`. The two artifacts can no longer disagree.
+
+The bundled `cliff.toml.template`'s body template has been emptied (the `[git].commit_parsers` section is still load-bearing for `--context` group assignment); custom `.config/git-cliff.toml` files no longer need a body template.
+
+Observable output differences from the prior cliff-rendered format:
+
+- Trailers (`Signed-off-by:`, `Co-authored-by:`, `Closes #N`, GitHub PR URLs) are stripped from rendered bodies.
+- Items whose commit subject carries the `!` breaking marker render with a `🚨 **Breaking:** ` prefix.
+- Empty version entries (releases with no commits routed to a section) are omitted; the prior cliff template rendered them as bare headings.
+- The footer comment is now `<!-- Generated by release-kit. Do not edit this file. Use .meta/changelog-overrides.json to override entries. -->`.
+
+The first release that ships under the new renderer will produce a one-time noisy diff in `CHANGELOG.md` (whitespace, trailers, breaking markers). Subsequent releases stabilize.
 
 ## CLI reference
 
@@ -524,6 +702,18 @@ The check is non-blocking initially: until codeassembly publishes its `work-type
 
 These commands are also exposed as `nmr work-types:check` / `nmr work-types:sync` from any package directory.
 
+#### Authenticated fetches
+
+When the upstream codeassembly repo is private, both `check` and `sync` need a GitHub token to fetch the canonical `work-types.json`. Set `GITHUB_TOKEN` in the environment and the commands send `Authorization: Bearer <token>` automatically; without it, requests are unauthenticated and a private upstream will return 404.
+
+```sh
+# Source from `gh auth` for local runs:
+export GITHUB_TOKEN=$(gh auth token)
+pnpm exec release-kit work-types check
+```
+
+The token needs `contents: read` on the codeassembly repo (fine-grained PAT scope) or the equivalent classic-PAT scope. A token without sufficient scope still produces a 404 — same response as a missing upstream — so a misconfigured token degrades to the transitional-warning path rather than failing loudly. CI wiring against private upstream is deferred until either codeassembly is publicly readable or a cross-repo PAT is provisioned as a workflow secret.
+
 ### `release-kit sync-labels`
 
 Manage GitHub label definitions via config-driven YAML files.
@@ -595,9 +785,11 @@ 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 into changelog sections
+- 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 [Editorial overrides](#editorial-overrides) 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`.
+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.
 
 ## External dependencies