ace-git 0.24.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 746038569079877012656b703209b794e8a055718955f23f8d4b613ec8fb6628
-  data.tar.gz: 841b2ac7dc6eed9348e36a46f6abef8e18c8f726e9f26a705d96a3548209ee27
+  metadata.gz: '089e377ec56099fb872544bfc754f6f95f00ecaf157715ecad93e726e9c8960f'
+  data.tar.gz: 35bb8b556655c0ef1804fb2fe26039dd182115e558127254c49e17da9ce3f1ba
 SHA512:
-  metadata.gz: b10072d2af5d314c0c00fefc7883ab6d33de5bad5388b549a50db5cc1134b92196d1462c4c598c9aeaa3a79114eb44be2d29693aa3a95db74646bd4786dd6131
-  data.tar.gz: 510071cb8c141cde868bcc0fb79d55e62edbf749c5b82dfbb987488cfa20fcd236fc7c2c5c963db3891655bcbef8bcf9223634298a5abeb0236c4518f9ecf6be
+  metadata.gz: c156b7e8b123f15f9d305d27933d68de72d640e16a803a9d7b5ce2cce12c1c7cf537bb7e6ae31e7c8ca044999869160ccf835281fdcc51e3bee76589cd43363f
+  data.tar.gz: 4eaeac69d71391c491718c68e68e1599a0a3e1991eae4a25d3e4e2a922959ef13e940c7d863eae01478a78ae9f81940a016fcac46da27ee7bbdf427f64527a03

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

@@ -27,6 +27,11 @@ git:
   #     provider: github
   #     url: https://github.example.com/owner/repo
 
+  # Provider packages required on first use (library names under ace/git/*).
+  # Both shipped provider gems are loaded by default; remove entries for
+  # providers you do not use.
+  providers: [github, forgejo]
+
   # Status command settings
   status:
     commits_limit: 3      # Number of recent commits to show

data/CHANGELOG.md

@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.25.0] - 2026-09-28
+
+### Added
+- Forge-neutral `ace-git pr` lifecycle CLI: `show`, `create`, `update`, `ready`, `merge`
+  with `--server` / `--default-server` selection and `--format json`.
+- Provider contract for PR lifecycle mutations (exact base/head identity,
+  idempotent create reconciliation, expected-head enforcement, unknown-outcome
+  classification) on `Ace::Git::Providers::Base`.
+- Normalized evidence types: PR provenance fields (`head_repository_url`,
+  `base_repository_url`, `merge_commit_sha`), `ProviderPullRequestIdentity`,
+  `ProviderMutationReceipt`, `ProviderCleanupProof` with the cleanup proof
+  status vocabulary.
+- Classified lifecycle failures: identity mismatch, conflicting exact matches,
+  expected-head conflict, unsupported capability, unknown mutation outcome.
+- Server selection helpers `ServerRegistry.resolve_for`, `matching_servers`,
+  and `servers_for_owner_repo`; `PrReference` atom for `NUMBER`,
+  `owner/repo#NUMBER`, and URL identifiers.
+- Config-driven provider loading via `git.providers` (default: both shipped
+  provider gems).
+
+### Changed
+- PR identifiers now validate repository identity against the resolved server;
+  mismatches fail before any mutation. `owner/repo#NUMBER` requires exactly one
+  configured matching server and never assumes github.com.
+
+
+### Added
+- Forge-neutral `ace-git pr` lifecycle CLI: `show`, `create`, `update`, `ready`, `merge`
+  with `--server` / `--default-server` selection and `--format json`.
+- Provider contract for PR lifecycle mutations (exact base/head identity,
+  idempotent create reconciliation, expected-head enforcement, unknown-outcome
+  classification) on `Ace::Git::Providers::Base`.
+- Normalized evidence types: PR provenance fields (`head_repository_url`,
+  `base_repository_url`, `merge_commit_sha`), `ProviderPullRequestIdentity`,
+  `ProviderMutationReceipt`, `ProviderCleanupProof` with the cleanup proof
+  status vocabulary.
+- Classified lifecycle failures: identity mismatch, conflicting exact matches,
+  expected-head conflict, unsupported capability, unknown mutation outcome.
+- Server selection helpers `ServerRegistry.resolve_for`, `matching_servers`,
+  and `servers_for_owner_repo`; `PrReference` atom for `NUMBER`,
+  `owner/repo#NUMBER`, and URL identifiers.
+- Config-driven provider loading via `git.providers` (default: both shipped
+  provider gems).
+
+### Changed
+- PR identifiers now validate repository identity against the resolved server;
+  mismatches fail before any mutation. `owner/repo#NUMBER` requires exactly one
+  configured matching server and never assumes github.com.
+
+
 ## [0.24.0] - 2026-09-21
 
 ### Added

