@williamthorsen/release-kit 5.2.0 → 5.3.0

package/README.md

@@ -2,42 +2,44 @@
 
 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.0 (2026-05-04)
+## Release notes — v5.3.0 (2026-05-10)
 
 ### 🎉 Features
 
-- Add emojis to changelog and release-note headings (#352)
+- Enable editorial overrides for changelog entries (#387)
 
-  Adds emoji prefixes to the section headings rendered in `CHANGELOG.md` and release notes generated by `@williamthorsen/release-kit`. Each of the 13 default work types gets a single decorative emoji so its section is easier to spot when skimming a release: 🐛 Bug fixes, 🎉 Features, 📚 Documentation, ♻️ Refactoring, ⚡ Performance, 🔒 Security, 🧪 Tests, ⚙️ Tooling, 👷 CI, 📦 Dependencies, 🏗️ Internal, 🗑️ Deprecated, and 🤖 Agentic support. Matching of `changelogJson.devOnlySections` is emoji-tolerant: existing consumer overrides written as bare names continue to work without modification.
+  Allows `release-kit` consumers to skip or correct historical changelog entries by means of an overrides file.
 
-- Surface bang violations in release prepare reports (#359)
+- Decentralize changelog overrides to per-scope .meta/ files (#391)
 
-  Release-prepare flows now surface `!`-policy violations as warnings in the prepare report. Each workspace's and project's commit window is parsed against the default policy table — `internal!` is rejected as contradictory, bare `drop:` is rejected for missing the required `!`, and so on — and any violations appear under the workspace's section in the report alongside short hash, truncated subject, type, and surface (prefix or body). A new `breakingPolicies` config field lets consumers override individual entries or pass `{}` to disable enforcement entirely. Release-time enforcement remains tolerant: violations are warnings, never failures, so a single legacy commit cannot block a release.
+  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.
 
-### 🐛 Bug fixes
+- 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.
 
-- Restrict publish to publishable workspaces (#345)
+  `work-types check` and `work-types sync` now authenticate when `GITHUB_TOKEN` is set, so they can reach private upstream repositories.
 
-  Fixes an issue where `release-kit publish` failed for workspaces marked `package.json#private: true`. The command now operates only on publishable workspaces — those where `private` is absent or `false` — and the rest of the release pipeline (`tag`, `create-github-release`, `prepare`, changelog) continues to handle private workspaces unchanged. This preserves the "versioned but not published" workflow: a private workspace can still be versioned, tagged, and published as a GitHub Release; only the registry-publish step is skipped. Without `--tags`, unpublishable tags are silently filtered (an empty result prints `Nothing to publish.` and exits 0). With `--tags` naming an unpublishable workspace, `release-kit publish` exits 1 with one error per offending tag, citing `package.json#private` and the workspace path.
+- Validate changelog overrides from the command line (#395)
 
-- Skip tooling-only releases instead of failing (#347)
+  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.
 
-  Fixes an issue where `release-kit create-github-release --tags <tag>` exited 1 whenever the tag's changelog had no all-audience content. The reusable `create-github-release.reusable.yaml` workflow forwards `github.ref_name` into `--tags`, so tooling-only releases consistently produced failed workflow runs even though no failure occurred. The command now exits 1 only when a requested tag has no changelog entry; intentional skip reasons (`no-audience-content`, `empty-body`) are informational. A typoed tag still surfaces an error even when batched alongside successful tags, and the info summary reports the per-tag skip reason for diagnostic visibility.
+### 🐛 Bug fixes
 
-- Establish canonical work-types SSOT and restore changelog section ordering (#358)
+- Suppress git-cliff stale-version warnings on prepare (#373)
 
-  Restores canonical section ordering in changelogs and release notes — sections were appearing in unpredictable order after the previous release added emoji prefixes to section headers. Sections now follow a stable priority: public-facing types (Features, Fixes, Security, …) first, then internal types, then process types. Release-note bullets for breaking changes carry a `🚨 **Breaking:**` prefix so they stand out at a glance. Documentation entries move out of public release notes — they continue to appear in dev changelogs.
+  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.
 
-  Closes #355.
+- Use synthetic changelogs for forced empty-range releases (#376)
 
-### ⚡ Performance
+  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.
 
-- Skip npx registry revalidation when running git-cliff (#361)
+- Accept `breakingPolicies` field in config files (#394)
 
-  Speeds up `release-kit prepare` by skipping the npm registry cache-revalidation HTTP request that ran on every `git-cliff` invocation. Per-invocation overhead drops from ~4.6 s to ~2.0 s; in a four-workspace monorepo this saves about 10 seconds per run. Also suppresses a transient stderr spinner that briefly appeared during package resolution and looked like a half-complete log message. Network fallback is preserved — runs on machines with an empty npx cache still resolve `git-cliff` over the network.
+  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.
 <!-- /section:release-notes -->
 
 ## Installation
@@ -68,7 +70,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 ─────────────────────────────────────
@@ -78,7 +80,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.
@@ -93,7 +95,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
@@ -236,7 +238,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.
@@ -310,33 +312,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
 
@@ -382,6 +384,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.
@@ -390,7 +408,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 fast 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
 
@@ -550,6 +730,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.
@@ -621,9 +813,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
 

package/cliff.toml.template

@@ -18,45 +18,10 @@
 # unique group (not per parser entry) — all parsers routing to the same group
 # share the same prefix.
 
-[changelog]
-header = """
-# Changelog
-
-All notable changes to this project will be documented in this file."""
-# Render each commit as a bullet with the description (stripped of ticket ID
-# and scope|type prefix). If the commit has a body, render it as indented
-# continuation paragraphs under the bullet.
-body = """{%- if version %}
-## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
-{%- else %}
-## [unreleased]
-{%- endif -%}
-{%- set non_merge = commits | filter(attribute="merge_commit", value=false) -%}
-{%- for group, group_commits in non_merge | group_by(attribute="group") %}
-
-### {{ group | striptags | trim | upper_first }}
-
-{% for commit in group_commits -%}
-{%- set subject = commit.message | split(pat="\n") | first -%}
-{%- set desc = subject | split(pat=": ") | slice(start=1) | join(sep=": ") -%}
-{%- set body_lines = commit.message | split(pat="\n") | slice(start=2) -%}
-{%- set body_text = body_lines | join(sep="\n") | trim -%}
-{%- if not loop.first %}
-
-{% endif -%}
-- {{ desc | upper_first }}
-{%- if body_text %}
-
-  {{ body_text | split(pat="\n") | join(sep="\n  ") }}
-{%- endif -%}
-{%- endfor -%}
-{%- endfor %}
-"""
-footer = """
-
-<!-- generated by git-cliff -->
-"""
-trim = false
+# Markdown rendering is handled in-process by `renderChangelogMarkdown.ts`. cliff is invoked
+# only for `--context` JSON output (see `buildChangelogEntries.ts`), so no `[changelog]` block
+# is needed. The `[git].commit_parsers` section below remains load-bearing for group
+# assignment in the `--context` payload.
 
 [git]
 conventional_commits = false

package/dist/esm/.cache

@@ -1 +1 @@
-64d26b06f4a6e205faa07a507fd64938899e4d635dd02b333016caf1d937a14e
+18bd566d86a692ebdc23649a475e7d5e01562a58df99b6091e222e890cef8f80

package/dist/esm/bin/release-kit.js

@@ -13,6 +13,7 @@ import { syncLabelsInitCommand } from "../sync-labels/initCommand.js";
 import { syncLabelsCommand } from "../sync-labels/syncCommand.js";
 import { syncWorkTypes } from "../syncWorkTypes.js";
 import { tagCommand } from "../tagCommand.js";
+import { validateOverridesCommand } from "../validateOverridesCommand.js";
 const VERSION = readPackageVersion(import.meta.url);
 function showUsage() {
   console.info(`
@@ -27,6 +28,7 @@ Commands:
   create-github-release  Create GitHub Releases from changelog.json for tags on HEAD
   show-tag-prefixes  Show derived and declared legacy tag prefixes per workspace
   init             Initialize release-kit in the current repository
+  overrides        Manage editorial changelog overrides
   sync-labels      Manage GitHub label synchronization
   work-types       Check for or sync work-type taxonomy drift against the upstream canonical
 
@@ -174,6 +176,35 @@ legacy tag prefixes. Surfaces any release-shaped tags whose prefix is neither a
 derived prefix nor declared in \`legacyIdentities\`, with a copy-pasteable
 config snippet.
 
+Options:
+  --help, -h    Show this help message
+`);
+}
+function showOverridesHelp() {
+  console.info(`
+Usage: release-kit overrides <subcommand> [options]
+
+Manage editorial changelog overrides.
+
+Subcommands:
+  validate      Validate every \`.meta/changelog-overrides.json\` file across all scopes
+
+Options:
+  --help, -h    Show this help message
+`);
+}
+function showOverridesValidateHelp() {
+  console.info(`
+Usage: release-kit overrides validate
+
+Validate every \`.meta/changelog-overrides.json\` file across the project and per-workspace
+scopes. Reports schema/parse errors, ambiguous-prefix errors, and stale-key warnings.
+
+Exit codes:
+  0    Clean \u2014 no errors, no stale keys
+  1    Stale-key warnings only (no errors)
+  2    Schema/parse or ambiguous-prefix errors (errors dominate)
+
 Options:
   --help, -h    Show this help message
 `);
@@ -389,6 +420,34 @@ if (command === "sync-labels") {
   showSyncLabelsHelp();
   process.exit(1);
 }
+if (command === "overrides") {
+  const subcommand = flags[0];
+  const subflags = flags.slice(1);
+  if (subcommand === "--help" || subcommand === "-h" || subcommand === void 0) {
+    showOverridesHelp();
+    process.exit(0);
+  }
+  if (subcommand === "validate") {
+    if (subflags.some((f) => f === "--help" || f === "-h")) {
+      showOverridesValidateHelp();
+      process.exit(0);
+    }
+    if (subflags.length > 0) {
+      console.error(`Error: Unknown option: ${subflags[0]}`);
+      process.exit(1);
+    }
+    const result = await validateOverridesCommand();
+    if (result.exitCode === 0) {
+      console.info(result.message);
+    } else {
+      console.error(result.message);
+    }
+    process.exit(result.exitCode);
+  }
+  console.error(`Error: Unknown subcommand: ${subcommand}`);
+  showOverridesHelp();
+  process.exit(1);
+}
 if (command === "work-types") {
   const subcommand = flags[0];
   const subflags = flags.slice(1);

package/dist/esm/buildChangelogEntries.js

@@ -69,6 +69,9 @@ function toCliffContextCommit(value) {
   if (typeof value.group === "string") {
     commit.group = value.group;
   }
+  if (typeof value.id === "string") {
+    commit.id = value.id;
+  }
   return commit;
 }
 function transformReleases(releases, devOnlySections) {
@@ -98,6 +101,9 @@ function transformReleases(releases, devOnlySections) {
       if (breaking) {
         item.breaking = true;
       }
+      if (commit.id !== void 0 && commit.id !== "") {
+        item.hash = commit.id;
+      }
       items.push(item);
     }
     const sections = [];

package/dist/esm/buildEmptyReleaseEntry.d.ts

@@ -0,0 +1,2 @@
+import type { ChangelogEntry } from './types.ts';
+export declare function buildEmptyReleaseEntry(version: string, date: string): ChangelogEntry;

package/dist/esm/buildEmptyReleaseEntry.js

@@ -0,0 +1,16 @@
+function buildEmptyReleaseEntry(version, date) {
+  return {
+    version,
+    date,
+    sections: [
+      {
+        title: "Notes",
+        audience: "dev",
+        items: [{ description: "Forced version bump." }]
+      }
+    ]
+  };
+}
+export {
+  buildEmptyReleaseEntry
+};

package/dist/esm/changelogJsonFile.d.ts

@@ -2,3 +2,5 @@ import type { ChangelogEntry, ReleaseConfig } from './types.ts';
 export declare function resolveChangelogJsonPath(config: Pick<ReleaseConfig, 'changelogJson'>, changelogPath: string): string;
 export declare function writeChangelogJson(filePath: string, entries: ChangelogEntry[]): string;
 export declare function upsertChangelogJson(filePath: string, entries: ChangelogEntry[]): string;
+export declare function upsertChangelogJsonAndReturn(filePath: string, entries: ChangelogEntry[]): ChangelogEntry[];
+export declare function mergeChangelogEntriesWithDisk(filePath: string, entries: ChangelogEntry[]): ChangelogEntry[];

package/dist/esm/changelogJsonFile.js

@@ -14,11 +14,19 @@ function writeChangelogJson(filePath, entries) {
   return filePath;
 }
 function upsertChangelogJson(filePath, entries) {
+  upsertChangelogJsonAndReturn(filePath, entries);
+  return filePath;
+}
+function upsertChangelogJsonAndReturn(filePath, entries) {
   const existing = readExistingEntries(filePath);
   const merged = mergeEntries(entries, existing);
   mkdirSync(dirname(filePath), { recursive: true });
   writeFileSync(filePath, stringify(merged, { maxLength: 100 }) + "\n", "utf8");
-  return filePath;
+  return merged;
+}
+function mergeChangelogEntriesWithDisk(filePath, entries) {
+  const existing = readExistingEntries(filePath);
+  return mergeEntries(entries, existing);
 }
 function sortNewestFirst(entries) {
   return [...entries].sort((a, b) => compareVersionsDescending(a.version, b.version));
@@ -62,7 +70,9 @@ function compareVersionsDescending(a, b) {
   return 0;
 }
 export {
+  mergeChangelogEntriesWithDisk,
   resolveChangelogJsonPath,
   upsertChangelogJson,
+  upsertChangelogJsonAndReturn,
   writeChangelogJson
 };

package/dist/esm/changelogJsonUtils.d.ts

@@ -1,4 +1,5 @@
-import type { ChangelogEntry } from './types.ts';
+import type { ChangelogEntry, ChangelogItem } from './types.ts';
+export declare function isChangelogItem(value: unknown): value is ChangelogItem;
 export declare function isChangelogEntry(value: unknown): value is ChangelogEntry;
 export declare function extractVersion(tag: string): string;
 export declare function readChangelogEntries(filePath: string): ChangelogEntry[] | undefined;