@williamthorsen/release-kit 5.0.0 → 5.2.0

package/README.md

@@ -5,61 +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.0.0 (2026-04-23)
+## Release notes — v5.2.0 (2026-05-04)
 
-### Bug fixes
+### 🎉 Features
 
-- Derive monorepo tag prefix from unscoped `package.json` name (#278)
+- Add emojis to changelog and release-note headings (#352)
 
-  Fixes a long-standing mismatch between a monorepo workspace's directory basename and its publishable package identity.
+  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.
 
-### Features
+- Surface bang violations in release prepare reports (#359)
 
-- Improve release-notes rendering quality (#261)
+  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.
 
-  Improves the quality of release notes and CHANGELOG entries generated by release-kit. Release notes sections are now ordered by work-type priority (bug fixes first, then features, then internal), and each bullet now includes the commit body text for context that a one-line title cannot provide. Refactoring commits are now excluded from the release notes.
+### 🐛 Bug fixes
 
-- Scaffold release-notes injection and check markers (#267)
+- Restrict publish to publishable workspaces (#345)
 
-  Adds release-notes injection to the configs scaffolded by `release-kit init`, so newly-onboarded consumers get the feature without having to discover or toggle the flag. The release-kit readyup kit gains a check that warns when a consumer's README is missing the marker pair where injected notes should land — without those markers, injection silently prepends to the top of the file, pushing the README's title below the notes.
+  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.
 
-- Split GitHub Release creation into its own workflow (#272)
+- Skip tooling-only releases instead of failing (#347)
 
-  Splits GitHub Release creation out of release-kit publish into a dedicated release-kit create-github-release CLI command and a matching reusable GitHub Actions workflow. Consumers that do not publish to npm can now create Releases independently, and the contents: write permission required to create a Release no longer leaks into the publish path.
+  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.
 
-- Replace --only with --tags on release-kit publish and push (#273)
+- Establish canonical work-types SSOT and restore changelog section ordering (#358)
 
-  `release-kit publish` and `release-kit push` now filter by full tag name via `--tags=<tag1,tag2>` instead of workspace directory name via `--only=<dir>`, matching the shape already used by `create-github-release`. Callers pass the tag they care about (e.g., `core-v1.3.0`) directly, with no translation step back to the publishing workspace's directory name. The reusable workflow gains an optional `tags:` input, and the internal `publish.yaml` caller now passes `tags: ${{ github.ref_name }}`, making the publish scope explicit rather than relying on the single-tag fetch default of `actions/checkout@v6`.
+  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.
 
-- Apply pre-1.0 bump rule and add --set-version CLI escape hatch (#274)
+  Closes #355.
 
-  Fixes an issue where a `feat!` commit on a pre-1.0 package would accidentally promote it to `1.0.0`. At pre-1.0 (`0.y.z`), a `'major'` release type now collapses to a minor bump. Adds a validated `--set-version <semver>` CLI flag on `release-kit prepare` that bypasses commit-derived bump logic and writes a specific version.
+### ⚡ Performance
 
-- Scaffold audit.yaml workflow from audit-deps init (#277)
+- Skip npx registry revalidation when running git-cliff (#361)
 
-  Adds GitHub Actions workflow scaffolding to `audit-deps init`. Running the command now writes both `.config/audit-deps.config.json` and `.github/workflows/audit.yaml` in the target repo, so that consumers no longer have to copy the canonical caller workflow by hand from this repo. The workflow content is shipped as a bundled template that ships to npm, and the repo's own workflow is kept byte-identical to that template via a consistency test — the canonical workflow cannot silently drift from what is published.
-
-- Add migrate-tag-prefixes.sh migration tool (#282)
-
-  Adds a one-shot migration tool, `migrate-tag-prefixes.sh`, shipped inside the release-kit package. The tool creates additive annotated-tag aliases under release-kit's new unscoped-package-name prefix that point at the same commits as the previous directory-basename tags, bridging the gap so post-migration `getCommitsSinceTarget` calls can resolve prior releases.
-
-- Add legacyTagPrefixes config field (#289)
-
-  Replaces the v4 → v5 tag-prefix migration mechanism (tag aliasing via `migrate-tag-prefixes.sh`) with a declarative `legacyTagPrefixes` config field. release-kit now searches for both legacy and modern prefixes when generating changelogs.
-
-  Adds a companion `release-kit show-tag-prefixes` CLI command that renders a per-workspace table of derived and declared legacy prefixes, flags cross-workspace collisions, and surfaces undeclared candidate prefixes with a copy-pasteable config snippet. `release-kit prepare` gains a one-line hint pointing operators to `show-tag-prefixes` when a workspace has no baseline tag but the repo contains candidate-shaped tags.
-
-- Replace `legacyTagPrefixes` with `legacyIdentities` (#297)
-
-  Replaces the per-workspace `legacyTagPrefixes: string[]` field with `legacyIdentities: LegacyIdentity[]`, a structured array of complete `(name, tagPrefix)` historical snapshots. Each legacy identity is now a self-consistent record of what a workspace used to be called and how its tags used to be prefixed, so a workspace that has been renamed (npm name change, tag-prefix change, or both) carries one entry per prior identity.
-
-- Add `retiredPackages` repo-level config field (#299)
-
-  Adds support for declaring packages that once lived in this repo but have been extracted or removed, so their historical tag prefixes (e.g., `preflight-v*` from the extracted `readyup` project) no longer surface as "Undeclared tag prefixes" in `release-kit show-tag-prefixes`. Declared retired packages are acknowledged as real history but never consulted for baseline lookup or changelog attribution — they complement `workspaces[].legacyIdentities`, which is used when a workspace still exists under a new identity.
-
-- Add release-notes preview generator to `release-kit prepare` (#302)
-
-  Adds the ability to generate release notes when running `release-kit prepare`. The `--with-release-notes` option enables the generation of per-workspace preview files so authors can verify release-note injection before publishing.  Injected release notes are also now prefixed with a `## Release notes — v{version} ({date})` heading to add missing context to the README.
+  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
@@ -163,15 +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           |
+| 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.
 
@@ -222,10 +202,95 @@ Validation rules:
 - `successor` is optional; if present, it must be a non-empty string.
 - Full-tuple `(name, tagPrefix)` duplicates within `retiredPackages` are rejected.
 - Two entries sharing the same `tagPrefix` but different `name`s are accepted — this documents a package renamed within the repo before being retired.
-- A `tagPrefix` that collides with an active workspace's derived prefix or any declared `workspaces[].legacyIdentities[].tagPrefix` is rejected. A retired prefix cannot also be current or legacy.
 
 `show-tag-prefixes` currently does not render a dedicated "Retired packages" section (deferred). Declaring a retired entry is verifiable by confirming that its `tagPrefix` stops appearing under "Undeclared tag prefixes" in the `show-tag-prefixes` output.
 
+### Tag prefix collisions
+
+Tag prefixes from distinct owners must not be identical or be a strict prefix of one another. An owner is one of:
+
+- An active workspace, comprising its derived `tagPrefix` plus any declared `legacyIdentities[].tagPrefix`. Identities of the same workspace are one owner, so their prefixes are allowed to overlap (this represents the same package across renames).
+- A `retiredPackages[]` entry (one owner per entry).
+- The `project` block, when configured.
+
+release-kit resolves baseline tags via `git describe --match=<prefix>*`, so a strict-prefix overlap between distinct owners would cause that glob to return cross-matches against the wrong owner's history. For example, a project prefix of `v` collides with a workspace prefix of `vue-helpers-v`, since `git describe --match=v*` would return both project tags and `vue-helpers` tags.
+
+The rule is enforced at config load; the resulting error identifies both colliding declarations.
+
+### Project releases
+
+Some monorepos ship a single combined deliverable — a Chrome extension, a CLI binary, a packaged desktop app — for which the per-workspace tags and changelogs alone do not describe what the user actually receives. Declare the optional `project` block to add a project-level release stage that runs alongside the per-workspace pipeline.
+
+```typescript
+import type { ReleaseKitConfig } from '@williamthorsen/release-kit';
+
+const config: ReleaseKitConfig = {
+  // Empty object is enough to opt in. Every non-excluded workspace contributes.
+  project: {},
+};
+
+export default config;
+```
+
+When configured, each `release-kit prepare` run additionally:
+
+- Computes commits since the last project tag (`<tagPrefix><version>`), filtered to the union of every contributing workspace's paths.
+- Bumps the root `package.json`'s `version` field using the same bump-derivation rules as workspaces (or the `--bump=...` override).
+- Regenerates the root `./CHANGELOG.md` via `git-cliff`, scoped to the project's `tagPrefix` and contributing paths.
+- Emits `./.meta/changelog.json` (when `changelogJson.enabled`).
+- With `--with-release-notes`, additionally emits `./docs/RELEASE_NOTES.v<version>.md`.
+- Appends the project tag to `tmp/.release-tags` so `release-kit commit` and `release-kit tag` pick it up alongside per-workspace tags.
+
+If no contributing workspace has commits since the last project tag, the project release is silently skipped — same behavior as a per-workspace skip.
+
+#### `ProjectConfig`
+
+```typescript
+interface ProjectConfig {
+  tagPrefix?: string; // Defaults to 'v'
+}
+```
+
+| Field       | Default | Description                                                          |
+| ----------- | ------- | -------------------------------------------------------------------- |
+| `tagPrefix` | `'v'`   | Prefix for project tags. The full tag is `${tagPrefix}${newVersion}` |
+
+Contributing workspaces are implicit: every non-excluded discovered workspace contributes. There is no field to override the contributing set in this initial release; if a future consumer needs to release a workspace as a component but exclude it from the project release, that override can be added then.
+
+Validation rules:
+
+- The root `package.json` must exist and declare a `version` field. release-kit reports an error at config-load time if either is missing.
+- The `project` block is rejected in single-package mode (the implicit "all non-excluded workspaces contribute" rule is meaningless in a single-package repo).
+- Unknown fields inside `project` are rejected.
+
+CLI flag interactions:
+
+- `--dry-run` previews project artifacts alongside workspace artifacts; no files are written.
+- `--bump=major|minor|patch` propagates to the project release as a level chooser. It does not trigger a release on its own when there are no commits or no bump-worthy commits.
+- `--force` runs the project release even when no commits or no bump-worthy commits exist since the last project tag. Defaults to patch when `--bump` is not given; combine with `--bump=X` to release at a different level.
+- `--only` is rejected with an error when `project` is configured. `--only` is a surgical, single-workspace operation; combining it with a project release that rolls up every contributing workspace would create ambiguous semantics. To release a single workspace, use a config without a `project` block, or run a full `prepare` (no `--only`) to include the project release.
+- `--set-version` is rejected with an error when `project` is configured. `--set-version` operates on a single workspace, but a project release rolls up every contributing workspace; the two semantics don't compose. To use `--set-version`, run on a config without a `project` block.
+
+`--bump` and `--force` are orthogonal: `--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.
+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. (Behavioral change from earlier
+# release-kit versions, where --bump=X alone would force a release.)
+release-kit prepare --bump=minor
+```
+
 ### `VersionPatterns`
 
 Defines which commit types trigger major or minor bumps. Any recognized type not listed defaults to a patch bump.
@@ -239,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.
 
-| 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)       |               |
+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.
 
-Work types from your config are merged with these defaults by key — your entries override or extend, they don't replace the full set.
+#### `docs` reclassification
 
-`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.
+`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.
 
-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.
+#### `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:
+
+- **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
 
@@ -277,15 +405,15 @@ Release-notes sections are rendered in the declaration order of the merged work-
 
 Run release preparation with automatic workspace discovery.
 
-| Flag                         | Description                                                                                                  |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `--dry-run`                  | Preview changes without writing files                                                                        |
-| `--bump=major\|minor\|patch` | Override the bump type for all workspaces                                                                    |
-| `--set-version=X.Y.Z`        | Set an explicit canonical semver version; bypasses commit-derived bumps. Requires `--only` in monorepo mode. |
-| `--force`                    | Bypass the "no commits since last tag" check (requires `--bump`)                                             |
-| `--only=name1,name2`         | Only process the named workspaces (monorepo only)                                                            |
-| `--with-release-notes`       | Write per-workspace release-notes previews under `{workspacePath}/docs/`                                     |
-| `--help`, `-h`               | Show help                                                                                                    |
+| Flag                         | Description                                                                                                                                        |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--dry-run`                  | Preview changes without writing files                                                                                                              |
+| `--bump=major\|minor\|patch` | Override the bump type for all workspaces                                                                                                          |
+| `--set-version=X.Y.Z`        | Set an explicit canonical semver version; bypasses commit-derived bumps. Requires `--only` in monorepo mode.                                       |
+| `--force`                    | Release even when no commits or no bump-worthy commits exist since the last tag (defaults to patch; combine with `--bump=X` for a different level) |
+| `--only=name1,name2`         | Only process the named workspaces (monorepo only; rejected when a `project` block is configured)                                                   |
+| `--with-release-notes`       | Write per-workspace release-notes previews under `{workspacePath}/docs/`                                                                           |
+| `--help`, `-h`               | Show help                                                                                                                                          |
 
 Workspace names for `--only` match the package directory name (e.g., `arrays`, `release-kit`).
 
@@ -330,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.
@@ -373,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.
@@ -385,6 +562,26 @@ Manage GitHub label definitions via config-driven YAML files.
 
 `init` scaffolds `.config/sync-labels.config.ts` with auto-detected workspace scope labels and a `.github/workflows/sync-labels.yaml` caller workflow, then generates `.github/labels.yaml`. `generate` reads the config and writes `.github/labels.yaml`. `sync` triggers the workflow remotely — it requires the `gh` CLI and an existing workflow file.
 
+#### Published JSON Schema for `.meta/label-map.json`
+
+release-kit publishes a JSON Schema for `.meta/label-map.json` — a separate, generic data file that maps commit-prefix scopes and types to GitHub label names. The schema lives at `packages/release-kit/schemas/label-map.json` in this repo and is reachable via the stable raw URL:
+
+```
+https://github.com/williamthorsen/node-monorepo-tools/raw/release-kit-v<version>/packages/release-kit/schemas/label-map.json
+```
+
+Consumers reference it from the top of their `.meta/label-map.json`:
+
+```json
+{
+  "$schema": "https://github.com/williamthorsen/node-monorepo-tools/raw/release-kit-v<version>/packages/release-kit/schemas/label-map.json",
+  "types": { "feat": "feature", "fix": "fix" },
+  "scopes": { "audit": "scope:audit" }
+}
+```
+
+release-kit publishes the schema only; it does not generate `.meta/label-map.json`. Generation requires commit-prefix knowledge that lives outside release-kit (in agent-conventions tooling), and is owned by those consumers.
+
 ## 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:

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 @@
-4493cd8b695da653fc9ae7a81c0916cc0cb92c9acf3d560433b18cdd74f945a4
+64d26b06f4a6e205faa07a507fd64938899e4d635dd02b333016caf1d937a14e

package/dist/esm/assertCleanWorkingTree.js

@@ -6,7 +6,7 @@ function assertCleanWorkingTree() {
   }).trim();
   if (status.length > 0) {
     throw new Error(
-      "Working tree has uncommitted changes. Commit or stash them before running prepare, or use --no-git-checks to bypass this check."
+      "Working tree has uncommitted changes. Commit or stash them, or use --no-git-checks to bypass this check."
     );
   }
 }