ace-assign 0.37.0 → 0.40.4

data/handbook/workflow-instructions/assign/create.wf.md

@@ -74,7 +74,8 @@ If input is an existing `.yml`/`.yaml` file path:
 
 If input is an exact preset/recipe-style request (for example `work-on-task --taskref 123`):
 - Run `wfi://assign/prepare` to produce normalized job content
-- Continue to hidden-spec rendering (step 4)
+- If prepare reports all requested refs are already terminal (`done/skipped/cancelled`), stop and return that no assignment was created
+- Otherwise continue to hidden-spec rendering (step 4) using the filtered ref set from prepare
 
 #### Path C: Explicit Step or Freeform Intent (Default)
 
@@ -100,7 +101,11 @@ For unmatched phrases:
 Skill-backed steps (for example `work-on-task`) stay high-level in rendered YAML.
 Runtime `ace-assign create` will materialize `assign.source` sub-steps deterministically.
 
-### 4. Render Hidden Spec (Paths B/C)
+### 4. Render Hidden Spec (Paths B/C with Workable Input)
+
+Precondition:
+- Path B: prepare returned workable, filtered content (not an all-terminal abort)
+- Path C: compose resolved at least one actionable step
 
 Create hidden spec directory if missing:
 
@@ -133,6 +138,7 @@ steps:
 Rules:
 - Each invocation writes a new file (no in-place mutation of prior hidden specs).
 - Hidden specs are internal provenance artifacts; users are not required to edit them.
+- Do not render a hidden spec for all-terminal `work-on-task` requests that aborted in Path B.
 
 ### 5. Create Assignment Deterministically
 
@@ -170,6 +176,7 @@ Step 010: ...
 |----------|--------|
 | Unknown explicit phrase | Return unmatched phrase + closest catalog/skill candidates; no assignment created |
 | Conflicting explicit order | Reorder only by hard rule and report the named rule that required it |
+| Path B all requested refs already terminal | Return clear no-op result (`All requested tasks are already terminal (done/skipped/cancelled): ...`, `No assignment created.`); skip hidden-spec render and `ace-assign create` |
 | Hidden-spec render failure | Return concrete render error; no assignment created |
 | `ace-assign create` rejection | Surface CLI error unchanged |
 | `--run` requested but no workable step | Keep create success; report why drive did not continue |
@@ -179,6 +186,8 @@ Step 010: ...
 - Re-running the same request creates a new hidden spec file.
 - Explicit duplicate steps are normalized unless repetition is clearly requested.
 - Explicit steps take precedence over recipe defaults when both are present.
+- Path B mixed refs (terminal + non-terminal) continue with filtered non-terminal refs only.
+- Path B all-terminal refs produce no assignment and no hidden-spec artifact.
 - High-level skill-backed steps may expand into sub-steps at create runtime via `assign.source` metadata.
 - `--run` is a workflow-level create-then-drive handoff, not natural-language parsing in `ace-assign create`.
 - Quiet mode for `ace-assign create` suppresses non-essential output (including provenance line).
@@ -187,6 +196,8 @@ Step 010: ...
 
 - Hidden spec is written under `.ace-local/assign/jobs/` for generated inputs
 - `ace-assign create FILE` receives the rendered spec path
+- Path B all-terminal requests do not render a hidden spec and do not call `ace-assign create`
+- Path B mixed requests render/create from filtered non-terminal refs only
 - Assignment metadata preserves hidden-spec provenance
 - Explicit step requests map to expected steps with explainable ordering
 - Capability skills remain excluded from assign composition
@@ -197,7 +208,7 @@ Step 010: ...
 
 ```bash
 # Validate intent-resolution language exists in create workflow
-rg -n "explicit|phrase|advisory|assign.source|--run" ace-assign/handbook/workflow-instructions/assign/create.wf.md
+rg -n "explicit|phrase|advisory|assign.source|--run|already terminal|No assignment created" ace-assign/handbook/workflow-instructions/assign/create.wf.md
 
 # Validate hidden-spec references remain present
 rg -n "\.ace-local/assign/jobs|Created from hidden spec" ace-assign
@@ -212,4 +223,4 @@ After assignment creation:
 
 ```bash
 /as-assign-drive <assignment-id>
