ace-task 0.31.9 → 0.36.1

data/lib/ace/task/cli.rb

@@ -10,6 +10,7 @@ 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"
 
 module Ace
   module Task
@@ -26,7 +27,8 @@ module Ace
         ["update", "Update task metadata (fields, move, reparent)"],
         ["doctor", "Run health checks on tasks"],
         ["status", "Show task status overview"],
-        ["plan", "Resolve or generate implementation plan"]
+        ["plan", "Resolve or generate implementation plan"],
+        ["github-sync", "Sync linked GitHub issues for task(s)"]
       ].freeze
 
       HELP_EXAMPLES = [
@@ -45,7 +47,9 @@ module Ace
         "ace-task status --up-next-limit 5",
         "ace-task plan q7w",
         "ace-task plan q7w --refresh",
-        "ace-task plan q7w --content"
+        "ace-task plan q7w --content",
+        "ace-task github-sync q7w",
+        "ace-task github-sync --all"
       ].freeze
 
       register "create", CLI::Commands::Create
@@ -55,6 +59,7 @@ module Ace
       register "doctor", CLI::Commands::Doctor
       register "status", CLI::Commands::Status
       register "plan", CLI::Commands::Plan
+      register "github-sync", CLI::Commands::GithubSync
 
       version_cmd = Ace::Support::Cli::VersionCommand.build(
         gem_name: "ace-task",

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Ace
+  module Task
+    module Molecules
+      # Bridges ace-task lifecycle events to reusable ace-git issue sync primitives.
+      class GithubIssueSyncAdapter
+        UNAVAILABLE_MESSAGE = "GitHub issue sync primitives are unavailable. " \
+          "Complete dependency task 8r4.t.ilo.2 or update ace-git."
+
+        CANDIDATE_INTEGRATIONS = [
+          ["Ace::Git::Molecules::GithubIssueSync", :validate_link!],
+          ["Ace::Git::Molecules::IssueSync", :validate_link!],
+          ["Ace::Git::Molecules::GithubIssueSync", :sync_task],
+          ["Ace::Git::Molecules::IssueSync", :sync_task]
+        ].freeze
+
+        def validate_link!(issue_id:, previous_task: nil)
+          return unless issue_id.to_i.positive?
+
+          receiver, method_name = resolve_integration(:validate_link!)
+          raise UNAVAILABLE_MESSAGE unless receiver && method_name
+
+          receiver.public_send(
+            method_name,
+            issue_id: issue_id.to_i,
+            task_id: previous_task&.id,
+            previous_task_id: previous_task&.id
+          )
+        end
+
+        def sync_task(task:, reason:, previous_task: nil)
+          current_issue_ids = [task.metadata["github_issue"]].compact.map(&:to_i).uniq
+          previous_issue_ids = [previous_task&.metadata&.[]("github_issue")].compact.map(&:to_i).uniq
+          issue_ids = (current_issue_ids + previous_issue_ids).uniq
+          return {synced: 0, issues: []} if issue_ids.empty?
+
+          receiver, method_name = resolve_integration(:sync_task)
+          raise UNAVAILABLE_MESSAGE unless receiver && method_name
+
+          payload = {
+            task_id: task.id,
+            task_title: task.title,
+            task_status: task.status,
+            task_path: task.file_path || task.path,
+            issue_ids: issue_ids,
+            current_issue_ids: current_issue_ids,
+            reason: reason,
+            previous: previous_task ? {
+              id: previous_task.id,
+              title: previous_task.title,
+              status: previous_task.status,
+              path: previous_task.file_path || previous_task.path
+            } : nil
+          }
+          receiver.public_send(method_name, **payload)
+          {synced: issue_ids.length, issues: issue_ids}
+        end
+
+        private
+
+        def resolve_integration(expected_method = nil)
+          CANDIDATE_INTEGRATIONS.each do |constant_name, method_name|
+            next if expected_method && method_name != expected_method
+
+            klass = constant_name.split("::").reject(&:empty?).inject(Object) { |ctx, name| ctx.const_get(name) }
+            return [klass, method_name] if klass.respond_to?(method_name)
+          rescue NameError
+            next
+          end
+
+          [nil, nil]
+        end
+      end
+    end
+  end
+end

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

@@ -32,7 +32,16 @@ module Ace
         # @param time [Time] Creation time (default: now)
         # @return [Models::Task] Created subtask
         # @raise [RangeError] If parent already has 36 subtasks
-        def create(parent_task, title, status: nil, priority: nil, tags: [], time: Time.now.utc, estimate: nil)
+        def create(
+          parent_task,
+          title,
+          status: nil,
+          priority: nil,
+          tags: [],
+          time: Time.now.utc,
+          estimate: nil,
+          github_issue: nil
+        )
           raise ArgumentError, "Title is required" if title.nil? || title.strip.empty?
 
           # Find next available subtask character
@@ -60,7 +69,8 @@ module Ace
             tags: tags,
             created_at: time,
             parent: parent_task.id,
-            estimate: estimate
+            estimate: estimate,
+            github_issue: github_issue
           )
 
           # Write spec file

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

