ace-task 0.38.1 → 0.39.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5816e661bad83e251f7163f2c31be9c0395492ab92ef00d2f8d0ddc63c02291
-  data.tar.gz: 8c69d8964833c9f008de95ea38dde3efa36095baa9814a60f8ebf8a8da86956e
+  metadata.gz: f192e0d481809ade06d5be298d573c824a6a2b16147448911a6743bdea524e5d
+  data.tar.gz: a1a05a622f467e7e9cb42139166c3335aba57ff1fb0cce34711c41453b725387
 SHA512:
-  metadata.gz: 4183d716b57fdde53188afb4a3da9d63e62398ea9223e9ffc954c9c7bd6061cd23e6005208cf4e58313176c2b33feb0831155d3490c6bd9f9859feda29c17b6a
-  data.tar.gz: a5dbbd8e5795dac65bad64b8c79cf515f6b5f3daf736a2e0baea7f9195a5e2a042797689a048fa913eb05532d437ab30dec6fa8c0f137c0ce037cf64a06ec9cb
+  metadata.gz: 566a4273824d53d2810a84d62202077de16411e6bd166c695ce454890c37e415fbc2b80c444c2768f46bedd03709633b87db5d2bf4e475edda85f89e87c3e948
+  data.tar.gz: 8e6266c0fc3c3bb400d840e35c3d3ff460dd9f24b0f1ae783ab14d414a5d29501ab24b7096615f2ecb3fb4bda32571031fee3fc3b8390c3bab70048a69eb0b6e

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.39.0] - 2026-10-02
+
+### Added
+- Named-forge issue links and best-effort issue synchronization for task creation, updates, and pending replay.
+
+### Changed
+- Task issue commands and workflow guidance now use forge-neutral `--issue` and `--default-server` options.
+- Raised minimum dependencies to the versions providing the issue tracking contract: ace-git ~> 0.26, ace-git-github ~> 0.3, ace-git-forgejo ~> 0.4.
+
+### Fixed
+- Issue identity locks serialize by canonical repository identity (provider + normalized web repository + issue number) and are held across task relocations, with parent-before-child ordering that closes the archive deadlock window.
+- Definitive-looking provider failures after a tracking comment committed (label/state steps, post-write ownership conflicts) retain the task, link, and pending identity as the cleanup record instead of deleting them; only pre-mutation ownership rejection rolls back.
+- Clear intent is persisted before comment reconciliation (with the create guard remembered), pending clears complete after authoritative create absence, and a pending clear's outgoing ID survives reparenting.
+- Generic task updates reject all issue-sync control fields, including `issue_sync_reconcile_create`.
+
 ## [0.38.1] - 2026-09-29
 
 ### Fixed

data/handbook/workflow-instructions/task/draft.wf.md

@@ -35,11 +35,11 @@ Create high-level behavioral specifications that define WHAT the system should d
      * User stories or experience descriptions
      * Interface specifications or contracts
    * If files are referenced, read their contents
-   * If the input is a GitHub issue URL, extract the issue number and treat it
-     as task lifecycle metadata. Use that number with `ace-task create
-     --github-issue <number>` when creating the parent task or single flat task.
+   * If the input is a configured forge issue URL, retain its exact repository
+     identity. Use it with `ace-task create --issue <url>` when creating the
+     parent task or single flat task.
      The issue URL may still appear in the task body as source context, but the
-     lifecycle link belongs in task frontmatter as `github_issue`.
+     lifecycle link belongs in task frontmatter as a complete `remote_issue` mapping.
    * **Intent mapping from enhanced ideas**: When the source idea contains the
      3-Question Delegation Brief sections (`What I Hope to Accomplish`,
      `What "Complete" Looks Like`, `Success Criteria`), use them as the