data/docs/usage.md

@@ -23,11 +23,12 @@ gem install ace-git
 
 ## Command Overview
 
-`ace-git` ships four commands:
+`ace-git` ships the following commands:
 
 - `diff` for filtered or formatted git diffs
 - `status` for repository context and PR activity
 - `branch` for current branch and tracking state
+- `pr` for the forge-neutral pull request lifecycle (`show`, `create`, `update`, `ready`, `merge`)
 - `version` for the installed package version
 
 `ace-git` with no arguments shows help. Git range shorthand such as `HEAD~5..HEAD` routes to `diff`.
@@ -154,6 +155,51 @@ ace-git branch --format json
 **Options:**
 - `--format, -f` - Output format: `text` (default), `json`
 
+### `ace-git pr`
+
+Forge-neutral pull request lifecycle over the configured forge servers
+(`git.servers`). Every subcommand accepts `--server NAME` / `--default-server`
+(mutually exclusive; with neither, the configured repository remote is
+resolved) and `--format json`. Server, provider, and the exact head SHA are
+part of every result; failures are classified and exit nonzero.
+
+```bash
+# Show normalized PR evidence (number, owner/repo#number, or URL)
+ace-git pr show 25
+ace-git pr show cs3b/ace#25 --format json
+ace-git pr show https://forge.example.com/cs3b/ace/pull/25 --server forgejo-lab
+
+# Create (or reconcile to) a draft PR for a pushed branch.
+# The pushed head SHA is proven against the PR; draft is the default.
+ace-git pr create --head feature --base main \
+  --expected-head "$(git rev-parse HEAD)" \
+  --title "Add feature" --body-file /tmp/body.md --format json
+
+# Fork PRs name the source repository explicitly; the base repository is
+# always the selected configured server. No fork inference happens.
+ace-git pr create --head feature --head-repo https://forge.example.com/fork/ace \
+  --base main --expected-head SHA --title "Fork PR" --draft
+
+# Update title/body after head verification
+ace-git pr update 25 --expected-head SHA --title "New title" --body-file /tmp/body.md
+
+# Mark a draft ready (provider capability; unsupported providers fail classified)
+ace-git pr ready 25 --expected-head SHA
+
+# Merge with provider-side expected-head enforcement; no default method
+ace-git pr merge 25 --expected-head SHA --method squash
+```
+
+**Behavior guarantees:**
+- Create is idempotent: one exact open base/head match returns the existing
+  PR (`idempotency: existing`); multiple matches are a conflict.
+- `merge` requires the provider to enforce `--expected-head` atomically;
+  providers without that capability return an unsupported-capability failure
+  instead of racing.
+- A create request whose outcome is unknown (transport failure after send)
+  reports an unknown outcome with the exact identity to reconcile; it never
+  retries automatically.
+
 ### `ace-git version`
 
 Print the installed `ace-git` version.

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "server_url"
+
+module Ace
+  module Git
+    module Atoms
+      # Parse a user-supplied pull request identifier into its exact components.
+      #
+      # Three accepted shapes:
+      # - bare number:            "25"
+      # - owner/repo#number:      "cs3b/ace#25"
+      # - full URL:               "https://forge.example.com/cs3b/ace/pull/25"
+      #                           "https://forge.example.com/cs3b/ace/pulls/25"
+      #
+      # A URL's repository part is canonicalized through {ServerUrl.normalize}
+      # so identity matching never assumes a hostname. Parsing is purely
+      # textual; it never contacts a forge and never infers github.com.
+      module PrReference
+        # Parsed reference: `number` always present; exactly one of
+        # `repository_url` (canonical URL form) or `owner_repo` is set for
+        # explicit-repository shapes, both nil for a bare number.
+        Reference = Data.define(:number, :repository_url, :owner_repo) do
+          # @return [Boolean] true when the reference names a repository
+          def repository_explicit?
+            !repository_url.nil? || !owner_repo.nil?
+          end
+
+          # @return [Hash] plain representation
+          def to_h
+            {number: number, repository_url: repository_url, owner_repo: owner_repo}
+          end
+        end
+
+        BARE_NUMBER_PATTERN = /\A\d+\z/
+        OWNER_REPO_PATTERN = /\A(?<owner>[\w.\-]+)\/(?<repo>[\w.\-]+)#(?<number>\d+)\z/
+        URL_PATTERN = %r{
+          \Ahttps?://[^/\s]+/(?<path>.+?)/pulls?/(?<number>\d+)(?:[/?#].*)?\z
+        }ix
+
+        class << self
+          # Parse a pull request identifier.
+          #
+          # @param input [String, Integer] identifier in any accepted shape
+          # @return [Reference, nil] parsed reference, or nil when unrecognized
+          def parse(input)
+            text = input.to_s.strip
+            return nil if text.empty?
+
+            if (match = text.match(BARE_NUMBER_PATTERN))
+              return Reference.new(number: match[0].to_i, repository_url: nil, owner_repo: nil)
+            end
+
+            if (match = text.match(OWNER_REPO_PATTERN))
+              return Reference.new(
+                number: match[:number].to_i,
+                repository_url: nil,
+                owner_repo: "#{match[:owner]}/#{match[:repo]}"
+              )
+            end
+
+            if (match = text.match(URL_PATTERN))
+              return Reference.new(
+                number: match[:number].to_i,
+                repository_url: ServerUrl.normalize("#{text.split("/")[0..2].join("/")}/#{match[:path]}"),
+                owner_repo: nil
+              )
+            end
+
+            nil
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+
+module Ace
+  module Git
+    module CLI
+      module Commands
+        # Forge-neutral pull request lifecycle commands.
+        #
+        # Every subcommand accepts `--server NAME` / `--default-server`
+        # (mutually exclusive; remote resolution when neither is given) and
+        # `--format json`. Success output carries the resolved server,
+        # provider, and exact PR identity; failures exit nonzero with the
+        # classified provider error and never claim success.
+        module Pr
+          # Shared plumbing for all pr subcommands.
+          class BaseCommand < Ace::Support::Cli::Command
+            include Ace::Support::Cli::Base
+
+            option :server, type: :string, desc: "Explicit configured forge server name"
+            option :default_server, type: :boolean, desc: "Use the configured default forge server"
+            option :remote, type: :string, desc: "Git remote used for server resolution when nothing is selected"
+            option :format, type: :string, default: "text", desc: "Output format: text, json"
+
+            private
+
+            def lifecycle(options)
+              Organisms::PullRequestLifecycle.new(
+                server_name: options[:server],
+                use_default: options[:default_server] == true,
+                remote_name: options[:remote]
+              )
+            end
+
+            def render_evidence(options, header: nil, **fields)
+              if options[:format] == "json"
+                puts JSON.pretty_generate(fields)
+              else
+                puts header if header
+                fields.each do |label, value|
+                  next if value.nil?
+
+                  puts "#{label.to_s.tr("_", "-")}: #{format_value(value)}"
+                end
+              end
+            end
+
+            def format_value(value)
+              case value
+              when Hash
+                value.compact.map { |key, nested| "#{key}=#{nested}" }.join(" ")
+              else
+                value.to_s
+              end
+            end
+
+            def emit_receipt(options, operation, receipt)
+              pr = receipt.pull_request
+              render_evidence(
+                options,
+                header: "#{operation} PR ##{pr.number} on #{receipt.server_name}",
+                server: receipt.server_name,
+                operation: receipt.operation,
+                idempotency: receipt.idempotency,
+                number: pr.number,
+                url: pr.url,
+                title: pr.title,
+                state: pr.state,
+                draft: pr.draft,
+                head: pr.head_sha,
+                head_ref: pr.head_ref,
+                head_repository: pr.head_repository_url,
+                base_ref: pr.base_ref,
+                base_repository: pr.base_repository_url
+              )
+            end
+          end
+
+          # `ace-git pr show ID`
+          class Show < BaseCommand
+            desc "Show normalized pull request evidence"
+
+            argument :identifier, required: true, desc: "PR number, owner/repo#number, or URL"
+
+            def call(identifier:, **options)
+              pr = lifecycle(options).show(identifier)
+              render_evidence(
+                options,
+                header: "PR ##{pr.number} on #{pr.server_name}",
+                server: pr.server_name,
+                number: pr.number,
+                url: pr.url,
+                title: pr.title,
+                state: pr.state,
+                draft: pr.draft,
+                head: pr.head_sha,
+                head_ref: pr.head_ref,
+                head_repository: pr.head_repository_url,
+                base_ref: pr.base_ref,
+                base_repository: pr.base_repository_url,
+                merge_commit: pr.merge_commit_sha
+              )
+            rescue Ace::Git::Error, ArgumentError => e
+              raise Ace::Support::Cli::Error.new(e.message)
+            end
+          end
+
+          # `ace-git pr create --head REF --head-repo URL --base REF --expected-head SHA --title TEXT [--body-file PATH] [--draft]`
+          class Create < BaseCommand
+            desc "Create (or reconcile to) a pull request; drafts are the default"
+
+            option :head, type: :string, required: true, desc: "Source branch/ref"
+            option :head_repo, type: :string, desc: "Source repository URL (fork); defaults to the base repository"
+            option :base, type: :string, required: true, desc: "Base branch/ref"
+            option :expected_head, type: :string, required: true, desc: "Exact SHA the pushed source ref must resolve to"
+            option :title, type: :string, required: true, desc: "Pull request title"
+            option :body_file, type: :string, desc: "Path to the pull request body text"
+            option :draft, type: :boolean, default: true, desc: "Create as draft when the provider supports it"
+
+            def call(head:, base:, expected_head:, title:, **options)
+              receipt = lifecycle(options).create(
+                head_ref: head,
+                head_repository_url: options[:head_repo],
+                base_ref: base,
+                expected_head: expected_head,
+                title: title,
+                body_file: options[:body_file],
+                draft: options[:draft] != false
+              )
+              emit_receipt(options, "created", receipt)
+            rescue Ace::Git::Error, ArgumentError => e
+              raise Ace::Support::Cli::Error.new(e.message)
+            end
+          end
+
+          # `ace-git pr update ID --expected-head SHA [--title TEXT] [--body-file PATH]`
+          class Update < BaseCommand
+            desc "Update pull request title/body after head verification"
+
+            argument :identifier, required: true, desc: "PR number, owner/repo#number, or URL"
+            option :expected_head, type: :string, required: true, desc: "Exact SHA the PR head must still be"
+            option :title, type: :string, desc: "New title"
+            option :body_file, type: :string, desc: "Path to the new body text"
+
+            def call(identifier:, expected_head:, **options)
+              receipt = lifecycle(options).update(
+                identifier,
+                expected_head: expected_head,
+                title: options[:title],
+                body_file: options[:body_file]
+              )
+              emit_receipt(options, "updated", receipt)
+            rescue Ace::Git::Error, ArgumentError => e
+              raise Ace::Support::Cli::Error.new(e.message)
+            end
+          end
+
+          # `ace-git pr ready ID --expected-head SHA`
+          class Ready < BaseCommand
+            desc "Mark a draft pull request ready for review"
+
+            argument :identifier, required: true, desc: "PR number, owner/repo#number, or URL"
+            option :expected_head, type: :string, required: true, desc: "Exact SHA the PR head must still be"
+
+            def call(identifier:, expected_head:, **options)
+              receipt = lifecycle(options).ready(identifier, expected_head: expected_head)
+              emit_receipt(options, "readied", receipt)
+            rescue Ace::Git::Error, ArgumentError => e
+              raise Ace::Support::Cli::Error.new(e.message)
+            end
+          end
+
+          # `ace-git pr merge ID --expected-head SHA --method squash|merge|rebase`
+          class Merge < BaseCommand
+            desc "Merge with provider-side expected-head enforcement; no default method"
+
+            argument :identifier, required: true, desc: "PR number, owner/repo#number, or URL"
+            option :expected_head, type: :string, required: true, desc: "Exact SHA enforced by the provider"
+            option :method, type: :string, required: true, desc: "Merge method: squash, merge, rebase"
+
+            def call(identifier:, expected_head:, method:, **options)
+              receipt = lifecycle(options).merge(identifier, expected_head: expected_head, method: method)
+              emit_receipt(options, "merged", receipt)
+            rescue Ace::Git::Error, ArgumentError => e
+              raise Ace::Support::Cli::Error.new(e.message)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/cli.rb

