feat: add Git::Repository::Branching#current_branch_state facade

Define HeadState as Data.define(:state, :name) in Git::Repository::Branching
and add a #current_branch_state facade method that returns it. The three
possible HEAD states are:

- :active   -- branch ref with at least one commit
- :unborn   -- branch ref that exists but has no commits yet
- :detached -- HEAD points directly to a commit SHA

A private helper, Private.get_branch_state, mirrors the Git::Lib implementation
but takes execution_context as an explicit argument rather than relying on self.
Git::Base#current_branch_state delegates to the facade.

Also updates UPGRADING.md with a migration row and a callout about the return-
type change (mutable Struct to immutable Data object), and marks the row in
redesign/c1c2_audit.md §7.3 as promoted (§7.5 promote count decremented from
2 to 1).

Task commits included:
- feat(branching): add Git::Repository::Branching#current_branch_state facade
- docs: update UPGRADING.md and c1c2_audit.md for current_branch_state

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jcouball

UPGRADING.md

@@ -79,6 +79,15 @@ notes for the final migration target.
 | `g.lib.change_head_branch(name)` | `g.change_head_branch(name)` |
 | `g.lib.branch_current` | `g.current_branch` |
 | `g.lib.ls_remote(location, opts)` | `g.ls_remote(location, opts)` |
+| `g.lib.current_branch_state` | `g.current_branch_state` |
+
+> **Note — `current_branch_state` return type change:** `g.lib.current_branch_state`
+> returned a `Git::Lib::HeadState` (a mutable `Struct`). `g.current_branch_state`
+> returns a `Git::Repository::Branching::HeadState` (an immutable `Data` object).
+> Both expose `.state` (`:active`, `:unborn`, or `:detached`) and `.name`. If your
+> code relies on the struct being mutable or uses positional construction
+> (`Git::Lib::HeadState.new(:active, 'main')`), update to keyword construction:
+> `Git::Repository::Branching::HeadState.new(state: :active, name: 'main')`.
 
 #### Methods with no replacement
 

lib/git/base.rb

@@ -977,6 +977,17 @@ def current_branch
     end
     alias branch_current current_branch
 
+    # Returns the current HEAD state as a structured value object
+    #
+    # @return [Git::Repository::Branching::HeadState] the current HEAD state;
+    #   see {Git::Repository::Branching#current_branch_state} for details
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
+    def current_branch_state
+      facade_repository.current_branch_state
+    end
+
     # @return [Git::Branch] an object for branch_name
     def branch(branch_name = current_branch)
       facade_repository.branch(branch_name)

lib/git/repository/branching.rb

@@ -11,6 +11,7 @@
 require 'git/commands/checkout/branch'
 require 'git/commands/checkout/files'
 require 'git/commands/checkout_index'
+require 'git/commands/rev_parse'
 require 'git/commands/update_ref/update'
 require 'git/parsers/branch'
 require 'git/repository/shared_private'
@@ -25,6 +26,16 @@ class Repository
     # @api public
     #
     module Branching # rubocop:disable Metrics/ModuleLength
+      # Represents the state of HEAD in a repository
+      #
+      # @!attribute [r] state
+      #   @return [Symbol] one of `:active`, `:unborn`, or `:detached`
+      #
+      # @!attribute [r] name
+      #   @return [String] the branch name, or `'HEAD'` when detached
+      #
+      HeadState = Data.define(:state, :name)
+
       # Option keys accepted by {#checkout}
       #
       CHECKOUT_ALLOWED_OPTS = %i[force f new_branch b start_point].freeze
@@ -54,6 +65,39 @@ def current_branch
         name.empty? ? 'HEAD' : name
       end
 
