kettle-family 1.3.6 → 1.3.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d912f3b7a33740ace19f7f0568177189b662819bec18bf94312de460f640fd9
-  data.tar.gz: d70a03c67ed0a96ce645d00ff769a920b500b3d1d3b231324a2d8170ea683cf1
+  metadata.gz: f74d2fca80b37d1577e7212df092067958426dc780d1e07594b545d057a7321e
+  data.tar.gz: 23f68c9dd77d68828708ecfea9d64c87af8b12182689e9c9c15e0dfddc6648d5
 SHA512:
-  metadata.gz: ca24fe1d3dff219117a561ecd8ff6d45edd6c1a4d4fb6db9172c874f8964676162747de8d3d45fa0caf1aa7707ec2733141eda5a993bbbcbc8d0fd81d5f8543c
-  data.tar.gz: b3f48464d35121fdee21d6d23158e81630ac373676a6581d876f2887e735cc60d5cb70c4a87359090b124a56707b544d13dd1b30f5745ecf93ef81775eb03bed
+  metadata.gz: 327d0135be9e3ee4fb1abea1794d3acf2e714f791b3e83063bb6290a5466ada57b0d49b969f85cbde18050499c34bb57a2334cd7b2a98857f411fe4b015147d9
+  data.tar.gz: 21892de4191d48f57e7b9183d6a45bbb7d6ef5b3ba1b1a3a4922ba42b39da09ddb0f3d8ba30d3e6c86730a86c876023e405b1d93617896f369916245b6b45718

data/CHANGELOG.md

