ace-git-github 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 865ef273c3954eefcfd0742e3a2dc3b2e9a02aa2e93aef1f13888f02e128aea7
-  data.tar.gz: 0f6167a9930838246beafea1454ce56a1b68938c96c6be658308e3724130801d
+  metadata.gz: baa6f879ef34125b1099214ec6387d091ebbca80116f51c7ea4ea37fc9fc08a9
+  data.tar.gz: b7f37f202295ba924168e9b3e2f639c221bf93c63a8d2f6112a2fc243cdb8888
 SHA512:
-  metadata.gz: 0043d7965efda107ac27aa490b6e7e329b7dbc4a792c919fb3bca22e11aabcf406203cf8b8578d662c8aba582d045f197de3ad7a42dba45af24dafb008a3a001
-  data.tar.gz: c3c2f64ae9a1a463113bb49f6f453104d358161e9c94b35261327ea3368e787a795d7460f605769cf8f938d5b14569a8290cdb14617f5c309676fd34d5980839
+  metadata.gz: 1f49e0c270b7235b7db93ecbeebef80a78ca5a9791959fae5f13b3d6e06c29576583c8f6a270654ffb7815f0703e5be5aaf41cae1c2e123dc80167d4fcf4e1ce
+  data.tar.gz: 770eec189bf46c9502bc405fbf0e5b1258c154e3a49a1467df4479f71c2118d29a2910c9830e2d78c5fbeb81e3239fd1c824aefa78f4b8cad8a9e99a7fca3513

data/CHANGELOG.md

@@ -7,13 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-03
+
+### Added
+- GitHub issue tracking through the shared provider contract, including repository-bound lookup and mutation.
+
+### Fixed
+- Issue labels are looked up and created on demand before attachment (concurrent creations tolerated), and the label listing no longer sends the gh-incompatible `--slurp` + `--jq` combination.
+
 ## [0.3.0] - 2026-10-02
 
 ### Added
 - Repository-bound GitHub PR comment and review retrieval, comment create/update, and thread resolution through the shared provider contract.
 - Correlation-based comment reconciliation after uncertain posts and explicit malformed or unsupported result classification.
 
-
 ## [0.2.0] - 2026-09-28
 
 ### Added

data/lib/ace/git/github/provider.rb

@@ -76,7 +76,12 @@ module Ace
         #   to every data/mutation command so a `--server` selection can never
         #   be silently retargeted to the checkout's repository.
         def repo_target
-          @repo_target ||= Ace::Git::Atoms::ServerUrl.normalize(server.url)
+          # Issue operations talk to the HTTPS web endpoint derived from the
+          # configured URL; a plain normalize would carry an SSH-style
+          # host:port into gh --hostname/--repo.
+          @repo_target ||= Ace::Git::Atoms::ServerUrl.normalize(
+            Ace::Git::Atoms::ServerUrl.web_base(server.url)
+          )
         end
 
         # @return [ProviderPullRequest, nil] evidence for the branch's PR
@@ -116,16 +121,107 @@ module Ace
           normalize_issue(output)
         end
 
