@williamthorsen/release-kit 11.0.0 → 13.0.0

package/docs/editorial-overrides.md

@@ -1,10 +1,10 @@
 # Editorial overrides
 
-How to correct a generated changelog entry without rewriting history: where override files live, how they compose, what an entry may set, and how to validate the files.
+How to correct a generated changelog entry without rewriting history: where override files live, how they compose, how a key targets items, what an entry may set, and how to validate the files.
 
-Generated changelogs occasionally need editorial correction — typos, redacted scope, reworded entries, or historical commits whose bodies carry verbatim PR-template scaffolding (`## What`, `## Why`, etc.) that renders as literal text in user-facing release notes. Rewriting git history is not viable, and any in-place edit to `CHANGELOG.md` or `.meta/changelog.json` is overwritten on the next release because release-kit regenerates both artifacts from scratch.
+Generated changelogs occasionally need editorial correction: typos, redacted scope, reworded entries, or historical commits whose bodies contain 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 a version that release-kit renders in `CHANGELOG.md` or `.meta/changelog.json` is overwritten on the next release, because release-kit regenerates that version in both artifacts from its entries.
 
-Override files are the supported escape hatch. Drop a checked-in JSON file at the conventional path for the scope you want to influence, keyed by commit hash, and `release-kit prepare` applies the overrides between `buildChangelogEntries` and serialization. Both `CHANGELOG.md` and `.meta/changelog.json` reflect the post-override view, so downstream consumers (the GitHub Release body, the in-app release-notes page, etc.) see the same content.
+Override files are the supported escape hatch. Add a checked-in JSON file at the conventional path for the scope that it should affect, keyed by commit hash or by commit hash and entry position, and `release-kit prepare` applies the overrides between `buildChangelogEntries` and serialization. Both `CHANGELOG.md` and `.meta/changelog.json` reflect the post-override view, so downstream consumers (the GitHub Release body, the in-app release-notes page, etc.) see the same content.
 
 ## File-location convention
 
@@ -14,7 +14,7 @@ Override files are the supported escape hatch. Drop a checked-in JSON file at th
 | 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`).
+Filenames don't have a leading dot, because the `.meta/` directory already provides the visibility property and parallels its sibling artifacts (`changelog.json`, `label-map.json`).
 
 ## Composition: per-key shadowing
 
@@ -22,26 +22,30 @@ When a workspace's changelog is rendered, both files are consulted:
 
 - The root file's overrides apply globally.
 - The workspace file's overrides apply only to that workspace.
-- When the **same hash key** (string-equal, byte-for-byte) appears in both files, the **workspace entry wins entirely** for that workspace's changelog — no field-level merge, the workspace entry replaces the root entry.
-- Different prefix strings that happen to resolve to the same commit do **not** shadow; they fall through to the existing ambiguous-prefix error so you can correct your override file.
+- When the **same key** (string-equal, byte-for-byte) appears in both files, the **workspace entry wins entirely** for that workspace's changelog: release-kit doesn't merge the two entries field by field; the workspace entry replaces the root entry.
+- Non-identical keys that match the same item, such as a root `abc1234` beside a workspace `abc1234:2`, or two prefixes of one commit, do **not** shadow. The run fails with the [overlapping-keys error](#conflicting-keys), which names both keys.
 - Other keys in the root file still apply for that workspace.
 
-The project-level changelog applies only the root file. Per-workspace files describe per-workspace editorial intent and have no meaning at the aggregated project tier.
+The project-level changelog applies only the root file. Per-workspace files describe per-workspace editorial intent and don't have any 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.
+- **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
 {
+  "$schema": "https://github.com/williamthorsen/node-monorepo-tools/raw/release-kit-v<version>/packages/release-kit/schemas/changelog-overrides.json",
   "82962311": {
     "audience": "skip"
   },
+  "3f0c9a1:2": {
+    "description": "Reworded headline for the second change-record entry"
+  },
   "abc1234d": {
     "body": "Cleaned-up prose without the original PR-template scaffolding."
   },
@@ -52,7 +56,7 @@ A key that doesn't match any commit gets a stale-reference warning. The warning'
 }
 ```
 