+      # Returns the current HEAD state as a structured value object
+      #
+      # HEAD can be in one of three states:
+      #
+      # - **`:active`** — HEAD points to a branch ref that has at least one commit.
+      # - **`:unborn`** — HEAD points to a branch ref that has been created but has
+      #   no commits yet (e.g. immediately after `git init` before any commit).
+      # - **`:detached`** — HEAD points directly to a commit SHA rather than a branch.
+      #
+      # @example Active branch
+      #   repo.current_branch_state
+      #   # => #<data Git::Repository::Branching::HeadState state=:active, name="main">
+      #
+      # @example Unborn branch (no commits yet)
+      #   repo.current_branch_state
+      #   # => #<data Git::Repository::Branching::HeadState state=:unborn, name="main">
+      #
+      # @example Detached HEAD
+      #   repo.current_branch_state
+      #   # => #<data Git::Repository::Branching::HeadState state=:detached, name="HEAD">
+      #
+      # @return [Git::Repository::Branching::HeadState] the current HEAD state
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      def current_branch_state
+        branch_name = Git::Commands::Branch::ShowCurrent.new(@execution_context).call.stdout.strip
+        return HeadState.new(state: :detached, name: 'HEAD') if branch_name.empty?
+
+        state = Private.get_branch_state(@execution_context, branch_name)
+        HeadState.new(state: state, name: branch_name)
+      end
+
       # Restore working tree files from a tree-ish
       #
       # @example Restore README.md to its HEAD state
@@ -537,6 +581,34 @@ def branches
       module Private
         module_function
 
+        # Determines whether the given branch ref points to an existing commit
+        #
+        # Returns `:active` when the branch ref resolves successfully. Returns
+        # `:unborn` when the branch ref exists but has no commits yet (exit
+        # status 1 with empty stderr from `git rev-parse --verify --quiet`).
+        # Re-raises for any other failure.
+        #
+        # @param execution_context [Git::ExecutionContext::Repository] the
+        #   execution context for git commands
+        #
+        # @param branch_name [String] the branch name to verify
+        #
+        # @return [:active, :unborn] the branch ref state
+        #
+        # @raise [Git::FailedError] if git exits with a failure unrelated to an
+        #   unborn branch
+        #
+        # @api private
+        #
+        def get_branch_state(execution_context, branch_name)
+          Git::Commands::RevParse.new(execution_context).call(branch_name, verify: true, quiet: true)
+          :active
+        rescue Git::FailedError => e
+          raise unless e.result.status.exitstatus == 1 && e.result.stderr.empty?
+
+          :unborn
+        end
+
         # Translates legacy checkout options to the new command interface
         #
         # Legacy callers passed combinations like:

redesign/c1c2_audit.md

@@ -411,7 +411,7 @@ These require a new facade method before a base.rb delegator can be added.
 | `parse_config(file)` | Parses a config file from path. | 🔍 human decision — expose or fold into `config()` with `:file` option? |
 | `stash_list` | Returns a formatted string `"stash@{0}: ...\n..."` — distinct from `stashes_all` which returns structured data. | 🔍 human decision — promote for backward compat, or deprecate in favor of `stashes_all`? |
 | `unmerged` | Returns paths with unresolved merge conflicts. Already partially covered by `each_conflict` (yields paths to temporary files for staged content). Pure path list is useful. | 🔍 human decision — promote `unmerged` as a simpler alternative to `each_conflict`? |
-| `current_branch_state` | Returns a `HeadState` struct with `:state` (`:active`/`:unborn`/`:detached`) and `:name`. Richer than `current_branch`. | ⬜ promote — add to `Git::Repository::Branching`; trivial effort (command class already wired in lib.rb) |
+| `current_branch_state` | Returns a `HeadState` value object with `:state` (`:active`/`:unborn`/`:detached`) and `:name`. Richer than `current_branch`. Legacy `Git::Lib` implementation used a mutable `Struct`; promoted facade uses an immutable `Data` object. | ✅ promoted — `HeadState` Data object defined in `Git::Repository::Branching`; facade in `Git::Repository::Branching` + `Git::Base` delegator added (PR 5g) |
 
 ### 7.4 Internal Plumbing — Mark as ❌ Remove
 
