ace-git 0.23.1 → 0.25.0

data/lib/ace/git/organisms/pull_request_lifecycle.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require_relative "../atoms/pr_reference"
+
+module Ace
+  module Git
+    module Organisms
+      # Forge-neutral pull request lifecycle orchestration.
+      #
+      # Owns the shared policy for every `ace-git pr` operation: server
+      # selection (exactly once per operation), identifier-to-server identity
+      # validation, body-file loading, and normalized provider invocation.
+      # Provider-specific command construction and parsing stay in the
+      # provider packages; this class only sees normalized evidence.
+      #
+      # Selection rules (see the qk1 parent contract):
+      # - `--server NAME` and `--default-server` are mutually exclusive.
+      # - With neither, the configured repository remote is resolved through
+      #   ServerRegistry; a failed remote resolution never falls back to a
+      #   default.
+      # - A PR URL or `owner/repo#number` is accepted only when it matches a
+      #   configured server exactly; an explicit selection that contradicts
+      #   the identifier fails before any mutation.
+      class PullRequestLifecycle
+        MERGE_METHODS = %i[squash merge rebase].freeze
+
+        # @param server_name [String, Symbol, nil] explicit server selection
+        # @param use_default [Boolean] resolve the configured default server
+        # @param remote_name [String, nil] git remote used when nothing selected
+        # @param timeout [Integer, nil] provider operation timeout
+        # @param runner [Proc, nil] injectable provider command runner (tests)
+        def initialize(server_name: nil, use_default: false, remote_name: nil, timeout: nil, runner: nil)
+          @selection = {server_name: server_name, use_default: use_default, remote_name: remote_name}
+          @timeout = timeout
+          @runner = runner
+        end
+
+        # Fetch normalized evidence for one pull request.
+        #
+        # @param identifier [String, Integer] number, `owner/repo#n`, or URL
+        # @return [ProviderPullRequest]
+        def show(identifier)
+          reference = parse_identifier(identifier)
+          server = resolve_server_for(reference)
+          provider_for(server).pull_request(number: reference.number)
+        end
+
+        # Create (or reconcile to) a pull request for an exact base/head
+        # identity. There is no identifier: the selected server's repository
+        # is the base, `head_repository_url` names the source (defaults to
+        # the base repository; no fork inference).
+        #
+        # @return [ProviderMutationReceipt] idempotency :created/:existing
+        def create(head_ref:, base_ref:, expected_head:, title:, head_repository_url: nil,
+          body: nil, body_file: nil, draft: true)
+          body_text = body_file ? load_body(body_file) : body
+          server = resolve_selected_server
+          provider_for(server).create_pull_request(
+            head_ref: head_ref,
+            head_repository_url: head_repository_url || server.url,
+            base_ref: base_ref,
+            expected_head: expected_head,
+            title: title,
+            body: body_text,
+            draft: draft
+          )
+        end
+
+        # Update title/body after exact-head verification.
+        #
+        # @return [ProviderMutationReceipt]
+        def update(identifier, expected_head:, title: nil, body: nil, body_file: nil)
+          body_text = body_file ? load_body(body_file) : body
+          reference = parse_identifier(identifier)
+          server = resolve_server_for(reference)
+          provider_for(server).update_pull_request(
+            number: reference.number, expected_head: expected_head,
+            title: title, body: body_text
+          )
+        end
+
+        # Mark a draft pull request ready after exact-head verification.
+        #
+        # @return [ProviderMutationReceipt]
+        def ready(identifier, expected_head:)
+          reference = parse_identifier(identifier)
+          server = resolve_server_for(reference)
+          provider_for(server).ready_pull_request(number: reference.number, expected_head: expected_head)
+        end
+
+        # Merge with provider-side expected-head enforcement; no implicit
+        # merge method exists.
+        #
+        # @param method [Symbol, String] :squash, :merge, or :rebase
+        # @return [ProviderMutationReceipt]
+        def merge(identifier, expected_head:, method:)
+          normalized = method.to_s.strip.downcase.to_sym
+          unless MERGE_METHODS.include?(normalized)
+            raise ArgumentError, "Invalid merge method '#{method}'; use one of: #{MERGE_METHODS.join(", ")}"
+          end
+
+          reference = parse_identifier(identifier)
+          server = resolve_server_for(reference)
+          provider_for(server).merge_pull_request(
+            number: reference.number, expected_head: expected_head, method: normalized
+          )
+        end
+
+        private
+
+        def parse_identifier(identifier)
+          reference = Atoms::PrReference.parse(identifier)
+          raise ArgumentError, "Invalid PR identifier: #{identifier}" unless reference
+
+          reference
+        end
+
+        def resolve_selected_server
+          ServerRegistry.resolve_for(**@selection)
+        end
+
+        # Resolve exactly one server for a parsed reference, validating any
+        # explicit selection against the identifier's repository identity.
+        def resolve_server_for(reference)
+          return resolve_selected_server unless reference.repository_explicit?
+
+          candidates = if reference.repository_url
+            ServerRegistry.matching_servers(reference.repository_url)
+          else
+            ServerRegistry.servers_for_owner_repo(reference.owner_repo)
+          end
+
+          if @selection[:server_name] || @selection[:use_default]
+            selected = ServerRegistry.resolve_for(**@selection)
+            unless candidates.any? { |candidate| candidate.name == selected.name }
+              identity = reference.repository_url || reference.owner_repo
+              raise ProviderIdentityMismatchError,
+                "PR identifier (#{identity}) does not match the selected server '#{selected.name}'"
+            end
+
+            selected
+          elsif candidates.size == 1
+            candidates.first
+          elsif candidates.empty?
+            identity = reference.repository_url || reference.owner_repo
+            raise AmbiguousRemoteError,
+              "PR repository '#{identity}' matches no configured server (configured: " \
+              "#{ServerRegistry.servers.map(&:name).join(", ")})"
+          else
+            identity = reference.repository_url || reference.owner_repo
+            raise AmbiguousRemoteError,
+              "PR repository '#{identity}' matches multiple configured servers " \
+              "(#{candidates.map(&:name).join(", ")}); select one explicitly"
+          end
+        end
+
+        def provider_for(server)
+          Ace::Git::Providers.for(server, timeout: @timeout, runner: @runner)
+        end
+
+        def load_body(path)
+          raise ArgumentError, "--body-file is required" unless path
+          raise ArgumentError, "Body file not found: #{path}" unless File.file?(path)
+
+          File.read(path)
+        rescue SystemCallError => e
+          raise ArgumentError, "Cannot read body file #{path}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/organisms/repo_status_loader.rb

