ace-git 0.19.3 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6de57ed11849e98fe1955d76111319dc711368343272b6b2d80dd58bc6f65bef
-  data.tar.gz: d05cb9bacf11ef83814bf2f763c3e3904ac527a2a8c6aa2164be413861cbe208
+  metadata.gz: ee4112e17d169c530b00f45e0b6cc8f75e9ca439efdbf8ea091c57dce4511fdb
+  data.tar.gz: c9701d7158d7b5c181be4a718482db44ebc31e5efc26497f0c1546095d2fd908
 SHA512:
-  metadata.gz: eb44c158096edc47a8d49b30fceb7f0cad852ff655f630ac6a585fa962ef4b81d3d749639778ef29bb98148f74be599dfcd4e1f698b63de4e9bce7932c944347
-  data.tar.gz: aff4d087154edc8ecc6dc8f90d9ee2db4a0f00933860a0b8331d7624b0d5f71d9276d33830b6cda07f1ce3021dd502bdb14f7db697396055cc4bbeef0e5a0bca
+  metadata.gz: c3653b988dc194c2b756c5bf3d6176c5ae3a326de9c811c868353616235bf2eec64578ee0d13721de5698d98f9a48907b5d100602d4a9da48b2f22bc7f30c792
+  data.tar.gz: 46a393b19445eb2ec0cfde8cd62fbf5803d4ce5c3012eafa3d10d0486eead6a8017f7e95b463968ac7fe0b9fbca2da4f8ba03c092ed15be1c794fb0c02cf502a

data/CHANGELOG.md

@@ -7,6 +7,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.22.0] - 2026-04-15
+
+### Changed
+- Reworked `TS-GIT-001` E2E contracts to use scenario-owned setup, removed runner bootstrap/fallback recipes, and tightened PR verification to direct `ace-git pr` outcomes.
+- Added `TS-GIT-002-public-surface-smoke` with help and range-routing coverage to validate documented public CLI entrypoints.
+
+## [0.21.1] - 2026-04-13
+
+### Changed
+- Completed the batch i05 migration follow-through for this package and aligned it with the restarted `fast` / `feat` / `e2e` verification model.
+
+### Technical
+- Included in the coordinated assignment-driven patch release for batch i05 package updates.
+
+
+
+### Changed
+- Expanded `as-github-pr-create` canonical skill metadata so public `create-pr` assign-step discovery is skill-owned rather than catalog-owned.
+
+## [0.21.0] - 2026-04-12
+
+### Changed
+- Migrated package tests to the `fast` / `feat` / `e2e` model, moved deterministic coverage into `test/fast` and `test/feat`, and aligned TS-GIT-001 scenario artifacts with the current E2E runner/verifier contract.
+- Release workflow now normalizes target branch context and supports automatic PR/task source detection.
+## [0.20.2] - 2026-04-07
+
+### Added
+- Added shared GitHub issue sync primitives (`GhCliExecutor`, `GithubIssueSync`) for broader package reuse.
+
+### Fixed
+- Prevented cross-task GitHub issue ownership conflicts during sync and derived sticky-comment update/delete IDs from `gh issue view` URLs.
+
+## [0.20.1] - 2026-04-07
+
+### Fixed
+- Corrected sticky-comment mutation to derive the REST comment ID from GitHub issue comment URLs when `gh issue view` returns GraphQL node IDs, so linked issues continue closing cleanly on task archive/update.
+
+## [0.20.0] - 2026-04-07
+
+### Fixed
+- Reconciled removed/retargeted task issue links by honoring explicit current issue sets during sync so unlinked issues are cleaned without re-adding stale tracked lines or applying lifecycle actions.
+- Removed stale tracking artifacts when the last linked task is detached by deleting the sticky tracking comment and removing the `ace:tracked` label.
+- Switched tracked task links to `blob/HEAD` URLs so issue comments resolve against repositories whose default branch is not `main`.
+- Enforced one-owner issue sync semantics by rejecting attempts to link a GitHub issue already owned by a different ACE task.
+
+### Added
+- Added reusable GitHub issue sync primitives in `ace-git` (`GhCliExecutor` and `GithubIssueSync`) for shared ACE issue lifecycle integration.
+
+### Changed
+- Migrated `ace-review` GitHub CLI execution ownership to the shared `ace-git` executor boundary.
+- Simplified linked-issue lifecycle handling by treating each tracked GitHub issue as owned by exactly one ACE task.
+
 ## [0.19.3] - 2026-03-31
 
 ### Fixed