@@ -13,6 +13,8 @@ module Ace
       # Generates folder structure and spec file with full frontmatter.
       # Optionally uses LLM for slug generation with deterministic fallback.
       class TaskCreator
+        class IdCollisionError < StandardError; end
+
         # @param root_dir [String] Root directory for tasks
         # @param config [Hash] Configuration hash
         def initialize(root_dir:, config: {})
@@ -29,52 +31,90 @@ module Ace
         # @param time [Time] Creation time (default: now)
         # @param use_llm_slug [Boolean] Whether to attempt LLM slug generation
         # @return [Models::Task] Created task
-        def create(title, status: nil, priority: nil, tags: [], dependencies: [], time: Time.now.utc, use_llm_slug: false, estimate: nil)
+        def create(
+          title,
+          status: nil,
+          priority: nil,
+          tags: [],
+          dependencies: [],
+          time: Time.now.utc,
+          use_llm_slug: false,
+          estimate: nil,
+          github_issue: nil
+        )
           raise ArgumentError, "Title is required" if title.nil? || title.strip.empty?
 
           # Generate task ID
           item_id = Atoms::TaskIdFormatter.generate(time)
           formatted_id = item_id.formatted_id
 
-          # Generate slugs
-          slugs = if use_llm_slug
-            generate_llm_slugs(title) || generate_slugs(title)
-          else
-            generate_slugs(title)
+          with_id_reservation(formatted_id) do
+            raise IdCollisionError, "Task ID collision detected for #{formatted_id}" if task_id_exists?(formatted_id)
+
+            # Generate slugs
+            slugs = if use_llm_slug
+              generate_llm_slugs(title) || generate_slugs(title)
+            else
+              generate_slugs(title)
+            end
+            folder_slug = slugs[:folder]
+            file_slug = slugs[:file]
+
+            # Create folder with folder_slug
+            folder_name = Atoms::TaskIdFormatter.folder_name(formatted_id, folder_slug)
+            task_dir = File.join(@root_dir, folder_name)
+            FileUtils.mkdir_p(task_dir)
+
+            begin
+              # Build frontmatter with all fields
+              effective_status = status || @config.dig("task", "default_status") || "pending"
+              frontmatter = Atoms::TaskFrontmatterDefaults.build(
+                id: formatted_id,
+                status: effective_status,
+                priority: priority,
+                tags: tags,
+                dependencies: dependencies,
+                created_at: time,
+                estimate: estimate,
+                github_issue: github_issue
+              )
+
+              # Write spec file with file_slug
+              spec_filename = Atoms::TaskIdFormatter.spec_filename(formatted_id, file_slug)
+              spec_file = File.join(task_dir, spec_filename)
+              content = build_spec_content(frontmatter: frontmatter, title: title)
+              File.write(spec_file, content)
+
+              # Load and return the created task
+              loader = TaskLoader.new
+              loader.load(task_dir, id: formatted_id)
+            rescue StandardError
+              FileUtils.rm_rf(task_dir) if Dir.exist?(task_dir)
+              raise
+            end
           end
