ace-git-worktree 0.23.0 → 0.24.1

data/lib/ace/git/worktree/molecules/pull_request_creator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "ace/git"
+
+module Ace
+  module Git
+    module Worktree
+      module Molecules
+        # Creates draft pull requests for task worktrees through the
+        # forge-neutral provider contract.
+        #
+        # The caller must supply the exact pushed head SHA (`expected_head`);
+        # creation or reuse is proven against that SHA by the provider, never
+        # inferred from branch names. Server selection resolves lazily inside
+        # the lifecycle organism, so local-only task runs never touch a forge.
+        class PullRequestCreator
+          # @param server_name [String, nil] explicit server selection
+          # @param use_default [Boolean] resolve the configured default server
+          # @param remote_name [String, nil] remote used for fallback resolution
+          # @param timeout [Integer, nil] provider timeout
+          # @param runner [Proc, nil] injectable provider 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
+
+          # Create (or reconcile to) a draft PR for a pushed branch.
+          #
+          # @param branch [String] pushed head branch
+          # @param base [String] base branch/ref
+          # @param title [String] PR title
+          # @param expected_head [String] exact SHA the pushed branch resolves to
+          # @param head_repository_url [String, nil] source repository URL
+          #   (defaults to the selected server's repository)
+          # @param body [String, nil] PR body text
+          # @return [Hash] {success:, pr_number:, pr_url:, existing:, head_sha:, error:}
+          def create_draft(branch:, base:, title:, expected_head:, head_repository_url: nil, body: nil)
+            lifecycle = Ace::Git::Organisms::PullRequestLifecycle.new(**@selection.merge(timeout: @timeout, runner: @runner))
+            receipt = lifecycle.create(
+              head_ref: branch,
+              head_repository_url: head_repository_url,
+              base_ref: base,
+              expected_head: expected_head,
+              title: title,
+              body: body,
+              draft: true
+            )
+            pr = receipt.pull_request
+            {
+              success: true,
+              pr_number: pr.number,
+              pr_url: pr.url,
+              existing: receipt.idempotency == :existing,
+              head_sha: pr.head_sha,
+              error: nil
+            }
+          rescue Ace::Git::Error => e
+            {success: false, pr_number: nil, pr_url: nil, existing: false, head_sha: nil, error: e.message}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/worktree/molecules/pull_request_evidence_resolver.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "ace/git"
+
+module Ace
+  module Git
+    module Worktree
+      module Molecules
+        # Resolves normalized pull request evidence for worktree consumers.
+        #
+        # The server is selected once (explicit `--server`, `--default-server`,
+        # or remote resolution) and the PR is fetched through the registered
+        # provider contract. Local-only callers never construct this molecule,
+        # so no forge resolution happens without a PR-aware request.
+        class PullRequestEvidenceResolver
+          # @param server_name [String, nil] explicit server selection
+          # @param use_default [Boolean] resolve the configured default server
+          # @param remote_name [String, nil] git remote for fallback resolution
+          # @param timeout [Integer, nil] provider timeout
+          # @param runner [Proc, nil] injectable provider 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 exact PR evidence with source/base provenance.
+          #
+          # @param number [Integer, String] pull request number
+          # @return [Hash] {server: ResolvedServer, evidence: ProviderPullRequest}
+          def resolve(number)
+            server = Ace::Git::ServerRegistry.resolve_for(**@selection)
+            provider = Ace::Git::Providers.for(server, timeout: @timeout, runner: @runner)
+            {server: server, evidence: provider.pull_request(number: number)}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/worktree/molecules/worktree_creator.rb

@@ -103,20 +103,27 @@ module Ace
             end
           end
 
-          # Create a worktree for a Pull Request
+          # Create a worktree for a Pull Request from an already-verified
+          # source ref (see PullRequestCheckoutPreparer).
           #
-          # @param pr_data [Hash] PR data hash from PrFetcher
+          # @param pr_data [Hash] normalized PR data: :number, :title,
+          #   :head_branch, :base_branch
           # @param config [WorktreeConfig] Worktree configuration
           # @param git_root [String, nil] Git repository root (auto-detected if nil)
+          # @param source_ref [String, nil] verified local ref (e.g. FETCH_HEAD)
+          #   the PR head was proven against; required
+          # @param remote_tracking [String, nil] "remote/branch" tracking ref
+          #   when the source is reachable via a configured local remote
           # @return [Hash] Result with :success, :worktree_path, :branch, :error
           #
           # @example
           #   pr_data = { number: 26, title: "Add feature", head_branch: "feature/auth", base_branch: "main" }
