ace-task 0.37.5 → 0.38.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 722bb3a4374541de1d0b486d404772f5a46d02546f05c46e8dcc4595eeb2a5ef
-  data.tar.gz: 98d289a6740f8ecdbb65b31e96af5cf5b1b851c97214eb449e46ede6baf20939
+  metadata.gz: dd08e12e78dbfc24fe3e60bc184f1053ca85a77f2e1b9eb3bd8f4390131cbe90
+  data.tar.gz: 51805310a020a9426cbf89c3cd079344c8960ecdb97cce13a75e717c679b3989
 SHA512:
-  metadata.gz: 740ebb0c5b0e3c2ae9068717f8b8c6e2aee0896f9160bf1df7889975cdede6aa10ace2c392ae9cbede915e78ccf151e6cf4a78b0c22826e9f76aec75ef324e79
-  data.tar.gz: f1b69097da5391ec1554cf9debc11867f587b29321b74cc5cc9dfdf8e87899387a9dc08fb5adeec8a87ee135e5b24405d16542823e35290d9f8a6d8998855970
+  metadata.gz: 94dc2fedb1dcc5133570aec5c7086c0c2cb43b84e84860fd75f27e29978c65511744cb81573e73f6203ac86982e208165b9f6901331f4e72ae9cbf8e8cde47bf
+  data.tar.gz: 62f5b092a0ed387ca9830ffa4b7d02c63bd9ce7084c3e6c389fe757ba6ad296122e25b8bae89bced72377f665c48c3266e89ed1f4ffae307e9008a3358b8482f

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.38.0] - 2026-09-28
+
+### Added
+- Dependency-aware `--sort=smart` for `ace-task list`: ready tasks (dependencies done or archived, or the task itself done/archived) list first under the existing priority/position ordering; tasks with unmet dependencies follow in a topological tail ordered by fewest dependency hops to readiness; dependency cycles render last with a `↺cycle` marker instead of hiding. Missing dependency references stay unmet and never crash listing; `id`, `priority`, and `created` sorts are unchanged.
+
+## [0.37.6] - 2026-09-27
+
+### Technical
+- Stub the GitHub sync adapter during pending replay in tests.
+
 ## [0.37.5] - 2026-09-26
 
 ### Added

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

@@ -36,7 +36,7 @@ module Ace
           option :in, type: :string, aliases: %w[-i], desc: "Filter by folder (next=root only [default], all=everything, maybe, archive)"
           option :root, type: :string, aliases: %w[-r], desc: "Override root path (subpath within tasks root)"
           option :filter, type: :array, aliases: %w[-f], desc: "Filter by key:value (repeatable, supports key:a|b and key:!value)"
-          option :sort, type: :string, aliases: %w[-S], desc: "Sort order: smart (default), id, priority, created"
+          option :sort, type: :string, aliases: %w[-S], desc: "Sort order: smart (default, dependency-aware), id, priority, created"
 
           option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
           option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
