kettle-family 1.3.3 → 1.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fd15138050afedb68be9d6d294f7e3a01dc1554949c8607b1176ddf8d061581
-  data.tar.gz: 272997658ef8c5a96b14fbc1dcc8d124b545abe50d5bc0ca423823c8dffc3ad8
+  metadata.gz: 3e18a444e22f9d52b19ef8396ce75bc80b85bb579fb353889fecb8547ddc8bec
+  data.tar.gz: b91bb8aa9018297be574e1eda7ddc26c6b8f314692cd4c4881c95fa4fe52062a
 SHA512:
-  metadata.gz: a5bac59bea82eec800e67069ae00f8810c54a29a7fe3119b4c9ef93f94924af677b0da411635928841d9c0df47d4bfb11853d622cccaf1c72faf6f6419a552d6
-  data.tar.gz: c4d9b06b6fed1f0822bdc62ec6d22b3cb379bc1fe7b49e388038e58780c567ecbe3f589e11faa7845e92b2b6b7d365499271f17d0ad8e942636d632f25dbf950
+  metadata.gz: 50d83077bd30c1c673772be79765f02d263cf499b382355f8b647889255abb9608155e8a0434d6c98d549ddad5188186f50e56b9608537e47b1cb5f2c1cfec5a
+  data.tar.gz: e81978953b9a9d94d2c518d770cd72e6b6efbcd5a3fd2c010da97f72cb9107d71624bd126cdf1799c1e17276f3546adaca3246089e151b6bccc7edc04db4cef2

data/CHANGELOG.md

@@ -30,6 +30,60 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [1.3.5] - 2026-10-05
+
+- TAG: [v1.3.5][1.3.5t]
+- COVERAGE: 93.16% -- 6636/7123 lines in 37 files
+- BRANCH COVERAGE: 77.64% -- 2701/3479 branches in 37 files
+- 33.64% documented
+
+### Added
+
+- `Kettle::Family::ReleaseStateCheck` accepts a `branches:` scope, and `Kettle::Family::Selection.branches_matching` reports which of a member branch stack currently satisfies a release-state token. Both are the seams for per-branch release and bump decisions.
+
+### Changed
+
+- A blocked release now reports phase `release_blocked` instead of `release_skip`, so a hard failure is never reported as a skipped member in the progress summary or report.
+
+- [kc] kettle-jem/prepare: updated 12 project files:
+  - dependencies (12)
+
+- [kc] kettle-jem/template: updated 6 project files:
+  - code and tests (1)
+  - dependencies (1)
+  - documentation (1)
+  - other (2)
+  - workflows (1)
+
+### Fixed
+
+- Already-released detection for branch-stack members is now scoped to the branch being released instead of the whole stack, so a clean published branch is no longer reported as having unreleased changes and blocked with a release_skip failure.
+
+- A published version whose release tag is followed only by post-release maintenance commits (checksums, dependency-floor lockfile reconciliation) is now skipped as already released; only changes to the gemspec, version file, or changelog after the tag make the published version stale.
+
+- Release-state status-token selection (`--only unreleased|prepared|pending|bump`) no longer collapses a branch-stack member to whichever branch happened to be evaluated last; a member is selected when any of its branches matches, and multiple tokens are still ANDed within a single branch.
+
+- `kettle-family bump` now bumps each branch of a member branch stack independently: branches with no pending version bump are reported as skipped instead of being bumped, so an already-released branch is no longer given version bumps it never needed. An explicit `--only MEMBER` remains an unconditional request and is not filtered.
+
+- Release-state worktrees orphaned by a killed run are reaped on the next run. Directories are named `worktree-PID-RANDOM`, so only those whose owning PID is no longer running are removed; live worktrees from concurrent runs are left alone.
+
+## [1.3.4] - 2026-10-02
+
+- TAG: [v1.3.4][1.3.4t]
+- COVERAGE: 93.26% -- 6571/7046 lines in 37 files
+- BRANCH COVERAGE: 77.70% -- 2666/3431 branches in 37 files
+- 33.33% documented
+
+### Added
+
+- kettle-family installs the latest stable Bundler and updates family lockfiles with `update-bundler`.
+
+### Fixed
+
+- Lock each repository's worktree registry across process setup, parallel branch probes, and cleanup to prevent intermittent Git worktree failures.
+
+- Family reports now include results from the update-bundler command.
+
 ## [1.3.3] - 2026-09-28
 
 - TAG: [v1.3.3][1.3.3t]