@@ -6,6 +6,7 @@ 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
@@ -50,18 +51,25 @@ module Ace
       REGISTERED_COMMANDS = [
         ["diff", "Show filtered git diff output"],
         ["status", "Show repository status and PR context"],
-        ["branch", "Show current branch information"]
+        ["branch", "Show current branch information"],
+        ["pr", "Forge-neutral pull request lifecycle: show, create, update, ready, merge"]
       ].freeze
 
       HELP_EXAMPLES = [
         "ace-git diff --since 7d           # Changes from last week",
         "ace-git diff -p 'lib/**' -f summary  # Filtered summary",
-        "ace-git status --no-pr            # Quick status, skip network"
+        "ace-git status --no-pr            # Quick status, skip network",
+        "ace-git pr show 25 --format json  # Normalized PR evidence"
       ].freeze
 
       register "diff", Commands::Diff.new
       register "status", Commands::Status.new
       register "branch", Commands::Branch.new
+      register "pr show", Commands::Pr::Show.new
+      register "pr create", Commands::Pr::Create.new
+      register "pr update", Commands::Pr::Update.new
+      register "pr ready", Commands::Pr::Ready.new
+      register "pr merge", Commands::Pr::Merge.new
 
       version_cmd = Ace::Support::Cli::VersionCommand.build(
         gem_name: "ace-git",

data/lib/ace/git/errors.rb

@@ -52,5 +52,31 @@ module Ace
 
     # The requested pull request, issue, branch, or commit does not exist.
     class ProviderObjectNotFoundError < Error; end
+
+    # ---- PR lifecycle mutation failures ----
+
+    # A supplied PR URL or repository identity does not match the resolved
+    # server (or the explicit selection contradicts the identifier). Detected
+    # before any mutation.
+    class ProviderIdentityMismatchError < Error; end
+
+    # More than one open pull request exactly matches the requested
+    # base/head identity, so no single object can be selected.
+    class ProviderConflictingMatchesError < Error; end
+
+    # The pull request head changed relative to the expected head SHA the
+    # caller supplied. The operation did not proceed (or the provider refused
+    # it atomically).
+    class ProviderExpectedHeadConflictError < Error; end
+
+    # The provider CLI cannot enforce a required precondition atomically
+    # (e.g. expected-head merge) or does not offer the requested operation.
+    # Never worked around with a check-then-act fallback.
+    class ProviderUnsupportedCapabilityError < Error; end
+
+    # A mutation request was sent but its outcome is unknown (e.g. transport
+    # failure after the send). Contains the exact base/head identity needed to
+    # reconcile by lookup; never retried automatically.
+    class ProviderUnknownOutcomeError < Error; end
   end
 end

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/providers/base.rb

@@ -104,11 +104,117 @@ module Ace
           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

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

@@ -12,7 +12,8 @@ module Ace
     # :open, :closed.
     ProviderPullRequest = Data.define(
       :server_name, :number, :title, :state, :head_ref, :base_ref,
-      :head_sha, :author, :url, :draft, :merged_at
+      :head_sha, :author, :url, :draft, :merged_at,
+      :head_repository_url, :base_repository_url, :merge_commit_sha
     )
 
     ProviderIssue = Data.define(:server_name, :number, :title, :state, :author, :url, :labels)
@@ -22,5 +23,74 @@ module Ace
 
     # Normalized repository evidence.
     ProviderRepository = Data.define(:server_name, :full_name, :default_branch, :url)
+
+    # Exact pull request source/base identity used for idempotent create
+    # reconciliation, expected-head proof, and cleanup consent binding.
+    #
+    # `head_sha` is the exact head commit the identity was captured at; every
+    # mutation decision that depends on head state must compare against it.
+    ProviderPullRequestIdentity = Data.define(
+      :head_repository_url, :head_ref, :base_repository_url, :base_ref, :head_sha
+    ) do
+      # @return [Hash] plain, JSON-serializable representation
+      def to_h
+        {
+          head_repository_url: head_repository_url,
+          head_ref: head_ref,
+          base_repository_url: base_repository_url,
+          base_ref: base_ref,
+          head_sha: head_sha
+        }
+      end
+    end
+
+    # Normalized result of one provider lifecycle mutation (create, update,
+    # ready, merge). Receipts are immutable evidence: the operation performed,
+    # the pull request state observed afterwards, and — for creates only —
+    # whether the request created a new PR or reconciled to an existing one
+    # (`:created` / `:existing`; nil for non-create operations).
+    ProviderMutationReceipt = Data.define(:server_name, :operation, :pull_request, :idempotency) do
+      # @return [Hash] plain, JSON-serializable representation
+      def to_h
+        {
+          server_name: server_name,
+          operation: operation,
+          idempotency: idempotency,
+          pull_request: pull_request&.to_h
+        }
+      end
+    end
+
+    # Cleanup proof status vocabulary. Only :merged is confirmed remote merge
+    # proof; every other status retains the candidate. Provider transport
+    # failures (:offline, :authentication_error, :malformed) are distinct from
+    # object states and never relabel a failed lookup as merged.
+    CLEANUP_PROOF_STATUSES = %i[
+      no_pr open closed_unmerged merged offline authentication_error malformed
+    ].freeze
+
+    # Normalized provider proof about the pull request behind a cleanup
+    # candidate (worktree, local ref, or remote ref). `status` is one of
+    # {CLEANUP_PROOF_STATUSES}; pr/head fields are nil unless a PR was found.
+    ProviderCleanupProof = Data.define(
+      :server_name, :status, :pr_number, :pr_url, :head_sha, :merge_commit_sha
+    ) do
+      # @return [Boolean] true only for confirmed remote merge proof
+      def merged?
+        status == :merged
+      end
+
+      # @return [Hash] plain, JSON-serializable representation
+      def to_h
+        {
+          server_name: server_name,
+          status: status,
+          pr_number: pr_number,
+          pr_url: pr_url,
+          head_sha: head_sha,
+          merge_commit_sha: merge_commit_sha
+        }
+      end
+    end
   end
 end

data/lib/ace/git/providers.rb

@@ -42,6 +42,12 @@ module Ace
 
         # Build the provider implementation for a resolved server.
         #
+        # Provider packages register themselves when required. On a miss, the
+        # provider libraries listed in the `git.providers` configuration are
+        # required once (mono-repo default: both shipped provider gems) and
+        # the registry is re-checked; a still-missing provider is a classified
+        # failure, never a fallback.
+        #
         # @param server [ResolvedServer] exactly-resolved server identity
         # @param timeout [Integer, nil] provider operation timeout in seconds
         # @param runner [Proc, nil] optional command runner injection for tests;
@@ -52,10 +58,14 @@ module Ace
         def for(server, timeout: nil, runner: nil)
           key = normalize_type(server.provider)
           provider_class = @mutex.synchronize { @registry[key] }
+          unless provider_class
+            require_configured_providers
+            provider_class = @mutex.synchronize { @registry[key] }
+          end
           unless provider_class
             raise UnknownProviderError,
               "No provider registered for type #{key.inspect} (server '#{server.name}'); " \
-              "install and require the provider package that owns #{key.inspect}"
+              "install the provider package that owns #{key.inspect} and list it in git.providers"
           end
 
           provider_class.new(server: server, timeout: timeout, runner: runner)
@@ -75,7 +85,10 @@ module Ace
 
         # Clear all registrations (test seam).
         def reset!
-          @mutex.synchronize { @registry.clear }
+          @mutex.synchronize do
+            @registry.clear
+            @required_configured = {}
+          end
         end
 
         private
@@ -86,6 +99,22 @@ module Ace
 
           normalized.to_sym
         end
+
+        # Require the provider libraries configured under `git.providers`
+        # (e.g. "github" -> ace/git/github). Load failures are ignored here;
+        # a missing provider surfaces as UnknownProviderError at resolution.
+        def require_configured_providers
+          @required_configured ||= {}
+          Array(Ace::Git.config["providers"]).each do |name|
+            library = name.to_s.strip.downcase
+            next if library.empty? || @required_configured[library]
+
+            require "ace/git/#{library}"
+            @required_configured[library] = true
+          rescue LoadError
+            @required_configured[library] = true
+          end
+        end
       end
     end
   end

data/lib/ace/git/server_registry.rb

@@ -99,6 +99,52 @@ module Ace
           matches.first
         end
 
+        # Resolve exactly one server for an operation from CLI-style selection.
+        #
+        # @param server_name [String, Symbol, nil] explicit configured server name
+        # @param use_default [Boolean] resolve the configured default server
+        # @param remote_name [String, nil] remote used when nothing is selected
+        # @return [ResolvedServer]
+        # @raise [ConfigError] when explicit selection and default conflict
+        # @raise [UnknownServerNameError, NoDefaultServerConfiguredError,
+        #   MultipleDefaultServersError, AmbiguousRemoteError] per resolution
+        def resolve_for(server_name: nil, use_default: false, remote_name: nil)
+          if server_name && use_default
+            raise ConfigError,
+              "Server selection is ambiguous: an explicit server ('#{server_name}') and " \
+              "the default-server request are mutually exclusive"
+          end
+
+          if server_name
+            resolve(server_name)
+          elsif use_default
+            resolve_default
+          else
+            resolve_remote(remote_name)
+          end
+        end
+
+        # Configured servers whose URL matches the repository URL exactly.
+        #
+        # @param repository_url [String] repository URL in any supported shape
+        # @return [Array<ResolvedServer>] matching servers (may be empty)
+        def matching_servers(repository_url)
+          entries.map(&:server).select { |server| Atoms::ServerUrl.match?(server.url, repository_url) }
+        end
+
+        # Configured servers whose repository path equals `owner/repo`
+        # (any host). Never assumes a forge hostname.
+        #
+        # @param owner_repo [String] "owner/repo"
+        # @return [Array<ResolvedServer>] matching servers (may be empty)
+        def servers_for_owner_repo(owner_repo)
+          wanted = owner_repo.to_s.downcase
+          entries.map(&:server).select do |server|
+            path = Atoms::ServerUrl.normalize(server.url).to_s.split("/", 2)[1]
+            path == wanted
+          end
+        end
+
         private
 
         # Validated configured entries, in configuration order.

data/lib/ace/git/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Git
-    VERSION = "0.24.0"
+    VERSION = "0.25.0"
   end
 end

data/lib/ace/git.rb

@@ -120,7 +120,7 @@ module Ace
       normalized = normalize_keys(git_section)
 
       # Copy top-level settings
-      %w[default_branch remote verbose timeout network_timeout servers].each do |key|
+      %w[default_branch remote verbose timeout network_timeout servers providers].each do |key|
         config[key] = normalized[key] if normalized.key?(key)
       end
 
@@ -195,6 +195,7 @@ end
 # Require ATOM architecture components
 require_relative "git/atoms/command_executor"
 require_relative "git/atoms/server_url"
+require_relative "git/atoms/pr_reference"
 require_relative "git/atoms/pr_identifier"
 require_relative "git/atoms/pattern_filter"
 require_relative "git/atoms/diff_parser"
@@ -220,6 +221,7 @@ require_relative "git/molecules/git_status_fetcher"
 
 require_relative "git/organisms/diff_orchestrator"
 require_relative "git/organisms/repo_status_loader"
+require_relative "git/organisms/pull_request_lifecycle"
 require_relative "git/resolved_server"
 require_relative "git/server_registry"
 require_relative "git/providers/base"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-git
 version: !ruby/object:Gem::Version
-  version: 0.24.0
+  version: 0.25.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-23 00:00:00.000000000 Z
+date: 2026-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-config
@@ -150,6 +150,7 @@ files:
 - lib/ace/git/atoms/lock_error_detector.rb
 - lib/ace/git/atoms/pattern_filter.rb
 - lib/ace/git/atoms/pr_identifier.rb
+- lib/ace/git/atoms/pr_reference.rb
 - lib/ace/git/atoms/repository_checker.rb
 - lib/ace/git/atoms/repository_state_detector.rb
 - lib/ace/git/atoms/server_url.rb
@@ -160,6 +161,7 @@ files:
 - lib/ace/git/cli.rb
 - lib/ace/git/cli/commands/branch.rb
 - lib/ace/git/cli/commands/diff.rb
+- lib/ace/git/cli/commands/pr.rb
 - lib/ace/git/cli/commands/status.rb
 - lib/ace/git/errors.rb
 - lib/ace/git/models/diff_config.rb
@@ -172,6 +174,7 @@ files:
 - lib/ace/git/molecules/git_status_fetcher.rb
 - lib/ace/git/molecules/recent_commits_fetcher.rb
 - lib/ace/git/organisms/diff_orchestrator.rb
+- lib/ace/git/organisms/pull_request_lifecycle.rb
 - lib/ace/git/organisms/repo_status_loader.rb
 - lib/ace/git/providers.rb
 - lib/ace/git/providers/base.rb