-```
+```

data/handbook/workflow-instructions/assign/prepare.wf.md

@@ -11,7 +11,7 @@ ace-docs:
 
 ## Purpose
 
-Transform informal instructions OR preset names into a structured job.yaml file that can be used with `ace-assign create job.yaml`. This workflow bridges the gap between high-level intent and the structured work queue format.
+Transform informal instructions OR preset names into a structured job.yaml file that can be used with `ace-assign create --yaml job.yaml`. This workflow bridges the gap between high-level intent and the structured work queue format.
 
 ## Input Formats
 
@@ -227,6 +227,38 @@ From informal instructions:
 - "tasks 148, 149, 150" → `taskrefs: ["148", "149", "150"]`
 - "PR 45" → `pr_number: "45"`
 
+### 3.1 Resolve Requested Taskrefs and Filter Terminal Tasks (`work-on-task` only)
+
+Apply this step when preparing the `work-on-task` preset.
+
+1. Resolve requested refs to concrete task refs first (before any filtering):
+   - `--taskref` single value
+   - comma-separated `--taskrefs`
+   - ranges like `148-152`
+   - patterns like `240.*`
+2. For each resolved ref, run:
+
+```bash
+ace-task show <taskref>
+```
+
+3. Parse the reported status using `Ace::Task::Atoms::TaskValidationRules::TERMINAL_STATUSES` as the source of truth:
+   - If status is terminal (`done`, `skipped`, `cancelled`) → add to `skipped_terminal_refs`
+   - Otherwise (`pending`, `draft`, `in-progress`, `blocked`) → keep in `effective_taskrefs`
+4. Preserve existing invalid-ref behavior:
+   - If a ref cannot be resolved/found, fail with the existing invalid task reference path.
+5. Branch by result:
+   - Mixed set (`effective_taskrefs` non-empty, `skipped_terminal_refs` non-empty):
+     - Continue with `effective_taskrefs`
+     - Report skipped refs clearly (example: `Skipped terminal tasks (done/skipped/cancelled): 149`)
+   - All-terminal set (`effective_taskrefs` empty, `skipped_terminal_refs` non-empty):
+     - Stop before preset expansion and before job generation
+     - Report:
+       - `All requested tasks are already terminal (done/skipped/cancelled): <refs>`
+       - `No assignment created.`
+
+`effective_taskrefs` is now the source of truth for downstream expansion, hidden spec rendering, and mark-tasks-done behavior.
+
 ### 4. Apply Customizations (if prose provided)
 
 Parse modifications:
@@ -246,6 +278,8 @@ params = { "taskrefs" => ["148", "149", "150"], "review_preset" => "batch" }
 steps = Ace::Assign::Atoms::PresetExpander.expand(preset, params)
 ```
 
+For `work-on-task`, pass `effective_taskrefs` from step 3.1 (not the unfiltered requested list).
+
 ### 5.1 Resolve Skill `assign.source` Metadata (Deterministic Runtime Expansion)
 
 After preset expansion, each step with a `skill:` field may declare assignment source metadata via the skill frontmatter:
@@ -331,7 +365,7 @@ Steps: 10 total
   - apply-feedback-3
   - finalize
 
-Start assignment with: ace-assign create job.yaml
+Start assignment with: ace-assign create --yaml job.yaml
 ```
 
 ## Output Format
@@ -373,6 +407,8 @@ steps:
 | Unknown preset | List available presets, ask for selection |
 | Missing required parameter | Prompt for value |
 | Invalid task reference | Show expected formats |