@@ -2830,7 +2884,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.3...HEAD
+[Unreleased]: https://github.com/kettle-dev/kettle-family/compare/v1.3.5...HEAD
+[1.3.5]: https://github.com/kettle-dev/kettle-family/compare/v1.3.4...v1.3.5
+[1.3.5t]: https://github.com/kettle-dev/kettle-family/releases/tag/v1.3.5
+[1.3.4]: https://github.com/kettle-dev/kettle-family/compare/v1.3.3...v1.3.4
+[1.3.4t]: https://github.com/kettle-dev/kettle-family/releases/tag/v1.3.4
 [1.3.3]: https://github.com/kettle-dev/kettle-family/compare/v1.3.2...v1.3.3
 [1.3.3t]: https://github.com/kettle-dev/kettle-family/releases/tag/v1.3.3
 [1.3.2]: https://github.com/kettle-dev/kettle-family/compare/v1.3.1...v1.3.2

data/README.md

@@ -510,6 +510,7 @@ The command names below are available from `kettle-family --help`:
 | `gha-sha-pins` | Inspect or update GitHub Actions SHA pins. |
 | `bup` | Run `bundle update --all`, or update a named dependency, at the family root and per member. |
 | `bupb` | Run `bundle update --bundler` at the family root and per member. |
+| `update-bundler` | Install the latest stable Bundler from RubyGems, then update family lockfiles. |
 | `bex` | Run an arbitrary `bundle exec` command per member. |
 | `install` | Build and install selected local family gems. |
 | `bump` | Check, plan, or execute family version alignment. |
@@ -614,6 +615,11 @@ root-first order with `bundle update --bundler`. A root that is itself a member
 is updated only once. A gem name may be passed to `bup` to update only that
 dependency, for example `kettle-family bup --execute kettle-test`.
 
+`update-bundler` installs the latest stable Bundler from `https://rubygems.org`
+without enabling prereleases, then runs the same root-first lockfile update as
+`bupb`. Family mise tasks select an installed stable Bundler explicitly to
+start the command, so an installed prerelease cannot intercept startup.
+
 Executed member updates commit successful lockfile changes by default. The
 family-root lockfile is also validated and committed for monorepos, where the
 root and members share one Git repository. A sibling-repository family root is
@@ -1186,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.011-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-7.123-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/cli.rb

@@ -4,14 +4,15 @@ require "command_kit"
 require "command_kit/commands"
 require "fileutils"
 require "optparse"
+require "rubygems/dependency_installer"
 
 module Kettle
   module Family
     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 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 bex release push pull sync up].freeze
+      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
+      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"
       usage "[options] COMMAND [ARGS...]"
@@ -27,6 +28,16 @@ module Kettle
         main(argv, stdout: out, stderr: err)
       end
 
+      # Defined as a singleton method above the `private` keyword: a `private`
+      # instance modifier does not apply to `def self.` definitions.
+      def self.default_only_filter(command:, only:)
+        return only unless only.to_s.empty?
+        return "bump" if %w[bump bump-version].include?(command)
+        return "pending" if command == "release"
+
+        only
+      end
+
       module SharedOptions
         def self.included(base)
           base.option :root, value: {type: String, usage: "PATH"}, desc: "Workspace or family root"
@@ -187,7 +198,12 @@ module Kettle
         end
 
         def run_family(command, overrides = {})
-          Kettle::Family::CLI.new(stdout: stdout, stderr: stderr).run_command(command, family_options(overrides))
+          effective = family_options(overrides)
+          # Thread the *effective* --only (including the command's default
+          # release-state token) downstream so per-branch logic sees the same
+          # selection the member selector used.
+          effective[:only] = Kettle::Family::CLI.default_only_filter(command: command, only: effective[:only])
+          Kettle::Family::CLI.new(stdout: stdout, stderr: stderr).run_command(command, effective)
         end
 
         def truthy_option?(name)
@@ -434,6 +450,31 @@ module Kettle
         description "Plan or execute bundle update --bundler."
       end
 