@@ -134,14 +134,14 @@ Create high-level behavioral specifications that define WHAT the system should d
    **Pattern A -- Single flat task (default):**
    ```bash
    ace-task create "Task Title" --status draft --estimate "TBD"
-   ace-task create "Task Title" --status draft --estimate "TBD" --github-issue 276
+   ace-task create "Task Title" --status draft --estimate "TBD" --issue 276 --default-server
    ```
 
    **Pattern B -- Orchestrator with subtasks:**
    ```bash
    # 1. Create the parent task first
    ace-task create "Parent Title" --status draft --estimate "TBD"
-   ace-task create "Parent Title" --status draft --estimate "TBD" --github-issue 276
+   ace-task create "Parent Title" --status draft --estimate "TBD" --issue 276 --default-server
    # Returns: v.X.Y+task.NNN
 
    # 2. Add each subtask with --child-of (auto-converts parent to orchestrator)
@@ -166,12 +166,12 @@ Create high-level behavioral specifications that define WHAT the system should d
    * For subtasks, list required shared context files explicitly in EACH subtask's bundle (no implicit inheritance)
    * Include behavioral specification template
    * Focus on behavioral content, leave implementation for replan step
-   * When drafting from a GitHub issue:
-     * Put `--github-issue <number>` only on the parent/orchestrator or single
+   * When drafting from a forge issue:
+     * Put `--issue <url>` only on the parent/orchestrator or single
        flat task create command unless separate subtasks each own distinct
-       GitHub issues.
-     * Run `ace-task github-sync <parent-or-task-ref>` after creation so the
-       GitHub issue receives the ACE task tracking update.
+       issues.
+     * Run `ace-task issue-sync <parent-or-task-ref>` after creation so the
+       exact linked issue receives the ACE task tracking update.
 
 ### Review-First Rule for Uncertain Drafts
 
@@ -243,8 +243,8 @@ When requirements are uncertain, do not create a special spike task. Draft the r
    * **Validation Checklist:**
      * [ ] All behavioral requirements captured as drafts
      * [ ] Task files have status: draft
-     * [ ] GitHub issue inputs are linked through `github_issue` frontmatter on the parent/single task
-     * [ ] Linked GitHub issue inputs have been synced with `ace-task github-sync <ref>`
+     * [ ] Forge issue inputs are linked through complete `remote_issue` frontmatter on the parent/single task
+     * [ ] Linked issue inputs have been synced with `ace-task issue-sync <ref>`
      * [ ] Behavioral specifications are complete
      * [ ] Interface contracts are defined
      * [ ] Success criteria are measurable
@@ -350,10 +350,10 @@ All code implementation happens during `ace-bundle wfi://task/work` (status: in-
 * All tasks have status: draft
 * No implementation details mixed with behavioral requirements
 * Clear handoff to review-task for readiness validation and promotion to pending
-* **REQUIRED when drafting from a GitHub issue URL:**
-  * The parent/orchestrator or single flat task is created with `--github-issue <number>`
-  * The task frontmatter contains `github_issue: <number>`
-  * `ace-task github-sync <ref>` has updated the linked issue
+* **REQUIRED when drafting from a forge issue URL:**
+  * The parent/orchestrator or single flat task is created with `--issue <url>`
+  * The task frontmatter contains a complete `remote_issue` mapping
+  * `ace-task issue-sync <ref>` has updated the linked issue
 * **REQUIRED when drafting from ideas:**
   * All source idea files marked as done via `ace-idea move <id> --to archive`
   * Task references updated to new idea file locations
