@williamthorsen/release-kit 13.0.0 → 14.0.0

package/.meta/changelog.json

@@ -1,4 +1,75 @@
 [
+  {
+    "version": "14.0.0",
+    "date": "2026-10-08",
+    "sections": [
+      {
+        "title": "🎉 Features",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Changes monorepo `--set-version` to take comma-separated `<workspace>@N.N.N` entries, which `prepare` accepts without `--only` and together with `--bump` and `--force`, and which release each named workspace's dependents. (#970)",
+            "breaking": true,
+            "migration": "Replace `--only arrays --set-version 1.0.0` with `--set-version arrays@1.0.0 --only arrays`, and keep `--only` unless the release should cover every workspace, because a `--set-version` run without `--only` is a full run.",
+            "hash": "07e3e99cb03e6031619bd58dac6ee339ceac0e89",
+            "entry": 2
+          }
+        ]
+      },
+      {
+        "title": "🐛 Bug fixes",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Fixes the issue that `release-kit prepare --only` left each dependent of the named workspaces published against the old version range of its dependency, by also releasing every transitive dependent: a dependent with commits of its own at its own bump, and one without at a propagated patch bump. (#970)",
+            "breaking": true,
+            "migration": "Expect each `--only` run to release the dependents of the named workspaces as well, and remove any dependents that were added to `--only` only to get past the stranded-dependents error, which `prepare` no longer reports.",
+            "hash": "07e3e99cb03e6031619bd58dac6ee339ceac0e89",
+            "entry": 1
+          }
+        ]
+      },
+      {
+        "title": "🧪 Tests",
+        "audience": "dev",
+        "items": [
+          {
+            "description": "Replaces the hand-rolled `console.warn` spies in release-kit's config-warning and push tests with `silenceConsole`, which restores the method when its `using` scope exits. (#964)",
+            "hash": "38cc179b4116bcd5aba8371b17b0816150c9e9a3",
+            "entry": 4
+          }
+        ]
+      },
+      {
+        "title": "📚 Documentation",
+        "audience": "dev",
+        "items": [
+          {
+            "description": "Updates the readyup examples in the `nmr`, `release-kit`, and `v11y-check` READMEs and the `nmr` rulebook to use the `sources` key and `rdy run --sources`, and states that `--sources` needs readyup 0.40 or later. (#977)",
+            "hash": "41177f8f562d59a4cf0aff9d24199dbd370bb1a1",
+            "entry": 4
+          }
+        ]
+      }
+    ]
+  },
+  {
+    "version": "13.1.0",
+    "date": "2026-10-02",
+    "sections": [
+      {
+        "title": "🎉 Features",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Adds an `archived: true` mark to `repoLabels.labels` entries, which `sync-labels generate` writes to `.github/labels.yaml` without changing the output for unmarked labels. (#955)",
+            "hash": "23c0e0eeaf3e59cd921632850c7771ccdd6effe1",
+            "entry": 1
+          }
+        ]
+      }
+    ]
+  },
   {
     "version": "13.0.0",
     "date": "2026-10-01",
@@ -1906,10 +1977,22 @@
         "audience": "all",
         "items": [
           {
-            "description": "Migrate release-kit from toolbelt (#18)",
-            "body": "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.",
-            "hash": "da3a61fd335fb3e05ce20a0bffcdc1647d7aeb45"
-          },
+            "description": "Allow git-cliff to be used without config (#31)",
+            "body": "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.",
+            "hash": "0cbd2605d6f5f53d1efe3dda8dd0f6e4376b499f"
+          }
+        ]
+      }
+    ]
+  },
+  {
+    "version": "2.0.0",
+    "date": "2026-03-16",
+    "sections": [
+      {
+        "title": "🎉 Features",
+        "audience": "all",
+        "items": [
           {
             "description": "Slim down release workflow by removing unnecessary pnpm install (#21)",
             "body": "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.",
@@ -1926,11 +2009,6 @@
             "body": "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`.",
             "breaking": true,
             "hash": "f3416120cfe5bf0e7dbf51389e0c2647ccf41d30"
-          },
-          {
-            "description": "Allow git-cliff to be used without config (#31)",
-            "body": "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.",
-            "hash": "0cbd2605d6f5f53d1efe3dda8dd0f6e4376b499f"
           }
         ]
       },

package/.readyup/kits/default.js

@@ -1,6 +1,6 @@
 /** @noformat -- @generated. Do not edit. Compiled by rdy. */
 /* eslint-disable */
-export const __readyupVersion = "0.38.0";
+export const __readyupVersion = "0.40.0";
 
 
 // .readyup/kits/default.ts
@@ -98,7 +98,7 @@ function translateGlob(pattern) {
 
 // .readyup/kits/default.ts
 function getMinVersion() {
-  const picked = { "version": "13.0.0" };
+  const picked = { "version": "14.0.0" };
   if (typeof picked["version"] !== "string") {
     throw new TypeError("release-kit/package.json: 'version' must be a string");
   }
@@ -116,7 +116,7 @@ var CONFIG_EXPORT_PATTERNS = [
 ];
 var COMMON_PRESET_HASH = "618bb5cbcbdd4f4f0c2a777add7e14d992d48483350dd9651bf8cf4c1fa9d418";
 var SYNC_LABELS_WORKFLOW_HASH = "6b50015e2919ffa4b16d0b4a1f340e585ff3e5b779a2256010d3c62fa07ff8f2";
-var RELEASE_WORKFLOW_HASH_MONOREPO = "f35503bcfc5c131a8309305fed27f8127cb901f422cb8b62978a34b86dda7f7a";
+var RELEASE_WORKFLOW_HASH_MONOREPO = "4a20ff3315155500f64a27133c54eb1bc1f07a4acc370ec0d83176109041c60d";
 var RELEASE_WORKFLOW_HASH_SINGLE = "d26dd4ca186632b388ea46bd885721124c03d19918e511baa40821d2d760da69";
 var PUBLISH_WORKFLOW_HASH_MONOREPO = "0afa9ffe914f3dc8f043e68252ebc604c8cc1a953422fcea37a909a4def370ee";
 var PUBLISH_WORKFLOW_HASH_SINGLE = "6f31183e0a1e66be791a19266c3b028dadbd9fe010f7fc4452f3f8970c937b43";

package/.readyup/kits/npm-auto-publish.js

@@ -1,6 +1,6 @@
 /** @noformat -- @generated. Do not edit. Compiled by rdy. */
 /* eslint-disable */
-export const __readyupVersion = "0.38.0";
+export const __readyupVersion = "0.40.0";
 
 
 // .readyup/kits/npm-auto-publish.ts

package/.readyup/manifest.json

@@ -8,12 +8,12 @@
       "esbuildVersion": "0.28.2",
       "inputs": [
         {
-          "hash": "91bc3638",
+          "hash": "7a8522cd",
           "kind": "module",
           "path": "kits/default.ts"
         },
         {
-          "hash": "7f9ab854",
+          "hash": "6eab98d1",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -43,10 +43,10 @@
       ],
       "name": "default",
       "path": "kits/default.js",
-      "readyupVersion": "0.38.0",
+      "readyupVersion": "0.40.0",
       "source": "kits/default.ts",
-      "sourceHash": "91bc3638",
-      "targetHash": "2fdeff1f"
+      "sourceHash": "7a8522cd",
+      "targetHash": "4e21467f"
     },
     {
       "checklists": [
@@ -68,10 +68,10 @@
       ],
       "name": "npm-auto-publish",
       "path": "kits/npm-auto-publish.js",
-      "readyupVersion": "0.38.0",
+      "readyupVersion": "0.40.0",
       "source": "kits/npm-auto-publish.ts",
       "sourceHash": "d9910d60",
-      "targetHash": "8bdbefef"
+      "targetHash": "2a6931b6"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to this project will be documented in this file.
 
+## 14.0.0 — 2026-10-08
+
+### 🎉 Features
+
+- 🚨 **Breaking:** Changes monorepo `--set-version` to take comma-separated `<workspace>@N.N.N` entries, which `prepare` accepts without `--only` and together with `--bump` and `--force`, and which release each named workspace's dependents. (#970)
+
+### 🐛 Bug fixes
+
+- 🚨 **Breaking:** Fixes the issue that `release-kit prepare --only` left each dependent of the named workspaces published against the old version range of its dependency, by also releasing every transitive dependent: a dependent with commits of its own at its own bump, and one without at a propagated patch bump. (#970)
+
+### 🧪 Tests
+
+- Replaces the hand-rolled `console.warn` spies in release-kit's config-warning and push tests with `silenceConsole`, which restores the method when its `using` scope exits. (#964)
+
+### 📚 Documentation
+
+- Updates the readyup examples in the `nmr`, `release-kit`, and `v11y-check` READMEs and the `nmr` rulebook to use the `sources` key and `rdy run --sources`, and states that `--sources` needs readyup 0.40 or later. (#977)
+
+## 13.1.0 — 2026-10-02
+
+### 🎉 Features
+
+- Adds an `archived: true` mark to `repoLabels.labels` entries, which `sync-labels generate` writes to `.github/labels.yaml` without changing the output for unmarked labels. (#955)
+
 ## 13.0.0 — 2026-10-01
 
 ### 🎉 Features
@@ -1105,9 +1129,13 @@ All notable changes to this project will be documented in this file.
 
 ### 🎉 Features
 
-- Migrate release-kit from toolbelt (#18)
+- Allow git-cliff to be used without config (#31)
 
-  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.
+  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.
+
+## 2.0.0 — 2026-03-16
+
+### 🎉 Features
 
 - 🚨 **Breaking:** Slim down release workflow by removing unnecessary pnpm install (#21)
 
@@ -1121,10 +1149,6 @@ All notable changes to this project will be documented in this file.
 
   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`.
 
-- 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.
-
 ### ♻️ Refactoring
 
 - Clean up release-kit post-migration issues (#19)

package/README.md

@@ -7,42 +7,15 @@ 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 the same commit history that decides each bump (with optional [editorial overrides](docs/editorial-overrides.md)).
 
 <!-- section:release-notes -->
-## Release notes — v13.0.0 (2026-10-01)
+## Release notes — v14.0.0 (2026-10-08)
 
 ### 🎉 Features
 
-- Adds the `--config <path>` flag to `release-kit push`, which now reads the config as `publish` and `create-github-release` do and fails when the file exists but is invalid. (#895)
-- Makes `release-kit` add an item derived from a change-record entry to a workspace's changelog and version bump only when the entry's `scopes`, after `scopeAliases` resolution, name the workspace's `dir`, are empty, or contain `*`, and extends that rule to the sections of earlier releases that `release-kit prepare` rebuilds. (#896)
-- Adds a warning to the `release-kit prepare` report that lists each change-record entry scope matching no workspace in its commit's window, such as a misspelled scope or the old name of a renamed directory that has no `scopeAliases` entry. (#896)
-- Makes `release-kit overrides validate` check a workspace's overrides against only the entries routed to that workspace, so that an override keyed to an entry routed elsewhere is reported as stale. (#896)
-- Adds `release-kit update-templates`, which writes each scaffolded workflow that is missing or differs from the installed template, prints a diff of each updated file, refreshes `sync-labels.yaml` only when it exists, keeps `publish.yaml`'s provenance setting, and never reads or writes the config files. (#952)
-- Changes the readyup kits' fix messages for a workflow that differs from its template, or that references a deprecated tag, to recommend `update-templates` rather than `init --force`. (#952)
-
-### 🪦 Removed
-
-- 🚨 **Breaking:** Removes `required` as a `breakingPolicies` value, making `drop` default to `optional` so that an unmarked `drop:` commit no longer reports a policy violation. (#905)
-- Stops `release-kit` from parsing a commit subject that combines a pipe scope with a parenthesized scope, such as `web|feat(other): ...`, or that lacks a space and a title after the colon, because subjects are now read through `@williamthorsen/change-grammar`. (#905)
-- Stops publishing `schemas/label-map.json` from `release-kit`, whose identical schema `@williamthorsen/change-grammar` now publishes; URLs under existing `release-kit-v*` tags keep resolving. (#905)
+- 🚨 **Breaking:** Changes monorepo `--set-version` to take comma-separated `<workspace>@N.N.N` entries, which `prepare` accepts without `--only` and together with `--bump` and `--force`, and which release each named workspace's dependents. (#970)
 
 ### 🐛 Bug fixes
 
-- Record a changelog entry for a forced release whose commits yield no item (#887)
-
-  Makes `release-kit prepare` record the "Forced version bump." changelog entry for any release forced by `--force` or `--set-version` whose commits yield no changelog item, instead of only for a release with no commits at all. It also stops a monorepo's project release from dropping the forced-release entries that earlier releases recorded.
-
-- Stops `release-kit prepare` from reporting `commitCount` 0 and dropping the unparseable commits and change-record and policy diagnostics of a workspace released only because a dependency was bumped, and makes `prepare` list that workspace's commits in the release commit summary under its tag. (#888)
-- Stops `release-kit prepare` from labeling a direct release that has no commits as bumped via a dependency, by marking a propagation-only release with the new `propagatedOnly` result field, whose report line now reads `Bumped via dependency: …` in place of `0 commits (bumped via dependency: …)`. (#888)
-- Stops a `release-kit` command run from inside a package from releasing that package as a single-package repo with its own tag and changelog, by running every command from the repo root: the nearest directory that contains `pnpm-workspace.yaml`, or else the working directory when it contains a `package.json`. (#893)
-- Stops `sync-labels generate` from writing the `--config` path into the `.github/labels.yaml` header as typed, which made the header and the result of `generate --check` depend on the directory from which the command ran; the header now names the config by its path relative to the repo root. (#893)
-- Stops `push`, `publish`, and `create-github-release` from pushing, publishing, or creating a GitHub Release for a tag on HEAD whose workspace the config excludes with `shouldExclude: true`, which each command now skips with a warning, including when `--tags` names the tag or when every tag on HEAD is excluded. (#895)
-- Stops `release-kit prepare` from silently deleting a `CHANGELOG.md` section whose version is absent from both the release windows and `changelog.json`, such as history written by hand before release-kit was adopted; `prepare` now keeps that section verbatim in version order, lists the kept versions in its report, and warns about each `##` section that names no version and is dropped. (#897)
-- Stops `release-kit prepare` from folding every earlier commit into the new version, and deriving the bump from all of them, when the current version was released and recorded in the changelog but never tagged; `prepare` now fails before any write, under `--force` and `--set-version` too, and names each target and the tag to create. (#897)
-- Adds the missing `removal` and `formatting` labels to the `common` preset by defining a label for every work type in change-grammar's taxonomy, and keeps the names, colors, and descriptions of the existing type labels. (#906)
-- Fixes the `release.yaml` generated by `release-kit init`, which `actionlint` rejected because its `bump` choice input listed an empty string as the auto-detect option, by offering `auto` as the default option and passing it to the reusable release workflow as an empty `bump`. (#936)
-- Rewords the error messages, `prepare` report lines, command help, and readyup kit fix strings of `release-kit` that addressed the reader as "your", separated a detail from its subject with an em-dash, or stated an absence with "no", such as "No workspaces had release-worthy changes." (#937)
-- Fixes the issue that the `release.yaml` and `sync-labels.yaml` workflows generated by `release-kit init` and `release-kit sync-labels init` contained unclear wording in two comments and in the `force` input description, which the change rewrites without altering any job, trigger, or input; the release-kit kit check reports a copy generated before this change as stale until `release-kit init --force` or `release-kit sync-labels init --force` regenerates it. (#946)
-- Fixes the issue that `release-kit` titled a propagation-only bump's changelog section `Dependency updates` rather than with the resolved `deps` work type's header, `📦 Dependencies` by default or a consumer's `workTypes.deps.header` override, which broke the heading convention and left the section outside the section order. (#950)
-- Fixes the issue that `release-kit init`'s next steps told a public repo to set `provenance: true` in `publish.yaml`, which the template already sets, and now tells a private repo to remove it instead. (#952)
+- 🚨 **Breaking:** Fixes the issue that `release-kit prepare --only` left each dependent of the named workspaces published against the old version range of its dependency, by also releasing every transitive dependent: a dependent with commits of its own at its own bump, and one without at a propagated patch bump. (#970)
 <!-- /section:release-notes -->
 
 ## Installation
@@ -88,7 +61,7 @@ Commit the scaffolded workflows, then start a release from the `release` workflo
 
 ```sh
 gh workflow run release.yaml                  # every workspace with release-worthy changes
-gh workflow run release.yaml -f only=arrays   # the named workspaces alone
+gh workflow run release.yaml -f only=arrays   # the named workspaces and their dependents
 ```
 
 After upgrading release-kit, run `release-kit update-templates` to update the scaffolded workflows to its templates; it leaves the config files alone.
@@ -167,15 +140,15 @@ release-kit publishes two [readyup](https://www.npmjs.com/package/readyup) kits:
 import { defineRdyConfig } from 'readyup';
 
 export default defineRdyConfig({
-  packages: ['@williamthorsen/release-kit'],
+  sources: ['npm:@williamthorsen/release-kit'],
 });
 ```
 
 ```bash
-rdy run --packages
+rdy run --sources
 ```
 
-`rdy run` needs `readyup` 0.23 or later, and `@williamthorsen/release-kit` as a _direct_ devDependency: A strict pnpm layout links nothing else into the project; therefore, a transitive copy is unreachable.
+`rdy run --sources` needs `readyup` 0.40 or later, and `@williamthorsen/release-kit` as a _direct_ devDependency: A strict pnpm layout links nothing else into the project; therefore, a transitive copy is unreachable.
 
 [Readiness checks](docs/readiness-checks.md) covers running each kit alone and what `npm-auto-publish` needs from the npm session.
 

package/dist/esm/findTransitiveDependents.d.ts

@@ -0,0 +1,3 @@
+import type { DependencyGraph } from './buildDependencyGraph.js';
+/** Returns the start workspace `dir`s together with the `dir` of every workspace that depends on one, transitively. */
+export declare function findTransitiveDependents(graph: DependencyGraph, startDirs: Iterable<string>): Set<string>;

package/dist/esm/findTransitiveDependents.js

@@ -0,0 +1,20 @@
+export function findTransitiveDependents(graph, startDirs) {
+    const found = new Set(startDirs);
+    const queue = [...found];
+    while (queue.length > 0) {
+        const dir = queue.shift();
+        if (dir === undefined)
+            break;
+        const packageName = graph.dirToPackageName.get(dir);
+        if (packageName === undefined)
+            continue;
+        const dependents = graph.dependentsOf.get(packageName) ?? [];
+        for (const dependent of dependents) {
+            if (found.has(dependent.dir))
+                continue;
+            found.add(dependent.dir);
+            queue.push(dependent.dir);
+        }
+    }
+    return found;
+}

package/dist/esm/help/prepareHelp.d.ts

@@ -2,6 +2,6 @@
  * Help text for `release-kit prepare`. The module does not have any import-time side effects, so that a test can
  * import it without running the CLI.
  */
-export declare const prepareHelpText = "\nUsage: release-kit prepare [options]\n\nRun release preparation with automatic workspace discovery.\n\nOptions:\n  --config <path>       Config file, relative to the current directory\n                         (default: .config/release-kit.config.ts at the repo root)\n  --dry-run             Run without modifying any files\n  --bump=major|minor|patch  Set the level of every release that happens; does not trigger one\n  --set-version=X.Y.Z   Set an explicit version; bypasses the changelog-derived bump. In monorepo\n                         mode it requires --only, and is rejected when a 'project' block is configured.\n  --force               Release even when the last tag is not followed by any commits,\n                         or by any bump-worthy ones. Defaults to patch when --bump is not given;\n                         use --bump=X for a different level.\n  --no-git-checks, -n   Skip the clean-working-tree check\n  --only=name1,name2    Only process the named workspaces (comma-separated, monorepo only).\n                         When a 'project' block is configured, the project release is skipped.\n  --with-release-notes  Also write per-workspace release-notes previews under <workspacePath>/docs/\n                         (docs/README.v<version>.md and docs/RELEASE_NOTES.v<version>.md).\n                         Recommended .gitignore entry: packages/*/docs/*.v*.md (or docs/*.v*.md).\n  --help, -h            Show this help message\n";
+export declare const prepareHelpText = "\nUsage: release-kit prepare [options]\n\nRun release preparation with automatic workspace discovery.\n\nOptions:\n  --config <path>       Config file, relative to the current directory\n                         (default: .config/release-kit.config.ts at the repo root)\n  --dry-run             Run without modifying any files\n  --bump=major|minor|patch  Set the level of every release that happens; does not trigger one\n  --set-version=X.Y.Z   Set an explicit version; bypasses the changelog-derived bump. In monorepo\n                         mode, name each workspace: --set-version=arrays@1.0.0[,strings@2.0.0].\n                         Rejected when a 'project' block is configured.\n  --force               Release even when the last tag is not followed by any commits,\n                         or by any bump-worthy ones. Defaults to patch when --bump is not given;\n                         use --bump=X for a different level.\n  --no-git-checks, -n   Skip the clean-working-tree check\n  --only=name1,name2    Release only the named workspaces and their dependents (comma-separated,\n                         monorepo only).\n                         When a 'project' block is configured, the project release is skipped.\n  --with-release-notes  Also write per-workspace release-notes previews under <workspacePath>/docs/\n                         (docs/README.v<version>.md and docs/RELEASE_NOTES.v<version>.md).\n                         Recommended .gitignore entry: packages/*/docs/*.v*.md (or docs/*.v*.md).\n  --help, -h            Show this help message\n";
 /** Prints the prepare command's help text. */
 export declare function showPrepareHelp(): void;

package/dist/esm/help/prepareHelp.js

@@ -9,12 +9,14 @@ Options:
   --dry-run             Run without modifying any files
   --bump=major|minor|patch  Set the level of every release that happens; does not trigger one
   --set-version=X.Y.Z   Set an explicit version; bypasses the changelog-derived bump. In monorepo
-                         mode it requires --only, and is rejected when a 'project' block is configured.
+                         mode, name each workspace: --set-version=arrays@1.0.0[,strings@2.0.0].
+                         Rejected when a 'project' block is configured.
   --force               Release even when the last tag is not followed by any commits,
                          or by any bump-worthy ones. Defaults to patch when --bump is not given;
                          use --bump=X for a different level.
   --no-git-checks, -n   Skip the clean-working-tree check
-  --only=name1,name2    Only process the named workspaces (comma-separated, monorepo only).
+  --only=name1,name2    Release only the named workspaces and their dependents (comma-separated,
+                         monorepo only).
                          When a 'project' block is configured, the project release is skipped.
   --with-release-notes  Also write per-workspace release-notes previews under <workspacePath>/docs/
                          (docs/README.v<version>.md and docs/RELEASE_NOTES.v<version>.md).

package/dist/esm/init/templates.js

@@ -89,7 +89,7 @@ on:
   workflow_dispatch:
     inputs:
       only:
-        description: 'Workspaces to release (comma-separated, leave empty for all)'
+        description: 'Workspaces to release, with their dependents (comma-separated, leave empty for all)'
         required: false
         type: string
       bump:

package/dist/esm/prepareCommand.d.ts

@@ -43,6 +43,7 @@ export declare function parseArgs(argv: string[]): {
     noGitChecks: boolean;
     bumpOverride: ReleaseType | undefined;
     only: string[] | undefined;
+    /** The raw `--set-version` value, whose accepted form depends on the mode. */
     setVersion: string | undefined;
     withReleaseNotes: boolean;
 };

package/dist/esm/prepareCommand.js

@@ -2,12 +2,9 @@ import { execSync } from 'node:child_process';
 import { formatGlyphLine, parseArgsOrExit, reportError, } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { assertCleanWorkingTree } from "./assertCleanWorkingTree.js";
-import { readReleaseHistory } from "./buildChangelogEntries.js";
-import { buildDependencyGraph } from "./buildDependencyGraph.js";
 import { configFlagSchema } from "./configFlagSchema.js";
 import { describeEmptyWorkspace, discoverWorkspaces } from "./discoverWorkspaces.js";
 import { dim } from "./format.js";
-import { getAllTagPrefixes } from "./generateChangelogs.js";
 import { RELEASE_GLYPHS } from "./glyphs.js";
 import { mergeMonorepoConfig, mergeSinglePackageConfig, readRootPackageVersion } from "./loadConfig.js";
 import { loadValidatedConfig, reportConfigProblem, reportConfigWarnings } from "./loadValidatedConfig.js";
@@ -17,7 +14,6 @@ import { releasePrepare } from "./releasePrepare.js";
 import { releasePrepareMono } from "./releasePrepareMono.js";
 import { reportPrepare } from "./reportPrepare.js";
 import { resolveConfigFlag } from "./resolveConfigFlag.js";
-import { validateOnlyExcludesStrandedDependents } from "./validateOnlyExcludesStrandedDependents.js";
 const VALID_BUMP_TYPES = ['major', 'minor', 'patch'];
 const CANONICAL_SEMVER_PATTERN = /^\d+\.\d+\.\d+$/;
 function isReleaseType(value) {
@@ -47,26 +43,10 @@ export function parseArgs(argv) {
         }
         bumpOverride = flags.bump;
     }
-    let setVersion;
-    if (flags.setVersion !== undefined) {
-        if (!CANONICAL_SEMVER_PATTERN.test(flags.setVersion)) {
-            reportError(`Invalid --set-version value "${flags.setVersion}". Must be canonical semver (N.N.N, no pre-release suffix).`);
-            process.exit(1);
-        }
-        setVersion = flags.setVersion;
-    }
     let only;
     if (flags.only !== undefined) {
         only = flags.only.split(',');
     }
-    if (setVersion !== undefined && bumpOverride !== undefined) {
-        reportError('--set-version cannot be combined with --bump');
-        process.exit(1);
-    }
-    if (setVersion !== undefined && flags.force) {
-        reportError('--set-version cannot be combined with --force');
-        process.exit(1);
-    }
     return {
         configPath: flags.config,
         dryRun: flags.dryRun,
@@ -74,7 +54,7 @@ export function parseArgs(argv) {
         noGitChecks: flags.noGitChecks,
         bumpOverride,
         only,
-        setVersion,
+        setVersion: flags.setVersion,
         withReleaseNotes: flags.withReleaseNotes,
     };
 }
@@ -83,7 +63,6 @@ export async function prepareCommand(argv, styles, invocationDir) {
     const options = {
         force,
         ...(bumpOverride !== undefined && { bumpOverride }),
-        ...(setVersion !== undefined && { setVersion }),
         ...(withReleaseNotes && { withReleaseNotes: true }),
     };
     if (dryRun) {
@@ -121,19 +100,23 @@ export async function prepareCommand(argv, styles, invocationDir) {
         process.exit(1);
     }
     if (workspace.kind === 'single-package') {
-        runSinglePackageMode(userConfig, options, only, dryRun, styles.stdout);
+        runSinglePackageMode(userConfig, options, only, setVersion, dryRun, styles.stdout);
     }
     else {
         runMonorepoMode(workspace.packageDirs, userConfig, options, only, setVersion, dryRun, styles.stdout);
     }
 }
-function runSinglePackageMode(userConfig, options, only, dryRun, style) {
+function runSinglePackageMode(userConfig, options, only, setVersion, dryRun, style) {
     if (only !== undefined) {
         reportError('--only is only supported for monorepo configurations');
         process.exit(1);
     }
+    if (setVersion !== undefined && !CANONICAL_SEMVER_PATTERN.test(setVersion)) {
+        reportError(`Invalid --set-version value "${setVersion}". Must be canonical semver (N.N.N, no pre-release suffix).`);
+        process.exit(1);
+    }
     const config = mergeSinglePackageConfig(userConfig);
-    runAndReport(() => releasePrepare(config, options), dryRun, style);
+    runAndReport(() => releasePrepare(config, { ...options, ...(setVersion !== undefined && { setVersion }) }), dryRun, style);
 }
 function runMonorepoMode(discoveredPaths, userConfig, options, only, setVersion, dryRun, style) {
     let config;
@@ -147,53 +130,48 @@ function runMonorepoMode(discoveredPaths, userConfig, options, only, setVersion,
     }
     if (setVersion !== undefined && config.project !== undefined) {
         reportError('--set-version cannot be combined with a project release. ' +
-            '--set-version operates on a single workspace; a project release rolls up every ' +
+            "--set-version sets individual workspaces' versions; a project release rolls up every " +
             'contributing workspace. To use --set-version, run on a config without a `project` block.');
         process.exit(1);
     }
-    let configuredWorkspaceDirs;
-    if (only !== undefined) {
-        const knownNames = config.workspaces.map((w) => w.dir);
-        for (const name of only) {
-            if (knownNames.includes(name)) {
-                continue;
-            }
-            reportError(`Unknown workspace "${name}". Known workspaces: ${knownNames.join(', ')}`);
-            process.exit(1);
+    const knownNames = config.workspaces.map((w) => w.dir);
+    const onlyNames = only ?? [];
+    for (const name of onlyNames) {
+        if (knownNames.includes(name)) {
+            continue;
         }
-        const graph = buildDependencyGraph(config.workspaces);
-        const violations = validateOnlyExcludesStrandedDependents(config.workspaces, only, graph, (workspace) => {
-            const history = readReleaseHistory(config, { tagPrefixes: getAllTagPrefixes(workspace), paths: workspace.paths });
-            return { has: history.unreleased.commits.length > 0, tag: history.previousTag };
-        });
-        if (violations !== undefined) {
-            reportError('--only excludes packages with changes that would be stranded by the release.');
-            process.stderr.write('The following packages must be added to --only or have their dependencies removed:\n');
-            for (const violation of violations) {
-                const since = violation.tag ?? 'the beginning';
-                process.stderr.write(`  - ${violation.dir} (downstream of ${violation.downstreamOf}; has commits since ${since})\n`);
-            }
-            process.stderr.write('Alternatively, run `release-kit prepare` without --only to release everything.\n');
+        reportError(`Unknown workspace "${name}". Known workspaces: ${knownNames.join(', ')}`);
+        process.exit(1);
+    }
+    const monorepoOptions = {
+        ...options,
+        ...(only !== undefined && { only }),
+        ...(setVersion !== undefined && { setVersions: parseSetVersions(setVersion, knownNames) }),
+    };
+    runAndReport(() => releasePrepareMono(config, monorepoOptions), dryRun, style);
+}
+function parseSetVersions(value, knownNames) {
+    const setVersions = new Map();
+    for (const entry of value.split(',')) {
+        const separatorIndex = entry.lastIndexOf('@');
+        const name = entry.slice(0, Math.max(0, separatorIndex));
+        const version = entry.slice(separatorIndex + 1);
+        if (separatorIndex <= 0 || !CANONICAL_SEMVER_PATTERN.test(version)) {
+            reportError(`Invalid --set-version entry "${entry}". In monorepo mode, each entry must be <workspace>@N.N.N ` +
+                '(canonical semver, no pre-release suffix), e.g. --set-version=arrays@1.0.0.');
             process.exit(1);
         }
-        configuredWorkspaceDirs = knownNames;
-        config.workspaces = config.workspaces.filter((w) => only.includes(w.dir));
-    }
-    if (setVersion !== undefined) {
-        if (only === undefined) {
-            reportError('--set-version requires --only in monorepo mode');
+        if (!knownNames.includes(name)) {
+            reportError(`Unknown workspace "${name}" in --set-version. Known workspaces: ${knownNames.join(', ')}`);
             process.exit(1);
         }
-        if (config.workspaces.length !== 1) {
-            reportError(`--set-version requires --only to match exactly one workspace; matched ${config.workspaces.length}`);
+        if (setVersions.has(name)) {
+            reportError(`--set-version names workspace "${name}" more than once`);
             process.exit(1);
         }
+        setVersions.set(name, version);
     }
-    runAndReport(() => releasePrepareMono(config, {
-        ...options,
-        ...(only !== undefined && { only }),
-        ...(configuredWorkspaceDirs !== undefined && { configuredWorkspaceDirs }),
-    }), dryRun, style);
+    return setVersions;
 }
 function runAndReport(computePlan, dryRun, style) {
     let plan;

package/dist/esm/releasePrepare.d.ts

@@ -10,24 +10,10 @@ export interface ReleasePrepareOptions {
     /** Level of the release, in place of the level that the changelog items call for; it doesn't trigger a release. */
     bumpOverride?: ReleaseType;
     /**
-     * Explicit target version (canonical `N.N.N`) that bypasses commit-derived bump logic.
-     * Mutually exclusive with `bumpOverride`. In monorepo mode the caller must narrow
-     * `config.workspaces` to a single workspace before invoking.
+     * Explicit target version (canonical `N.N.N`) that bypasses commit-derived bump logic and takes precedence over
+     * `bumpOverride` and `force`.
      */
     setVersion?: string;
-    /**
-     * Workspace directories to which `--only` narrowed the run (monorepo only), with
-     * `config.workspaces` already filtered to match. Present only for a narrowed run, which
-     * skips the project release: The project tier rolls up every contributing workspace, and
-     * the narrowing has changed which workspaces those are.
-     */
-    only?: string[];
-    /**
-     * Every configured workspace `dir`, taken before `--only` narrowed `config.workspaces`; the unrouted-scope report
-     * does not report a scope naming one of them that the run did not read. Defaults to the `dir`s of
-     * `config.workspaces`.
-     */
-    configuredWorkspaceDirs?: readonly string[];
     /**
      * If true, plan per-workspace release-notes previews under `{workspacePath}/docs/`
      * (`README.v{version}.md` and `RELEASE_NOTES.v{version}.md`) from each workspace's

package/dist/esm/releasePrepareMono.d.ts

@@ -1,14 +1,29 @@
 import type { ReleasePlan } from './releasePlan.js';
 import type { ReleasePrepareOptions } from './releasePrepare.js';
 import type { MonorepoPrepareConfig } from './types.js';
+/** Options for monorepo release preparation. */
+export interface MonorepoPrepareOptions extends Omit<ReleasePrepareOptions, 'setVersion'> {
+    /**
+     * Workspace `dir`s from which the release starts; the run plans them and their transitive dependents. Present only
+     * for a narrowed run, which skips the project release: The project tier rolls up every contributing workspace, and
+     * the narrowing has changed which workspaces those are.
+     */
+    only?: readonly string[];
+    /**
+     * Explicit target versions (canonical `N.N.N`), keyed by workspace `dir`. Each named workspace starts the release
+     * and releases at its version, which takes precedence over `bumpOverride` and `force`.
+     */
+    setVersions?: ReadonlyMap<string, string>;
+}
 /**
  * Orchestrates release preparation for a monorepo with multiple workspaces.
  *
+ * Phase 0: Selects the planned workspaces: those from which the release starts and their transitive dependents.
  * Phase 1: Determines direct bumps from commits for each workspace.
- * Phase 2: Builds the dependency graph and propagates bumps to dependents.
+ * Phase 2: Propagates bumps to dependents.
  * Phase 2b: Sorts the full release set topologically.
  * Phase 3: Plans bumps and changelogs in dependency order.
  * Phase 3b: Plans the project release.
  * Phase 4: Renders the format command.
  */
-export declare function releasePrepareMono(config: MonorepoPrepareConfig, options: ReleasePrepareOptions): ReleasePlan;
+export declare function releasePrepareMono(fullConfig: MonorepoPrepareConfig, options: MonorepoPrepareOptions): ReleasePlan;

package/dist/esm/releasePrepareMono.js

@@ -11,6 +11,7 @@ import { applyWorkspaceOverrides, createOverrideContext, formatStaleOverrideKeyW
 import { decideRelease } from "./decideRelease.js";
 import { deriveDependenciesHeader, deriveSectionOrder } from "./deriveReleaseNotesConfig.js";
 import { detectUndeclaredTagPrefixes } from "./detectUndeclaredTagPrefixes.js";
+import { findTransitiveDependents } from "./findTransitiveDependents.js";
 import { findUnroutedEntryScopes } from "./findUnroutedEntryScopes.js";
 import { getAllTagPrefixes } from "./generateChangelogs.js";
 import { hasPrettierConfig } from "./hasPrettierConfig.js";
@@ -21,10 +22,17 @@ import { propagateBumps } from "./propagateBumps.js";
 import { planPreservedSections } from "./readChangelogSections.js";
 import { releasePrepareProject } from "./releasePrepareProject.js";
 import { renderChangelogMarkdown } from "./renderChangelogMarkdown.js";
-export function releasePrepareMono(config, options) {
+export function releasePrepareMono(fullConfig, options) {
     const { only, withReleaseNotes } = options;
     const writes = [];
     const warnings = [];
+    const graph = buildDependencyGraph(fullConfig.workspaces);
+    const startDirs = selectStartDirs(fullConfig.workspaces, options);
+    const plannedDirs = findTransitiveDependents(graph, startDirs);
+    const config = {
+        ...fullConfig,
+        workspaces: fullConfig.workspaces.filter((workspace) => plannedDirs.has(workspace.dir)),
+    };
     if (withReleaseNotes === true && !config.changelogJson.enabled) {
         warnings.push('--with-release-notes requires changelogJson.enabled; skipping preview generation');
     }
@@ -32,10 +40,9 @@ export function releasePrepareMono(config, options) {
     const sectionOrder = deriveSectionOrder(workTypes);
     const dependenciesHeader = deriveDependenciesHeader(workTypes);
     const overrideContext = createOverrideContext(config.workspaces);
-    const { directBumps, directResults, skippedResults, untaggedBaselines } = determineDirectBumps(config, options);
-    reportUnroutedEntryScopes([...directResults.values(), ...skippedResults], config, options);
+    const { directBumps, directResults, skippedResults, untaggedBaselines } = determineDirectBumps(config, options, startDirs);
+    reportUnroutedEntryScopes([...directResults.values(), ...skippedResults], config, fullConfig.workspaces.map((workspace) => workspace.dir));
     const skippedHistories = new Map(skippedResults.map((skipped) => [skipped.workspace.dir, skipped.history]));
-    const graph = buildDependencyGraph(config.workspaces);
     const fullReleaseSet = propagateBumps(directBumps, graph);
     assertTaggedBaseline([...untaggedBaselines]
         .filter(([dir]) => directBumps.has(dir) || !fullReleaseSet.has(dir))
@@ -107,11 +114,15 @@ export function releasePrepareMono(config, options) {
         ...(project !== undefined && { project }),
     };
 }
-function determineDirectBumps(config, options) {
-    const { force, bumpOverride, setVersion } = options;
-    if (setVersion !== undefined && config.workspaces.length !== 1) {
-        throw new Error(`--set-version requires exactly one workspace; received ${config.workspaces.length}`);
+function selectStartDirs(workspaces, options) {
+    const { only, setVersions } = options;
+    if (only === undefined) {
+        return new Set(workspaces.map((workspace) => workspace.dir));
     }
+    return new Set([...only, ...(setVersions?.keys() ?? [])]);
+}
+function determineDirectBumps(config, options, startDirs) {
+    const { force, bumpOverride, setVersions } = options;
     const directBumps = new Map();
     const directResults = new Map();
     const skippedResults = [];
@@ -138,6 +149,7 @@ function determineDirectBumps(config, options) {
         if (tag === undefined) {
             maybeEmitBaselineHint(workspace, knownPrefixes, hintState);
         }
+        const setVersion = setVersions?.get(workspace.dir);
         if (setVersion !== undefined) {
             directBumps.set(workspace.dir, { releaseType: 'patch', newVersionOverride: setVersion });
             directResults.set(workspace.dir, {
@@ -152,7 +164,7 @@ function determineDirectBumps(config, options) {
         const decision = decideRelease({
             naturalBump: history.unreleased.bump,
             commitCount: history.unreleased.commits.length,
-            force,
+            force: force === true && startDirs.has(workspace.dir),
             bumpOverride,
             skipReasons: {
                 noCommits: `No commits for ${name} ${since}. Pass --force to release at patch. Skipping.`,
@@ -173,8 +185,8 @@ function determineDirectBumps(config, options) {
     }
     return { directBumps, directResults, skippedResults, untaggedBaselines };
 }
-function reportUnroutedEntryScopes(results, config, options) {
-    const findings = findUnroutedEntryScopes(results.map(({ workspace, history }) => ({ dir: workspace.dir, commits: history.unreleased.commits })), options.configuredWorkspaceDirs ?? config.workspaces.map((workspace) => workspace.dir), config.scopeAliases ?? {});
+function reportUnroutedEntryScopes(results, config, configuredWorkspaceDirs) {
+    const findings = findUnroutedEntryScopes(results.map(({ workspace, history }) => ({ dir: workspace.dir, commits: history.unreleased.commits })), configuredWorkspaceDirs, config.scopeAliases ?? {});
     for (const { workspace, history } of results) {
         history.unreleased.diagnostics.unroutedEntryScopes = findings.get(workspace.dir) ?? [];
     }

package/dist/esm/sync-labels/generateCommand.js

@@ -15,7 +15,12 @@ export function formatLabelsYaml(labels, presetHashes, configFilePath = CONFIG_F
     for (const [name, hash] of sortedPresetHashes) {
         headerLines.push(`# ${name} preset hash: ${hash}`);
     }
-    const declared = labels.map((label) => ({ ...label, description: label.description ?? '' }));
+    const declared = labels.map(({ archived, color, description, name }) => ({
+        name,
+        color,
+        description: description ?? '',
+        ...(archived !== undefined && { archived }),
+    }));
     const yamlBody = stringify(declared, { singleQuote: true, lineWidth: 0 });
     return headerLines.join('\n') + '\n' + yamlBody;
 }

package/dist/esm/sync-labels/resolveLabels.js

@@ -26,6 +26,7 @@ export function resolveLabels(config) {
                 name,
                 color: spec.color,
                 ...(spec.description !== undefined && { description: spec.description }),
+                ...(spec.archived !== undefined && { archived: spec.archived }),
             });
         }
     }

package/dist/esm/sync-labels/types.d.ts

@@ -1,4 +1,4 @@
-/** A single GitHub label definition compatible with EndBug/label-sync. */
+/** A single GitHub label definition, as `sync-labels generate` writes it to `.github/labels.yaml`. */
 export interface LabelDefinition {
     /** Display name of the label. */
     name: string;
@@ -6,4 +6,6 @@ export interface LabelDefinition {
     color: string;
     /** Short description shown in the GitHub UI. Absent when the label has none. */
     description?: string;
+    /** Marks the label for the sync to archive rather than keep active. Absent for an active label. */
+    archived?: true;
 }

package/dist/esm/types.d.ts

@@ -446,11 +446,13 @@ export declare const breakingPolicyValueSchema: z.ZodEnum<{
 export declare const labelSpecSchema: z.ZodObject<{
     color: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
+    archived: z.ZodOptional<z.ZodLiteral<true>>;
 }, z.core.$strict>;
 /**
- * A label's color and optional description; the name is the record key in `repoLabels.labels`.
- * An omitted description resolves to empty, which the generated labels file declares explicitly so that a sync
- * clears whatever description the label has on the repo.
+ * A label's color, optional description, and optional archived mark; the name is the record key in
+ * `repoLabels.labels`. An omitted description resolves to empty, which the generated labels file declares explicitly
+ * so that a sync clears whatever description the label has on the repo. `archived: true` retires the label: The sync
+ * archives it, keeping it on the issues and pull requests that have it.
  */
 export type LabelSpec = z.infer<typeof labelSpecSchema>;
 /**
@@ -468,6 +470,7 @@ export declare const repoLabelsSchema: z.ZodObject<{
     labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
         color: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
+        archived: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strict>>>>;
 }, z.core.$strict>;
 /** Consumer-facing `repoLabels` block: bundled presets to extend plus per-name adjustments. */
@@ -496,6 +499,7 @@ export declare const releaseKitConfigSchema: z.ZodObject<{
         labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
             color: z.ZodString;
             description: z.ZodOptional<z.ZodString>;
+            archived: z.ZodOptional<z.ZodLiteral<true>>;
         }, z.core.$strict>>>>;
     }, z.core.$strict>>;
     retiredPackages: z.ZodOptional<z.ZodArray<z.ZodObject<{

package/dist/esm/types.js

@@ -55,6 +55,7 @@ export const labelSpecSchema = z
     .object({
     color: z.string().min(1),
     description: z.string().optional(),
+    archived: z.literal(true).optional(),
 })
     .strict();
 export const repoLabelsSchema = z

package/docs/labels.md

@@ -42,6 +42,20 @@ Names match case-insensitively, as GitHub matches them: `Bug` in the `labels` re
 
 Overlaps between layers are never errors; order resolves them, and the committed `.github/labels.yaml` diff shows any unexpected change at review. Two misstatements are config errors, because neither is visible in the output diff: a dangling `null`, which removes a name not defined by any preset, and `labels` keys that differ only in case, all but one of which the fold would discard.
 
+### Retiring a label
+
+Mark a label `archived: true` to retire it without losing its history:
+
+```typescript
+labels: {
+  'scope:basic': { color: '00ff96', archived: true }, // retire the scope of a removed package
+},
+```
+
+The sync workflow archives a marked label rather than deleting it. An archived label stays on the issues and pull requests that have it, but it cannot be added to new ones and does not appear in the label picker. Removing the mark unarchives the label on the next sync. Removing the entry instead deletes the label, as the sync deletes every label that `.github/labels.yaml` does not declare, and the label disappears from every issue and pull request that had it.
+
+The mark is set only in the `labels` record, not in a preset. To retire a preset's label, replace it with an entry that restates its color and adds the mark.
+
 ### When labels are applied
 
 The scaffolded workflow declares three triggers:
@@ -56,6 +70,8 @@ Applying on merge closes the window in which a regenerated `.github/labels.yaml`
 
 The `check` job runs the same sync in dry-run. Its **Label diff** log group lists every create, edit, rename, and deletion that the sync would perform, including deletions of labels that the file does not declare: the destructive edits that a diff of `.github/labels.yaml` alone cannot show, because a label created by hand or by another workflow is absent from the file both before and after. Read that log; the check reports success whether or not the diff is destructive, so a green check is not evidence that nothing will be deleted.
 
+Its **Archive state** log group lists each label that the sync would archive or unarchive. Archiving runs after the rest of the sync, so a label that the file both adds and marks is created and then archived.
+
 The two jobs are split because a job's permissions are fixed when the run is created and cannot vary by trigger. The split keeps a write-scoped token out of pull-request runs.
 
 The push trigger filters on the path alone; the `sync` job compares `github.ref_name` against the repository's default branch. The workflow therefore doesn't need a per-repo edit, whatever that branch is named, and a push touching `.github/labels.yaml` on any other branch produces a run whose jobs all skip.

package/docs/project-releases.md

@@ -68,7 +68,7 @@ CLI flag interactions:
 - `--dry-run` previews project artifacts alongside workspace artifacts; it doesn't write any files.
 - `--bump=major|minor|patch` propagates to the project release as a level chooser. It does not trigger a release on its own when the window doesn't have any commits or any bump-worthy commits.
 - `--force` runs the project release even when the history since the last project tag doesn't have any commits or any bump-worthy commits. Defaults to patch when `--bump` is not given; combine with `--bump=X` to release at a different level.
-- `--only` narrows the run to the named workspaces and skips the project release, which is reported as a warning. The project release rolls up every contributing workspace, and `--only` changes which workspaces those are, so rolling up a narrowed set would release a project version covering work that the run excluded. Run a full `prepare` (without `--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.
+- `--only` narrows the run to the named workspaces and their dependents and skips the project release, which is reported as a warning. The project release rolls up every contributing workspace, and `--only` changes which workspaces those are, so rolling up a narrowed set would release a project version covering work that the run excluded. Run a full `prepare` (without `--only`) to include the project release.
+- `--set-version` is rejected with an error when `project` is configured. `--set-version` sets individual workspaces' versions, 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.
 
 How `--bump` and `--force` combine for every target is in [Releasing](releasing.md#release-kit-prepare).

package/docs/readiness-checks.md

@@ -7,12 +7,12 @@ release-kit publishes two [readyup](https://www.npmjs.com/package/readyup) kits
 The [README](../README.md#readiness-checks) shows how to name release-kit in the readyup config.
 
 ```bash
-rdy run --packages                                               # every kit each listed package publishes
+rdy run --sources                                                # every kit each listed package publishes
 rdy run --from npm:@williamthorsen/release-kit                   # the default kit alone
 rdy run --from npm:@williamthorsen/release-kit npm-auto-publish  # the npm-auto-publish kit
 rdy list --from npm:@williamthorsen/release-kit                  # what release-kit publishes
 ```
 
-`--packages` is the form that keeps working when release-kit publishes further kits.
+`--sources` is the form that keeps working when release-kit publishes further kits.
 
 Because `npm-auto-publish` queries the npm registry for each package's trusted publisher, it needs an npm session elevated by two-factor authentication, and is meant to be invoked deliberately rather than included in an unattended run. A session that cannot answer those queries, whether it is missing a login, missing the elevation, or facing an unreachable registry, is reported once by the `npm session can answer trust queries` gate. The rows that would repeat the failed query are then skipped: the trusted-publisher rows in every case, and `published to npm` when the registry itself is unreachable. Each package's `package.json` checks report throughout, since they don't read a registry.

package/docs/releasing.md

@@ -29,7 +29,7 @@ The workflows are managed files: release-kit renders them, and a change made by
 
 Runs release preparation with automatic workspace discovery.
 
-Workspace names for `--only` match the package directory name (e.g., `arrays`, `release-kit`).
+`--only` names the workspaces from which the release starts, by package directory name (e.g., `arrays`, `release-kit`). The run also releases every workspace that depends on one of them, directly or transitively: A dependent with commits of its own releases at its own bump, and one without releases at a propagated patch bump, so that it publishes against the new version. Workspaces outside that set are left out of the run.
 
 `prepare` reads each target's history once and builds the changelog items of its unreleased commits. The bump is the highest level that those items call for, under [`versionPatterns`](configuration.md#versionpatterns), so the bump and the changelog describe the same release: A `feat` entry in a [change-record block](changelogs.md#change-record-blocks) bumps minor under a `docs:` title, and a breaking item bumps major.
 
@@ -82,18 +82,20 @@ docs/*.v*.md
 
 The `--set-version` flag is a first-class escape hatch for the cases in which the derived bump produces the wrong version, most notably when promoting a pre-1.0 package to 1.0.0. Pre-1.0 packages collapse a `feat!` breaking change to a minor bump (matching semantic-release's `initialMajor: false` and release-please's `bump-minor-pre-major`), so a deliberate promotion to 1.0.0 must be requested explicitly.
 
+In a single-package repo, the value is the version: `--set-version 1.0.0`. In a monorepo, it names the workspace with each version, as comma-separated `<workspace>@N.N.N` entries: `--set-version arrays@1.0.0,strings@2.0.0`. Each named workspace releases at its version whether or not it has commits, and starts the release like a workspace named by `--only`.
+
 The flag validates that:
 
-- The value is canonical `N.N.N` semver (pre-release suffixes are rejected).
-- The target is strictly greater than the current version (numeric comparison on each component).
-- In monorepo mode, `--only` is set and resolves to exactly one workspace.
+- Each version is canonical `N.N.N` semver (pre-release suffixes are rejected).
+- In a monorepo, each entry names a known workspace, and none names it twice.
+- Each version is strictly greater than the workspace's current version (numeric comparison on each component).
 
-`--set-version` is mutually exclusive with `--bump` and `--force`. The rest of the pipeline (changelog generation, tag creation, commit summary, propagation to dependents) runs unchanged, so dependents receive a propagated patch bump triggered by the overridden version.
+The rest of the pipeline (changelog generation, tag creation, commit summary, propagation to dependents) runs unchanged, so each dependent receives a propagated patch bump that records the explicit version. Without `--only`, the run is a full run with the explicit versions applied. `--bump` and `--force` combine with `--set-version` and govern every other workspace.
 
-Promoting a pre-1.0 package to 1.0.0 in a monorepo:
+Promoting a pre-1.0 package to 1.0.0 in a monorepo, which also releases its dependents:
 
 ```sh
-release-kit prepare --only arrays --set-version 1.0.0
+release-kit prepare --set-version arrays@1.0.0 --only arrays
 ```
 
 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, merge a descriptive release commit (e.g., a `feat!` describing the stable API) before running `prepare`.
@@ -118,7 +120,7 @@ The `init` command scaffolds a release workflow at `.github/workflows/release.ya
 
 | Input   | Type    | Description                                                                                                                                     |
 | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `only`  | string  | Workspaces to release (comma-separated, leave empty for all)                                                                                    |
+| `only`  | string  | Workspaces to release, with their dependents (comma-separated, leave empty for all)                                                             |
 | `bump`  | choice  | Bump type: `auto` (default, detects it from commits), `patch`, `minor`, or `major`                                                              |
 | `force` | boolean | Release even when the window doesn't have any commits or any bump-worthy commits (defaults to patch; combine with `bump` for a different level) |
 
@@ -130,7 +132,7 @@ For repos that need a self-contained workflow instead of the reusable one, the s
 # All workspaces
 gh workflow run release.yaml
 
-# Specific workspace(s)
+# Specific workspace(s), with their dependents
 gh workflow run release.yaml -f only=arrays
 gh workflow run release.yaml -f only=arrays,strings -f bump=minor
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/release-kit",
-  "version": "13.0.0",
+  "version": "14.0.0",
   "description": "Version-bumping and changelog-generation toolkit for release workflows",
   "keywords": [
     "changelog",
@@ -50,9 +50,9 @@
     "schemas/**"
   ],
   "dependencies": {
-    "@williamthorsen/change-grammar": "0.1.0",
-    "@williamthorsen/nmr-core": "0.13.1",
-    "@williamthorsen/toolbelt.errors": "0.8.1",
+    "@williamthorsen/change-grammar": "0.2.0",
+    "@williamthorsen/nmr-core": "0.13.2",
+    "@williamthorsen/toolbelt.errors": "0.8.2",
     "json-stringify-pretty-compact": "4.0.0",
     "semver": "7.8.5",
     "yaml": "2.9.1",
@@ -60,12 +60,12 @@
   },
   "devDependencies": {
     "@types/semver": "7.8.0",
-    "@williamthorsen/toolbelt.filesystem": "0.9.1",
-    "@williamthorsen/toolbelt.testing": "0.6.1",
-    "@williamthorsen/toolbelt.vitest": "0.10.1",
+    "@williamthorsen/toolbelt.filesystem": "0.9.2",
+    "@williamthorsen/toolbelt.testing": "0.6.2",
+    "@williamthorsen/toolbelt.vitest": "0.10.2",
     "actionlint": "2.0.6",
     "esbuild": "0.28.2",
-    "readyup": "0.38.0",
+    "readyup": "0.40.0",
     "smol-toml": "1.9.0",
     "vitest": "4.1.11"
   },

package/dist/esm/validateOnlyExcludesStrandedDependents.d.ts

@@ -1,37 +0,0 @@
-import type { DependencyGraph } from './buildDependencyGraph.js';
-import type { WorkspaceConfig } from './types.js';
-/** Result of probing a workspace's commits since its last tag. */
-export interface CommitsProbeResult {
-    /** Whether the workspace has any commits since its last tag (excluding `release:` commits). */
-    has: boolean;
-    /**
-     * The baseline tag from which the commits were measured; `undefined` when the workspace does not have a prior tag.
-     */
-    tag: string | undefined;
-}
-/** A single excluded workspace whose changes would be stranded by the `--only` invocation. */
-export interface StrandedDependentViolation {
-    /** The excluded workspace's `dir`. */
-    dir: string;
-    /** The `dir` of the released (or anticipated-release) dependency whose release republishes this workspace. */
-    downstreamOf: string;
-    /**
-     * The baseline tag from which this workspace's commits were counted; `undefined` if the workspace does not have a
-     * prior tag.
-     */
-    tag: string | undefined;
-}
-/** Probe callback that returns whether a workspace has commits since its last tag. */
-type CommitsProbe = (workspace: WorkspaceConfig) => CommitsProbeResult;
-/**
- * Detects `--only` invocations that would silently strand changes in excluded internal dependents.
- *
- * First computes R, the `--only` workspaces that will release, then walks the reverse-dependency graph breadth-first
- * from R and records each excluded workspace with its own commits as a violation. The walk continues through a
- * violation, as though the user had added it to `--only`, which reports deeper violations in the same pass. It stops
- * at an excluded workspace without commits, which does not republish, so its dependents are unaffected by R.
- *
- * Returns `undefined` when the walk does not find any violation, or the violations sorted by `dir`.
- */
-export declare function validateOnlyExcludesStrandedDependents(workspaces: readonly WorkspaceConfig[], only: readonly string[], graph: DependencyGraph, hasCommits: CommitsProbe): StrandedDependentViolation[] | undefined;
-export {};

package/dist/esm/validateOnlyExcludesStrandedDependents.js

@@ -1,115 +0,0 @@
-export function validateOnlyExcludesStrandedDependents(workspaces, only, graph, hasCommits) {
-    const probeCommits = memoizeCommitsProbe(hasCommits);
-    const workspaceByDir = new Map(workspaces.map((w) => [w.dir, w]));
-    const released = computeReleasedSet(only, workspaceByDir, graph, probeCommits);
-    const violations = collectStrandedViolations(released, new Set(only), graph, probeCommits);
-    if (violations.length === 0)
-        return undefined;
-    violations.sort((a, b) => a.dir.localeCompare(b.dir));
-    return violations;
-}
-function memoizeCommitsProbe(probe) {
-    const cache = new Map();
-    return (workspace) => {
-        const cached = cache.get(workspace.dir);
-        if (cached !== undefined)
-            return cached;
-        const result = probe(workspace);
-        cache.set(workspace.dir, result);
-        return result;
-    };
-}
-function computeReleasedSet(only, workspaceByDir, graph, probeCommits) {
-    const released = new Set();
-    for (const dir of only) {
-        const workspace = workspaceByDir.get(dir);
-        if (workspace !== undefined && probeCommits(workspace).has) {
-            released.add(dir);
-        }
-    }
-    let changed = true;
-    while (changed) {
-        changed = false;
-        for (const dir of only) {
-            if (released.has(dir))
-                continue;
-            if (hasDependencyIn(dir, graph, released)) {
-                released.add(dir);
-                changed = true;
-            }
-        }
-    }
-    return released;
-}
-function hasDependencyIn(dir, graph, released) {
-    const forwardDeps = graph.dependenciesOf.get(dir);
-    if (forwardDeps === undefined)
-        return false;
-    for (const depPackageName of forwardDeps) {
-        const depDir = graph.packageNameToDir.get(depPackageName);
-        if (depDir !== undefined && released.has(depDir))
-            return true;
-    }
-    return false;
-}
-function collectStrandedViolations(released, onlySet, graph, probeCommits) {
-    const violations = [];
-    const violationDirs = new Set();
-    const visited = new Set();
-    const queue = [];
-    for (const dir of released) {
-        const packageName = graph.dirToPackageName.get(dir);
-        if (packageName !== undefined) {
-            queue.push({ packageName, attributionRoot: dir });
-        }
-    }
-    while (queue.length > 0) {
-        const item = queue.shift();
-        if (item === undefined)
-            break;
-        if (visited.has(item.packageName))
-            continue;
-        visited.add(item.packageName);
-        const dependents = graph.dependentsOf.get(item.packageName);
-        if (dependents === undefined)
-            continue;
-        for (const dependent of dependents) {
-            visitDependent(dependent, item.attributionRoot, {
-                released,
-                onlySet,
-                graph,
-                probeCommits,
-                queue,
-                violations,
-                violationDirs,
-            });
-        }
-    }
-    return violations;
-}
-function visitDependent(dependent, attributionRoot, ctx) {
-    if (ctx.onlySet.has(dependent.dir)) {
-        if (ctx.released.has(dependent.dir)) {
-            enqueueDependent(dependent, ctx);
-        }
-        return;
-    }
-    const probe = ctx.probeCommits(dependent);
-    if (!probe.has)
-        return;
-    if (!ctx.violationDirs.has(dependent.dir)) {
-        ctx.violationDirs.add(dependent.dir);
-        ctx.violations.push({
-            dir: dependent.dir,
-            downstreamOf: attributionRoot,
-            tag: probe.tag,
-        });
-    }
-    enqueueDependent(dependent, ctx);
-}
-function enqueueDependent(dependent, ctx) {
-    const packageName = ctx.graph.dirToPackageName.get(dependent.dir);
-    if (packageName !== undefined) {
-        ctx.queue.push({ packageName, attributionRoot: dependent.dir });
-    }
-}