@williamthorsen/release-kit 4.5.0 → 4.6.0

package/CHANGELOG.md

@@ -2,228 +2,251 @@
 
 All notable changes to this project will be documented in this file.
 
-## [release-kit-v4.5.0] - 2026-04-06
+## [release-kit-v4.6.0] - 2026-04-15
 
 ### Features
 
-- Release-kit|feat: Add spike to common repo labels
+- Guard `prepare` against dirty working tree (#188)
+
+  Add a clean-working-tree check at the start of `prepareCommand` that exits with an error when `git status --porcelain` reports uncommitted changes. This prevents the double-bump problem where running `prepare` multiple times bumps the version each time from the already-bumped `package.json`.
+
+  The check can be bypassed with `--no-git-checks` (`-n`) and is automatically skipped during `--dry-run`.
+
+- Add sync-labels drift detection to release-kit readyup kit (#190)
+
+  Adds readyup kit checks that detect when a consumer's sync-labels workflow or generated labels file has drifted from the current templates and presets. The `generate` command now embeds per-preset content hashes in the `labels.yaml` header, enabling hash-based staleness detection.
+
+- Improve changelog formatting & add cliff config drift detection (#193)
+
+  Improves changelog generation: cleanly indented commit bodies, stripped type prefixes, and no unticketed noise. Adds hash-based drift detection so the rdy kit warns when a consumer's local cliff config falls behind the current template. Fixes a latent bug where git-cliff rejected the bundled `.template` file extension.
+
+- Generate release notes distinct from changelogs (#199)
+
+  Adds structured changelog generation with audience tagging to the `release-kit` package, enabling GitHub Release creation and npm README injection with user-facing release notes filtered from developer-only sections. The existing CHANGELOG.md pipeline is unchanged; a new `.meta/changelog.json` artifact is generated in parallel during `release-kit prepare`, and consumed during `release-kit publish` to create GitHub Releases and inject release notes into the published package's README.
+
+### Refactoring
+
+- Decouple GitHub Release creation and README injection from npm publish (#203)
+
+  Makes GitHub Release creation available as a standalone CLI command (`release-kit github-release`) and removes README injection logic from the publish function. Non-published projects (applications, websites, internal tools) can now create GitHub Releases independently after `release-kit prepare`, and the inject/restore lifecycle is managed by the command layer rather than buried inside business logic.
+
+### Tooling
+
+- Enable automated publication to npm (#187)
+
+  Prepares the repository for reliable tag-triggered npm publishing by adding missing package metadata, standardizing licensing, and introducing a readyup kit that validates publish readiness across all packages.
+
+## [release-kit-v4.5.1] - 2026-04-10
+
+### Bug fixes
+
+- Fix sync-labels init scaffolding output (#179)
+
+  Fixes three issues in `release-kit sync-labels init` scaffolding output that cause immediate errors for consumers: adds missing workflow permissions, corrects config template indentation from 2 to 4 spaces, and switches YAML quoting from double to single quotes.
 
 ## [release-kit-v4.4.0] - 2026-04-04
 
 ### Documentation
 
-- #135 release-kit|docs: Refine README to match preflight documentation standard (#138)
+- Refine README to match preflight documentation standard (#138)
 
-Restructures the release-kit README to match the documentation standard established by the preflight README (#114). Reorders sections to follow the cross-package convention, converts CLI flag listings from code blocks to tables, adds representative `prepare --dry-run` output to the quick start, and condenses ~90 lines of inline workflow YAML into a summary with an inputs table and trigger examples. Fixes several accuracy gaps found by verifying documentation against source.
+  Restructures the release-kit README to match the documentation standard established by the preflight README (#114). Reorders sections to follow the cross-package convention, converts CLI flag listings from code blocks to tables, adds representative `prepare --dry-run` output to the quick start, and condenses ~90 lines of inline workflow YAML into a summary with an inputs table and trigger examples. Fixes several accuracy gaps found by verifying documentation against source.
 
 ### Features
 
-- #142 feat: Add --version flag to nmr and release-kit (#143)
+- Add --version flag to nmr and release-kit (#143)
 
-Adds `--version` / `-V` support to the `nmr` and `release-kit` CLIs, matching the existing `preflight` behavior. Moves the build-time version generation script to the shared `config/` directory so all three packages use a single `generateVersion.ts`.
+  Adds `--version` / `-V` support to the `nmr` and `release-kit` CLIs, matching the existing `preflight` behavior. Moves the build-time version generation script to the shared `config/` directory so all three packages use a single `generateVersion.ts`.
 
-- #150 feat: Detect and report missing build output in bin wrappers (#152)
+- Detect and report missing build output in bin wrappers (#152)
 
-Adds try/catch with `ERR_MODULE_NOT_FOUND` detection to all six bin wrappers across `nmr`, `preflight`, and `release-kit`. Previously, five of the six wrappers used bare `import()` calls that produced cryptic unhandled rejections when `dist/` was missing, and `preflight`'s existing try/catch gave no actionable guidance.
+  Adds try/catch with `ERR_MODULE_NOT_FOUND` detection to all six bin wrappers across `nmr`, `preflight`, and `release-kit`. Previously, five of the six wrappers used bare `import()` calls that produced cryptic unhandled rejections when `dist/` was missing, and `preflight`'s existing try/catch gave no actionable guidance.
 
 ### Refactoring
 
-- #88 release-kit|refactor: Extract deleteFileIfExists helper (#136)
+- Extract deleteFileIfExists helper (#136)
 
-Replaces the duplicate `deleteTagsFile` and `deleteSummaryFile` functions in `createTags.ts` with a single parameterized `deleteFileIfExists(path)` utility. The new helper lives in its own module and is exported from the package barrel for reuse.
+  Replaces the duplicate `deleteTagsFile` and `deleteSummaryFile` functions in `createTags.ts` with a single parameterized `deleteFileIfExists(path)` utility. The new helper lives in its own module and is exported from the package barrel for reuse.
 
-- #145 refactor: Extract shared CLI argument-parsing utility into core (#151)
+- Extract shared CLI argument-parsing utility into core (#151)
 
-Add a schema-driven `parseArgs` function to `@williamthorsen/node-monorepo-core` that handles boolean flags, string flags (both `--flag=value` and `--flag value`), short aliases, positional collection, the `--` delimiter, and unknown-flag errors. Migrate all CLI argument-parsing sites in preflight (3 sites) and release-kit (5 sites) to use it. A companion `translateParseError` helper normalizes internal error messages for consistent user-facing output.
+  Add a schema-driven `parseArgs` function to `@williamthorsen/node-monorepo-core` that handles boolean flags, string flags (both `--flag=value` and `--flag value`), short aliases, positional collection, the `--` delimiter, and unknown-flag errors. Migrate all CLI argument-parsing sites in preflight (3 sites) and release-kit (5 sites) to use it. A companion `translateParseError` helper normalizes internal error messages for consistent user-facing output.
 
 ## [release-kit-v4.0.0] - 2026-04-02
 
 ### Features
 
-- #125 feat: Rename reusable workflows to .reusable.yaml convention (#129)
+- Rename reusable workflows to .reusable.yaml convention (#129)
 
-Renames all three reusable GitHub Actions workflow files from the inconsistent `-workflow.yaml`/bare `.yaml` convention to a uniform `.reusable.yaml` suffix. Updates all references across caller workflows, release-kit templates, tests, preflight collection, and documentation. Scaffolds the sync-labels caller workflow and labels file for this repo. Deletes superseded legacy files.
+  Renames all three reusable GitHub Actions workflow files from the inconsistent `-workflow.yaml`/bare `.yaml` convention to a uniform `.reusable.yaml` suffix. Updates all references across caller workflows, release-kit templates, tests, preflight collection, and documentation. Scaffolds the sync-labels caller workflow and labels file for this repo. Deletes superseded legacy files.
 
 ## [release-kit-v3.0.0] - 2026-03-29
 
 ### Bug fixes
 
-- #68 release-kit|fix: Pass tag pattern to git-cliff based on tagPrefix (#77)
+- Pass tag pattern to git-cliff based on tagPrefix (#77)
 
-Fixes the issue that git-cliff was processing the entire commit history on every run instead of only commits since the last release.
+  Fixes the issue that git-cliff was processing the entire commit history on every run instead of only commits since the last release.
 
-Constructs the pattern from `tagPrefix` at invocation time (e.g., `release-kit-v` → `release-kit-v[0-9].*`) and pass it via `--tag-pattern`, which overrides the config file default.
+  Constructs the pattern from `tagPrefix` at invocation time (e.g., `release-kit-v` → `release-kit-v[0-9].*`) and pass it via `--tag-pattern`, which overrides the config file default.
 
-- #72 release-kit|fix: Propagate version bumps to workspace dependents (#80)
+- Propagate version bumps to workspace dependents (#80)
 
-Restructures `releasePrepareMono` from a single-pass loop into a phased pipeline that automatically patch-bumps workspace dependents when a component is released. A reverse dependency graph is built from `workspace:` references in `dependencies` and `peerDependencies`, then BFS propagation walks upward from bumped components to their dependents. Propagated-only components receive synthetic changelog entries instead of git-cliff invocations.
+  Restructures `releasePrepareMono` from a single-pass loop into a phased pipeline that automatically patch-bumps workspace dependents when a component is released. A reverse dependency graph is built from `workspace:` references in `dependencies` and `peerDependencies`, then BFS propagation walks upward from bumped components to their dependents. Propagated-only components receive synthetic changelog entries instead of git-cliff invocations.
 
 ### Features
 
-- #73 release-kit|feat!: Support conventional-commit format in commit parsing (#85)
+- Support conventional-commit format in commit parsing (#85)
 
-Adds support for the conventional commits format (`type(scope): description`) alongside the existing pipe-prefixed format (`scope|type: description`) in release-kit's commit parser. Renames `workspace` to `scope` throughout release-kit types, config, validation, and consumers.
+  Adds support for the conventional commits format (`type(scope): description`) alongside the existing pipe-prefixed format (`scope|type: description`) in release-kit's commit parser. Renames `workspace` to `scope` throughout release-kit types, config, validation, and consumers.
 
-- #70 release-kit|feat: Add commit command for local release flow (#89)
+- Add commit command for local release flow (#89)
 
-Adds a `release-kit commit` command that centralizes the release commit step between `prepare` and `tag`. The command reads tag names and a per-component commit summary from temporary files written by `prepare`, stages all changes, and creates a formatted commit. Two new utilities — `stripScope` and `buildReleaseSummary` — support building the commit body by stripping redundant scope indicators and formatting commits under their component headings. The CI workflow is simplified to use `release-kit commit` and `release-kit tag` instead of inline shell logic.
+  Adds a `release-kit commit` command that centralizes the release commit step between `prepare` and `tag`. The command reads tag names and a per-component commit summary from temporary files written by `prepare`, stages all changes, and creates a formatted commit. Two new utilities — `stripScope` and `buildReleaseSummary` — support building the commit body by stripping redundant scope indicators and formatting commits under their component headings. The CI workflow is simplified to use `release-kit commit` and `release-kit tag` instead of inline shell logic.
 
-- #69 release-kit|feat: Add CI publish workflow with OIDC trusted publishing (#90)
+- Add CI publish workflow with OIDC trusted publishing (#90)
 
-Adds automated npm publication via a tag-push-triggered GitHub Actions workflow using OIDC trusted publishing. Extends `release-kit publish` with a `--provenance` flag and `release-kit init` with publish workflow scaffolding.
+  Adds automated npm publication via a tag-push-triggered GitHub Actions workflow using OIDC trusted publishing. Extends `release-kit publish` with a `--provenance` flag and `release-kit init` with publish workflow scaffolding.
 
-- #91 release-kit|feat: Make --provenance opt-in to support private repos (#94)
+- Make --provenance opt-in to support private repos (#94)
 
-Adds a `provenance` boolean input (default `false`) to the reusable `publish-workflow.yaml` so private repos using OIDC trusted publishing no longer fail at publish time. The `--provenance` flag is only passed to `release-kit publish` when the caller sets `provenance: true`.
+  Adds a `provenance` boolean input (default `false`) to the reusable `publish-workflow.yaml` so private repos using OIDC trusted publishing no longer fail at publish time. The `--provenance` flag is only passed to `release-kit publish` when the caller sets `provenance: true`.
 
-Updates the scaffolded `publish.yaml` template to include `provenance: false` with an inline comment guiding public repos to opt in. Expand the `release-kit init` next-steps output with hints about the provenance setting and trusted publisher registration. Set `provenance: true` in this repo's own `publish.yaml` since it is public.
+  Updates the scaffolded `publish.yaml` template to include `provenance: false` with an inline comment guiding public repos to opt in. Expand the `release-kit init` next-steps output with hints about the provenance setting and trusted publisher registration. Set `provenance: true` in this repo's own `publish.yaml` since it is public.
 
 ## [release-kit-v2.3.2] - 2026-03-28
 
 ### Bug fixes
 
-- #71 release-kit|fix: Prevent unparseable commits from being silently dropped (#76)
+- Prevent unparseable commits from being silently dropped (#76)
 
-Prevents `releasePrepareMono` and `releasePrepare` from silently skipping components whose commits have unparseable messages. Adds ticket-prefix stripping to `parseCommitMessage` (mirroring cliff.toml's `commit_preprocessors`), a patch-floor safety net when commits exist but none parse, and unparseable-commit reporting in `reportPrepare`.
+  Prevents `releasePrepareMono` and `releasePrepare` from silently skipping components whose commits have unparseable messages. Adds ticket-prefix stripping to `parseCommitMessage` (mirroring cliff.toml's `commit_preprocessors`), a patch-floor safety net when commits exist but none parse, and unparseable-commit reporting in `reportPrepare`.
 
 ## [release-kit-v2.3.0] - 2026-03-28
 
 ### Features
 
-- #8 feat: Add shared writeFileWithCheck utility and overwrite reporting (#66)
+- Add shared writeFileWithCheck utility and overwrite reporting (#66)
 
-Extracts three duplicated `writeIfAbsent` implementations and two duplicated terminal helper sets into shared utilities in `@williamthorsen/node-monorepo-core`, then migrates all consumers (`release-kit init`, `preflight init`, `sync-labels`) to use them. All init commands now report which files were created, overwritten, skipped, or failed — including when `--force` replaces existing files.
+  Extracts three duplicated `writeIfAbsent` implementations and two duplicated terminal helper sets into shared utilities in `@williamthorsen/node-monorepo-core`, then migrates all consumers (`release-kit init`, `preflight init`, `sync-labels`) to use them. All init commands now report which files were created, overwritten, skipped, or failed — including when `--force` replaces existing files.
 
-- #11 release-kit|feat: Separate tag-write errors from release preparation errors (#67)
+- Separate tag-write errors from release preparation errors (#67)
 
-When tag-file writing fails, the error message now reads "Error writing release tags:" instead of the misleading "Error preparing release:", which only appeared because both operations shared a single try/catch.
+  When tag-file writing fails, the error message now reads "Error writing release tags:" instead of the misleading "Error preparing release:", which only appeared because both operations shared a single try/catch.
 
-Refactors `writeReleaseTags` to use the shared `writeFileWithCheck` utility from `@node-monorepo-tools/core` instead of raw `mkdirSync`/`writeFileSync`. The function now returns a structured `WriteResult` instead of throwing, and contains no `console` calls — all presentation moves to `runAndReport`.
+  Refactors `writeReleaseTags` to use the shared `writeFileWithCheck` utility from `@node-monorepo-tools/core` instead of raw `mkdirSync`/`writeFileSync`. The function now returns a structured `WriteResult` instead of throwing, and contains no `console` calls — all presentation moves to `runAndReport`.
 
 ### Tests
 
-- #14 release-kit|tests: Add eligibility check failure and short-circuit tests (#63)
+- Add eligibility check failure and short-circuit tests (#63)
 
-Adds 4 unit tests to `initCommand.unit.test.ts` covering the remaining `checkEligibility` orchestration gaps: individual failure exit codes for `hasPackageJson` and `usesPnpm`, and short-circuit verification ensuring downstream checks are skipped when an earlier check fails.
+  Adds 4 unit tests to `initCommand.unit.test.ts` covering the remaining `checkEligibility` orchestration gaps: individual failure exit codes for `hasPackageJson` and `usesPnpm`, and short-circuit verification ensuring downstream checks are skipped when an earlier check fails.
 
-- #13 release-kit|tests: Add cliff.toml.template alignment test (#64)
+- Add cliff.toml.template alignment test (#64)
 
-Adds a unit test that enforces bidirectional alignment between `DEFAULT_WORK_TYPES` and the bundled `cliff.toml.template` commit parsers. The test parses the TOML template using `smol-toml`, then verifies that every canonical type name and alias is matched by a parser with the correct group heading, and that every parser group maps to a known work type header.
+  Adds a unit test that enforces bidirectional alignment between `DEFAULT_WORK_TYPES` and the bundled `cliff.toml.template` commit parsers. The test parses the TOML template using `smol-toml`, then verifies that every canonical type name and alias is matched by a parser with the correct group heading, and that every parser group maps to a known work type header.
 
-- #12 release-kit|tests: Add releasePrepare coverage for bumpOverride, tagPrefix, and dry-run tags (#65)
+- Add releasePrepare coverage for bumpOverride, tagPrefix, and dry-run tags (#65)
 
-Adds three unit tests to `releasePrepare.unit.test.ts` covering previously untested code paths: the `bumpOverride` bypass of commit-based bump detection, custom `tagPrefix` propagation into tags, and tag computation in dry-run mode.
+  Adds three unit tests to `releasePrepare.unit.test.ts` covering previously untested code paths: the `bumpOverride` bypass of commit-based bump detection, custom `tagPrefix` propagation into tags, and tag computation in dry-run mode.
 
 ## [release-kit-v2.2.0] - 2026-03-27
 
-### Dependencies
-
-- Root|deps: Add release-kit as root devDependency
-
-Make `npx release-kit` and `pnpm exec release-kit` resolve within
-this repo by adding a `workspace:*` dependency that symlinks the bin.
-
 ### Features
 
-- #23 release-kit|feat: Add sync-labels command (#33)
+- Add sync-labels command (#33)
 
-Add a `release-kit sync-labels` command group with three subcommands (`init`, `generate`, `sync`) for declarative GitHub label management in monorepos. Bundle a reusable GitHub Actions workflow and composable label presets with the release-kit package. Introduce a `findPackageRoot` utility to replace fragile hardcoded path resolutions across the codebase.
+  Add a `release-kit sync-labels` command group with three subcommands (`init`, `generate`, `sync`) for declarative GitHub label management in monorepos. Bundle a reusable GitHub Actions workflow and composable label presets with the release-kit package. Introduce a `findPackageRoot` utility to replace fragile hardcoded path resolutions across the codebase.
 
-- #34 release-kit|feat: Report up-to-date status for unchanged init files (#35)
+- Report up-to-date status for unchanged init files (#35)
 
-`release-kit init` now compares existing file content against the default before reporting status. When an existing file is identical to the default (after normalizing trailing whitespace), it reports `✅ (up to date)` instead of the misleading `⚠️ (already exists)`.
+  `release-kit init` now compares existing file content against the default before reporting status. When an existing file is identical to the default (after normalizing trailing whitespace), it reports `✅ (up to date)` instead of the misleading `⚠️ (already exists)`.
 
-- Release-workflow|feat: Accept force input
+- Auto-detect Prettier for CHANGELOG formatting (#36)
 
-Pass `--force` to the prepare command so callers can force a version
-bump even when there are no release-worthy changes.
+  When `formatCommand` is not configured, release-kit now auto-detects whether the repo uses Prettier by checking for config files (`.prettierrc*`, `prettier.config.*`) or a `"prettier"` key in root `package.json`. If found, it defaults to `npx prettier --write` on generated files. If not found, formatting is skipped.
 
-- #27 release-kit|feat: Auto-detect Prettier for CHANGELOG formatting (#36)
+- Add tag-creation command (#40)
 
-When `formatCommand` is not configured, release-kit now auto-detects whether the repo uses Prettier by checking for config files (`.prettierrc*`, `prettier.config.*`) or a `"prettier"` key in root `package.json`. If found, it defaults to `npx prettier --write` on generated files. If not found, formatting is skipped.
+  Adds a `release-kit tag` CLI command that reads computed tag names from the `tmp/.release-tags` file produced by `prepare` and creates annotated git tags. The command supports `--dry-run` (preview without creating tags) and `--no-git-checks` (skip dirty working tree validation). The `createTags` function and its options type are exported for programmatic use.
 
-- #28 release-kit|feat: Add tag-creation command (#40)
+- Add publish command (#42)
 
-Adds a `release-kit tag` CLI command that reads computed tag names from the `tmp/.release-tags` file produced by `prepare` and creates annotated git tags. The command supports `--dry-run` (preview without creating tags) and `--no-git-checks` (skip dirty working tree validation). The `createTags` function and its options type are exported for programmatic use.
+  Adds a `release-kit publish` subcommand that derives packages to publish from git tags on HEAD and delegates to the repo's detected package manager. Also cleans up the `.release-tags` file after tag creation.
 
-- #29 release-kit|feat: Add publish command (#42)
+- Remove tagPrefix customization from component config (#49)
 
-Adds a `release-kit publish` subcommand that derives packages to publish from git tags on HEAD and delegates to the repo's detected package manager. Also cleans up the `.release-tags` file after tag creation.
+  Removes the ability to customize `tagPrefix` per component, enforcing the deterministic `{dir}-v` convention universally. The internal `tagPrefix` property on `ComponentConfig` and `ReleaseConfig` is preserved — only the override/customization entry points are removed. Existing configs that still include `tagPrefix` now receive a clear deprecation error.
 
-- #41 release-kit|feat: Remove tagPrefix customization from component config (#49)
+- Add styled terminal output to prepare command (#55)
 
-Removes the ability to customize `tagPrefix` per component, enforcing the deterministic `{dir}-v` convention universally. The internal `tagPrefix` property on `ComponentConfig` and `ReleaseConfig` is preserved — only the override/customization entry points are removed. Existing configs that still include `tagPrefix` now receive a clear deprecation error.
+  Adds ANSI formatting and emoji markers to the `release-kit prepare` command output. Progress chatter is dimmed, key results (version bumps, release tags, completion status) are highlighted with bold text and emoji, and monorepo components are separated by box-drawing section headers.
 
-- #54 release-kit|feat: Add styled terminal output to prepare command (#55)
+- Extract nmr CLI from core package (#61)
 
-Adds ANSI formatting and emoji markers to the `release-kit prepare` command output. Progress chatter is dimmed, key results (version bumps, release tags, completion status) are highlighted with bold text and emoji, and monorepo components are separated by box-drawing section headers.
+  Extracts all nmr CLI code from `packages/core` into a new `packages/nmr` package (`@williamthorsen/nmr`). Core is reduced to an empty shared-library shell ready for cross-cutting utilities. All internal references are rewired and the full build/test pipeline passes.
 
-- #59 feat: Extract nmr CLI from core package (#61)
-
-Extracts all nmr CLI code from `packages/core` into a new `packages/nmr` package (`@williamthorsen/nmr`). Core is reduced to an empty shared-library shell ready for cross-cutting utilities. All internal references are rewired and the full build/test pipeline passes.
-
-Scopes: core, nmr
+  Scopes: core, nmr
 
 ### Refactoring
 
-- #43 refactor: Replace dist bin targets with thin wrapper scripts (#48)
+- Replace dist bin targets with thin wrapper scripts (#48)
 
-The `bin` entries in `packages/core` and `packages/release-kit` pointed directly into `dist/esm/`, causing `pnpm install` to emit "Failed to create bin" warnings in fresh worktrees where `dist/` does not yet exist. Each bin entry now points to a committed wrapper script in `bin/` that dynamically imports the real entry point. The `files` field in both packages includes `bin` so the wrappers are published.
+  The `bin` entries in `packages/core` and `packages/release-kit` pointed directly into `dist/esm/`, causing `pnpm install` to emit "Failed to create bin" warnings in fresh worktrees where `dist/` does not yet exist. Each bin entry now points to a committed wrapper script in `bin/` that dynamically imports the real entry point. The `files` field in both packages includes `bin` so the wrappers are published.
 
-- #53 release-kit|refactor: Separate presentation from logic in prepare workflow (#57)
+- Separate presentation from logic in prepare workflow (#57)
 
-Extracts all `console.info` calls from the prepare workflow's logic functions (`bumpAllVersions`, `generateChangelogs`, `releasePrepare`, `releasePrepareMono`) into a dedicated `reportPrepare` formatter. Logic functions now return structured result types (`BumpResult`, `ComponentPrepareResult`, `PrepareResult`). The legacy `runReleasePrepare` entry point is retired, with its utilities absorbed into `prepareCommand`.
+  Extracts all `console.info` calls from the prepare workflow's logic functions (`bumpAllVersions`, `generateChangelogs`, `releasePrepare`, `releasePrepareMono`) into a dedicated `reportPrepare` formatter. Logic functions now return structured result types (`BumpResult`, `ComponentPrepareResult`, `PrepareResult`). The legacy `runReleasePrepare` entry point is retired, with its utilities absorbed into `prepareCommand`.
 
 ### Tests
 
-- #17 release-kit|tests: Cover multi-changelogPaths and error paths (#44)
-
-Add three tests for previously untested code paths:
+- Cover multi-changelogPaths and error paths (#44)
 
-- `releasePrepareMono`: component with two `changelogPaths` entries, asserting `git-cliff` is invoked once per path with the correct `--output` target.
-- `getCommitsSinceTarget`: `git describe` failure with a non-128 exit status propagates as a wrapped error instead of being swallowed.
-- `getCommitsSinceTarget`: `git log` failure is wrapped and re-thrown with the commit range in the message.
+  Add three tests for previously untested code paths:
+  - `releasePrepareMono`: component with two `changelogPaths` entries, asserting `git-cliff` is invoked once per path with the correct `--output` target.
+  - `getCommitsSinceTarget`: `git describe` failure with a non-128 exit status propagates as a wrapped error instead of being swallowed.
+  - `getCommitsSinceTarget`: `git log` failure is wrapped and re-thrown with the commit range in the message.
 
-Also adds a `findAllCliffOutputPaths()` test helper that collects the `--output` arg from every `git-cliff` mock call.
+  Also adds a `findAllCliffOutputPaths()` test helper that collects the `--output` arg from every `git-cliff` mock call.
 
 ### Tooling
 
-- #37 root|tooling: Adopt nmr to run monorepo and workspace scripts (#38)
+- Adopt nmr to run monorepo and workspace scripts (#38)
 
-Replaces the legacy workspace script runner and ~25 root `package.json` scripts with `nmr`, the monorepo's own context-aware script runner. Root scripts are reduced to 4 (`prepare`, `postinstall`, `ci`, `bootstrap`), packages use direct build commands for bootstrap, and release-kit declares tier-3 test overrides for its integration test configs.
+  Replaces the legacy workspace script runner and ~25 root `package.json` scripts with `nmr`, the monorepo's own context-aware script runner. Root scripts are reduced to 4 (`prepare`, `postinstall`, `ci`, `bootstrap`), packages use direct build commands for bootstrap, and release-kit declares tier-3 test overrides for its integration test configs.
 
 ## [release-kit-v2.1.0] - 2026-03-17
 
 ### Features
 
-- #7 release-kit|feat!: Slim down release workflow by removing unnecessary pnpm install (#21)
+- Slim down release workflow by removing unnecessary pnpm install (#21)
 
-Make release-kit self-contained by invoking git-cliff via `npx --yes` instead of requiring it on PATH, and by appending modified file paths to the format command so lightweight formatters like `npx prettier --write` work without a full `pnpm install`. Update init templates, README, and consuming repo config/workflow to reference workflow v3.
+  Make release-kit self-contained by invoking git-cliff via `npx --yes` instead of requiring it on PATH, and by appending modified file paths to the format command so lightweight formatters like `npx prettier --write` work without a full `pnpm install`. Update init templates, README, and consuming repo config/workflow to reference workflow v3.
 
-- #22 release-kit|feat: Add --force flag to release-kit prepare (#25)
+- Add --force flag to release-kit prepare (#25)
 
-Add a `--force` flag to `release-kit prepare` that bypasses the "no commits since last tag" check in monorepo mode, allowing version bumping and changelog generation to proceed even when no new commits are found since the last release tag. The flag requires `--bump` since there are no commits to infer bump type from. The local release workflow gains a `force` boolean input for future use.
+  Add a `--force` flag to `release-kit prepare` that bypasses the "no commits since last tag" check in monorepo mode, allowing version bumping and changelog generation to proceed even when no new commits are found since the last release tag. The flag requires `--bump` since there are no commits to infer bump type from. The local release workflow gains a `force` boolean input for future use.
 
-- #20 release-kit|feat!: Move reusable release workflow into repo (#26)
+- Move reusable release workflow into repo (#26)
 
-Moves the reusable release workflow from `williamthorsen/.github` into this repo as `release-workflow.yaml`, stripping all pnpm-related steps since release-kit now runs git-cliff and prettier via `npx` internally. Updates this repo's caller workflow to use a relative path and update init templates to reference the new location. Establishes a naming convention (`{name}-workflow.yaml` for reusable, `{name}.yaml` for callers) and independent versioning strategy (`{name}-workflow-v{major}` tags), documented in `.github/workflows/README.md`.
+  Moves the reusable release workflow from `williamthorsen/.github` into this repo as `release-workflow.yaml`, stripping all pnpm-related steps since release-kit now runs git-cliff and prettier via `npx` internally. Updates this repo's caller workflow to use a relative path and update init templates to reference the new location. Establishes a naming convention (`{name}-workflow.yaml` for reusable, `{name}.yaml` for callers) and independent versioning strategy (`{name}-workflow-v{major}` tags), documented in `.github/workflows/README.md`.
 
-- #30 release-kit|feat: Allow git-cliff to be used without config (#31)
+- Allow git-cliff to be used without config (#31)
 
-Adds a `resolveCliffConfigPath()` function that searches for a git-cliff config in a 4-step cascade (explicit path → `.config/git-cliff.toml` → `cliff.toml` → bundled `cliff.toml.template`), eliminating the requirement for consuming repos to maintain a cliff config copy. Restructures the `init` command to scaffold only the workflow file by default, with new `--with-config` and `--force` flags. Moves `.release-tags` from `/tmp/release-kit/` to project-local `tmp/` for predictable behavior in local runs.
+  Adds a `resolveCliffConfigPath()` function that searches for a git-cliff config in a 4-step cascade (explicit path → `.config/git-cliff.toml` → `cliff.toml` → bundled `cliff.toml.template`), eliminating the requirement for consuming repos to maintain a cliff config copy. Restructures the `init` command to scaffold only the workflow file by default, with new `--with-config` and `--force` flags. Moves `.release-tags` from `/tmp/release-kit/` to project-local `tmp/` for predictable behavior in local runs.
 
 ### Refactoring
 
-- #6 release-kit|refactor: Clean up release-kit post-migration issues (#19)
+- Clean up release-kit post-migration issues (#19)
 
-Addresses five code quality issues and a test coverage gap identified during the release-kit migration (#5). Extracts a duplicated `isRecord` type guard into a shared module, eliminates a double-read in `bumpAllVersions`, improves error handling in `usesPnpm` by replacing a silent catch with a structured error boundary, removes an unreachable `'feature'` pattern from version defaults, and adds an integration test for scaffold template path resolution.
+  Addresses five code quality issues and a test coverage gap identified during the release-kit migration (#5). Extracts a duplicated `isRecord` type guard into a shared module, eliminates a double-read in `bumpAllVersions`, improves error handling in `usesPnpm` by replacing a silent catch with a structured error boundary, removes an unreachable `'feature'` pattern from version defaults, and adds an integration test for scaffold template path resolution.
 
 ## [release-kit-v1.0.1] - 2026-03-14
 
 ### Features
 
-- #5 release-kit|feat: Migrate release-kit from toolbelt (#18)
+- Migrate release-kit from toolbelt (#18)
 
-Migrates the complete `@williamthorsen/release-kit` package (v1.0.1) from `williamthorsen/toolbelt` into `packages/release-kit/`, adds shebang preservation to the shared esbuild plugin for CLI binaries, and sets up dogfooding infrastructure so this monorepo uses release-kit for its own releases.
+  Migrates the complete `@williamthorsen/release-kit` package (v1.0.1) from `williamthorsen/toolbelt` into `packages/release-kit/`, adds shebang preservation to the shared esbuild plugin for CLI binaries, and sets up dogfooding infrastructure so this monorepo uses release-kit for its own releases.
 
 <!-- generated by git-cliff -->

package/LICENSE

@@ -1,7 +1,7 @@
-UNLICENSED SOFTWARE
+ISC License
 
-Copyright (c) 2023-2025 William Thorsen
+Copyright (c) 2026 William Thorsen
 
-All rights reserved.
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
 
-This software is provided 'as-is', without any express or implied warranty. No rights are granted to use, copy, modify, or distribute this software for any purpose. For full legal details, consult a legal expert. This notice may not be removed or altered from any distribution.
+The software is provided "as is" and the author disclaims all warranties with regard to this software including all implied warranties of merchantability and fitness. In no event shall the author be liable for any special, direct, indirect, or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software.

package/cliff.toml.template

@@ -1,76 +1,88 @@
 # git-cliff configuration
-# See https://git-cliff.org/docs/configuration
+# Generates changelogs from conventional-ish commit messages.
+#
+# Commit format: [ticket-prefix ]scope|type[!]: description [#PR]
+# Examples:
+#   #19 rdy|feat: Add utility functions for common check patterns (#26)
+#   AFG-42 panel|fix: Fix button layout (#73)
+#
+# Only ticketed commits (leading #NN or PROJ-NN) are included.
+# Unticketed maintenance commits (deps upgrades, tooling tweaks) are skipped.
 
 [changelog]
-# changelog header
 header = """
-# Changelog\n
-All notable changes to this project will be documented in this file.\n
-"""
-# template for the changelog body
-body = """
-{% if version %}\
-    ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
-{% else %}\
-    ## [unreleased]
-{% endif %}\
-{% for group, commits in commits | group_by(attribute="group") %}
-    ### {{ group | striptags | trim | upper_first }}
-    {% for commit in commits %}
-        - {% if commit.scope %}*({{ commit.scope }})* {% endif %}\
-            {% if commit.breaking %}[**breaking**] {% endif %}\
-            {{ commit.message | upper_first }}\
-    {% endfor %}
-{% endfor %}\n
+# Changelog
+
+All notable changes to this project will be documented in this file."""
+# Render each commit as a bullet with the description (stripped of ticket ID
+# and scope|type prefix). If the commit has a body, render it as indented
+# continuation paragraphs under the bullet.
+body = """{%- if version %}
+## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
+{%- else %}
+## [unreleased]
+{%- endif -%}
+{%- set non_merge = commits | filter(attribute="merge_commit", value=false) -%}
+{%- for group, group_commits in non_merge | group_by(attribute="group") %}
+
+### {{ group | striptags | trim | upper_first }}
+
+{% for commit in group_commits -%}
+{%- set subject = commit.message | split(pat="\n") | first -%}
+{%- set desc = subject | split(pat=": ") | slice(start=1) | join(sep=": ") -%}
+{%- set body_lines = commit.message | split(pat="\n") | slice(start=2) -%}
+{%- set body_text = body_lines | join(sep="\n") | trim -%}
+{%- if not loop.first %}
+
+{% endif -%}
+- {{ desc | upper_first }}
+{%- if body_text %}
+
+  {{ body_text | split(pat="\n") | join(sep="\n  ") }}
+{%- endif -%}
+{%- endfor -%}
+{%- endfor %}
 """
-# template for the changelog footer
 footer = """
+
 <!-- generated by git-cliff -->
 """
-# remove the leading and trailing whitespace from the templates
-trim = true
+trim = false
 
 [git]
-# parse the commits based on https://www.conventionalcommits.org
 conventional_commits = false
-# filter out the commits that are not conventional
 filter_unconventional = false
-# process each line of a commit as an individual commit
 split_commits = false
-# regex for preprocessing the commit messages
-commit_preprocessors = [
-  # Strip GitHub-style issue prefixes like "#8 " or "#123 "
-  { pattern = '^#\d+\s+', replace = "" },
-  # Strip Jira-style ticket prefixes like "TOOL-123 " or "AFG-456 "
-  { pattern = '^[A-Z]+-\d+\s+', replace = "" },
-]
-# regex for parsing and grouping commits
-# Supports "type: desc", "scope|type: desc", and "type(scope): desc" formats
+commit_preprocessors = []
+# Require a ticket-ID prefix for inclusion.
+# Supported prefixes: "#123 ", "#123-1 ", "#123.1 ", "TOOL-123 "
 commit_parsers = [
-  { message = "^(.*\\|)?fix(\\(.*\\))?(!)?:", group = "Bug fixes" },
-  { message = "^(.*\\|)?bugfix(\\(.*\\))?(!)?:", group = "Bug fixes" },
-  { message = "^(.*\\|)?feat(\\(.*\\))?(!)?:", group = "Features" },
-  { message = "^(.*\\|)?feature(\\(.*\\))?(!)?:", group = "Features" },
-  { message = "^(.*\\|)?internal(\\(.*\\))?(!)?:", group = "Internal" },
-  { message = "^(.*\\|)?refactor(\\(.*\\))?(!)?:", group = "Refactoring" },
-  { message = "^(.*\\|)?tests?(\\(.*\\))?(!)?:", group = "Tests" },
-  { message = "^(.*\\|)?tooling(\\(.*\\))?(!)?:", group = "Tooling" },
-  { message = "^(.*\\|)?ci(\\(.*\\))?(!)?:", group = "CI" },
-  { message = "^(.*\\|)?deps?(\\(.*\\))?(!)?:", group = "Dependencies" },
-  { message = "^(.*\\|)?docs?(\\(.*\\))?(!)?:", group = "Documentation" },
-  { message = "^(.*\\|)?fmt(\\(.*\\))?(!)?:", group = "Formatting" },
+  { message = "^release:", skip = true },
+  { message = "^Merge", skip = true },
+  { 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-]+\\|)?fmt(!)?:", group = "Formatting" },
+  { 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 },
 ]
-# protect breaking changes from being skipped due to matching a skipping commit_parser
 protect_breaking_commits = false
-# filter out the commits that are not matched by commit parsers
 filter_commits = true
-# regex for matching git tags
 tag_pattern = "v[0-9].*"
-# regex for skipping tags
 skip_tags = ""
-# regex for ignoring tags
 ignore_tags = ""
-# sort the tags topologically
 topo_order = false
-# sort the commits inside sections by oldest/newest order
 sort_commits = "oldest"

package/dist/esm/.cache

@@ -1 +1 @@
-ee18b710e962397616b0a9fc54a9101c2096a2925b2aebb8db506ae9972ff6c5
+020cc360fffab3d5b52fc5e388bc432d37399fdfb25c30cff31a23d37f1c2c09

package/dist/esm/assertCleanWorkingTree.d.ts

@@ -0,0 +1 @@
+export declare function assertCleanWorkingTree(): void;

package/dist/esm/assertCleanWorkingTree.js

@@ -0,0 +1,15 @@
+import { execFileSync } from "node:child_process";
+function assertCleanWorkingTree() {
+  const status = execFileSync("git", ["status", "--porcelain"], {
+    encoding: "utf8",
+    stdio: ["pipe", "pipe", "pipe"]
+  }).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."
+    );
+  }
+}
+export {
+  assertCleanWorkingTree
+};