+      class UpdateBundler < WorkflowCommand
+        command_name "update-bundler"
+        usage "[options]"
+        description "Install the latest stable Bundler, then update family lockfiles."
+
+        def run(*args)
+          unexpected_arguments!(args)
+          install_latest_stable_bundler if truthy_option?(:execute)
+          run_family("update-bundler")
+        end
+
+        private
+
+        def install_latest_stable_bundler
+          original_sources = Gem.sources.to_a
+          Gem.sources = ["https://rubygems.org"]
+          Gem::DependencyInstaller.new(domain: :remote, prerelease: false, document: []).install("bundler")
+          Gem::Specification.reset
+        rescue => error
+          raise Error, "could not install latest stable Bundler from RubyGems: #{error.message}"
+        ensure
+          Gem.sources = original_sources if original_sources
+        end
+      end
+
       class Bex < WorkflowCommand
         command_name "bex"
         usage "[options] -- COMMAND [ARGS...]"
@@ -626,6 +667,7 @@ module Kettle
       command GhaShaPins
       command Bup
       command Bupb
+      command UpdateBundler
       command Bex
       command Install
       command Bump
@@ -795,11 +837,7 @@ module Kettle
       end
 
       def default_only_filter(command:, only:)
-        return only unless only.to_s.empty?
-        return "bump" if %w[bump bump-version].include?(command)
-        return "pending" if command == "release"
-
-        only
+        self.class.default_only_filter(command: command, only: only)
       end
 
       def direct_member_only_names(only)
@@ -1095,6 +1133,17 @@ module Kettle
             memo.last.branch = branch
             break unless memo.last.ok?
 
+            if (skipped = branch_bump_skip_result(
+              member: member,
+              branch: branch,
+              command: command,
+              options: options,
+              release_state_results: release_state_results
+            ))
+              memo << skipped
+              next
+            end
+
             branch_members = rediscovered_selected_members(config: member_config, selected_names: [member.name], command: command)
             branch_members = [member] if branch_members.empty?
             branch_results = command_results_for_current_branch(
@@ -1113,6 +1162,41 @@ module Kettle
         end
       end
 
+      BUMP_COMMANDS = %w[bump bump-version].freeze
+
+      # Bumping a whole branch stack must be per-branch: a branch already
+      # released with nothing pending has nothing to bump. `--only bump` is a
+      # status-driven selection, so it is filtered by each branch's own
+      # release-state. An explicit `--only MEMBER` is a direct request and is
+      # honored as given.
+      def branch_bump_skip_result(member:, branch:, command:, options:, release_state_results:)
+        return unless BUMP_COMMANDS.include?(command)
+        return unless status_token_only?(options[:only])
+
+        matching = Selection.branches_matching(release_state_results, member_name: member.name, tokens: %w[bump])
+        return if matching.empty? || matching.include?(branch)
+
+        CommandResult.new(
+          member_name: member.name,
+          phase: command,
+          command: ["internal", "branch-bump-skip", branch],
+          workdir: member.root,
+          status: 0,
+          success: true,
+          stdout: "#{member.name}@#{branch} has no unreleased entries at its released version; skipping bump on this branch",
+          stderr: "",
+          elapsed_seconds: 0.0,
+          skipped: true,
+          reason: "no version bump pending on #{branch}",
+          branch: branch
+        )
+      end
+
+      def status_token_only?(only)
+        names = only.to_s.split(",").map(&:strip).reject(&:empty?)
+        !names.empty? && names.all? { |name| Selection.status_token?(name) }
+      end
+
       def rediscovered_selected_members(config:, selected_names:, command:)
         discovered = Discovery.new(config: config).members
         ordered = (command == "install") ? install_order(discovered, config) : Orderer.new(members: discovered, mode: config.order_mode, hints: config.order_hints).ordered

data/lib/kettle/family/release_state_check.rb

@@ -23,11 +23,18 @@ module Kettle
       ].freeze
       TRANSFER_CHANGELOG_TOTAL_UNSET = Object.new.freeze
       CACHE_MISS = Object.new.freeze
-
-      def initialize(members:, config: nil, jobs: nil)
+      WORKTREE_ADMIN_MUTEX = Mutex.new
+
+      # +branches+ scopes the check to specific release target branches. A
+      # branch-stack member produces one result per branch; a per-branch
+      # decision (is this branch already published? does it need a bump?) must
+      # never consult the whole stack, or every branch inherits the state of
+      # the branch that happens to have unreleased entries.
+      def initialize(members:, config: nil, jobs: nil, branches: nil)
         @members = members
         @config = config
         @jobs = jobs
+        @branches = branches&.map(&:to_s)&.reject(&:empty?)
         @github_latest_release_by_repo = {}
         @transfer_changelog_status_by_root = {}
         @transfer_changelog_lag_by_key = {}