+| Mixed refs include terminal tasks | Skip terminal refs, continue with remaining refs, and report skipped refs |
+| All requested refs are terminal | Stop before expansion/job generation and report: `All requested tasks are already terminal (done/skipped/cancelled): ...` + `No assignment created.` |
 | Unresolved placeholders | Report which parameters need values |
 
 ## Examples
@@ -437,10 +473,35 @@ Expands range to tasks 148, 149, 150, 151, 152.
 
 Expands pattern to match subtasks (requires resolution at prepare time).
 
+### Example 7: Mixed Set with Terminal Tasks
+
+```
+/as-assign-prepare work-on-task --taskrefs 148,149,150
+```
+
+If `149` is terminal (for example `done`):
+- continue with `148,150`
+- report `Skipped terminal tasks (done/skipped/cancelled): 149`
+
+### Example 8: All Requested Tasks Already Terminal
+
+```
+/as-assign-prepare work-on-task --taskrefs 148,149
+```
+
+If both are terminal:
+- report `All requested tasks are already terminal (done/skipped/cancelled): 148,149`
+- report `No assignment created.`
+- do not generate a job.yaml
+
 ## Success Criteria
 
 - [ ] Input correctly parsed (preset, parameters, or prose)
 - [ ] Preset loaded and parameters injected
+- [ ] Requested refs resolve to concrete task refs before any terminal-status filtering
+- [ ] Terminal filtering uses `Ace::Task::Atoms::TaskValidationRules::TERMINAL_STATUSES`
+- [ ] Mixed requested sets continue with non-terminal refs and report skipped terminal refs
+- [ ] All-terminal requested sets stop before queue/job creation
 - [ ] Expansion directives processed (if present)
 - [ ] Hierarchical steps numbered correctly
 - [ ] Loops expanded into separate steps
@@ -457,7 +518,7 @@ After job.yaml is created:
 /as-assign-create job.yaml
 
 # Or directly:
-ace-assign create job.yaml
+ace-assign create --yaml job.yaml
 
 # Check status
 ace-assign status

data/lib/ace/assign/atoms/preset_loader.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ace
+  module Assign
+    module Atoms
+      # Loads assign presets from project overrides first, then gem defaults.
+      module PresetLoader
+        VALID_PRESET_NAME = /\A[A-Za-z0-9_-]+\z/.freeze
+
+        def self.load(preset_name)
+          name = preset_name.to_s.strip
+          raise Ace::Support::Cli::Error, "Preset name cannot be empty" if name.empty?
+          unless VALID_PRESET_NAME.match?(name)
+            raise Ace::Support::Cli::Error,
+              "Invalid preset name '#{name}'. Allowed characters: letters, numbers, underscore, hyphen."
+          end
+
+          path = resolve_path(name)
+          raise Ace::Support::Cli::Error, "Preset '#{name}' not found" unless path
+
+          data = YAML.safe_load_file(path, aliases: true)
+          unless data.is_a?(Hash)
+            raise Ace::Support::Cli::Error, "Preset '#{name}' is invalid"
+          end
+
+          data
+        rescue Psych::SyntaxError => e
+          raise Ace::Support::Cli::Error, "Invalid YAML in preset '#{name}': #{e.message}"
+        end
+
+        def self.resolve_path(name)
+          project_root = Ace::Support::Fs::Molecules::ProjectRootFinder.find_or_current
+          gem_root = Gem.loaded_specs["ace-assign"]&.gem_dir || File.expand_path("../../../..", __dir__)
+
+          project_path = File.join(project_root, ".ace", "assign", "presets", "#{name}.yml")
+          default_path = File.join(gem_root, ".ace-defaults", "assign", "presets", "#{name}.yml")
+
+          return project_path if File.exist?(project_path)
+          return default_path if File.exist?(default_path)
+
+          nil
+        end
+        private_class_method :resolve_path
+      end
+    end
+  end
+end

