ace-git 0.25.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '089e377ec56099fb872544bfc754f6f95f00ecaf157715ecad93e726e9c8960f'
-  data.tar.gz: 35bb8b556655c0ef1804fb2fe26039dd182115e558127254c49e17da9ce3f1ba
+  metadata.gz: 8f05486971c36b968a3eeeb42f4bfdeda24b0a3d672732dd5ff532ab4a7db034
+  data.tar.gz: 21fe708e731585aba811f719acc8705b906b2c2e11cf249f9d5279223890ea69
 SHA512:
-  metadata.gz: c156b7e8b123f15f9d305d27933d68de72d640e16a803a9d7b5ce2cce12c1c7cf537bb7e6ae31e7c8ca044999869160ccf835281fdcc51e3bee76589cd43363f
-  data.tar.gz: 4eaeac69d71391c491718c68e68e1599a0a3e1991eae4a25d3e4e2a922959ef13e940c7d863eae01478a78ae9f81940a016fcac46da27ee7bbdf427f64527a03
+  metadata.gz: a4439500ea545b8c557af9e6b436852b14bebec56f4e44b4f36c72c005851d72d29256cef3a70fcff6de50900bc2e101d5f55ef93a7b48c850b69c200157ddca
+  data.tar.gz: 705d2d95b952af1c2bd44a8da79b1173210b00313744c3dbd554b9d22d76983534b5db3552655a8fd797584accc4c774b205bb5710cb8e8b0fd61ddddf0fc80e

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.27.0] - 2026-10-03
+
+### Added
+- Forge-neutral issue tracking contract with named-server selection, normalized issue evidence, and classified provider failures.
+
+### Fixed
+- Scheme-less server URLs with numeric ports (forge.example:8443/owner/repo) keep the port in the derived web endpoint instead of parsing it as an scp-style repo path.
+
+## [0.26.0] - 2026-10-02
+
+### Added
+- Normalized PR comment and review evidence, comment mutation receipts, and guarded review snapshots with exact repository and head identity.
+- Recheck PR heads around collection and before review comments or thread mutations; classify unsupported capabilities and uncertain post outcomes.
+
 ## [0.25.0] - 2026-09-28
 
 ### Added

data/docs/usage.md

@@ -282,10 +282,14 @@ the provider contract (`Ace::Git::Providers::Base`), and normalized evidence typ
 provider packages own all forge CLI behavior:
 
 - **ace-git-github** - GitHub behavior via the `gh` CLI (PR lookups, diffs, issue
-  synchronization). Registers under the `github` provider type.
+  tracking operations). Registers under the `github` provider type.
 - **ace-git-forgejo** - Forgejo behavior via the `fj` CLI. Registers under the
   `forgejo` provider type.
 