@@ -37,6 +44,7 @@ module Kettle
       end
 
       def results(event_handler: nil)
+        return scoped_checkout_results(event_handler: event_handler) if checked_out_scoped_results?
         return branch_results(event_handler: event_handler) unless release_target_branches.empty?
         if shared_changelog?
           results = parallel_map(members) { |member| check_shared_changelog_member_or_local(member, event_handler: event_handler) }
@@ -52,26 +60,53 @@ module Kettle
 
       private
 
-      attr_reader :members, :config, :jobs
+      attr_reader :members, :config, :jobs, :branches
+
+      # A single-branch scope whose checkout already sits on that branch needs
+      # no worktree: the primary checkout is the branch under test.
+      def checked_out_scoped_results?
+        return false unless branches&.one?
+
+        members.any? { |member| current_branch_for(member) == branches.first }
+      end
+
+      def scoped_checkout_results(event_handler: nil)
+        branch = branches.first
+        results = parallel_map(members) { |member| check_member(member, branch: branch, event_handler: event_handler) }
+        results.flatten
+      end
+
+      def current_branch_for(member)
+        git_output(member.root, "branch", "--show-current")
+      end
 
       def branch_results(event_handler: nil)
         root = git_root
         selected_names = members.map(&:name)
-        parallel_map(release_target_branches) do |branch|
-          branch_results_for(branch: branch, root: root, selected_names: selected_names, event_handler: event_handler)
-        end.flatten
+        with_branch_worktrees(root: root, branches: release_target_branches) do |entries|
+          parallel_map(entries) do |entry|
+            if entry[:error]
+              error_result(branch: entry[:branch], error: entry[:error])
+            else
+              branch_results_for_worktree(
+                branch: entry[:branch],
+                worktree_root: entry[:worktree_root],
+                selected_names: selected_names,
+                event_handler: event_handler
+              )
+            end
+          end.flatten
+        end
       end
 
-      def branch_results_for(branch:, root:, selected_names:, event_handler:)
-        with_branch_worktree(root: root, branch: branch) do |worktree_root|
-          branch_members = discover_branch_members(worktree_root: worktree_root, selected_names: selected_names)
-          if shared_changelog?
-            results = parallel_map(branch_members) { |member| check_shared_changelog_member_or_local(member, branch: branch, event_handler: event_handler) }
-            next normalize_shared_version_bump(results)
-          end
-
-          parallel_map(branch_members) { |member| check_member(member, branch: branch, event_handler: event_handler) }
+      def branch_results_for_worktree(branch:, worktree_root:, selected_names:, event_handler:)
+        branch_members = discover_branch_members(worktree_root: worktree_root, selected_names: selected_names)
+        if shared_changelog?
+          results = parallel_map(branch_members) { |member| check_shared_changelog_member_or_local(member, branch: branch, event_handler: event_handler) }
+          return normalize_shared_version_bump(results)
         end
+
+        parallel_map(branch_members) { |member| check_member(member, branch: branch, event_handler: event_handler) }
       rescue Error => error
         [error_result(branch: branch, error: error)]
       end
@@ -759,6 +794,7 @@ module Kettle
 
       def release_target_branches
         return [] unless config
+        return @branches if @branches
 
         config.release_target_branches
       end
@@ -826,25 +862,87 @@ module Kettle
         File.realpath(stdout.strip)
       end
 
-      def with_branch_worktree(root:, branch:)
+      def with_branch_worktrees(root:, branches:)
+        with_worktree_registry_lock(root: root) do
+          base = File.join(root, "tmp", "kettle-family-release-state")
+          FileUtils.mkdir_p(base)
+          prune_stale_worktrees(root: root)
+          entries = branches.map do |branch|
+            {branch: branch, worktree_root: File.join(base, "worktree-#{Process.pid}-#{SecureRandom.hex(8)}")}
+          end
+          entries.each do |entry|
+            add_branch_worktree(root: root, branch: entry[:branch], worktree_root: entry[:worktree_root])
+          rescue Error => error
+            entry[:error] = error
+          end
+          yield entries
+        ensure
+          entries&.reverse_each do |entry|
+            remove_branch_worktree(root: root, worktree_root: entry[:worktree_root])
+          end
+        end
+      end
+
+      def with_worktree_registry_lock(root:)
+        stdout, stderr, status = Open3.capture3("git", "rev-parse", "--git-common-dir", chdir: root)
+        raise Error, "could not determine git common directory for #{root}: #{stderr}" unless status.success?
+
+        lock_path = File.join(File.expand_path(stdout.strip, root), "kettle-family-worktree.lock")
+        File.open(lock_path, File::RDWR | File::CREAT, 0o600) do |lock_file|
+          lock_file.flock(File::LOCK_EX)
+          yield
+        ensure
+          lock_file&.flock(File::LOCK_UN)
+        end
+      end
+
+      # A killed run (SIGKILL, terminal close) skips the ensure-block cleanup and
+      # leaves registered worktrees behind. Registered-but-ownerless worktrees
+      # are pinned refs that accumulate forever, so reap them on the way in.
+      def prune_stale_worktrees(root:)
         base = File.join(root, "tmp", "kettle-family-release-state")