+        def issue_tracking(number:)
+          data = gh_json(["issue", "view", number.to_s, "--json", "number,title,state,author,url,labels"])
+          evidence = normalize_issue(data)
+          unless evidence.number.to_i == number.to_i && url_matches_server?(evidence.url, number)
+            raise Ace::Git::ProviderIdentityMismatchError, "Issue ##{number} is not in #{server.url}"
+          end
+          uri = URI.parse(Ace::Git::Atoms::ServerUrl.web_base(server.url))
+          owner_repo = uri.path.sub(%r{\A/}, "").chomp("/").sub(/\.git\z/, "")
+          pages = gh_json(["api", "repos/#{owner_repo}/issues/#{number}/comments", "--hostname", forge_hostname(uri),
+                           "--paginate", "--slurp"], bind_repo: false)
+            unless pages.is_a?(Array) && pages.all? { |page| page.is_a?(Array) }
+              raise Ace::Git::ProviderMalformedOutputError, "Malformed GitHub comment pagination for issue ##{number}"
+            end
+            {
+            issue: evidence,
+            comments: pages.flatten.map do |comment|
+              id = comment["id"]
+              raise Ace::Git::ProviderMalformedOutputError, "Issue comment has no API id" unless id.to_s.match?(/\A\d+\z/)
+
+              {id: id.to_i, body: comment["body"].to_s}
+            end,
+            labels: Array(data["labels"]).map { |label| label["name"].to_s }
+          }
+        end
+
+        def create_issue_comment(number:, body:)
+          issue_api("POST", "issues/#{number}/comments", fields: ["body=#{body}"])
+        end
+
+        def update_issue_comment(number:, comment_id:, body:)
+          assert_issue_comment_owned!(number, comment_id)
+          issue_api("PATCH", "issues/comments/#{Integer(comment_id)}", fields: ["body=#{body}"])
+        end
+
+        def delete_issue_comment(number:, comment_id:)
+          assert_issue_comment_owned!(number, comment_id)
+          issue_api("DELETE", "issues/comments/#{Integer(comment_id)}")
+        end
+
+        def add_issue_label(number:, label:)
+          ensure_repo_label(label)
+          issue_api("POST", "issues/#{number}/labels", fields: ["labels[]=#{label}"])
+        end
+
+        def remove_issue_label(number:, label:)
+          issue_api("DELETE", "issues/#{number}/labels/#{URI.encode_www_form_component(label)}")
+        end
+
+        def set_issue_state(number:, state:)
+          raise ArgumentError, "Invalid issue state #{state.inspect}" unless %i[open closed].include?(state)
+
+          issue_api("PATCH", "issues/#{number}", fields: ["state=#{state}"])
+        end
+
+        # Fresh repositories lack the tracking label: look it up and create
+        # it on demand BEFORE attaching, so linking cannot commit a tracking
+        # comment it could never label (mirrors the Forgejo provider). A
+        # concurrent creator surfaces as a failed create whose re-list
+        # confirms the ensured state; any other lookup/create failure still
+        # surfaces through the attach call.
+        def ensure_repo_label(label)
+          uri = URI.parse(Ace::Git::Atoms::ServerUrl.web_base(server.url))
+          owner_repo = uri.path.sub(%r{\A/}, "").chomp("/").sub(/\.git\z/, "")
+          hostname = forge_hostname(uri)
+          return if label_exists?(owner_repo, hostname, label)
+
+          CliExecutor.execute("api", ["repos/#{owner_repo}/labels", "--hostname", hostname,
+            "--method", "POST", "--raw-field", "name=#{label}", "--raw-field", "color=0e8a16"],
+            timeout: timeout, runner: runner)
+          label_exists?(owner_repo, hostname, label)
+        end
+
+        def label_exists?(owner_repo, hostname, label)
+          # gh api rejects --slurp combined with --jq; per-page jq output is
+          # one name per line, which the line parse below handles.
+          result = CliExecutor.execute("api", ["repos/#{owner_repo}/labels?per_page=100", "--hostname", hostname,
+            "--paginate", "--jq", ".[].name"], timeout: timeout, runner: runner)
+          return false unless result[:success]
+
+          result[:stdout].to_s.lines.map(&:strip).include?(label)
+        rescue Ace::Git::Error
+          false
+        end
+
         # @return [Array<ProviderCheck>] normalized check evidence for a ref
         def checks(ref:)
           output = gh_json(["pr", "checks", ref.to_s, "--json", "name,state,bucket"])
           output.map do |check|
+            state = check["state"].to_s.downcase
+            raise Ace::Git::ProviderMalformedOutputError,
+              "Malformed GitHub check entry: missing state" if state.empty?
             bucket = check["bucket"].to_s.downcase