@@ -63,7 +63,8 @@ module Ace
 
             puts Ace::Task::Molecules::TaskDisplayFormatter.format_list(
               tasks, total_count: manager.last_list_total,
-              global_folder_stats: manager.last_folder_counts
+              global_folder_stats: manager.last_folder_counts,
+              cycle_ids: manager.last_list_cycle_ids
             )
           end
         end

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

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "ace/support/items"
+
+module Ace
+  module Task
+    module Molecules
+      # Dependency-aware ordering for the smart list sort.
+      #
+      # Ready tasks (every dependency satisfied, or the task itself done or
+      # archived) come first under the existing smart comparator. Tasks with
+      # unmet dependencies follow in a topological tail ordered by dependency
+      # depth (fewest hops to readiness first, with the smart comparator as
+      # tie-breaker). Tasks caught in a dependency cycle render last so cycles
+      # stay visible instead of hiding or looping.
+      class DependencyAwareSmartSorter
+        # Status that satisfies a dependency.
+        SATISFIED_STATUSES = %w[done].freeze
+        # Folder that satisfies a dependency regardless of status (archived).
+        ARCHIVE_FOLDER = "_archive"
+
+        # Ordered listing plus the ids of cyclic tasks (for list rendering).
+        Result = Struct.new(:tasks, :cycle_ids)
+
+        # @param tasks [Array<Models::Task>] Tasks in the current listing
+        # @param score_fn [Proc] ->(task) { Float } existing smart score
+        # @param pin_accessor [Proc] ->(task) { position, nil } pinned position
+        # @param external_statuses [Hash{String => Array(String, String)}]
+        #   [status, special_folder] for dependency references outside the
+        #   listing (e.g. archived); absent entries count as unmet.
+        # @return [Result]
+        def self.sort(tasks, score_fn:, pin_accessor:, external_statuses: {})
+          return Result.new([], []) if tasks.nil? || tasks.empty?
+
+          index = {}
+          tasks.each { |task| index[task.id] = task }
+
+          unmet_deps = {}
+          tasks.each do |task|
+            deps = normalize_dependencies(task.dependencies)
+            unmet_deps[task.id] = deps.reject { |dep| satisfied?(dep, index, external_statuses) }
+          end
+
+          ready = []
+          unmet_ids = {}
+          tasks.each do |task|
+            if unmet_deps[task.id].empty? || satisfied_state?(task.status, task.special_folder)
+              ready << task
+            else
+              unmet_ids[task.id] = true
+            end
+          end
+
+          cycle_ids = cyclic_ids(index, unmet_deps)
+          cycle_lookup = cycle_ids.each_with_object({}) { |id, lookup| lookup[id] = true }
+          cycle_ids.each { |id| unmet_ids.delete(id) }
+
+          depths = depth_map(index, unmet_deps, unmet_ids)
+
+          ordered = order_group(ready, score_fn, pin_accessor)
+          unmet_ids.keys.group_by { |id| depths[id] }.sort.each do |_depth, ids|
+            ordered.concat(order_group(ids.map { |id| index[id] }, score_fn, pin_accessor))
+          end
+          cyclic_tasks = tasks.select { |task| cycle_lookup[task.id] }
+          ordered.concat(order_group(cyclic_tasks, score_fn, pin_accessor))
+
+          Result.new(ordered, cycle_ids)
+        end
+
+        class << self
+          private
+
+          def order_group(group, score_fn, pin_accessor)
+            return [] if group.empty?
+
+            Ace::Support::Items::Molecules::SmartSorter.sort(
+              group, score_fn: score_fn, pin_accessor: pin_accessor
+            )
+          end
+
+          def normalize_dependencies(raw)
+            Array(raw).compact.map(&:to_s)
+          end
+
+          # A dependency is satisfied when the referenced task is done or
+          # archived. References outside the listing consult external_statuses;
+          # unknown references stay unmet so a task cannot appear ready.
+          def satisfied?(dep_id, index, external_statuses)
+            task = index[dep_id]
+            return satisfied_state?(task.status, task.special_folder) if task
+
+            external = external_statuses[dep_id]
+            return satisfied_state?(external[0], external[1]) if external
+
+            false
+          end
+
+          def satisfied_state?(status, special_folder)
+            SATISFIED_STATUSES.include?(status.to_s.downcase) || special_folder == ARCHIVE_FOLDER
+          end
+
+          # Cyclic ids: members of any strongly connected component of the
+          # unmet-dependency graph larger than one, plus self-dependencies.
+          def cyclic_ids(index, unmet_deps)
+            edges = {}
+            index.each_key do |id|
+              edges[id] = unmet_deps[id].select { |dep| index.key?(dep) }
+            end
+
+            cyclic = []
+            strongly_connected_cyclic_ids(edges, cyclic)
+            cyclic
+          end
+
+          # Tarjan's algorithm over unmet edges (recursion depth is bounded by
+          # the dependency chain length, which is small for task graphs).
+          def strongly_connected_cyclic_ids(edges, cyclic)
+            counter = 0
+            indices = {}
+            lowlinks = {}
+            stack = []
+            on_stack = {}
+
+            visit = nil
+            visit = lambda do |vertex|
+              indices[vertex] = lowlinks[vertex] = counter
+              counter += 1
+              stack.push(vertex)
+              on_stack[vertex] = true
+
+              edges[vertex].each do |neighbor|
+                if indices.key?(neighbor)
+                  lowlinks[vertex] = [lowlinks[vertex], indices[neighbor]].min if on_stack[neighbor]
+                else
+                  visit.call(neighbor)
+                  lowlinks[vertex] = [lowlinks[vertex], lowlinks[neighbor]].min
+                end
+              end
+
+              if lowlinks[vertex] == indices[vertex]
+                component = []
+                loop do
+                  member = stack.pop
+                  on_stack[member] = false
+                  component << member
+                  break if member == vertex
+                end
+
+                cyclic.concat(component) if component.length > 1 || component.any? { |id| edges[id].include?(id) }
+              end
+            end
+
+            edges.each_key do |vertex|
+              visit.call(vertex) unless indices.key?(vertex)
+            end
+          end
+
+          # Hop distance to the ready/satisfied boundary for unmet acyclic
+          # tasks. Missing, ready, and cyclic dependencies contribute zero, so
+          # traversal stays finite and acyclic by construction.
+          def depth_map(index, unmet_deps, unmet_ids)
+            depths = {}
+            unmet_ids.each_key do |id|
+              compute_depth(id, index, unmet_deps, unmet_ids, depths)
+            end
+            depths
+          end
+
+          def compute_depth(id, index, unmet_deps, unmet_ids, depths)
+            return depths[id] if depths.key?(id)
+
+            deepest = unmet_deps[id].map do |dep|
+              if unmet_ids[dep]
+                compute_depth(dep, index, unmet_deps, unmet_ids, depths)
+              else
+                0
+              end
+            end.max || 0
+            depths[id] = 1 + deepest
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -113,8 +113,9 @@ module Ace
         # @param tasks [Array<Models::Task>] Tasks to format
         # @param total_count [Integer, nil] Total items before folder filtering
         # @param global_folder_stats [Hash, nil] Folder name → count hash from full scan