-        FileUtils.mkdir_p(base)
-        worktree_root = File.join(base, "worktree-#{Process.pid}-#{SecureRandom.hex(8)}")
-        add_branch_worktree(root: root, branch: branch, worktree_root: worktree_root)
-        yield worktree_root
-      ensure
-        remove_branch_worktree(root: root, worktree_root: worktree_root)
+        WORKTREE_ADMIN_MUTEX.synchronize do
+          Open3.capture3("git", "worktree", "prune", chdir: root)
+          orphaned_worktree_paths(base).each do |path|
+            Open3.capture3("git", "worktree", "remove", "--force", path, chdir: root)
+            FileUtils.rm_rf(path)
+          end
+        end
+      end
+
+      # Worktree directories are named worktree-PID-RANDOM. A PID that is no
+      # longer running cannot still own a live worktree.
+      def orphaned_worktree_paths(base)
+        Dir[File.join(base, "worktree-*")].select do |path|
+          pid = File.basename(path)[/worktree-(\d+)-/, 1]
+          next false if pid.nil? || pid == Process.pid.to_s
+
+          !process_alive?(pid)
+        end
+      end
+
+      def process_alive?(pid)
+        Process.kill(0, pid)
+        true
+      rescue Errno::ESRCH
+        false
+      rescue Errno::EPERM
+        true
       end
 
       def add_branch_worktree(root:, branch:, worktree_root:)
-        _stdout, stderr, status = Open3.capture3("git", "worktree", "add", "--detach", worktree_root, branch, chdir: root)
-        raise Error, "could not add worktree for #{branch}: #{stderr}" unless status.success?
+        WORKTREE_ADMIN_MUTEX.synchronize do
+          _stdout, stderr, status = Open3.capture3("git", "worktree", "add", "--detach", worktree_root, branch, chdir: root)
+          raise Error, "could not add worktree for #{branch}: #{stderr}" unless status.success?
+        end
       end
 
       def remove_branch_worktree(root:, worktree_root:)
         return unless worktree_root && Dir.exist?(worktree_root)
 
-        Open3.capture3("git", "worktree", "remove", "--force", worktree_root, chdir: root)
+        WORKTREE_ADMIN_MUTEX.synchronize do
+          Open3.capture3("git", "worktree", "remove", "--force", worktree_root, chdir: root)
+        end
       end
 
       def discover_branch_members(worktree_root:, selected_names:)

data/lib/kettle/family/report.rb

@@ -29,6 +29,7 @@ module Kettle
         template
         test
         up
+        update-bundler
       ].freeze
 
       attr_reader :family_name, :family_mode, :order_mode, :members, :selected_members, :config_path, :command, :results, :branch_lanes, :release_target_branches, :member_release_target_branches, :release_mode, :release_resume_arguments, :warnings, :event_log_dirs
@@ -516,6 +517,7 @@ module Kettle
 
       def release_terminal_result?(result)
         result.phase == "release_skip" ||
+          result.phase == "release_blocked" ||
           result.phase == "release_publish" ||
           result.phase == "release_build"
       end

data/lib/kettle/family/selection.rb

@@ -21,6 +21,21 @@ module Kettle
         STATUS_TOKEN_KEYS.key?(value.to_s)
       end
 