@@ -4,12 +4,17 @@ module Ace
   module Git
     module Organisms
       # Orchestrates loading complete repository status
-      # Combines branch info, task pattern detection, and PR metadata
+      # Combines branch info, task pattern detection, and PR evidence
+      #
+      # PR enrichment is provider-optional: it resolves the default forge
+      # server and its registered provider via the core contract. With no
+      # server configured, no provider registered, or a classified provider
+      # failure, status stays purely local and the PR sections are skipped.
       class RepoStatusLoader
         class << self
           # Load complete repository status
           # @param options [Hash] Options for status loading
-          # @option options [Boolean] :include_pr Whether to fetch PR metadata (default: true)
+          # @option options [Boolean] :include_pr Whether to fetch PR evidence (default: true)
           # @option options [Boolean] :include_pr_activity Whether to fetch PR activity (default: true)
           # @option options [Boolean] :include_commits Whether to fetch recent commits (default: true)
           # @option options [Integer] :commits_limit Number of recent commits to fetch (default: 3)
@@ -53,28 +58,18 @@ module Ace
               recent_commits = fetch_recent_commits(limit: commits_limit)
             end
 
-            # Fetch PR data (metadata and activity) - parallelized for performance
+            # Fetch PR evidence (metadata and activity) via the provider contract
             pr_metadata = nil
             pr_activity = nil
             if !branch_info[:detached]
-              if include_pr && include_pr_activity
-                # Both requested: use parallel fetch for ~50% speedup
-                pr_data = fetch_pr_data_parallel(
-                  current_branch: branch_info[:name],
-                  timeout: timeout
-                )
-                pr_metadata = pr_data[:pr_metadata]
-                pr_activity = pr_data[:pr_activity]
-              elsif include_pr
-                # Only PR metadata requested
-                pr_metadata = fetch_pr_metadata(timeout: timeout)
-              elsif include_pr_activity
-                # Only activity requested
-                pr_activity = fetch_pr_activity(
-                  current_branch: branch_info[:name],
-                  timeout: timeout
-                )
-              end
+              pr_sections = fetch_pr_sections(
+                current_branch: branch_info[:name],
+                include_metadata: include_pr,
+                include_activity: include_pr_activity,
+                timeout: timeout
+              )
+              pr_metadata = pr_sections[:pr_metadata]
+              pr_activity = pr_sections[:pr_activity]
             end
 
             # Build and return status
