@williamthorsen/release-kit 5.1.0 → 5.2.1

package/README.md

@@ -5,49 +5,13 @@ 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.1 (2026-05-05)
 
-### Bug fixes
+### 🐛 Bug fixes
 
-- Make publish's clean-tree safety gate reachable (#311)
+- Soft-skip tags with no changelog entry under --tags (#366)
 
-  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.
-
-- Make `--set-version` + `project` rejection explicit (#319)
-
-  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`).
-
-- Reject `--only` that would strand excluded dependents (#321)
-
-  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.
-
-- Order prerelease versions correctly in changelog sort (#334)
-
-  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.
-
-### Features
-
-- Add `project` block for project-level release stage (#317)
-
-  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.
-
-- Publish JSON Schema for `.meta/label-map.json` (#325)
-
-  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.
-
-- Label prepare errors with the failing stage (#326)
-
-  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.
+  Fixes an issue where `release-kit create-github-release --tags <tag>` exited 1 — failing the calling CI workflow — when the requested tag had no changelog entry. Tooling-only releases (those whose changelog generator legitimately omits an entry) are now soft-skipped with an info-level summary, the same as releases skipped because their entry has no audience-relevant content. Typo protection is preserved: passing an unknown tag to `--tags` still exits 1.
 <!-- /section:release-notes -->
 
 ## Installation
@@ -151,16 +115,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 +278,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
+
+`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.
+
+#### `!` (breaking change) policy
+
+Each work-type carries a `breakingPolicy` value:
+
+- `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:
 
-| 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)       |               |
+- **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.
 
-Work types from your config are merged with these defaults by key — your entries override or extend, they don't replace the full set.
+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.
 
-`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.
+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:
 
-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.
+```
+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 +432,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 +502,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
+704a70608ce284c9f8ef2dda2e6604a5f38ac0c995c9419ae39206ed053775c6

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
 };

package/dist/esm/checkWorkTypesDrift.d.ts

@@ -0,0 +1,11 @@
+export declare const UPSTREAM_WORK_TYPES_URL = "https://raw.githubusercontent.com/williamthorsen/codeassembly/main/packages/agents/content/skills/_data/work-types.json";
+export interface DriftCheckResult {
+    exitCode: 0 | 1 | 2 | 3;
+    message: string;
+}
+export interface CheckWorkTypesDriftDependencies {
+    localPath?: string;
+    fetch?: typeof globalThis.fetch;
+    upstreamUrl?: string;
+}
+export declare function checkWorkTypesDrift(dependencies?: CheckWorkTypesDriftDependencies): Promise<DriftCheckResult>;