+      # Defined as a singleton method above the `private` keyword: a `private`
+      # instance modifier does not apply to `def self.` definitions.
+      #
+      # Branches of one member that currently satisfy +tokens+. Used to decide
+      # per-branch bump work, so a bump never touches a branch that has nothing
+      # to release.
+      def self.branches_matching(release_state_results, member_name:, tokens:)
+        keys = Array(tokens).map(&:to_s).filter_map { |token| STATUS_TOKEN_KEYS[token] }
+        return [] if keys.empty?
+
+        Array(release_state_results).select do |result|
+          result.member_name == member_name && keys.all? { |key| result.state[key] == true }
+        end.map(&:branch).compact.uniq
+      end
+
       def self.validate_release_state_only_filter!(only)
         names = only.to_s.split(",").map(&:strip).reject(&:empty?)
         status_tokens = names.select { |name| status_token?(name) }
@@ -83,22 +98,29 @@ module Kettle
         selected.drop(index)
       end
 
+      # A branch-stack member yields one release-state result per branch, all
+      # sharing a member_name. Collapsing them by member_name alone would let
+      # whichever branch came last decide selection for every branch, so a
+      # member qualifies when *any* of its branches matches the token.
       def select_release_state_status(selected, status_tokens)
         results_by_member = release_state_results_by_member
-        failed = results_by_member.values.select { |result| !result.ok? }
-        raise Error, "release-state check failed for: #{failed.map(&:member_name).join(", ")}" unless failed.empty?
+        failed = results_by_member.values.flatten.select { |result| !result.ok? }
+        raise Error, "release-state check failed for: #{failed.map(&:member_name).uniq.join(", ")}" unless failed.empty?
 
         selected.select do |candidate|
-          result = results_by_member[candidate.name]
-          result && status_tokens.all? { |token| truthy_state?(result.state[STATUS_TOKEN_KEYS.fetch(token)]) }
+          Array(results_by_member[candidate.name]).any? do |result|
+            status_tokens.all? { |token| truthy_state?(result.state[STATUS_TOKEN_KEYS.fetch(token)]) }
+          end
         end
       end
 
+      # Branch-stack members report one result per branch, all sharing a member
+      # name, so results are grouped per member instead of collapsed to one.
       def release_state_results_by_member
         raise Error, "--only release-state tokens require release-state results" unless release_state_results
 
         release_state_results.each_with_object({}) do |result, memo|
-          memo[result.member_name] = result
+          (memo[result.member_name] ||= []) << result
         end
       end
 

data/lib/kettle/family/version.rb

@@ -5,7 +5,7 @@ module Kettle
     # Version namespace for this gem.
     module Version
       # Current gem version.
-      VERSION = "1.3.3"
+      VERSION = "1.3.5"
     end
     # Current gem version exposed at the traditional constant location.
     VERSION = Version::VERSION # Traditional Constant Location

data/lib/kettle/family/workflow.rb

@@ -574,7 +574,7 @@ module Kettle
 
         runner = CommandRunner.new(execute: execute, accept: accept)
         results = []
-        update_family_root_bundle(runner: runner, memo: results) if %w[bup bupb].include?(command)
+        update_family_root_bundle(runner: runner, memo: results) if %w[bup bupb update-bundler].include?(command)
         return results unless results.all?(&:ok?)
 
         if command == "gha-sha-pins" && execute
@@ -607,10 +607,10 @@ module Kettle
 
           normalize_lockfiles(member: member, runner: runner, memo: memo, phase: "normalize_lockfiles") if command == "template"
           commit_gha_sha_pins(member: member, runner: runner, memo: memo) if command == "gha-sha-pins"
-          if command == "bupb"
+          if %w[bupb update-bundler].include?(command)
             bupb_appraisal_results(member: member, runner: runner, memo: memo)
           end
-          if %w[bup bupb].include?(command) && memo.last&.ok? && validate_bundle_update_lockfile(member: member, memo: memo)
+          if %w[bup bupb update-bundler].include?(command) && memo.last&.ok? && validate_bundle_update_lockfile(member: member, memo: memo)
             commit_bundle_update(member: member, runner: runner, memo: memo)
           end
           commit_bex_changes(member: member, runner: runner, memo: memo) if command == "bex"
@@ -3978,28 +3978,38 @@ module Kettle
         @release_progress&.update(member, status: "ci bundle #{relative} #{attempt}/#{REGISTRY_WAIT_ATTEMPTS}", mark: ">")
       end
 
+      # A published version only means "already released" when nothing
+      # releasable landed after its tag. kettle-release commits checksums
+      # (and the family commits dependency-floor lockfiles) *after* tagging,
+      # so comparing HEAD to the tag directly never matches; compare the
+      # release-relevant paths instead.
       def already_released_result(member)
         tag = release_tag_name(member.version)