@@ -383,7 +383,7 @@ All code implementation happens during `ace-bundle wfi://task/work` (status: in-
 Create the parent or single task with the linked issue number:
 
 ```bash
-ace-task create "Task Title" --status draft --estimate "TBD" --github-issue 276
+ace-task create "Task Title" --status draft --estimate "TBD" --issue 276 --default-server
 ```
 
 ---

data/lib/ace/task/atoms/task_frontmatter_defaults.rb

@@ -27,7 +27,7 @@ module Ace
           created_at: nil,
           parent: nil,
           estimate: nil,
-          github_issue: nil
+          remote_issue: nil
         )
           fm = {
             "id" => id,
@@ -39,7 +39,10 @@ module Ace
           fm["dependencies"] = dependencies || []
           fm["tags"] = tags || []
           fm["parent"] = parent if parent
-          fm["github_issue"] = github_issue if github_issue
+          fm["remote_issue"] = remote_issue if remote_issue
+          # Linked tasks start pending-sync in the same write that establishes
+          # the link; a crash before the first sync still replays via --pending.
+          fm["issue_sync_pending"] = true if remote_issue
           fm
         end
 

data/lib/ace/task/cli/commands/create.rb

@@ -21,7 +21,7 @@ module Ace
             '--title "Fix login bug"                      # Create task with title flag',
             '"Fix auth" --priority high --tags auth,security  # With priority and tags',
             '"Setup DB" --child-of q7w                    # Create as subtask',
-            '"Track issue" --github-issue 276             # Link GitHub issue',
+            '"Track issue" --issue 276 --server forgejo-lab # Link one exact issue',
             '"Quick task" --in maybe                      # Create in _maybe/ folder',
             '"Draft spec" --status draft --estimate TBD   # Create as draft with estimate',
             '"Preview only" --dry-run                     # Show what would be created'
@@ -34,7 +34,9 @@ module Ace
           option :tags, type: :string, aliases: %w[-T], desc: "Tags (comma-separated)"
           option :status, type: :string, aliases: %w[-s], desc: "Initial status (draft, pending, blocked, ...)"
           option :estimate, type: :string, aliases: %w[-e], desc: "Effort estimate (e.g. TBD, 2h, 1d)"
-          option :"github-issue", type: :array, desc: "Linked GitHub issue number"
+          option :issue, type: :array, desc: "Issue number or URL to link"
+          option :server, type: :string, desc: "Named forge server"
+          option :"default-server", type: :boolean, desc: "Use the configured default forge server"
           option :"child-of", type: :string, desc: "Parent task reference (creates subtask)"
           option :in, type: :string, aliases: %w[-i], desc: "Target folder (e.g. next, maybe)"
           option :"dry-run", type: :boolean, aliases: %w[-n], desc: "Preview without writing"
@@ -53,7 +55,13 @@ module Ace
             tags = tags_str ? tags_str.split(",").map(&:strip).reject(&:empty?) : []
             status = options[:status]
             estimate = options[:estimate]
-            github_issue = parse_github_issue(options[:"github-issue"])
+            issue = parse_issue(options[:issue])
+            if !issue && (options[:server] || options[:"default-server"])
+              raise Ace::Support::Cli::Error, "Server selection requires --issue"
+            end
+            remote_issue = issue && Ace::Task::Molecules::IssueLink.from_input(
+              issue, server_name: options[:server], use_default: options[:"default-server"]
+            )
             child_of = options[:"child-of"]
             in_folder = options[:in]
 
@@ -70,7 +78,7 @@ module Ace
               puts "  Status:   #{status}" if status
               puts "  Priority: #{priority}" if priority
               puts "  Estimate: #{estimate}" if estimate
-              puts "  GitHub:   #{github_issue}" if github_issue
+              puts "  Issue:    #{remote_issue['url']}" if remote_issue
               puts "  Tags:     #{tags.join(", ")}" if tags.any?
               puts "  Parent:   #{child_of}" if child_of
               puts "  Folder:   #{in_folder}" if in_folder
@@ -88,7 +96,7 @@ module Ace
                   priority: priority,
                   tags: tags,
                   estimate: estimate,
-                  github_issue: github_issue
+                  remote_issue: remote_issue
                 )
               else
                 manager.create(
@@ -97,7 +105,7 @@ module Ace
                   priority: priority,
                   tags: tags,
                   estimate: estimate,
-                  github_issue: github_issue
+                  remote_issue: remote_issue
                 )
               end
             rescue Ace::Task::Organisms::TaskManager::CreateRetriesExhaustedError => e
@@ -126,6 +134,8 @@ module Ace
                 intention: "create task #{task.id}"
               )
             end
+          rescue Ace::Git::Error, ArgumentError => e
+            raise Ace::Support::Cli::Error, e.message
           end
 
           private
@@ -148,18 +158,15 @@ module Ace
             !value.nil? && !value.to_s.strip.empty?
           end
 
-          def parse_github_issue(raw_values)
+          def parse_issue(raw_values)
             values = Array(raw_values).flatten.compact
             return nil if values.empty?
-            raise Ace::Support::Cli::Error.new("Only one --github-issue may be provided") if values.length > 1
+            raise Ace::Support::Cli::Error.new("Only one --issue may be provided") if values.length > 1
 
             candidate = values.first.to_s.strip