@@ -30,6 +30,65 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [1.3.9] - 2026-10-10
+
+- TAG: [v1.3.9][1.3.9t]
+- COVERAGE: 93.43% -- 7068/7565 lines in 43 files
+- BRANCH COVERAGE: 77.95% -- 2832/3633 branches in 43 files
+- 35.42% documented
+
+### Added
+
+- New `clean-blockers` command uninstalls locally installed gems, from any family, whose unreleased versions are pinned by members’ lockfiles. Unlike `clean-unreleased`, which can only remove a family sibling newer than its latest release, it removes cross-family offenders: a kettle-dev member blocked by unreleased StructuredMerge gems, or vice versa.
+
+- Add clean-installed: the deterministic inverse of install. Uninstalls each selected member's current source version (plus configured install local_dependencies, which install also covers) when that version is unreleased, including cached .gem files. The other two cleanups cannot see this pollution class: clean-unreleased derives candidates from release state and can miss versions it judges released, and clean-blockers only sees lockfile pins, so an installed-but-unpinned gem (observed: commonmarker-merge 7.1.10) survives and then breaks gem activation with a dangling exact pin once the rest of its series is removed. Release state comes from the same ReleaseStateCheck clean-unreleased uses; members at a released source version are left alone. Also extracts MemberLoader from LocalInstall so install and clean-installed construct members identically.
+
+- Add a release-mode pre-clean to bup, bupb, and update-bundler: before a registry-only re-resolution, installed gems whose versions no registry publishes are removed, including cross-family gems named in member lockfiles. Previously the release-mode update only detected such pins after the fact (PublishedVersionCheck) and its advice to re-run the update was circular, because bundler resolves against the local gem dir and >= floors always re-pin the installed unreleased version. Removal up front turns that opaque post-update failure into a resolved-before-it-mattered cleanup. Fails open when the registry is unreachable: a network blip never removes gems. Also adds the standalone clean-installed command, the deterministic inverse of install, which uninstalls each member's unreleased source version (plus install local_dependencies) including cached .gem files.
+
+### Changed
+
+- [kc] kettle-jem/prepare: updated 2 project files:
+  - dependencies (2)
+
+- [kc] kettle-jem/template: updated 3 project files:
+  - code and tests (1)
+  - documentation (1)
+  - other (1)
+
+### Fixed
+
+- Add a structured CommandResult#diagnostics channel carrying complete, machine-readable findings. stdout is a human summary truncated to its last 20 lines, so a JSON consumer parsing it to decide what to act on silently acted on an incomplete set: a real cross-family release reported 28 unpublished lockfile pins and the JSON carried only 20, losing 8 gems. PublishedVersionCheck now emits each pin as gem, version, remote, member, and lockfile data alongside its message.
+
+- clean-blockers (and clean-unreleased, sharing GemUninstallSupport): two uninstall bugs fixed. The batched gem uninstall now retries once with --ignore-dependencies when RubyGems aborts on a dependent outside the batch (Gem::DependencyRemovalException), re-batching only what survived the abort; the dependency refusal previously left a partial cleanup reported as failure. And the cleanup now removes the cached .gem files as well as the installed specifications -- gem uninstall leaves cache/<name>-<version>.gem behind, and the next bundle install was reinstalling the same unreleased versions from that cache without touching the network, so the cleanup did not hold.
+
+- release: stop handing member kettle-release children the family-root dev bundle via BUNDLE_GEMFILE in release mode. That bundle resolves the family's own members, which are unreleased while any member is being released, so the child's kettle-release died booting (observed: "Could not find kettle-family-1.3.9 ... in locally installed gems" for every member). In release mode the child now resolves kettle-release from its own released dependency; local release tooling (KETTLE_DEV_DEV set) still pins the local kettle-dev bundle.
+
+## [1.3.7] - 2026-10-09
+
+- TAG: [v1.3.7][1.3.7t]
+- COVERAGE: 93.30% -- 6778/7265 lines in 38 files
+- BRANCH COVERAGE: 77.95% -- 2757/3537 branches in 38 files
+- 34.47% documented
+
+### Changed
+
+- Reject --start-at for template and test instead of silently dropping members. Those commands dispatch in dependency waves and a concurrent queue, so the set of members that still need work is not a suffix of the configured order and no positional value can select it. The flag now exits 1 with a message pointing at the equivalent --only selection. release is deliberately left accepting --start-at: it uses MEMBER@BRANCH to select a branch lane via release_target_branches, and its own resume hints already use --only rather than --start-at. Sequentially dispatched commands (lint, bup, check, docs, install, sync, push, pull, bump) keep positional --start-at, which is correct because they abort at the first failure so pending genuinely is a suffix.
+
+- [kc] kettle-jem/prepare: updated 5 project files:
+  - dependencies (5)
+
+- [kc] kettle-jem/template: updated 2 project files:
+  - code and tests (1)
+  - other (1)
+
+### Fixed
+
+- Fix clean-unreleased missing locally installed unreleased versions. Under `bundle exec`, every RubyGems enumeration API (find_all_by_name, stubs_for, Specification.all) reports only the versions the active bundle resolves, not everything installed in the gem home. An unreleased version that was built and installed but is not pinned by the lockfile was therefore invisible, so cleanup reported "no unreleased installed versions found" with outcome success while leaving the offender installed -- blind in exactly the state it exists to correct, since re-resolving the lockfile to released versions is what hides the offender. Installed versions are now read by scanning the specification directories under each Gem.path root, which sees every installed version regardless of bundle activation and still excludes PATH/git source checkouts. Verified against the kettle-dev family: the fix now surfaces 10 unreleased members (kettle-rb 0.1.16, kettle-test 2.0.24, token-resolver 2.0.13, and others) that the previous implementation reported as none, while correctly leaving the two released members (kettle-dev 3.1.8, kettle-family 1.3.6) alone.
+
+- Fix clean-unreleased --execute reporting success when gem uninstall removes nothing. RubyGems exits 0 and prints "Gem 'name' is not installed" when the target is absent from GEM_HOME, so an exit-status check could not distinguish a completed cleanup from one that silently did nothing -- the same silent-success failure mode as the enumeration bug. The batch outcome is now verified by re-enumerating installed versions afterwards, and any survivor turns the result into a failure that names it. Investigated and deliberately not implemented: `gem uninstall -i <root>` is not a workaround for a gem home other than GEM_HOME, because it fails with the same "not installed in GEM_HOME" error even when the path equals GEM_HOME. That case already fails loudly with a non-zero exit rather than being reported as success.
+
+- Fix the resume hint for template and test silently dropping members that never ran. Those commands do not dispatch positionally: template groups members into dependency waves derived from gemspec dependencies, test uses a concurrent work queue, and in both a failure only sets a stop flag that prevents threads from popping further work -- members already in flight finish while later waves never run. The pending set is therefore interleaved through the configured order rather than being a suffix of it, so the emitted positional `--start-at <failed member>` dropped every pending member ordered ahead of the failure. Measured on the kettle-dev family: nomono failed in template wave 1 and left kettle-dev, kettle-changelog, kettle-family and kettle-soup-cover pending at ordered positions 6, 8, 9 and 11 while kettle-drift at 7 and kettle-wash at 10 had succeeded, so `--start-at nomono` resumed only nomono and token-resolver and reported outcome success having never templated the other four. Resume hints for these commands are now set-based, mirroring release: one `--only` hint per failure plus a combined `--only` hint naming every member that never ran. Sequentially dispatched commands keep positional `--start-at`, which remains correct because they abort at the first failure. A failed family-root phase still restarts the whole command, since it aborts before member dispatch. Note that template and test ignore the configured `release.waves`, which only affect release ordering.
+
 ## [1.3.6] - 2026-10-07
 
 - TAG: [v1.3.6][1.3.6t]