-        current_release_head = released_version_current_head?(member, tag)
-        if current_release_head
-          stdout = "#{member.name} #{member.version} is already published and current HEAD matches #{tag}; skipping release"
+        branch = current_member_branch(member)
+        scope = branch ? "#{member.name}@#{branch}" : member.name
+        if no_releasable_changes_since_tag?(member, tag)
+          stdout = "#{scope} #{member.version} is already published#{branch_suffix(branch)} and nothing releasable " \
+            "landed after #{tag}; skipping release"
           reason = "already released"
           skipped = true
-        elsif unreleased_changes_pending?(member)
-          stdout = "#{member.name} #{member.version} is already published, but release-state reports unreleased changes. " \
-            "Bump the version with `kettle-family bump patch --execute --only #{member.name}` before releasing."
+        elsif unreleased_changes_pending?(member, branch: branch)
+          stdout = "#{scope} #{member.version} is already published#{branch_suffix(branch)}, but release-state reports " \
+            "unreleased changes on this branch. Bump only this branch with " \
+            "`kettle-family bump patch --execute --only #{member.name}` before releasing."
           reason = "published version has unreleased changes"
           skipped = false
         else
-          stdout = "#{member.name} #{member.version} is already published, current HEAD is newer than #{tag}, " \
-            "and release-state reports no unreleased changes; skipping release"
+          stdout = "#{scope} #{member.version} is already published#{branch_suffix(branch)}, and release-state reports " \
+            "no unreleased changes on this branch; skipping release"
           reason = "already released; no unreleased changes"
           skipped = true
         end
 
         CommandResult.new(
           member_name: member.name,
-          phase: "release_skip",
+          # A blocked release is a distinct terminal phase from a skip: it is a
+          # hard failure and must never be reported as "skipped".
+          phase: skipped ? "release_skip" : "release_blocked",
           command: ["internal", "released-version-check", member.version],
           workdir: member.root,
           status: skipped ? 0 : 1,
@@ -4008,12 +4018,34 @@ module Kettle
           stderr: "",
           elapsed_seconds: 0.0,
           skipped: skipped,
-          reason: reason
+          reason: reason,
+          branch: branch
         )
       end
 
-      def unreleased_changes_pending?(member)
-        results = ReleaseStateCheck.new(members: [member], config: config).results
+      def branch_suffix(branch)
+        branch ? " on #{branch}" : ""
+      end
+
+      def current_member_branch(member)
+        return unless git_work_tree?(member.root)
+
+        stdout, _stderr, status = Open3.capture3("git", "branch", "--show-current", chdir: member.root)
+        return unless status.success?
+
+        branch = stdout.strip
+        branch.empty? ? nil : branch
+      end
+
+      # Scope the check to the branch being released. Consulting the whole
+      # branch stack here would report every already-published branch as
+      # having unreleased changes whenever any other branch in the stack does.
+      def unreleased_changes_pending?(member, branch: nil)
+        results = ReleaseStateCheck.new(
+          members: [member],
+          config: config,
+          branches: branch ? [branch] : nil
+        ).results
         return true unless results.all?(&:ok?)
 
         results.any? { |result| result.state.fetch("unreleased_entries", true) }
@@ -4023,12 +4055,42 @@ module Kettle
         "v#{version}"
       end
 
-      def released_version_current_head?(member, tag)
-        return true unless git_work_tree?(member.root)
+      # Post-release maintenance commits (checksums, lockfile reconciliation,
+      # docs) land after the tag by design, so "HEAD != tag" cannot mean
+      # "needs a release". Only a change to the gemspec, version file, or
+      # changelog between the tag and HEAD makes the published version stale.
+      def no_releasable_changes_since_tag?(member, tag)
+        return false unless git_work_tree?(member.root)
 
         tag_sha = git_rev_parse(member.root, "refs/tags/#{tag}^{}")