+            unless bucket.empty? || BUCKET_MAP.key?(bucket)
+              raise Ace::Git::ProviderMalformedOutputError,
+                "Malformed GitHub check entry: unrecognized bucket #{bucket}"
+            end
             Ace::Git::ProviderCheck.new(
               server_name: server.name,
               name: check["name"].to_s,
-              state: check["state"].to_s.downcase.to_sym,
-              conclusion: BUCKET_MAP.fetch(bucket, bucket.empty? ? nil : bucket.to_sym),
+              state: state.to_sym,
+              conclusion: BUCKET_MAP.fetch(bucket, nil),
               url: nil
             )
           end
@@ -341,10 +437,18 @@ end
             raise Ace::Git::ProviderMalformedOutputError, "Incomplete GitHub PR check evidence"
           end
           checks = runs.map do |run|
+            status = run["status"].to_s.downcase
+            raise Ace::Git::ProviderMalformedOutputError,
+              "Malformed GitHub check run entry: missing status" if status.empty?
+            conclusion = run["conclusion"]
+            unless conclusion.nil? || conclusion.is_a?(String)
+              raise Ace::Git::ProviderMalformedOutputError,
+                "Malformed GitHub check run entry: conclusion must be a string or null"
+            end
             Ace::Git::ProviderCheck.new(
               server_name: server.name, name: run["name"],
-              state: run["status"].to_s.downcase.to_sym,
-              conclusion: run["conclusion"]&.downcase&.to_sym,
+              state: status.to_sym,
+              conclusion: conclusion&.downcase&.to_sym,
               url: run["html_url"]
             )
           end
@@ -443,7 +547,7 @@ end
           end
           begin
             matches = matching_review_comments(pr, marker, expected_head)
-          rescue Ace::Git::ProviderMalformedOutputError, Ace::Git::ProviderUnreachableError => e
+          rescue Ace::Git::ProviderMalformedOutputError, Ace::Git::ProviderAuthenticationError, Ace::Git::ProviderObjectNotFoundError, Ace::Git::ProviderUnreachableError => e
             raise Ace::Git::ProviderUnknownOutcomeError,
               "PR comment sent but reconciliation read failed for session #{correlation}: #{e.message}; reconcile before repeating"
           end
@@ -494,7 +598,7 @@ end
             # valid GET item endpoints) and validate its PR identity.
             begin
               updated = gh_api(update_route)
-            rescue Ace::Git::ProviderMalformedOutputError, Ace::Git::ProviderUnreachableError => e
+            rescue Ace::Git::ProviderMalformedOutputError, Ace::Git::ProviderAuthenticationError, Ace::Git::ProviderObjectNotFoundError, Ace::Git::ProviderUnreachableError => e
               raise Ace::Git::ProviderUnknownOutcomeError,
                 "Comment update sent but verification read failed for comment #{comment_id}: #{e.message}; reconcile before repeating"
             end
@@ -530,7 +634,7 @@ end
             }
           GRAPHQL
           thread = gh_graphql(query, id: thread_id).dig("data", "node")
-          verify_review_thread!(thread, pr, expected_head)
+          verify_review_thread!(thread, pr, expected_head, thread_id: thread_id)
           if thread["isResolved"] == true
             verify_post_mutation_head!(pr, expected_head, "thread #{thread_id}")
             return true
@@ -556,7 +660,7 @@ end
               "head #{expected_head}, thread #{thread_id}: #{e.message}"
           end
           begin
-            verify_review_thread!(resolved, pr, expected_head)
+            verify_review_thread!(resolved, pr, expected_head, thread_id: thread_id)
           rescue Ace::Git::ProviderIdentityMismatchError, Ace::Git::ProviderMalformedOutputError, Ace::Git::ProviderExpectedHeadConflictError => e
             raise Ace::Git::ProviderUnknownOutcomeError,
               "Thread resolution sent but confirmation unreadable for #{server.name}/#{pr.number}, thread #{thread_id}: #{e.message}; reconcile before repeating"