-            raise Ace::Support::Cli::Error.new("Invalid GitHub issue '#{values.first}': expected numeric ID") unless candidate.match?(/\A\d+\z/)
-
-            id = candidate.to_i
-            raise Ace::Support::Cli::Error.new("Invalid GitHub issue '#{values.first}': expected positive numeric ID") if id <= 0
+            raise Ace::Support::Cli::Error.new("Issue identifier cannot be empty") if candidate.empty?
 
-            id
+            candidate
           end
         end
       end

data/lib/ace/task/cli/commands/issue_link.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+
+module Ace
+  module Task
+    module CLI
+      module Commands
+        class IssueLink < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Link a task to one validated issue or clear its owned tracking artifacts"
+          argument :ref, required: true, desc: "Task reference"
+          option :issue, type: :string, desc: "Issue number or URL"
+          option :clear, type: :boolean, desc: "Clear the existing issue link"
+          option :server, type: :string, desc: "Named forge server"
+          option :"default-server", type: :boolean, desc: "Use configured default forge server"
+
+          def call(ref:, **options)
+            if options[:clear] && (options[:issue] || options[:server] || options[:"default-server"])
+              raise Ace::Support::Cli::Error, "--clear cannot combine with issue or server selection"
+            end
+            result = Ace::Task::Organisms::TaskManager.new.issue_link(
+              ref, issue: options[:issue], clear: options[:clear],
+              server_name: options[:server], use_default: options[:"default-server"]
+            )
+            raise Ace::Support::Cli::Error, "Task #{ref.inspect} not found" unless result
+
+            puts(options[:clear] ? "Cleared issue link for #{result.id}" :
+              "Linked #{result.id} to #{result.metadata.fetch('remote_issue').fetch('url')}")
+          rescue Ace::Git::Error, ArgumentError => e
+            raise Ace::Support::Cli::Error, e.message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/task/cli/commands/issue_sync.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+
+module Ace
+  module Task
+    module CLI
+      module Commands
+        class IssueSync < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Synchronize the exact stored issue link for one task or a selected task set"
+          argument :ref, required: false, desc: "Task reference"
+          option :all, type: :boolean, desc: "Sync all linked tasks"
+          option :pending, type: :boolean, desc: "Replay deferred issue synchronization"
+
+          def call(ref: nil, **options)
+            if options[:all] && options[:pending] || ref && (options[:all] || options[:pending])
+              raise Ace::Support::Cli::Error, "Choose REF, --all, or --pending"
+            end
+            unless ref || options[:all] || options[:pending]
+              raise Ace::Support::Cli::Error, "Provide REF, --all, or --pending"
+            end
+            result = Ace::Task::Organisms::TaskManager.new.issue_sync(
+              ref: ref, all: options[:all], pending: options[:pending]
+            )
+            raise Ace::Support::Cli::Error, "Task #{ref.inspect} not found" unless result
+
+            Array(result[:failures]).each do |failure|
+              warn "Issue sync failed for #{failure[:task_id]} (#{failure[:remote_issues].inspect}): #{failure[:error]}"
+            end
+            summary = "Issue sync: synced #{result[:synced]}, failed #{result[:failed]}, " \
+              "pending #{result[:pending]}, skipped #{result[:skipped]}"
+            raise Ace::Support::Cli::Error, summary if result[:failed].positive? || result[:pending].positive?
+
+            puts summary
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/task/cli/commands/update.rb

@@ -114,6 +114,8 @@ module Ace
                 intention: intention
               )
             end
+          rescue ArgumentError => e
+            raise Ace::Support::Cli::Error, e.message
           end
 
           private

data/lib/ace/task/cli.rb

@@ -10,7 +10,8 @@ require_relative "cli/commands/update"
 require_relative "cli/commands/doctor"
 require_relative "cli/commands/status"
 require_relative "cli/commands/plan"
-require_relative "cli/commands/github_sync"
+require_relative "cli/commands/issue_sync"
+require_relative "cli/commands/issue_link"
 
 module Ace
   module Task
@@ -28,7 +29,8 @@ module Ace
         ["doctor", "Run health checks on tasks"],
         ["status", "Show task status overview"],
         ["plan", "Resolve or generate implementation plan"],