-        head_sha = git_rev_parse(member.root, "HEAD")
-        !tag_sha.to_s.empty? && tag_sha == head_sha
+        return false if tag_sha.to_s.empty?
+        return true if tag_sha == git_rev_parse(member.root, "HEAD")
+
+        releasable_changes_since_tag(member, tag).empty?
+      end
+
+      def releasable_changes_since_tag(member, tag)
+        paths = releasable_paths(member)
+        return [] if paths.empty?
+
+        stdout, _stderr, status = Open3.capture3(
+          "git", "diff", "--name-only", "#{tag}^{}", "HEAD", "--", *paths, chdir: member.root
+        )
+        # An unreadable diff is not evidence of "nothing to release".
+        return [tag] unless status.success?
+
+        stdout.lines.map(&:strip).reject(&:empty?)
+      end
+
+      def releasable_paths(member)
+        paths = [member.gemspec_path, member.version_file, config.changelog_full_path(member)]
+        paths.compact.filter_map do |path|
+          next unless File.file?(path)
+
+          Pathname.new(path).relative_path_from(Pathname.new(member.root)).to_s
+        rescue ArgumentError
+          path.to_s
+        end.uniq
       end
 
       def git_work_tree?(root)
@@ -4083,7 +4145,7 @@ module Kettle
           return gha_sha_pins_command(command_text: command_text)
         end
         return bup_command if command == "bup"
-        return bupb_command if command == "bupb"
+        return bupb_command if %w[bupb update-bundler].include?(command)
         return bex_command if command == "bex"
 
         command_for(command)
@@ -4108,11 +4170,11 @@ module Kettle
 
       def stable_bundler_version
         active_version = Gem.loaded_specs["bundler"]&.version
-        return active_version if active_version && !active_version.prerelease?
-
         Gem::Specification
           .find_all_by_name("bundler")
           .map(&:version)
+          .push(active_version)
+          .compact
           .reject(&:prerelease?)
           .max
       end
@@ -4358,7 +4420,7 @@ module Kettle
       end
 
       def command_env
-        return bundle_update_env if %w[bup bupb].include?(command)
+        return bundle_update_env if %w[bup bupb update-bundler].include?(command)
 
         workflow_env
       end
@@ -4634,7 +4696,9 @@ module Kettle
       def emit_release_progress_summary(results, progress:)
         return unless progress
 
-        release_results = results.select { |result| result.phase == release_phase || result.phase == "release_skip" }
+        release_results = results.select do |result|
+          result.phase == release_phase || result.phase == "release_skip" || result.phase == "release_blocked"
+        end
         progress.stop
         progress.summary("release summary: #{release_results.count(&:ok?)}/#{release_results.length} members ok")
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-family
 version: !ruby/object:Gem::Version
-  version: 1.3.3
+  version: 1.3.5
 platform: ruby
 authors:
 - Peter H. Boling
@@ -94,7 +94,7 @@ dependencies:
         version: '3.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.1.4
+        version: 3.1.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -104,7 +104,7 @@ dependencies:
         version: '3.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.1.4
+        version: 3.1.7
 - !ruby/object:Gem::Dependency
   name: kettle-gha-pins
   requirement: !ruby/object:Gem::Requirement
@@ -304,7 +304,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.4
+        version: 3.2.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -314,7 +314,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.4
+        version: 3.2.5
 - !ruby/object:Gem::Dependency
   name: turbo_tests2
   requirement: !ruby/object:Gem::Requirement
@@ -324,7 +324,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.11
+        version: 3.2.13
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -334,21 +334,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.11
-- !ruby/object:Gem::Dependency
-  name: webrick
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.9'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.9'
+        version: 3.2.13
 - !ruby/object:Gem::Dependency
   name: ruby-progressbar
   requirement: !ruby/object:Gem::Requirement
@@ -392,7 +378,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.13
+        version: 2.0.15
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -402,7 +388,21 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.13
+        version: 2.0.15
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
 description: "\U0001F469‍\U0001F469‍\U0001F467‍\U0001F467 Kettle::Family provides
   scripts and conventions for coordinating related Ruby gems as one family."
 email:
@@ -459,10 +459,10 @@ licenses:
 - AGPL-3.0-only
 metadata:
   homepage_uri: https://kettle-family.galtzo.com
-  source_code_uri: https://github.com/kettle-dev/kettle-family/tree/v1.3.3
-  changelog_uri: https://github.com/kettle-dev/kettle-family/blob/v1.3.3/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-dev/kettle-family/tree/v1.3.5
+  changelog_uri: https://github.com/kettle-dev/kettle-family/blob/v1.3.5/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-dev/kettle-family/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-family/1.3.3
+  documentation_uri: https://www.rubydoc.info/gems/kettle-family/1.3.5
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-dev/kettle-family/wiki
   news_uri: https://www.railsbling.com/tags/kettle-family