@@ -662,13 +766,17 @@ end
             "Cannot post review comment to PR ##{pr.number} in #{pr.state} state"
         end
 
-        def verify_review_thread!(thread, pr, expected_head)
+        def verify_review_thread!(thread, pr, expected_head, thread_id: nil)
           unless thread.is_a?(Hash) && thread["id"] && thread["pullRequest"].is_a?(Hash) &&
               thread.dig("pullRequest", "number") == pr.number &&
               Ace::Git::Atoms::ServerUrl.match?(thread.dig("pullRequest", "repository", "url"), server.url)
             raise Ace::Git::ProviderIdentityMismatchError,
               "GitHub review thread does not belong to selected PR ##{pr.number}"
           end
+          if thread_id && thread["id"] != thread_id
+            raise Ace::Git::ProviderIdentityMismatchError,
+              "GitHub returned thread #{thread["id"]} instead of #{thread_id}"
+          end
           unless thread.dig("pullRequest", "headRefOid") == expected_head
             raise Ace::Git::ProviderExpectedHeadConflictError,
               "GitHub review thread PR head changed before resolution"
@@ -699,7 +807,7 @@ end
         def verify_post_mutation_head!(pr, expected_head, correlation)
           current = begin
             pull_request(number: pr.number)
-          rescue Ace::Git::ProviderMalformedOutputError, Ace::Git::ProviderUnreachableError => e
+          rescue Ace::Git::ProviderMalformedOutputError, Ace::Git::ProviderAuthenticationError, Ace::Git::ProviderObjectNotFoundError, Ace::Git::ProviderUnreachableError => e
             raise Ace::Git::ProviderUnknownOutcomeError,
               "Head verification read failed after mutation for #{server.name}: #{e.message}; reconcile before repeating"
           end
@@ -739,35 +847,43 @@ end
 
         def matching_review_comments(pr, marker, head)
           gh_api_pages("issues/#{pr.number}/comments").filter_map do |entry|
-            next unless entry.is_a?(Hash) && entry["body"].is_a?(String) && entry["body"].include?(marker)
+            # Every row must be a valid comment; a row without a body
+      # means malformed collection and must not hide our session post.
+            unless entry.is_a?(Hash) && entry["body"].is_a?(String)
+              raise Ace::Git::ProviderMalformedOutputError, "Malformed GitHub PR comment collection"
+            end
+            next unless entry["body"].include?(marker)
 
             review_comment(entry, pr, head)
           end
         end
 
         def review_comment(entry, pr, head, threads = {})
+          user = entry.is_a?(Hash) ? entry["user"] : nil
           unless entry.is_a?(Hash) && entry["id"].is_a?(Integer) && entry["id"].positive? && entry["body"].is_a?(String) &&
-              entry.dig("user", "login").is_a?(String)
+              user.is_a?(Hash) && user["login"].is_a?(String)
             raise Ace::Git::ProviderMalformedOutputError, "Malformed GitHub PR comment evidence"
           end
           thread_id, resolved = threads[entry["id"]] || [nil, nil]
           Ace::Git::ProviderReviewComment.new(
             server_name: server.name, repository_url: server.url, pr_number: pr.number,
-            id: entry["id"], author: entry.dig("user", "login"), body: entry["body"],
+            id: entry["id"], author: user["login"], body: entry["body"],
             url: entry["html_url"], path: entry["path"], line: entry["line"],
-            head_sha: entry["commit_id"] || head, resolved: resolved, thread_id: thread_id
+            head_sha: entry["commit_id"], resolved: resolved, thread_id: thread_id
           )
         end
 
         def review_entry(entry, pr, head)