@@ -2905,7 +2964,11 @@ Please file a bug if you notice a violation of semantic versioning.
 - Fixed CI load failures on engines without compatible `pty` support by falling back to Open3 for interactive release commands.
 - Fixed Ruby 3.2 version-bump support by loading Prism lazily and wiring the Prism gem only for MRI versions that need it.
 
-[Unreleased]: https://github.com/kettle-dev/kettle-family/compare/v1.3.6...HEAD
+[Unreleased]: https://github.com/kettle-dev/kettle-family/compare/v1.3.9...HEAD
+[1.3.9]: https://github.com/kettle-dev/kettle-family/compare/v1.3.7...v1.3.9
+[1.3.9t]: https://github.com/kettle-dev/kettle-family/releases/tag/v1.3.9
+[1.3.7]: https://github.com/kettle-dev/kettle-family/compare/v1.3.6...v1.3.7
+[1.3.7t]: https://github.com/kettle-dev/kettle-family/releases/tag/v1.3.7
 [1.3.6]: https://github.com/kettle-dev/kettle-family/compare/v1.3.5...v1.3.6
 [1.3.6t]: https://github.com/kettle-dev/kettle-family/releases/tag/v1.3.6
 [1.3.5]: https://github.com/kettle-dev/kettle-family/compare/v1.3.4...v1.3.5

data/README.md

