ace-task 0.31.0

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

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+require "time"
+require "ace/support/items"
+require "ace/b36ts"
+require_relative "path_utils"
+
+module Ace
+  module Task
+    module Molecules
+      # Manages task plan cache lookup, freshness checks, and artifact writes.
+      class TaskPlanCache
+        LATEST_POINTER = "latest-plan.md"
+
+        def initialize(task_id:, cache_root: ".ace-local/task")
+          @task_id = task_id
+          @cache_root = cache_root
+        end
+
+        def cache_dir
+          File.join(Dir.pwd, @cache_root, @task_id)
+        end
+
+        def prompts_dir
+          File.join(cache_dir, "prompts")
+        end
+
+        def latest_pointer_path
+          File.join(cache_dir, LATEST_POINTER)
+        end
+
+        def resolve_latest_plan
+          from_pointer = resolve_from_pointer
+          return from_pointer if from_pointer
+
+          plan_files.max_by { |path| File.mtime(path) }
+        end
+
+        def fresh?(plan_path, task_file:)
+          return false unless File.file?(plan_path)
+
+          metadata = read_metadata(plan_path)
+          return false unless metadata
+
+          fresh_task_file?(metadata, task_file) && fresh_context_files?(metadata)
+        end
+
+        def write_plan(content:, model:, task_file:, context_files:, prompt_files: nil)
+          FileUtils.mkdir_p(cache_dir)
+
+          plan_path = build_unique_plan_path
+
+          metadata = {
+            "task_id" => @task_id,
+            "generated_at" => Time.now.utc.iso8601,
+            "model" => model,
+            "task_file" => {
+              "path" => relative_path(task_file),
+              "mtime" => File.mtime(task_file).to_i
+            },
+            "context_files" => context_files.map { |path|
+              {
+                "path" => relative_path(path),
+                "mtime" => File.mtime(path).to_i
+              }
+            }
+          }
+
+          if prompt_files
+            metadata["prompt_files"] = prompt_files.transform_values { |path|
+              relative_path(path)
+            }
+          end
+
+          body = "#{YAML.dump(metadata)}---\n\n"
+          body << content.to_s.rstrip
+          body << "\n"
+          File.write(plan_path, body)
+
+          File.write(latest_pointer_path, "#{File.basename(plan_path)}\n")
+          File.write(
+            File.join(cache_dir, "latest-plan.meta.yml"),
+            YAML.dump(metadata)
+          )
+          plan_path
+        end
+
+        private
+
+        def resolve_from_pointer
+          pointer = latest_pointer_path
+          return nil unless File.exist?(pointer)
+
+          if File.symlink?(pointer)
+            target = File.expand_path(File.readlink(pointer), cache_dir)
+            return target if valid_plan_file?(target)
+            return nil
+          end
+
+          target_ref = File.read(pointer).strip
+          return nil if target_ref.empty?
+
+          target = if target_ref.start_with?("/")
+            target_ref
+          else
+            File.expand_path(target_ref, cache_dir)
+          end
+          return target if valid_plan_file?(target)
+
+          nil
+        rescue Errno::ENOENT
+          nil
+        end
+
+        def plan_files
+          return [] unless Dir.exist?(cache_dir)
+
+          Dir.glob(File.join(cache_dir, "*-plan.md"))
+            .select { |path| valid_plan_file?(path) }
+        end
+
+        def valid_plan_file?(path)
+          File.file?(path) && path.end_with?("-plan.md")
+        end
+
+        def read_metadata(plan_path)
+          content = File.read(plan_path)
+          frontmatter, = Ace::Support::Items::Atoms::FrontmatterParser.parse(content)
+          frontmatter.is_a?(Hash) ? frontmatter : nil
+        rescue
+          nil
+        end
+
+        def fresh_task_file?(metadata, task_file)
+          task_meta = metadata["task_file"]
+          return false unless task_meta.is_a?(Hash)
+
+          tracked_path = resolve_tracked_path(task_meta["path"])
+          tracked_mtime = task_meta["mtime"].to_i
+          return false unless tracked_path == File.expand_path(task_file)
+          return false unless File.exist?(tracked_path)
+
+          File.mtime(tracked_path).to_i == tracked_mtime
+        end
+
+        def fresh_context_files?(metadata)
+          context_files = Array(metadata["context_files"])
+          return true if context_files.empty?
+
+          context_files.all? do |ctx|
+            next false unless ctx.is_a?(Hash)
+
+            tracked_path = resolve_tracked_path(ctx["path"])
+            tracked_mtime = ctx["mtime"].to_i
+            File.exist?(tracked_path) && File.mtime(tracked_path).to_i == tracked_mtime
+          end
+        end
+
+        def resolve_tracked_path(path)
+          return "" if path.nil? || path.to_s.empty?
+          return path if path.start_with?("/")
+
+          File.expand_path(path, Dir.pwd)
+        end
+
+        def relative_path(path)
+          Ace::Task::Molecules::PathUtils.relative_path(path)
+        end
+
+        MAX_UNIQUE_ATTEMPTS = 10
+
+        def build_unique_plan_path
+          base_id = Ace::B36ts.encode(Time.now.utc, format: :"2sec")
+          MAX_UNIQUE_ATTEMPTS.times do |attempt|
+            suffix = attempt.zero? ? "" : "-#{attempt}"
+            path = File.join(cache_dir, "#{base_id}#{suffix}-plan.md")
+            return path unless File.exist?(path)
+          end
+
+          raise Ace::Support::Cli::Error.new(
+            "Failed to generate unique plan path after #{MAX_UNIQUE_ATTEMPTS} attempts. " \
+            "Clear .ace-local/task/#{@task_id}/ and retry."
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "ace/core"
+require_relative "path_utils"
+require_relative "task_plan_prompt_builder"
+
+module Ace
+  module Task
+    module Molecules
+      # Generates implementation plans from task specs using ace-llm backend.
+      class TaskPlanGenerator
+        DEFAULT_TIMEOUT = 600
+
+        # After generate(), contains { system_file:, prompt_file: } if file-based prompts were used
+        attr_reader :prompt_paths
+
+        def initialize(model:, timeout: DEFAULT_TIMEOUT, client: nil, cli_args: nil)
+          @model = model
+          @timeout = timeout
+          @client = client
+          @cli_args = cli_args
+          @prompt_paths = nil
+        end
+
+        def generate(task:, context_files:, cache_dir: nil)
+          if cache_dir
+            generate_with_file_prompts(task, cache_dir)
+          else
+            generate_with_inline_prompt(task, context_files)
+          end
+        rescue LoadError => e
+          raise Ace::Support::Cli::Error.new(
+            "Plan generation backend unavailable: #{e.message}. " \
+            "Ensure ace-llm is installed/configured, or provide --model."
+          )
+        rescue Ace::Support::Cli::Error
+          raise
+        rescue RuntimeError, IOError, Errno::ENOENT, Errno::ECONNREFUSED, Timeout::Error => e
+          raise Ace::Support::Cli::Error.new(
+            "Plan generation failed: #{e.message}. Retry with --refresh or choose a working --model."
+          )
+        end
+
+        private
+
+        def generate_with_file_prompts(task, cache_dir)
+          builder = TaskPlanPromptBuilder.new(
+            task: task,
+            cache_dir: cache_dir
+          )
+          paths = builder.build
+          @prompt_paths = paths
+
+          response = llm_client.query(
+            @model,
+            File.read(paths[:prompt_file]),
+            system: File.read(paths[:system_file]),
+            timeout: @timeout,
+            fallback: false,
+            cli_args: @cli_args
+          )
+
+          extract_text(response)
+        end
+
+        def generate_with_inline_prompt(task, context_files)
+          prompt = build_prompt(task, context_files)
+          response = llm_client.query(
+            @model,
+            prompt,
+            system: nil,
+            timeout: @timeout,
+            fallback: false,
+            cli_args: @cli_args
+          )
+
+          extract_text(response)
+        end
+
+        def extract_text(response)
+          text = response[:text].to_s.strip
+          if text.empty?
+            raise Ace::Support::Cli::Error.new(
+              "Plan generation failed: backend returned empty output. Retry with --refresh or --model."
+            )
+          end
+
+          text
+        end
+
+        def build_prompt(task, context_files)
+          task_content = File.read(task.file_path)
+          context_section = if context_files.empty?
+            "No additional context files were captured for this task."
+          else
+            context_files.map { |path| "- #{relative_path(path)}" }.join("\n")
+          end
+
+          <<~PROMPT
+            Create a concrete implementation plan for task #{task.id}.
+
+            Requirements:
+            - Plan against the behavioral spec structure.
+            - Explicitly cover: Interface Contract, Error Handling, Edge Cases, Success Criteria.
+            - Cover operating modes when relevant: dry-run, force/refresh, verbose, quiet.
+            - If details are missing, include a "Behavioral Gaps" section (do not invent hidden assumptions).
+            - Include concrete acceptance checks and validation commands.
+            - Keep output as markdown only.
+
+            Output format — anchored checklist:
+            - Each step must have a stable ID (e.g., S01, S02).
+            - Include `path:line` anchors for file locations where changes apply.
+            - List dependencies between steps explicitly.
+            - Include per-step verification commands.
+            - End with a freshness summary listing input files and their expected state.
+
+            Task spec path:
+            #{relative_path(task.file_path)}
+
+            Captured context files:
+            #{context_section}
+
+            Task spec content:
+            #{task_content}
+          PROMPT
+        end
+
+        def relative_path(path)
+          Ace::Task::Molecules::PathUtils.relative_path(path)
+        end
+
+        def llm_client
+          return @client if @client
+
+          require "ace/llm"
+          Ace::LLM::QueryInterface
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require "ace/b36ts"
+
+module Ace
+  module Task
+    module Molecules
+      # Assembles and persists prompt files for task plan generation.
+      # System prompt = project context + task/plan workflow (composed via ace-bundle).
+      # User prompt = ace-bundle <task.s.md> (task spec + bundle: frontmatter context).
+      # Config files saved alongside output for debugging/introspection.
+      # Files stored in .ace-local/task/<task-id>/prompts/.
+      class TaskPlanPromptBuilder
+        def initialize(task:, cache_dir:)
+          @task = task
+          @cache_dir = cache_dir
+        end
+
+        # Returns { system_file: path, prompt_file: path }
+        def build
+          FileUtils.mkdir_p(prompts_dir)
+          timestamp = Ace::B36ts.encode(Time.now.utc, format: :"2sec")
+
+          {
+            system_file: build_system_prompt(timestamp),
+            prompt_file: build_user_prompt(timestamp)
+          }
+        end
+
+        private
+
+        def prompts_dir
+          File.join(@cache_dir, "prompts")
+        end
+
+        def build_system_prompt(timestamp)
+          config_path = File.join(prompts_dir, "#{timestamp}-system.config.md")
+          output_path = File.join(prompts_dir, "#{timestamp}-system.md")
+          write_system_config(config_path)
+          run_ace_bundle(config_path, output_path)
+          output_path
+        end
+
+        def build_user_prompt(timestamp)
+          config_path = File.join(prompts_dir, "#{timestamp}-user.config.md")
+          output_path = File.join(prompts_dir, "#{timestamp}-user.md")
+          FileUtils.cp(@task.file_path, config_path)
+          run_ace_bundle(@task.file_path, output_path)
+          output_path
+        end
+
+        def write_system_config(path)
+          File.write(path, <<~CONFIG)
+            ---
+            bundle:
+              params:
+                format: markdown-xml
+              base: tmpl://agent/plan-mode
+              sections:
+                workflow:
+                  title: Planning Workflow
+                  files:
+                    - wfi://task/plan
+                project_context:
+                  title: Project Context
+                  presets:
+                    - project
+                repeat_instruction:
+                  title: Plan Mode Reminder
+                  files:
+                    - tmpl://agent/plan-mode
+            ---
+          CONFIG
+        end
+
+        def run_ace_bundle(input, output_path)
+          _stdout, status = Open3.capture2(
+            "ace-bundle", input, "--format", "markdown-xml", "--output", output_path
+          )
+          unless status.success?
+            raise Ace::Support::Cli::Error.new("ace-bundle failed for: #{input}")
+          end
+        rescue Errno::ENOENT
+          raise Ace::Support::Cli::Error.new("ace-bundle not found (required for prompt building)")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../atoms/task_id_formatter"
+require_relative "task_loader"
+require_relative "subtask_creator"
+
+module Ace
+  module Task
+    module Molecules
+      # Reparents tasks: promote subtask to standalone, convert to orchestrator,
+      # or demote standalone to subtask of another task.
+      class TaskReparenter
+        # @param root_dir [String] Root directory for tasks
+        # @param config [Hash] Configuration hash
+        def initialize(root_dir:, config: {})
+          @root_dir = root_dir
+          @config = config
+        end
+
+        # Reparent a task based on the target value.
+        #
+        # @param task [Models::Task] The task to reparent
+        # @param target [String] "none" (promote), "self" (orchestrator), or a parent ref
+        # @param resolve_ref [Proc] Callable that resolves a ref to a Task (for "<ref>" case)
+        # @return [Models::Task] The reparented task at its new location
+        def reparent(task, target:, resolve_ref:)
+          case target.downcase
+          when "none"
+            promote_to_standalone(task)
+          when "self"
+            convert_to_orchestrator(task)
+          else
+            demote_to_subtask(task, parent_ref: target, resolve_ref: resolve_ref)
+          end
+        end
+
+        private
+
+        # Promote a subtask to a standalone task at root level.
+        # Moves the folder to root, strips parent from frontmatter, assigns new standalone ID.
+        def promote_to_standalone(task)
+          unless task.subtask?
+            raise ArgumentError, "Task #{task.id} is already a standalone task"
+          end
+
+          # Generate new standalone ID preserving the original timestamp
+          raw_b36ts = Atoms::TaskIdFormatter.reconstruct(base_task_id(task.id))
+          new_item_id = Atoms::TaskIdFormatter.format(raw_b36ts)
+          new_id = new_item_id.formatted_id
+
+          # Extract slug from current folder name
+          slug = extract_slug(task.path, task.id)
+
+          # Build new folder/file names
+          new_folder_name = Atoms::TaskIdFormatter.folder_name(new_id, slug)
+          new_dir = File.join(@root_dir, new_folder_name)
+
+          raise ArgumentError, "Destination already exists: #{new_dir}" if File.exist?(new_dir)
+
+          # Move the folder
+          FileUtils.mv(task.path, new_dir)
+
+          # Rename spec file and update frontmatter
+          old_spec_basename = File.basename(task.file_path)
+          new_spec_basename = "#{new_folder_name}.s.md"
+          old_spec_in_new_dir = File.join(new_dir, old_spec_basename)
+          new_spec_path = File.join(new_dir, new_spec_basename)
+
+          File.rename(old_spec_in_new_dir, new_spec_path) if old_spec_basename != new_spec_basename
+
+          # Update frontmatter: change ID, remove parent
+          update_frontmatter(new_spec_path) do |fm|
+            fm["id"] = new_id
+            fm.delete("parent")
+          end
+
+          loader = TaskLoader.new
+          loader.load(new_dir, id: new_id)
+        end
+
+        # Convert a standalone task into an orchestrator with itself as first subtask.
+        # Creates orchestrator spec in current dir, renames current spec to subtask .a.
+        def convert_to_orchestrator(task)
+          if task.subtask?
+            raise ArgumentError, "Cannot convert subtask #{task.id} to orchestrator — promote first"
+          end
+
+          slug = extract_slug(task.path, task.id)
+
+          # Create subtask ID using first subtask char (0)
+          next_char = SubtaskCreator::SUBTASK_CHARS[0]
+          subtask_id = "#{task.id}.#{next_char}"
+          subtask_folder_name = "#{next_char}-#{slug}"
+          subtask_dir = File.join(task.path, subtask_folder_name)
+
+          raise ArgumentError, "Subtask directory already exists: #{subtask_dir}" if File.exist?(subtask_dir)
+
+          FileUtils.mkdir_p(subtask_dir)
+
+          # Move current spec file into subtask dir with renamed filename
+          subtask_spec_name = "#{subtask_id}-#{slug}.s.md"
+          subtask_spec_path = File.join(subtask_dir, subtask_spec_name)
+          FileUtils.mv(task.file_path, subtask_spec_path)
+
+          # Update subtask frontmatter: new ID, add parent
+          update_frontmatter(subtask_spec_path) do |fm|
+            fm["id"] = subtask_id
+            fm["parent"] = task.id
+          end
+
+          # Create orchestrator spec file
+          orch_spec_name = "#{File.basename(task.path)}.s.md"
+          orch_spec_path = File.join(task.path, orch_spec_name)
+
+          orch_frontmatter = Atoms::TaskFrontmatterDefaults.build(
+            id: task.id,
+            status: task.status,
+            priority: task.priority,
+            tags: task.tags
+          )
+          orch_content = Ace::Support::Items::Atoms::FrontmatterSerializer.serialize(orch_frontmatter)
+          File.write(orch_spec_path, "#{orch_content}\n\n# #{task.title}\n")
+
+          loader = TaskLoader.new
+          loader.load(task.path, id: task.id)
+        end
+
+        # Demote a standalone task to a subtask of another parent.
+        def demote_to_subtask(task, parent_ref:, resolve_ref:)
+          parent_task = resolve_ref.call(parent_ref)
+          raise ArgumentError, "Parent task '#{parent_ref}' not found" unless parent_task
+
+          if task.id == parent_task.id
+            raise ArgumentError, "Cannot reparent task to itself"
+          end
+
+          # Allocate next subtask char
+          existing_chars = scan_existing_subtask_chars(parent_task.path, parent_task.id)
+          next_char = allocate_next_char(existing_chars)
+
+          # Build new subtask ID
+          new_id = "#{parent_task.id}.#{next_char}"
+          slug = extract_slug(task.path, task.id)
+          new_folder_name = "#{next_char}-#{slug}"
+          new_dir = File.join(parent_task.path, new_folder_name)
+
+          raise ArgumentError, "Destination already exists: #{new_dir}" if File.exist?(new_dir)
+
+          # Move folder into parent
+          FileUtils.mv(task.path, new_dir)
+
+          # Rename spec file
+          old_spec_basename = File.basename(task.file_path)
+          new_spec_basename = "#{new_id}-#{slug}.s.md"
+          old_spec_in_new_dir = File.join(new_dir, old_spec_basename)
+          new_spec_path = File.join(new_dir, new_spec_basename)
+
+          File.rename(old_spec_in_new_dir, new_spec_path) if old_spec_basename != new_spec_basename
+
+          # Update frontmatter: new ID, set parent
+          update_frontmatter(new_spec_path) do |fm|
+            fm["id"] = new_id
+            fm["parent"] = parent_task.id
+          end
+
+          loader = TaskLoader.new
+          loader.load(new_dir, id: new_id)
+        end
+
+        # Extract the base task ID (without subtask char) from a potentially dotted ID
+        # "8pp.t.q7w.a" => "8pp.t.q7w"
+        def base_task_id(id)
+          parts = id.split(".")
+          if parts.length > 3
+            parts[0..2].join(".")
+          else
+            id
+          end
+        end
+
+        # Extract slug from folder path and task ID.
+        def extract_slug(path, id)
+          folder = File.basename(path)
+
+          # Try full ID prefix first: "8pp.t.q7w.0-slug" or "8pp.t.q7w-slug"
+          prefix = "#{id}-"
+          return folder[prefix.length..] if folder.start_with?(prefix)
+
+          # Try short format: "0-slug" (subtask char + dash + slug)
+          parts = id.split(".")
+          if parts.length > 3
+            char_prefix = "#{parts.last}-"
+            return folder[char_prefix.length..] if folder.start_with?(char_prefix)
+          end
+
+          folder
+        end
+
+        # Update frontmatter in a spec file, yielding the hash for modification.
+        def update_frontmatter(file_path)
+          content = File.read(file_path)
+          frontmatter, body = Ace::Support::Items::Atoms::FrontmatterParser.parse(content)
+          body = body.sub(/\A\n/, "")
+
+          yield frontmatter
+
+          new_content = Ace::Support::Items::Atoms::FrontmatterSerializer.rebuild(frontmatter, body)
+          tmp_path = "#{file_path}.tmp.#{Process.pid}"
+          File.write(tmp_path, new_content)
+          File.rename(tmp_path, file_path)
+        rescue
+          File.unlink(tmp_path) if tmp_path && File.exist?(tmp_path)
+          raise
+        end
+
+        # Reuse subtask char allocation logic from SubtaskCreator.
+        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
+
+        def allocate_next_char(existing_chars)
+          SubtaskCreator::SUBTASK_CHARS.each do |char|
+            return char unless existing_chars.include?(char)
+          end
+
+          raise RangeError, "Maximum number of subtasks (#{SubtaskCreator::MAX_SUBTASKS}) exceeded"
+        end
+      end
+    end
+  end
+end