@williamthorsen/release-kit 5.1.0 → 5.2.0

package/README.md

@@ -5,49 +5,39 @@ 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`.
 
 <!-- section:release-notes -->
-## Release notes — v5.1.0 (2026-04-30)
+## Release notes — v5.2.0 (2026-05-04)
 
-### Bug fixes
+### 🎉 Features
 
-- Make publish's clean-tree safety gate reachable (#311)
+- Add emojis to changelog and release-note headings (#352)
 
-  Fixes an issue where `release-kit publish` failed with pnpm's "working tree is dirty" error on a clean tree whenever `releaseNotes.shouldInjectIntoReadme: true` was configured. release-kit injects the release notes into the package README before invoking `pnpm publish`, so pnpm's own working-tree check fired on a tree release-kit had just dirtied — even though the user's tree was clean at command start.
+  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.
 
-- Make `--set-version` + `project` rejection explicit (#319)
+- Surface bang violations in release prepare reports (#359)
 
-  Improves the error users see when invoking `release-kit prepare --set-version` with a `project` block configured. The combination is still rejected — as before — but now produces a single, project-aware message ("--set-version cannot be combined with a project release…") rather than the previous two-step chain (`--set-version requires --only`, then `--only cannot be combined with a project release` after the user added `--only`).
+  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.
 
-- Reject `--only` that would strand excluded dependents (#321)
+### 🐛 Bug fixes
 
-  Fixes a silent footgun in `release-kit prepare --only=...`: an excluded internal dependent with its own changes would be left unreleased with no runtime signal, even though the targeted workspace it depends on was being released. The command now rejects such invocations up front, naming every excluded dependent whose changes would be stranded.
+- Restrict publish to publishable workspaces (#345)
 
-- Order prerelease versions correctly in changelog sort (#334)
+  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.
 
-  Fixes a latent issue in `@williamthorsen/release-kit` where prerelease version tags (e.g., `1.2.3-alpha`, `1.2.3-rc.1`) were sorted as if their prerelease component were absent, causing them to appear in the wrong position relative to releases sharing the same base version. Changelog entries are now ordered per SemVer §11: prerelease versions precede the corresponding release (`1.2.3-alpha < 1.2.3`), build metadata is ignored for ordering, and entries that fail SemVer validation sort deterministically to the bottom of the list rather than collapsing into mid-list positions.
+- Skip tooling-only releases instead of failing (#347)
 
-### Features
+  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.
 
-- Add `project` block for project-level release stage (#317)
+- Establish canonical work-types SSOT and restore changelog section ordering (#358)
 
-  Adds support for monorepos that ship a single combined deliverable to version, changelog, and release-note the project itself rather than only its constituent workspaces.
+  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.
 
-- Publish JSON Schema for `.meta/label-map.json` (#325)
+  Closes #355.
 
-  Adds a JSON Schema for `.meta/label-map.json` to release-kit, packaged at `packages/release-kit/schemas/label-map.json` and shipped to npm. Consumers reference it via the stable raw URL pattern `https://github.com/williamthorsen/node-monorepo-tools/raw/release-kit-v<version>/packages/release-kit/schemas/label-map.json` — the same shape audit-deps already uses.
+### ⚡ Performance
 