-Per-entry fields are all optional, but at least one must be present per entry:
+The top-level `$schema` key is optional and names the [published JSON Schema](#published-json-schema) for editor support; it is not an override. Per-entry fields are all optional, but at least one must be present per entry:
 
 | Field         | Type                       | Effect                                                                                                                            |
 | ------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
@@ -61,29 +65,62 @@ Per-entry fields are all optional, but at least one must be present per entry:
 | `body`        | `string`                   | Replaces the entry's body (the prose that renders below the bullet). Other fields are preserved.                                  |
 | `breaking`    | `boolean`                  | Toggles the `🚨 **Breaking:** ` marker on the bullet.                                                                             |
 
-There is no `migration` key: the field is derived from `body`, so an override that replaces `body` re-derives it. See [The `migration` field](changelogs.md#the-migration-field).
+An override entry doesn't take a `migration` key: On a title-derived item the field is derived from `body`, so an override that replaces `body` re-derives it, and an item derived from a change-record entry keeps its entry's `migration`. See [The `migration` field](changelogs.md#the-migration-field).
+
+## Keys
+
+A key takes one of two forms. In both, the hash part is lowercase hex and matches as a prefix of the commit hash.
+
+| Key          | Targets                                                          |
+| ------------ | ---------------------------------------------------------------- |
+| `<hash>`     | Every item of the commit                                         |
+| `<hash>:<n>` | The one item derived from the commit's `n`th change-record entry |
+
+`n` counts from 1 over the `entries` of the commit's [change-record block](changelogs.md#change-record-blocks), in the order in which the PR lists them, including entries that don't yield an item. An item derived from the commit's title doesn't have an entry position, so `<hash>:<n>` never matches it. Any other key fails loading.
+
+The hash part can be the full 40-character SHA or a prefix. `prepare` resolves it against the distinct commit hashes in the changelog:
+
+- **One commit**: The override applies to the items that the key targets. A 7-character prefix is usually unambiguous within a single repo's history; longer prefixes are always safe.
+- **No commit**: The override is treated as a stale reference (probably from a rebase or branch deletion) and prepare reports a warning. The release continues. An ordinal key whose commit doesn't have an item at position `n` is stale in the same way.
+- **Several commits**: The release aborts with an error naming the key and the matching hashes. Lengthen the prefix or use the full SHA.
+
+### Conflicting keys
 
-## Hash-prefix matching
+Two further conditions abort the release. Each counts the items within one changelog.
 
-Keys can be either the full 40-character commit SHA or a non-ambiguous prefix. The matcher walks every `ChangelogItem.hash` value present in the entry tree and resolves each override key to its set of matching hashes:
+- **A bare key that sets `description` or `body` on a commit with several items.** One headline or body cannot replace several different ones, so the error names the ordinal keys to use instead: `Override key 'abc1234' sets description on a commit with several items; use abc1234:1, abc1234:2`. `audience` and `breaking` on a bare key still apply to every item.
+- **Two non-identical keys that match the same item.** The error names both keys, such as `Override keys 'abc1234' and 'abc1234:2' both match the item at abc1234:2; keep one`. Neither override applies to the item.
+
+### Example: one commit, several items
+
+Suppose commit `3f0c9a1` merged a PR whose change record lists three entries. Its changelog contains three items, and each key below targets one of them:
+
+```json
+{
+  "3f0c9a1:2": { "description": "Reworded headline for the second entry" },
+  "3f0c9a1:3": { "audience": "skip" }
+}
+```
 
-- **Exact prefix match (1 hit)** — the override applies. A 7-character prefix is usually unambiguous within a single repo's history; longer prefixes are always safe.
-- **No matches (0 hits)** — the override is treated as a stale reference (probably from a rebase or branch deletion) and prepare reports a warning. The release continues.
-- **Ambiguous prefix (2+ hits)** — the release aborts with an error naming the key and the matching hashes. Lengthen the prefix or use the full SHA.
+A bare `"3f0c9a1": { "audience": "skip" }` would skip all three items instead. Adding it beside the keys above fails the run, because it overlaps each of them.
 
-Override application errors abort the run with a non-zero exit; warnings (zero-match keys) are non-fatal and surface on `PrepareResult.warnings`.
+Override application errors abort the run with a non-zero exit; warnings (zero-match keys) are non-fatal and appear in `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:
+The override file is validated when `release-kit prepare` loads it. Each error names the offending key so that the developer can locate it in the file:
 
-- Missing file → empty map, no error (the no-op default — projects that do not need overrides skip the file entirely).
+- Missing file → empty map, no error (the no-op default: Projects that do not need overrides skip the file entirely).
 - Malformed JSON → error.
+- A key that is neither `<hash>` nor `<hash>:<n>` (uppercase hex, non-hex characters, `:0`, a leading zero in `n`) → error.
+- A top-level `$schema` that is not a string → error.
 - Wrong top-level shape (e.g., array, primitive) → error.
 - Unknown fields on an entry → error.
 - Wrong field types (e.g., `description` as a number) → error.
 - An entry with no fields set → error (a copy-paste mistake more often than not).
-- `audience: 'all'` or `audience: 'dev'` → error in the current release: only `'skip'` is supported (see below).
+- `audience: 'all'` or `audience: 'dev'` → error in the current release: Only `'skip'` is supported (see below).
+
+Applying the overrides then aborts the run on an ambiguous prefix and on either of the [conflicting-key conditions](#conflicting-keys): a bare key setting `description` or `body` on a commit with several items, and two keys matching the same item.
 
 ### Standalone validation: `release-kit overrides validate`
 
@@ -95,25 +132,47 @@ pnpm exec release-kit overrides validate
 
 This walks every `.meta/changelog-overrides.json` file across the project tier and per-workspace tier, reporting three classes of finding:
 
-| Class               | Examples                                                                                    | Exit code |
-| ------------------- | ------------------------------------------------------------------------------------------- | --------- |
-| Schema/parse errors | malformed JSON, unknown fields, wrong field types, no-field entries, unsupported `audience` | `2`       |
-| Ambiguous-prefix    | an override key resolves to 2+ commit hashes                                                | `2`       |
-| Stale-key warnings  | an override key resolves to no commit in its applicable scope                               | `1`       |
+| Class               | Examples                                                                                                    | Exit code |
+| ------------------- | ----------------------------------------------------------------------------------------------------------- | --------- |
+| Schema/parse errors | malformed JSON, malformed keys, unknown fields, wrong field types, no-field entries, unsupported `audience` | `2`       |
+| Ambiguous-prefix    | an override key resolves to 2+ commit hashes                                                                | `2`       |
+| Conflicting keys    | a bare key sets `description` or `body` on a commit with several items; two keys match the same item        | `2`       |
+| Stale-key warnings  | an override key doesn't resolve to any item in its applicable scope                                         | `1`       |
+
+Tier-aware stale-key semantics match `release-kit prepare`'s match-set exactly: A workspace-tier key is stale if it does not match in its own workspace's history; a root-tier key is stale only if it doesn't match in **any** scope (neither any workspace nor the project release window).
 
-Tier-aware stale-key semantics match `release-kit prepare`'s match-set exactly: a workspace-tier key is stale if it does not match in its own workspace's history; a root-tier key is stale only if it matches in **no** scope (no workspace AND not the project release window).
+Conflicting keys are found within one file and across the root and workspace files, as `prepare` composes them. An overlap between a root key and a workspace key is reported against the workspace file.
 
 The same logic is also exposed programmatically via the `validateAllChangelogOverrides` function exported from `@williamthorsen/release-kit`, for callers that want to integrate the check into their own tooling.
 
+## Published JSON Schema
+
+release-kit publishes a JSON Schema for the override file. The schema lives at `packages/release-kit/schemas/changelog-overrides.json` in this repo and is reachable via the stable raw URL:
+
+```
+https://github.com/williamthorsen/node-monorepo-tools/raw/release-kit-v<version>/packages/release-kit/schemas/changelog-overrides.json
+```
+
+An override file references it from its top-level `$schema` key:
+
+```json
+{
+  "$schema": "https://github.com/williamthorsen/node-monorepo-tools/raw/release-kit-v<version>/packages/release-kit/schemas/changelog-overrides.json",
+  "82962311": { "audience": "skip" }
+}
+```
+
+The schema states the key form and the entry fields. It accepts `audience` values `'all'` and `'dev'`, which the file format declares; the loader still rejects them (see below).
+
 ## Audience semantics: v1 supports `'skip'` only
 
-The on-disk format declares the full `'all' | 'dev' | 'skip'` audience vocabulary so the file format will not need to change when the v2 reclassification feature ships. In the current release, only `'skip'` is supported at runtime; `'all'` and `'dev'` are rejected with an explicit "not yet supported" error.
+The on-disk format declares the full `'all' | 'dev' | 'skip'` audience vocabulary so that the file format will not need to change when the v2 reclassification feature is released. 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.
+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 that the override mechanism can be released now and the section-split logic can be added 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:
+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 the project's in-app release notes as literal Markdown headings. Add an override at the project tier:
 
 ```json
 // .meta/changelog-overrides.json
@@ -128,9 +187,9 @@ On the next `release-kit prepare` run, the matched item's body is replaced befor
 
 ## 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.
+Release-kit attributes commits to workspaces by file path, so a commit that primarily belongs to one workspace can appear 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 appears in `packages/nmr/CHANGELOG.md`, where it isn't the right editorial framing.
 
-Drop a workspace-tier override at `packages/nmr/.meta/changelog-overrides.json`:
+Add a workspace-tier override at `packages/nmr/.meta/changelog-overrides.json`:
 
 ```json
 // packages/nmr/.meta/changelog-overrides.json
@@ -141,4 +200,4 @@ Drop a workspace-tier override at `packages/nmr/.meta/changelog-overrides.json`:
 }
 ```
 
-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.
+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

@@ -1,16 +1,16 @@
 # 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`.
+How to declare the repository's labels in `.config/release-kit.config.ts`, how the scaffolded workflow applies them, and where the schema for `.meta/label-map.json` is published.
 
 ## `release-kit sync-labels`
 
-Manage GitHub label definitions via the `repoLabels` block of `.config/release-kit.config.ts`.
+Manages 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.
+`init` scaffolds the `.github/workflows/sync-labels.yaml` caller workflow and seeds a `repoLabels` block with scope labels discovered from workspaces and declared `retiredPackages`. When `.config/release-kit.config.ts` does not exist, `init` writes it; when it does, `init` prints the block for manual paste; a hand-authored config is never rewritten. `generate` resolves the block and writes `.github/labels.yaml`; with `--check` it regenerates in memory and exits non-zero if the committed file is stale or missing, writing nothing. `sync` triggers the workflow remotely; it requires the `gh` CLI and an existing workflow file.
 
 `init` and `generate` accept `--config <path>` to read a config elsewhere; `sync` reads none and rejects the flag. Under `--config`, `init` reads the named file and prints the block for manual paste, and fails when that file does not exist rather than scaffolding one, so its write target stays `.config/release-kit.config.ts`. See [Config file location](configuration.md#config-file-location).
 
-Every `sync-labels` subcommand refuses to run while the retired `.config/sync-labels.config.ts` is present, so custom labels cannot be silently dropped mid-migration, and the refusal names what to move and where.
+Every `sync-labels` subcommand refuses to run while the retired `.config/sync-labels.config.ts` is present, so that custom labels cannot be silently dropped mid-migration, and the refusal names what to move and where.
 
 ### Label configuration
 
@@ -29,20 +29,22 @@ export default defineConfig({
 });
 ```
 
-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:
+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.
+1. Presets, in `extends` order: A later preset wins on a shared name.
+2. The `labels` record: An entry adds a label, replaces one that an earlier layer defined, or removes it (`null`). Replacement is wholesale: An entry omitting `description` resolves to a label without a description rather than inheriting the one that an earlier layer supplied.
+
+The `common` preset defines a label for every work type in change-grammar's taxonomy, named by the type's `trackerLabel`, in addition to the labels in its bundled YAML file.
 
 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.
+Overlaps between layers are never errors; order resolves them, and the committed `.github/labels.yaml` diff shows any unexpected change at review. Two misstatements are config errors, because neither is visible in the output diff: a dangling `null`, which removes a name not defined by any preset, 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:
+The scaffolded workflow declares three triggers:
 
 | Trigger                                                   | Job     | Token           | Effect                            |
 | --------------------------------------------------------- | ------- | --------------- | --------------------------------- |
@@ -50,36 +52,36 @@ The scaffolded workflow carries three triggers:
 | 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.
+Applying on merge closes the window in which a regenerated `.github/labels.yaml` remains unapplied. In that window, a later manual dispatch would apply an unreviewed label set.
 
-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 `check` job runs the same sync in dry-run. Its **Label diff** log group lists every create, edit, rename, and deletion that the sync would perform, including deletions of labels that the file does not declare: the destructive edits that 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 two jobs are split because a job's permissions are fixed when the run is created and cannot vary by trigger. The split 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.
+The push trigger filters on the path alone; the `sync` job compares `github.ref_name` against the repository's default branch. The workflow therefore doesn't need a 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.
+GitHub issues a read-only `GITHUB_TOKEN` to pull requests from forks, and by default pauses runs from first-time contributors until a maintainer approves them. Because the dry-run reads labels and writes nothing, the check normally runs once approved. A repo that disables workflows on fork pull requests doesn't get a 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`
+### 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:
+`.meta/label-map.json` is a separate, generic data file that maps commit-prefix scopes and types to GitHub label names. `@williamthorsen/change-grammar` publishes its JSON Schema, 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
+https://github.com/williamthorsen/node-monorepo-tools/raw/change-grammar-v<version>/packages/change-grammar/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",
+  "$schema": "https://github.com/williamthorsen/node-monorepo-tools/raw/change-grammar-v<version>/packages/change-grammar/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.
+Earlier releases published the same schema from release-kit, and URLs under existing `release-kit-v*` tags keep resolving. release-kit does not generate `.meta/label-map.json`; change-grammar's `deriveLabelMap` derives one from the taxonomy and the workspace scopes.

package/docs/project-releases.md

@@ -2,7 +2,7 @@
 
 How to add a project-level release to a monorepo, what the `project` block accepts, and how that release interacts with `prepare`'s flags.
 
-Some monorepos ship a single combined deliverable — a Chrome extension, a CLI binary, a packaged desktop app — for which the per-workspace tags and changelogs alone do not describe what the user actually receives. Declare the optional `project` block to add a project-level release stage that runs alongside the per-workspace pipeline.
+Some monorepos release a single combined deliverable, such as a Chrome extension, a CLI binary, or a packaged desktop app, for which the per-workspace tags and changelogs alone do not describe what the user actually receives. Declare the optional `project` block to add a project-level release stage that runs alongside the per-workspace pipeline.
 
 ```typescript
 import type { ReleaseKitConfig } from '@williamthorsen/release-kit/config';
@@ -19,12 +19,12 @@ When configured, each `release-kit prepare` run additionally:
 
 - Computes commits since the last project tag (`<tagPrefix><version>`), filtered to `paths` (by default, the union of every contributing workspace's paths).
 - Bumps the root `package.json`'s `version` field using the same bump-derivation rules as workspaces (or the `--bump=...` override).
-- Regenerates the root `./CHANGELOG.md` from the structured `ChangelogEntry[]` produced by `git-cliff --context` (scoped to the project's `tagPrefix` and the same `paths`) and any matching editorial overrides.
+- Regenerates the root `./CHANGELOG.md` from the structured `ChangelogEntry[]` built from the project's release history (scoped to the project's `tagPrefix` and the same `paths`) and any matching editorial overrides, keeping the [existing sections](changelogs.md#existing-changelogmd-sections) whose versions those entries lack.
 - 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.
+- Appends the project tag to `tmp/.release-tags` so that `release-kit commit` and `release-kit tag` pick it up alongside per-workspace tags.
 
-If no commit under `paths` has landed since the last project tag, the project release is silently skipped — same behavior as a per-workspace skip.
+If the history since the last project tag doesn't contain any commit under `paths`, the project release is silently skipped, as a per-workspace release is.
 
 ## `ProjectConfig`
 
@@ -37,14 +37,14 @@ interface ProjectConfig {
 
 | Field       | Default                 | Description                                                          |
 | ----------- | ----------------------- | -------------------------------------------------------------------- |
-| `paths`     | Contributing-path union | Patterns selecting the commits the project release considers         |
+| `paths`     | Contributing-path union | Patterns selecting the commits that the project release considers    |
 | `tagPrefix` | `'v'`                   | Prefix for project tags. The full tag is `${tagPrefix}${newVersion}` |
 
-By default the contributing workspaces are implicit: every non-excluded discovered workspace contributes its `<dir>/**` glob, and the project release considers commits under their union.
+By default the contributing workspaces are implicit: Every non-excluded discovered workspace contributes its `<dir>/**` glob, and the project release considers commits under their union.
 
-Declare `paths` to choose the window yourself. Each entry reaches two matchers: `git log` as a pathspec, and `git-cliff --include-path` as a glob. A declared value **replaces** the workspace union rather than extending it: `paths: ['docs/**']` drops every workspace commit from the project release.
+Declare `paths` to choose the window explicitly. Each entry is a git pathspec, which both the bump and the changelog read. A declared value **replaces** the workspace union rather than extending it: `paths: ['docs/**']` drops every workspace commit from the project release.
 
-A repo whose content lives at the root — where no commit matches any `<dir>/**` glob, so the project release would skip every run — declares the whole tree:
+In a repo whose content lives at the root, commits don't match any `<dir>/**` glob, so the project release would skip every run. Such a repo declares the whole tree:
 
 ```typescript
 const config: ReleaseKitConfig = {
@@ -54,21 +54,21 @@ const config: ReleaseKitConfig = {
 
 `'**'` is the whole-tree pattern, matching root-level files, dotfiles, and nested paths alike.
 
-Terminate a directory scope with `/**`. The two matchers agree on `'aws/**'` but diverge on a bare `'aws'`, which git reads as the whole subtree and git-cliff matches against nothing; `'.'` is the same trap for the repo root. A release under such an entry finds commits, bumps the version, and writes the tag, while its changelog gains no entry for them — and nothing reports an error.
+A bare directory such as `'aws'` selects its whole subtree, as `'aws/**'` does.
 
 Validation rules:
 
 - The root `package.json` must exist and declare a `version` field. release-kit reports an error at config-load time if either is missing.
 - The `project` block is rejected in single-package mode (the package's own release already covers the whole repo, so a project tier would only duplicate it).
-- `paths`, when declared, must hold at least one non-empty string. An empty array is rejected: it reaches git and git-cliff as no filter at all, which is the inverse of how it reads.
+- `paths`, when declared, must contain at least one non-empty string. An empty array is rejected, because git would read it as the absence of a filter: the inverse of how the array reads.
 - Unknown fields inside `project` are rejected.
 
 CLI flag interactions:
 
-- `--dry-run` previews project artifacts alongside workspace artifacts; no files are written.
-- `--bump=major|minor|patch` propagates to the project release as a level chooser. It does not trigger a release on its own when there are no commits or no bump-worthy commits.
-- `--force` runs the project release even when no commits or no bump-worthy commits exist since the last project tag. Defaults to patch when `--bump` is not given; combine with `--bump=X` to release at a different level.
-- `--only` narrows the run to the named workspaces and skips the project release, which is reported as a warning. The project release rolls up every contributing workspace, and `--only` changes which workspaces those are, so rolling up a narrowed set would release a project version covering work the run excluded. Run a full `prepare` (no `--only`) to include the project release.
+- `--dry-run` previews project artifacts alongside workspace artifacts; it doesn't write any files.
+- `--bump=major|minor|patch` propagates to the project release as a level chooser. It does not trigger a release on its own when the window doesn't have any commits or any bump-worthy commits.
+- `--force` runs the project release even when the history since the last project tag doesn't have any commits or any bump-worthy commits. Defaults to patch when `--bump` is not given; combine with `--bump=X` to release at a different level.
+- `--only` narrows the run to the named workspaces and skips the project release, which is reported as a warning. The project release rolls up every contributing workspace, and `--only` changes which workspaces those are, so rolling up a narrowed set would release a project version covering work that the run excluded. Run a full `prepare` (without `--only`) to include the project release.
 - `--set-version` is rejected with an error when `project` is configured. `--set-version` operates on a single workspace, but a project release rolls up every contributing workspace; the two semantics don't compose. To use `--set-version`, run on a config without a `project` block.
 
 How `--bump` and `--force` combine for every target is in [Releasing](releasing.md#release-kit-prepare).

package/docs/publishing.md

@@ -4,16 +4,16 @@ How `release-kit publish` and `release-kit create-github-release` choose which p
 
 ## `release-kit publish`
 
-Publish packages that have release tags on HEAD. The publish workflow's reusable workflow `publish.reusable.yaml` invokes this command in CI.
+Publishes packages that have release tags on HEAD. The publish workflow's reusable workflow `publish.reusable.yaml` invokes this command in CI.
 
 ### Publishability filter
 
-`publish` and `create-github-release` operate only on workspaces where `package.json#private` is absent or `false`. A workspace marked `private: true` is "versioned but not published": it can still be tagged by `release-kit tag` and get a `CHANGELOG.md` entry, but it is skipped by both `release-kit publish` (no registry publish) and `release-kit create-github-release` (no GitHub Release). `private: true` alone routes a workspace out of publish and announce — no extra release config is required. Other commands ignore this filter and operate on private workspaces unchanged.
+`publish` and `create-github-release` operate only on workspaces whose `package.json#private` is absent or `false`. A workspace marked `private: true` is "versioned but not published": It can still be tagged by `release-kit tag` and get a `CHANGELOG.md` entry, but it is skipped by both `release-kit publish` (no registry publish) and `release-kit create-github-release` (no GitHub Release). `private: true` alone excludes a workspace from publish and announce; it doesn't require any extra release config. Other commands ignore this filter and operate on private workspaces unchanged.
 
 An unpublishable tag is always skipped cleanly, never fatal. For `release-kit publish`, whether the skip is announced depends on how the tag was resolved:
 
-- **Without `--tags`** (implicit resolution): unpublishable tags on HEAD are silently filtered. The pre-publish listing shows only the publishable subset. If the filter empties the set, `release-kit publish` prints `Nothing to publish.` and exits 0.
-- **With `--tags`** (explicit naming): each named tag pointing at an unpublishable workspace is skipped with a warning, and any publishable tags named in the same command still publish.
+- **Without `--tags`** (implicit resolution): Unpublishable tags on HEAD are silently filtered. The pre-publish listing shows only the publishable subset. If the filter empties the set, `release-kit publish` prints `Nothing to publish.` and exits 0.
+- **With `--tags`** (explicit naming): Each named tag pointing at an unpublishable workspace is skipped with a warning, and any publishable tags named in the same command are still published.
 
 `release-kit create-github-release` skips unpublishable workspaces with a warning regardless of `--tags`; an all-private tag set is a clean no-op.
 
@@ -25,6 +25,6 @@ Skipping basic-v1.0.0 (packages/basic): package.json#private is true.
 
 ## `release-kit create-github-release`
 
-Create GitHub Releases from `changelog.json` for tags on HEAD. Independent of `npm publish`: invoking this command creates Releases for publishable packages whether or not they were published to a registry. Private workspaces are skipped (see [Publishability filter](#publishability-filter)).
+Creates GitHub Releases from `changelog.json` for tags on HEAD. Independent of `npm publish`: Invoking this command creates Releases for publishable packages whether or not they were published to a registry. Private workspaces are skipped (see [Publishability filter](#publishability-filter)).
 
 When `--tags` is omitted, every release tag pointing at HEAD is processed. The CLI requires the `gh` CLI on `PATH` and `contents: write` permission. The bundled `create-github-release.reusable.yaml` GitHub Actions workflow runs this command in CI.

package/docs/readiness-checks.md

@@ -2,7 +2,7 @@
 
 What release-kit's two readyup kits check, how to run each, and what `npm-auto-publish` needs from the npm session.
 
-release-kit publishes two [readyup](https://www.npmjs.com/package/readyup) kits that check a consuming repo against the release it has installed: the `default` kit covers release-kit's own setup — workflows matching the current templates, config free of removed fields, sync-labels wiring — and `npm-auto-publish` covers a repo's OIDC-based npm publishing setup. Both ship inside the package, so they check against the version you installed rather than whatever a repository ref happens to point at, and a check added in a release reaches your repo on upgrade.
+release-kit publishes two [readyup](https://www.npmjs.com/package/readyup) kits that check a consuming repo against the release that it has installed: The `default` kit covers release-kit's own setup (workflows matching the current templates, config free of removed fields, sync-labels wiring), and `npm-auto-publish` covers a repo's OIDC-based npm publishing setup. Both are included in the package, so they check against the installed version rather than whatever a repository ref happens to point at, and a check added in a release becomes available to a repo when it upgrades.
 
 The [README](../README.md#readiness-checks) shows how to name release-kit in the readyup config.
 
@@ -13,6 +13,6 @@ rdy run --from npm:@williamthorsen/release-kit npm-auto-publish  # the npm-auto-
 rdy list --from npm:@williamthorsen/release-kit                  # what release-kit publishes
 ```
 
-`--packages` is the form that survives release-kit publishing further kits.
+`--packages` is the form that keeps working when release-kit publishes further kits.
 
-`npm-auto-publish` queries the npm registry for each package's trusted publisher, so it needs an npm session elevated by two-factor authentication, and is meant to be invoked deliberately rather than swept up by an unattended run. A session that cannot answer those queries, whether it is missing a login, missing the elevation, or facing an unreachable registry, is reported once by the `npm session can answer trust queries` gate. The rows that would repeat the failed query then stand down: the trusted-publisher rows in every case, and `published to npm` where the registry itself is unreachable. Each package's `package.json` checks report throughout, since they read no registry.
+Because `npm-auto-publish` queries the npm registry for each package's trusted publisher, it needs an npm session elevated by two-factor authentication, and is meant to be invoked deliberately rather than included in an unattended run. A session that cannot answer those queries, whether it is missing a login, missing the elevation, or facing an unreachable registry, is reported once by the `npm session can answer trust queries` gate. The rows that would repeat the failed query are then skipped: the trusted-publisher rows in every case, and `published to npm` when the registry itself is unreachable. Each package's `package.json` checks report throughout, since they don't read a registry.