ace-git 0.23.1 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4630b03ca193f78f73339cb3c2a9b8fbb07c7ca9545b1132cfd66f3e0dda160
-  data.tar.gz: 60096f6410637684ef3753300a2bf3195a07052170032774be9ea3e66e4c0d5d
+  metadata.gz: 746038569079877012656b703209b794e8a055718955f23f8d4b613ec8fb6628
+  data.tar.gz: 841b2ac7dc6eed9348e36a46f6abef8e18c8f726e9f26a705d96a3548209ee27
 SHA512:
-  metadata.gz: 285125f8923236d4ba4ae5186a20b354eaa978019c5c17eb37fbf6b9bd96057ad0901549f6ae94f690bbc67268dbd7aa692238a9f07a88c8d41fe58c3ad8765d
-  data.tar.gz: 4d8da76f2676ea2c09434b8a8afa2589a643bd00b5140614286c1be12a5f696adbbd7ce10c079eab35f8efdc24e42ad7fdb8e9e9d5a8bcb58763961c79e9086e
+  metadata.gz: b10072d2af5d314c0c00fefc7883ab6d33de5bad5388b549a50db5cc1134b92196d1462c4c598c9aeaa3a79114eb44be2d29693aa3a95db74646bd4786dd6131
+  data.tar.gz: 510071cb8c141cde868bcc0fb79d55e62edbf749c5b82dfbb987488cfa20fcd236fc7c2c5c963db3891655bcbef8bcf9223634298a5abeb0236c4518f9ecf6be

data/.ace-defaults/git/config.yml

@@ -10,7 +10,22 @@ git:
 
   # Timeout settings (in seconds)
   timeout: 30          # Local git operations (diff, status, log)
-  network_timeout: 60  # Network operations (gh CLI, remote operations)
+  network_timeout: 60  # Network operations (provider CLIs, remote operations)
+
+  # Forge server registry (provider-neutral)
+  # Configure each forge server once with a unique name; mark at most one as
+  # default. Resolve by explicit name, by default, or by matching a git remote
+  # URL. The `provider` value selects the registered provider package that owns
+  # that server's behavior.
+  servers: []
+  # servers:
+  #   - name: forgejo-lab
+  #     provider: forgejo
+  #     url: https://forgejo.example.com/owner/repo
+  #     default: true
+  #   - name: github-public
+  #     provider: github
+  #     url: https://github.example.com/owner/repo
 
   # Status command settings
   status:

data/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.24.0] - 2026-09-21
+
+### Added
+
+- Forge-neutral provider foundation: `Ace::Git::ServerRegistry` (explicit named servers, exactly-one-default resolution, deterministic remote-URL matching with no hostname assumptions), `Ace::Git::ResolvedServer`, the `Ace::Git::Providers` registry with the `Providers::Base` contract, normalized evidence types (`ProviderPullRequest`, `ProviderIssue`, `ProviderCheck`, `ProviderRepository`), and the neutral `Atoms::PrIdentifier` / `Atoms::ServerUrl` atoms.
+- Classified failure taxonomy in `git/errors.rb`: `NoDefaultServerConfiguredError`, `MultipleDefaultServersError`, `DuplicateServerNameError`, `UnknownProviderError`, `UnknownServerNameError`, `AmbiguousRemoteError`, `ProviderCliMissingError`, `ProviderAuthenticationError`, `ProviderUnreachableError`, `ProviderMalformedOutputError`, `ProviderObjectNotFoundError`.
+- `git.servers` configuration section supporting multiple uniquely named servers with at most one explicit default.
+- Boundary proof: local Git operations succeed with provider CLIs scrubbed from PATH, and a test pins the core lib to zero forge CLI references.
+
+### Changed
+
+- Status PR enrichment routes through the provider contract (default server + registered provider); with no server or provider configured, status stays purely local and PR sections are skipped.
+- Forge server URLs in gemspec metadata point at the canonical delivery forge instead of hardcoded GitHub URLs.
+
+### Removed
+
+- All forge behavior from the core (pre-1.0 replacement, no shims or aliases): `GhCliExecutor`, `PrMetadataFetcher`, `GithubIssueSync`, the `ace-git pr` CLI command, the GitHub-specific `PrIdentifierParser`, and the `GhNotInstalledError` / `GhAuthenticationError` / `PrNotFoundError` error classes. GitHub behavior moved to the new `ace-git-github` gem; Forgejo behavior is provided by the new `ace-git-forgejo` gem.
 
 ## [0.23.1] - 2026-09-02
 