-- Label prepare errors with the failing stage (#326)
+- Skip npx registry revalidation when running git-cliff (#361)
 
-  Adds stage attribution to errors thrown during `release-kit prepare`. Errors from per-workspace bumps and changelog generation, the project release stage, and the post-release format command now begin with a stage label that identifies the failing stage and (where relevant) the affected workspace.
-
-- Make `--force` and `--bump` orthogonal (#328)
-
-  Decouples `--force` and `--bump` so each flag has a single responsibility, and unifies skip semantics across the per-workspace and project pipelines.
-
-### Documentation
-
-- Document tag prefix collisions as general rule (#320)
-
-  Documents the strict-prefix tag-prefix collision rule as a general validation rule that applies to every release-kit consumer declaring more than one tag prefix: across active workspaces, declared legacy identities, retired packages, and the optional `project` block. Previously, the rule appeared only inside the `Project releases` validation list.
+  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.
 <!-- /section:release-notes -->
 
 ## Installation
@@ -151,16 +141,17 @@ The config file supports both `export default config` and `export const config =
 
 ### `ReleaseKitConfig` reference
 
-| Field             | Type                             | Description                                                                                                                   |
-| ----------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `cliffConfigPath` | `string`                         | Explicit path to cliff config. If omitted, resolved automatically: `.config/git-cliff.toml` → `cliff.toml` → bundled template |
-| `workspaces`      | `WorkspaceOverride[]`            | Override or exclude discovered workspaces (matched by `dir`)                                                                  |
-| `formatCommand`   | `string`                         | Shell command to run after changelog generation; modified file paths are appended as arguments                                |
-| `versionPatterns` | `VersionPatterns`                | Rules for which commit types trigger major/minor bumps                                                                        |
-| `scopeAliases`    | `Record<string, string>`         | Maps shorthand scope names to canonical names in commits                                                                      |
-| `workTypes`       | `Record<string, WorkTypeConfig>` | Work type definitions, merged with defaults by key                                                                            |
-| `retiredPackages` | `RetiredPackage[]`               | Packages that once lived in this repo but have been extracted or removed; suppresses undeclared-tag-prefix warnings           |
-| `project`         | `ProjectConfig`                  | Opt-in project-level release block. Declaring `project: {}` (even empty) enables a project-release stage in `prepare`         |
+| Field              | Type                                                      | Description                                                                                                                                          |
+| ------------------ | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cliffConfigPath`  | `string`                                                  | Explicit path to cliff config. If omitted, resolved automatically: `.config/git-cliff.toml` → `cliff.toml` → bundled template                        |
+| `workspaces`       | `WorkspaceOverride[]`                                     | Override or exclude discovered workspaces (matched by `dir`)                                                                                         |
+| `formatCommand`    | `string`                                                  | Shell command to run after changelog generation; modified file paths are appended as arguments                                                       |
+| `versionPatterns`  | `VersionPatterns`                                         | Rules for which commit types trigger major/minor bumps                                                                                               |
+| `scopeAliases`     | `Record<string, string>`                                  | Maps shorthand scope names to canonical names in commits                                                                                             |
+| `workTypes`        | `Record<string, WorkTypeConfig>`                          | Work type definitions, merged with defaults by key                                                                                                   |
+| `breakingPolicies` | `Record<string, 'forbidden' \| 'optional' \| 'required'>` | Per-type `!`-policy lookup. Defaults to `DEFAULT_BREAKING_POLICIES`. Replaces the default entirely when provided. Set to `{}` to disable enforcement |
+| `retiredPackages`  | `RetiredPackage[]`                                        | Packages that once lived in this repo but have been extracted or removed; suppresses undeclared-tag-prefix warnings                                  |
+| `project`          | `ProjectConfig`                                           | Opt-in project-level release block. Declaring `project: {}` (even empty) enables a project-release stage in `prepare`                                |
 
 All fields are optional.
 
@@ -313,30 +304,93 @@ interface VersionPatterns {
 
 Default: `{ major: ['!'], minor: ['feat'] }`
 
-### Default work types
+### Work types and tiers
+
+The canonical taxonomy lives in `packages/release-kit/src/work-types.json` and 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`      | 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.
+
+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.
+
+#### `utility` alias
 
-| Key         | Header          | Aliases       |
-| ----------- | --------------- | ------------- |
-| `fix`       | Bug fixes       | `bugfix`      |
-| `deprecate` | Deprecated      |               |
-| `feat`      | Features        | `feature`     |
-| `internal`  | Internal        |               |
-| `perf`      | Performance     | `performance` |
-| `refactor`  | Refactoring     |               |
-| `sec`       | Security        | `security`    |
-| `tests`     | Tests           | `test`        |
-| `tooling`   | Tooling         |               |
-| `ci`        | CI              |               |
-| `deps`      | Dependencies    | `dep`         |
-| `docs`      | Documentation   | `doc`         |
-| `ai`        | Agentic support |               |
-| `fmt`       | (skipped)       |               |
+`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.
 
-Work types from your config are merged with these defaults by key — your entries override or extend, they don't replace the full set.
+#### `!` (breaking change) policy
 
-`fmt:` commits are recognized for version-bump determination (they contribute to a patch bump) but are skipped by the bundled `cliff.toml.template`, so they do not appear in `CHANGELOG.md` or release notes.
+Each work-type carries a `breakingPolicy` value:
 
-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: `Agentic support`, `CI`, `Dependencies`, `Internal`, `Refactoring`, `Tests`, `Tooling`. Override via `changelogJson.devOnlySections` in your config.
+- `optional` (`feat`, `sec`) — `!` is allowed; both `type:` and `type!:` parse cleanly.
+- `forbidden` (most types) — `!` is a policy violation. The premise: types like `internal!`, `perf!`, `fix!` are contradictory; an internal change cannot break a consumer contract, a pure perf change preserves the contract, and a bug-fix is by definition not a contract change.
+- `required` (`drop`) — bare `drop:` is a policy violation; only `drop!:` is accepted. The premise: removing a feature always breaks consumers; the `!` form makes that explicit.
+
+##### Two-tier policy enforcement
+
+The `!` policy operates at two distinct levels with different semantics:
+
+- **Write-time** (commit-msg hook) — strict rejection. Policy violations are blocked at the gate where the author can act on them immediately. _Hook-based enforcement is tracked separately and is not yet shipped._
+- **Release-time** (`parseCommitMessage`) — tolerant warn-and-continue. 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 a `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.
+
+A `BREAKING CHANGE:` body footer on a `forbidden`-policy type triggers the same warning path as the prefix `!` does — the spirit of the policy is "internal/perf/etc. cannot be breaking", which must apply to both surfaces.
+
+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:
+
+```
+arrays
+  Found 1 commits since arrays-v1.0.0
+  ⚠️  1 policy violation:
+      · def5678 'internal!: refactor cache' — type 'internal' at prefix surface
+  Bumping versions (patch)...
+  📦 1.0.0 → 1.0.1 (patch)
+```
+
+To customize, set `breakingPolicies` in `release-kit.config.ts` — provide a partial map to override individual types, or `{}` to disable enforcement entirely (the parser falls back to `'optional'` for any missing type). Violations remain warnings, never failures.
+
+#### `🚨 **Breaking:**` bullet marker
+
+Items whose commit subject carries the `!` prefix (e.g. `feat!`, `drop!`, `feat(api)!`) are rendered with a `🚨 **Breaking:** ` prefix on the bullet:
+
+```markdown
+- 🚨 **Breaking:** Drop legacy /v1 endpoint
+```
+
+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.
+
+#### `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.
+
+#### 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.
 
 ## CLI reference
 
@@ -404,6 +458,33 @@ 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`.
 
+### `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.
+
+| Flag                   | Description                                                                  |
+| ---------------------- | ---------------------------------------------------------------------------- |
+| `--dry-run`            | Preview without publishing                                                   |
+| `--no-git-checks`      | Skip the clean-working-tree check                                            |
+| `--tags=tag1,tag2,...` | Only publish the named tags (comma-separated, full tag names)                |
+| `--provenance`         | Generate provenance statement (requires OIDC, not supported by classic yarn) |
+| `--help`, `-h`         | Show help                                                                    |
+
+#### Publishability filter
+
+`publish` operates 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`, get a `CHANGELOG.md` entry, and get a GitHub Release via `release-kit create-github-release` — only the registry publish step is skipped. Other commands ignore this filter and operate on private workspaces unchanged.
+
+The filter behaves differently depending on whether `--tags` is provided:
+
+- **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): if any named tag points at an unpublishable workspace, `release-kit publish` exits 1 with one error line per unpublishable tag, citing `package.json#private`. Explicit naming surfaces the contradiction rather than silently dropping the tag.
+
+Example output when an explicit tag is unpublishable:
+
+```
+Error: basic-v1.0.0 (packages/basic) cannot be published: 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 regardless of whether the matching package was published.
@@ -447,6 +528,28 @@ Scaffolded files:
 - `.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`)
 
+### `release-kit work-types`
+
+Manage the canonical work-types taxonomy used by changelog and release-notes generation.
+
+| Subcommand | Description                                                                         |
+| ---------- | ----------------------------------------------------------------------------------- |
+| `check`    | Compare the local `work-types.json` against the upstream codeassembly canonical     |
+| `sync`     | Overwrite the local `work-types.json` with the upstream contents (after validation) |
+
+`check` exit codes:
+
+| Code | Meaning                                                                           |
+| ---- | --------------------------------------------------------------------------------- |
+| `0`  | Match (or upstream missing — transitional warning printed)                        |
+| `1`  | Drift detected                                                                    |
+| `2`  | Network error or non-OK HTTP response                                             |
+| `3`  | Schema mismatch (upstream JSON does not parse or fails the top-level shape check) |
+
+The check is non-blocking initially: until codeassembly publishes its `work-types.json`, the upstream URL returns 404 and `check` exits 0 with a warning. CI flip to a blocking check is tracked as a follow-up once the upstream ships.
+
+These commands are also exposed as `nmr work-types:check` / `nmr work-types:sync` from any package directory.
+
 ### `release-kit sync-labels`
 
 Manage GitHub label definitions via config-driven YAML files.

package/cliff.toml.template

@@ -10,6 +10,13 @@
 # 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.
 
 [changelog]
 header = """
@@ -61,24 +68,26 @@ commit_preprocessors = []
 commit_parsers = [
   { message = "^release:", skip = true },
   { message = "^Merge", skip = true },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?ai(!)?:", group = "Agentic support" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?bugfix(!)?:", group = "Bug fixes" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?ci(!)?:", group = "CI" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?deprecate(!)?:", group = "Deprecated" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?deps?(!)?:", group = "Dependencies" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?docs?(!)?:", group = "Documentation" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?feat(!)?:", group = "Features" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?feature(!)?:", group = "Features" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?fix(!)?:", group = "Bug fixes" },
+  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?feat(!)?:", group = "<!-- 01 -->🎉 Features" },
+  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?feature(!)?:", group = "<!-- 01 -->🎉 Features" },
+  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?drop(!)?:", group = "<!-- 02 -->🪦 Removed" },
+  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?deprecate(!)?:", group = "<!-- 03 -->🗑️ Deprecated" },
+  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?fix(!)?:", group = "<!-- 04 -->🐛 Bug fixes" },
+  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?bugfix(!)?:", group = "<!-- 04 -->🐛 Bug fixes" },
+  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?sec(!)?:", group = "<!-- 05 -->🔒 Security" },
+  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?security(!)?:", group = "<!-- 05 -->🔒 Security" },
+  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?perf(!)?:", group = "<!-- 06 -->⚡ Performance" },
+  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?performance(!)?:", group = "<!-- 06 -->⚡ Performance" },
+  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?internal(!)?:", group = "<!-- 07 -->🏗️ Internal features" },
+  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?utility(!)?:", group = "<!-- 07 -->🏗️ Internal features" },
+  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?refactor(!)?:", group = "<!-- 08 -->♻️ Refactoring" },
+  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?tests?(!)?:", group = "<!-- 09 -->🧪 Tests" },
+  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?tooling(!)?:", group = "<!-- 10 -->⚙️ Tooling" },
+  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?ci(!)?:", group = "<!-- 11 -->👷 CI" },
+  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?deps?(!)?:", group = "<!-- 12 -->📦 Dependencies" },
+  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?ai(!)?:", group = "<!-- 13 -->🤖 Agentic support" },
+  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?docs?(!)?:", group = "<!-- 14 -->📚 Documentation" },
   { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?fmt(!)?:", skip = true },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?internal(!)?:", group = "Internal" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?perf(!)?:", group = "Performance" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?performance(!)?:", group = "Performance" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?refactor(!)?:", group = "Refactoring" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?sec(!)?:", group = "Security" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?security(!)?:", group = "Security" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?tests?(!)?:", group = "Tests" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?tooling(!)?:", group = "Tooling" },
   # Skip unticketed commits (maintenance, deps, initial scaffolding, etc.)
   { message = ".*", skip = true },
 ]

package/dist/esm/.cache

@@ -1 +1 @@
-fca70d83414ef35352e152c9e916f24705c93c5556b14c16388a5b791752f075
+64d26b06f4a6e205faa07a507fd64938899e4d635dd02b333016caf1d937a14e

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { parseArgs, translateParseError } from "@williamthorsen/nmr-core";
+import { parseArgs, readPackageVersion, translateParseError } from "@williamthorsen/nmr-core";
+import { checkWorkTypesDrift } from "../checkWorkTypesDrift.js";
 import { commitCommand } from "../commitCommand.js";
 import { createGithubReleaseCommand } from "../createGithubReleaseCommand.js";
 import { initCommand } from "../init/initCommand.js";
@@ -10,8 +11,9 @@ import { showTagPrefixesCommand } from "../showTagPrefixesCommand.js";
 import { generateCommand } from "../sync-labels/generateCommand.js";
 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 { VERSION } from "../version.js";
+const VERSION = readPackageVersion(import.meta.url);
 function showUsage() {
   console.info(`
 Usage: release-kit <command> [options]
@@ -26,6 +28,7 @@ Commands:
   show-tag-prefixes  Show derived and declared legacy tag prefixes per workspace
   init             Initialize release-kit in the current repository
   sync-labels      Manage GitHub label synchronization
+  work-types       Check for or sync work-type taxonomy drift against the upstream canonical
 
 Options:
   --dry-run     Preview changes without writing files
@@ -171,6 +174,49 @@ 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 showWorkTypesHelp() {
+  console.info(`
+Usage: release-kit work-types <subcommand>
+
+Manage the canonical work-types taxonomy used by changelog and release-notes generation.
+
+Subcommands:
+  check         Compare the local work-types.json against the upstream codeassembly canonical
+  sync          Overwrite the local work-types.json with the upstream contents
+
+Exit codes (check):
+  0    Match (or upstream missing \u2014 transitional warning printed)
+  1    Drift detected
+  2    Network error
+  3    Schema mismatch
+
+Options:
+  --help, -h    Show this help message
+`);
+}
+function showWorkTypesCheckHelp() {
+  console.info(`
+Usage: release-kit work-types check
+
+Compare the local work-types.json against the upstream codeassembly canonical and report
+drift. Exit 0 on match, 1 on drift, 0 + warning when upstream is missing (transitional),
+2 on network error, 3 on schema mismatch.
+
+Options:
+  --help, -h    Show this help message
+`);
+}
+function showWorkTypesSyncHelp() {
+  console.info(`
+Usage: release-kit work-types sync
+
+Fetch the upstream work-types.json, validate its top-level shape, and overwrite the local
+copy with the upstream content (formatted with 2-space indent + trailing newline).
+
 Options:
   --help, -h    Show this help message
 `);
@@ -179,7 +225,9 @@ function showPublishHelp() {
   console.info(`
 Usage: release-kit publish [options]
 
-Publish packages that have release tags on HEAD.
+Publish packages that have release tags on HEAD. Operates only on workspaces where
+package.json#private is absent or false. Without --tags, unpublishable workspaces are
+silently filtered out. With --tags, naming an unpublishable tag is an error.
 
 Options:
   --dry-run              Preview without publishing
@@ -341,6 +389,51 @@ if (command === "sync-labels") {
   showSyncLabelsHelp();
   process.exit(1);
 }
+if (command === "work-types") {
+  const subcommand = flags[0];
+  const subflags = flags.slice(1);
+  if (subcommand === "--help" || subcommand === "-h" || subcommand === void 0) {
+    showWorkTypesHelp();
+    process.exit(0);
+  }
+  if (subcommand === "check") {
+    if (subflags.some((f) => f === "--help" || f === "-h")) {
+      showWorkTypesCheckHelp();
+      process.exit(0);
+    }
+    if (subflags.length > 0) {
+      console.error(`Error: Unknown option: ${subflags[0]}`);
+      process.exit(1);
+    }
+    const result = await checkWorkTypesDrift();
+    if (result.exitCode === 0) {
+      console.info(result.message);
+    } else {
+      console.error(result.message);
+    }
+    process.exit(result.exitCode);
+  }
+  if (subcommand === "sync") {
+    if (subflags.some((f) => f === "--help" || f === "-h")) {
+      showWorkTypesSyncHelp();
+      process.exit(0);
+    }
+    if (subflags.length > 0) {
+      console.error(`Error: Unknown option: ${subflags[0]}`);
+      process.exit(1);
+    }
+    const result = await syncWorkTypes();
+    if (result.exitCode === 0) {
+      console.info(result.message);
+    } else {
+      console.error(result.message);
+    }
+    process.exit(result.exitCode);
+  }
+  console.error(`Error: Unknown subcommand: ${subcommand}`);
+  showWorkTypesHelp();
+  process.exit(1);
+}
 console.error(`Error: Unknown command: ${command}`);
 showUsage();
 process.exit(1);

package/dist/esm/buildChangelogEntries.d.ts

@@ -1,3 +1,4 @@
 import type { GenerateChangelogOptions } from './generateChangelogs.ts';
 import type { ChangelogEntry, ReleaseConfig } from './types.ts';
+export declare function stripGroupDecorations(group: string): string;
 export declare function buildChangelogEntries(config: Pick<ReleaseConfig, 'cliffConfigPath' | 'changelogJson'>, tag: string, options?: GenerateChangelogOptions): ChangelogEntry[];

package/dist/esm/buildChangelogEntries.js

@@ -1,31 +1,32 @@
-import { execFileSync } from "node:child_process";
-import { copyFileSync, mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
 import { extractVersion } from "./changelogJsonUtils.js";
+import { DEFAULT_WORK_TYPES } from "./defaults.js";
+import { COMMIT_PREPROCESSOR_PATTERNS } from "./parseCommitMessage.js";
 import { resolveCliffConfigPath } from "./resolveCliffConfigPath.js";
+import { runGitCliff } from "./runGitCliff.js";
+import { stripEmojiPrefix } from "./stripEmojiPrefix.js";
 import { isRecord, isUnknownArray } from "./typeGuards.js";
+const HTML_COMMENT_PREFIX_PATTERN = /^<!--[^>]*-->/;
+const CANONICAL_SECTION_ORDER = new Map(
+  Object.values(DEFAULT_WORK_TYPES).map((config, index) => [stripGroupDecorations(config.header), index])
+);
+function canonicalSectionPriority(title) {
+  const index = CANONICAL_SECTION_ORDER.get(stripGroupDecorations(title));
+  return index ?? Number.POSITIVE_INFINITY;
+}
+function stripGroupDecorations(group) {
+  return stripEmojiPrefix(group.replace(HTML_COMMENT_PREFIX_PATTERN, ""));
+}
 function buildChangelogEntries(config, tag, options) {
   const resolvedConfigPath = resolveCliffConfigPath(config.cliffConfigPath, import.meta.url);
-  let cliffConfigPath = resolvedConfigPath;
-  let tempDir;
-  if (resolvedConfigPath.endsWith(".template")) {
-    tempDir = mkdtempSync(join(tmpdir(), "cliff-"));
-    cliffConfigPath = join(tempDir, "cliff.toml");
-    copyFileSync(resolvedConfigPath, cliffConfigPath);
-  }
-  const args = ["--config", cliffConfigPath, "--context", "--tag", tag];
+  const cliffArgs = ["--context", "--tag", tag];
   if (options?.tagPattern !== void 0) {
-    args.push("--tag-pattern", options.tagPattern);
+    cliffArgs.push("--tag-pattern", options.tagPattern);
   }
   for (const includePath of options?.includePaths ?? []) {
-    args.push("--include-path", includePath);
+    cliffArgs.push("--include-path", includePath);
   }
   try {
-    const contextJson = execFileSync("npx", ["--yes", "git-cliff", ...args], {
-      encoding: "utf8",
-      stdio: ["pipe", "pipe", "inherit"]
-    });
+    const contextJson = runGitCliff(resolvedConfigPath, cliffArgs, ["pipe", "pipe", "inherit"]);
     const releases = parseCliffContext(contextJson);
     const devOnlySections = new Set(config.changelogJson.devOnlySections);
     return transformReleases(releases, devOnlySections);
@@ -33,10 +34,6 @@ function buildChangelogEntries(config, tag, options) {
     throw new Error(
       `Failed to build changelog entries for tag ${tag}: ${error instanceof Error ? error.message : String(error)}`
     );
-  } finally {
-    if (tempDir !== void 0) {
-      rmSync(tempDir, { recursive: true, force: true });
-    }
   }
 }
 function parseCliffContext(json) {
@@ -76,6 +73,7 @@ function toCliffContextCommit(value) {
 }
 function transformReleases(releases, devOnlySections) {
   const entries = [];
+  const devOnlyNormalised = new Set([...devOnlySections].map(stripGroupDecorations));
   for (const release of releases) {
     if (release.version === void 0) {
       continue;
@@ -84,9 +82,10 @@ function transformReleases(releases, devOnlySections) {
     const date = release.timestamp !== void 0 ? new Date(release.timestamp * 1e3).toISOString().slice(0, 10) : "unreleased";
     const sectionMap = /* @__PURE__ */ new Map();
     for (const commit of release.commits ?? []) {
-      const group = commit.group ?? "Other";
+      const group = stripCommentPrefix(commit.group ?? "Other");
       const description = extractDescription(commit.message);
       const body = extractBody(commit.message);
+      const breaking = subjectHasBreakingMarker(commit.message);
       let items = sectionMap.get(group);
       if (items === void 0) {
         items = [];
@@ -96,6 +95,9 @@ function transformReleases(releases, devOnlySections) {
       if (body !== void 0) {
         item.body = body;
       }
+      if (breaking) {
+        item.breaking = true;
+      }
       items.push(item);
     }
     const sections = [];
@@ -105,16 +107,27 @@ function transformReleases(releases, devOnlySections) {
       }
       sections.push({
         title,
-        audience: devOnlySections.has(title) ? "dev" : "all",
+        audience: devOnlyNormalised.has(stripGroupDecorations(title)) ? "dev" : "all",
         items
       });
     }
+    sections.sort((a, b) => canonicalSectionPriority(a.title) - canonicalSectionPriority(b.title));
     if (sections.length > 0) {
       entries.push({ version, date, sections });
     }
   }
   return entries;
 }
+function stripCommentPrefix(group) {
+  return group.replace(HTML_COMMENT_PREFIX_PATTERN, "");
+}
+function subjectHasBreakingMarker(message) {
+  let subject = message.split("\n", 1)[0] ?? "";
+  for (const pattern of COMMIT_PREPROCESSOR_PATTERNS) {
+    subject = subject.replace(pattern, "");
+  }
+  return /^(?:[^|]+\|)?\w+(?:\([^)]+\))?!:/.test(subject);
+}
 function extractDescription(message) {
   const firstLine = message.split("\n")[0] ?? message;
   const afterColon = firstLine.split(": ").slice(1).join(": ");
@@ -155,5 +168,6 @@ function extractBody(message) {
   return lines.slice(start, end).join("\n").trim();
 }
 export {
-  buildChangelogEntries
+  buildChangelogEntries,
+  stripGroupDecorations
 };