@williamthorsen/release-kit 10.7.0 → 10.8.0

package/.meta/changelog.json

@@ -1,4 +1,32 @@
 [
+  {
+    "version": "10.8.0",
+    "date": "2026-09-15",
+    "sections": [
+      {
+        "title": "🎉 Features",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Allow the breaking marker on fix and perf commits (#818)",
+            "body": "- Makes `release-kit prepare` bump the major version for a `fix!` or `perf!` commit under the default breaking policies, instead of reporting a policy violation and bumping only the patch version while the changelog marked the entry breaking.\n- Corrects `docs/work-types.md` to state that a `breakingPolicies` map replaces the default policies rather than overriding individual types, and that release-kit treats every type omitted by the map as `optional`.",
+            "hash": "9d7bbe89deef6cdcedd999336e1cb8118bbf739f"
+          }
+        ]
+      },
+      {
+        "title": "🐛 Bug fixes",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Omit the breaking marker from changelog entries whose type forbids it (#819)",
+            "body": "- Makes the configured `breakingPolicies` map decide whether the changelog marks a commit breaking, as it already decides the version bump.",
+            "hash": "6ff7414f6f826fc85ae3337c4ac6bd9e38fe6ef7"
+          }
+        ]
+      }
+    ]
+  },
   {
     "version": "10.7.0",
     "date": "2026-09-15",

package/.readyup/kits/default.js

@@ -98,7 +98,7 @@ function translateGlob(pattern) {
 
 // .readyup/kits/default.ts
 function getMinVersion() {
-  const picked = { "version": "10.7.0" };
+  const picked = { "version": "10.8.0" };
   if (typeof picked["version"] !== "string") {
     throw new TypeError("release-kit/package.json: 'version' must be a string");
   }

package/.readyup/manifest.json

@@ -13,7 +13,7 @@
           "path": "kits/default.ts"
         },
         {
-          "hash": "a373c49d",
+          "hash": "a8611365",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -46,7 +46,7 @@
       "readyupVersion": "0.36.0",
       "source": "kits/default.ts",
       "sourceHash": "55ff5731",
-      "targetHash": "68976fc8"
+      "targetHash": "be5f29ad"
     },
     {
       "checklists": [

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## 10.8.0 — 2026-09-15
+
+### 🎉 Features
+
+- Allow the breaking marker on fix and perf commits (#818)
+
+  - Makes `release-kit prepare` bump the major version for a `fix!` or `perf!` commit under the default breaking policies, instead of reporting a policy violation and bumping only the patch version while the changelog marked the entry breaking.
+  - Corrects `docs/work-types.md` to state that a `breakingPolicies` map replaces the default policies rather than overriding individual types, and that release-kit treats every type omitted by the map as `optional`.
+
+### 🐛 Bug fixes
+
+- Omit the breaking marker from changelog entries whose type forbids it (#819)
+
+  - Makes the configured `breakingPolicies` map decide whether the changelog marks a commit breaking, as it already decides the version bump.
+
 ## 10.7.0 — 2026-09-15
 
 ### 🎉 Features

package/README.md

@@ -7,30 +7,20 @@ 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 from `git-cliff --context` output rendered in-process (with optional [editorial overrides](docs/editorial-overrides.md)).
 
 <!-- section:release-notes -->
-## Release notes — v10.7.0 (2026-09-15)
+## Release notes — v10.8.0 (2026-09-15)
 
 ### 🎉 Features
 
-- Fix scaffold error handling and cover every scaffolded workflow (#806)
+- Allow the breaking marker on fix and perf commits (#818)
 
-  - Adds a `create-github-release.yaml matches template` check to release-kit's ReadyUp kit, which warns when `.github/workflows/create-github-release.yaml` differs from the template for the detected repo type and skips in a repo that has not installed that workflow.
-  - Stops `v11y init --force` from replacing an existing `.config/v11y-check.config.json` with the defaults, which discarded the repo's thresholds and the allowlist maintained by `v11y sync`.
-
-  Migration: To reset `.config/v11y-check.config.json` to its defaults, delete the file and run `v11y init`, because `v11y init --force` now overwrites only `.github/workflows/audit.yaml`.
+  - Makes `release-kit prepare` bump the major version for a `fix!` or `perf!` commit under the default breaking policies, instead of reporting a policy violation and bumping only the patch version while the changelog marked the entry breaking.
+  - Corrects `docs/work-types.md` to state that a `breakingPolicies` map replaces the default policies rather than overriding individual types, and that release-kit treats every type omitted by the map as `optional`.
 
 ### 🐛 Bug fixes
 
-- Gate the trusted-publisher checks on trust-query capability (#786)
-
-  - Fixes the issue that the `npm-auto-publish` kit advised `npm trust github …` for every package when the npm session lacked the two-factor authentication that trust queries need.
-
-- Treat label names that differ only in case as one label (#808)
-
-  - Fixes the issue that `sync-labels generate` wrote a preset's `bug` and a local `Bug` to `.github/labels.yaml` as two labels, which made the first sync fail to create the second and every later sync rename the existing label back and forth.
-  - Lets a `labels` entry change a preset label's casing: `Bug` replaces a preset's `bug` and appears in the output as `Bug`, and `Bug: null` removes it.
-  - Makes `labels` keys that differ only in case a config error that names each group, such as `'bug' and 'Bug'`, since folding them would discard all but one without any sign in the output.
+- Omit the breaking marker from changelog entries whose type forbids it (#819)
 
-  Migration: Keep one of any keys in the `labels` record that differ only in case, and delete the others.
+  - Makes the configured `breakingPolicies` map decide whether the changelog marks a commit breaking, as it already decides the version bump.
 <!-- /section:release-notes -->
 
 ## Installation

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

@@ -209,7 +209,7 @@ Subcommands:
   sync          Overwrite the local work-types.json with the upstream contents
 
 Exit codes (check):
-  0    Match (or upstream missing — transitional warning printed)
+  0    Match (or upstream not found, with a warning)
   1    Drift detected
   2    Network error
   3    Schema mismatch
@@ -223,8 +223,8 @@ function showWorkTypesCheckHelp() {
 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.
+drift. Exit 0 on match, 1 on drift, 0 + warning when upstream is not found, 2 on network
+error, 3 on schema mismatch.
 
 Options:
   --help, -h    Show this help message

package/dist/esm/buildChangelogEntries.d.ts

@@ -23,4 +23,4 @@ export declare function stripGroupDecorations(group: string): string;
  * not whether git-cliff runs). This means dry-run exercises the full git-cliff toolchain and surfaces missing-binary,
  * malformed-config, and template-resolution failures earlier than before.
  */
-export declare function buildChangelogEntries(config: Pick<ReleaseConfig, 'cliffConfigPath' | 'changelogJson'>, tag: string, options?: GenerateChangelogOptions): ChangelogEntry[];
+export declare function buildChangelogEntries(config: Pick<ReleaseConfig, 'breakingPolicies' | 'changelogJson' | 'cliffConfigPath' | 'workTypes'>, tag: string, options?: GenerateChangelogOptions): ChangelogEntry[];

package/dist/esm/buildChangelogEntries.js

@@ -1,8 +1,8 @@
 import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
 import { extractVersion } from "./changelogJsonUtils.js";
-import { DEFAULT_WORK_TYPES } from "./defaults.js";
+import { DEFAULT_BREAKING_POLICIES, DEFAULT_WORK_TYPES } from "./defaults.js";
 import { extractMigration } from "./extractMigration.js";
-import { COMMIT_PREPROCESSOR_PATTERNS, PIPE_SCOPE_SOURCE } from "./parseCommitMessage.js";
+import { COMMIT_PREPROCESSOR_PATTERNS, parseCommitMessage, PIPE_SCOPE_SOURCE } from "./parseCommitMessage.js";
 import { resolveCliffConfigPath } from "./resolveCliffConfigPath.js";
 import { runGitCliff } from "./runGitCliff.js";
 import { stripEmojiPrefix } from "./stripEmojiPrefix.js";
@@ -30,7 +30,9 @@ export function buildChangelogEntries(config, tag, options) {
         const contextJson = runGitCliff(resolvedConfigPath, cliffArgs);
         const releases = parseCliffContext(contextJson);
         const devOnlySections = new Set(config.changelogJson.devOnlySections);
-        return transformReleases(releases, devOnlySections);
+        const workTypes = config.workTypes ?? DEFAULT_WORK_TYPES;
+        const breakingPolicies = config.breakingPolicies ?? DEFAULT_BREAKING_POLICIES;
+        return transformReleases(releases, devOnlySections, workTypes, breakingPolicies);
     }
     catch (error) {
         throw chainError(`Failed to build changelog entries for tag ${tag}`, error);
@@ -74,7 +76,7 @@ function toCliffContextCommit(value) {
     }
     return commit;
 }
-function transformReleases(releases, devOnlySections) {
+function transformReleases(releases, devOnlySections, workTypes, breakingPolicies) {
     const entries = [];
     const devOnlyNormalised = new Set([...devOnlySections].map(stripGroupDecorations));
     for (const release of releases) {
@@ -89,7 +91,7 @@ function transformReleases(releases, devOnlySections) {
             const group = stripCommentPrefix(commit.group ?? 'Other');
             const description = extractDescription(commit.message);
             const body = extractBody(commit.message);
-            const breaking = subjectHasBreakingMarker(commit.message);
+            const breaking = isBreakingUnderPolicy(commit, workTypes, breakingPolicies);
             let items = sectionMap.get(group);
             if (items === undefined) {
                 items = [];
@@ -132,6 +134,13 @@ function transformReleases(releases, devOnlySections) {
 function stripCommentPrefix(group) {
     return group.replace(HTML_COMMENT_PREFIX_PATTERN, '');
 }
+function isBreakingUnderPolicy(commit, workTypes, breakingPolicies) {
+    if (!subjectHasBreakingMarker(commit.message)) {
+        return false;
+    }
+    const parsed = parseCommitMessage(commit.message, commit.id ?? '', workTypes, undefined, { breakingPolicies });
+    return parsed?.breaking ?? true;
+}
 const SUBJECT_BREAKING_MARKER_PATTERN = new RegExp(String.raw `^(?:${PIPE_SCOPE_SOURCE}\|)?\w+(?:\([^)]+\))?!:`);
 function subjectHasBreakingMarker(message) {
     let subject = message.split('\n', 1)[0] ?? '';

package/dist/esm/checkWorkTypesDrift.d.ts

@@ -4,7 +4,7 @@ export declare const UPSTREAM_WORK_TYPES_URL = "https://raw.githubusercontent.co
 export interface DriftCheckResult {
     /**
      * Process exit code semantics:
-     * - `0` — match (or upstream missing/transitional, with a warning).
+     * - `0` — match (or upstream not found, with a warning).
      * - `1` — drift detected.
      * - `2` — network error.
      * - `3` — schema mismatch (upstream JSON does not parse or fails the schema invariants).
@@ -27,8 +27,7 @@ export interface CheckWorkTypesDriftDependencies {
  *
  * Failure modes:
  * - Network error → exit 2 with a diagnostic.
- * - Upstream 404 → exit 0 with a transitional warning (codeassembly hasn't published the
- *   JSON yet; the check is informational while migration is in flight).
+ * - Upstream 404 → exit 0 with a warning.
  * - Schema mismatch → exit 3 with a diagnostic.
  * - Drift → exit 1 with a unified-diff-style message.
  * - Match → exit 0.

package/dist/esm/checkWorkTypesDrift.js

@@ -38,7 +38,7 @@ export async function checkWorkTypesDrift(dependencies = {}) {
     if (response.status === 404) {
         return {
             exitCode: 0,
-            message: `Upstream work-types.json not yet published at ${url}; skipping drift check.`,
+            message: `Upstream work-types.json not found at ${url}; skipping drift check.`,
         };
     }
     if (!response.ok) {

package/dist/esm/parseCommitMessage.d.ts

@@ -15,10 +15,9 @@ export type PolicyViolationSurface = 'prefix' | 'body';
 /**
  * Callback invoked when `parseCommitMessage` detects a `!`-policy violation.
  *
- * Two-tier policy: at write-time (commit-msg hook, OOS for ticket #355), violations are
- * rejected outright; at release-time (this parser), violations are warn-and-continue so
- * legacy log entries don't block releases. Callers (`decideRelease`, `releasePrepareMono`,
- * etc.) collect callback invocations and surface them in the release report.
+ * The parser warns and continues on a violation, so legacy log entries don't block releases.
+ * Callers (`decideRelease`, `releasePrepareMono`, etc.) collect callback invocations and
+ * surface them in the release report.
  */
 export type PolicyViolationHandler = (commit: Commit, type: string, surface: PolicyViolationSurface) => void;
 /** Optional configuration for `parseCommitMessage` beyond the core inputs. */
@@ -47,6 +46,6 @@ export interface ParseCommitMessageOptions {
  * `!`-policy enforcement is **release-time tolerant**: when the resolved type's policy
  * forbids `!`, the marker is dropped from the parse (`breaking: false`) and
  * `onPolicyViolation` is invoked. When the policy requires `!`, a bare type triggers the
- * same warning path. The strict write-time gate (commit-msg hook) is out of scope.
+ * same warning path.
  */
 export declare function parseCommitMessage(message: string, hash: string, workTypes: Record<string, WorkTypeConfig>, scopeAliases?: Record<string, string>, options?: ParseCommitMessageOptions): ParsedCommit | undefined;

package/dist/esm/types.d.ts

@@ -11,19 +11,20 @@ export interface ChangelogItem {
     /**
      * Whether this item represents a breaking change.
      *
-     * `true` when the commit subject carries the `!` prefix (e.g. `feat!:` or `drop(scope)!:`).
-     * The `BREAKING CHANGE:` body footer is intentionally NOT considered here — only the prefix
-     * `!` marks a changelog item as breaking. Renderers prefix breaking-item bullets with the
-     * marker constructed from `WORK_TYPES_DATA.markers.breaking` (rendered as `🚨 **Breaking:** `
-     * with the canonical SSOT values) to surface them prominently in release notes.
+     * `true` when the commit subject carries the `!` prefix (e.g. `feat!:` or `drop(scope)!:`) and
+     * the commit's work-type policy permits it, so the item agrees with the version bump.
+     * The `BREAKING CHANGE:` body footer is intentionally NOT considered here. Renderers prefix
+     * breaking-item bullets with the marker constructed from `WORK_TYPES_DATA.markers.breaking`
+     * (rendered as `🚨 **Breaking:** ` with the canonical SSOT values) to surface them prominently
+     * in release notes.
      */
     breaking?: boolean;
     /**
      * Migration instruction for a consumer, taken from the `Migration:` paragraph of `body`.
      *
      * Derived from `body` wherever `body` is set, and absent where the body carries no labeled
-     * paragraph. Independent of `breaking`: a `fix` that tightens validation cannot carry `!` under
-     * the default breaking policy and still imposes a migration. `body` keeps the paragraph, so
+     * paragraph. Independent of `breaking`: a `deprecate` commit cannot carry `!` under the default
+     * breaking policy and still calls for a migration. `body` keeps the paragraph, so
      * `CHANGELOG.md` goes on rendering it in place.
      */
     migration?: string;

package/dist/esm/work-types.json

@@ -1,133 +1,149 @@
 {
   "$schema": "./work-types.schema.json",
+  "markers": {
+    "breaking": {
+      "emoji": "🚨",
+      "label": "Breaking"
+    }
+  },
   "tiers": ["public", "internal", "process"],
   "types": [
     {
-      "tier": "public",
-      "key": "feat",
       "aliases": ["feature"],
+      "breakingPolicy": "optional",
+      "description": "A change that gives consumers a new capability or extends an existing one.",
       "emoji": "🎉",
+      "key": "feat",
       "label": "Features",
-      "breakingPolicy": "optional"
+      "tier": "public"
     },
     {
-      "tier": "public",
-      "key": "drop",
       "aliases": [],
+      "breakingPolicy": "required",
+      "description": "A change that removes a capability or surface on which consumers depend.",
       "emoji": "🪦",
+      "key": "drop",
       "label": "Removed",
-      "breakingPolicy": "required"
+      "tier": "public"
     },
     {
-      "tier": "public",
-      "key": "deprecate",
       "aliases": [],
+      "breakingPolicy": "forbidden",
+      "description": "A change that marks a capability or surface for removal while the capability or surface keeps working.",
       "emoji": "🗑️",
+      "key": "deprecate",
       "label": "Deprecated",
-      "breakingPolicy": "forbidden"
+      "tier": "public"
     },
     {
-      "tier": "public",
-      "key": "fix",
       "aliases": ["bugfix"],
+      "breakingPolicy": "optional",
+      "description": "A change that corrects behavior that consumers meet and that differs from what was intended.",
       "emoji": "🐛",
+      "key": "fix",
       "label": "Bug fixes",
-      "breakingPolicy": "forbidden"
+      "tier": "public"
     },
     {
-      "tier": "public",
-      "key": "sec",
       "aliases": ["security"],
+      "breakingPolicy": "optional",
+      "description": "A change that closes a vulnerability or hardens a consumer-facing surface against attack.",
       "emoji": "🔒",
+      "key": "sec",
       "label": "Security",
-      "breakingPolicy": "optional"
+      "tier": "public"
     },
     {
-      "tier": "public",
-      "key": "perf",
       "aliases": ["performance"],
+      "breakingPolicy": "optional",
+      "description": "A change that reduces the time, memory, or other resources that consumer-facing work uses, without changing its result.",
       "emoji": "⚡",
+      "key": "perf",
       "label": "Performance",
-      "breakingPolicy": "forbidden"
+      "tier": "public"
     },
     {
-      "tier": "internal",
-      "key": "internal",
       "aliases": ["utility"],
+      "breakingPolicy": "forbidden",
+      "description": "A change that adds or extends a capability that consumers do not use directly, such as a helper or an internal module.",
       "emoji": "🏗️",
+      "key": "internal",
       "label": "Internal features",
-      "breakingPolicy": "forbidden"
+      "tier": "internal"
     },
     {
-      "tier": "internal",
-      "key": "refactor",
       "aliases": [],
+      "breakingPolicy": "forbidden",
+      "description": "A change that restructures existing code without changing its behavior.",
       "emoji": "♻️",
+      "key": "refactor",
       "label": "Refactoring",
-      "breakingPolicy": "forbidden"
+      "tier": "internal"
     },
     {
-      "tier": "internal",
-      "key": "tests",
       "aliases": ["test"],
+      "breakingPolicy": "forbidden",
+      "description": "A change confined to tests, test fixtures, or test helpers, including one that unblocks a build or a type check.",
       "emoji": "🧪",
+      "key": "tests",
       "label": "Tests",
-      "breakingPolicy": "forbidden"
+      "tier": "internal"
     },
     {
-      "tier": "process",
-      "key": "tooling",
       "aliases": [],
+      "breakingPolicy": "forbidden",
+      "description": "A change to the tools used to develop the project: build, lint, formatting, and release configuration, and development scripts.",
       "emoji": "⚙️",
+      "key": "tooling",
       "label": "Tooling",
-      "breakingPolicy": "forbidden"
+      "tier": "process"
     },
     {
-      "tier": "process",
-      "key": "ci",
       "aliases": [],
+      "breakingPolicy": "forbidden",
+      "description": "A change to continuous-integration workflows and their configuration.",
       "emoji": "👷",
+      "key": "ci",
       "label": "CI",
-      "breakingPolicy": "forbidden"
+      "tier": "process"
     },
     {
-      "tier": "process",
-      "key": "deps",
       "aliases": ["dep"],
+      "breakingPolicy": "forbidden",
+      "description": "A change that adds, removes, or upgrades a dependency, including its lockfile and version-catalog entries.",
       "emoji": "📦",
+      "key": "deps",
       "label": "Dependencies",
-      "breakingPolicy": "forbidden"
+      "tier": "process"
     },
     {
-      "tier": "process",
-      "key": "ai",
       "aliases": [],
+      "breakingPolicy": "forbidden",
+      "description": "A change to guidance on working in the repository itself, such as its `AGENTS.md` or a repo-local skill, or to the repository's agent configuration.",
       "emoji": "🤖",
+      "key": "ai",
       "label": "Agentic support",
-      "breakingPolicy": "forbidden"
+      "tier": "process"
     },
     {
-      "tier": "process",
-      "key": "docs",
       "aliases": ["doc"],
+      "breakingPolicy": "forbidden",
+      "description": "A change to documentation for human readers, such as a README, a guide, or a code comment.",
       "emoji": "📚",
+      "key": "docs",
       "label": "Documentation",
-      "breakingPolicy": "forbidden"
+      "tier": "process"
     },
     {
-      "tier": "process",
-      "key": "fmt",
       "aliases": [],
+      "breakingPolicy": "forbidden",
+      "description": "A change to formatting alone, such as whitespace or line wrapping, that leaves the content unchanged.",
       "emoji": "🎨",
+      "excludedFromChangelog": true,
+      "key": "fmt",
       "label": "Formatting",
-      "breakingPolicy": "forbidden",
-      "excludedFromChangelog": true
+      "tier": "process"
     }
   ],
-  "markers": {
-    "breaking": {
-      "emoji": "🚨",
-      "label": "Breaking"
-    }
-  }
+  "version": "1.1.0"
 }

package/dist/esm/work-types.schema.json

@@ -4,13 +4,18 @@
   "title": "Work types",
   "description": "Canonical taxonomy of commit work types used by release-kit. Drives section ordering, audience classification, and the `!` (breaking) policy. The structured single-source-of-truth for everything that previously lived in `DEFAULT_WORK_TYPES` and `cliff.toml.template` group definitions.",
   "type": "object",
-  "required": ["tiers", "types", "markers"],
+  "required": ["tiers", "types", "markers", "version"],
   "additionalProperties": false,
   "properties": {
     "$schema": {
       "type": "string",
       "description": "Optional reference to this schema for IDE validation."
     },
+    "version": {
+      "type": "string",
+      "description": "Semantic version of the data shape. Bumped when the structure changes in a way that breaks downstream consumers.",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
     "tiers": {
       "type": "array",
       "description": "Render tiers in canonical order. Each entry's `tier` field must reference one of these names.",
@@ -55,7 +60,7 @@
     },
     "workType": {
       "type": "object",
-      "required": ["tier", "key", "aliases", "emoji", "label", "breakingPolicy"],
+      "required": ["tier", "key", "aliases", "emoji", "label", "breakingPolicy", "description"],
       "additionalProperties": false,
       "properties": {
         "tier": {
@@ -84,6 +89,11 @@
           "description": "Human-readable section label (rendered as `${emoji} ${label}` in changelogs and release notes).",
           "minLength": 1
         },
+        "description": {
+          "type": "string",
+          "description": "The changes that the type covers, read by an agent choosing a type for a change.",
+          "minLength": 1
+        },
         "breakingPolicy": {
           "type": "string",
           "description": "Policy governing the `!` (breaking) marker for this type. `forbidden`: `!` is a policy violation. `optional`: `!` is allowed. `required`: bare type is a policy violation; only the `!` form is accepted.",

package/dist/esm/workTypesData.d.ts

@@ -1,15 +1,13 @@
 /**
- * Canonical work-types data — runtime mirror of `work-types.json`.
+ * Canonical work-types data: the runtime mirror of `work-types.json`.
  *
- * `work-types.json` is the canonical SSOT for the taxonomy and is the file
- * `release-kit work-types check` / `:sync` operate on. This `.ts` mirror exists for
- * runtime consumption: ESM JSON imports require an `import attributes` clause that
- * esbuild's `bundle: false` mode strips, so a plain TS module is the most reliable way
- * to ship the data to consumers.
+ * `work-types.json` is release-kit's copy of the codeassembly canonical. This `.ts` mirror exists for
+ * runtime consumption: The compiler baseline does not enable JSON module imports, and a TS constant keeps
+ * `breakingPolicy` typed as its three-value union.
  *
- * A drift test (`workTypesData.unit.test.ts`) asserts that this constant deep-equals the
- * parsed contents of `work-types.json`. To change the taxonomy, edit BOTH files (or run
- * `nmr work-types:sync` to pull from upstream).
+ * `nmr work-types:sync` updates only the JSON, so copy its change here by hand. A drift test
+ * (`workTypesData.unit.test.ts`) asserts that this constant deep-equals the parsed contents of
+ * `work-types.json`.
  */
 /** Schema for a single entry. */
 export interface WorkTypeEntry {
@@ -18,6 +16,7 @@ export interface WorkTypeEntry {
     aliases: string[];
     emoji: string;
     label: string;
+    description: string;
     breakingPolicy: 'forbidden' | 'optional' | 'required';
     excludedFromChangelog?: boolean;
 }
@@ -34,6 +33,8 @@ export interface MarkerEntry {
 }
 /** Schema for the full data. */
 export interface WorkTypesData {
+    /** Semantic version of the data shape, as declared by the upstream canonical. */
+    version: string;
     tiers: string[];
     types: WorkTypeEntry[];
     /**

package/dist/esm/workTypesData.js

@@ -1,18 +1,60 @@
 export const WORK_TYPES_DATA = {
+    version: '1.1.0',
     tiers: ['public', 'internal', 'process'],
     types: [
-        { tier: 'public', key: 'feat', aliases: ['feature'], emoji: '🎉', label: 'Features', breakingPolicy: 'optional' },
-        { tier: 'public', key: 'drop', aliases: [], emoji: '🪦', label: 'Removed', breakingPolicy: 'required' },
-        { tier: 'public', key: 'deprecate', aliases: [], emoji: '🗑️', label: 'Deprecated', breakingPolicy: 'forbidden' },
-        { tier: 'public', key: 'fix', aliases: ['bugfix'], emoji: '🐛', label: 'Bug fixes', breakingPolicy: 'forbidden' },
-        { tier: 'public', key: 'sec', aliases: ['security'], emoji: '🔒', label: 'Security', breakingPolicy: 'optional' },
+        {
+            tier: 'public',
+            key: 'feat',
+            aliases: ['feature'],
+            emoji: '🎉',
+            label: 'Features',
+            description: 'A change that gives consumers a new capability or extends an existing one.',
+            breakingPolicy: 'optional',
+        },
+        {
+            tier: 'public',
+            key: 'drop',
+            aliases: [],
+            emoji: '🪦',
+            label: 'Removed',
+            description: 'A change that removes a capability or surface on which consumers depend.',
+            breakingPolicy: 'required',
+        },
+        {
+            tier: 'public',
+            key: 'deprecate',
+            aliases: [],
+            emoji: '🗑️',
+            label: 'Deprecated',
+            description: 'A change that marks a capability or surface for removal while the capability or surface keeps working.',
+            breakingPolicy: 'forbidden',
+        },
+        {
+            tier: 'public',
+            key: 'fix',
+            aliases: ['bugfix'],
+            emoji: '🐛',
+            label: 'Bug fixes',
+            description: 'A change that corrects behavior that consumers meet and that differs from what was intended.',
+            breakingPolicy: 'optional',
+        },
+        {
+            tier: 'public',
+            key: 'sec',
+            aliases: ['security'],
+            emoji: '🔒',
+            label: 'Security',
+            description: 'A change that closes a vulnerability or hardens a consumer-facing surface against attack.',
+            breakingPolicy: 'optional',
+        },
         {
             tier: 'public',
             key: 'perf',
             aliases: ['performance'],
             emoji: '⚡',
             label: 'Performance',
-            breakingPolicy: 'forbidden',
+            description: 'A change that reduces the time, memory, or other resources that consumer-facing work uses, without changing its result.',
+            breakingPolicy: 'optional',
         },
         {
             tier: 'internal',
@@ -20,6 +62,7 @@ export const WORK_TYPES_DATA = {
             aliases: ['utility'],
             emoji: '🏗️',
             label: 'Internal features',
+            description: 'A change that adds or extends a capability that consumers do not use directly, such as a helper or an internal module.',
             breakingPolicy: 'forbidden',
         },
         {
@@ -28,19 +71,61 @@ export const WORK_TYPES_DATA = {
             aliases: [],
             emoji: '♻️',
             label: 'Refactoring',
+            description: 'A change that restructures existing code without changing its behavior.',
+            breakingPolicy: 'forbidden',
+        },
+        {
+            tier: 'internal',
+            key: 'tests',
+            aliases: ['test'],
+            emoji: '🧪',
+            label: 'Tests',
+            description: 'A change confined to tests, test fixtures, or test helpers, including one that unblocks a build or a type check.',
+            breakingPolicy: 'forbidden',
+        },
+        {
+            tier: 'process',
+            key: 'tooling',
+            aliases: [],
+            emoji: '⚙️',
+            label: 'Tooling',
+            description: 'A change to the tools used to develop the project: build, lint, formatting, and release configuration, and development scripts.',
+            breakingPolicy: 'forbidden',
+        },
+        {
+            tier: 'process',
+            key: 'ci',
+            aliases: [],
+            emoji: '👷',
+            label: 'CI',
+            description: 'A change to continuous-integration workflows and their configuration.',
+            breakingPolicy: 'forbidden',
+        },
+        {
+            tier: 'process',
+            key: 'deps',
+            aliases: ['dep'],
+            emoji: '📦',
+            label: 'Dependencies',
+            description: 'A change that adds, removes, or upgrades a dependency, including its lockfile and version-catalog entries.',
+            breakingPolicy: 'forbidden',
+        },
+        {
+            tier: 'process',
+            key: 'ai',
+            aliases: [],
+            emoji: '🤖',
+            label: 'Agentic support',
+            description: "A change to guidance on working in the repository itself, such as its `AGENTS.md` or a repo-local skill, or to the repository's agent configuration.",
             breakingPolicy: 'forbidden',
         },
-        { tier: 'internal', key: 'tests', aliases: ['test'], emoji: '🧪', label: 'Tests', breakingPolicy: 'forbidden' },
-        { tier: 'process', key: 'tooling', aliases: [], emoji: '⚙️', label: 'Tooling', breakingPolicy: 'forbidden' },
-        { tier: 'process', key: 'ci', aliases: [], emoji: '👷', label: 'CI', breakingPolicy: 'forbidden' },
-        { tier: 'process', key: 'deps', aliases: ['dep'], emoji: '📦', label: 'Dependencies', breakingPolicy: 'forbidden' },
-        { tier: 'process', key: 'ai', aliases: [], emoji: '🤖', label: 'Agentic support', breakingPolicy: 'forbidden' },
         {
             tier: 'process',
             key: 'docs',
             aliases: ['doc'],
             emoji: '📚',
             label: 'Documentation',
+            description: 'A change to documentation for human readers, such as a README, a guide, or a code comment.',
             breakingPolicy: 'forbidden',
         },
         {
@@ -49,6 +134,7 @@ export const WORK_TYPES_DATA = {
             aliases: [],
             emoji: '🎨',
             label: 'Formatting',
+            description: 'A change to formatting alone, such as whitespace or line wrapping, that leaves the content unchanged.',
             breakingPolicy: 'forbidden',
             excludedFromChangelog: true,
         },

package/docs/changelogs.md

@@ -8,13 +8,13 @@ Neither `CHANGELOG.md` nor `.meta/changelog.json` reaches a published tarball on
 
 Each item under a section in `.meta/changelog.json` carries one required field and four optional ones:
 
-| Field         | Type      | Meaning                                                                                                                                        |
-| ------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `description` | `string`  | The bullet headline, taken from the commit subject with the ticket ID and type prefix stripped.                                                |
-| `body`        | `string`  | The commit body, with trailing trailer metadata stripped.                                                                                      |
-| `breaking`    | `boolean` | Present and `true` where the commit subject carried the `!` prefix. See [`!` (breaking change) policy](work-types.md#-breaking-change-policy). |
-| `migration`   | `string`  | The migration step for a consumer. See below.                                                                                                  |
-| `hash`        | `string`  | The full commit SHA, and the key on which an override entry matches. Absent on synthetic propagation entries.                                  |
+| Field         | Type      | Meaning                                                                                                                                                                         |
+| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `description` | `string`  | The bullet headline, taken from the commit subject with the ticket ID and type prefix stripped.                                                                                 |
+| `body`        | `string`  | The commit body, with trailing trailer metadata stripped.                                                                                                                       |
+| `breaking`    | `boolean` | Present and `true` where the commit subject carried the `!` prefix and the commit's type permits it. See [`!` (breaking change) policy](work-types.md#-breaking-change-policy). |
+| `migration`   | `string`  | The migration step for a consumer. See below.                                                                                                                                   |
+| `hash`        | `string`  | The full commit SHA, and the key on which an override entry matches. Absent on synthetic propagation entries.                                                                   |
 
 Every optional field is omitted rather than emitted as `null`, so a consumer tests for presence.
 
@@ -32,7 +32,7 @@ A commit body states a migration step as a paragraph opening with the literal la
 
 Three properties are worth knowing:
 
-- **It is independent of `breaking`.** A `fix` cannot carry `!` under the default breaking policy, and a `fix` that tightens validation still imposes a migration. Filter on `migration` to find every step; filter on `breaking` to find every breaking change.
+- **It is independent of `breaking`.** A `deprecate` cannot carry `!` under the default breaking policy, and a `deprecate` still calls for a migration. Filter on `migration` to find every step; filter on `breaking` to find every breaking change.
 - **`body` keeps the paragraph.** The field is an extraction, not a move, so `CHANGELOG.md` and `.meta/changelog.json` go on agreeing.
 - **It is derived, not authored.** `migration` is not a field an override file can set (see [File shape](editorial-overrides.md#file-shape)); it is re-derived from whatever `body` an override installs, and cleared where that body carries no labeled paragraph. To change the migration text, override `body`.
 

package/docs/work-types.md

@@ -2,16 +2,16 @@
 
 The taxonomy against which release-kit parses commits: its tiers, the breaking-change policy, section markers, customization, and the commands that compare it with its upstream.
 
-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.
+release-kit bundles a copy of the codeassembly canonical taxonomy in `packages/release-kit/src/work-types.json`, kept level by `release-kit work-types sync`. The taxonomy is split into three tiers that drive section rendering and audience classification.
 
 | Tier     | Key         | Header                    | Aliases       | `!` policy   |
 | -------- | ----------- | ------------------------- | ------------- | ------------ |
 | public   | `feat`      | 🎉 Features               | `feature`     | optional     |
 | public   | `drop`      | 🪦 Removed                |               | **required** |
 | public   | `deprecate` | 🗑️ Deprecated             |               | forbidden    |
-| public   | `fix`       | 🐛 Bug fixes              | `bugfix`      | forbidden    |
+| public   | `fix`       | 🐛 Bug fixes              | `bugfix`      | optional     |
 | public   | `sec`       | 🔒 Security               | `security`    | optional     |
-| public   | `perf`      | ⚡ Performance            | `performance` | forbidden    |
+| public   | `perf`      | ⚡ Performance            | `performance` | optional     |
 | internal | `internal`  | 🏗️ Internal features      | `utility`     | forbidden    |
 | internal | `refactor`  | ♻️ Refactoring            |               | forbidden    |
 | internal | `tests`     | 🧪 Tests                  | `test`        | forbidden    |
@@ -38,18 +38,15 @@ Section render order is **tier order (`public` → `internal` → `process`), th
 
 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.
+- `optional` (`feat`, `fix`, `sec`, `perf`): `!` is allowed; both `type:` and `type!:` parse cleanly. Any of these can break consumers, and the marker records when one does: A fix can break consumers who relied on the defective behavior, and a performance change can break a contract to achieve its gain.
+- `forbidden` (`deprecate` and every `internal`- and `process`-tier type): `!` is a policy violation. Deprecating a surface keeps it working, and removing it is a `drop`. Internal- and process-tier work does not face consumers; a change that breaks consumers faces them and therefore takes a public-tier type.
+- `required` (`drop`): Bare `drop:` is a policy violation; only `drop!:` is accepted. Removing a public surface always breaks consumers, and the `!` form makes that explicit.
 
-### Two-tier policy enforcement
+### Policy enforcement
 
-The `!` policy operates at two distinct levels with different semantics:
+`parseCommitMessage` enforces the `!` policy at release time and treats a violation as a warning. Commits already in the log cannot be rewritten, so a policy-violating commit is parsed using its canonical type with `breaking: false` (the `!` is dropped from the parse) and an `onPolicyViolation` callback fires. Callers (`decideRelease` etc.) can collect these warnings and surface them in the release report. A single legacy `internal!` in a year-old log does not block releases.
 
-- **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.
+A `BREAKING CHANGE:` body footer on a `forbidden`-policy type triggers the same warning path as the prefix `!` does: A type that cannot be breaking is parsed as non-breaking whichever surface carries the signal.
 
 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:
 
@@ -62,17 +59,23 @@ arrays
   📦 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.
+To customize, set `breakingPolicies` in `release-kit.config.ts`. The map replaces the default policies rather than merging with them, and the parser treats any type that the map omits as `'optional'`: A config that changes one type lists every policy that it keeps, and `{}` disables enforcement entirely. 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:
+Items whose commit subject carries the `!` prefix (e.g. `feat!`, `drop!`, `feat(api)!`) on a type whose policy permits it are rendered with a `🚨 **Breaking:** ` prefix on the bullet:
 
 ```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.
+The marker agrees with the version bump:
+
+- A `forbidden`-policy type carrying `!`, such as `refactor!`, gets no marker, just as its `!` raises no bump; the prepare report lists it as a policy violation. An [editorial override](editorial-overrides.md) that sets `breaking: true` restores the marker for one entry.
+- The configured `breakingPolicies` map, `{}` included, decides which types permit the marker.
+- A commit whose type the parser cannot resolve has no policy, so its `!` prefix alone decides.
+
+A `BREAKING CHANGE:` body footer on its own does **not** retroactively mark a changelog item as breaking, even on a type whose policy permits `!`; the changelog signal is tied to the commit prefix. This avoids surprise breaking-marker appearances for older commits written under earlier conventions.
 
 The emoji and label of this marker are sourced from the `markers.breaking` entry in `work-types.json` (see [Section markers](#section-markers)) so consumers that render their own breaking-changes section draw from the same SSOT.
 
@@ -104,18 +107,10 @@ The default `devOnlySections` (excluded from public release notes but still writ
 
 Manage the canonical work-types taxonomy used by changelog and release-notes generation.
 
-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.
+`check` exits 0 on a match, 1 on drift, 2 when the upstream fetch fails, and 3 when either file is not valid JSON or the upstream fails the shape check. When the upstream URL returns 404, `check` exits 0 with a warning.
 
 These commands are also exposed as `nmr work-types:check` / `nmr work-types:sync` from any package directory.
 
 ### Authenticated fetches
 
-When the upstream codeassembly repo is private, both `check` and `sync` need a GitHub token to fetch the canonical `work-types.json`. Set `GITHUB_TOKEN` in the environment and the commands send `Authorization: Bearer <token>` automatically; without it, requests are unauthenticated and a private upstream will return 404.
-
-```sh
-# Source from `gh auth` for local runs:
-export GITHUB_TOKEN=$(gh auth token)
-pnpm exec release-kit work-types check
-```
-
-The token needs `contents: read` on the codeassembly repo (fine-grained PAT scope) or the equivalent classic-PAT scope. A token without sufficient scope still produces a 404 — same response as a missing upstream — so a misconfigured token degrades to the transitional-warning path rather than failing loudly. CI wiring against private upstream is deferred until either codeassembly is publicly readable or a cross-repo PAT is provisioned as a workflow secret.
+The upstream codeassembly repo is public, so `check` and `sync` need no token. When `GITHUB_TOKEN` is set in the environment, both commands send it as `Authorization: Bearer <token>`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/release-kit",
-  "version": "10.7.0",
+  "version": "10.8.0",
   "description": "Version-bumping and changelog-generation toolkit for release workflows",
   "keywords": [
     "changelog",