-          #   result = creator.create_for_pr(pr_data, config)
-          #   # => { success: true, worktree_path: "/project/.ace-wt/pr-26", branch: "pr-26", tracking: "origin/feature/auth" }
-          def create_for_pr(pr_data, config, git_root: nil)
+          #   result = creator.create_for_pr(pr_data, config, source_ref: "FETCH_HEAD")
+          #   # => { success: true, worktree_path: ".../ace-pr-26", branch: "pr-26-add-feature", tracking: nil }
+          def create_for_pr(pr_data, config, git_root: nil, source_ref: nil, remote_tracking: nil)
             return error_result("PR data is required") unless pr_data
             return error_result("Configuration is required") unless config
+            return error_result("Verified source ref is required for PR checkout") if source_ref.nil? || source_ref.empty?
 
             begin
               # Determine git repository root
@@ -125,7 +132,6 @@ module Ace
 
               # Get PR-specific configuration (fallback to defaults)
               pr_config = config.pr_config || {}
-              remote_name = pr_config[:remote_name] || "origin"
               directory_format = pr_config[:directory_format] || "ace-pr-{number}"
               branch_format = pr_config[:branch_format] || "pr-{number}-{slug}"
 
@@ -140,27 +146,28 @@ module Ace
               validation = validate_worktree_path(worktree_path, git_root)
               return error_result(validation[:error]) unless validation[:valid]
 
-              # Fetch the remote branch
-              head_branch = pr_data[:head_branch]
-              fetch_result = fetch_remote_branch(remote_name, head_branch, git_root)
-              return error_result(fetch_result[:error]) unless fetch_result[:success]
-
-              # Create worktree with remote tracking
-              result = create_worktree_with_tracking(
-                worktree_path,
-                local_branch_name,
-                "#{remote_name}/#{head_branch}",
-                git_root,
-                configure_push: config.configure_push_for_mismatch?
-              )
+              # Create the worktree from the proven source ref
+              result = create_worktree(worktree_path, local_branch_name, git_root, start_point: source_ref)
               return result unless result[:success]
 
+              # Configure push behavior when tracking a differently-named branch
+              if remote_tracking && local_branch_name != extract_remote_branch_name(remote_tracking)
+                configure_push_for_worktree(worktree_path, local_branch_name, remote_tracking)
+              end
+
+              # Bind the reported tracking ref as the branch's real upstream so
+              # `@{upstream}` resolves; advisory when the tracking ref is not a
+              # local remote-tracking ref (fork URL fetches).
+              upstream = remote_tracking ? set_and_verify_upstream(local_branch_name, remote_tracking) : nil
+
               # Success - return worktree information
               {
                 success: true,
                 worktree_path: worktree_path,
                 branch: local_branch_name,
-                tracking: "#{remote_name}/#{head_branch}",
+                tracking: remote_tracking,
+                upstream: upstream,
+                warnings: remote_tracking && !upstream ? ["Could not set upstream to #{remote_tracking}"] : nil,
                 directory_name: directory_name,
                 pr_number: pr_data[:number],
                 pr_title: pr_data[:title],
@@ -764,6 +771,31 @@ module Ace
             }
           end
 
+          # Set and verify upstream for a PR worktree branch.
+          #
+          # @param local_branch [String] the worktree's local branch
+          # @param remote_tracking [String] e.g. "origin/feature"
+          # @return [String, nil] the verified upstream, or nil when it could
+          #   not be established (advisory)
+          def set_and_verify_upstream(local_branch, remote_tracking)
+            require_relative "../atoms/git_command"
+
+            exists = Atoms::GitCommand.execute(
+              "show-ref", "--verify", "--quiet", "refs/remotes/#{remote_tracking}", timeout: 5
+            )
+            return nil unless exists[:success]
+
+            result = Atoms::GitCommand.execute(
+              "branch", "--set-upstream-to=#{remote_tracking}", local_branch, timeout: 10
+            )
+            return nil unless result[:success]
+
+            verify = Atoms::GitCommand.execute(
+              "rev-parse", "--abbrev-ref", "#{local_branch}@{upstream}", timeout: 5
+            )
+            verify[:success] && verify[:output].to_s.strip == remote_tracking ? remote_tracking : nil
+          end
+
           # Format PR name using template
           #
           # @param template [String] Template string with {variables}

data/lib/ace/git/worktree/organisms/task_worktree_orchestrator.rb

@@ -31,7 +31,6 @@ module Ace
             @task_committer = Molecules::TaskCommitter.new(project_root: project_root)
             @task_pusher = Molecules::TaskPusher.new
             @worktree_creator = Molecules::WorktreeCreator.new
-            @pr_creator = Molecules::PrCreator.new
             @parent_task_resolver = Molecules::ParentTaskResolver.new(project_root: project_root)
           end
 