-        ["github-sync", "Sync linked GitHub issues for task(s)"]
+        ["issue-sync", "Sync linked issues for task(s)"],
+        ["issue-link", "Link or clear one exact remote issue"]
       ].freeze
 
       HELP_EXAMPLES = [
@@ -48,8 +50,9 @@ module Ace
         "ace-task plan q7w",
         "ace-task plan q7w --refresh",
         "ace-task plan q7w --content",
-        "ace-task github-sync q7w",
-        "ace-task github-sync --all"
+        "ace-task issue-sync q7w",
+        "ace-task issue-sync --pending",
+        "ace-task issue-link q7w --issue 42 --server forgejo-lab"
       ].freeze
 
       register "create", CLI::Commands::Create
@@ -59,7 +62,8 @@ module Ace
       register "doctor", CLI::Commands::Doctor
       register "status", CLI::Commands::Status
       register "plan", CLI::Commands::Plan
-      register "github-sync", CLI::Commands::GithubSync
+      register "issue-sync", CLI::Commands::IssueSync
+      register "issue-link", CLI::Commands::IssueLink
 
       version_cmd = Ace::Support::Cli::VersionCommand.build(
         gem_name: "ace-task",

data/lib/ace/task/molecules/issue_link.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "uri"
+require "ace/git"
+
+module Ace
+  module Task
+    module Molecules
+      # Resolves and validates the one persisted remote issue identity.
+      module IssueLink
+        FIELDS = %w[server_name provider repository_url number url].freeze
+
+        module_function
+
+        def from_input(input, server_name: nil, use_default: false)
+          value = input.to_s.strip
+          raise ArgumentError, "Issue identifier is empty" if value.empty?
+
+          selected = server_name || use_default ?
+            Ace::Git::ServerRegistry.resolve_for(server_name: server_name, use_default: use_default) : nil
+          number, candidates = if value.match?(/\A[1-9]\d*\z/)
+            [value.to_i, nil]
+          elsif (match = value.match(%r{\A(https?://[^\s]+?)/issues/([1-9]\d*)\z}))
+            [match[2].to_i, Ace::Git::ServerRegistry.matching_servers(match[1])]
+          elsif (match = value.match(/\A([^\s#]+\/[^\s#]+)#([1-9]\d*)\z/))
+            [match[2].to_i, Ace::Git::ServerRegistry.servers_for_owner_repo(match[1])]
+          else
+            raise ArgumentError, "Invalid issue identifier #{input.inspect}; use a positive number or issue URL"
+          end
+
+          if candidates
+            raise Ace::Git::AmbiguousRemoteError, "Issue repository matches no configured server" if candidates.empty?
+            # A URL input must resolve uniquely on its own; explicit selection
+            # filters but never disambiguates multiple matches.
+            raise Ace::Git::AmbiguousRemoteError,
+              "Issue repository matches multiple configured servers" if candidates.length != 1
+            if selected && candidates.first.name != selected.name
+              raise Ace::Git::ProviderIdentityMismatchError,
+                "Issue identifier does not match selected server #{selected.name}"
+            end
+            selected ||= candidates.first
+          else
+            selected ||= Ace::Git::ServerRegistry.resolve_for
+          end
+
+          {
+            "server_name" => selected.name,
+            "provider" => selected.provider.to_s,
+            "repository_url" => selected.url,
+            "number" => number,
+            "url" => "#{Ace::Git::Atoms::ServerUrl.web_base(selected.url)}/issues/#{number}"
+          }
+        end
+
+        def validate!(mapping)
+          unless mapping.is_a?(Hash) && mapping.keys.map(&:to_s).sort == FIELDS.sort
+            raise ArgumentError, "remote_issue must contain exactly #{FIELDS.join(', ')}"
+          end
+          identity = mapping.transform_keys(&:to_s)
+          number = identity["number"]
+          unless number.is_a?(Integer) && number.positive?
+            raise ArgumentError, "remote_issue.number must be a positive integer"
+          end
+          server = Ace::Git::ServerRegistry.resolve(identity["server_name"])
+          expected = from_input(number.to_s, server_name: server.name)
+          unless identity == expected
+            raise Ace::Git::ProviderIdentityMismatchError,
+              "Stored remote_issue identity for #{server.name} no longer matches its configured repository/provider"
+          end
+          server
+        end
+      end
+    end
+  end
+end

data/lib/ace/task/molecules/issue_sync_adapter.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "issue_link"
+require "pathname"
+
+module Ace
+  module Task
+    module Molecules
+      class IssueSyncAdapter
+        def initialize(provider_factory: Ace::Git::Providers)
+          @provider_factory = provider_factory
+        end
+
+        def validate_link!(identity:, task_id: nil, previous_task_id: nil)
+          server = IssueLink.validate!(identity)
+          tracking(server).validate_link!(number: identity.fetch("number"), task_id: task_id,
+            previous_task_id: previous_task_id)
+        end
+
+        def sync_task(task:, previous_task_id: nil, before_create: nil)
+          identity = task.metadata.fetch("remote_issue")
+          server = IssueLink.validate!(identity)
+          tracking(server).sync(
+            number: identity.fetch("number"), task_id: task.id,
+            previous_task_id: previous_task_id,
+            task_link: task_link(identity, task), task_status: task.status,
+            create_pending: task.metadata["issue_sync_operation"] == "reconcile-create" ||
+              task.metadata["issue_sync_reconcile_create"] == true,
+            before_create: before_create
+          )
+        end
+
+        # Clear-time reconciliation: establish comment ownership without any
+        # lifecycle side effect (clear never changes issue state).
+        def reconcile_comment(task:)
+          identity = task.metadata.fetch("remote_issue")
+          server = IssueLink.validate!(identity)
+          tracking(server).sync(
+            number: identity.fetch("number"), task_id: task.id,
+            previous_task_id: task.metadata["issue_sync_previous_id"],
+            task_link: task_link(identity, task), task_status: task.status,
+            create_pending: task.metadata["issue_sync_operation"] == "reconcile-create" ||
+              task.metadata["issue_sync_reconcile_create"] == true,
+            comment_only: true
+          )
+        end
+
+        def clear_task(task:, previous_task_id: nil)
+          identity = task.metadata.fetch("remote_issue")
+          server = IssueLink.validate!(identity)
+          tracking(server).clear(number: identity.fetch("number"), task_id: task.id,
+            previous_task_id: previous_task_id)
+        end
+
+        private
+
+        def tracking(server)
+          Ace::Git::Organisms::IssueTracking.new(provider: @provider_factory.for(server))
+        end
+
+        # Repository-relative so the forge blob link is stable no matter which
+        # working directory ace-task was invoked from.
+        def safe_task_path(task)
+          path = Pathname.new(task.file_path || task.path).expand_path
+          root = Pathname.new(git_repo_root(path))
+          relative = path.relative_path_from(root).to_s
+          relative.start_with?("../") ? path.basename.to_s : relative
+        rescue ArgumentError, SystemCallError
+          path.basename.to_s
+        end
+
+        def git_repo_root(path)
+          candidate = path.dirname
+          loop do
+            return candidate.to_s if File.exist?(File.join(candidate, ".git"))
+
+            parent = candidate.parent
+            raise SystemCallError, "no git repository" if parent == candidate
+
+            candidate = parent
+          end
+        end
+
+        # A repository-relative path is not a resolvable link target inside a
+        # forge comment; build a web URL from the linked repository using the
+        # provider's file-browse route (GitHub: /blob/, Forgejo: /src/branch/).
+        def task_link(identity, task)
+          base = Ace::Git::Atoms::ServerUrl.web_base(identity.fetch("repository_url"))
+          path = safe_task_path(task)
+          if identity.fetch("provider") == "github"
+            "#{base}/blob/HEAD/#{path}"
+          else
+            "#{base}/src/branch/HEAD/#{path}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/task/molecules/subtask_creator.rb

@@ -40,7 +40,7 @@ module Ace
           tags: [],
           time: Time.now.utc,
           estimate: nil,
-          github_issue: nil
+          remote_issue: nil
         )
           raise ArgumentError, "Title is required" if title.nil? || title.strip.empty?
 
@@ -70,7 +70,7 @@ module Ace
             created_at: time,
             parent: parent_task.id,
             estimate: estimate,
-            github_issue: github_issue
+            remote_issue: remote_issue
           )
 
           # Write spec file

data/lib/ace/task/molecules/task_creator.rb

@@ -40,7 +40,7 @@ module Ace
           time: Time.now.utc,
           use_llm_slug: false,
           estimate: nil,
-          github_issue: nil
+          remote_issue: nil
         )
           raise ArgumentError, "Title is required" if title.nil? || title.strip.empty?
 
@@ -76,7 +76,7 @@ module Ace
                 dependencies: dependencies,
                 created_at: time,
                 estimate: estimate,
-                github_issue: github_issue
+                remote_issue: remote_issue
               )
 
               # Write spec file with file_slug

data/lib/ace/task/molecules/task_frontmatter_validator.rb

@@ -110,7 +110,7 @@ module Ace
               issues << {type: :warning, message: "Title exceeds #{Atoms::TaskValidationRules::MAX_TITLE_LENGTH} characters (#{title.length} chars)", location: file_path}
             end
 
-            validate_github_fields(frontmatter, file_path, issues)
+            validate_issue_fields(frontmatter, file_path, issues)
           end
 
           def validate_recommended_fields(frontmatter, file_path, issues)
@@ -134,24 +134,50 @@ module Ace
             end
           end
 
-          def validate_github_fields(frontmatter, file_path, issues)
-            linked = frontmatter["github_issue"]
-            unless linked.nil? || (linked.is_a?(Integer) && linked.positive?)
-              issues << {
-                type: :error,
-                message: "Invalid GitHub issue ID '#{linked}' in github_issue (expected positive integer)",
-                location: file_path
-              }
-            end
-
-            pending = frontmatter["github_sync_pending"]
-            return if pending.nil? || pending == true || pending == false
+          def validate_issue_fields(frontmatter, file_path, issues)
+            %w[github_issue github_sync_pending].each do |key|
+              next unless frontmatter.key?(key)
 
-            issues << {
-              type: :error,
-              message: "Invalid github_sync_pending value (expected boolean)",
-              location: file_path
-            }
+              issues << {type: :error, message: "Obsolete #{key}; use remote_issue/issue_sync_pending",
+                         location: file_path}
+            end
+            if frontmatter.key?("remote_issue")
+              linked = frontmatter["remote_issue"]
+              valid = linked.is_a?(Hash) && linked.keys.all? { |key| key.is_a?(String) } &&
+                linked.keys.sort ==
+                %w[number provider repository_url server_name url] &&
+                linked["number"].is_a?(Integer) && linked["number"].positive? &&
+                %w[server_name provider repository_url url].all? { |key| linked[key].is_a?(String) && !linked[key].empty? } &&
+                linked["url"] == "#{Ace::Git::Atoms::ServerUrl.web_base(linked["repository_url"])}/issues/#{linked["number"]}"
+              unless valid
+                issues << {type: :error, message: "Invalid complete remote_issue identity", location: file_path}
+              end
+            end
+            pending = frontmatter["issue_sync_pending"]
+            unless pending.nil? || pending == true || pending == false
+              issues << {type: :error, message: "Invalid issue_sync_pending value (expected boolean)",
+                         location: file_path}
+            end
+            if pending == true && !frontmatter.key?("remote_issue")
+              issues << {type: :error, message: "issue_sync_pending requires a complete remote_issue identity",
+                         location: file_path}
+            end
+            operation = frontmatter["issue_sync_operation"]
+            valid_operation = operation.nil? ||
+              (%w[clear reconcile-create].include?(operation) && pending == true && frontmatter["remote_issue"].is_a?(Hash))
+            unless valid_operation
+              issues << {type: :error, message: "Invalid issue_sync_operation", location: file_path}
+            end
+            previous_id = frontmatter["issue_sync_previous_id"]
+            unless previous_id.nil? || (previous_id.is_a?(String) && !previous_id.empty?)
+              issues << {type: :error, message: "Invalid issue_sync_previous_id value (expected task ID string)",
+                         location: file_path}
+            end
+            reconcile_flag = frontmatter["issue_sync_reconcile_create"]
+            unless reconcile_flag.nil? || reconcile_flag == true
+              issues << {type: :error, message: "Invalid issue_sync_reconcile_create value (expected boolean)",
+                         location: file_path}
+            end
           end
         end
       end