-          folder_slug = slugs[:folder]
-          file_slug = slugs[:file]
-
-          # Create folder with folder_slug
-          folder_name = Atoms::TaskIdFormatter.folder_name(formatted_id, folder_slug)
-          task_dir = File.join(@root_dir, folder_name)
-          FileUtils.mkdir_p(task_dir)
-
-          # Build frontmatter with all fields
-          effective_status = status || @config.dig("task", "default_status") || "pending"
-          frontmatter = Atoms::TaskFrontmatterDefaults.build(
-            id: formatted_id,
-            status: effective_status,
-            priority: priority,
-            tags: tags,
-            dependencies: dependencies,
-            created_at: time,
-            estimate: estimate
-          )
-
-          # Write spec file with file_slug
-          spec_filename = Atoms::TaskIdFormatter.spec_filename(formatted_id, file_slug)
-          spec_file = File.join(task_dir, spec_filename)
-          content = build_spec_content(frontmatter: frontmatter, title: title)
-          File.write(spec_file, content)
-
-          # Load and return the created task
-          loader = TaskLoader.new
-          loader.load(task_dir, id: formatted_id)
         end
 
         private
 
+        def task_id_exists?(formatted_id)
+          Dir.glob(File.join(@root_dir, "**", "#{formatted_id}-*")).any? do |path|
+            File.directory?(path)
+          end
+        end
+
+        def with_id_reservation(formatted_id)
+          reservation_path = File.join(@root_dir, ".ace-task-id-lock-#{formatted_id}")
+          acquired = false
+          Dir.mkdir(reservation_path)
+          acquired = true
+          yield
+        rescue Errno::EEXIST
+          raise IdCollisionError, "Task ID collision detected for #{formatted_id}"
+        ensure
+          FileUtils.rm_rf(reservation_path) if acquired && reservation_path && Dir.exist?(reservation_path)
+        end
+
         def generate_folder_slug(title)
           sanitized = Ace::Support::Items::Atoms::SlugSanitizer.sanitize(title)
           words = sanitized.split("-")

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

@@ -109,6 +109,8 @@ module Ace
             if title.length > Atoms::TaskValidationRules::MAX_TITLE_LENGTH
               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)
           end
 
           def validate_recommended_fields(frontmatter, file_path, issues)
@@ -131,6 +133,19 @@ module Ace
               issues << issue.merge(location: file_path)
             end
           end
+
+          def validate_github_fields(frontmatter, file_path, issues)
+            linked = frontmatter["github_issue"]
+            return if linked.nil?
+
+            unless 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
+          end
         end
       end
     end

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

@@ -35,7 +35,9 @@ module Ace
           )
         rescue Ace::Support::Cli::Error
           raise
-        rescue RuntimeError, IOError, Errno::ENOENT, Errno::ECONNREFUSED, Timeout::Error => e
+        rescue StandardError => e
+          raise unless recoverable_query_error?(e)
+
           raise Ace::Support::Cli::Error.new(
             "Plan generation failed: #{e.message}. Retry with --refresh or choose a working --model."
           )
@@ -135,6 +137,16 @@ module Ace
           require "ace/llm"
           Ace::LLM::QueryInterface
         end
+
+        def recoverable_query_error?(error)
+          return true if error.class.name == "Ace::LLM::ProviderError"
+
+          error.is_a?(RuntimeError) ||
+            error.is_a?(IOError) ||
+            error.is_a?(Errno::ENOENT) ||
+            error.is_a?(Errno::ECONNREFUSED) ||
+            error.is_a?(Timeout::Error)
+        end
       end
     end
   end

data/lib/ace/task/organisms/task_doctor.rb

@@ -3,6 +3,7 @@
 require_relative "../molecules/task_scanner"
 require_relative "../molecules/task_frontmatter_validator"
 require_relative "../molecules/task_structure_validator"