@@ -439,7 +439,7 @@ upgrade notes as "unsupported; remove any `g.lib.X` calls."
 | Status | Count |
 |--------|-------|
 | ✅ promote (repo already had it, `Git::Base` delegator added — PR 2d; or alias added) | 24 |
-| ⬜ promote (new facade work required) | 2 |
+| ⬜ promote (new facade work required) | 1 |
 | ❌ remove (internal plumbing) | 12 |
 | 🔍 human decision | 16 |
 | **Total orphaned methods** | **56** |

spec/integration/git/repository/branching_spec.rb

@@ -452,4 +452,61 @@
       expect(result.full).to eq(described_instance.current_branch)
     end
   end
+
+  # ---------------------------------------------------------------------------
+  # #current_branch_state
+  # ---------------------------------------------------------------------------
+  #
+  # current_branch_state calls both ShowCurrent and RevParse, so integration
+  # tests confirm the multi-command orchestration produces the correct HeadState
+  # value across all three possible HEAD states.
+
+  describe '#current_branch_state' do
+    context 'when HEAD is on an active branch (has commits)' do
+      it 'returns HeadState with state :active' do
+        result = described_instance.current_branch_state
+        expect(result).to be_a(Git::Repository::Branching::HeadState)
+        expect(result.state).to eq(:active)
+      end
+
+      it 'returns the current branch name as the name attribute' do
+        result = described_instance.current_branch_state
+        expect(result.name).to eq(described_instance.current_branch)
+      end
+    end
+
+    context 'in detached HEAD state (checked out at a commit SHA directly)' do
+      before do
+        sha = repo.log(1).execute.first.sha
+        repo.lib.checkout(sha)
+      end
+
+      it 'returns HeadState with state :detached and name HEAD' do
+        result = described_instance.current_branch_state
+        expect(result.state).to eq(:detached)
+        expect(result.name).to eq('HEAD')
+      end
+    end
+
+    context 'on an unborn branch (repository initialized with no commits)' do
+      let(:unborn_repo_dir) { Dir.mktmpdir('unborn_repo') }
+      let(:unborn_repo) { Git.init(unborn_repo_dir) }
+      let(:unborn_execution_context) { Git::ExecutionContext::Repository.from_base(unborn_repo) }
+      let(:unborn_instance) { Git::Repository.new(execution_context: unborn_execution_context) }
+
+      after { FileUtils.rm_rf(unborn_repo_dir) }
+
+      it 'returns HeadState with state :unborn' do
+        result = unborn_instance.current_branch_state
+        expect(result.state).to eq(:unborn)
+      end
+
+      it 'returns the initial branch name (not HEAD)' do
+        result = unborn_instance.current_branch_state
+        expect(result.name).not_to eq('HEAD')
+        expect(result.name).to be_a(String)
+        expect(result.name).not_to be_empty
+      end
+    end
+  end
 end

spec/unit/git/base_spec.rb

@@ -205,6 +205,16 @@
     end
   end
 
+  describe '#current_branch_state' do
+    include_context 'with a stubbed facade_repository'
+
+    it 'delegates to facade_repository.current_branch_state' do
+      head_state = instance_double(Git::Repository::Branching::HeadState)
+      expect(facade_repository).to receive(:current_branch_state).and_return(head_state)
+      expect(described_instance.current_branch_state).to be(head_state)
+    end
+  end
+
   describe '#gblob' do
     include_context 'with a stubbed facade_repository'
 

spec/unit/git/repository/branching_spec.rb

@@ -13,6 +13,29 @@
   let(:execution_context) { instance_double(Git::ExecutionContext::Repository) }
   let(:described_instance) { Git::Repository.new(execution_context: execution_context) }
 