data/docs/getting-started.md

@@ -17,7 +17,8 @@ guided workflow.
 - Ruby 3.2+
 - Git 2.23+
 - `ace-git` installed
-- Optional: GitHub CLI (`gh`) for PR-aware commands and workflows
+- Optional: a provider package (`ace-git-github` or `ace-git-forgejo`) plus a configured
+  default forge server for PR-aware status enrichment
 
 ## Installation
 
@@ -76,7 +77,6 @@ Use this for preferences, not for redefining the workflow logic.
 | Show repo context | `ace-git status` |
 | Show a quick diff summary | `ace-git diff --format summary` |
 | Show branch tracking info | `ace-git branch` |
-| Show PR metadata | `ace-git pr` |
 | Show package version | `ace-git version` |
 
 ## Run Package Tests
@@ -90,7 +90,7 @@ Use the restarted package test model:
 
 ## Next Steps
 
-- Load `wfi://github/pr/create` to open a structured PR workflow
-- Load `wfi://github/pr/update` to refresh an existing PR description
 - Load `wfi://git/reorganize-commits` to clean up branch history before review
+- Install a provider package (`ace-git-github` / `ace-git-forgejo`) and configure
+  `git.servers` for PR-aware status enrichment
 - Run `ace-git --help` to browse command-level examples

data/docs/usage.md

@@ -23,12 +23,11 @@ gem install ace-git
 
 ## Command Overview
 
-`ace-git` ships five commands:
+`ace-git` ships four commands:
 
 - `diff` for filtered or formatted git diffs
 - `status` for repository context and PR activity
 - `branch` for current branch and tracking state
-- `pr` for PR metadata lookup
 - `version` for the installed package version
 
 `ace-git` with no arguments shows help. Git range shorthand such as `HEAD~5..HEAD` routes to `diff`.
@@ -155,43 +154,6 @@ ace-git branch --format json
 **Options:**
 - `--format, -f` - Output format: `text` (default), `json`
 
-### `ace-git pr [NUMBER]`
-
-Fetch and display PR metadata using GitHub CLI.
-
-```bash
-# Auto-detect PR from current branch
-ace-git pr
-
-# Specific PR number
-ace-git pr 123
-
-# Cross-repository PR
-ace-git pr owner/repo#456
-
-# JSON output
-ace-git pr --format json
-```
-
-**Options:**
-- `--format, -f` - Output format: `markdown` (default), `json`
-- `--with-diff` - Include PR diff in output
-
-**PR Number Formats:**
-- Simple number: `123`
-- Qualified: `owner/repo#456`
-- GitHub URL: `https://github.com/owner/repo/pull/789`
-
-**Requirements:** GitHub CLI (`gh`) must be installed and authenticated.
-
-```bash
-# Install gh
-brew install gh
-
-# Authenticate
-gh auth login
-```
-
 ### `ace-git version`
 
 Print the installed `ace-git` version.
@@ -267,11 +229,18 @@ Note: `test/**/*` and `spec/**/*` are NOT excluded by default - test changes are
 - **ace-bundle** - Load ACE workflow instructions directly
 - **ace-nav** - Discover workflow and template protocol paths
 
-## Reusable GitHub Issue Primitives
+## Provider Packages
 
-`ace-git` also exposes reusable library primitives for issue synchronization flows used by other ACE packages:
+`ace-git` is forge-neutral. It defines the server registry (`Ace::Git::ServerRegistry`),
+the provider contract (`Ace::Git::Providers::Base`), and normalized evidence types;
+provider packages own all forge CLI behavior:
 
-- `Ace::Git::Molecules::GhCliExecutor` - shared `gh` command execution with timeout and auth/install error handling
-- `Ace::Git::Molecules::GithubIssueSync.sync_task(...)` - sticky comment upsert, `ace:tracked` label management, and close/reopen lifecycle actions
+- **ace-git-github** - GitHub behavior via the `gh` CLI (PR lookups, diffs, issue
+  synchronization). Registers under the `github` provider type.
+- **ace-git-forgejo** - Forgejo behavior via the `fj` CLI. Registers under the
+  `forgejo` provider type.
 