data/README.md

@@ -36,5 +36,14 @@
 
 **Coordinate with commit and worktree tools** - pair with [ace-git-commit](../ace-git-commit) for scoped commit authoring, [ace-git-worktree](../ace-git-worktree) for task-oriented worktree management, and [ace-bundle](../ace-bundle) for loading workflow instructions.
 
+## Testing Contract
+
+`ace-git` follows the restarted package test model:
+
+- `ace-test ace-git` for deterministic fast-loop coverage (`test/fast/`)
+- `ace-test ace-git feat` for deterministic feature/contract coverage (`test/feat/`)
+- `ace-test-e2e ace-git` for retained workflow scenarios (`test/e2e/`)
+- `ace-test ace-git all` for full package verification
+
 ---
 [Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md) | Part of [ACE](https://github.com/cs3b/ace)

data/docs/getting-started.md

@@ -79,6 +79,15 @@ Use this for preferences, not for redefining the workflow logic.
 | Show PR metadata | `ace-git pr` |
 | Show package version | `ace-git version` |
 
+## Run Package Tests
+
+Use the restarted package test model:
+
+- `ace-test ace-git` for deterministic fast-loop tests
+- `ace-test ace-git feat` for deterministic feature/contract tests
+- `ace-test-e2e ace-git` for retained workflow scenarios
+- `ace-test ace-git all` for complete package verification
+
 ## Next Steps
 
 - Load `wfi://github/pr/create` to open a structured PR workflow

data/docs/usage.md

@@ -236,7 +236,7 @@ diff:
 | `grouped_stats.layers` | Array | `["lib","test","handbook"]` | Preferred layer grouping order |
 | `grouped_stats.collapse_above` | Integer | `5` | Collapse markdown groups above this file count |
 | `grouped_stats.show_full_tree` | String | `collapsible` | Tree rendering strategy hint |
-| `grouped_stats.dotfile_groups` | Array | `[".ace-taskflow",".ace"]` | Dot-directories to prioritize in grouping |
+| `grouped_stats.dotfile_groups` | Array | `[".ace-task",".ace"]` | Dot-directories to prioritize in grouping |
 
 **Default exclude_patterns** (from `.ace-defaults/git/config.yml`):
 - Lock files: `**/*.lock`, `package-lock.json`, `yarn.lock`, `Gemfile.lock`
@@ -251,9 +251,27 @@ Note: `test/**/*` and `spec/**/*` are NOT excluded by default - test changes are
 - `0` - Success
 - `1` - Error (configuration error, git error, etc.)
 
+## Testing Contract
+
+`ace-git` uses the `fast` / `feat` / `e2e` model:
+
+- `ace-test ace-git` - default deterministic suite (`test/fast/`)
+- `ace-test ace-git feat` - deterministic feature/contract suite (`test/feat/`)
+- `ace-test-e2e ace-git` - scenario workflow suite (`test/e2e/`)
+- `ace-test ace-git all` - full package suite
+
 ## Related Tools
 
 - **ace-git-commit** - Smart git commit generation
 - **ace-git-worktree** - Git worktree management
 - **ace-bundle** - Load ACE workflow instructions directly
 - **ace-nav** - Discover workflow and template protocol paths
+
+## Reusable GitHub Issue Primitives
+
+`ace-git` also exposes reusable library primitives for issue synchronization flows used by other ACE packages:
+
+- `Ace::Git::Molecules::GhCliExecutor` - shared `gh` command execution with timeout and auth/install error handling
+- `Ace::Git::Molecules::GithubIssueSync.sync_task(...)` - sticky comment upsert, `ace:tracked` label management, and close/reopen lifecycle actions
+
+These are intended for package integrations such as `ace-task` and are not invoked directly through `ace-git` CLI commands.

data/handbook/guides/version-control-system-git.g.md

@@ -19,9 +19,9 @@ This guide provides comprehensive documentation for Git-specific version control
 
 This project uses a **mono-repo architecture** with all packages at the repository root:
 
-- **ace-*/**: Ruby gems for specific functionality (ace-git, ace-taskflow, ace-docs, etc.)
+- **ace-*/**: Ruby gems for specific functionality (ace-git, ace-task, ace-docs, etc.)
 - **docs/**: Project documentation and architecture decisions
-- **.ace-taskflow/**: Task management and release coordination
+- **.ace-task/**: Task management and release coordination
 - **_legacy/**: Archived content from previous multi-repo structure
 
 #### Common Git Commands

data/handbook/skills/as-git-rebase/SKILL.md

@@ -25,15 +25,16 @@ integration:
 assign:
   source: wfi://git/rebase
   steps:
-    - name: rebase-with-main
-      description: Rebase current branch onto origin/main while preserving changelog intent
-      intent:
-        phrases:
-          - "rebase with main"
-          - "rebase with origin main"
-          - "rebase onto main"
-          - "sync with main"
-      tags: [git, history, rebase]
+  - name: rebase-with-target
+    description: Rebase current branch onto the target branch
+    intent:
+      phrases:
+        - "rebase with target branch"
+        - "rebase with main"
+        - "rebase with origin main"
+        - "rebase onto main"
+        - "sync with main"
+    tags: [git, history, rebase]
 skill:
   kind: workflow
   execution:

data/handbook/skills/as-github-pr-create/SKILL.md

@@ -25,7 +25,6 @@ integration:
         context: fork
         model: haiku
 assign:
-  source: wfi://github/pr/create
   steps:
     - name: create-pr
       description: Create a pull request for the implemented changes
@@ -35,6 +34,19 @@ assign:
           - "create a pr"
           - "open pr"
           - "open pull request"
+      prerequisites:
+        - name: work-on-task
+          strength: required
+          reason: "Must have code changes to create a PR"
+      produces: [pull-request]
+      consumes: [code-changes, commits]
+      context:
+        default: null
+        reason: "PR creation needs access to git state in main context"
+      when_to_skip:
+        - "PR already exists for this branch"
+        - "Changes don't warrant a PR (e.g., direct push allowed)"
+      effort: light
       tags: [git, pr, publishing]
 skill:
   kind: workflow

data/handbook/workflow-instructions/git/rebase.wf.md

@@ -5,6 +5,17 @@ purpose: Safe rebase workflow with state capture, explicit conflict triage, and
 ace-docs:
   last-updated: 2026-03-12
   last-checked: 2026-03-21
+bundle:
+  embed_document_source: true
+  params:
+    output: cache
+    timeout: 30
+    max_size: 81920
+  sections:
+    current_repository_status:
+      title: Current Repository Status
+      commands:
+        - ace-git status --format json
 ---
 
 # Rebase Workflow
@@ -35,28 +46,80 @@ Rebase feature branches against a target branch with automatic state capture for
 # $target_branch: Branch to rebase against (default: auto-detect or origin/main)
 # $no_verify: Skip post-rebase verification (default: false)
 
-# Helper: Auto-detect target branch from task spec or default to origin/main
-get_target_branch() {
+# Helper: Normalize a branch to an explicit remote ref
+normalize_target_ref() {
+  local branch
+  branch=$(printf '%s' "$1" | tr -d '[:space:]')
+
+  case "$branch" in
+    origin/*) echo "$branch" ;;
+    refs/heads/*) echo "origin/${branch#refs/heads/}" ;;
+    refs/remotes/origin/*) echo "${branch#refs/remotes/}" ;;
+    refs/remotes/*/*) echo "${branch#refs/remotes/}" ;;
+    "") echo "origin/main" ;;
+    *) echo "origin/$branch" ;;
+  esac
+}
+
+# Helper: Auto-detect target branch from task spec
+get_task_target_branch() {
   local task_file
   task_file=$(ls _current/*.s.md 2>/dev/null | head -1)
   if [ -n "$task_file" ] && [ -f "$task_file" ] && [ -r "$task_file" ]; then
     ruby -ryaml -e '
-      c = File.read(ARGV[0])
-      if c.start_with?("---")
-        yaml_content = c.split("---", 3)[1]
-        if yaml_content
-          data = YAML.safe_load(yaml_content, permitted_classes: [Symbol])
-          puts data.dig("worktree", "target_branch") || "origin/main"
-        else
-          puts "origin/main"
+      begin
+        c = File.read(ARGV[0])
+        if c.start_with?("---")
+          yaml_content = c.split("---", 3)[1]
+          if yaml_content
+            data = YAML.safe_load(yaml_content, permitted_classes: [Symbol])
+            worktree = data["worktree"] || data[:worktree]
+            next unless worktree.is_a?(Hash)
+            target = worktree["target_branch"] || worktree[:target_branch]
+            puts target if target
+          end
         end
-      else
-        puts "origin/main"
+      rescue
+        exit 0
       end
-    ' "$task_file" 2>/dev/null || echo "origin/main"
-  else
-    echo "origin/main"
+    ' "$task_file" 2>/dev/null
+  fi
+}
+
+# Helper: Auto-detect target branch from git context (`ace-git status`)
+get_status_target_branch() {
+  ace-git status --format json 2>/dev/null | ruby -rjson -e '
+    begin
+      data = JSON.parse(STDIN.read)
+      pr_metadata = data["pr_metadata"] || data[:pr_metadata]
+      if pr_metadata.is_a?(Hash)
+        base = pr_metadata["baseRefName"] || pr_metadata[:baseRefName]
+        base ||= pr_metadata["base"] || pr_metadata[:base]
+        puts base if base
+      end
+    rescue
+      exit 0
+    end
+  ' 2>/dev/null
+}
+
+# Helper: Auto-detect target branch from task spec/context or default to origin/main
+get_target_branch() {
+  local target_branch
+
+  target_branch="$(get_task_target_branch)"
+  if [ -n "$target_branch" ]; then
+    normalize_target_ref "$target_branch"
+    return
   fi
+
+  target_branch="$(get_status_target_branch)"
+  if [ -n "$target_branch" ]; then
+    normalize_target_ref "$target_branch"
+    return
+  fi
+
+  echo "origin/main"
 }
 
 # Helper: Recover session variables (for multi-shell workflows)
@@ -408,4 +471,4 @@ Target: {branch} | Commits: {count}
 Verification: {MATCH|MISMATCH} | Tests: {Pass|Fail}
 Reason: {no-conflicts|localized-conflict|repeated-conflicts|large-conflict-set|user-request}
 Status: {Complete|Needs attention}
-```
+```

data/handbook/workflow-instructions/github/pr/update.wf.md

@@ -31,7 +31,7 @@ If no PR exists for current branch, ask the user for the target PR number.
 
 ```bash
 gh pr view $pr_number --json baseRefName,headRefName,title
-ace-taskflow status
+ace-task status
 ```
 
 If taskflow context indicates a subtask and the PR targets `main`, retarget to the parent task branch before continuing.

data/lib/ace/git/models/diff_config.rb

@@ -39,7 +39,7 @@ module Ace
           grouped_stats_layers: %w[lib test handbook],
           grouped_stats_collapse_above: 5,
           grouped_stats_show_full_tree: "collapsible",
-          grouped_stats_dotfile_groups: %w[.ace-taskflow .ace]
+          grouped_stats_dotfile_groups: %w[.ace-task .ace]
         )
           @exclude_patterns = Array(exclude_patterns)
           @exclude_whitespace = exclude_whitespace
@@ -152,7 +152,7 @@ module Ace
             grouped_stats_layers: grouped_stats["layers"] || grouped_stats[:layers] || %w[lib test handbook],
             grouped_stats_collapse_above: grouped_stats.fetch("collapse_above", grouped_stats.fetch(:collapse_above, 5)),
             grouped_stats_show_full_tree: grouped_stats["show_full_tree"] || grouped_stats[:show_full_tree] || "collapsible",
-            grouped_stats_dotfile_groups: grouped_stats["dotfile_groups"] || grouped_stats[:dotfile_groups] || %w[.ace-taskflow .ace]
+            grouped_stats_dotfile_groups: grouped_stats["dotfile_groups"] || grouped_stats[:dotfile_groups] || %w[.ace-task .ace]
           )
         end
 

data/lib/ace/git/molecules/gh_cli_executor.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "open3"
+require "timeout"
+
+module Ace
+  module Git
+    module Molecules
+      # Safely execute gh CLI commands with timeout and structured output.
+      class GhCliExecutor
+        DEFAULT_GH_TIMEOUT = 30
+        DEFAULT_SIMPLE_TIMEOUT = 10
+
+        def self.execute(subcommand, args = [], timeout: nil)
+          check_installed
+          timeout_seconds = timeout || Ace::Git.network_timeout || DEFAULT_GH_TIMEOUT
+          command = ["gh", subcommand] + args
+          run_command(command, timeout_seconds)
+        rescue Timeout::Error
+          raise Ace::Git::TimeoutError, "gh command timed out after #{timeout_seconds} seconds"
+        end
+
+        def self.check_installed
+          result = execute_simple("--version")
+          raise Ace::Git::GhNotInstalledError unless result[:success]
+
+          true
+        end
+
+        def self.check_authenticated
+          result = execute_simple("auth", ["status"])
+          raise Ace::Git::GhAuthenticationError unless result[:success]
+
+          {
+            authenticated: true,
+            username: extract_username(result[:stderr])
+          }
+        end
+
+        def self.execute_simple(command, args = [], timeout_seconds = nil)
+          timeout_seconds ||= Ace::Git.network_timeout || DEFAULT_SIMPLE_TIMEOUT
+          cmd = ["gh", command] + args
+          run_command(cmd, timeout_seconds)
+        rescue Timeout::Error
+          {
+            success: false,
+            stdout: "",
+            stderr: "Command timed out",
+            exit_code: 1
+          }
+        end
+
+        def self.extract_username(output)
+          match = output.match(/Logged in to .+ as (\S+)/)
+          match ? match[1] : nil
+        end
+
+        def self.run_command(command, timeout_seconds)
+          stdout_str, stderr_str, status = Timeout.timeout(timeout_seconds) do
+            Open3.capture3(*command)
+          end
+
+          {
+            success: status.success?,
+            stdout: stdout_str,
+            stderr: stderr_str,
+            exit_code: status.exitstatus
+          }
+        rescue Errno::ENOENT
+          raise Ace::Git::GhNotInstalledError
+        end
+
+        private_class_method :execute_simple, :extract_username, :run_command
+      end
+    end
+  end
+end

data/lib/ace/git/molecules/github_issue_sync.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Ace
+  module Git
+    module Molecules
+      # Synchronize ACE task linkage metadata to GitHub issues.
+      class GithubIssueSync
+        class OwnershipConflict < StandardError; end
+
+        STICKY_MARKER = "<!-- ace-task:tracked -->"
+        TRACKED_LABEL = "ace:tracked"
+        TERMINAL_STATUSES = %w[done completed shipped closed cancelled skipped archived].freeze
+
+        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 = GhCliExecutor.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:)
+          GhCliExecutor.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)
+          GhCliExecutor.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)
+          GhCliExecutor.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 = GhCliExecutor.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 = GhCliExecutor.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 = GhCliExecutor.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 = GhCliExecutor.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
+
+      # Backward-compatible alias for early integration experiments.
+      IssueSync = GithubIssueSync
+    end
+  end
+end

data/lib/ace/git/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Git
-    VERSION = '0.19.3'
+    VERSION = '0.22.0'
   end
 end

data/lib/ace/git.rb

@@ -221,6 +221,8 @@ require_relative "git/molecules/branch_reader"
 require_relative "git/molecules/pr_metadata_fetcher"
 require_relative "git/molecules/recent_commits_fetcher"
 require_relative "git/molecules/git_status_fetcher"
+require_relative "git/molecules/gh_cli_executor"
+require_relative "git/molecules/github_issue_sync"
 
 require_relative "git/organisms/diff_orchestrator"
 require_relative "git/organisms/repo_status_loader"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-git
 version: !ruby/object:Gem::Version
-  version: 0.19.3
+  version: 0.22.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-04-01 00:00:00.000000000 Z
+date: 2026-04-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-config
@@ -168,7 +168,9 @@ files:
 - lib/ace/git/molecules/config_loader.rb
 - lib/ace/git/molecules/diff_filter.rb
 - lib/ace/git/molecules/diff_generator.rb
+- lib/ace/git/molecules/gh_cli_executor.rb
 - lib/ace/git/molecules/git_status_fetcher.rb
+- lib/ace/git/molecules/github_issue_sync.rb
 - lib/ace/git/molecules/pr_metadata_fetcher.rb
 - lib/ace/git/molecules/recent_commits_fetcher.rb
 - lib/ace/git/organisms/diff_orchestrator.rb