ace-assign 0.37.0

data/lib/ace/assign/molecules/skill_assign_source_resolver.rb

@@ -0,0 +1,376 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "pathname"
+require "date"
+
+module Ace
+  module Assign
+    module Molecules
+      # Resolves assignment metadata from skill frontmatter.
+      #
+      # Flow:
+      # 1) Find SKILL.md by skill name (e.g., "ace-task-work")
+      # 2) Read assign.source URI from skill frontmatter (e.g., wfi://task/work)
+      # 3) Resolve workflow file from URI
+      # 4) Parse workflow assign frontmatter (sub-steps/context)
+      class SkillAssignSourceResolver
+        ASSIGN_CAPABLE_KINDS = %w[workflow orchestration].freeze
+
+        def initialize(project_root: nil, skill_paths: nil, workflow_paths: nil)
+          @project_root = project_root || Ace::Support::Fs::Molecules::ProjectRootFinder.find_or_current
+          configured_skill_paths = skill_paths || Ace::Assign.config["skill_source_paths"]
+          configured_workflow_paths = workflow_paths || Ace::Assign.config["workflow_source_paths"]
+
+          canonical_paths = discover_canonical_skill_source_paths
+          canonical_workflow_paths = discover_canonical_workflow_source_paths
+          override_paths = normalize_paths(configured_skill_paths || [])
+          if canonical_workflow_paths.empty? && (configured_workflow_paths.nil? || configured_workflow_paths.empty?)
+            configured_workflow_paths = discover_workspace_workflow_paths
+          end
+          configured_workflow_paths = canonical_workflow_paths if configured_workflow_paths.nil? || configured_workflow_paths.empty?
+          @skill_paths = (canonical_paths + override_paths).uniq
+          @workflow_paths = (canonical_workflow_paths + normalize_paths(configured_workflow_paths || [])).uniq
+          @skill_index = nil
+        end
+
+        # Resolve assign config for a skill.
+        #
+        # @param skill_name [String] Skill identifier (e.g., "ace-task-work")
+        # @return [Hash, nil] Parsed assign config (keys: :sub_steps, :context, etc.) or nil if not declared
+        # @raise [Ace::Assign::Error] If skill declares an invalid/unresolvable source
+        def resolve_assign_config(skill_name)
+          skill_path = skill_index[skill_name] || find_skill_by_convention(skill_name)
+          return nil unless skill_path
+
+          skill_frontmatter = parse_frontmatter(File.read(skill_path))
+          if assign_capable_skill_frontmatter?(skill_frontmatter) && skill_frontmatter["assign"]
+            validate_assign_source!(skill_frontmatter["assign"], skill_name)
+          end
+
+          assign_block = skill_frontmatter["assign"]
+          return nil unless assign_block.is_a?(Hash)
+
+          source = assign_block["source"]&.to_s&.strip
+          return nil if source.nil? || source.empty?
+
+          workflow_path = resolve_source_uri(source, skill_name)
+          workflow_frontmatter = parse_frontmatter(File.read(workflow_path))
+          parsed = Atoms::AssignFrontmatterParser.parse(workflow_frontmatter)
+
+          unless parsed[:valid]
+            raise Error, "Invalid assign frontmatter in '#{workflow_path}' for skill '#{skill_name}': #{parsed[:errors].join("; ")}"
+          end
+
+          parsed[:config]
+        end
+
+        # List assign-capable canonical skills discovered from skill sources.
+        #
+        # Assign-capable skills are canonical skills with:
+        # - skill.kind: workflow|orchestration
+        # - assign.source present and non-empty
+        #
+        # @return [Array<String>] Skill names
+        # @raise [Ace::Assign::Error] When assign-capable skill has invalid assign metadata
+        def assign_capable_skill_names
+          skill_index.keys.sort.filter do |skill_name|
+            skill_path = skill_index[skill_name]
+            frontmatter = parse_frontmatter(File.read(skill_path))
+            next false unless assign_capable_skill_frontmatter?(frontmatter)
+            next false unless frontmatter["assign"].is_a?(Hash)
+
+            validate_assign_source!(frontmatter["assign"], skill_name)
+            true
+          end
+        end
+
+        # Build assignment step entries from canonical skills.
+        #
+        # Only steps declared under `assign.steps` are emitted here. This keeps
+        # canonical skills authoritative for public skill-backed assignment steps,
+        # while internal helper steps can continue to use catalog templates.
+        #
+        # @return [Array<Hash>] Step definitions keyed by canonical precedence
+        def assign_step_catalog
+          catalog = {}
+
+          each_assign_capable_skill do |skill_name, frontmatter|
+            steps = frontmatter.dig("assign", "steps")
+            workflow_source = frontmatter.dig("assign", "source")&.to_s&.strip
+            workflow_source = frontmatter.dig("skill", "execution", "workflow")&.to_s&.strip if workflow_source.nil? || workflow_source.empty?
+            next unless steps.is_a?(Array)
+
+            steps.each do |step|
+              next unless step.is_a?(Hash)
+
+              step_name = step["name"]&.to_s&.strip
+              next if step_name.nil? || step_name.empty?
+              next if catalog.key?(step_name)
+
+              entry = step.dup
+              entry["name"] = step_name
+              entry["skill"] = skill_name
+              entry["source_skill"] = skill_name
+              entry["workflow"] = workflow_source if workflow_source && !workflow_source.empty?
+              entry["description"] ||= frontmatter["description"]
+              catalog[step_name] = entry
+            end
+          end
+
+          catalog.values
+        end
+
+        # Resolve canonical skill rendering details for a skill-backed step.
+        #
+        # @param skill_name [String]
+        # @return [Hash, nil]
+        def resolve_skill_rendering(skill_name)
+          skill_path = skill_index[skill_name] || find_skill_by_convention(skill_name)
+          return nil unless skill_path
+
+          frontmatter, skill_body = parse_frontmatter_and_body(File.read(skill_path))
+          workflow_source = frontmatter.dig("assign", "source")&.to_s&.strip
+          if workflow_source.nil? || workflow_source.empty?
+            workflow_source = frontmatter.dig("skill", "execution", "workflow")&.to_s&.strip
+          end
+
+          workflow_path = resolve_workflow_path(workflow_source, skill_name)
+          workflow_body = workflow_path ? parse_frontmatter_and_body(File.read(workflow_path)).last.to_s.strip : ""
+
+          {
+            "name" => frontmatter["name"] || skill_name,
+            "description" => frontmatter["description"],
+            "skill" => skill_name,
+            "workflow" => workflow_source,
+            "workflow_path" => workflow_path,
+            "body" => workflow_body.empty? ? skill_body.to_s.strip : workflow_body
+          }
+        end
+
+        def resolve_workflow_rendering(workflow_source, step_name: nil, source_skill: nil)
+          workflow_ref = workflow_source&.to_s&.strip
+          return nil if workflow_ref.nil? || workflow_ref.empty?
+
+          workflow_path = resolve_workflow_path(workflow_ref, step_name || source_skill || workflow_ref)
+          return nil unless workflow_path
+
+          frontmatter, body = parse_frontmatter_and_body(File.read(workflow_path))
+          {
+            "name" => step_name || frontmatter["name"],
+            "description" => frontmatter["description"],
+            "workflow" => workflow_ref,
+            "workflow_path" => workflow_path,
+            "source_skill" => source_skill,
+            "body" => body.to_s.strip
+          }
+        end
+
+        def resolve_workflow_assign_config(workflow_source, step_name: nil, source_skill: nil)
+          rendering = resolve_workflow_rendering(workflow_source, step_name: step_name, source_skill: source_skill)
+          return nil unless rendering && rendering["workflow_path"]
+
+          workflow_frontmatter = parse_frontmatter(File.read(rendering["workflow_path"]))
+          parsed = Atoms::AssignFrontmatterParser.parse(workflow_frontmatter)
+          return nil unless parsed[:valid]
+
+          parsed[:config]
+        end
+
+        # Resolve canonical rendering details for a public step name.
+        #
+        # @param step_name [String]
+        # @return [Hash, nil]
+        def resolve_step_rendering(step_name)
+          entry = assign_step_catalog.find { |step| step["name"] == step_name }
+          return nil unless entry
+
+          workflow_rendering = resolve_workflow_rendering(
+            entry["workflow"],
+            step_name: entry["name"],
+            source_skill: entry["source_skill"] || entry["skill"]
+          )
+          return entry.merge(workflow_rendering) if workflow_rendering
+
+          rendering = resolve_skill_rendering(entry["skill"])
+          return nil unless rendering
+
+          entry.merge(rendering)
+        end
+
+        private
+
+        attr_reader :project_root, :skill_paths, :workflow_paths
+
+        def skill_index
+          @skill_index ||= begin
+            index = {}
+            skill_paths.each do |base_path|
+              Dir.glob(File.join(base_path, "**", "SKILL.md")).sort.each do |path|
+                frontmatter = parse_frontmatter(File.read(path))
+                name = frontmatter["name"]&.to_s
+                index[name] ||= path if name && !name.empty?
+              rescue
+                next
+              end
+            end
+            index
+          end
+        end
+
+        def normalize_paths(paths)
+          paths.map do |path|
+            path_str = path.to_s
+            if Pathname.new(path_str).absolute?
+              path_str
+            else
+              File.expand_path(path_str, project_root)
+            end
+          end
+        end
+
+        def find_skill_by_convention(skill_name)
+          dir_name = skill_name.to_s.tr(":", "_")
+          skill_paths.each do |base_path|
+            candidate = File.join(base_path, dir_name, "SKILL.md")
+            return candidate if File.exist?(candidate)
+          end
+          nil
+        end
+
+        def parse_frontmatter(content)
+          parse_frontmatter_and_body(content).first
+        end
+
+        def parse_frontmatter_and_body(content)
+          lines = content.lines
+          return [{}, content.to_s] unless lines.first&.strip == "---"
+
+          closing_index = lines[1..]&.index { |line| line.strip == "---" }
+          return [{}, content.to_s] unless closing_index
+
+          frontmatter_yaml = lines[1, closing_index].join
+          frontmatter = YAML.safe_load(frontmatter_yaml, permitted_classes: [Date, Time]) || {}
+          body_lines = lines[(closing_index + 2)..] || []
+          [frontmatter, body_lines.join]
+        end
+
+        def assign_capable_skill_frontmatter?(frontmatter)
+          kind = frontmatter.dig("skill", "kind")&.to_s
+          ASSIGN_CAPABLE_KINDS.include?(kind)
+        end
+
+        def validate_assign_source!(assign_block, skill_name)
+          source = assign_block["source"]&.to_s&.strip
+          if source.nil? || source.empty?
+            raise Error, "Missing assign.source for assign-capable skill '#{skill_name}'"
+          end
+        end
+
+        def resolve_workflow_path(workflow_source, reference_name)
+          return nil if workflow_source.nil? || workflow_source.empty?
+          return nil unless workflow_source.start_with?("wfi://")
+
+          resolve_source_uri(workflow_source, reference_name)
+        end
+
+        def each_assign_capable_skill
+          skill_index.each do |skill_name, skill_path|
+            frontmatter = parse_frontmatter(File.read(skill_path))
+            next unless assign_capable_skill_frontmatter?(frontmatter)
+            next unless frontmatter["assign"].is_a?(Hash)
+
+            validate_assign_source!(frontmatter["assign"], skill_name)
+            yield skill_name, frontmatter
+          end
+        end
+
+        def discover_canonical_skill_source_paths
+          discover_protocol_source_paths(
+            protocol: "skill",
+            package_glob: File.join(project_root, "*", ".ace-defaults", "nav", "protocols", "skill-sources", "*.yml")
+          )
+        end
+
+        def discover_canonical_workflow_source_paths
+          discover_protocol_source_paths(
+            protocol: "wfi",
+            package_glob: File.join(project_root, "*", ".ace-defaults", "nav", "protocols", "wfi-sources", "*.yml")
+          )
+        end
+
+        def discover_protocol_source_paths(protocol:, package_glob:)
+          registry_paths = Dir.chdir(project_root) do
+            registry = Ace::Support::Nav::Molecules::SourceRegistry.new
+            registry.sources_for_protocol(protocol).filter_map do |source|
+              next if source.config.is_a?(Hash) && source.config["enabled"] == false
+
+              candidate = resolve_source_directory(source)
+              File.directory?(candidate) ? candidate : nil
+            rescue
+              nil
+            end
+          end
+
+          (registry_paths + discover_package_default_source_paths(package_glob)).uniq
+        end
+
+        def resolve_source_directory(source)
+          candidate = source.full_path
+          return candidate if File.directory?(candidate)
+
+          relative_path = source.config&.dig("relative_path")&.to_s&.strip
+          return nil if relative_path.nil? || relative_path.empty?
+
+          return nil unless source.config_file&.include?("/.ace-defaults/")
+
+          package_root = source.config_file.split("/.ace-defaults/").first
+          fallback = File.expand_path(relative_path, package_root)
+          File.directory?(fallback) ? fallback : nil
+        end
+
+        def discover_package_default_source_paths(source_glob)
+          source_files = Dir.glob(source_glob).sort
+          source_files.filter_map do |source_file|
+            source_data = YAML.safe_load_file(source_file, permitted_classes: [Date, Time]) || {}
+            relative_path = source_data.dig("config", "relative_path")&.to_s&.strip
+            next if relative_path.nil? || relative_path.empty?
+
+            package_root = File.expand_path("../../../../..", source_file)
+            candidate = File.expand_path(relative_path, package_root)
+            File.directory?(candidate) ? candidate : nil
+          rescue
+            nil
+          end
+        end
+
+        def discover_workspace_workflow_paths
+          Dir.glob(File.join(project_root, "*", "handbook", "workflow-instructions")).sort
+        end
+
+        def resolve_source_uri(uri, skill_name)
+          if uri.start_with?("wfi://")
+            resolve_wfi_uri(uri, skill_name)
+          else
+            raise Error, "Unsupported assign.source '#{uri}' for skill '#{skill_name}'. Supported: wfi://..."
+          end
+        end
+
+        def resolve_wfi_uri(uri, skill_name)
+          workflow_name = uri.delete_prefix("wfi://").strip
+          if workflow_name.empty?
+            raise Error, "Empty workflow name in assign.source '#{uri}' for skill '#{skill_name}'"
+          end
+
+          workflow_paths.each do |base_path|
+            candidate = File.join(base_path, "#{workflow_name}.wf.md")
+            return candidate if File.exist?(candidate)
+          end
+
+          searched = workflow_paths.join(", ")
+          raise Error, "Could not resolve assign.source '#{uri}' for skill '#{skill_name}'. Searched: #{searched}"
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/molecules/step_renumberer.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Ace
+  module Assign
+    module Molecules
+      # Handles step file renumbering with cascade support and atomic operations.
+      #
+      # Extracted from AssignmentExecutor to provide:
+      # - Testable renumbering logic
+      # - Transactional rename with rollback on failure
+      # - Parent metadata updates for descendants
+      #
+      # @example Basic usage
+      #   renumberer = StepRenumberer.new(step_writer: step_writer, queue_scanner: scanner)
+      #   renumberer.renumber(steps_dir, ["010", "011"])
+      class StepRenumberer
+        attr_reader :step_writer, :queue_scanner
+
+        def initialize(step_writer:, queue_scanner:)
+          @step_writer = step_writer
+          @queue_scanner = queue_scanner
+        end
+
+        # Renumber steps by shifting their file numbers.
+        # Also cascades to all descendants to prevent orphaning children.
+        #
+        # @param steps_dir [String] Path to steps directory
+        # @param numbers_to_shift [Array<String>] Step numbers to shift
+        # @return [Hash] Result with :renamed (count) and :rollback_needed (bool)
+        def renumber(steps_dir, numbers_to_shift)
+          return {renamed: 0, rollback_needed: false} if numbers_to_shift.empty?
+
+          all_numbers = queue_scanner.step_numbers(steps_dir)
+          sorted_steps = build_shift_list(numbers_to_shift, all_numbers)
+
+          # Track operations for potential rollback
+          completed_renames = []
+          rollback_needed = false
+
+          begin
+            sorted_steps.each do |old_number|
+              new_number = calculate_new_number(old_number, numbers_to_shift)
+              next if new_number == old_number
+
+              # Calculate new parent for frontmatter update
+              new_parent = calculate_new_parent(old_number, numbers_to_shift)
+
+              rename_result = rename_step_files(
+                steps_dir,
+                old_number,
+                new_number,
+                new_parent: new_parent
+              )
+
+              completed_renames << {old: old_number, new: new_number, files: rename_result[:files]}
+            end
+          rescue => e
+            rollback_needed = true
+            rollback_renames(completed_renames)
+            raise e
+          end
+
+          {renamed: completed_renames.size, rollback_needed: rollback_needed}
+        end
+
+        private
+
+        # Build complete list of steps to shift including descendants.
+        #
+        # @param numbers_to_shift [Array<String>] Explicit steps to shift
+        # @param all_numbers [Array<String>] All existing step numbers
+        # @return [Array<String>] Sorted list (deepest children first)
+        def build_shift_list(numbers_to_shift, all_numbers)
+          all_to_shift = []
+          numbers_to_shift.each do |num|
+            all_to_shift << num
+            # Find all descendants (steps starting with "num.")
+            all_numbers.each do |n|
+              all_to_shift << n if Atoms::StepNumbering.child_of?(n, num)
+            end
+          end
+          all_to_shift.uniq!
+
+          # Sort in reverse by full number (deeper children first, then parents)
+          # This prevents filename collisions and ensures proper cascade
+          all_to_shift.sort.reverse
+        end
+
+        # Calculate the new number for a step being shifted.
+        #
+        # @param old_number [String] Current step number
+        # @param numbers_to_shift [Array<String>] Steps explicitly being shifted
+        # @return [String] New step number
+        def calculate_new_number(old_number, numbers_to_shift)
+          if numbers_to_shift.include?(old_number)
+            Atoms::StepNumbering.shift_number(old_number, 1)
+          else
+            # This is a descendant - cascade parent shift
+            parent_old = Atoms::StepNumbering.parse(old_number)[:parent]
+            parent_new = if parent_old && numbers_to_shift.include?(parent_old)
+              Atoms::StepNumbering.shift_number(parent_old, 1)
+            end
+
+            # Replace old parent prefix with new parent prefix
+            if parent_new
+              old_number.sub(/^#{Regexp.escape(parent_old)}/, parent_new)
+            else
+              # Find shifted ancestor
+              ancestor = numbers_to_shift.find { |n| Atoms::StepNumbering.child_of?(old_number, n) }
+              if ancestor
+                new_ancestor = Atoms::StepNumbering.shift_number(ancestor, 1)
+                old_number.sub(/^#{Regexp.escape(ancestor)}/, new_ancestor)
+              else
+                old_number
+              end
+            end
+          end
+        end
+
+        # Calculate new parent number for frontmatter update.
+        #
+        # @param old_number [String] Step being renamed
+        # @param numbers_to_shift [Array<String>] Steps explicitly being shifted
+        # @return [String, nil] New parent number or nil if no parent update needed
+        def calculate_new_parent(old_number, numbers_to_shift)
+          old_parent = Atoms::StepNumbering.parse(old_number)[:parent]
+          return nil unless old_parent
+
+          ancestor = numbers_to_shift.find { |n| old_parent == n || Atoms::StepNumbering.child_of?(old_parent, n) }
+          if ancestor
+            new_ancestor = Atoms::StepNumbering.shift_number(ancestor, 1)
+            old_parent.sub(/^#{Regexp.escape(ancestor)}/, new_ancestor)
+          else
+            old_parent
+          end
+        end
+
+        # Rename step and report files from one number to another.
+        #
+        # @param steps_dir [String] Path to steps directory
+        # @param old_number [String] Old step number
+        # @param new_number [String] New step number
+        # @param new_parent [String, nil] New parent number for frontmatter update
+        # @return [Hash] Result with :files (renamed file paths)
+        def rename_step_files(steps_dir, old_number, new_number, new_parent: nil)
+          renamed_files = []
+
+          # Find step file with this number
+          pattern = File.join(steps_dir, "#{old_number}-*.st.md")
+          step_files = Dir.glob(pattern)
+
+          step_files.each do |old_path|
+            filename = File.basename(old_path)
+            new_filename = filename.sub(/^#{Regexp.escape(old_number)}/, new_number)
+            new_path = File.join(steps_dir, new_filename)
+
+            FileUtils.mv(old_path, new_path)
+            renamed_files << {old_path: old_path, new_path: new_path, type: :step}
+
+            # Add audit trail metadata to track renumbering history
+            metadata = {
+              "renumbered_from" => old_number,
+              "renumbered_at" => Time.now.utc.iso8601
+            }
+            metadata["parent"] = new_parent if new_parent
+            step_writer.update_frontmatter(new_path, metadata)
+          end
+
+          # Also rename any report files
+          cache_dir = File.dirname(steps_dir)
+          reports_dir = File.join(cache_dir, "reports")
+          if File.directory?(reports_dir)
+            report_pattern = File.join(reports_dir, "#{old_number}-*.r.md")
+            report_files = Dir.glob(report_pattern)
+
+            report_files.each do |old_path|
+              filename = File.basename(old_path)
+              new_filename = filename.sub(/^#{Regexp.escape(old_number)}/, new_number)
+              new_path = File.join(reports_dir, new_filename)
+
+              FileUtils.mv(old_path, new_path)
+              renamed_files << {old_path: old_path, new_path: new_path, type: :report}
+            end
+          end
+
+          {files: renamed_files}
+        end
+
+        # Rollback completed renames on failure.
+        #
+        # @param completed_renames [Array<Hash>] List of completed rename operations
+        # @return [Array<Hash>] List of rollback errors (empty if all succeeded)
+        def rollback_renames(completed_renames)
+          rollback_errors = []
+
+          # Reverse order to undo in opposite sequence
+          completed_renames.reverse_each do |rename|
+            rename[:files].each do |file_info|
+              next unless File.exist?(file_info[:new_path])
+
+              FileUtils.mv(file_info[:new_path], file_info[:old_path])
+            rescue => e
+              # Capture rollback errors but continue attempting remaining rollbacks
+              rollback_errors << {
+                file: file_info[:new_path],
+                target: file_info[:old_path],
+                error: e.message
+              }
+            end
+          end
+
+          # Warn about rollback failures if any occurred
+          if rollback_errors.any?
+            warn "[ace-assign] Warning: #{rollback_errors.size} file(s) failed to rollback during renumber recovery:"
+            rollback_errors.each do |err|
+              warn "  - #{err[:file]} -> #{err[:target]}: #{err[:error]}"
+            end
+          end
+
+          rollback_errors
+        end
+      end
+    end
+  end
+end