+  # ---------------------------------------------------------------------------
+  # HeadState
+  # ---------------------------------------------------------------------------
+
+  describe 'HeadState' do
+    subject(:head_state_class) { Git::Repository::Branching::HeadState }
+
+    it 'is a Data class' do
+      expect(head_state_class).to be < Data
+    end
+
+    it 'constructs with keyword arguments' do
+      instance = head_state_class.new(state: :active, name: 'main')
+      expect(instance.state).to eq(:active)
+      expect(instance.name).to eq('main')
+    end
+
+    it 'is immutable (does not respond to state=)' do
+      instance = head_state_class.new(state: :active, name: 'main')
+      expect(instance).not_to respond_to(:state=)
+    end
+  end
+
   # ---------------------------------------------------------------------------
   # #current_branch
   # ---------------------------------------------------------------------------
@@ -51,6 +74,88 @@
     end
   end
 
+  # ---------------------------------------------------------------------------
+  # #current_branch_state
+  # ---------------------------------------------------------------------------
+
+  describe '#current_branch_state' do
+    subject(:result) { described_instance.current_branch_state }
+
+    let(:show_current_command) { instance_double(Git::Commands::Branch::ShowCurrent) }
+    let(:rev_parse_command) { instance_double(Git::Commands::RevParse) }
+
+    before do
+      allow(Git::Commands::Branch::ShowCurrent)
+        .to receive(:new).with(execution_context).and_return(show_current_command)
+      allow(Git::Commands::RevParse)
+        .to receive(:new).with(execution_context).and_return(rev_parse_command)
+    end
+
+    context 'when on an active branch (RevParse succeeds)' do
+      before do
+        allow(show_current_command).to receive(:call).and_return(command_result("main\n"))
+        allow(rev_parse_command)
+          .to receive(:call).with('main', verify: true, quiet: true)
+          .and_return(command_result('abc123'))
+      end
+
+      it 'returns HeadState with state :active and the branch name' do
+        expect(result).to eq(
+          Git::Repository::Branching::HeadState.new(state: :active, name: 'main')
+        )
+      end
+    end
+
+    context 'when on an unborn branch (RevParse exits 1 with empty stderr)' do
+      let(:unborn_result) { command_result('', stderr: '', exitstatus: 1) }
+
+      before do
+        allow(show_current_command).to receive(:call).and_return(command_result("main\n"))
+        allow(rev_parse_command)
+          .to receive(:call).with('main', verify: true, quiet: true)
+          .and_raise(Git::FailedError.new(unborn_result))
+      end
+
+      it 'returns HeadState with state :unborn and the branch name' do
+        expect(result).to eq(
+          Git::Repository::Branching::HeadState.new(state: :unborn, name: 'main')
+        )
+      end
+    end
+
+    context 'in detached HEAD state (ShowCurrent returns empty stdout)' do
+      before do
+        allow(show_current_command).to receive(:call).and_return(command_result(''))
+      end
+
+      it 'returns HeadState with state :detached and name HEAD' do
+        expect(result).to eq(
+          Git::Repository::Branching::HeadState.new(state: :detached, name: 'HEAD')
+        )
+      end
+
+      it 'does not call RevParse' do
+        expect(rev_parse_command).not_to receive(:call)
+        result
+      end
+    end
+
+    context 'when RevParse exits 1 with non-empty stderr' do
+      let(:error_result) { command_result('', stderr: 'fatal: not a git repository', exitstatus: 1) }
+
+      before do
+        allow(show_current_command).to receive(:call).and_return(command_result("main\n"))
+        allow(rev_parse_command)
+          .to receive(:call).with('main', verify: true, quiet: true)
+          .and_raise(Git::FailedError.new(error_result))
+      end
+
+      it 're-raises the FailedError' do
+        expect { result }.to raise_error(Git::FailedError)
+      end
+    end
+  end
+
   # ---------------------------------------------------------------------------
   # #checkout_file
   # ---------------------------------------------------------------------------