+Both providers implement the same issue-tracking contract (issue lookup, comment
+create/update/delete, label add/remove, state transitions) so task issue
+synchronization stays forge-neutral; `ace-task` owns the sync orchestration.
+
 Configure servers in `.ace/git.yml` (or project config) under `git.servers`, then
 resolve them by name, by default, or from a git remote URL. Every failure path is
 classified (missing CLI, unauthenticated, unreachable, malformed output, object

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

@@ -38,6 +38,46 @@ module Ace
           text.chomp("/").downcase
         end
 
+        # Derive the HTTP(S) web endpoint for a configured server URL.
+        # HTTPS/HTTP URLs keep their scheme and authority; SSH-style URLs
+        # (scp-style "git@host:path", "ssh://") map to https web endpoints.
+        #
+        # @param url [String] configured server URL
+        # @return [String] web base without trailing slash or .git suffix
+        def self.web_base(url)
+          text = url.to_s.strip
+          scheme = text[/\A(https?):\/\//i, 1]&.downcase
+          rest = text.sub(/\A[a-z][a-z0-9+.\-]*:\/\//i, "").sub(/\A[^\/\s]+@/, "")
+          if scheme
+            authority, _, path = rest.partition("/")
+          elsif text.match?(/\Assh:\/\//i)
+            # ssh:// URLs separate the authority (with optional port) by slash.
+            rest = text.sub(/\Assh:\/\//i, "").sub(/\A[^\/\s]+@/, "")
+            authority, _, path = rest.partition("/")
+            authority = authority.split(":").first.to_s
+            scheme = "https"
+          else
+            host_part, sep, remainder = rest.partition(":")
+            if sep == ":" && remainder.match?(%r{\A\d+/})
+              # A numeric segment before the slash is an SSH-style port, not
+              # an scp repo path: keep it in the web authority.
+              authority = "#{host_part}:#{remainder.split("/", 2).first}"
+              path = remainder.split("/", 2).last
+            elsif sep == ":" && !remainder.start_with?("/")
+              # scp-style "git@host:path"; ssh ports ride the colon and are
+              # dropped from the web endpoint.
+              authority = host_part.split(":").first.to_s
+              path = remainder.sub(%r{\A\d+/}, "")
+            else
+              # Scheme-less "host/owner/repo" splits on the first slash.
+              authority, _, path = rest.partition("/")
+            end
+            scheme = "https"
+          end
+          path = path.sub(%r{/+\z}, "").sub(/\.git\z/i, "")
+          "#{scheme}://#{authority}/#{path}"
+        end
+
         # Compare a configured server URL against a remote URL for identity.
         #
         # @param server_url [String] configured server base URL

data/lib/ace/git/errors.rb

@@ -78,5 +78,10 @@ module Ace
     # failure after the send). Contains the exact base/head identity needed to
     # reconcile by lookup; never retried automatically.
     class ProviderUnknownOutcomeError < Error; end
+
+    # Reconciliation reads all completed and the tracked marker never
+    # appeared: authoritative absence of a prior create. The only outcome
+    # that may authorize a fresh create POST.
+    class ProviderReconcileAbsenceError < ProviderUnknownOutcomeError; end
   end
 end

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

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+module Ace
+  module Git
+    module Organisms
+      # One ACE task owns at most one exact remote issue. The provider handles
+      # transport; this service owns only the marker, label, and task lifecycle.
+      class IssueTracking
+        STICKY_MARKER = "<!-- ace-task:tracked -->"
+        RECONCILE_READ_ATTEMPTS = 3
+        RECONCILE_READ_INTERVAL_SECONDS = 1
+        CREATE_RECONCILE_READ_ATTEMPTS = 5
+        CREATE_RECONCILE_READ_INTERVAL_SECONDS = 2
+        TRACKED_LABEL = "ace:tracked"
+        TERMINAL_STATUSES = %w[done cancelled skipped].freeze
+
+        def initialize(provider:)
+          @provider = provider
+        end
+
+        def validate_link!(number:, task_id: nil, previous_task_id: nil)
+          snapshot = fetch(number)
+          owners = owned_task_ids(snapshot)
+          if sticky_comment(snapshot) && owners.empty?
+            raise ProviderMalformedOutputError, "Issue ##{number} has an ACE marker without a task owner"
+          end
+          accepted = [task_id, previous_task_id].compact.map(&:to_s).uniq
+          return snapshot if owners.empty? || (!accepted.empty? && owners.all? { |owner| accepted.include?(owner) })
+
+          raise ProviderIdentityMismatchError,
+            "Issue ##{number} is already owned by ACE task #{owners.join(', ')}"
+        end
+
+        def sync(number:, task_id:, task_link:, task_status:, previous_task_id: nil,
+          create_pending: false, before_create: nil, comment_only: false)
+          # Reparenting/promotion changes the local ID; the remote marker may
+          # still name the previous ID, or may already carry the new one when
+          # a prior sync failed partway. Both count as this task's ownership.
+          snapshot = validate_link!(number: number, task_id: task_id, previous_task_id: previous_task_id)
+          sticky = sticky_comment(snapshot)
+          desired_line = "Tracked in ace-task: [#{task_id}](#{task_link})"
+          desired_body = compose_tracking_body(sticky&.dig(:body), desired_line)
+          if sticky.nil?
+            if create_pending
+              # A prior create ended with an unknown outcome: this replay must
+              # reconcile (bounded extended reads), never issue a second POST.
+              resolved = CREATE_RECONCILE_READ_ATTEMPTS.times.any? do |attempt|
+                snapshot = fetch(number)
+                found = sticky_comment(snapshot)
+                break true if found&.[](:body) == desired_body
+
+                if found
+                  # The marker that just appeared may belong to another task
+                  # or be malformed; validate ownership before overwriting
+                  # anything (same guard as validate_link!).
+                  owners = owned_task_ids(snapshot)
+                  accepted = [task_id, previous_task_id].compact.map(&:to_s).uniq
+                  if (found && owners.empty?) || !owners.all? { |owner| accepted.include?(owner) }
+                    raise ProviderIdentityMismatchError,
+                      "Issue ##{number} is already owned by ACE task #{owners.join(', ')}"
+                  end
+                  desired_line = "Tracked in ace-task: [#{task_id}](#{task_link})"
+                  reconciled_body = compose_tracking_body(found[:body], desired_line)
+                  desired_body = reconciled_body
+                  mutate_and_reconcile(number, desired_body: reconciled_body) do
+                    @provider.update_issue_comment(number: number, comment_id: found[:id], body: reconciled_body)
+                  end
+                  break true
+                end
+                sleep(create_reconcile_interval(attempt))
+                false
+              end
+              raise ProviderReconcileAbsenceError,
+                "Prior tracking comment create for issue ##{number} is still unresolved" unless resolved
+            else
+              mutate_and_reconcile(number, desired_body: desired_body) do
+                # Persist the uncertain-create guard before the only
+                # non-idempotent call, so a stop after the POST leaves a
+                # durable reconcile record instead of a duplicate on replay.
+                before_create&.call
+                @provider.create_issue_comment(number: number, body: desired_body)
+              end
+            end
+          elsif sticky[:body] != desired_body
+            mutate_and_reconcile(number, desired_body: desired_body) do
+              @provider.update_issue_comment(number: number, comment_id: sticky[:id], body: desired_body)
+            end
+          end
+          verified = nil
+          unless comment_only
+            begin
+              snapshot = fetch(number)
+              unless snapshot[:labels].include?(TRACKED_LABEL)
+                mutate_and_reconcile(number, label: TRACKED_LABEL) do
+                  @provider.add_issue_label(number: number, label: TRACKED_LABEL)
+                end
+              end
+              desired_state = TERMINAL_STATUSES.include?(task_status.to_s) ? :closed : :open
+              snapshot = fetch(number)
+              unless snapshot[:issue].state == desired_state
+                mutate_and_reconcile(number, state: desired_state) do
+                  @provider.set_issue_state(number: number, state: desired_state)
+                end
+              end
+            rescue ProviderAuthenticationError, ProviderObjectNotFoundError => e
+              # The non-idempotent comment POST already committed, so a later
+              # definitive-looking failure cannot prove the create failed.
+              # Replay must reconcile the committed marker, never re-POST.
+              raise ProviderUnknownOutcomeError,
+                "post-create step failed after the tracking comment committed: #{e.class}: #{e.message}"
+            end
+            verified = fetch(number)
+            unless sticky_comment(verified)&.[](:body) == desired_body &&
+                verified[:labels].include?(TRACKED_LABEL) && verified[:issue].state == desired_state
+              raise ProviderMalformedOutputError, "Issue ##{number} did not reflect ACE tracking updates"
+            end
+          else
+            verified = fetch(number)
+            unless sticky_comment(verified)&.[](:body) == desired_body
+              raise ProviderMalformedOutputError, "Issue ##{number} did not reflect ACE tracking updates"
+            end
+          end
+          verified
+        end
+
+        # Clear only the task's marker/comment and ACE label. Issue state is
+        # intentionally untouched, even when it was changed by prior sync.
+        def clear(number:, task_id:, previous_task_id: nil)
+          snapshot = fetch(number)
+          owners = owned_task_ids(snapshot)
+          sticky = sticky_comment(snapshot)
+          if sticky && owners.empty?
+            raise ProviderMalformedOutputError, "Issue ##{number} has an ACE marker without a task owner"
+          end
+          accepted = [task_id, previous_task_id].compact.map(&:to_s).uniq
+          unless owners.empty? || (!accepted.empty? && owners.all? { |owner| accepted.include?(owner) })
+            raise ProviderIdentityMismatchError, "Issue ##{number} is owned by another ACE task"
+          end
+          if sticky
+            # Strip inline markers concatenated onto note lines (historical
+            # layout) so the rebuilt body verifies marker-free.
+            preserved = sticky[:body].to_s.lines
+              .reject { |line| line.chomp == STICKY_MARKER || line.start_with?("Tracked in ace-task: ") }
+              .map { |line| line.gsub(STICKY_MARKER, "") }
+            mutate_and_reconcile(number, absent_comment: true) do
+              if preserved.empty?
+                @provider.delete_issue_comment(number: number, comment_id: sticky[:id])
+              else
+                @provider.update_issue_comment(number: number, comment_id: sticky[:id], body: preserved.join)
+              end
+            end
+          end
+          snapshot = fetch(number)
+          if snapshot[:labels].include?(TRACKED_LABEL)
+            mutate_and_reconcile(number, absent_label: TRACKED_LABEL) do
+              @provider.remove_issue_label(number: number, label: TRACKED_LABEL)
+            end
+          end
+          verified = fetch(number)
+          if sticky_comment(verified) || verified[:labels].include?(TRACKED_LABEL)
+            raise ProviderMalformedOutputError, "Issue ##{number} still contains ACE tracking artifacts"
+          end
+          verified
+        end
+
+        private
+
+        # Unrelated lines are preserved verbatim (including trailing
+        # whitespace); only ACE-owned lines are ever added or removed. A
+        # marker concatenated onto a note line (historical layout) is
+        # stripped in place so clear can rebuild the body cleanly.
+        def compose_tracking_body(existing_body, desired_line)
+          preserved = existing_body.to_s.lines
+            .reject { |line| line.chomp == STICKY_MARKER || line.start_with?("Tracked in ace-task: ") }
+            .map { |line| line.gsub(STICKY_MARKER, "") }
+          prefix = preserved.join
+          prefix += "\n" unless prefix.empty? || prefix.end_with?("\n")
+          "#{prefix}#{STICKY_MARKER}\n#{desired_line}"
+        end
+
+        def create_reconcile_interval(attempt)
+          CREATE_RECONCILE_READ_INTERVAL_SECONDS * (attempt + 1)
+        end
+
+        def fetch(number)
+          snapshot = @provider.issue_tracking(number: number)
+          unless snapshot.is_a?(Hash) && snapshot[:issue]&.number.to_i == number.to_i &&
+              snapshot[:comments].is_a?(Array) && snapshot[:labels].is_a?(Array)
+            raise ProviderMalformedOutputError, "Incomplete issue tracking evidence for ##{number}"
+          end
+          # Pagination across capped pages can repeat comments; dedupe by id
+          # so duplicate pages never read as multiple ACE tracking comments.
+          seen_ids = []
+          snapshot = snapshot.merge(
+            comments: snapshot[:comments].reject do |comment|
+              if seen_ids.include?(comment[:id])
+                true
+              else
+                seen_ids << comment[:id]
+                false
+              end
+            end
+          )
+          snapshot
+        end
+
+        def sticky_comment(snapshot)
+          matches = snapshot[:comments].select { |comment| comment[:body].to_s.include?(STICKY_MARKER) }
+          if matches.length > 1
+            raise ProviderIdentityMismatchError, "Multiple ACE tracking comments on issue ##{snapshot[:issue].number}"
+          end
+          matches.first
+        end
+
+        def owned_task_ids(snapshot)
+          sticky = sticky_comment(snapshot)
+          return [] unless sticky
+
+          sticky[:body].to_s.lines.filter_map do |line|
+            line[/\ATracked in ace-task: \[([^\]]+)\]\(/, 1]
+          end.uniq
+        end
+
+        def mutate_and_reconcile(number, desired_body: nil, label: nil, state: nil,
+          absent_comment: false, absent_label: nil)
+          yield
+        rescue ProviderUnknownOutcomeError
+          begin
+            @reconcile_resolved = reconcile_outcome(number, desired_body: desired_body, label: label, state: state,
+              absent_comment: absent_comment, absent_label: absent_label)
+          rescue ProviderUnknownOutcomeError
+            raise
+          rescue StandardError => e
+            # The mutation outcome is still unknown when reconciliation reads
+            # fail (a 401/404 on a read says nothing about the write); keep
+            # the uncertainty so replay reconciles instead of duplicating.
+            raise ProviderUnknownOutcomeError,
+              "Mutation outcome unresolved; reconciliation read failed: #{e.class}"
+          end
+          raise unless @reconcile_resolved
+        end
+
+        def reconcile_outcome(number, desired_body: nil, label: nil, state: nil,
+          absent_comment: false, absent_label: nil)
+          resolved = RECONCILE_READ_ATTEMPTS.times.any? do |attempt|
+            snapshot = fetch(number)
+            outcome = if desired_body
+              sticky_comment(snapshot)&.[](:body) == desired_body
+            elsif label
+              snapshot[:labels].include?(label)
+            elsif state
+              snapshot[:issue].state == state
+            elsif absent_comment
+              sticky_comment(snapshot).nil?
+            elsif absent_label
+              !snapshot[:labels].include?(absent_label)
+            end
+            break outcome if outcome
+
+            # The forge may still be committing the write; an immediate read
+            # can miss it and a replay would then duplicate the mutation.
+            sleep(RECONCILE_READ_INTERVAL_SECONDS * (attempt + 1)) if desired_body
+            outcome
+          end
+          resolved
+        end
+      end
+    end
+  end
+end

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

@@ -45,6 +45,134 @@ module Ace
           provider_for(server).pull_request(number: reference.number)
         end
 
+        # Exact-head PR metadata without the diff/comment/check inventory.
+        # Delta resolution needs identity and base provenance only; pulling
+        # the full diff there would transfer it just to discard it.
+        def review_metadata_snapshot(identifier)
+          reference = parse_identifier(identifier)
+          server = resolve_server_for(reference)
+          provider = provider_for(server)
+          before = provider.pull_request(number: reference.number)
+          head = required_head!(before)
+          details = provider.pull_request_review_details(number: reference.number)
+          body_before = provider.pull_request_body(number: reference.number)
+          # Hydration is a remote read: build the metadata from the read that
+          # follows it, and re-read the body after — the task spec text lives
+          # in the body, so an edit between reads invalidates the collection.
+          after = provider.pull_request(number: reference.number)
+          body_after = provider.pull_request_body(number: reference.number)
+          if body_before != body_after
+            raise ProviderExpectedHeadConflictError,
+              "PR body changed while collecting review metadata; retry on the current head"
+          end
+          after = after.with(body: body_after) unless body_after.nil?
+          # Body hydration and identity must agree with the base provenance
+          # read before collection; a moved base invalidates the metadata.
+          latest_details = provider.pull_request_review_details(number: reference.number)
+          if after.head_sha != head || after.head_ref != before.head_ref ||
+              after.base_ref != before.base_ref || latest_details.base_sha != details.base_sha
+            raise ProviderExpectedHeadConflictError,
+              "PR head/base changed while collecting review metadata; retry on the current head"
+          end
+          ProviderReviewSnapshot.new(
+            provider: server.provider, pull_request: after,
+            base_sha: details.base_sha, files: details.files,
+            diff: nil, review_evidence: ProviderReviewEvidence.new(
+              server_name: server.name, repository_url: server.url,
+              pr_number: before.number, head_sha: head, comments: [], reviews: []
+            ),
+            checks: []
+          )
+        end
+
+        # Collect one complete review packet under an exact head/base guard.
+        # Provider failure is propagated; empty diff/comments remain valid
+        # evidence only after the full inventory and second read agree.
+        def review_snapshot(identifier, include_comments: true)
+          reference = parse_identifier(identifier)
+          server = resolve_server_for(reference)
+          provider = provider_for(server)
+          before = provider.pull_request(number: reference.number)
+          head = required_head!(before)
+          details = provider.pull_request_review_details(number: reference.number)
+          diff = provider.pull_request_diff(number: reference.number)
+          unless diff.is_a?(String)
+            raise ProviderMalformedOutputError, "PR diff is not text"
+          end
+          comments = if include_comments
+            provider.pull_request_review_evidence(number: reference.number, expected_head: head)
+          else
+            ProviderReviewEvidence.new(
+              server_name: server.name, repository_url: server.url,
+              pr_number: before.number, head_sha: head, comments: [], reviews: []
+            )
+          end
+          checks = provider.pull_request_checks(number: reference.number, head_sha: head)
+          # The CLI-parsed PR may omit the description; hydrate it from the
+          # provider's body capability when available (nil stays absence).
+          # Hydration is itself a remote read: the final identity comes from
+          # the read that follows it, so body and identity can never come
+          # from different points in time.
+          body_before = provider.pull_request_body(number: reference.number)
+          after = provider.pull_request(number: reference.number)
+          body_after = provider.pull_request_body(number: reference.number)
+          if body_before != body_after
+            raise ProviderExpectedHeadConflictError,
+              "PR body changed while collecting review evidence; retry on the current head"
+          end
+          after = after.with(body: body_after) unless body_after.nil?
+          latest_details = provider.pull_request_review_details(number: reference.number)
+          if after.head_sha != head || latest_details.base_sha != details.base_sha ||
+              after.head_ref != before.head_ref || after.base_ref != before.base_ref ||
+              after.head_repository_url != before.head_repository_url ||
+              after.base_repository_url != before.base_repository_url
+            raise ProviderExpectedHeadConflictError,
+              "PR head/base changed while collecting review evidence; retry on the current head"
+          end
+          unless details.files.is_a?(Array) && checks.is_a?(Array) &&
+              comments.head_sha == head && comments.pr_number == before.number
+            raise ProviderMalformedOutputError, "PR review evidence is incomplete or mismatched"
+          end
+          ProviderReviewSnapshot.new(
+            provider: server.provider, pull_request: after,
+            base_sha: details.base_sha, files: details.files,
+            diff: diff, review_evidence: comments, checks: checks
+          )
+        end
+
+        def post_review_comment(identifier, expected_head:, body:, correlation:)
+          reference = parse_identifier(identifier)
+          provider = provider_for(resolve_server_for(reference))
+          provider.create_pull_request_comment(
+            number: reference.number, expected_head: expected_head,
+            body: body, correlation: correlation
+          )
+        end
+
+        def update_review_comment(identifier, expected_head:, comment_id:, body:)
+          reference = parse_identifier(identifier)
+          provider = provider_for(resolve_server_for(reference))
+          provider.update_pull_request_comment(
+            number: reference.number, expected_head: expected_head,
+            comment_id: comment_id, body: body
+          )
+        end
+
+        def resolve_review_thread(identifier, expected_head:, thread_id:)
+          reference = parse_identifier(identifier)
+          provider = provider_for(resolve_server_for(reference))
+          provider.resolve_pull_request_thread(
+            number: reference.number, expected_head: expected_head,
+            thread_id: thread_id
+          )
+        end
+
+        def file_at_ref(identifier, path:, ref:)
+          reference = parse_identifier(identifier)
+          provider = provider_for(resolve_server_for(reference))
+          provider.repository_file(path: path, ref: ref)
+        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
@@ -106,8 +234,19 @@ module Ace
           )
         end
 
+        def resolved_server_url(identifier)
+          reference = parse_identifier(identifier)
+          resolve_server_for(reference).url
+        end
         private
 
+        def required_head!(pull_request)
+          head = pull_request.head_sha
+          return head if head.to_s.match?(/\A[0-9a-f]{40}\z/)
+
+          raise ProviderMalformedOutputError, "PR evidence is missing an exact head SHA"
+        end
+
         def parse_identifier(identifier)
           reference = Atoms::PrReference.parse(identifier)
           raise ArgumentError, "Invalid PR identifier: #{identifier}" unless reference
@@ -154,7 +293,11 @@ module Ace
           end
         end
 
+        # The forge server URL for a PR identifier, resolved on demand
+      # through the shared registry (pure resolution, no mutation).
+
         def provider_for(server)
+          @resolved_server_url = server.url
           Ace::Git::Providers.for(server, timeout: @timeout, runner: @runner)
         end
 

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

@@ -89,6 +89,37 @@ module Ace
           raise NotImplementedError, "Providers must implement #{self.class}#issue"
         end
 
+        # Read the exact issue and its comments/labels for task tracking.
+        # Returns {issue: ProviderIssue, comments: [{id:, body:}], labels: [String]}.
+        # Every mutation below is scoped to this provider's resolved server.
+        def issue_tracking(number:)
+          raise NotImplementedError, "Providers must implement #{self.class}#issue_tracking"
+        end
+
+        def create_issue_comment(number:, body:)
+          raise NotImplementedError, "Providers must implement #{self.class}#create_issue_comment"
+        end
+
+        def update_issue_comment(number:, comment_id:, body:)
+          raise NotImplementedError, "Providers must implement #{self.class}#update_issue_comment"
+        end
+
+        def delete_issue_comment(number:, comment_id:)
+          raise NotImplementedError, "Providers must implement #{self.class}#delete_issue_comment"
+        end
+
+        def add_issue_label(number:, label:)
+          raise NotImplementedError, "Providers must implement #{self.class}#add_issue_label"
+        end
+
+        def remove_issue_label(number:, label:)
+          raise NotImplementedError, "Providers must implement #{self.class}#remove_issue_label"
+        end
+
+        def set_issue_state(number:, state:)
+          raise NotImplementedError, "Providers must implement #{self.class}#set_issue_state"
+        end
+
         # Fetch check/CI status evidence for a reference.
         #
         # @param ref [String] commit sha or branch name
@@ -104,6 +135,50 @@ module Ace
           raise NotImplementedError, "Providers must implement #{self.class}#repository"
         end
 
+        # Collect normalized conversation comments, code comments and reviews
+        # for one exact PR head. A provider must reject malformed collections;
+        # an empty successful collection is represented by empty arrays.
+        def pull_request_review_evidence(number:, expected_head:)
+          raise NotImplementedError, "Providers must implement #{self.class}#pull_request_review_evidence"
+        end
+
+        # The PR description text when the provider can supply it; nil stays
+        # an honest absence for providers whose CLI surface omits the body.
+        def pull_request_body(number:)
+          nil
+        end
+
+        # The exact base SHA and complete file inventory used to prove that a
+        # review diff has not been silently truncated.
+        def pull_request_review_details(number:)
+          raise NotImplementedError, "Providers must implement #{self.class}#pull_request_review_details"
+        end
+
+        def pull_request_checks(number:, head_sha:)
+          raise NotImplementedError, "Providers must implement #{self.class}#pull_request_checks"
+        end
+
+        def repository_file(path:, ref:)
+          raise NotImplementedError, "Providers must implement #{self.class}#repository_file"
+        end
+
+        # Create a top-level PR comment. `correlation` is a stable session key
+        # embedded in the body so a retry can find exactly one prior send.
+        # A possible post-send transport failure raises ProviderUnknownOutcomeError.
+        def create_pull_request_comment(number:, expected_head:, body:, correlation:)
+          raise NotImplementedError, "Providers must implement #{self.class}#create_pull_request_comment"
+        end
+
+        def update_pull_request_comment(number:, expected_head:, comment_id:, body:)
+          raise NotImplementedError, "Providers must implement #{self.class}#update_pull_request_comment"
+        end
+
+        # Thread resolution is a separate capability. Unsupported providers
+        # must raise ProviderUnsupportedCapabilityError, never simulate success.
+        def resolve_pull_request_thread(number:, expected_head:, thread_id:)
+          raise NotImplementedError, "Providers must implement #{self.class}#resolve_pull_request_thread"
+        end
+
         # ---- PR lifecycle mutations ----
         #
         # Contract requirements (enforced by every provider implementation):

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

@@ -11,7 +11,7 @@ module Ace
     # Pull request state values: :open, :merged, :closed. Issue state values:
     # :open, :closed.
     ProviderPullRequest = Data.define(
-      :server_name, :number, :title, :state, :head_ref, :base_ref,
+      :server_name, :number, :title, :body, :state, :head_ref, :base_ref,
       :head_sha, :author, :url, :draft, :merged_at,
       :head_repository_url, :base_repository_url, :merge_commit_sha
     )
@@ -21,6 +21,33 @@ module Ace
     # Normalized check/CI evidence for one check run.
     ProviderCheck = Data.define(:server_name, :name, :state, :conclusion, :url)
 
+    # Comments keep the exact repository and PR identity supplied by the
+    # selected provider. A nil path/line denotes a conversation comment.
+    ProviderReviewComment = Data.define(
+      :server_name, :repository_url, :pr_number, :id, :author, :body,
+      :url, :path, :line, :head_sha, :resolved, :thread_id
+    )
+
+    ProviderReview = Data.define(
+      :server_name, :repository_url, :pr_number, :id, :author, :body,
+      :state, :url, :head_sha
+    )
+
+    ProviderReviewEvidence = Data.define(
+      :server_name, :repository_url, :pr_number, :head_sha, :comments, :reviews
+    )
+
+    ProviderReviewDetails = Data.define(:server_name, :repository_url, :pr_number, :base_sha, :files)
+
+    ProviderReviewSnapshot = Data.define(
+      :provider, :pull_request, :base_sha, :files, :diff, :review_evidence, :checks
+    )
+
+    ProviderReviewMutation = Data.define(
+      :server_name, :repository_url, :pr_number, :head_sha, :comment,
+      :idempotency
+    )
+
     # Normalized repository evidence.
     ProviderRepository = Data.define(:server_name, :full_name, :default_branch, :url)
 

data/lib/ace/git/server_registry.rb

@@ -129,7 +129,20 @@ module Ace
         # @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) }
+          supplied = repository_url.to_s
+          supplied_scheme = supplied[/\A([a-z][a-z0-9+.\-]*):\/\//i, 1]&.downcase
+          entries.map(&:server).select do |server|
+            # Compare the derived web endpoint so SSH clone URLs (including
+            # custom SSH ports) match their HTTPS issue URLs.
+            next false unless Atoms::ServerUrl.match?(Atoms::ServerUrl.web_base(server.url), supplied)
+            next true if supplied_scheme.nil?
+
+            # An explicit issue-URL scheme must not downgrade to a server
+            # serving the same host/path over a weaker scheme. SSH-configured
+            # clones serve their web endpoint over HTTPS.
+            server_scheme = Atoms::ServerUrl.web_base(server.url)[/\A(https?):\/\//i, 1]&.downcase
+            server_scheme == supplied_scheme
+          end
         end
 
         # Configured servers whose repository path equals `owner/repo`

data/lib/ace/git/version.rb

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

data/lib/ace/git.rb

@@ -222,6 +222,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/organisms/issue_tracking"
 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.25.0
+  version: 0.27.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-29 00:00:00.000000000 Z
+date: 2026-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-config
@@ -174,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/issue_tracking.rb
 - lib/ace/git/organisms/pull_request_lifecycle.rb
 - lib/ace/git/organisms/repo_status_loader.rb
 - lib/ace/git/providers.rb