-          unless entry.is_a?(Hash) && entry["id"].is_a?(Integer) && entry["id"].positive? && entry.dig("user", "login").is_a?(String) &&
+          user = entry.is_a?(Hash) ? entry["user"] : nil
+          unless entry.is_a?(Hash) && entry["id"].is_a?(Integer) && entry["id"].positive? &&
+              user.is_a?(Hash) && user["login"].is_a?(String) &&
               entry["state"].is_a?(String) && !entry["state"].empty?
             raise Ace::Git::ProviderMalformedOutputError, "Malformed GitHub PR review evidence"
           end
           Ace::Git::ProviderReview.new(
             server_name: server.name, repository_url: server.url, pr_number: pr.number,
-            id: entry["id"], author: entry.dig("user", "login"), body: entry["body"],
-            state: entry["state"], url: entry["html_url"], head_sha: entry["commit_id"] || head
+            id: entry["id"], author: user["login"], body: entry["body"],
+            state: entry["state"], url: entry["html_url"], head_sha: entry["commit_id"]
           )
         end
 
@@ -862,6 +978,26 @@ end
           out
         end
 
+        def assert_issue_comment_owned!(number, comment_id)
+          return if issue_tracking(number: number)[:comments].any? { |comment| comment[:id].to_i == comment_id.to_i }
+
+          raise Ace::Git::ProviderIdentityMismatchError,
+            "Comment #{comment_id} is not on selected issue ##{number} in #{server.url}"
+        end
+
+        def issue_api(method, suffix, fields: [])
+          uri = URI.parse(Ace::Git::Atoms::ServerUrl.web_base(server.url))
+          owner_repo = uri.path.sub(%r{\A/}, "").chomp("/").sub(/\.git\z/, "")
+          args = ["repos/#{owner_repo}/#{suffix}", "--hostname", forge_hostname(uri), "--method", method]
+          fields.each { |field| args += ["--raw-field", field] }
+          result = CliExecutor.execute("api", args, timeout: timeout, runner: runner)
+          classify_failure(result[:stderr], context: "issue #{method} #{suffix}") unless result[:success]
+          result
+        rescue Ace::Git::ProviderUnreachableError => e
+          raise Ace::Git::ProviderUnknownOutcomeError,
+            "Unknown outcome for issue mutation on #{server.url} (#{suffix}): #{e.message}"
+        end
+
         STATE_ORDER = {open: 0, merged: 1, closed: 2}.freeze
 
         # Send one mutating `gh` command. When `ambiguous` is true (create),
@@ -974,10 +1110,38 @@ end
         def server_host_root
           @server_host_root ||= begin
             uri = URI.parse(server.url.to_s)
-            "#{uri.scheme || "https"}://#{uri.host}#{":#{uri.port}" if uri.port && uri.port != uri.default_port}"
+            "#{uri.scheme || "https"}://#{forge_hostname(uri)}"
+          end
+        end
+
+        # gh --hostname accepts "host:port"; a bare uri.host would silently
+        # retarget a port-configured server to the default authority.
+        # Issue evidence must match the configured server URL including its
+        # scheme; ServerUrl.match? intentionally ignores schemes for git
+        # remotes, but a web issue URL must not downgrade the authority.
+        def url_matches_server?(evidence_url, number)
+          expected = "#{Ace::Git::Atoms::ServerUrl.web_base(server.url)}/issues/#{number.to_i}"
+          return false unless evidence_url.to_s.chomp("/").casecmp?(expected)
+
+          configured = URI.parse(Ace::Git::Atoms::ServerUrl.web_base(server.url)).scheme
+          supplied = URI.parse(evidence_url.to_s).scheme
+          configured.nil? || supplied.nil? || configured.downcase == supplied.downcase
+        end
+
+        # Unrecognized or missing state is malformed evidence: mapping it to
+        # :closed would let sync close an issue without valid state proof.
+        def normalize_state(value)
+          case value.to_s.upcase
+          when "OPEN" then :open
+          when "CLOSED" then :closed
+          else raise Ace::Git::ProviderMalformedOutputError, "Unknown issue state #{value.inspect}"
           end
         end
 