+require_relative "../molecules/task_doctor_fixer"
 require_relative "../atoms/task_validation_rules"
 
 module Ace
@@ -108,13 +109,20 @@ module Ace
           scanner = Molecules::TaskScanner.new(@root_path)
           return unless scanner.root_exists?
 
-          scan_results = scanner.scan
+          scan_results = frontmatter_scan_results(scanner)
           @stats[:tasks_scanned] = scan_results.size
+          id_locations = Hash.new { |hash, key| hash[key] = [] }
 
           scan_results.each do |scan_result|
             spec_file = scan_result.file_path
             next unless spec_file && File.exist?(spec_file)
 
+            content = File.read(spec_file)
+            frontmatter, _body = Ace::Support::Items::Atoms::FrontmatterParser.parse(content)
+            if frontmatter.is_a?(Hash) && frontmatter["id"] && !frontmatter["id"].to_s.strip.empty?
+              id_locations[frontmatter["id"]] << spec_file
+            end
+
             issues = Molecules::TaskFrontmatterValidator.validate(
               spec_file,
               special_folder: scan_result.special_folder
@@ -127,6 +135,8 @@ module Ace
               add_issue(issue[:type], issue[:message], issue[:location])
             end
           end
+
+          add_duplicate_id_issues(id_locations)
         end
 
         def run_scope_check
@@ -175,6 +185,26 @@ module Ace
           count
         end
 
+        def frontmatter_scan_results(scanner)
+          top_level_results = scanner.scan
+          subtask_results = top_level_results.flat_map { |scan_result|
+            scanner.scan_subtasks(scan_result.dir_path, parent_id: scan_result.id)
+          }
+          top_level_results + subtask_results
+        end
+
+        def add_duplicate_id_issues(id_locations)
+          id_locations.each do |id, locations|
+            next unless locations.size > 1
+
+            add_issue(
+              :error,
+              "Duplicate task ID '#{id}' found in: #{locations.sort.join(', ')}",
+              locations.first
+            )
+          end
+        end
+
         def add_issue(type, message, location = nil)
           issue = {type: type, message: message}
           issue[:location] = location if location

data/lib/ace/task/organisms/task_manager.rb

@@ -7,6 +7,7 @@ require_relative "../molecules/task_loader"
 require_relative "../molecules/task_creator"
 require_relative "../molecules/subtask_creator"
 require_relative "../molecules/task_reparenter"
+require_relative "../molecules/github_issue_sync_adapter"
 require_relative "../atoms/task_validation_rules"
 
 module Ace
@@ -15,6 +16,9 @@ module Ace
       # Orchestrates all task CRUD operations.
       # Entry point for task management with config-driven root directory.
       class TaskManager
+        CREATE_RETRY_LIMIT = 3
+        class CreateRetriesExhaustedError < StandardError; end
+
         attr_reader :last_list_total, :last_folder_counts
 
         # @param root_dir [String, nil] Override root directory for tasks
@@ -35,11 +39,41 @@ module Ace
         # @param dependencies [Array<String>] Dependency task IDs
         # @param use_llm_slug [Boolean] Whether to attempt LLM slug generation
         # @return [Models::Task] Created task
-        def create(title, status: nil, priority: nil, tags: [], dependencies: [], use_llm_slug: false, estimate: nil)
+        def create(
+          title,
+          status: nil,
+          priority: nil,
+          tags: [],
+          dependencies: [],
+          use_llm_slug: false,
+          estimate: nil,
+          github_issue: nil
+        )
           ensure_root_dir
+          ensure_github_issue_linkable!(github_issue)
           creator = Molecules::TaskCreator.new(root_dir: @root_dir, config: @config)
-          creator.create(title, status: status, priority: priority, tags: tags,
-            dependencies: dependencies, use_llm_slug: use_llm_slug, estimate: estimate)
+          attempts = 0
+
+          begin
+            attempts += 1
+            created_task = creator.create(
+              title,
+              status: status,
+              priority: priority,
+              tags: tags,
+              dependencies: dependencies,
+              use_llm_slug: use_llm_slug,
+              time: Time.now.utc + ((attempts - 1) * 2),
+              estimate: estimate,
+              github_issue: github_issue
+            )
+            sync_linked_issues_for(created_task, reason: "create")
+            created_task
+          rescue Molecules::TaskCreator::IdCollisionError
+            retry if attempts < CREATE_RETRY_LIMIT
+            raise CreateRetriesExhaustedError,
+              "Failed to create task: unable to generate a unique ID after #{CREATE_RETRY_LIMIT} attempts"
+          end
         end
 
         # Show (load) a single task by reference, including subtasks.
@@ -109,6 +143,8 @@ module Ace
 
           # Apply field updates if any
           has_field_updates = [set, add, remove].any? { |h| h && !h.empty? }
+          desired_issue = extract_desired_github_issue(task, set: set, remove: remove)
+          ensure_github_issue_linkable!(desired_issue, previous_task: task) if desired_issue
           if has_field_updates
             Ace::Support::Items::Molecules::FieldUpdater.update(
               task.file_path, set: set, add: add, remove: remove
@@ -146,7 +182,9 @@ module Ace
             resolve_fn = ->(r) { show(r) }
             # Reload task from current path before reparenting (may have been field-updated)
             task_for_reparent = loader.load(current_path, id: task.id, special_folder: current_special)
-            return reparenter.reparent(task_for_reparent, target: move_as_child_of, resolve_ref: resolve_fn)
+            reparented = reparenter.reparent(task_for_reparent, target: move_as_child_of, resolve_ref: resolve_fn)
+            sync_linked_issues_for(reparented, reason: "reparent", previous_task: task)
+            return reparented
           end
 
           # Auto-archive hook: if a subtask status was set to terminal,
@@ -156,7 +194,11 @@ module Ace
           end
 
           # Reload and return updated task
-          loader.load(current_path, id: current_id, special_folder: current_special)
+          updated_task = loader.load(current_path, id: current_id, special_folder: current_special)
+          if sync_needed_after_update?(task, updated_task, set: set, add: add, remove: remove, move_to: move_to)
+            sync_linked_issues_for(updated_task, reason: "update", previous_task: task)
+          end
+          updated_task
         end
 
         # Create a subtask within a parent task.
@@ -166,12 +208,45 @@ module Ace
         # @param priority [String, nil] Priority level
         # @param tags [Array<String>] Tags
         # @return [Models::Task, nil] Created subtask or nil if parent not found
-        def create_subtask(parent_ref, title, status: nil, priority: nil, tags: [], estimate: nil)
+        def create_subtask(parent_ref, title, status: nil, priority: nil, tags: [], estimate: nil, github_issue: nil)
           parent = show(parent_ref)
           return nil unless parent
 
+          ensure_github_issue_linkable!(github_issue)
           subtask_creator = Molecules::SubtaskCreator.new(config: @config)
-          subtask_creator.create(parent, title, status: status, priority: priority, tags: tags, estimate: estimate)
+          created_subtask = subtask_creator.create(
+            parent,
+            title,
+            status: status,
+            priority: priority,
+            tags: tags,
+            estimate: estimate,
+            github_issue: github_issue
+          )
+          sync_linked_issues_for(created_subtask, reason: "create")
+          created_subtask
+        end
+
+        def github_sync(ref: nil, all: false)
+          raise ArgumentError, "Provide --all or a task reference" if !all && (ref.nil? || ref.strip.empty?)
+
+          if all
+            tasks = list(in_folder: "all")
+            linked_tasks = tasks.select { |t| linked_issue_id(t) }
+            results = linked_tasks.map { |task| sync_linked_issues_for(task, reason: "manual-sync") }
+            return summarize_manual_sync_results(results, skipped: tasks.length - linked_tasks.length)
+          end
+
+          task = show(ref)
+          return nil unless task
+
+          unless linked_issue_id(task)
+            return {synced: 0, failed: 0, skipped: 1, task_id: task.id, failures: []}
+          end
+
+          result = sync_linked_issues_for(task, reason: "manual-sync")
+          summary = summarize_manual_sync_results([result], skipped: 0)
+          summary.merge(task_id: task.id)
         end
 
         # Get the root directory.
@@ -347,6 +422,80 @@ module Ace
             item.metadata[key] || item.metadata[key.to_sym] if item.respond_to?(:metadata) && item.metadata
           end
         end
+
+        def sync_needed_after_update?(before_task, after_task, set:, add:, remove:, move_to:)
+          return false unless after_task
+          return true if move_to
+          return true if before_task.path != after_task.path
+          return true if linked_issue_id(before_task) != linked_issue_id(after_task)
+
+          touched_keys = [set, add, remove].compact.flat_map(&:keys).map(&:to_s)
+          touched_keys.any? do |key|
+            key == "title" || key == "status" || key == "github_issue"
+          end
+        end
+
+        def linked_issue_id(task)
+          return nil unless task&.metadata
+
+          issue_id = task.metadata["github_issue"]
+          return nil unless issue_id.to_i.positive?
+
+          issue_id.to_i
+        end
+
+        def extract_desired_github_issue(task, set:, remove:)
+          return nil if set&.key?("github_issue") && !set["github_issue"].to_i.positive?
+          return set["github_issue"].to_i if set&.key?("github_issue") && set["github_issue"].to_i.positive?
+          return nil if Array(remove&.keys).map(&:to_s).include?("github_issue")
+
+          linked_issue_id(task)
+        end
+
+        def ensure_github_issue_linkable!(github_issue, previous_task: nil)
+          return unless github_issue
+
+          Molecules::GithubIssueSyncAdapter.new.validate_link!(issue_id: github_issue, previous_task: previous_task)
+        end
+
+        def sync_linked_issues_for(task, reason:, previous_task: nil)
+          issue_ids = [linked_issue_id(task), linked_issue_id(previous_task)].compact.uniq
+          return sync_result_for(task: task, issues: issue_ids, success: true, reason: reason) if issue_ids.empty?
+
+          adapter = Molecules::GithubIssueSyncAdapter.new
+          adapter.sync_task(task: task, reason: reason, previous_task: previous_task)
+          sync_result_for(task: task, issues: issue_ids, success: true, reason: reason)
+        rescue StandardError => e
+          @last_update_note = "GitHub sync warning for task #{task&.id}: #{e.message}"
+          sync_result_for(task: task, issues: issue_ids, success: false, reason: reason, error: e.message)
+        end
+
+        def sync_result_for(task:, issues:, success:, reason:, error: nil)
+          {
+            task_id: task&.id,
+            issue_ids: issues,
+            success: success,
+            reason: reason,
+            error: error
+          }
+        end
+
+        def summarize_manual_sync_results(results, skipped:)
+          failures = results.reject { |result| result[:success] }.map do |result|
+            {
+              task_id: result[:task_id],
+              issue_ids: result[:issue_ids],
+              error: result[:error]
+            }
+          end
+
+          {
+            synced: results.length - failures.length,
+            failed: failures.length,
+            skipped: skipped,
+            failures: failures
+          }
+        end
       end
     end
   end

data/lib/ace/task/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Task
-    VERSION = '0.31.9'
+    VERSION = '0.36.1'
   end
 end

data/lib/ace/task.rb

@@ -5,6 +5,7 @@ require_relative "task/version"
 # Dependencies
 require "ace/support/items"
 require "ace/b36ts"
+require "ace/git"
 
 # Atoms
 require_relative "task/atoms/task_id_formatter"
@@ -23,6 +24,7 @@ require_relative "task/molecules/task_creator"
 require_relative "task/molecules/subtask_creator"
 require_relative "task/molecules/task_display_formatter"
 require_relative "task/molecules/path_utils"
+require_relative "task/molecules/github_issue_sync_adapter"
 require_relative "task/molecules/task_plan_cache"
 require_relative "task/molecules/task_plan_generator"