@williamthorsen/release-kit 11.0.0 → 13.0.0

package/docs/releasing.md

@@ -1,43 +1,59 @@
 # Releasing
 
-How to scaffold the release workflows, what `release-kit prepare` does with its flags, and how the release workflow runs a release.
+How to scaffold the release workflows and keep them up to date, what `release-kit prepare` does with its flags, and how the release workflow runs a release.
 
 The [README](../README.md#quick-start) shows the first run.
 
 ## `release-kit init`
 
-Initialize release-kit in the current repository. By default, scaffolds only the GitHub Actions workflow files. Use `--with-config` to also scaffold configuration files.
+Initializes release-kit in the current repository. By default, scaffolds only the GitHub Actions workflow files. Use `--with-config` to also scaffold configuration files.
 
 Scaffolded files:
 
-- `.github/workflows/create-github-release.yaml` — workflow that creates a GitHub Release on tag push, independent of npm publish
-- `.github/workflows/publish.yaml` — workflow that delegates to a reusable publish workflow
-- `.github/workflows/release.yaml` — workflow that delegates to a reusable release workflow
-- `.config/release-kit.config.ts` — starter config with commented-out customization examples (with `--with-config`)
-- `.config/git-cliff.toml` — copied from the bundled template (with `--with-config`)
+- `.github/workflows/create-github-release.yaml`: Workflow that creates a GitHub Release on tag push, independent of npm publish
+- `.github/workflows/publish.yaml`: Workflow that delegates to a reusable publish workflow
+- `.github/workflows/release.yaml`: Workflow that delegates to a reusable release workflow
+- `.config/release-kit.config.ts`: Starter config with commented-out customization examples (with `--with-config`)
+
+## `release-kit update-templates`
+
+Updates the scaffolded workflows to the templates of the installed release-kit version, and prints what changed in each file. Run it after upgrading release-kit; `--dry-run` previews the changes without writing them.
+
+The workflows are managed files: release-kit renders them, and a change made by hand is overwritten on the next update. The config files are the repository's own, and the command never reads or writes them.
+
+- It creates a missing workflow that `init` would create.
+- It refreshes `.github/workflows/sync-labels.yaml` only when the file exists, because `sync-labels init` scaffolds it on request.
+- It keeps `publish.yaml`'s provenance setting: When the file does not set `provenance: true`, as in a private repository, the updated file does not either.
 
 ## `release-kit prepare`
 
-Run release preparation with automatic workspace discovery.
+Runs release preparation with automatic workspace discovery.
 
 Workspace names for `--only` match the package directory name (e.g., `arrays`, `release-kit`).
 
-`--bump` and `--force` are orthogonal: `--bump` is purely a level chooser; `--force` is purely a release trigger. Examples:
+`prepare` reads each target's history once and builds the changelog items of its unreleased commits. The bump is the highest level that those items call for, under [`versionPatterns`](configuration.md#versionpatterns), so the bump and the changelog describe the same release: A `feat` entry in a [change-record block](changelogs.md#change-record-blocks) bumps minor under a `docs:` title, and a breaking item bumps major.
+
+- A commit that doesn't yield an item doesn't bump anything: one without a ticket-ID prefix, one of a type excluded from the changelog (such as `fmt`), and one whose change-record entries are all undeclared or excluded.
+- A `BREAKING CHANGE:` footer doesn't raise a major bump. Only a subject's `!` and an entry's `breaking: true` mark an item breaking; on a type whose policy forbids `!`, the footer is reported as a [policy violation](work-types.md#policy-enforcement).
+- A target whose commits don't yield an item is skipped. The prepare report lists the commits that could not be parsed and the change-record diagnostics, skipped targets included.
+
+`--bump` and `--force` are orthogonal in every mode, single-package included: `--bump` is purely a level chooser; `--force` is purely a release trigger. Examples:
 
 ```sh
 # Release every target at its natural bump level (no flags).
 release-kit prepare
 
-# Force a release even when no bump-worthy commits exist; defaults to patch
-# per target, with each target keeping its natural bump if one is derivable.
+# Force a release even when the commits don't yield any changelog item;
+# defaults to patch per target, with each target keeping its natural bump
+# if it has one.
 release-kit prepare --force
 
 # Force a release at a uniform level across every releasing target.
 release-kit prepare --force --bump=minor
 
-# --bump=X alone is a level chooser, NOT a trigger. If a target has no
-# bump-worthy commits, it skips with a "Pass --force..." reason. If it has
-# bump-worthy commits, the override applies.
+# --bump=X alone is a level chooser, NOT a trigger. If a target's commits
+# don't yield any changelog item, it skips with a "Pass --force..." reason.
+# Otherwise the override applies.
 release-kit prepare --bump=minor
 ```
 
@@ -45,10 +61,10 @@ release-kit prepare --bump=minor
 
 `--with-release-notes` writes two versioned files per workspace after each workspace's `changelog.json` is produced:
 
-- `<workspacePath>/docs/README.v<version>.md` — the workspace `README.md` with release notes injected at the `<!-- section:release-notes -->` marker.
-- `<workspacePath>/docs/RELEASE_NOTES.v<version>.md` — the standalone release notes for this version.
+- `<workspacePath>/docs/README.v<version>.md`: The workspace `README.md` with release notes injected at the `<!-- section:release-notes -->` marker.
+- `<workspacePath>/docs/RELEASE_NOTES.v<version>.md`: The standalone release notes for this version.
 
-The publish-time inject-and-revert lifecycle is unchanged; previews are additive, deterministic, and safe to regenerate. When `changelogJson.enabled` is `false`, prepare reports a warning and skips preview generation. In dry-run mode, planned writes are logged and no files are created.
+The publish-time inject-and-revert lifecycle is unchanged; previews are additive, deterministic, and safe to regenerate. When `changelogJson.enabled` is `false`, prepare reports a warning and skips preview generation. In dry-run mode, prepare logs the planned writes and doesn't create any files.
 
 Because preview filenames are versioned, committing them will accumulate files over time. The recommended `.gitignore` entry for monorepos is:
 
@@ -64,7 +80,7 @@ docs/*.v*.md
 
 ### Setting an explicit version with `--set-version`
 
-The `--set-version` flag is a first-class escape hatch for the cases where commit-derived bump logic produces the wrong version — most notably, promoting a pre-1.0 package to 1.0.0. Pre-1.0 packages collapse a `feat!` breaking change to a minor bump (matching semantic-release's `initialMajor: false` and release-please's `bump-minor-pre-major`), so a deliberate promotion to 1.0.0 must be requested explicitly.
+The `--set-version` flag is a first-class escape hatch for the cases in which the derived bump produces the wrong version, most notably when promoting a pre-1.0 package to 1.0.0. Pre-1.0 packages collapse a `feat!` breaking change to a minor bump (matching semantic-release's `initialMajor: false` and release-please's `bump-minor-pre-major`), so a deliberate promotion to 1.0.0 must be requested explicitly.
 
 The flag validates that:
 
@@ -80,17 +96,31 @@ Promoting a pre-1.0 package to 1.0.0 in a monorepo:
 release-kit prepare --only arrays --set-version 1.0.0
 ```
 
-An empty changelog section is expected for a bare promotion, because the changelog is generated from commits since the last tag. To include a narrative entry, land a descriptive release commit (e.g., a `feat!` describing the stable API) before running `prepare`.
+An empty changelog section is expected for a bare promotion, because the changelog is generated from commits since the last tag. To include a narrative entry, merge a descriptive release commit (e.g., a `feat!` describing the stable API) before running `prepare`.
+
+### Adopting release-kit in a repo with untagged releases
+
+`prepare` finds a target's previous release by its tag. When a target's current version was released and recorded in its `CHANGELOG.md` or `changelog.json` but never tagged, the unreleased window would extend back to the start of history: The new version would absorb every earlier commit, and its bump would be derived from all of them. `prepare` stops before writing anything instead, under `--force` and `--set-version` too, and names each target, its version, and the tag to create:
+
+```text
+The current version is recorded in the changelog, but its tag is not the previous tag reachable from HEAD:
+  - workspace 'api': 1.2.0 (create tag api-v1.2.0)
+Tag the commit that released each version, then run prepare again.
+```
+
+Tag each named version at the commit that released it, then run `prepare` again. In a monorepo, `prepare` checks the project only after every workspace passes, so a second run can name the project's tag. The check skips a first release, whose version isn't recorded in any changelog, and a workspace that releases only through propagation.
+
+Each new tag closes a release window. When that window's commits yield items, `prepare` renders the tagged version from them, in place of its hand-written section; it keeps every other hand-written version as [Existing `CHANGELOG.md` sections](changelogs.md#existing-changelogmd-sections) describes.
 
 ## GitHub Actions workflow
 
 The `init` command scaffolds a release workflow at `.github/workflows/release.yaml` that delegates to a reusable release workflow. The scaffolded workflow accepts these inputs:
 
-| Input   | Type    | Description                                                                                                                 |
-| ------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `only`  | string  | Workspaces to release (comma-separated, leave empty for all)                                                                |
-| `bump`  | choice  | Override bump type: `patch`, `minor`, `major` (empty = auto-detect)                                                         |
-| `force` | boolean | Release even when no commits or no bump-worthy commits exist (defaults to patch; combine with `bump` for a different level) |
+| Input   | Type    | Description                                                                                                                                     |
+| ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `only`  | string  | Workspaces to release (comma-separated, leave empty for all)                                                                                    |
+| `bump`  | choice  | Bump type: `auto` (default, detects it from commits), `patch`, `minor`, or `major`                                                              |
+| `force` | boolean | Release even when the window doesn't have any commits or any bump-worthy commits (defaults to patch; combine with `bump` for a different level) |
 
 For repos that need a self-contained workflow instead of the reusable one, the scaffolded file can be expanded. The key steps are: checkout with full history (`fetch-depth: 0`), run `release-kit prepare` with optional `--only`, `--bump`, and `--force` flags, check for changes, read tags from `tmp/.release-tags`, then commit, tag, and push.
 

package/docs/work-types.md

@@ -1,60 +1,63 @@
 # Work types and tiers
 
-The taxonomy against which release-kit parses commits: its tiers, the breaking-change policy, section markers, customization, and the maintainer scripts that keep release-kit's copy level with its upstream.
-
-release-kit bundles a copy of the codeassembly canonical taxonomy in `packages/release-kit/src/work-types.json`, kept level by the [maintainer scripts](#maintaining-the-bundled-taxonomy). The taxonomy is split into three tiers that drive section rendering and audience classification.
-
-| Tier     | Key         | Header                    | Aliases       | `!` policy   |
-| -------- | ----------- | ------------------------- | ------------- | ------------ |
-| public   | `feat`      | 🎉 Features               | `feature`     | optional     |
-| public   | `drop`      | 🪦 Removed                |               | **required** |
-| public   | `deprecate` | 🗑️ Deprecated             |               | forbidden    |
-| public   | `fix`       | 🐛 Bug fixes              | `bugfix`      | optional     |
-| public   | `sec`       | 🔒 Security               | `security`    | optional     |
-| public   | `perf`      | ⚡ Performance            | `performance` | optional     |
-| 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    |
+The taxonomy against which release-kit parses commits: its tiers, the breaking-change policy, section markers, and customization.
+
+release-kit reads the taxonomy from `CANONICAL_TAXONOMY` in [`@williamthorsen/change-grammar`](https://github.com/williamthorsen/node-monorepo-tools/tree/main/packages/change-grammar#readme), which also parses commit subjects. The taxonomy is split into three tiers that determine section rendering and audience classification.
+
+| Tier     | Key         | Header                    | Aliases       | `!` policy |
+| -------- | ----------- | ------------------------- | ------------- | ---------- |
+| public   | `feat`      | 🎉 Features               | `feature`     | optional   |
+| public   | `drop`      | 🪦 Removed                |               | optional   |
+| public   | `deprecate` | 🗑️ Deprecated             |               | forbidden  |
+| public   | `fix`       | 🐛 Bug fixes              | `bugfix`      | optional   |
+| public   | `sec`       | 🔒 Security               | `security`    | optional   |
+| public   | `perf`      | ⚡ Performance            | `performance` | optional   |
+| 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**. It comes from the declaration order of `CANONICAL_TAXONOMY`: `CANONICAL_SECTION_ORDER` in `buildChangelogEntries.ts` indexes each header by its row, and `transformReleases` sorts a release's sections by that index whatever order the commits arrived in.
+
+## Subject forms
+
+`classifyChangelogCommit` resolves a commit's type through `parseCommitMessage`, so a subject maps to its section under any form that the parser accepts: `type:`, `scope|type:`, and the conventional-commit `type(scope):`, each followed by a space and a title. A subject combining both scope forms, such as `web|feat(api):`, does not parse. The type is matched case-insensitively: `Feat:` and `FEAT:` resolve like `feat:`. The ticket-ID prefix is still required, and an alias resolves before the section is chosen. A commit whose [change-record block](changelogs.md#change-record-blocks) records entries takes its sections from the entries' types instead of from its subject.
 
 ## `utility` alias
 
-`utility:` is a backward-compat alias for `internal:`. Both forms parse to the same canonical type, route to the same `🏗️ Internal features` section, and are subject to the same `!` policy.
+`utility:` is a backward-compat alias for `internal:`. Both forms parse to the same canonical type, appear under the same `🏗️ Internal features` section, and are subject to the same `!` policy.
 
 ## `!` (breaking change) policy
 
-Each work-type carries a `breakingPolicy` value:
+Each work-type has a `breakingPolicy` value:
 
-- `optional` (`feat`, `fix`, `sec`, `perf`): `!` is allowed; both `type:` and `type!:` parse cleanly. Any of these can break consumers, and the marker records when one does: A fix can break consumers who relied on the defective behavior, and a performance change can break a contract to achieve its gain.
+- `optional` (`feat`, `drop`, `fix`, `sec`, `perf`): `!` is allowed; both `type:` and `type!:` parse cleanly. Any of these can break consumers, and the marker records when one does: A removal breaks consumers only when the removed surface was published, a fix can break consumers who relied on the defective behavior, and a performance change can break a contract to achieve its gain.
 - `forbidden` (`deprecate` and every `internal`- and `process`-tier type): `!` is a policy violation. Deprecating a surface keeps it working, and removing it is a `drop`. Internal- and process-tier work does not face consumers; a change that breaks consumers faces them and therefore takes a public-tier type.
-- `required` (`drop`): Bare `drop:` is a policy violation; only `drop!:` is accepted. Removing a public surface always breaks consumers, and the `!` form makes that explicit.
 
 ### Policy enforcement
 
-`parseCommitMessage` enforces the `!` policy at release time and treats a violation as a warning. Commits already in the log cannot be rewritten, so a policy-violating commit is parsed using its canonical type with `breaking: false` (the `!` is dropped from the parse) and an `onPolicyViolation` callback fires. Callers (`decideRelease` etc.) can collect these warnings and surface them in the release report. A single legacy `internal!` in a year-old log does not block releases.
+`parseCommitMessage` enforces the `!` policy at release time and treats a violation as a warning. Commits already in the log cannot be rewritten, so a policy-violating commit is parsed using its canonical type with `breaking: false` (the `!` is dropped from the parse) and an `onPolicyViolation` callback fires. `readReleaseHistory` collects these warnings while it builds the items of the unreleased window, and the release report lists them. A single legacy `internal!` in a year-old log does not block releases.
 
-A `BREAKING CHANGE:` body footer on a `forbidden`-policy type triggers the same warning path as the prefix `!` does: A type that cannot be breaking is parsed as non-breaking whichever surface carries the signal.
+A `BREAKING CHANGE:` body footer on a `forbidden`-policy type triggers the same warning path as the prefix `!` does: A type that cannot be breaking is parsed as non-breaking whichever surface has the signal. The warning is all that a footer triggers; it doesn't raise a bump (see [`🚨 **Breaking:**` bullet marker](#-breaking-bullet-marker)).
 
-The release-prepare orchestrators (`releasePrepare`, `releasePrepareMono`, `releasePrepareProject`) apply `DEFAULT_BREAKING_POLICIES` automatically. Violations encountered while parsing each workspace's or project's commit window are collected onto the corresponding result's `policyViolations` field and rendered under the section in the prepare report:
+The release-prepare orchestrators (`releasePrepare`, `releasePrepareMono`, `releasePrepareProject`) apply `DEFAULT_BREAKING_POLICIES` automatically. Violations in the titles and change-record entries of each workspace's or project's unreleased window are collected onto the corresponding result's `policyViolations` field, on a skipped result as on a released one, and rendered under the section in the prepare report:
 
 ```
 arrays
   Found 1 commits since arrays-v1.0.0
   🟠 1 policy violation:
-      · def5678 'internal!: refactor cache' — type 'internal' at prefix surface
+      · def5678 'internal!: refactor cache': type 'internal' at prefix surface
   Bumping versions (patch)...
   📦 1.0.0 → 1.0.1 (patch)
 ```
@@ -63,7 +66,7 @@ To customize, set `breakingPolicies` in `release-kit.config.ts`. The map replace
 
 ## `🚨 **Breaking:**` bullet marker
 
-Items whose commit subject carries the `!` prefix (e.g. `feat!`, `drop!`, `feat(api)!`) on a type whose policy permits it are rendered with a `🚨 **Breaking:** ` prefix on the bullet:
+Items whose commit subject has the `!` prefix (e.g. `feat!`, `drop!`, `feat(api)!`) on a type whose policy permits it are rendered with a `🚨 **Breaking:** ` prefix on the bullet:
 
 ```markdown
 - 🚨 **Breaking:** Drop legacy /v1 endpoint
@@ -71,17 +74,17 @@ Items whose commit subject carries the `!` prefix (e.g. `feat!`, `drop!`, `feat(
 
 The marker agrees with the version bump:
 
-- A `forbidden`-policy type carrying `!`, such as `refactor!`, gets no marker, just as its `!` raises no bump; the prepare report lists it as a policy violation. An [editorial override](editorial-overrides.md) that sets `breaking: true` restores the marker for one entry.
+- A `forbidden`-policy type with `!`, such as `refactor!`, doesn't get a marker, just as its `!` doesn't raise a bump; the prepare report lists it as a policy violation. An [editorial override](editorial-overrides.md) that sets `breaking: true` restores the marker for one entry.
 - The configured `breakingPolicies` map, `{}` included, decides which types permit the marker.
-- A commit whose type the parser cannot resolve has no policy, so its `!` prefix alone decides.
+- A commit whose type the parser cannot resolve doesn't appear in any changelog, so the question of a marker doesn't arise.
 
-A `BREAKING CHANGE:` body footer on its own does **not** retroactively mark a changelog item as breaking, even on a type whose policy permits `!`; the changelog signal is tied to the commit prefix. This avoids surprise breaking-marker appearances for older commits written under earlier conventions.
+A `BREAKING CHANGE:` body footer on its own does **not** retroactively mark a changelog item as breaking, even on a type whose policy permits `!`; the changelog signal is tied to the commit prefix. This avoids surprise breaking-marker appearances for older commits written under earlier conventions. Because the bump follows the items, a footer doesn't raise a major bump either: A consumer that marks breaking changes with the footer alone gets the bump of the commit's type.
 
-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.
+The emoji and label of this marker come from the `markers.breaking` entry of `CANONICAL_TAXONOMY` (see [Section markers](#section-markers)), which is also the source for consumers that render their own breaking-changes section.
 
 ## 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.
+Alongside `tiers` and `types`, `CANONICAL_TAXONOMY` declares a top-level `markers` object for cross-cutting section markers: visual indicators that aren't tied to a specific work type. Today its only entry is `breaking`.
 
 ```jsonc
 {
@@ -91,29 +94,14 @@ Alongside `tiers` and `types`, `work-types.json` exposes a top-level `markers` o
 }
 ```
 
-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.
+Entries store plain text only, so that the taxonomy stays format-agnostic: 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.
+`fmt:` commits are recognized by `parseCommitMessage`, but `fmt` sets `excludedFromChangelog: true`, which `DEFAULT_WORK_TYPES` copies onto its `WorkTypeConfig`. `classifyChangelogCommit` excludes a commit whose type sets the flag, so a `fmt:` commit never appears in `CHANGELOG.md`, `changelog.json`, or release notes. Because it doesn't yield an item, it doesn't raise a bump, and the release report does not list it as unparseable. The taxonomy declares a label and emoji for `fmt` like any other type, but they never render.
 
 ## Custom work types
 
-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.
-
-## Maintaining the bundled taxonomy
-
-`src/workTypesData.ts` mirrors `src/work-types.json` for runtime use. Two maintainer scripts of the release-kit package compare that JSON with its codeassembly upstream and update it. They exist only in a checkout of this repository and are not part of the published `release-kit` CLI.
-
-- `nmr work-types:check` compares the content of `src/work-types.json` with the upstream, ignoring the local `$schema` hint.
-- `nmr work-types:sync` overwrites `src/work-types.json` with the upstream when their content differs.
-
-Both run from `packages/release-kit`, or from anywhere in the repository as `nmr -F @williamthorsen/release-kit work-types:check` and `nmr -F @williamthorsen/release-kit work-types:sync`. After `sync` writes the file, update `src/workTypesData.ts` to match; `workTypesData.unit.test.ts` fails until the two agree.
-
-`check` exits 0 on a match, 1 on drift, 2 when the upstream fetch fails, and 3 when either file is not valid JSON or the upstream fails the shape check. When the upstream URL returns 404, `check` exits 0 with a warning.
-
-### Authenticated fetches
+Work types from a config are merged with these defaults by key: A consumer entry overrides or extends, it does not replace the full set. `classifyChangelogCommit` reads the merged record, so an added type appears in the changelog under the `header` that it declares, and an entry setting `excludedFromChangelog: true` keeps its commits out of the changelog and the bump. Release-notes sections are rendered in the declaration order of the merged work-types record, with any unknown titles trailing the known ones.
 
-The upstream codeassembly repo is public, so `check` and `sync` need no token. When `GITHUB_TOKEN` is set in the environment, both scripts send it as `Authorization: Bearer <token>`.
+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`; matching is decorator-tolerant: A bare-name override like `['Internal features']` keeps working against the emoji-prefixed default titles.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/release-kit",
-  "version": "11.0.0",
+  "version": "13.0.0",
   "description": "Version-bumping and changelog-generation toolkit for release workflows",
   "keywords": [
     "changelog",
@@ -43,7 +43,6 @@
     ".readyup/manifest.json",
     "CHANGELOG.md",
     "bin",
-    "cliff.toml.template",
     "dist/*",
     "docs",
     "!docs/*.v*.md",
@@ -51,7 +50,8 @@
     "schemas/**"
   ],
   "dependencies": {
-    "@williamthorsen/nmr-core": "0.13.0",
+    "@williamthorsen/change-grammar": "0.1.0",
+    "@williamthorsen/nmr-core": "0.13.1",
     "@williamthorsen/toolbelt.errors": "0.8.1",
     "json-stringify-pretty-compact": "4.0.0",
     "semver": "7.8.5",
@@ -63,8 +63,10 @@
     "@williamthorsen/toolbelt.filesystem": "0.9.1",
     "@williamthorsen/toolbelt.testing": "0.6.1",
     "@williamthorsen/toolbelt.vitest": "0.10.1",
+    "actionlint": "2.0.6",
+    "esbuild": "0.28.2",
     "readyup": "0.38.0",
-    "smol-toml": "1.8.0",
+    "smol-toml": "1.9.0",
     "vitest": "4.1.11"
   },
   "engines": {
@@ -76,8 +78,6 @@
   },
   "scripts": {
     "build:post": "rdy compile",
-    "build:pre": "rdy verify",
-    "work-types:check": "node scripts/check-work-types.ts",
-    "work-types:sync": "node scripts/sync-work-types.ts"
+    "build:pre": "rdy verify"
   }
 }

package/presets/labels/common.yaml

@@ -1,37 +1,17 @@
 # Common label definitions for GitHub repositories.
 # Compatible with EndBug/label-sync format.
+# Work-type labels are built from change-grammar's taxonomy in src/sync-labels/typeLabels.ts.
 
 # Main categories
-- name: ai
-  color: a2eeef
-  description: Guidance on working in this repo, such as its AGENTS.md or a repo-local skill, or its agent config
 - name: breaking
   color: b60205
   description: Breaking API change or removal of functionality
 - name: bug
   color: d73a4a
   description: "Something isn't working"
-- name: deprecation
-  color: fbca04
-  description: Marks functionality for future removal
-- name: documentation
-  color: a2eeef
-  description: Documentation for human readers, such as a README, a guide, or a code comment
-- name: feature
-  color: '0075ca'
-  description: Added or improved external functionality
-- name: fix
-  color: d73a4a
-  description: Fixes a bug
 - name: operational
   color: '000000'
   description: Actions outside the codebase
-- name: performance
-  color: '0075ca'
-  description: Improves performance without changing behavior
-- name: security
-  color: b60205
-  description: Security vulnerability or hardening
 - name: spike
   color: '000000'
   description: Investigation
@@ -47,26 +27,6 @@
   color: fbca04
   description: Further information is needed
 
-# Refactoring
-- name: ci
-  color: edc287
-  description: CI/CD tooling & configuration
-- name: dependencies
-  color: edc287
-  description: Change to dependencies
-- name: internal
-  color: 1d76db
-  description: Internal change without external impact
-- name: refactoring
-  color: edc287
-  description: Improvement to code without change in functionality
-- name: tests
-  color: edc287
-  description: Tests
-- name: tooling
-  color: edc287
-  description: Development tools
-
 # Priority
 - name: 'priority:critical'
   color: b60205

package/schemas/changelog-overrides.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "changelog-overrides",
+  "description": "Editorial overrides that release-kit applies to generated changelog items. Each key is a lowercase hex commit hash or prefix, which targets every item of the commit, optionally followed by `:<n>`, which targets the item derived from the commit's `n`th change-record entry.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference for editor support."
+    }
+  },
+  "patternProperties": {
+    "^[0-9a-f]+(:[1-9][0-9]*)?$": {
+      "type": "object",
+      "description": "Override for the items that the key targets. At least one field must be set.",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "audience": {
+          "enum": ["all", "dev", "skip"],
+          "description": "`skip` removes the items. `all` and `dev` are reserved and not yet supported."
+        },
+        "description": {
+          "type": "string",
+          "description": "Replaces the item's headline."
+        },
+        "body": {
+          "type": "string",
+          "description": "Replaces the item's body."
+        },
+        "breaking": {
+          "type": "boolean",
+          "description": "Sets whether the item is marked as breaking."
+        }
+      }
+    }
+  }
+}

package/cliff.toml.template

@@ -1,65 +0,0 @@
-# git-cliff configuration
-# Generates changelogs from conventional-ish commit messages.
-#
-# Commit format: [ticket-prefix ]scope|type[!]: description [#PR]
-# Examples:
-#   #19 rdy|feat: Add utility functions for common check patterns (#26)
-#   AFG-42 panel|fix: Fix button layout (#73)
-#   ## feat: Quick utility added during interactive session
-#
-# Only ticketed commits (leading #NN, PROJ-NN, or ##) are included.
-# Unticketed maintenance commits (deps upgrades, tooling tweaks) are skipped.
-# Use ## as a synthetic ticket prefix for ad-hoc commits that belong in the changelog.
-#
-# Section order: each `group` value carries a hidden `<!-- NN -->` HTML-comment
-# prefix encoding the canonical row position. tera's `group_by` filter sorts
-# groups lexicographically by string, and the body template's `striptags`
-# filter erases the comment from the rendered heading. Numbering is per
-# unique group (not per parser entry) — all parsers routing to the same group
-# share the same prefix.
-
-# 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
-filter_unconventional = false
-split_commits = false
-commit_preprocessors = []
-# Require a ticket-ID prefix for inclusion.
-# Supported prefixes: "#123 ", "#123-1 ", "#123.1 ", "TOOL-123 ", "## "
-commit_parsers = [
-  { message = "^release:", skip = true },
-  { message = "^Merge", skip = true },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?feat(!)?:", group = "<!-- 01 -->🎉 Features" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?feature(!)?:", group = "<!-- 01 -->🎉 Features" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?drop(!)?:", group = "<!-- 02 -->🪦 Removed" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?deprecate(!)?:", group = "<!-- 03 -->🗑️ Deprecated" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?fix(!)?:", group = "<!-- 04 -->🐛 Bug fixes" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?bugfix(!)?:", group = "<!-- 04 -->🐛 Bug fixes" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?sec(!)?:", group = "<!-- 05 -->🔒 Security" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?security(!)?:", group = "<!-- 05 -->🔒 Security" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?perf(!)?:", group = "<!-- 06 -->⚡ Performance" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?performance(!)?:", group = "<!-- 06 -->⚡ Performance" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?internal(!)?:", group = "<!-- 07 -->🏗️ Internal features" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?utility(!)?:", group = "<!-- 07 -->🏗️ Internal features" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?refactor(!)?:", group = "<!-- 08 -->♻️ Refactoring" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?tests?(!)?:", group = "<!-- 09 -->🧪 Tests" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?tooling(!)?:", group = "<!-- 10 -->⚙️ Tooling" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?ci(!)?:", group = "<!-- 11 -->👷 CI" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?deps?(!)?:", group = "<!-- 12 -->📦 Dependencies" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?ai(!)?:", group = "<!-- 13 -->🤖 Agentic support" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?docs?(!)?:", group = "<!-- 14 -->📚 Documentation" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([^|]+\\|)?fmt(!)?:", skip = true },
-  # Skip unticketed commits (maintenance, deps, initial scaffolding, etc.)
-  { message = ".*", skip = true },
-]
-protect_breaking_commits = false
-filter_commits = true
-tag_pattern = "v[0-9].*"
-skip_tags = ""
-ignore_tags = ""
-topo_order = false
-sort_commits = "oldest"

package/dist/esm/collectPolicyViolations.d.ts

@@ -1,15 +0,0 @@
-import type { PolicyViolationHandler } from './parseCommitMessage.js';
-import type { PolicyViolation } from './types.js';
-/**
- * Build a fresh `policyViolations` accumulator paired with the `onPolicyViolation` callback
- * that pushes structured entries into it.
- *
- * Used by all three release-prepare orchestrators (`releasePrepare`, `releasePrepareMono`,
- * `releasePrepareProject`) to collect parser-side `!`-policy violations into a result-attachable
- * array. Centralizing the callback shape keeps the `commitSubject` extraction rule (`firstLine
- * post-split`) consistent across orchestrators.
- */
-export declare function createPolicyViolationCollector(): {
-    violations: PolicyViolation[];
-    onPolicyViolation: PolicyViolationHandler;
-};

package/dist/esm/collectPolicyViolations.js

@@ -1,12 +0,0 @@
-export function createPolicyViolationCollector() {
-    const violations = [];
-    const onPolicyViolation = (commit, type, surface) => {
-        violations.push({
-            commitHash: commit.hash,
-            commitSubject: commit.message.split('\n', 1)[0] ?? '',
-            type,
-            surface,
-        });
-    };
-    return { violations, onPolicyViolation };
-}

package/dist/esm/determineBumpFromCommits.d.ts

@@ -1,17 +0,0 @@
-import { type PolicyViolationHandler } from './parseCommitMessage.js';
-import type { Commit, ReleaseType, VersionPatterns, WorkTypeConfig } from './types.js';
-/** Aggregate result of parsing commits and determining the bump type. */
-export interface BumpDetermination {
-    releaseType: ReleaseType | undefined;
-    parsedCommitCount: number;
-    unparseableCommits: Commit[] | undefined;
-}
-/** Optional configuration for parser-policy plumbing. */
-export interface DetermineBumpOptions {
-    /** Per-canonical-type breaking-policy lookup (drives `!` policy enforcement). */
-    breakingPolicies?: Record<string, 'forbidden' | 'optional' | 'required'>;
-    /** Receives policy-violation notifications from `parseCommitMessage`. */
-    onPolicyViolation?: PolicyViolationHandler;
-}
-/** Parse commits, determine bump type, and apply patch floor when commits exist but none parsed. */
-export declare function determineBumpFromCommits(commits: Commit[], workTypes: Record<string, WorkTypeConfig>, versionPatterns: VersionPatterns, scopeAliases: Record<string, string> | undefined, options?: DetermineBumpOptions): BumpDetermination;

package/dist/esm/determineBumpFromCommits.js

@@ -1,28 +0,0 @@
-import { determineBumpType } from "./determineBumpType.js";
-import { parseCommitMessage, } from "./parseCommitMessage.js";
-export function determineBumpFromCommits(commits, workTypes, versionPatterns, scopeAliases, options) {
-    const parseOptions = {
-        ...(options?.breakingPolicies !== undefined && { breakingPolicies: options.breakingPolicies }),
-        ...(options?.onPolicyViolation !== undefined && { onPolicyViolation: options.onPolicyViolation }),
-    };
-    const parsedCommits = [];
-    const unparseable = [];
-    for (const commit of commits) {
-        const parsed = parseCommitMessage(commit.message, commit.hash, workTypes, scopeAliases, parseOptions);
-        if (parsed === undefined) {
-            unparseable.push(commit);
-        }
-        else {
-            parsedCommits.push(parsed);
-        }
-    }
-    let releaseType = determineBumpType(parsedCommits, workTypes, versionPatterns);
-    if (releaseType === undefined && commits.length > 0) {
-        releaseType = 'patch';
-    }
-    return {
-        releaseType,
-        parsedCommitCount: parsedCommits.length,
-        unparseableCommits: unparseable.length > 0 ? unparseable : undefined,
-    };
-}