ace-task 0.31.0

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+
+module Ace
+  module Task
+    module CLI
+      module Commands
+        # ace-support-cli Command class for ace-task show
+        class Show < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc <<~DESC.strip
+            Show task details
+
+            Displays a task by reference (full ID like 8pp.t.q7w, short t.q7w, or suffix q7w).
+          DESC
+
+          example [
+            "q7w                           # Show by suffix shortcut",
+            "8pp.t.q7w                     # Show by full ID",
+            "t.q7w                         # Show by short reference",
+            "q7w --path                    # Print file path only",
+            "q7w --content                 # Print raw markdown content",
+            "q7w --tree                    # Show parent + subtask tree"
+          ]
+
+          argument :ref, required: true, desc: "Task reference (full ID, short ref, or suffix)"
+
+          option :path, type: :boolean, desc: "Print file path only"
+          option :content, type: :boolean, desc: "Print raw markdown content"
+          option :tree, type: :boolean, desc: "Show parent + subtask tree view"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
+          option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
+
+          def call(ref:, **options)
+            manager = Ace::Task::Organisms::TaskManager.new
+            task = manager.show(ref)
+
+            unless task
+              raise Ace::Support::Cli::Error.new("Task '#{ref}' not found")
+            end
+
+            if options[:path]
+              puts task.file_path
+            elsif options[:content]
+              puts File.read(task.file_path)
+            else
+              puts Molecules::TaskDisplayFormatter.format(task, show_content: false)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+
+module Ace
+  module Task
+    module CLI
+      module Commands
+        # ace-support-cli Command class for ace-task status
+        class Status < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc <<~DESC.strip
+            Show task status overview
+
+            Displays up-next tasks, summary stats, and recently completed tasks.
+          DESC
+
+          example [
+            "                             # Default status view",
+            "--up-next-limit 5            # Show 5 up-next tasks",
+            "--recently-done-limit 3      # Show 3 recently done tasks"
+          ]
+
+          option :up_next_limit, type: :integer, desc: "Max up-next tasks to show"
+          option :recently_done_limit, type: :integer, desc: "Max recently-done tasks to show"
+
+          def call(**options)
+            manager = Ace::Task::Organisms::TaskManager.new
+            all_tasks = manager.list(in_folder: "all")
+
+            config = Ace::Task::Molecules::TaskConfigLoader.load
+            limits = resolve_limits(config, options)
+
+            score_fn = ->(task) do
+              ssc = Ace::Support::Items::Atoms::SortScoreCalculator
+              weight = ssc.priority_weight(task.priority)
+              age = task.created_at ? [(Time.now - task.created_at) / 86_400.0, 0].max : 0
+              ssc.compute(priority_weight: weight, age_days: age, status: task.status)
+            end
+
+            smart_sorter = ->(items) do
+              Ace::Support::Items::Molecules::SmartSorter.sort(
+                items,
+                score_fn: score_fn,
+                pin_accessor: ->(t) { t.metadata&.dig("position") }
+              )
+            end
+
+            categorized = Ace::Support::Items::Molecules::StatusCategorizer.categorize(
+              all_tasks,
+              up_next_limit: limits[:up_next],
+              recently_done_limit: limits[:recently_done],
+              pending_statuses: %w[pending],
+              done_statuses: %w[done],
+              up_next_sorter: smart_sorter
+            )
+
+            puts Ace::Task::Molecules::TaskDisplayFormatter.format_status(
+              categorized, all_tasks: all_tasks
+            )
+          end
+
+          private
+
+          def resolve_limits(config, options)
+            status_config = config.dig("task", "status") || {}
+            {
+              up_next: (options[:up_next_limit] || status_config["up_next_limit"] || 3).to_i,
+              recently_done: (options[:recently_done_limit] || status_config["recently_done_limit"] || 9).to_i
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/support/items"
+
+module Ace
+  module Task
+    module CLI
+      module Commands
+        # ace-support-cli Command class for ace-task update
+        class Update < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc <<~DESC.strip
+            Update task metadata and/or move to a folder
+
+            Updates frontmatter fields using set, add, or remove operations.
+            Use --set for scalar fields, --add/--remove for array fields like tags.
+            Use --move-to to relocate to a special folder or back to root.
+          DESC
+
+          example [
+            "q7w --set status=done",
+            "q7w --set status=done,priority=high",
+            "q7w --add tags=shipped --remove tags=pending-review",
+            "q7w --set worktree.branch=my-branch",
+            "q7w --set status=done --move-to archive",
+            "q7w --move-to next",
+            "q7w.a --move-as-child-of none    # Promote subtask to standalone",
+            "q7w --move-as-child-of self      # Convert to orchestrator",
+            "q7w --move-as-child-of abc       # Demote to subtask of abc",
+            "q7w --position first             # Pin to sort before all tasks",
+            "q7w --position last              # Pin to sort after existing tasks",
+            "q7w --position after:abc         # Pin to sort after task abc",
+            "q7w --remove position            # Remove pin, return to auto-sort"
+          ]
+
+          argument :ref, required: true, desc: "Task reference (full ID, short ref, or suffix)"
+
+          option :set, type: :array, desc: "Set field: key=value (comma-separated for multiple)"
+          option :add, type: :array, desc: "Add to array field: key=value (comma-separated for multiple)"
+          option :remove, type: :array, desc: "Remove from array field: key=value (comma-separated for multiple)"
+          option :move_to, type: :string, aliases: %w[-m], desc: "Move to folder (archive, maybe, anytime, next)"
+          option :move_as_child_of, type: :string, desc: "Reparent: <parent_ref>, 'none' (promote), 'self' (orchestrator)"
+          option :position, type: :string, aliases: %w[-p], desc: "Set position: first, last, after:<ref>, before:<ref>"
+
+          option :git_commit, type: :boolean, aliases: %w[--gc], desc: "Auto-commit changes"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
+          option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
+
+          def call(ref:, **options)
+            set_args = Array(options[:set])
+            add_args = Array(options[:add])
+            remove_args = Array(options[:remove])
+            move_to = options[:move_to]
+            move_as_child = options[:move_as_child_of]
+            position_arg = options[:position]
+
+            has_any_op = !set_args.empty? || !add_args.empty? || !remove_args.empty? ||
+              move_to || move_as_child || position_arg
+            unless has_any_op
+              warn "Error: at least one of --set, --add, --remove, --move-to, --move-as-child-of, or --position is required"
+              warn ""
+              warn "Usage: ace-task update REF [--set K=V]... [--move-to FOLDER] [--position first|last|after:REF|before:REF]"
+              raise Ace::Support::Cli::Error.new("No update operations specified")
+            end
+
+            if move_to && move_as_child
+              raise Ace::Support::Cli::Error.new("Cannot use --move-to and --move-as-child-of together")
+            end
+
+            set_hash = parse_kv_pairs(set_args)
+            add_hash = parse_kv_pairs(add_args)
+            remove_hash = parse_kv_pairs(remove_args)
+
+            manager = Ace::Task::Organisms::TaskManager.new
+
+            # Resolve --position into a set or remove operation
+            if position_arg
+              pos_value = resolve_position(position_arg, manager)
+              set_hash["position"] = pos_value
+            end
+
+            task = manager.update(ref, set: set_hash, add: add_hash, remove: remove_hash,
+              move_to: move_to, move_as_child_of: move_as_child)
+
+            unless task
+              raise Ace::Support::Cli::Error.new("Task '#{ref}' not found")
+            end
+
+            if move_as_child
+              puts "Task reparented: #{task.id} #{task.title}"
+            elsif move_to
+              folder_info = task.special_folder || "root"
+              puts "Task updated: #{task.id} #{task.title} → #{folder_info}"
+            else
+              puts "Task updated: #{task.id} #{task.title}"
+            end
+            puts "Info: #{manager.last_update_note}" if manager.last_update_note
+
+            if options[:git_commit]
+              commit_paths = (move_to || move_as_child) ? [manager.root_dir] : [task.path]
+              intention = if move_as_child
+                "reparent task #{task.id}"
+              elsif move_to
+                "update task #{task.id} and move to #{task.special_folder || "root"}"
+              else
+                "update task #{task.id}"
+              end
+              Ace::Support::Items::Molecules::GitCommitter.commit(
+                paths: commit_paths,
+                intention: intention
+              )
+            end
+          end
+
+          private
+
+          # Resolve a --position argument into a B36TS value.
+          # Supports: first, last, after:<ref>, before:<ref>
+          def resolve_position(arg, manager)
+            pg = Ace::Support::Items::Atoms::PositionGenerator
+
+            case arg
+            when "first"
+              pg.first
+            when "last"
+              pg.last
+            when /\Aafter:(.+)\z/
+              target = manager.show($1)
+              raise Ace::Support::Cli::Error.new("Task '#{$1}' not found for position reference") unless target
+
+              target_pos = target.metadata&.dig("position")
+              if target_pos
+                pg.after(target_pos)
+              else
+                # Target has no position — generate a current timestamp
+                pg.last
+              end
+            when /\Abefore:(.+)\z/
+              target = manager.show($1)
+              raise Ace::Support::Cli::Error.new("Task '#{$1}' not found for position reference") unless target
+
+              target_pos = target.metadata&.dig("position")
+              if target_pos
+                pg.before(target_pos)
+              else
+                # Target has no position — generate a very early timestamp
+                pg.first
+              end
+            else
+              raise Ace::Support::Cli::Error.new("Invalid --position value '#{arg}': expected first, last, after:<ref>, or before:<ref>")
+            end
+          end
+
+          # Parse ["key=value", "key=value2"] into {"key" => typed_value, ...}
+          def parse_kv_pairs(args)
+            result = {}
+            args.each do |arg|
+              unless arg.include?("=")
+                raise Ace::Support::Cli::Error.new("Invalid format '#{arg}': expected key=value")
+              end
+
+              parsed = Ace::Support::Items::Atoms::FieldArgumentParser.parse([arg])
+              parsed.each do |key, value|
+                result[key] = if result.key?(key)
+                  Array(result[key]) + Array(value)
+                else
+                  value
+                end
+              end
+            rescue Ace::Support::Items::Atoms::FieldArgumentParser::ParseError => e
+              raise Ace::Support::Cli::Error.new("Invalid argument '#{arg}': #{e.message}")
+            end
+            result
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/task/cli.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+require_relative "version"
+require_relative "cli/commands/create"
+require_relative "cli/commands/show"
+require_relative "cli/commands/list"
+require_relative "cli/commands/update"
+require_relative "cli/commands/doctor"
+require_relative "cli/commands/status"
+require_relative "cli/commands/plan"
+
+module Ace
+  module Task
+    # Flat CLI registry for ace-task (task management).
+    module TaskCLI
+      extend Ace::Support::Cli::RegistryDsl
+
+      PROGRAM_NAME = "ace-task"
+
+      REGISTERED_COMMANDS = [
+        ["create", "Create a new task"],
+        ["show", "Show task details"],
+        ["list", "List tasks"],
+        ["update", "Update task metadata (fields, move, reparent)"],
+        ["doctor", "Run health checks on tasks"],
+        ["status", "Show task status overview"],
+        ["plan", "Resolve or generate implementation plan"]
+      ].freeze
+
+      HELP_EXAMPLES = [
+        'ace-task create "Fix login bug"',
+        'ace-task create "Fix auth" --priority high --tags auth,security',
+        "ace-task show q7w",
+        "ace-task show q7w --tree",
+        "ace-task list --status pending",
+        "ace-task list --in maybe",
+        "ace-task update q7w --set status=done --move-to archive",
+        "ace-task update q7w --set status=done --set priority=high",
+        "ace-task update q7w --move-to next",
+        "ace-task doctor",
+        "ace-task doctor --auto-fix --dry-run",
+        "ace-task status",
+        "ace-task status --up-next-limit 5",
+        "ace-task plan q7w",
+        "ace-task plan q7w --refresh",
+        "ace-task plan q7w --content"
+      ].freeze
+
+      register "create", CLI::Commands::Create
+      register "show", CLI::Commands::Show
+      register "list", CLI::Commands::List
+      register "update", CLI::Commands::Update
+      register "doctor", CLI::Commands::Doctor
+      register "status", CLI::Commands::Status
+      register "plan", CLI::Commands::Plan
+
+      version_cmd = Ace::Support::Cli::VersionCommand.build(
+        gem_name: "ace-task",
+        version: Ace::Task::VERSION
+      )
+      register "version", version_cmd
+      register "--version", version_cmd
+
+      help_cmd = Ace::Support::Cli::HelpCommand.build(
+        program_name: PROGRAM_NAME,
+        version: Ace::Task::VERSION,
+        commands: REGISTERED_COMMANDS,
+        examples: HELP_EXAMPLES
+      )
+      register "help", help_cmd
+      register "--help", help_cmd
+      register "-h", help_cmd
+
+      # Entry point for CLI invocation
+      # @param args [Array<String>] Command-line arguments
+      def self.start(args)
+        Ace::Support::Cli::Runner.new(self).call(args: args)
+      end
+    end
+  end
+end

data/lib/ace/task/models/task.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Ace
+  module Task
+    module Models
+      # Value object representing a task.
+      Task = Struct.new(
+        :id,             # Formatted task ID (e.g., "8pp.t.q7w")
+        :status,         # Task status (e.g., "pending", "in-progress", "done")
+        :title,          # Human-readable title
+        :priority,       # Priority level (e.g., "critical", "high", "medium", "low")
+        :estimate,       # Effort estimate
+        :dependencies,   # Array of task IDs this task depends on
+        :tags,           # Array of tag strings
+        :content,        # Body markdown content
+        :path,           # Directory path
+        :file_path,      # Full path to spec file
+        :special_folder, # Special folder name (e.g., "_maybe", nil if none)
+        :created_at,     # Time decoded from ID
+        :subtasks,       # Array of subtask Task objects (loaded from folder co-location)
+        :parent_id,      # Parent task ID if this is a subtask
+        :metadata,       # Extra frontmatter fields
+        keyword_init: true
+      ) do
+        # Last 3 characters of the ID (shortcut for resolution)
+        def shortcut
+          id[-3..] if id
+        end
+
+        # Whether this task is a subtask (has a parent)
+        def subtask?
+          !parent_id.nil?
+        end
+
+        # Whether this task has subtasks
+        def has_subtasks?
+          subtasks && !subtasks.empty?
+        end
+
+        def to_s
+          "Task(#{id}: #{title})"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Ace
+  module Task
+    module Molecules
+      # Shared path utilities for task plan components.
+      module PathUtils
+        module_function
+
+        def relative_path(path)
+          absolute = File.expand_path(path)
+          cwd = File.expand_path(Dir.pwd)
+          return absolute unless absolute.start_with?("#{cwd}/")
+
+          absolute.delete_prefix("#{cwd}/")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../atoms/task_id_formatter"
+require_relative "../atoms/task_frontmatter_defaults"
+require_relative "task_loader"
+
+module Ace
+  module Task
+    module Molecules
+      # Creates subtasks within a parent task's folder.
+      # Allocates subtask characters sequentially: 0-9 then a-z (max 36 subtasks).
+      class SubtaskCreator
+        # Maximum number of subtasks per parent (0-9 = 10, a-z = 26)
+        MAX_SUBTASKS = 36
+
+        # Ordered sequence of subtask characters
+        SUBTASK_CHARS = (0..35).map { |i| i.to_s(36) }.freeze
+
+        # @param config [Hash] Configuration hash
+        def initialize(config: {})
+          @config = config
+        end
+
+        # Create a subtask within a parent task's folder.
+        #
+        # @param parent_task [Models::Task] Parent task
+        # @param title [String] Subtask title
+        # @param status [String, nil] Initial status
+        # @param priority [String, nil] Priority level
+        # @param tags [Array<String>] Tags
+        # @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)
+          raise ArgumentError, "Title is required" if title.nil? || title.strip.empty?
+
+          # Find next available subtask character
+          existing_chars = scan_existing_subtask_chars(parent_task.path, parent_task.id)
+          next_char = allocate_next_char(existing_chars)
+
+          # Build subtask ID: parent_id + ".{char}"
+          subtask_id = "#{parent_task.id}.#{next_char}"
+
+          # Generate slugs (folder: 5 words, file: 7 words)
+          folder_slug = generate_folder_slug(title)
+          file_slug = generate_file_slug(title)
+
+          # Build folder and file names
+          folder_name = "#{next_char}-#{folder_slug}"
+          subtask_dir = File.join(parent_task.path, folder_name)
+          FileUtils.mkdir_p(subtask_dir)
+
+          # Build frontmatter
+          effective_status = status || @config.dig("task", "default_status") || "pending"
+          frontmatter = Atoms::TaskFrontmatterDefaults.build(
+            id: subtask_id,
+            status: effective_status,
+            priority: priority,
+            tags: tags,
+            created_at: time,
+            parent: parent_task.id,
+            estimate: estimate
+          )
+
+          # Write spec file
+          spec_filename = "#{subtask_id}-#{file_slug}.s.md"
+          spec_file = File.join(subtask_dir, spec_filename)
+          content = build_spec_content(frontmatter: frontmatter, title: title)
+          File.write(spec_file, content)
+
+          # Load and return
+          loader = TaskLoader.new
+          loader.load(subtask_dir, id: subtask_id, load_subtasks: false)
+        end
+
+        private
+
+        # Scan parent directory for existing subtask folders and extract their chars.
+        def scan_existing_subtask_chars(parent_dir, _parent_id)
+          chars = []
+          return chars unless Dir.exist?(parent_dir)
+
+          Dir.entries(parent_dir).sort.each do |entry|
+            next if entry.start_with?(".")
+
+            full_path = File.join(parent_dir, entry)
+            next unless File.directory?(full_path)
+
+            # Short format: "0-slug" or "a-slug"
+            if (short_match = entry.match(/^([a-z0-9])-/))
+              chars << short_match[1]
+            end
+          end
+
+          chars
+        end
+
+        # Allocate the next available subtask character.
+        # @raise [RangeError] If all 36 chars are used
+        def allocate_next_char(existing_chars)
+          SUBTASK_CHARS.each do |char|
+            return char unless existing_chars.include?(char)
+          end
+
+          raise RangeError, "Maximum number of subtasks (#{MAX_SUBTASKS}) exceeded"
+        end
+
+        def generate_folder_slug(title)
+          sanitized = Ace::Support::Items::Atoms::SlugSanitizer.sanitize(title)
+          words = sanitized.split("-")
+          result = words.take(5).join("-")
+          result.empty? ? "subtask" : result
+        end
+
+        def generate_file_slug(title)
+          sanitized = Ace::Support::Items::Atoms::SlugSanitizer.sanitize(title)
+          words = sanitized.split("-")
+          result = words.take(7).join("-")
+          result.empty? ? "subtask" : result
+        end
+
+        def build_spec_content(frontmatter:, title:)
+          serialized = Ace::Support::Items::Atoms::FrontmatterSerializer.serialize(frontmatter)
+          "#{serialized}\n\n# #{title}\n"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "ace/support/fs"
+
+module Ace
+  module Task
+    module Molecules
+      # Loads and merges configuration for ace-task from the cascade:
+      # .ace-defaults/task/config.yml (gem) -> ~/.ace/task/config.yml (user) -> .ace/task/config.yml (project)
+      class TaskConfigLoader
+        DEFAULT_ROOT_DIR = ".ace-tasks"
+
+        # Load configuration with cascade merge
+        # @param gem_root [String] Path to the ace-task gem root
+        # @return [Hash] Merged configuration
+        def self.load(gem_root: nil)
+          gem_root ||= File.expand_path("../../../..", __dir__)
+          new(gem_root: gem_root).load
+        end
+
+        def initialize(gem_root:)
+          @gem_root = gem_root
+        end
+
+        # Load and merge configuration
+        # @return [Hash] Merged configuration
+        def load
+          config = load_defaults
+          config = deep_merge(config, load_user_config)
+          deep_merge(config, load_project_config)
+        end
+
+        # Get the root directory for tasks
+        # @param config [Hash] Configuration hash
+        # @return [String] Absolute path to tasks root directory
+        def self.root_dir(config = nil)
+          config ||= load
+          dir = config.dig("task", "root_dir") || DEFAULT_ROOT_DIR
+
+          if dir.start_with?("/")
+            dir
+          else
+            File.join(Ace::Support::Fs::Molecules::ProjectRootFinder.find_or_current, dir)
+          end
+        end
+
+        private
+
+        def load_defaults
+          path = File.join(@gem_root, ".ace-defaults", "task", "config.yml")
+          load_yaml(path) || {}
+        end
+
+        def load_user_config
+          path = File.join(Dir.home, ".ace", "task", "config.yml")
+          load_yaml(path) || {}
+        end
+
+        def load_project_config
+          path = File.join(Ace::Support::Fs::Molecules::ProjectRootFinder.find_or_current, ".ace", "task", "config.yml")
+          load_yaml(path) || {}
+        end
+
+        def load_yaml(path)
+          return nil unless File.exist?(path)
+
+          YAML.safe_load_file(path, permitted_classes: [Date, Time, Symbol])
+        rescue Errno::ENOENT
+          nil
+        rescue Psych::SyntaxError => e
+          warn "Warning: ace-task config parse error in #{path}: #{e.message}"
+          nil
+        end
+
+        def deep_merge(base, override)
+          return base unless override.is_a?(Hash)
+
+          result = base.dup
+          override.each do |key, value|
+            result[key] = if result[key].is_a?(Hash) && value.is_a?(Hash)
+              deep_merge(result[key], value)
+            else
+              value
+            end
+          end
+          result
+        end
+      end
+    end
+  end
+end