+        def forge_hostname(uri)
+          uri.port && uri.port != uri.default_port ? "#{uri.host}:#{uri.port}" : uri.host
+        end
+
         def merged_at_of(data)
           data["mergedAt"]
         end
@@ -993,7 +1157,7 @@ end
             server_name: server.name,
             number: data["number"],
             title: data["title"],
-            state: data["state"].to_s.upcase == "OPEN" ? :open : :closed,
+            state: normalize_state(data["state"]),
             author: normalize_author(data["author"]),
             url: data["url"],
             labels: nil

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

@@ -3,7 +3,7 @@
 module Ace
   module Git
     module Github
-      VERSION = "0.3.0"
+      VERSION = "0.4.0"
     end
   end
 end

data/lib/ace/git/github.rb

@@ -6,7 +6,6 @@ require_relative "github/version"
 require_relative "github/cli_executor"
 require_relative "github/pr_identifier"
 require_relative "github/pr_fetcher"
-require_relative "github/issue_sync"
 require_relative "github/provider"
 
 module Ace

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-git-github
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-02 00:00:00.000000000 Z
+date: 2026-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-git
@@ -38,7 +38,6 @@ files:
 - Rakefile
 - lib/ace/git/github.rb
 - lib/ace/git/github/cli_executor.rb
-- lib/ace/git/github/issue_sync.rb
 - lib/ace/git/github/pr_fetcher.rb
 - lib/ace/git/github/pr_identifier.rb
 - lib/ace/git/github/provider.rb

data/lib/ace/git/github/issue_sync.rb