@@ -100,13 +95,8 @@ module Ace
             # Get basic status (skip PR activity since we're fetching a specific PR)
             status = load(include_pr: false, include_pr_activity: false)
 
-            # Fetch specific PR metadata
-            begin
-              result = Molecules::PrMetadataFetcher.fetch_metadata(pr_identifier, timeout: timeout)
-              pr_metadata = result[:success] ? result[:metadata] : nil
-            rescue Ace::Git::Error
-              pr_metadata = nil
-            end
+            # Fetch specific PR evidence
+            pr_metadata = resolve_pr_metadata(pr_identifier, timeout: timeout)
 
             # Return status with PR data
             Models::RepoStatus.from_data(
@@ -131,6 +121,60 @@ module Ace
 
           private
 
+          # Resolve a specific PR via the provider contract
+          # @return [ProviderPullRequest, nil] PR evidence or nil
+          def resolve_pr_metadata(pr_identifier, timeout:)
+            provider = active_provider(timeout: timeout)
+            return nil unless provider
+
+            provider.pull_request(number: pr_identifier)
+          rescue Ace::Git::Error
+            # Classified provider failure: keep status local, skip PR evidence
+            nil
+          end
+
+          # Fetch PR evidence sections via the provider contract
+          # @return [Hash] {:pr_metadata => ProviderPullRequest, :pr_activity => Hash}
+          def fetch_pr_sections(current_branch:, include_metadata:, include_activity:, timeout:)
+            provider = active_provider(timeout: timeout)
+            return {pr_metadata: nil, pr_activity: nil} unless provider
+
+            metadata = include_metadata ? provider.pull_request_for_branch(branch: current_branch) : nil
+            activity = include_activity ? fetch_activity(provider, current_branch: current_branch) : nil
+
+            {pr_metadata: metadata, pr_activity: activity}
+          rescue Ace::Git::Error
+            # Classified provider failure: keep status local, skip PR evidence
+            {pr_metadata: nil, pr_activity: nil}
+          end
+
+          # Build merged/open activity lists from recent PR evidence
+          def fetch_activity(provider, current_branch:)
+            prs = provider.recent_pull_requests(limit: 30)
+            merged = prs
+              .select { |pr| pr.state == :merged }
+              .first(Ace::Git.merged_prs_limit)
+            open_prs = prs
+              .select { |pr| pr.state == :open && pr.head_ref != current_branch }
+              .first(Ace::Git.open_prs_limit)
+
+            return nil if merged.empty? && open_prs.empty?
+
+            {merged: merged, open: open_prs}
+          end
+
+          # Resolve the default server's registered provider, or nil.
+          # Resolution failures are classified; enrichment is optional, so any
+          # of them simply skips the PR sections.
+          def active_provider(timeout:)
+            server = ServerRegistry.resolve_default
+            return nil unless server
+
+            Providers.for(server, timeout: timeout)
+          rescue Ace::Git::Error
+            nil
+          end
+
           # Fetch git status in short branch format
           # @return [String, nil] Git status output or nil
           def fetch_git_status
@@ -149,114 +193,6 @@ module Ace
           rescue
             nil
           end
-
-          # Fetch PR metadata for current branch
-          # @param timeout [Integer] Timeout in seconds
-          # @return [Hash, nil] PR metadata or nil
-          def fetch_pr_metadata(timeout:)
-            # First try to find PR for current branch
-            pr_number = Molecules::PrMetadataFetcher.find_pr_for_branch(timeout: timeout)
-            return nil unless pr_number
-
-            # Then fetch full metadata
-            result = Molecules::PrMetadataFetcher.fetch_metadata(pr_number, timeout: timeout)
-            result[:success] ? result[:metadata] : nil
-          rescue Ace::Git::GhNotInstalledError, Ace::Git::GhAuthenticationError
-            # gh not available, skip PR metadata
-            nil
-          rescue Ace::Git::PrNotFoundError
-            # No PR for this branch
-            nil
-          rescue Ace::Git::TimeoutError
-            # Timeout, skip PR metadata
-            nil
-          rescue
-            # Any other error, skip PR metadata
-            nil
-          end
-
-          # Fetch PR activity (recently merged and open PRs)
-          # @param current_branch [String] Current branch name to exclude from open PRs
-          # @param timeout [Integer] Timeout in seconds
-          # @return [Hash, nil] PR activity with :merged and :open arrays (symbol keys), or nil
-          #   Each PR in the arrays has string keys from JSON parsing: "number", "title", etc.
-          def fetch_pr_activity(current_branch:, timeout:)
-            merged_result = Molecules::PrMetadataFetcher.fetch_recently_merged(
-              limit: Ace::Git.merged_prs_limit,
-              timeout: timeout
-            )
-            open_result = Molecules::PrMetadataFetcher.fetch_open_prs(
-              exclude_branch: current_branch,
-              timeout: timeout
-            )
-
-            # Return nil if both failed
-            return nil unless merged_result[:success] || open_result[:success]
-
-            # Use symbol keys for outer hash, string keys for PR data (from JSON)
-            # This is documented behavior - consumers should access via pr_activity[:merged]
-            # and individual PRs via pr["number"], pr["title"], etc.
-            {
-              merged: merged_result[:success] ? merged_result[:prs] : [],
-              open: open_result[:success] ? open_result[:prs] : []
-            }
-          rescue
-            # Any error, skip PR activity
-            nil
-          end
-
-          # Fetch PR metadata and activity in a single API call for optimal performance
-          # Uses gh pr list --state all to get all PRs, then filters locally
-          # @param current_branch [String] Current branch name to match/exclude
-          # @param timeout [Integer] Timeout in seconds
-          # @return [Hash] Result with :pr_metadata and :pr_activity keys
-          def fetch_pr_data_parallel(current_branch:, timeout:)
-            # Single API call gets all recent PRs
-            result = Molecules::PrMetadataFetcher.fetch_all_prs(
-              limit: 15,  # Enough for current + merged + open
-              timeout: timeout
-            )
-
-            return {pr_metadata: nil, pr_activity: nil} unless result[:success]
-
-            prs = result[:prs]
-
-            # Find current PR (matching branch, prefer OPEN > MERGED > CLOSED)
-            branch_prs = prs.select { |pr| pr["headRefName"] == current_branch }
-            current_pr = branch_prs.min_by { |pr|
-              case pr["state"]
-              when "OPEN" then 0
-              when "MERGED" then 1
-              when "CLOSED" then 2
-              else 3
-              end
-            }
-
-            # Get merged PRs (sorted by mergedAt descending, limited)
-            merged_prs = prs
-              .select { |pr| pr["state"] == "MERGED" }
-              .sort_by { |pr| pr["mergedAt"] || "" }
-              .reverse
-              .take(Ace::Git.merged_prs_limit)
-
-            # Get open PRs (exclude current branch, limited)
-            open_prs = prs
-              .select { |pr| pr["state"] == "OPEN" && pr["headRefName"] != current_branch }
-              .take(Ace::Git.open_prs_limit)
-
-            # Build activity hash (nil if no activity to show)
-            pr_activity = nil
-            if merged_prs.any? || open_prs.any?
-              pr_activity = {merged: merged_prs, open: open_prs}
-            end
-
-            {
-              pr_metadata: current_pr,
-              pr_activity: pr_activity
-            }
-          rescue
-            {pr_metadata: nil, pr_activity: nil}
-          end
         end
       end
     end

data/lib/ace/git/providers/base.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Ace
+  module Git
+    module Providers
+      # Abstract provider contract implemented by provider packages.
+      #
+      # The core defines the interface and the normalized evidence types;
+      # implementations own all provider CLI invocation, output parsing, and
+      # authentication verification. The core itself never executes a provider
+      # CLI and never parses provider output.
+      #
+      # Subclasses receive the resolved server identity and may accept two
+      # optional constructor keywords (see {Providers.for}):
+      # - timeout: operation timeout in seconds
+      # - runner: injectable command runner for tests; a callable receiving
+      #   keyword arguments (args:, timeout:, env:) and returning a Hash with
+      #   :stdout, :stderr, :exit_code
+      class Base
+        attr_reader :server, :timeout
+
+        # @param server [ResolvedServer] resolved server identity
+        # @param timeout [Integer, nil] operation timeout (default: config)
+        # @param runner [Proc, nil] injectable command runner for tests
+        def initialize(server:, timeout: nil, runner: nil)
+          @server = server
+          @timeout = timeout || Ace::Git.network_timeout
+          @runner = runner
+        end
+
+        # @return [Boolean] true when the provider CLI binary is installed
+        def available?
+          raise NotImplementedError, "Providers must implement #{self.class}#available?"
+        end
+
+        # @raise [ProviderCliMissingError] when the provider CLI is missing
+        def check_available!
+          raise NotImplementedError, "Providers must implement #{self.class}#check_available!"
+        end
+
+        # @return [Boolean] true when the provider CLI is authenticated
+        def authenticated?
+          raise NotImplementedError, "Providers must implement #{self.class}#authenticated?"
+        end
+
+        # @raise [ProviderAuthenticationError] when unauthenticated
+        def check_authenticated!
+          raise NotImplementedError, "Providers must implement #{self.class}#check_authenticated!"
+        end
+
+        # Fetch one pull request.
+        #
+        # @param number [Integer, String] pull request number
+        # @return [ProviderPullRequest] normalized pull request evidence
+        def pull_request(number:)
+          raise NotImplementedError, "Providers must implement #{self.class}#pull_request"
+        end
+
+        # Find the pull request associated with a branch.
+        #
+        # @param branch [String] branch name
+        # @return [ProviderPullRequest, nil] evidence, or nil when no pull
+        #   request is associated with the branch
+        def pull_request_for_branch(branch:)
+          raise NotImplementedError, "Providers must implement #{self.class}#pull_request_for_branch"
+        end
+
+        # Fetch the full diff of one pull request.
+        #
+        # @param number [Integer, String] pull request number
+        # @return [String] unified diff text
+        def pull_request_diff(number:)
+          raise NotImplementedError, "Providers must implement #{self.class}#pull_request_diff"
+        end
+
+        # List recent pull requests across states (newest first).
+        #
+        # @param limit [Integer] maximum number of pull requests
+        # @return [Array<ProviderPullRequest>] normalized pull requests
+        def recent_pull_requests(limit:)
+          raise NotImplementedError, "Providers must implement #{self.class}#recent_pull_requests"
+        end
+
+        # Fetch one issue.
+        #
+        # @param number [Integer, String] issue number
+        # @return [ProviderIssue] normalized issue evidence
+        def issue(number:)
+          raise NotImplementedError, "Providers must implement #{self.class}#issue"
+        end
+
+        # Fetch check/CI status evidence for a reference.
+        #
+        # @param ref [String] commit sha or branch name
+        # @return [Array<ProviderCheck>] normalized check evidence
+        def checks(ref:)
+          raise NotImplementedError, "Providers must implement #{self.class}#checks"
+        end
+
+        # Fetch repository metadata for the resolved server.
+        #
+        # @return [ProviderRepository] normalized repository evidence
+        def repository
+          raise NotImplementedError, "Providers must implement #{self.class}#repository"
+        end
+
+        # ---- PR lifecycle mutations ----
+        #
+        # Contract requirements (enforced by every provider implementation):
+        # - Exact identity: lookup and create operate on the exact
+        #   head repository URL/ref and base repository URL/ref; no fork
+        #   inference and no branch-name-only matching.
+        # - Expected head: every head-dependent operation receives the exact
+        #   head SHA the caller saw and must fail with
+        #   ProviderExpectedHeadConflictError when the live head differs. For
+        #   merge the enforcement must be atomic provider-side; a provider CLI
+        #   without such support raises ProviderUnsupportedCapabilityError
+        #   instead of emulating a check-then-merge race.
+        # - Idempotent create: one exact open base/head match returns the
+        #   existing PR (`:existing` receipt); zero matches create; more than
+        #   one match raises ProviderConflictingMatchesError.
+        # - Unknown outcomes: a transport failure after a request that may
+        #   have mutated state raises ProviderUnknownOutcomeError carrying the
+        #   exact identity; implementations never retry automatically.
+        # - Receipts: mutations return a ProviderMutationReceipt whose
+        #   evidence carries source/base repository provenance and exact head.
+
+        # Find open pull requests matching an exact base/head identity.
+        #
+        # @param head_repository_url [String] source repository URL
+        # @param head_ref [String] source branch/ref
+        # @param base_repository_url [String] base repository URL
+        # @param base_ref [String] base branch/ref
+        # @return [Array<ProviderPullRequest>] matching open pull requests
+        def find_open_pull_requests(head_repository_url:, head_ref:, base_repository_url:, base_ref:)
+          raise NotImplementedError, "Providers must implement #{self.class}#find_open_pull_requests"
+        end
+
+        # Create a pull request, reconciling against an exact open match.
+        #
+        # @param head_ref [String] source branch/ref
+        # @param head_repository_url [String] source repository URL
+        # @param base_ref [String] base branch/ref
+        # @param expected_head [String] exact SHA the pushed source ref must
+        #   resolve to; the created/reconciled PR head is proven against it
+        # @param title [String] pull request title
+        # @param body [String, nil] pull request body text
+        # @param draft [Boolean] request a draft pull request when the
+        #   provider supports draft state; the returned evidence always
+        #   reports the provider's actual draft state
+        # @return [ProviderMutationReceipt] with idempotency :created/:existing
+        # @raise [ProviderConflictingMatchesError] on multiple exact matches
+        # @raise [ProviderExpectedHeadConflictError] when the head differs
+        # @raise [ProviderUnknownOutcomeError] on unknown post-send outcome
+        def create_pull_request(head_ref:, head_repository_url:, base_ref:, expected_head:, title:, body: nil, draft: true)
+          raise NotImplementedError, "Providers must implement #{self.class}#create_pull_request"
+        end
+
+        # Update title/body of a pull request after head verification.
+        #
+        # @param number [Integer, String] pull request number
+        # @param expected_head [String] exact SHA the PR head must still be
+        # @param title [String, nil] new title
+        # @param body [String, nil] new body text
+        # @return [ProviderMutationReceipt]
+        # @raise [ProviderExpectedHeadConflictError] when the head differs
+        def update_pull_request(number:, expected_head:, title: nil, body: nil)
+          raise NotImplementedError, "Providers must implement #{self.class}#update_pull_request"
+        end
+
+        # Mark a draft pull request ready for review after head verification.
+        #
+        # @param number [Integer, String] pull request number
+        # @param expected_head [String] exact SHA the PR head must still be
+        # @return [ProviderMutationReceipt]
+        # @raise [ProviderExpectedHeadConflictError] when the head differs
+        # @raise [ProviderUnsupportedCapabilityError] when the provider cannot
+        #   change draft state
+        def ready_pull_request(number:, expected_head:)
+          raise NotImplementedError, "Providers must implement #{self.class}#ready_pull_request"
+        end
+
+        # Merge a pull request with provider-side expected-head enforcement.
+        #
+        # @param number [Integer, String] pull request number
+        # @param expected_head [String] exact SHA enforced atomically by the
+        #   provider before merging
+        # @param method [Symbol, String] :squash, :merge, or :rebase; there
+        #   is no implicit default
+        # @return [ProviderMutationReceipt]
+        # @raise [ProviderExpectedHeadConflictError] when the provider refuses
+        #   the merge because the head changed
+        # @raise [ProviderUnsupportedCapabilityError] when the provider CLI
+        #   cannot enforce the head precondition atomically
+        def merge_pull_request(number:, expected_head:, method:)
+          raise NotImplementedError, "Providers must implement #{self.class}#merge_pull_request"
+        end
+
+        private
+
+        # Command runner: injected fake or nil (implementations use their own
+        # executor when nil).
+        attr_reader :runner
+
+        # Shared lifecycle guard: refuse when the live head differs from the
+        # caller's expected head. Providers must use this so the classified
+        # failure shape stays identical across forges.
+        def verify_expected_head!(pull_request, expected_head)
+          unless pull_request.head_sha.is_a?(String) && !pull_request.head_sha.empty?
+            raise ProviderMalformedOutputError,
+              "Provider evidence for PR ##{pull_request.number} is missing the exact head SHA"
+          end
+          return pull_request if pull_request.head_sha == expected_head
+
+          raise ProviderExpectedHeadConflictError,
+            "PR ##{pull_request.number} head changed: expected #{expected_head}, found #{pull_request.head_sha}"
+        end
+      end
+    end
+  end
+end