@@ -861,14 +860,14 @@ module Ace
             result[:success] && result[:output]&.include?(branch)
           end
 
-          # Create draft PR for task
+          # Create draft PR for task through the forge-neutral provider contract.
           #
-          # Creates a draft PR targeting the source branch (start_point) from which
-          # the worktree branch was created.
+          # The exact pushed head SHA is proven to the provider (expected_head);
+          # PR identity is never inferred from branch names alone.
           #
           # @param task_data [Hash] Task data hash from ace-task
           # @param worktree_result [Hash] Worktree creation result with :branch, :start_point
-          # @param options [Hash] Options (may include :source for base branch override)
+          # @param options [Hash] Options (may include :source, :server, :default_server)
           # @return [Hash] Result with :success, :pr_number, :pr_url, :existing, :error
           def create_pr_for_task(task_data, worktree_result, options)
             branch = worktree_result[:branch]
@@ -880,14 +879,49 @@ module Ace
             # Resolve base branch - handle SHA vs branch name
             base = resolve_pr_base(start_point, options)
 
-            # Create draft PR
-            @pr_creator.create_draft(
+            push_remote = options[:push_remote] || @config.push_remote || "origin"
+            creator = Molecules::PullRequestCreator.new(
+              server_name: options[:server],
+              use_default: options[:default_server] == true,
+              remote_name: push_remote
+            )
+            creator.create_draft(
               branch: branch,
               base: base,
-              title: title
+              title: title,
+              expected_head: pushed_branch_sha(branch, worktree_result[:worktree_path]),
+              head_repository_url: remote_url(push_remote)
             )
           end
 
+          # Exact SHA of the pushed worktree branch, proven locally before any
+          # provider call.
+          #
+          # @param branch [String] worktree branch name
+          # @param worktree_path [String, nil] worktree directory to resolve in
+          # @return [String] branch head SHA
+          def pushed_branch_sha(branch, worktree_path)
+            result = if worktree_path && Dir.exist?(worktree_path)
+              Dir.chdir(worktree_path) do
+                Atoms::GitCommand.execute("rev-parse", "--verify", "#{branch}^{commit}", timeout: 10)
+              end
+            else
+              Atoms::GitCommand.execute("rev-parse", "--verify", "#{branch}^{commit}", timeout: 10)
+            end
+            return result[:output].to_s.strip if result[:success]
+
+            raise Ace::Git::Error, "Cannot prove pushed head SHA for branch '#{branch}': #{result[:error]}"
+          end
+
+          # Local URL of a configured git remote (no network).
+          #
+          # @param remote [String] remote name
+          # @return [String, nil] remote URL
+          def remote_url(remote)
+            result = Atoms::GitCommand.execute("remote", "get-url", remote, timeout: 10)
+            result[:success] ? result[:output].to_s.strip : nil
+          end
+
           # Resolve PR base branch from start_point
           #
           # If start_point is a commit SHA (not a branch name), creates a branch
@@ -948,7 +982,7 @@ module Ace
           # Add started_at timestamp to task file IN WORKTREE
           #
           # This creates an initial commit in the worktree branch, enabling PR creation
-          # (GitHub requires at least one commit difference between branches for a PR).
+          # (Forges require at least one commit difference between branches for a PR).
           #
           # @param task_data [Hash] Task data hash from ace-task
           # @param worktree_result [Hash] Worktree creation result with :worktree_path

data/lib/ace/git/worktree/organisms/worktree_manager.rb

@@ -121,25 +121,31 @@ module Ace
             end
           end
 
-          # Create a worktree for a Pull Request
+          # Create a worktree for a Pull Request from normalized evidence.
           #
-          # @param pr_number [Integer] PR number
-          # @param pr_data [Hash] PR data from Ace::Git::Github::PrFetcher
+          # @param evidence [Ace::Git::ProviderPullRequest] normalized PR
+          #   evidence with exact source/base provenance
+          # @param checkout [Hash, nil] verified checkout from
+          #   PullRequestCheckoutPreparer ({local_ref:, remote_tracking:});
+          #   nil is valid only for dry runs
           # @param options [Hash] Options for creation
           # @return [Hash] Creation result
           #
           # @example
           #   manager = WorktreeManager.new
-          #   pr_data = { number: 26, title: "Add feature", head_branch: "feature/auth" }
-          #   result = manager.create_pr(26, pr_data)
-          def create_pr(pr_number, pr_data, options = {})
-            return error_result("PR number is required") if pr_number.nil?
-            return error_result("PR data is required") if pr_data.nil?
+          #   checkout = preparer.prepare(evidence)
+          #   result = manager.create_pr(evidence, checkout)
+          def create_pr(evidence, checkout, options = {})
+            return error_result("PR evidence is required") if evidence.nil?
+
+            pr_number = evidence.number
+            pr_data = normalized_pr_data(evidence)
+            local_branch = preview_pr_branch(pr_data)
 
             # Check if worktree already exists for this PR's branch
-            head_branch = pr_data[:head_branch]
             existing = @worktree_lister.find_by_branch("pr-#{pr_number}") ||
-              @worktree_lister.find_by_branch(head_branch)
+              @worktree_lister.find_by_branch(local_branch) ||
+              @worktree_lister.find_by_branch(evidence.head_ref)
 
             if existing && !options[:force]
               return error_result("Worktree already exists at: #{existing.path}")
@@ -150,11 +156,15 @@ module Ace
               return dry_run_pr_creation(pr_number, pr_data, options)
             end
 
+            return error_result("Verified checkout is required for PR worktree creation") unless checkout
+
             # Create the worktree
             result = @worktree_creator.create_for_pr(
               pr_data,
               @config,
-              git_root: @project_root
+              git_root: @project_root,
+              source_ref: checkout[:local_ref],
+              remote_tracking: checkout[:remote_tracking]
             )
 
             if result[:success]
@@ -554,6 +564,40 @@ module Ace
 
           # Create error result
           #
+          # Convert normalized PR evidence into the internal pr_data naming
+          # format used by configuration templates.
+          #
+          # @param evidence [Ace::Git::ProviderPullRequest]
+          # @return [Hash] {number:, title:, head_branch:, base_branch:}
+          def normalized_pr_data(evidence)
+            {
+              number: evidence.number,
+              title: evidence.title,
+              head_branch: evidence.head_ref,
+              base_branch: evidence.base_ref
+            }
+          end
+
+          # Preview the configured local branch name for a PR worktree.
+          #
+          # @param pr_data [Hash] normalized PR data
+          # @return [String] formatted branch name
+          def preview_pr_branch(pr_data)
+            pr_config = @config.pr_config || {}
+            branch_format = pr_config[:branch_format] || "pr-{number}-{slug}"
+            require_relative "../atoms/slug_generator"
+
+            result = branch_format.dup
+            result.gsub!("{number}", pr_data[:number].to_s)
+            if pr_data[:title]
+              slug = Atoms::SlugGenerator.from_title(pr_data[:title])
+              result.gsub!("{slug}", slug)
+              result.gsub!("{title_slug}", slug)
+            end
+            result.gsub!("{base_branch}", pr_data[:base_branch].to_s) if pr_data[:base_branch]
+            result
+          end
+
           # Dry run PR worktree creation
           #
           # @param pr_number [Integer] PR number

data/lib/ace/git/worktree/version.rb

@@ -3,7 +3,7 @@
 module Ace
   module Git
     module Worktree
-      VERSION = "0.23.0"
+      VERSION = "0.24.1"
     end
   end
 end

data/lib/ace/git/worktree.rb

@@ -190,7 +190,9 @@ module Ace
 
       require_relative "worktree/molecules/config_loader"
       require_relative "worktree/molecules/task_fetcher"
-      require_relative "worktree/molecules/pr_creator"
+      require_relative "worktree/molecules/pull_request_creator"
+      require_relative "worktree/molecules/pull_request_evidence_resolver"
+      require_relative "worktree/molecules/pull_request_checkout_preparer"
       require_relative "worktree/molecules/task_committer"
       require_relative "worktree/molecules/task_pusher"
       require_relative "worktree/molecules/task_status_updater"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-git-worktree
 version: !ruby/object:Gem::Version
-  version: 0.23.0
+  version: 0.24.1
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-27 00:00:00.000000000 Z
+date: 2026-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
@@ -65,20 +65,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.24'
-- !ruby/object:Gem::Dependency
-  name: ace-git-github
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.1.1
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.1.1
 - !ruby/object:Gem::Dependency
   name: ace-task
   requirement: !ruby/object:Gem::Requirement
@@ -205,7 +191,9 @@ files:
 - lib/ace/git/worktree/molecules/current_task_linker.rb
 - lib/ace/git/worktree/molecules/hook_executor.rb
 - lib/ace/git/worktree/molecules/parent_task_resolver.rb
-- lib/ace/git/worktree/molecules/pr_creator.rb
+- lib/ace/git/worktree/molecules/pull_request_checkout_preparer.rb
+- lib/ace/git/worktree/molecules/pull_request_creator.rb
+- lib/ace/git/worktree/molecules/pull_request_evidence_resolver.rb
 - lib/ace/git/worktree/molecules/task_committer.rb
 - lib/ace/git/worktree/molecules/task_fetcher.rb
 - lib/ace/git/worktree/molecules/task_pusher.rb