@@ -1192,7 +1192,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-7.231-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-7.565-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/kettle-dev/kettle-family/blob/main/SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/lib/kettle/family/blocker_cleanup.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "kettle/dev/lockfile_reset"
+
+module Kettle
+  module Family
+    # Removes locally installed gem versions that block a command, including gems
+    # belonging to OTHER families.
+    #
+    # Why this exists alongside +UnreleasedGemCleanup+ (`clean-unreleased`): that
+    # command derives candidates from family members' release state, so it can
+    # only ever remove a member of its own family whose installed version exceeds
+    # the latest release. The gems that actually block a release are usually
+    # cross-family, and each family is blocked by the other's legitimately
+    # installed development versions. Measured live:
+    #
+    #   kettle-dev        28 pins   ast-crispr 7.1.10, ast-merge, tree_haver, ...
+    #   kettle-drift      22 pins   (all structuredmerge gems)
+    #   kettle-family     28 pins   (all structuredmerge gems)
+    #   kettle-changelog   2 pins   nomono 1.1.7, token-resolver 2.0.13
+    #   kettle-jem         3 pins   kettle-test 2.0.24, nomono, token-resolver
+    #   smorg-rb           3 pins   (all kettle-dev gems)
+    #
+    # Neither family's `clean-unreleased` can see the other's offenders, which is
+    # what forced the kettle-dev 3.1.9 and kettle-family 1.3.7 releases to be
+    # finished manually after `gem push`: the tag, checksum and GitHub Release
+    # steps all run through a release-mode dependency update, and that cannot
+    # resolve while cross-family unreleased pins are present.
+    #
+    # The blocker set comes from calling PublishedVersionCheck directly on each
+    # selected member and reading its structured diagnostics, NOT from running the
+    # blocked command and parsing its report. A dry-run release cannot surface
+    # them: workflow.rb:2522-2526 replaces the member result with a synthetic
+    # "release readiness requires lockfile normalization" entry before
+    # append_release_internal_checks runs, so published_version_check never
+    # appears and every diagnostics array is empty. The findings are computed
+    # inside release_lockfile_readiness_would_fail? (workflow.rb:5785-5794) and
+    # then discarded in favour of a boolean. Running with --execute to obtain them
+    # would run the release, which is what we are trying to unblock.
+    #
+    # PublishedVersionCheck is read-only, so this is safe to run without
+    # --execute; only the uninstall itself is gated.
+    class BlockerCleanup
+      PHASE = "clean_blockers"
+      BLOCKER_KIND = "unpublished_lockfile_pin"
+      NO_BLOCKERS_MESSAGE = "no unpublished lockfile pins found"
+      # A member in local-gem mode resolves its family siblings through PATH
+      # remotes, so its lockfile has no GEM-section specs to check. Reporting
+      # "no blockers" for it would claim a clean bill of health that was never
+      # established, so it is reported separately.
+      NOT_INSPECTABLE_MESSAGE = "lockfile has no registry-resolved pins; nothing inspectable"
+      NOT_REMOVABLE_PREFIX = "blockers pinned but not installed in a gem home (source checkout, not removable): "
+
+      include GemUninstallSupport
+
+      def initialize(members:, execute: false, runner: nil)
+        @members = members
+        @execute = execute
+        @runner = runner || CommandRunner.new(execute: execute)
+      end
+
+      # @return [Array<CommandResult>]
+      def results
+        findings = members.map { |member| member_blockers(member) }
+        removable = removable_candidates(findings)
+        annotated = annotate_contributors(findings, removable)
+        informational = informational_results(annotated)
+        return informational if removable.empty?
+
+        informational + batched_cleanup_results(annotated, removable)
+      end
+
+      private
+
+      attr_reader :members, :execute, :runner
+
+      def uninstall_phase
+        PHASE
+      end
+
+      # One member's blockers, from the check's structured diagnostics.
+      #
+      # @return [Hash] member, blockers (deduped [name, version, remote]),
+      #   inspectable (whether the lockfile had registry pins at all)
+      def member_blockers(member)
+        lockfile = File.join(member.root, "Gemfile.lock")
+        return {member: member, blockers: [], inspectable: false} unless File.file?(lockfile)
+
+        pins = registry_pins(lockfile)
+        result = PublishedVersionCheck.call(member: member)
+        blockers = result.diagnostics
+          .select { |diagnostic| diagnostic["kind"] == BLOCKER_KIND }
+          .map { |diagnostic| [diagnostic["gem"], diagnostic["version"], diagnostic["remote"]] }
+          .uniq
+
+        {member: member, blockers: blockers, inspectable: !pins.empty?}
+      end
+
+      def registry_pins(lockfile)
+        Kettle::Dev::LockfileReset.registry_gem_specs_from_source(File.read(lockfile))
+      rescue
+        []
+      end
+
+      # Blockers that are actually installed in a gem home and can therefore be
+      # removed, deduplicated across members by [name, version].
+      #
+      # A blocker that is not installed in a gem home is a PATH or git source
+      # checkout: `gem uninstall` cannot remove it, and including one would abort
+      # the whole batch. Those are reported rather than attempted.
+      #
+      # The version is normalized by stripping any platform suffix, because a
+      # lockfile pins `nokogiri (1.19.4-x86_64-linux-gnu)` while gem homes store
+      # the spec as `nokogiri-1.19.4-x86_64-linux-gnu.gemspec` and
+      # #installed_versions records it as 1.19.4.
+      def removable_candidates(findings)
+        findings.flat_map { |finding| normalized_blockers(finding) }
+          .uniq
+          .select { |name, version| installed_versions(name).include?(version) }
+      end
+
+      # A finding's blockers as [name, Gem::Version] pairs, minus any whose version
+      # cannot be parsed. Shared by #removable_candidates and #annotate_contributors
+      # so both see identical pairs and cannot drift apart.
+      def normalized_blockers(finding)
+        finding.fetch(:blockers).filter_map do |name, version, _remote|
+          normalized = normalize_version(version)
+          [name, normalized] unless normalized.nil?
+        end
+      end
+
+      # Strips any platform suffix and parses, rejecting blanks.
+      #
+      # The blank guard matters: `Gem::Version.new("")` returns version "0" rather
+      # than raising, so an empty version from a malformed diagnostic would become
+      # a bogus `name:0` uninstall argument instead of being skipped.
+      #
+      # @return [Gem::Version, nil]
+      def normalize_version(version)
+        text = version.to_s.split("-", 2).first.to_s.strip
+        return nil if text.empty?
+
+        parse_gem_version(text)
+      end
+
+      # Adds `:own` — the subset of the global removable set this member pinned.
+      #
+      # Computed once here rather than on demand: three call sites need it
+      # (host selection, contributing filter, per-member reporting), and each
+      # would otherwise re-run the same normalization and membership test.
+      def annotate_contributors(findings, removable)
+        findings.map do |finding|
+          own = normalized_blockers(finding).select { |candidate| removable.include?(candidate) }.uniq
+          finding.merge(own: own)
+        end
+      end
+
+      # Per-member reporting. Members that contributed removable blockers get the
+      # shared batch outcome; the rest get a plain informational result.
+      def informational_results(annotated)
+        annotated.filter_map do |finding|
+          next if finding.fetch(:own).any?
+
+          member = finding.fetch(:member)
+          message = if finding.fetch(:blockers).any?
+            unremovable_blockers_message(finding)
+          elsif finding.fetch(:inspectable)
+            NO_BLOCKERS_MESSAGE
+          else
+            NOT_INSPECTABLE_MESSAGE
+          end
+          informational_result(member: member, message: message)
+        end
+      end
+
+      def contributors(annotated)
+        annotated.select { |finding| finding.fetch(:own).any? }
+      end
+
+      # Names the blockers this member pinned that cannot be removed here, and
+      # why, so a cross-family offender is attributable rather than mysterious.
+      def unremovable_blockers_message(finding)
+        names = finding.fetch(:blockers).map { |name, version, _remote| "#{name} #{version}" }
+        "#{NOT_REMOVABLE_PREFIX}#{names.join(", ")}"
+      end
+
+      # Runs the batch once, then reports that one outcome against every member
+      # that contributed to it. See the class comment for why a single batched
+      # invocation is required rather than one per gem.
+      def batched_cleanup_results(annotated, removable)
+        contributing = contributors(annotated)
+        # Defensive: `removable` is derived from findings' own blockers, so a
+        # non-empty set always has at least one contributor. Guarded anyway
+        # because a nil host would raise NoMethodError inside the uninstall.
+        host = contributing.first&.fetch(:member)
+        return [] if host.nil?
+
+        command = batched_uninstall_command(removable)
+        # gem uninstall does not depend on the working directory, so the first
+        # contributing member provides a real directory to execute in.
+        outcome = if execute
+          verified_uninstall_outcome(candidates: removable, host: host, command: command)
+        else
+          dry_run_uninstall_outcome(command: command)
+        end
+
+        contributing.map { |finding| member_result(finding, outcome) }
+      end
+
+      # One member's view of the shared batch outcome, naming the gems that member
+      # pinned so a failure is attributable rather than mysterious.
+      #
+      # The member's own contribution comes from the annotated finding:
+      # PublishedVersionCheck hits the registry, so re-invoking it during
+      # reporting would add a network round-trip per member.
+      def member_result(finding, outcome)
+        member = finding.fetch(:member)
+        own = finding.fetch(:own)
+        own_reason = describe_gem_versions(own)
+        reason = if outcome.ok? || own.empty?
+          outcome.reason
+        else
+          "batched gem uninstall including #{own_reason} failed"
+        end
+        outcome.dup.tap do |copy|
+          copy.member_name = member.name
+          copy.workdir = member.root
+          copy.stdout = outcome.skipped ? "would uninstall #{own_reason}" : outcome.stdout
+          copy.reason = reason
+        end
+      end
+
+      def informational_result(member:, message:)
+        CommandResult.new(
+          member_name: member.name,
+          phase: PHASE,
+          command: ["internal", PHASE],
+          workdir: member.root,
+          status: 0,
+          success: true,
+          stdout: message,
+          stderr: "",
+          elapsed_seconds: 0.0,
+          skipped: false,
+          reason: nil
+        )
+      end
+    end
+  end
+end