-These are intended for package integrations such as `ace-task` and are not invoked directly through `ace-git` CLI commands.
+Configure servers in `.ace/git.yml` (or project config) under `git.servers`, then
+resolve them by name, by default, or from a git remote URL. Every failure path is
+classified (missing CLI, unauthenticated, unreachable, malformed output, object
+not found) with no silent fallbacks.

data/lib/ace/git/atoms/command_executor.rb

@@ -106,7 +106,7 @@ module Ace
             # Using Timeout to prevent hanging on network issues or stuck git operations
             Timeout.timeout(timeout) do
               # Using Open3.capture3 to avoid shell injection
-              # Arguments are passed directly as array elements, not through shell
+              # Arguments are passed directly as array elements, never via a shell
               # If env is provided, prepend it to the command (Open3 convention)
               args = env ? [env, *command_parts] : command_parts
               stdout, stderr, status = Open3.capture3(*args)

data/lib/ace/git/atoms/pr_identifier.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Ace
+  module Git
+    module Atoms
+      # Parse provider-neutral pull request identifiers into structured form.
+      #
+      # Supports the forge-neutral forms:
+      # - Simple number: "123"
+      # - Qualified reference: "owner/repo#456"
+      #
+      # Provider-specific identifier formats (for example full web URLs) belong
+      # to the provider packages, not to the core.
+      module PrIdentifier
+        # Parsed identifier result
+        ParseResult = Data.define(:number, :repo)
+
+        # Maximum identifier length to bound regex work
+        MAX_IDENTIFIER_LENGTH = 256
+
+        # Parse a pull request identifier string.
+        #
+        # Returns nil for nil/empty input (no PR specified), raises ArgumentError
+        # for invalid formats. This lets callers distinguish "no PR" (nil input)
+        # from "invalid PR" (bad format).
+        #
+        # @param input [String, Integer] pull request identifier
+        # @return [ParseResult, nil] parsed identifier, or nil for nil/empty input
+        # @raise [ArgumentError] if identifier format is invalid
+        #
+        # @example Simple number
+        #   parse(123) # => ParseResult(number: "123", repo: nil)
+        #
+        # @example Qualified reference
+        #   parse("owner/repo#456") # => ParseResult(number: "456", repo: "owner/repo")
+        #
+        # @example Nil/empty input
+        #   parse(nil) # => nil
+        def self.parse(input)
+          return nil if input.nil?
+
+          input_str = input.to_s.strip
+          return nil if input_str.empty?
+
+          if input_str.length > MAX_IDENTIFIER_LENGTH
+            raise ArgumentError, "PR identifier too long (max #{MAX_IDENTIFIER_LENGTH} characters)"
+          end
+
+          case input_str
+          when /\A(\d+)\z/
+            number = ::Regexp.last_match(1)
+            raise ArgumentError, "Invalid PR identifier format: #{input_str}" if number.to_i.zero?
+
+            # Canonical form (no leading zeros) for consistent downstream use
+            ParseResult.new(number: number.to_i.to_s, repo: nil)
+          when /\A(?<repo>[a-zA-Z0-9_\-.]+\/[a-zA-Z0-9_\-.]+)#(?<number>\d+)\z/
+            match = ::Regexp.last_match
+            ParseResult.new(number: match[:number], repo: match[:repo])
+          else
+            raise ArgumentError, "Invalid PR identifier format: #{input_str}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/atoms/server_url.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Ace
+  module Git
+    module Atoms
+      # Normalize forge server URLs and remote URLs to a canonical comparable
+      # form. Purely textual: no network access, no hostname allow-lists, and
+      # no assumptions about any particular forge host.
+      #
+      # Supported input shapes:
+      # - "https://forge.example.com/owner/repo.git"
+      # - "http://forge.internal:3000/owner/repo"
+      # - "git@forge.example.com:owner/repo.git" (scp-style)
+      # - "ssh://git@forge.example.com:2222/owner/repo.git"
+      # - "forge.example.com/owner/repo"
+      #
+      # Canonical form: lowercase "host[:port]/path" with any credentials,
+      # scheme, trailing slash, and ".git" suffix removed. A colon segment is
+      # treated as a port (not an scp separator) only when it is all digits and
+      # followed by a slash; everything else is scp-style "host:path".
+      module ServerUrl
+        # Normalize a server or remote URL to the canonical comparable form.
+        #
+        # @param url [String] server or remote URL
+        # @return [String] canonical "host[:port]/path" form
+        def self.normalize(url)
+          text = url.to_s.strip
+          text = text.sub(%r{\A[a-z][a-z0-9+.\-]*://}i, "")
+          text = text.sub(%r{\A[^/@]+@}, "")
+
+          if (port_match = text.match(%r{\A([^/:]+):(\d+)(/.+)\z}))
+            text = "#{port_match[1]}:#{port_match[2]}#{port_match[3]}"
+          elsif (scp_match = text.match(%r{\A([^/:]+):(.+)\z}))
+            text = "#{scp_match[1]}/#{scp_match[2]}"
+          end
+
+          text = text.sub(%r{/?\.git/?\z}i, "")
+          text.chomp("/").downcase
+        end
+
+        # Compare a configured server URL against a remote URL for identity.
+        #
+        # @param server_url [String] configured server base URL
+        # @param remote_url [String] git remote URL
+        # @return [Boolean] true when both normalize to the same form
+        def self.match?(server_url, remote_url)
+          normalized_server = normalize(server_url)
+          normalized_remote = normalize(remote_url)
+          return false if normalized_server.empty? || normalized_remote.empty?
+
+          normalized_server == normalized_remote
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/atoms/status_formatter.rb

@@ -75,40 +75,37 @@ module Ace
             lines
           end
 
-          # Format current PR section (highlighted for current branch)
-          # @param pr_metadata [Hash] PR metadata
+          # Format current PR section (spotlit for current branch)
+          # @param pr [ProviderPullRequest, nil] normalized pull request evidence
           # @return [Array<String>] Lines of markdown
-          def format_current_pr_section(pr_metadata)
+          def format_current_pr_section(pr)
             lines = []
             lines << ""
             lines << "## Current PR"
             lines << ""
 
-            # Main line: #85 [OPEN] Title
-            main_line = "##{pr_metadata["number"]}"
-            main_line += " [#{pr_metadata["state"]}]" if pr_metadata["state"]
-            main_line += " #{pr_metadata["title"]}" if pr_metadata["title"]
+            # Main line: #85 [open] Title
+            main_line = "##{pr.number}"
+            main_line += " [#{pr.state}]" if pr.state
+            main_line += " #{pr.title}" if pr.title
             lines << main_line
 
             # Details line: Target: main | Author: @username | Draft/Not draft
             details = []
-            details << "Target: #{pr_metadata["baseRefName"]}" if pr_metadata["baseRefName"]
-            if pr_metadata["author"]
-              author = pr_metadata.dig("author", "login") || pr_metadata["author"]
-              details << "Author: @#{author}"
-            end
-            details << (pr_metadata["isDraft"] ? "Draft" : "Not draft") if pr_metadata.key?("isDraft")
+            details << "Target: #{pr.base_ref}" if pr.base_ref
+            details << "Author: @#{pr.author}" if pr.author
+            details << (pr.draft ? "Draft" : "Not draft") unless pr.draft.nil?
             lines << "  #{details.join(" | ")}" unless details.empty?
 
             # URL line
-            lines << "  #{pr_metadata["url"]}" if pr_metadata["url"]
+            lines << "  #{pr.url}" if pr.url
 
             lines
           end
 
           # Format PR activity section
-          # @param pr_activity [Hash, nil] PR activity with :merged and :open arrays
-          #   Each PR in the arrays has string keys from JSON parsing: "number", "title", etc.
+          # @param pr_activity [Hash, nil] Activity with :merged and :open arrays of
+          #   normalized ProviderPullRequest evidence
           # @return [Array<String>] Lines of markdown
           def format_pr_activity_section(pr_activity)
             lines = []
@@ -119,17 +116,15 @@ module Ace
             # Handle nil pr_activity for defensive programming
             return lines << "No recent PR activity" if pr_activity.nil?
 
-            # pr_activity uses symbol keys (from RepoStatusLoader)
-            # PR data within uses string keys (from JSON parsing)
             merged = pr_activity[:merged] || []
             open_prs = pr_activity[:open] || []
 
             unless merged.empty?
               lines << "Merged:"
               merged.each do |pr|
-                title = pr["title"] || "(no title)"
-                merged_ago = format_merged_time_compact(pr["mergedAt"])
-                lines << "  ##{pr["number"]} #{title}#{merged_ago}"
+                title = pr.title || "(no title)"
+                merged_ago = format_merged_time_compact(pr.merged_at)
+                lines << "  ##{pr.number} #{title}#{merged_ago}"
               end
             end
 
@@ -137,9 +132,9 @@ module Ace
               lines << "" unless merged.empty? # Add spacing between Merged and Open
               lines << "Open:"
               open_prs.each do |pr|
-                title = pr["title"] || "(no title)"
-                author = format_author(pr["author"])
-                lines << "  ##{pr["number"]} #{title}#{author}"
+                title = pr.title || "(no title)"
+                author = format_author(pr.author)
+                lines << "  ##{pr.number} #{title}#{author}"
               end
             end
 
@@ -163,13 +158,13 @@ module Ace
           end
 
           # Format author info
-          # @param author [Hash, String, nil] Author data
+          # @param author [String, nil] Author identifier
           # @return [String] Formatted string like " (@username)"
           def format_author(author)
             return "" if author.nil?
 
-            login = author.is_a?(Hash) ? author["login"] : author.to_s
-            return "" if login.nil? || login.empty?
+            login = author.to_s
+            return "" if login.empty?
 
             " (@#{login})"
           end

data/lib/ace/git/cli/commands/status.rb

@@ -59,24 +59,34 @@ module Ace
             # Include diff if requested
             if options[:with_diff] && status.has_pr?
               begin
-                diff_result = Molecules::PrMetadataFetcher.fetch_diff(
-                  status.pr_metadata["number"].to_s
-                )
-                if diff_result[:success]
+                provider = active_provider
+                diff = provider&.pull_request_diff(number: status.pr_metadata.number.to_s)
+                if diff
                   puts ""
                   puts "## PR Diff"
                   puts ""
                   puts "```diff"
-                  puts diff_result[:diff]
+                  puts diff
                   puts "```"
                 end
               rescue Ace::Git::Error
-                # Silently skip diff if it fails
+                # Classified provider failure: skip the diff section
               end
             end
           rescue Ace::Git::Error => e
             raise Ace::Support::Cli::Error.new(e.message)
           end
+
+          private
+
+          # Resolve the default server's registered provider for optional
+          # enrichment; nil when no server or provider is configured.
+          def active_provider
+            server = Ace::Git::ServerRegistry.resolve_default
+            Ace::Git::Providers.for(server)
+          rescue Ace::Git::Error
+            nil
+          end
         end
       end
     end

data/lib/ace/git/cli.rb

@@ -6,7 +6,6 @@ require_relative "../git"
 require_relative "cli/commands/diff"
 require_relative "cli/commands/status"
 require_relative "cli/commands/branch"
-require_relative "cli/commands/pr"
 
 module Ace
   module Git
@@ -51,8 +50,7 @@ module Ace
       REGISTERED_COMMANDS = [
         ["diff", "Show filtered git diff output"],
         ["status", "Show repository status and PR context"],
-        ["branch", "Show current branch information"],
-        ["pr", "Show pull request information"]
+        ["branch", "Show current branch information"]
       ].freeze
 
       HELP_EXAMPLES = [
@@ -64,7 +62,6 @@ module Ace
       register "diff", Commands::Diff.new
       register "status", Commands::Status.new
       register "branch", Commands::Branch.new
-      register "pr", Commands::Pr.new
 
       version_cmd = Ace::Support::Cli::VersionCommand.build(
         gem_name: "ace-git",

data/lib/ace/git/errors.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Ace
+  module Git
+    # Error handling pattern:
+    # - Atoms: Pure functions, raise exceptions for invalid inputs
+    # - Molecules: May return error hashes for "expected" errors (e.g., not in git repo)
+    #   or raise exceptions for unexpected failures
+    # - Organisms: Orchestrate molecules, propagate or wrap exceptions
+    # - Commands: Catch exceptions and return exit codes (0=success, 1=error)
+    #
+    # All custom exceptions inherit from Ace::Git::Error for consistent catching.
+    class Error < StandardError; end
+    class GitError < Error; end
+    class ConfigError < Error; end
+    class TimeoutError < Error; end
+
+    # ---- Forge server resolution failures ----
+
+    # Default requested but no default server is configured.
+    class NoDefaultServerConfiguredError < Error; end
+
+    # More than one server is marked as default in configuration.
+    class MultipleDefaultServersError < Error; end
+
+    # Multiple servers are configured with the same identifier.
+    class DuplicateServerNameError < Error; end
+
+    # A server references a provider type that no provider package registered.
+    class UnknownProviderError < Error; end
+
+    # The requested server name is not present in configuration.
+    class UnknownServerNameError < Error; end
+
+    # A remote URL matches multiple configured servers, or none, so the server
+    # identity cannot be determined without caller input.
+    class AmbiguousRemoteError < Error; end
+
+    # ---- Provider interaction failures ----
+
+    # The provider CLI binary is not installed in PATH.
+    class ProviderCliMissingError < Error; end
+
+    # The provider CLI is unauthenticated or its credential lease expired.
+    class ProviderAuthenticationError < Error; end
+
+    # The remote forge endpoint is offline or unreachable.
+    class ProviderUnreachableError < Error; end
+
+    # The provider CLI returned invalid JSON or an unexpected schema.
+    class ProviderMalformedOutputError < Error; end
+
+    # The requested pull request, issue, branch, or commit does not exist.
+    class ProviderObjectNotFoundError < Error; end
+  end
+end

data/lib/ace/git/models/diff_config.rb

@@ -91,7 +91,7 @@ module Ace
           elsif exclude_renames?
             flags << "--diff-filter=ACDMTUXB"
           elsif exclude_moves?
-            # Moves appear as rename with 100% similarity, disable high-similarity renames
+            # Moves appear as renames with total similarity; disable such exact renames
             flags << "-M0" # Disable rename detection (moves are renames at 100% similarity)
           end
           flags
@@ -164,7 +164,7 @@ module Ace
           hash.each_key do |key|
             key_str = key.to_s
             next if KNOWN_KEYS.include?(key_str)
-            # Skip nested sections that may be passed through
+            # Skip nested sections that may be propagated
             next if %w[diff rebase pr squash default_branch remote verbose].include?(key_str)
 
             warn "[ace-git] Unknown config key '#{key_str}' in DiffConfig - did you mean one of: #{KNOWN_KEYS.join(", ")}?"

data/lib/ace/git/models/repo_status.rb

@@ -68,7 +68,7 @@ module Ace
         # Check if has associated PR
         # @return [Boolean] True if PR metadata present
         def has_pr?
-          !pr_metadata.nil? && !pr_metadata.empty?
+          !pr_metadata.nil?
         end
 
         # Check if has detected task pattern

data/lib/ace/git/molecules/branch_reader.rb

@@ -35,17 +35,14 @@ module Ace
           # @param executor [Module] Command executor
           # @return [Hash] { ahead: Integer, behind: Integer }
           def tracking_status(executor: Atoms::CommandExecutor)
-            result = executor.execute("git", "rev-list", "--left-right", "--count", "@{upstream}...HEAD")
+            ahead = count_commits("@{upstream}..HEAD", executor: executor)
+            behind = count_commits("HEAD..@{upstream}", executor: executor)
 
-            unless result[:success]
+            if ahead.nil? || behind.nil?
               return {ahead: 0, behind: 0, error: "No tracking branch or not in git repo"}
             end
 
-            parts = result[:output].strip.split(/\s+/)
-            {
-              ahead: parts[1].to_i,
-              behind: parts[0].to_i
-            }
+            {ahead: ahead, behind: behind}
           end
 
           # Get full branch information
@@ -85,6 +82,15 @@ module Ace
               "#{behind} behind"
             end
           end
+
+          # Count commits in a rev-list range; nil when the range is invalid
+          # (e.g. no upstream configured)
+          def count_commits(range, executor: Atoms::CommandExecutor)
+            result = executor.execute("git", "rev-list", "--count", range)
+            return nil unless result[:success]
+
+            result[:output].strip.to_i
+          end
         end
       end
     end

data/lib/ace/git/molecules/config_loader.rb

@@ -13,7 +13,7 @@ module Ace
         class << self
           # Load configuration using ace-config cascade with deep merge
           # Priority: instance_config merged over global config (which is already defaults + user)
-          # @param instance_config [Hash] Instance-level configuration (highest priority)
+          # @param instance_config [Hash] Instance-level configuration (top priority)
           # @return [Models::DiffConfig] Merged configuration
           def load(instance_config = {})
             # Get global config from ace-git (already merged defaults + user per ADR-022)