@@ -1,252 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-require "open3"
-
-module Ace
-  module Git
-    module Github
-      # Synchronize ACE task linkage metadata to GitHub issues.
-      class IssueSync
-        class OwnershipConflict < StandardError; end
-
-        STICKY_MARKER = "<!-- ace-task:tracked -->"
-        TRACKED_LABEL = "ace:tracked"
-        TERMINAL_STATUSES = %w[done completed shipped closed cancelled skipped archived].freeze
-
-        # True when GitHub sync can run: the gh CLI is installed and authenticated.
-        # GitHub sync is best-effort; callers skip it silently when this is false.
-        def self.available?
-          CliExecutor.authenticated?
-        end
-
-        def self.sync_task(task_id:, task_title:, task_status:, task_path:, issue_ids:, reason:, previous: nil,
-          current_issue_ids: nil)
-          current_ids = if current_issue_ids.nil?
-            Array(issue_ids).map(&:to_i).uniq
-          else
-            Array(current_issue_ids).map(&:to_i).uniq
-          end
-
-          issue_ids.each do |issue_id|
-            sync_issue(
-              issue_id: issue_id.to_i,
-              task_id: task_id,
-              task_title: task_title,
-              task_status: task_status,
-              task_path: task_path,
-              reason: reason,
-              previous: previous,
-              currently_linked: current_ids.include?(issue_id.to_i)
-            )
-          end
-
-          {success: true, synced: issue_ids.length, issues: issue_ids}
-        end
-
-        def self.sync_issue(issue_id:, task_id:, task_title:, task_status:, task_path:, reason:, previous:,
-          currently_linked:)
-          issue = fetch_issue(issue_id)
-          sticky = find_sticky_comment(issue["comments"] || [])
-
-          lines = tracked_lines(sticky&.dig("body"))
-          validate_link!(issue_id: issue_id, task_id: task_id, previous_task_id: previous&.[](:id), lines: lines) if currently_linked
-          lines = remove_previous_line(lines, previous)
-          lines = upsert_line(lines, task_id: task_id, task_title: task_title, task_path: task_path) if currently_linked
-          if lines.empty?
-            cleanup_tracking_artifacts(issue_id: issue_id, sticky: sticky, labels: issue["labels"] || [])
-            return {success: true, issue: issue_id, reason: reason}
-          end
-
-          body = render_body(lines)
-
-          if sticky
-            update_comment(issue_id: issue_id, comment: sticky, body: body)
-          else
-            create_comment(issue_id: issue_id, body: body)
-          end
-
-          ensure_label(issue_id, issue["labels"] || [])
-          if currently_linked
-            sync_lifecycle(
-              issue_id: issue_id,
-              issue_state: issue["state"],
-              task_status: task_status
-            )
-          end
-
-          {success: true, issue: issue_id, reason: reason}
-        end
-
-        def self.cleanup_tracking_artifacts(issue_id:, sticky:, labels:)
-          delete_comment(issue_id: issue_id, comment: sticky) if sticky
-          remove_label(issue_id, labels)
-        end
-
-        def self.fetch_issue(issue_id)
-          result = CliExecutor.execute("issue", ["view", issue_id.to_s, "--json", "state,comments,labels"])
-          raise "Failed to fetch issue #{issue_id}: #{result[:stderr]}" unless result[:success]
-
-          JSON.parse(result[:stdout])
-        rescue JSON::ParserError => e
-          raise "Failed to parse issue #{issue_id} response: #{e.message}"
-        end
-
-        def self.find_sticky_comment(comments)
-          comments.find { |comment| comment["body"].to_s.include?(STICKY_MARKER) }
-        end
-
-        def self.tracked_lines(body)
-          body.to_s.lines.map(&:rstrip).select { |line| line.start_with?("Tracked in ace-task: ") }
-        end
-
-        def self.remove_previous_line(lines, previous)
-          return lines unless previous.is_a?(Hash)
-
-          previous_id = previous[:id] || previous["id"]
-          return lines unless previous_id
-
-          lines.reject { |line| extract_task_id(line) == previous_id.to_s }
-        end
-
-        def self.upsert_line(lines, task_id:, task_title:, task_path:)
-          filtered = lines.reject { |line| extract_task_id(line) == task_id.to_s }
-          filtered << tracked_line(task_id: task_id, task_title: task_title, task_path: task_path)
-          filtered.uniq.sort
-        end
-
-        def self.tracked_line(task_id:, task_title:, task_path:)
-          "Tracked in ace-task: [#{task_id}](#{task_url(task_path)})"
-        end
-
-        def self.extract_task_id(line)
-          match = line.match(/\[([^\]]+)\]\(/)
-          match ? match[1] : nil
-        end
-
-        def self.render_body(lines)
-          ([STICKY_MARKER] + lines).join("\n")
-        end
-
-        def self.create_comment(issue_id:, body:)
-          CliExecutor.execute("issue", ["comment", issue_id.to_s, "--body", body]).tap do |result|
-            raise "Failed to create sticky comment for issue #{issue_id}: #{result[:stderr]}" unless result[:success]
-          end
-        end
-
-        def self.update_comment(issue_id:, comment:, body:)
-          comment_id = comment_api_id(comment)
-          CliExecutor.execute("api", [
-            "repos/{owner}/{repo}/issues/comments/#{comment_id}",
-            "--method", "PATCH",
-            "--field", "body=#{body}"
-          ]).tap do |result|
-            raise "Failed to update sticky comment for issue #{issue_id}: #{result[:stderr]}" unless result[:success]
-          end
-        end
-
-        def self.delete_comment(issue_id:, comment:)
-          comment_id = comment_api_id(comment)
-          CliExecutor.execute("api", [
-            "repos/{owner}/{repo}/issues/comments/#{comment_id}",
-            "--method", "DELETE"
-          ]).tap do |result|
-            raise "Failed to delete sticky comment for issue #{issue_id}: #{result[:stderr]}" unless result[:success]
-          end
-        end
-
-        def self.comment_api_id(comment)
-          database_id = comment["databaseId"] || comment[:databaseId]
-          return database_id.to_s if database_id.to_s.match?(/\A\d+\z/)
-
-          url = comment["url"] || comment[:url]
-          return Regexp.last_match(1) if url.to_s.match(/issuecomment-(\d+)/)
-
-          (comment["id"] || comment[:id]).to_s
-        end
-
-        def self.ensure_label(issue_id, labels)
-          return if labels.any? { |label| label["name"] == TRACKED_LABEL }
-
-          result = CliExecutor.execute("issue", ["edit", issue_id.to_s, "--add-label", TRACKED_LABEL])
-          raise "Failed to add #{TRACKED_LABEL} label to issue #{issue_id}: #{result[:stderr]}" unless result[:success]
-        end
-
-        def self.remove_label(issue_id, labels)
-          return unless labels.any? { |label| label["name"] == TRACKED_LABEL }
-
-          result = CliExecutor.execute("issue", ["edit", issue_id.to_s, "--remove-label", TRACKED_LABEL])
-          raise "Failed to remove #{TRACKED_LABEL} label from issue #{issue_id}: #{result[:stderr]}" unless result[:success]
-        end
-
-        def self.validate_link!(issue_id:, task_id:, previous_task_id: nil, lines: nil)
-          issue = fetch_issue(issue_id)
-          sticky = find_sticky_comment(issue["comments"] || [])
-          lines ||= tracked_lines(sticky&.dig("body"))
-          owners = lines.map { |line| extract_task_id(line) }.compact.uniq
-          return true if owners.empty?
-          return true if owners == [task_id.to_s]
-          return true if previous_task_id && owners == [previous_task_id.to_s]
-
-          raise OwnershipConflict, "GitHub issue ##{issue_id} is already owned by task #{owners.first}"
-        end
-
-        def self.sync_lifecycle(issue_id:, issue_state:, task_status:)
-          terminal = TERMINAL_STATUSES.include?(task_status.to_s.downcase)
-          issue_open = issue_state.to_s.upcase == "OPEN"
-
-          if terminal && issue_open
-            close_result = CliExecutor.execute("issue", ["close", issue_id.to_s])
-            raise "Failed to close issue #{issue_id}: #{close_result[:stderr]}" unless close_result[:success]
-          elsif !terminal && !issue_open
-            reopen_result = CliExecutor.execute("issue", ["reopen", issue_id.to_s])
-            raise "Failed to reopen issue #{issue_id}: #{reopen_result[:stderr]}" unless reopen_result[:success]
-          end
-        end
-
-        def self.task_url(task_path)
-          return task_path.to_s if task_path.to_s.empty?
-
-          repo_root = repo_root_path
-          relative = if repo_root && task_path.start_with?(repo_root + "/")
-            task_path.delete_prefix(repo_root + "/")
-          else
-            task_path.to_s
-          end
-
-          repo_slug = github_repo_slug
-          return relative unless repo_slug
-
-          "https://github.com/#{repo_slug}/blob/HEAD/#{relative}"
-        end
-
-        def self.repo_root_path
-          stdout, _stderr, status = Open3.capture3("git", "rev-parse", "--show-toplevel")
-          return nil unless status.success?
-
-          stdout.strip
-        rescue
-          nil
-        end
-
-        def self.github_repo_slug
-          stdout, _stderr, status = Open3.capture3("git", "remote", "get-url", "origin")
-          return nil unless status.success?
-
-          url = stdout.strip
-          return Regexp.last_match(1) if url.match(%r{github\.com[:/](.+?)(?:\.git)?$})
-
-          nil
-        rescue
-          nil
-        end
-
-        private_class_method :sync_issue, :fetch_issue, :find_sticky_comment, :tracked_lines, :remove_previous_line,
-          :upsert_line, :tracked_line, :extract_task_id, :render_body, :create_comment, :update_comment, :delete_comment,
-          :comment_api_id, :ensure_label, :remove_label, :cleanup_tracking_artifacts, :sync_lifecycle, :task_url, :repo_root_path,
-          :github_repo_slug
-      end
-
-    end
-  end
-end