data/lib/ace/assign/atoms/preset_step_resolver.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Ace
+  module Assign
+    module Atoms
+      # Resolves preset step definitions by exact or base-name matching.
+      module PresetStepResolver
+        ITERATION_SUFFIX_REGEX = /-\d+\z/.freeze
+
+        def self.find_steps(preset, names)
+          Array(names).map { |name| find_step(preset, name) }
+        end
+
+        def self.find_step(preset, name)
+          requested = name.to_s.strip
+          raise Ace::Support::Cli::Error, "Step name cannot be empty" if requested.empty?
+
+          steps = Array(preset["steps"])
+          if steps.empty?
+            raise Ace::Support::Cli::Error,
+              "Preset '#{preset['name'] || 'unknown'}' has no steps defined. Add a non-empty 'steps' array."
+          end
+
+          exact = steps.find { |step| step_name(step) == requested }
+          return exact if exact
+
+          base = base_name(requested)
+          matched = steps.find { |step| base_name(step_name(step)) == base }
+          return matched if matched
+
+          available = available_names(steps)
+          raise Ace::Support::Cli::Error,
+            "Step '#{requested}' not found in preset '#{preset['name'] || 'unknown'}'. " \
+            "Available: #{available.join(', ')}"
+        end
+
+        def self.base_name(name)
+          name.to_s.sub(ITERATION_SUFFIX_REGEX, "")
+        end
+
+        def self.iteration_name?(name)
+          name.to_s.match?(ITERATION_SUFFIX_REGEX)
+        end
+
+        def self.next_iteration_name(base, existing_names)
+          stem = base_name(base)
+          existing = Array(existing_names).map(&:to_s)
+          numbers = existing.filter_map do |name|
+            match = name.match(/\A#{Regexp.escape(stem)}-(\d+)\z/)
+            match && match[1].to_i
+          end
+
+          next_number = numbers.empty? ? 1 : numbers.max + 1
+          "#{stem}-#{next_number}"
+        end
+
+        def self.step_name(step)
+          step.is_a?(Hash) ? step["name"].to_s : ""
+        end
+        private_class_method :step_name
+
+        def self.available_names(steps)
+          names = steps.map { |step| step_name(step) }.reject(&:empty?)
+          (names + names.map { |name| base_name(name) }).uniq.sort
+        end
+        private_class_method :available_names
+      end
+    end
+  end
+end

data/lib/ace/assign/cli/commands/add.rb

@@ -1,100 +1,304 @@
 # frozen_string_literal: true
 
+require "ace/task"
+require "yaml"
+require "set"
+
 module Ace
   module Assign
     module CLI
       module Commands
-        # Add a new step dynamically
-        #
-        # Supports hierarchical step injection:
-        # - Default: adds after current/last done step
-        # - --after: adds as sibling after specified step
-        # - --after + --child: adds as child of specified step
-        #
-        # @example Add step after current
-        #   ace-assign add fix-tests -i "Fix the failing tests"
-        #
-        # @example Inject sibling after specific step
-        #   ace-assign add verify --after 010 -i "Verify initialization"
-        #   # Creates 011-verify.st.md (renumbers existing 011+ if needed)
-        #
-        # @example Inject child step
-        #   ace-assign add verify --after 010 --child -i "Verify"
-        #   # Creates 010.01-verify.st.md
+        # Add step trees dynamically to a running assignment.
         class Add < Ace::Support::Cli::Command
           include Ace::Support::Cli::Base
           include AssignmentTarget
 
-          desc "Add a new step to the queue dynamically"
+          desc "Add step(s) to the queue dynamically"
 
-          argument :name, required: true, desc: "Step name"
-          option :instructions, aliases: ["-i"], desc: "Step instructions"
+          option :yaml, desc: "Path to YAML file with a top-level steps: array"
+          option :step, desc: "Preset step name(s), comma-separated"
+          option :task, desc: "Task reference to expand from preset child-template"
+          option :preset, desc: "Preset name (required only for --step/--task overrides)"
           option :after, aliases: ["-a"], desc: "Insert after this step number (e.g., 010)"
           option :child, aliases: ["-c"], type: :boolean, default: false, desc: "Insert as child of --after step"
           option :assignment, desc: "Target specific assignment ID"
           option :quiet, aliases: ["-q"], type: :boolean, default: false, desc: "Suppress non-essential output"
           option :debug, aliases: ["-d"], type: :boolean, default: false, desc: "Show debug output"
 
-          def call(name:, **options)
-            # Validate: --child requires --after
-            if options[:child] && !options[:after]
-              raise Ace::Support::Cli::Error, "--child requires --after to specify the parent step"
+          def call(**options)
+            validate_mode_options!(options)
+            validate_child_requires_after!(options)
+
+            target = resolve_assignment_target(options)
+            executor = build_executor_for_target(target)
+
+            mode = selected_mode(options)
+            case mode
+            when :yaml
+              handle_yaml_mode(executor, options)
+            when :step
+              handle_step_mode(executor, options)
+            when :task
+              handle_task_mode(executor, options)
+            else
+              raise Ace::Support::Cli::Error, "Exactly one of --yaml, --step, or --task is required"
             end
+          end
 
-            # Validate: adding child would not exceed MAX_DEPTH
-            if options[:child] && options[:after]
-              parsed = Atoms::StepNumbering.parse(options[:after])
-              max_depth = Atoms::StepNumbering::MAX_DEPTH
-              if parsed[:depth] >= max_depth
-                raise Ace::Support::Cli::Error,
-                  "Cannot add child: would exceed maximum nesting depth of #{max_depth + 1} levels " \
-                  "(parent '#{options[:after]}' is at depth #{parsed[:depth]})"
-              end
+          private
+
+          def validate_mode_options!(options)
+            selected = insertion_modes(options).count { |_, value| !value.to_s.strip.empty? }
+            raise Ace::Support::Cli::Error, "Exactly one of --yaml, --step, or --task is required" if selected.zero?
+            raise Ace::Support::Cli::Error, "--yaml, --step, and --task are mutually exclusive" if selected > 1
+
+            preset = options[:preset].to_s.strip
+            return if preset.empty?
+            return if !options[:step].to_s.strip.empty? || !options[:task].to_s.strip.empty?
+
+            raise Ace::Support::Cli::Error, "--preset requires --step or --task"
+          end
+
+          def validate_child_requires_after!(options)
+            if options[:child] && options[:after].to_s.strip.empty? && options[:task].to_s.strip.empty?
+              raise Ace::Support::Cli::Error, "--child requires --after to specify the parent step"
             end
+          end
 
-            instructions = options[:instructions] || "Complete this step and finish with: ace-assign finish --message report.md"
+          def insertion_modes(options)
+            {
+              yaml: options[:yaml],
+              step: options[:step],
+              task: options[:task]
+            }
+          end
 
-            target = resolve_assignment_target(options)
-            executor = build_executor_for_target(target)
-            result = executor.add(
-              name,
-              instructions,
+          def selected_mode(options)
+            insertion_modes(options).find { |_, value| !value.to_s.strip.empty? }&.first
+          end
+
+          def handle_yaml_mode(executor, options)
+            yaml_path = options[:yaml].to_s.strip
+            steps = load_steps_from_file(yaml_path)
+            result = executor.add_batch(
+              steps: steps,
               after: options[:after],
-              as_child: options[:child]
+              as_child: options[:child],
+              source_file: yaml_path
             )
+            print_yaml_result(result, yaml_path) unless options[:quiet]
+            nil
+          end
 
-            unless options[:quiet]
-              added = result[:added]
-              puts "Created: steps/#{File.basename(added.file_path)}"
-              puts "Number: #{added.number}"
-              puts "Status: #{added.status}"
-
-              if options[:after]
-                if options[:child]
-                  puts "Relationship: child of #{options[:after]}"
-                else
-                  puts "Relationship: sibling after #{options[:after]}"
-                end
-              end
+          def handle_step_mode(executor, options)
+            preset_name = resolve_preset_name(executor, options)
+            preset = Atoms::PresetLoader.load(preset_name)
+            requested = parse_step_names(options[:step])
+            templates = Atoms::PresetStepResolver.find_steps(preset, requested)
+
+            steps = []
+            added_steps = []
+            renumbered = []
+            sibling_cursor = options[:after]
+
+            templates.each do |template|
+              state = executor.status[:state]
+              existing_names = state.steps.map(&:name)
+              step = build_preset_step(template, existing_names: existing_names)
+              steps << step
+
+              inserted = executor.add_batch(
+                steps: [step],
+                after: options[:child] ? options[:after] : sibling_cursor,
+                as_child: options[:child],
+                source_file: "preset:#{preset_name}"
+              )
+
+              inserted_added = Array(inserted[:added])
+              added_steps.concat(inserted_added)
+              renumbered.concat(Array(inserted[:renumbered]))
+              sibling_cursor = inserted_added.first&.number unless options[:child]
+            end
+
+            result = {added: added_steps, renumbered: renumbered.uniq}
+
+            print_step_result(result, steps, after: options[:after]) unless options[:quiet]
+            nil
+          end
+
+          def handle_task_mode(executor, options)
+            preset_name = resolve_preset_name(executor, options)
+            preset = Atoms::PresetLoader.load(preset_name)
+            task_ref = options[:task].to_s.strip
+            raise Ace::Support::Cli::Error, "--task requires a task reference" if task_ref.empty?
+            raise Ace::Support::Cli::Error, "Task not found: #{task_ref}" unless task_manager.show(task_ref)
 
-              if result[:renumbered]&.any?
-                puts
-                puts "Renumbered steps:"
-                result[:renumbered].each do |old_num|
-                  new_num = Atoms::StepNumbering.shift_number(old_num, 1)
-                  puts "  #{old_num} -> #{new_num}"
-                end
+            child_template = preset.dig("expansion", "child-template")
+            unless child_template.is_a?(Hash)
+              raise Ace::Support::Cli::Error, "Preset '#{preset_name}' has no expansion.child-template"
+            end
+
+            parent_step = options[:after].to_s.strip
+            parent_step = detect_batch_parent(executor) if parent_step.empty?
+            if parent_step.to_s.strip.empty?
+              raise Ace::Support::Cli::Error, "No batch parent found. Pass --after <step> to specify."
+            end
+
+            task_step = build_task_step(child_template, task_ref, debug: options[:debug])
+            insert_as_child = options[:child] || options[:after].to_s.strip.empty?
+            result = executor.add_batch(
+              steps: [task_step],
+              after: parent_step,
+              as_child: insert_as_child,
+              source_file: "preset:#{preset_name}:task:#{task_ref}"
+            )
+
+            print_task_result(result, task_ref, parent_step, as_child: insert_as_child) unless options[:quiet]
+            nil
+          end
+
+          def resolve_preset_name(executor, options)
+            explicit = options[:preset].to_s.strip
+            return explicit unless explicit.empty?
+
+            assignment = executor.status[:assignment]
+            Molecules::PresetInferrer.infer_from_assignment(assignment)
+          end
+
+          def parse_step_names(raw)
+            names = raw.to_s.split(",").map(&:strip).reject(&:empty?)
+            raise Ace::Support::Cli::Error, "--step requires at least one step name" if names.empty?
+
+            names
+          end
+
+          def build_preset_step(template, existing_names:)
+            step = deep_dup_hash(template)
+            step_name = step["name"].to_s
+            if Atoms::PresetStepResolver.iteration_name?(step_name)
+              next_name = Atoms::PresetStepResolver.next_iteration_name(
+                Atoms::PresetStepResolver.base_name(step_name),
+                existing_names
+              )
+              step["name"] = next_name
+              existing_names << next_name
+            else
+              existing_names << step_name
+            end
+            step
+          end
+
+          def build_task_step(template, task_ref, debug: false)
+            normalized = template.each_with_object({}) { |(key, value), memo| memo[key.to_s] = value }
+            step = substitute_tokens(normalized, "item" => task_ref)
+            warn_unexpanded_template_tokens(step) if debug
+            step
+          end
+
+          def substitute_tokens(value, replacements)
+            case value
+            when Hash
+              value.each_with_object({}) do |(key, nested), memo|
+                memo[key] = substitute_tokens(nested, replacements)
               end
+            when Array
+              value.map { |item| substitute_tokens(item, replacements) }
+            when String
+              value.gsub(/\{\{([a-zA-Z0-9_]+)\}\}/) do
+                replacements.fetch(Regexp.last_match(1), Regexp.last_match(0))
+              end
+            else
+              value
+            end
+          end
+
+          def warn_unexpanded_template_tokens(value)
+            tokens = collect_template_tokens(value)
+            return if tokens.empty?
 
-              if added.status == :in_progress
-                puts
-                puts "Instructions:"
-                puts added.instructions
+            warn "[ace-assign] Warning: Unexpanded preset template token(s): " \
+                 "#{tokens.join(', ')}. Supported tokens for --task mode: {{item}}"
+          end
+
+          def collect_template_tokens(value, tokens = Set.new)
+            case value
+            when Hash
+              value.each_value { |nested| collect_template_tokens(nested, tokens) }
+            when Array
+              value.each { |item| collect_template_tokens(item, tokens) }
+            when String
+              value.scan(/\{\{([a-zA-Z0-9_]+)\}\}/) do |match|
+                tokens << "{{#{match.first}}}"
               end
             end
+
+            tokens.to_a.sort
           end
 
-          private
+          def detect_batch_parent(executor)
+            state = executor.status[:state]
+
+            batch_parent = state.top_level.find { |step| step.name == "batch-tasks" }
+            return batch_parent.number if batch_parent
+
+            fallback = state.top_level.find do |step|
+              state.children_of(step.number).any? { |child| child.name.start_with?("work-on-") }
+            end
+            fallback&.number
+          end
+
+          def task_manager
+            @task_manager ||= Ace::Task::Organisms::TaskManager.new
+          end
+
+          def load_steps_from_file(path)
+            raise Ace::Support::Cli::Error, "File not found: #{path}" unless File.exist?(path)
+
+            begin
+              data = YAML.safe_load_file(path, aliases: true)
+            rescue Psych::SyntaxError => e
+              raise Ace::Support::Cli::Error, "Invalid YAML in #{path}: #{e.message}"
+            end
+
+            steps = data.is_a?(Hash) ? data["steps"] : nil
+            unless steps.is_a?(Array) && steps.any?
+              raise Ace::Support::Cli::Error, "No steps defined in #{path}"
+            end
+
+            steps
+          end
+
+          def deep_dup_hash(value)
+            Marshal.load(Marshal.dump(value))
+          end
+
+          def print_yaml_result(result, source_path)
+            added_steps = Array(result[:added])
+            puts "Added #{added_steps.size} step(s) from #{File.basename(source_path)}"
+            print_added_steps(added_steps)
+          end
+
+          def print_step_result(result, requested_steps, after: nil)
+            added_steps = Array(result[:added])
+            root_name = requested_steps.first["name"]
+            relation = after.to_s.strip.empty? ? "" : " after #{after}"
+            puts "Added #{root_name} (#{added_steps.size} step(s))#{relation}".strip
+            print_added_steps(added_steps)
+          end
+
+          def print_task_result(result, task_ref, parent_step, as_child:)
+            added_steps = Array(result[:added])
+            relation = as_child ? "under" : "after"
+            puts "Added task #{task_ref} #{relation} #{parent_step}"
+            print_added_steps(added_steps)
+          end
+
+          def print_added_steps(steps)
+            steps.each do |step|
+              fork_suffix = step.context == "fork" ? " (fork)" : ""
+              puts "  #{step.number}: #{step.name} [#{step.status}]#{fork_suffix}"
+            end
+          end
         end
       end
     end