ace-task 0.31.0

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "ace/support/items"
+
+module Ace
+  module Task
+    module Molecules
+      # Wraps ShortcutResolver for task-format IDs (9-char formatted IDs like "8pp.t.q7w").
+      #
+      # Normalizes various reference forms before resolving:
+      #   "8pp.t.q7w"    → full ID lookup (9 chars)
+      #   "t.q7w"        → strip marker, suffix lookup "q7w"
+      #   "q7w"          → bare suffix lookup
+      #   "8pp.t.q7w.a"  → subtask lookup (11 chars: parent + ".{char}")
+      class TaskResolver
+        # Task formatted IDs are 9 chars: "8pp.t.q7w"
+        FULL_ID_LENGTH = 9
+
+        # Short reference pattern: "t.q7w" → extract suffix "q7w"
+        SHORT_REF_PATTERN = /^[a-z]\.([0-9a-z]{3})$/
+
+        # Subtask reference pattern: "8pp.t.q7w.a" (parent ID + dot + single char)
+        SUBTASK_REF_PATTERN = /^([0-9a-z]{3}\.[a-z]\.[0-9a-z]{3})\.([a-z0-9])$/
+
+        # Short subtask reference: "q7w.a" or "t.q7w.a" (suffix + subtask char)
+        SHORT_SUBTASK_REF_PATTERN = /^(?:[a-z]\.)?([0-9a-z]{3})\.([a-z0-9])$/
+
+        # @param scan_results [Array<ScanResult>] Scan results to resolve against
+        def initialize(scan_results)
+          @scan_results = scan_results
+          @resolver = Ace::Support::Items::Molecules::ShortcutResolver.new(
+            scan_results,
+            full_id_length: FULL_ID_LENGTH
+          )
+        end
+
+        # Resolve a task reference to a ScanResult.
+        # Handles full IDs, shortcuts, and subtask references.
+        #
+        # @param ref [String] Task reference (full ID, short, suffix, or subtask)
+        # @param on_ambiguity [Proc, nil] Called with array of matches on ambiguity
+        # @return [ScanResult, nil]
+        def resolve(ref, on_ambiguity: nil)
+          return nil if ref.nil? || ref.empty?
+
+          cleaned = ref.strip.downcase
+
+          # Check for full subtask reference first: "8pp.t.q7w.a"
+          if (subtask_match = cleaned.match(SUBTASK_REF_PATTERN))
+            return resolve_subtask(subtask_match[1], subtask_match[2])
+          end
+
+          # Check for short subtask reference: "q7w.a" or "t.q7w.a"
+          if (short_sub = cleaned.match(SHORT_SUBTASK_REF_PATTERN))
+            suffix = short_sub[1]
+            subtask_char = short_sub[2]
+            parent_result = @resolver.resolve(suffix)
+            return resolve_subtask(parent_result.id, subtask_char) if parent_result
+          end
+
+          normalized = normalize_ref(cleaned)
+          @resolver.resolve(normalized, on_ambiguity: on_ambiguity)
+        end
+
+        private
+
+        def normalize_ref(ref)
+          # Check for short ref pattern: "t.q7w" → "q7w"
+          if (match = ref.match(SHORT_REF_PATTERN))
+            match[1]
+          else
+            ref
+          end
+        end
+
+        # Resolve a subtask reference by finding the parent's scan result,
+        # then looking for the subtask folder within that parent's directory.
+        def resolve_subtask(parent_id, subtask_char)
+          parent_result = @scan_results.find { |sr| sr.id == parent_id }
+          return nil unless parent_result
+
+          subtask_id = "#{parent_id}.#{subtask_char}"
+
+          Dir.entries(parent_result.dir_path).sort.each do |entry|
+            next if entry.start_with?(".")
+
+            full_path = File.join(parent_result.dir_path, entry)
+            next unless File.directory?(full_path)
+
+            # Short format: "0-slug" or "a-slug"
+            short_match = entry.match(/^([a-z0-9])-(.+)$/)
+            next unless short_match
+            next unless short_match[1] == subtask_char
+
+            slug = short_match[2]
+
+            spec_files = Dir.glob(File.join(full_path, "*.s.md"))
+            next if spec_files.empty?
+
+            return Ace::Support::Items::Models::ScanResult.new(
+              id: subtask_id,
+              slug: slug,
+              folder_name: entry,
+              dir_path: full_path,
+              file_path: spec_files.first,
+              special_folder: parent_result.special_folder
+            )
+          end
+
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "ace/support/items"
+
+module Ace
+  module Task
+    module Molecules
+      # Wraps DirectoryScanner for task-format directories.
+      # 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
+
+        # ID extractor for task-format folders: "8pp.t.q7w-fix-login"
+        TASK_ID_EXTRACTOR = ->(folder_name) {
+          match = folder_name.match(/^([0-9a-z]{3}\.[a-z]\.[0-9a-z]{3})-(.+)$/)
+          return nil unless match
+
+          id = match[1]
+          slug = match[2]
+          [id, slug]
+        }
+
+        FILE_PATTERN = "*.s.md"
+
+        # @param root_dir [String] Root directory containing tasks (e.g., ".ace-tasks")
+        def initialize(root_dir)
+          @root_dir = root_dir
+          @scanner = Ace::Support::Items::Molecules::DirectoryScanner.new(
+            root_dir,
+            file_pattern: FILE_PATTERN,
+            id_extractor: TASK_ID_EXTRACTOR
+          )
+        end
+
+        # Scan for all primary tasks (excludes subtask folders).
+        # @return [Array<ScanResult>] Sorted scan results
+        def scan
+          @scanner.scan.reject { |sr| subtask_folder?(sr.folder_name) }
+        end
+
+        # Scan and filter by special folder or virtual filter
+        # @param folder [String, nil] Folder name, virtual filter ("next", "all"), or nil for all
+        # @return [Array<ScanResult>] Filtered scan results
+        def scan_in_folder(folder)
+          results = scan
+          @last_scan_total = results.size
+          @last_folder_counts = results.group_by(&:special_folder).transform_values(&:size)
+          return results if folder.nil?
+
+          virtual = Ace::Support::Items::Atoms::SpecialFolderDetector.virtual_filter?(folder)
+          case virtual
+          when :all then results
+          when :next then results.select { |r| r.special_folder.nil? }
+          else
+            normalized = Ace::Support::Items::Atoms::SpecialFolderDetector.normalize(folder)
+            results.select { |r| r.special_folder == normalized }
+          end
+        end
+
+        # Scan for all items including subtask folders.
+        # @return [Array<ScanResult>] Sorted scan results
+        def scan_all
+          @scanner.scan
+        end
+
+        # Scan for subtask directories within a parent task directory.
+        # Subtask folders follow the pattern: {parent_id}.{char}-{slug}
+        #
+        # @param parent_dir [String] Path to the parent task directory
+        # @param parent_id [String] Formatted parent task ID (e.g., "8pp.t.q7w")
+        # @return [Array<ScanResult>] Subtask scan results, sorted by ID
+        def scan_subtasks(parent_dir, parent_id:)
+          return [] unless Dir.exist?(parent_dir)
+
+          results = []
+          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)
+
+            subtask_id = nil
+            slug = nil
+
+            # Short format: "0-slug" or "a-slug"
+            if (short_match = entry.match(/^([a-z0-9])-(.+)$/))
+              subtask_id = "#{parent_id}.#{short_match[1]}"
+              slug = short_match[2]
+            else
+              next
+            end
+
+            spec_files = Dir.glob(File.join(full_path, FILE_PATTERN))
+            next if spec_files.empty?
+
+            special_folder = Ace::Support::Items::Atoms::SpecialFolderDetector.detect_in_path(
+              full_path, root: @root_dir
+            )
+
+            results << Ace::Support::Items::Models::ScanResult.new(
+              id: subtask_id,
+              slug: slug,
+              folder_name: entry,
+              dir_path: full_path,
+              file_path: spec_files.first,
+              special_folder: special_folder
+            )
+          end
+
+          results.sort_by(&:id)
+        end
+
+        # Check if root directory exists
+        # @return [Boolean]
+        def root_exists?
+          Dir.exist?(@root_dir)
+        end
+
+        private
+
+        # Check if a folder name matches the subtask pattern
+        def subtask_folder?(folder_name)
+          folder_name.match?(/\A[a-z0-9]-/)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require_relative "../atoms/task_file_pattern"
+
+module Ace
+  module Task
+    module Molecules
+      # Validates the directory structure of a tasks root directory.
+      # Checks folder naming, file naming, and structural conventions.
+      class TaskStructureValidator
+        # Task folder naming pattern: {xxx.t.yyy}-{slug}
+        FOLDER_PATTERN = /^[0-9a-z]{3}\.[a-z]\.[0-9a-z]{3}-.+$/
+
+        # @param root_dir [String] Root directory for tasks (e.g., ".ace-tasks")
+        def initialize(root_dir)
+          @root_dir = root_dir
+        end
+
+        # Validate the entire tasks directory structure
+        # @return [Array<Hash>] List of issues found
+        def validate(root_dir = @root_dir)
+          issues = []
+
+          unless Dir.exist?(root_dir)
+            issues << {type: :error, message: "Tasks root directory does not exist", location: root_dir}
+            return issues
+          end
+
+          check_folder_naming(root_dir, issues)
+          check_spec_files(root_dir, issues)
+          check_stale_backups(root_dir, issues)
+          check_empty_directories(root_dir, issues)
+
+          issues
+        end
+
+        private
+
+        # Check that task folders follow {xxx.t.yyy}-{slug} naming
+        def check_folder_naming(root_dir, issues)
+          task_dirs(root_dir).each do |dir|
+            folder_name = File.basename(dir)
+
+            next if folder_name.start_with?("_")
+
+            unless folder_name.match?(FOLDER_PATTERN)
+              issues << {
+                type: :error,
+                message: "Folder name does not match '{id}-{slug}' convention: '#{folder_name}'",
+                location: dir
+              }
+            end
+          end
+        end
+
+        # Check that each task folder has exactly one .s.md spec file (excluding .idea.s.md)
+        def check_spec_files(root_dir, issues)
+          task_dirs(root_dir).each do |dir|
+            folder_name = File.basename(dir)
+            next if folder_name.start_with?("_")
+
+            spec_files = Dir.glob(File.join(dir, Atoms::TaskFilePattern::SPEC_PATTERN))
+              .reject { |f| f.end_with?(".idea.s.md") }
+
+            if spec_files.empty?
+              issues << {
+                type: :warning,
+                message: "No .s.md spec file in task folder",
+                location: dir
+              }
+            elsif spec_files.size > 1
+              issues << {
+                type: :warning,
+                message: "Multiple .s.md spec files in folder (#{spec_files.size} found)",
+                location: dir
+              }
+            end
+          end
+        end
+
+        # Check for stale backup/tmp files
+        def check_stale_backups(root_dir, issues)
+          backup_patterns = [
+            File.join(root_dir, "**", "*.backup.*"),
+            File.join(root_dir, "**", "*.tmp"),
+            File.join(root_dir, "**", "*~")
+          ]
+
+          backup_patterns.each do |pattern|
+            Dir.glob(pattern).each do |file|
+              next if file.include?("/.git/")
+
+              issues << {
+                type: :warning,
+                message: "Stale backup file (safe to delete)",
+                location: file
+              }
+            end
+          end
+        end
+
+        # Check for empty directories
+        def check_empty_directories(root_dir, issues)
+          Dir.glob(File.join(root_dir, "**", "*")).each do |path|
+            next unless File.directory?(path)
+            next if path.include?("/.git/")
+
+            files = Dir.glob(File.join(path, "**", "*")).select { |f| File.file?(f) }
+            if files.empty?
+              issues << {
+                type: :warning,
+                message: "Empty directory (safe to delete)",
+                location: path
+              }
+            end
+          end
+        end
+
+        # Find all immediate subdirectories that look like task folders
+        # (excludes special folders which are containers, includes their children)
+        def task_dirs(root_dir)
+          dirs = []
+
+          Dir.glob(File.join(root_dir, "*")).each do |path|
+            next unless File.directory?(path)
+
+            folder_name = File.basename(path)
+            if folder_name.start_with?("_")
+              # Recurse into special folders
+              Dir.glob(File.join(path, "*")).each do |subpath|
+                dirs << subpath if File.directory?(subpath) && !category_folder?(subpath)
+              end
+            else
+              dirs << path unless category_folder?(path)
+            end
+          end
+
+          dirs
+        end
+
+        # Check if a folder is a category folder (only contains subdirectories, no files)
+        def category_folder?(dir_path)
+          return false unless Dir.exist?(dir_path)
+
+          files = Dir.glob(File.join(dir_path, "*")).select { |f| File.file?(f) }
+          return false if files.any?
+
+          subdirs = Dir.glob(File.join(dir_path, "*")).select { |f| File.directory?(f) }
+          subdirs.any?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require_relative "../molecules/task_scanner"
+require_relative "../molecules/task_frontmatter_validator"
+require_relative "../molecules/task_structure_validator"
+require_relative "../atoms/task_validation_rules"
+
+module Ace
+  module Task
+    module Organisms
+      # Orchestrates comprehensive health checks for the tasks system.
+      # Runs structure validation, frontmatter validation, and scope/status
+      # consistency checks across all tasks in a root directory.
+      class TaskDoctor
+        attr_reader :root_path, :options
+
+        # @param root_path [String] Path to tasks root directory
+        # @param options [Hash] Diagnosis options (:check, :verbose, etc.)
+        def initialize(root_path, options = {})
+          @root_path = root_path
+          @options = options
+          @issues = []
+          @stats = {
+            tasks_scanned: 0,
+            folders_checked: 0,
+            errors: 0,
+            warnings: 0,
+            info: 0
+          }
+        end
+
+        # Run comprehensive health check
+        # @return [Hash] Diagnosis results
+        def run_diagnosis
+          unless @root_path && Dir.exist?(@root_path)
+            return {
+              valid: false,
+              health_score: 0,
+              issues: [{type: :error, message: "Tasks root directory not found: #{@root_path}"}],
+              stats: @stats,
+              duration: 0,
+              root_path: @root_path
+            }
+          end
+
+          @start_time = Time.now
+
+          if options[:check]
+            run_specific_check(options[:check])
+          else
+            run_full_check
+          end
+
+          health_score = calculate_health_score
+
+          {
+            valid: @stats[:errors] == 0,
+            health_score: health_score,
+            issues: @issues,
+            stats: @stats,
+            duration: Time.now - @start_time,
+            root_path: @root_path
+          }
+        end
+
+        # Check if an issue can be auto-fixed
+        # @param issue [Hash] Issue to check
+        # @return [Boolean]
+        def auto_fixable?(issue)
+          return false unless issue[:type] == :error || issue[:type] == :warning
+
+          Molecules::TaskDoctorFixer::FIXABLE_PATTERNS.any? { |pattern| issue[:message].match?(pattern) }
+        end
+
+        private
+
+        def run_full_check
+          run_structure_check
+          run_frontmatter_check
+          run_scope_check
+        end
+
+        def run_specific_check(check_type)
+          case check_type.to_s
+          when "structure"
+            run_structure_check
+          when "frontmatter"
+            run_frontmatter_check
+          when "scope"
+            run_scope_check
+          else
+            add_issue(:error, "Unknown check type: #{check_type}")
+          end
+        end
+
+        def run_structure_check
+          validator = Molecules::TaskStructureValidator.new(@root_path)
+          issues = validator.validate
+
+          issues.each do |issue|
+            add_issue(issue[:type], issue[:message], issue[:location])
+          end
+
+          @stats[:folders_checked] = count_task_folders
+        end
+
+        def run_frontmatter_check
+          scanner = Molecules::TaskScanner.new(@root_path)
+          return unless scanner.root_exists?
+
+          scan_results = scanner.scan
+          @stats[:tasks_scanned] = scan_results.size
+
+          scan_results.each do |scan_result|
+            spec_file = scan_result.file_path
+            next unless spec_file && File.exist?(spec_file)
+
+            issues = Molecules::TaskFrontmatterValidator.validate(
+              spec_file,
+              special_folder: scan_result.special_folder
+            )
+
+            # Filter out scope issues here (handled separately in run_scope_check)
+            issues.reject! { |i| scope_issue?(i[:message]) }
+
+            issues.each do |issue|
+              add_issue(issue[:type], issue[:message], issue[:location])
+            end
+          end
+        end
+
+        def run_scope_check
+          scanner = Molecules::TaskScanner.new(@root_path)
+          return unless scanner.root_exists?
+
+          scan_results = scanner.scan
+
+          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)
+            next unless frontmatter.is_a?(Hash)
+
+            status = frontmatter["status"]
+            special_folder = scan_result.special_folder
+
+            scope_issues = Atoms::TaskValidationRules.scope_consistent?(status, special_folder)
+            scope_issues.each do |issue|
+              add_issue(issue[:type], issue[:message], spec_file)
+            end
+          end
+        end
+
+        def scope_issue?(message)
+          message.include?("not in _archive") ||
+            message.include?("in _archive/ but status") ||
+            message.include?("in _maybe/ with terminal")
+        end
+
+        def count_task_folders
+          return 0 unless Dir.exist?(@root_path)
+
+          count = 0
+          Dir.glob(File.join(@root_path, "*")).each do |path|
+            next unless File.directory?(path)
+
+            count += if File.basename(path).start_with?("_")
+              Dir.glob(File.join(path, "*")).count { |p| File.directory?(p) }
+            else
+              1
+            end
+          end
+          count
+        end
+
+        def add_issue(type, message, location = nil)
+          issue = {type: type, message: message}
+          issue[:location] = location if location
+          @issues << issue
+
+          case type
+          when :error then @stats[:errors] += 1
+          when :warning then @stats[:warnings] += 1
+          when :info then @stats[:info] += 1
+          end
+        end
+
+        def calculate_health_score
+          score = 100
+          score -= @stats[:errors] * 10
+          score -= @stats[:warnings] * 2
+          [[score, 0].max, 100].min
+        end
+      end
+    end
+  end
+end