data/lib/kettle/family/clean_installed.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module Kettle
+  module Family
+    # Uninstalls exactly what `install` installs: each selected member's current
+    # source version, plus the cached .gem files.
+    #
+    # This is the deterministic inverse of `install`, and it exists because the
+    # other two cleanups cannot see this class of pollution:
+    #
+    # - +UnreleasedGemCleanup+ (`clean-unreleased`) removes installed versions
+    #   newer than the latest release, but it derives candidates per member from
+    #   release state and can miss versions it judges released.
+    # - +BlockerCleanup+ (`clean-blockers`) removes what members' lockfiles pin,
+    #   so an installed-but-unpinned gem is invisible to it. Observed live:
+    #   commonmarker-merge 7.1.10 survived a blocker cleanup (no release
+    #   lockfile pinned it), then broke gem activation family-wide with its
+    #   dangling exact pin on markdown-merge = 7.1.10 once the rest of the
+    #   series was removed.
+    #
+    # Candidates are the members `install` would act on -- the selected members
+    # plus any configured install local_dependencies -- restricted to those whose
+    # source version is unreleased (a member already at its released version has
+    # nothing to remove; uninstalling it would only churn the bundles that
+    # resolve it). Release state comes from the same ReleaseStateCheck
+    # +UnreleasedGemCleanup+ uses.
+    #
+    # The uninstall itself is the shared GemUninstallSupport batch: one
+    # invocation, a documented --ignore-dependencies retry when an out-of-batch
+    # dependent aborts it, cache removal, and post-uninstall re-enumeration.
+    #
+    # Note for the family running it: when this command is executed from an
+    # installed kettle-family, the batch includes kettle-family itself. The
+    # uninstall runs in a subprocess, so self-removal mid-run is safe; the
+    # executable falls back to the latest released install afterwards.
+    class CleanInstalled
+      PHASE = "clean_installed"
+      RELEASED_MESSAGE = "source version is released; nothing to uninstall"
+      NOT_INSTALLED_MESSAGE = "source version is not installed"
+      UNKNOWN_VERSION_MESSAGE = "source version is unknown; nothing to uninstall"
+      UNKNOWN_RELEASED_MESSAGE = "latest released version is unknown; no cleanup attempted"
+
+      include GemUninstallSupport
+      include MemberLoader
+
+      def initialize(config:, members:, execute: false, runner: nil)
+        @config = config
+        @members = members
+        @execute = execute
+        @runner = runner || CommandRunner.new(execute: execute)
+      end
+
+      # @return [Array<CommandResult>]
+      def results
+        findings = member_findings
+        removable = findings.filter_map { |finding| finding[:candidate] }.uniq
+        annotated = findings.map do |finding|
+          candidate = finding[:candidate]
+          own = (candidate && removable.include?(candidate)) ? [candidate] : []
+          finding.merge(own: own)
+        end
+        informational = annotated.filter_map { |finding| informational_for(finding) }
+        return informational if removable.empty?
+
+        informational + batched_cleanup_results(annotated.select { |finding| finding[:own].any? }, removable)
+      end
+
+      private
+
+      attr_reader :config, :members, :execute, :runner
+
+      def uninstall_phase
+        PHASE
+      end
+
+      # The members `install` would act on: selected members plus configured
+      # install local_dependencies, deduplicated by name.
+      def candidate_members
+        local = config.install_local_dependencies.map { |path| member_from_path(path) }
+        seen = {}
+        (local + members).each_with_object([]) do |member, memo|
+          next if seen.key?(member.name)
+
+          seen[member.name] = true
+          memo << member
+        end
+      end
+
+      def release_state_by_member
+        ReleaseStateCheck.new(config: config, members: candidate_members).results.each_with_object({}) do |result, memo|
+          memo[result.member_name] = result
+        end
+      end
+
+      # One member's candidate: its source version, when that version is
+      # unreleased and installed. [name, Gem::Version] or nil, plus the reason
+      # there is nothing to do.
+      def member_findings
+        states = release_state_by_member
+        candidate_members.map do |member|
+          state = states[member.name]
+          candidate, message = candidate_for(member, state)
+          {member: member, candidate: candidate, message: message, state: state}
+        end
+      end
+
+      def candidate_for(member, state)
+        return [nil, nil] unless state&.ok?
+
+        latest = latest_released_version(state.state)
+        return [nil, nil] unless latest
+
+        source = parse_gem_version(member.version.to_s)
+        return [nil, UNKNOWN_VERSION_MESSAGE] unless source
+        return [nil, RELEASED_MESSAGE] unless source > latest
+        return [[member.name, source], nil] if installed_versions(member.name).include?(source)
+
+        [nil, NOT_INSTALLED_MESSAGE]
+      end
+
+      def latest_released_version(state)
+        value = state.fetch("latest_released", nil).to_s
+        return nil if value.empty? || value == "unknown"
+
+        Gem::Version.new(value.delete_prefix("v"))
+      rescue ArgumentError
+        nil
+      end
+
+      # Per-member outcomes that are not part of the batch: unreadable release
+      # state (a failure naming its member), or nothing to do (informational).
+      def informational_for(finding)
+        member = finding.fetch(:member)
+        state = finding[:state]
+        return release_state_failure(member: member, release_state: state) unless state&.ok?
+
+        message = finding[:message]
+        return nil if message.nil? && finding[:own].any?
+        return informational_result(member: member, message: UNKNOWN_RELEASED_MESSAGE) if message.nil?
+
+        informational_result(member: member, message: message)
+      end
+
+      # Runs the batch once, then reports that one outcome against every member
+      # whose gem was in it, mirroring UnreleasedGemCleanup: the command and
+      # exit state are shared, but each member reports only its own gem so a
+      # failure stays attributable.
+      def batched_cleanup_results(contributors, removable)
+        host = contributors.first.fetch(:member)
+        command = batched_uninstall_command(removable)
+        outcome = if execute
+          verified_uninstall_outcome(candidates: removable, host: host, command: command)
+        else
+          dry_run_uninstall_outcome(command: command)
+        end
+
+        contributors.map do |finding|
+          member_result(finding.fetch(:member), outcome, finding.fetch(:own))
+        end
+      end
+
+      def member_result(member, outcome, own_candidates)
+        own = describe_gem_versions(own_candidates)
+        reason = if outcome.ok? || own_candidates.empty?
+          outcome.reason
+        else
+          "batched gem uninstall including #{own} failed"
+        end
+        outcome.dup.tap do |copy|
+          copy.member_name = member.name
+          copy.workdir = member.root
+          copy.stdout = outcome.skipped ? "would uninstall #{own}" : outcome.stdout
+          copy.reason = reason
+        end
+      end
+
+      def informational_result(member:, message:)
+        CommandResult.new(
+          member_name: member.name,
+          phase: PHASE,
+          command: ["internal", PHASE],
+          workdir: member.root,
+          status: 0,
+          success: true,
+          stdout: message,
+          stderr: "",
+          elapsed_seconds: 0.0,
+          skipped: false,
+          reason: nil
+        )
+      end
+
+      def release_state_failure(member:, release_state:)
+        CommandResult.new(
+          member_name: member.name,
+          phase: PHASE,
+          command: ["internal", PHASE],
+          workdir: member.root,
+          status: release_state&.status || 1,
+          success: false,
+          stdout: "",
+          stderr: release_state&.stderr.to_s,
+          elapsed_seconds: 0.0,
+          skipped: false,
+          reason: "release state unavailable"
+        )
+      end
+    end
+  end
+end