+        # @param cycle_ids [Array<String>] Dependency-cycle task ids to mark
         # @return [String] Formatted list output
-        def self.format_list(tasks, total_count: nil, global_folder_stats: nil)
+        def self.format_list(tasks, total_count: nil, global_folder_stats: nil, cycle_ids: [])
           stats_line = format_stats_line(
             tasks,
             total_count: total_count,
@@ -124,7 +125,7 @@ module Ace
           body = if tasks.empty?
             "No tasks found."
           else
-            tasks.map { |task| format_list_item(task) }.join("\n")
+            tasks.map { |task| format_list_item(task, cycle_ids: cycle_ids) }.join("\n")
           end
 
           "#{body}\n\n#{stats_line}"
@@ -203,7 +204,7 @@ module Ace
         private_class_method :format_up_next_section, :format_recently_done_section
 
         # Format a single task as a compact list item.
-        def self.format_list_item(task)
+        def self.format_list_item(task, cycle_ids: [])
           c = Ace::Support::Items::Atoms::AnsiColors
           status_sym = colored_status_sym(task.status)
           priority_sym = PRIORITY_LABELS[task.priority] || ""
@@ -219,8 +220,9 @@ module Ace
           subtask_str = task.has_subtasks? ? c.colorize(" \u203a#{task.subtasks.length}", c::DIM) : ""
           tags_str = (task.tags && task.tags.any?) ? c.colorize(" [#{task.tags.join(", ")}]", c::DIM) : ""
           folder_str = task.special_folder ? c.colorize(" (#{task.special_folder})", c::DIM) : ""
+          cycle_str = cycle_ids.include?(task.id) ? c.colorize(" \u21BAcycle", c::DIM) : ""
 
-          "#{status_sym} #{priority_prefix}#{id_str}  #{task.title}#{subtask_str}#{tags_str}#{folder_str}"
+          "#{status_sym} #{priority_prefix}#{id_str}  #{task.title}#{subtask_str}#{tags_str}#{folder_str}#{cycle_str}"
         end
 
         private_class_method :format_list_item

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

@@ -9,7 +9,7 @@ module Ace
       # Uses a custom id_extractor that matches xxx.t.yyy-slug folder names.
       # Excludes subtask folders from primary scan results.
       class TaskScanner
-        attr_reader :last_scan_total, :last_folder_counts
+        attr_reader :last_scan_total, :last_folder_counts, :last_scan_results
 
         # ID extractor for task-format folders: "8pp.t.q7w-fix-login"
         TASK_ID_EXTRACTOR = ->(folder_name) {
@@ -45,6 +45,7 @@ module Ace
         def scan_in_folder(folder)
           results = scan
           @last_scan_total = results.size
+          @last_scan_results = results
           @last_folder_counts = results.group_by(&:special_folder).transform_values(&:size)
           return results if folder.nil?
 

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

@@ -19,7 +19,7 @@ module Ace
         CREATE_RETRY_LIMIT = 3
         class CreateRetriesExhaustedError < StandardError; end
 
-        attr_reader :last_list_total, :last_folder_counts
+        attr_reader :last_list_total, :last_folder_counts, :last_list_cycle_ids
 
         # @param root_dir [String, nil] Override root directory for tasks
         # @param config [Hash, nil] Override configuration
@@ -27,6 +27,8 @@ module Ace
           @config = config || load_config
           @root_dir = root_dir || resolve_root_dir
           @last_update_note = nil
+          @last_list_cycle_ids = []
+          @last_scan_results = []
         end
 
         attr_reader :last_update_note
@@ -94,13 +96,15 @@ module Ace
         # @param in_folder [String, nil] Filter by special folder (default: "next" = root items only)
         # @param tags [Array<String>] Filter by tags (any match)
         # @param filters [Array<String>, nil] Generic filter strings
-        # @param sort [String] Sort order: "smart", "id", "priority", "created" (default: "smart")
+        # @param sort [String] Sort order: "smart" (default, dependency-aware), "id", "priority", "created"
         # @return [Array<Models::Task>] List of tasks
         def list(status: nil, in_folder: "next", tags: [], filters: nil, sort: "smart")
           scanner = Molecules::TaskScanner.new(@root_dir)
           scan_results = scanner.scan_in_folder(in_folder)
           @last_list_total = scanner.last_scan_total
           @last_folder_counts = scanner.last_folder_counts
+          @last_scan_results = scanner.last_scan_results
+          @last_list_cycle_ids = []
 
           loader = Molecules::TaskLoader.new
           tasks = scan_results.filter_map do |sr|
@@ -293,11 +297,36 @@ module Ace
         end
 
         def smart_sort(tasks)
-          Ace::Support::Items::Molecules::SmartSorter.sort(
+          result = Molecules::DependencyAwareSmartSorter.sort(
             tasks,
             score_fn: method(:compute_task_score),
-            pin_accessor: ->(t) { t.metadata&.dig("position") }
+            pin_accessor: ->(t) { t.metadata&.dig("position") },
+            external_statuses: external_dep_statuses(tasks)
           )
+          @last_list_cycle_ids = result.cycle_ids
+          result.tasks
+        end
+
+        # Load statuses for dependency references pointing outside the current
+        # listing (e.g. archived tasks), so smart sort can classify them as
+        # satisfied or unmet.
+        def external_dep_statuses(tasks)
+          listed_ids = {}
+          tasks.each { |t| listed_ids[t.id] = true }
+          external_ids = tasks.flat_map { |t| Array(t.dependencies) }.uniq - listed_ids.keys
+          return {} if external_ids.empty?
+
+          by_id = {}
+          @last_scan_results.each { |sr| by_id[sr.id] = sr }
+
+          loader = Molecules::TaskLoader.new
+          external_ids.each_with_object({}) do |dep_id, statuses|
+            scan_result = by_id[dep_id]
+            next unless scan_result
+
+            dep = loader.load(scan_result.dir_path, id: scan_result.id, special_folder: scan_result.special_folder)
+            statuses[dep_id] = [dep.status, dep.special_folder] if dep
+          end
         end
 
         def compute_task_score(task)

data/lib/ace/task/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Task
-    VERSION = "0.37.5"
+    VERSION = "0.38.0"
   end
 end

data/lib/ace/task.rb

@@ -24,6 +24,7 @@ require_relative "task/molecules/task_loader"
 require_relative "task/molecules/task_creator"
 require_relative "task/molecules/subtask_creator"
 require_relative "task/molecules/task_display_formatter"
+require_relative "task/molecules/dependency_aware_smart_sorter"
 require_relative "task/molecules/path_utils"
 require_relative "task/molecules/github_issue_sync_adapter"
 require_relative "task/molecules/task_plan_cache"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-task
 version: !ruby/object:Gem::Version
-  version: 0.37.5
+  version: 0.38.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-27 00:00:00.000000000 Z
+date: 2026-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-core
@@ -179,6 +179,7 @@ files:
 - lib/ace/task/cli/commands/status.rb
 - lib/ace/task/cli/commands/update.rb
 - lib/ace/task/models/task.rb
+- lib/ace/task/molecules/dependency_aware_smart_sorter.rb
 - lib/ace/task/molecules/github_issue_sync_adapter.rb
 - lib/ace/task/molecules/path_utils.rb
 - lib/ace/task/molecules/subtask_creator.rb