data/lib/kettle/family/cli.rb

@@ -11,7 +11,7 @@ module Kettle
     class CLI < CommandKit::Command
       include CommandKit::Commands
 
-      COMMANDS = %w[version mise-trust discover plan report metadata check clean-unreleased reconcile-releases reset test lint docs template gha-sha-pins bup bupb update-bundler bex install bump bump-version add-changelog release push pull sync up branch-lanes release-state state].freeze
+      COMMANDS = %w[version mise-trust discover plan report metadata check clean-blockers clean-installed clean-unreleased reconcile-releases reset test lint docs template gha-sha-pins bup bupb update-bundler bex install bump bump-version add-changelog release push pull sync up branch-lanes release-state state].freeze
       WORKFLOW_COMMANDS = %w[check reset test lint docs template gha-sha-pins bup bupb update-bundler bex release push pull sync up].freeze
 
       command_name "kettle-family"
@@ -353,6 +353,18 @@ module Kettle
         description "Uninstall locally installed family gem versions newer than the latest released version."
       end
 
+      class CleanBlockers < WorkflowCommand
+        command_name "clean-blockers"
+        usage "[options]"
+        description "Uninstall locally installed gems, from any family, whose unreleased versions are pinned by members' lockfiles."
+      end
+
+      class CleanInstalled < WorkflowCommand
+        command_name "clean-installed"
+        usage "[options]"
+        description "Uninstall the exact gem versions install installs: each member's current source version, when unreleased, including cached .gem files."
+      end
+
       class ReconcileReleases < BaseCommand
         include ExecutionOptions
 
@@ -657,6 +669,8 @@ module Kettle
       command "report", ReportCommand
       command Metadata
       command Check
+      command CleanBlockers
+      command CleanInstalled
       command CleanUnreleased
       command ReconcileReleases
       command Reset
@@ -715,6 +729,7 @@ module Kettle
       def build_report(command, options)
         config = Config.load(root: options[:root], path: options[:config])
         start_at = parse_start_at(options[:start_at])
+        Selection.validate_positional_start_at!(command, start_at.member)
         effective_only = default_only_filter(command: command, only: options[:only])
         discovery = Discovery.new(
           config: config,
@@ -869,6 +884,8 @@ module Kettle
         return bump_version_results(config: config, members: members, options: options, phase: command, release_state_results: release_state_results) if %w[bump bump-version].include?(command)
         return add_changelog_results(members: members, options: options) if command == "add-changelog"
         return clean_unreleased_results(config: config, members: members, options: options) if command == "clean-unreleased"
+        return clean_blockers_results(members: members, options: options) if command == "clean-blockers"
+        return clean_installed_results(config: config, members: members, options: options) if command == "clean-installed"
         return reconcile_release_results(config: config, members: members, options: options) if command == "reconcile-releases"
         return branch_lane_results(config: config, members: members) if command == "branch-lanes"
         return release_state_results(config: config, members: members, jobs: options[:jobs], event_handler: state_event_handler) if command == "release-state"
@@ -1360,6 +1377,14 @@ module Kettle
         UnreleasedGemCleanup.new(config: config, members: members, execute: options[:execute]).results
       end
 
+      def clean_blockers_results(members:, options:)
+        BlockerCleanup.new(members: members, execute: options[:execute]).results
+      end
+
+      def clean_installed_results(config:, members:, options:)
+        CleanInstalled.new(config: config, members: members, execute: options[:execute]).results
+      end
+
       def reconcile_release_results(config:, members:, options:)
         ReleaseReconciler.new(config: config, members: members, execute: options[:execute]).results
       end