ace-assign 0.42.4 → 0.55.0

data/lib/ace/assign/organisms/assignment_executor.rb

@@ -12,15 +12,40 @@ module Ace
       # start → advance → complete (with fail/add/retry branches)
       class AssignmentExecutor
         DEFAULT_DYNAMIC_STEP_INSTRUCTIONS = "Complete this step and finish with: ace-assign finish --message report.md".freeze
+        PROJECT_ROOT_SIGNAL = "project_root".freeze
+        CATALOG_SIGNAL = "catalog".freeze
 
         attr_reader :assignment_manager, :queue_scanner, :step_writer, :step_renumberer, :skill_source_resolver
 
-        def initialize(cache_base: nil)
+        class << self
+          def clear_caches!
+            @cache_store = { step_catalog_cache: {} }
+          end
+
+          def cache_store
+            @cache_store ||= { step_catalog_cache: {} }
+          end
+
+          private
+
+          def cached_value(store_key, key)
+            cache_store[store_key][key]
+          end
+
+          def store_cached_value(store_key, key, value)
+            cache_store[store_key][key] = value
+          end
+        end
+
+        def initialize(cache_base: nil, skill_source_resolver: nil, step_catalog: nil)
           @assignment_manager = Molecules::AssignmentManager.new(cache_base: cache_base)
           @queue_scanner = Molecules::QueueScanner.new
           @step_writer = Molecules::StepWriter.new
-          @skill_source_resolver = Molecules::SkillAssignSourceResolver.new
+          @skill_source_resolver = skill_source_resolver || Molecules::SkillAssignSourceResolver.new
           @step_catalog = nil
+          @step_catalog_from_fixture = step_catalog
+          @step_catalog_from_fixture_set = !step_catalog.nil?
+          @step_catalog_loaded = false
           @step_renumberer = Molecules::StepRenumberer.new(
             step_writer: @step_writer,
             queue_scanner: @queue_scanner
@@ -73,12 +98,6 @@ module Ace
             )
           end
 
-          # Mark first workable step as in_progress.
-          # This skips batch parent containers that have incomplete children.
-          initial_state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
-          first_workable = initial_state.next_workable
-          step_writer.mark_in_progress(first_workable.file_path) if first_workable
-
           # Archive source config into task's steps directory and update assignment metadata
           archived_path = archive_source_config(config_path, assignment.id)
           assignment = Models::Assignment.new(
@@ -120,7 +139,6 @@ module Ace
         # Start a pending step.
         #
         # Rules:
-        # - Fails if any step is already in progress (strict mode)
         # - Starts an explicit pending target when provided
         # - Otherwise starts the next workable pending step
         #
@@ -132,7 +150,6 @@ module Ace
           raise AssignmentErrors::NoActive, "No active assignment. Use 'ace-assign create --yaml <job.yaml>' to begin." unless assignment
 
           state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
-          raise StepErrors::InvalidState, "Cannot start: step #{state.current.number} is already in progress. Finish or fail it first." if state.current
 
           fork_root = fork_root&.strip
           target_step = if step_number && !step_number.to_s.strip.empty?
@@ -151,7 +168,8 @@ module Ace
             raise StepErrors::InvalidState, "No pending workable step found."
           end
 
-          step_writer.mark_in_progress(target_step.file_path)
+          validate_start_activation!(state, target_step, fork_root: fork_root)
+          step_writer.mark_active(target_step.file_path)
           assignment_manager.update(assignment)
 
           new_state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
@@ -163,10 +181,10 @@ module Ace
           }
         end
 
-        # Finish an in-progress step and advance queue state.
+        # Finish an active step and update queue state.
         #
         # @param report_content [String] Completion report content
-        # @param step_number [String, nil] Optional in-progress step number to finish
+        # @param step_number [String, nil] Optional active step number to finish
         # @param fork_root [String, nil] Optional subtree root to constrain advancement
         # @return [Hash] Result with completed step and updated state
         def finish_step(report_content:, step_number: nil, fork_root: nil)
@@ -175,7 +193,7 @@ module Ace
 
           state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
           current = find_target_step_for_finish(state, step_number, fork_root)
-          raise Error, "No step currently in progress. Try 'ace-assign start' or 'ace-assign retry'." unless current
+          raise Error, "No step currently active. Try 'ace-assign start' or 'ace-assign retry'." unless current
 
           # Enforce hierarchy: cannot mark parent as done with incomplete children
           if state.has_incomplete_children?(current.number)
@@ -196,18 +214,6 @@ module Ace
           # Re-scan to get fresh state after auto-completions
           state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
 
-          fork_root = fork_root&.strip
-          # Find next step to work on using hierarchical rules.
-          # When fork_root is provided, keep advancement inside that subtree.
-          next_step = if fork_root && !fork_root.empty? && state.find_by_number(fork_root)
-            find_next_step_in_subtree(state, current.number, fork_root)
-          else
-            find_next_step(state, current.number)
-          end
-          if next_step
-            step_writer.mark_in_progress(next_step.file_path)
-          end
-
           assignment_manager.update(assignment)
 
           new_state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
@@ -219,13 +225,7 @@ module Ace
           }
         end
 
-        # Complete current step with report and advance
-        #
-        # Legacy bridge: preserves single-call semantics for fork-run callers.
-        # Previously, advance() auto-started the next step as a side effect.
-        # The new start/finish split makes this explicit, but advance() retains
-        # the auto-start behavior for subtree entry so fork-run workflows
-        # (which call advance() with fork_root) continue to work unchanged.
+        # Complete current step with report content from a file.
         #
         # @param report_path [String] Path to report file
         # @param fork_root [String, nil] Optional subtree root to constrain advancement
@@ -233,26 +233,6 @@ module Ace
         def advance(report_path, fork_root: nil)
           raise ConfigErrors::NotFound, "Report file not found: #{report_path}" unless File.exist?(report_path)
 
-          # Auto-start the next workable subtree step when fork_root is given but
-          # no step in the subtree is yet in_progress (subtree entry case).
-          fork_root_str = fork_root&.strip
-          if fork_root_str && !fork_root_str.empty?
-            assignment = assignment_manager.find_active
-            if assignment
-              state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
-              active_in_subtree = state.in_progress_in_subtree(fork_root_str)
-              if active_in_subtree.size > 1
-                active_refs = active_in_subtree.map { |step| "#{step.number}(#{step.name})" }.join(", ")
-                raise StepErrors::InvalidState, "Cannot advance subtree #{fork_root_str}: multiple steps are in progress (#{active_refs})."
-              end
-
-              if active_in_subtree.empty?
-                next_workable = state.next_workable_in_subtree(fork_root_str)
-                step_writer.mark_in_progress(next_workable.file_path) if next_workable
-              end
-            end
-          end
-
           finish_step(report_content: File.read(report_path), fork_root: fork_root)
         end
 
@@ -260,13 +240,13 @@ module Ace
         #
         # @param message [String] Error message
         # @return [Hash] Result with updated state
-        def fail(message)
+        def fail(message, fork_root: nil)
           assignment = assignment_manager.find_active
           raise AssignmentErrors::NoActive, "No active assignment. Use 'ace-assign create --yaml <job.yaml>' to begin." unless assignment
 
           state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
-          current = state.current
-          raise Error, "No step currently in progress. Try 'ace-assign add' to add a new step or 'ace-assign retry' to retry a failed step." unless current
+          current = find_target_step_for_fail(state, fork_root)
+          raise Error, "No step currently active. Try 'ace-assign add' to add a new step or 'ace-assign retry' to retry a failed step." unless current
 
           # Mark step as failed
           step_writer.mark_failed(current.file_path, error_message: message)
@@ -290,7 +270,7 @@ module Ace
         # @param after [String, nil] Insert after this step number (optional)
         # @param as_child [Boolean] Insert as child of 'after' step (default: false, sibling)
         # @return [Hash] Result with new step
-        def add(name, instructions, after: nil, as_child: false, added_by: nil, extra: {})
+        def add(name, instructions, after: nil, as_child: false, added_by: nil, extra: {}, fork_root: nil)
           assignment = assignment_manager.find_active
           raise AssignmentErrors::NoActive, "No active assignment. Use 'ace-assign create --yaml <job.yaml>' to begin." unless assignment
 
@@ -298,6 +278,7 @@ module Ace
           raise Error, "Step name cannot be empty." if step_name.empty?
 
           state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
+          after, as_child = normalize_scoped_insertion_anchor(state, after: after, as_child: as_child, fork_root: fork_root)
           existing_numbers = queue_scanner.step_numbers(assignment.steps_dir)
 
           # Validate --after step exists
@@ -319,9 +300,6 @@ module Ace
             queue_scanner.step_numbers(assignment.steps_dir)
           end
 
-          # Determine initial status upfront to avoid redundant I/O
-          initial_status = state.current ? :pending : :in_progress
-
           # Build added_by metadata for audit trail
           added_by ||= if after && as_child
             "child_of:#{after}"
@@ -339,7 +317,7 @@ module Ace
             number: new_number,
             name: step_name,
             instructions: instructions,
-            status: initial_status,
+            status: :pending,
             added_by: added_by,
             parent: as_child ? after : nil,
             extra: extra_frontmatter
@@ -371,7 +349,7 @@ module Ace
         # @note Structural validation is performed for the full batch before any writes.
         #   Runtime I/O failures can still interrupt insertion after partial writes.
         # @return [Hash] Result with added steps and final state
-        def add_batch(steps:, after: nil, as_child: false, source_file: nil)
+        def add_batch(steps:, after: nil, as_child: false, source_file: nil, fork_root: nil)
           unless steps.is_a?(Array) && steps.any?
             source_label = source_file.to_s.strip.empty? ? "batch input" : source_file
             raise Error, "No steps defined in #{source_label}"
@@ -383,6 +361,12 @@ module Ace
 
           prevalidate_batch_trees!(steps)
 
+          assignment = assignment_manager.find_active
+          raise AssignmentErrors::NoActive, "No active assignment. Use 'ace-assign create --yaml <job.yaml>' to begin." unless assignment
+
+          state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
+          after, as_child = normalize_scoped_insertion_anchor(state, after: after, as_child: as_child, fork_root: fork_root)
+
           added_steps = []
           renumbered = []
           sibling_cursor = after
@@ -400,7 +384,6 @@ module Ace
             sibling_cursor = inserted[:root_number] unless as_child
           end
 
-          assignment = assignment_manager.find_active
           state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
           {
             assignment: assignment,
@@ -414,7 +397,7 @@ module Ace
         #
         # @param step_ref [String] Step number or reference to retry
         # @return [Hash] Result with new retry step
-        def retry_step(step_ref)
+        def retry_step(step_ref, fork_root: nil)
           assignment = assignment_manager.find_active
           raise AssignmentErrors::NoActive, "No active assignment. Use 'ace-assign create --yaml <job.yaml>' to begin." unless assignment
 
@@ -423,16 +406,18 @@ module Ace
           # Find the step to retry
           original = state.find_by_number(step_ref.to_s)
           raise StepErrors::NotFound, "Step #{step_ref} not found in queue" unless original
+          validate_retry_scope!(state, original, fork_root)
 
           # Get existing numbers
           existing_numbers = queue_scanner.step_numbers(assignment.steps_dir)
 
           # Insert after all current steps (at end of queue before pending)
           # Find last done or failed step
-          base_number = if state.current
-            state.current.number
-          elsif state.last_done
-            state.last_done.number
+          scoped_state = scoped_retry_state(state, assignment: assignment, fork_root: fork_root)
+          base_number = if scoped_state.current
+            scoped_state.current.number
+          elsif scoped_state.last_done
+            scoped_state.last_done.number
           else
             original.number
           end
@@ -573,7 +558,10 @@ module Ace
         # @param sub_steps [Array<String>] Declared sub-step names
         # @return [Hash] Parent step config for runtime queue
         def build_split_parent_step(step:, parent_number:, parent_context:, sub_steps:)
-          source_skill = step["skill"]
+          source_skill = step["source_skill"] || step["skill"]
+          if (source_skill.nil? || source_skill.to_s.strip.empty?) && step["source"].to_s.start_with?("skill://")
+            source_skill = step["source"].to_s.delete_prefix("skill://").strip
+          end
           original_text = normalize_instructions(step["instructions"]).strip
           definition = find_step_definition("split-subtree-root") || {}
 
@@ -600,6 +588,7 @@ module Ace
           )
           parent_step.delete("sub_steps")
           parent_step.delete("sub-steps")
+          parent_step.delete("source")
           parent_step.delete("skill")
           parent_step.delete("workflow")
           parent_step["source_skill"] = source_skill if source_skill
@@ -652,9 +641,11 @@ module Ace
           if parent_context == "fork"
             lines.concat(
               [
-                "Delegate this subtree into forked context:",
+                "Unscoped driver action: delegate this subtree into forked context:",
                 "- ace-assign fork-run --assignment <assignment-id>@{{parent_number}}",
-                "Inside the forked agent, continue execution within this subtree scope only."
+                "Scoped forked agent action: do not call fork-run again for {{parent_number}}.",
+                "If this scoped root is active and no child step is active yet: ace-assign start --assignment <assignment-id>@{{parent_number}}",
+                "After a child step becomes active, continue execution within this subtree scope only."
               ]
             )
           else
@@ -712,6 +703,13 @@ module Ace
             child["workflow"] = step_def["workflow"] if step_def["workflow"]
             preserve_explicit_skill = (sub_steps_origin == "explicit")
             child["skill"] = step_def["skill"] if step_def["skill"] && (preserve_explicit_skill || !step_def["workflow"])
+            child["source"] = if step_def["source"]
+              step_def["source"]
+            elsif step_def["workflow"]
+              step_def["workflow"]
+            elsif step_def["skill"]
+              "skill://#{step_def["skill"]}"
+            end
 
             context_default = step_def.dig("context", "default")
             child["context"] = context_default if context_default && !fork_context_value?(parent_context)
@@ -811,14 +809,9 @@ module Ace
           when "pre-commit-review"
             pre_commit_review_action_instructions(task_hint: task_hint)
           when "verify-test"
-            "- Identify modified packages#{task_hint}.\n- For each modified package, run: cd <package> && ace-test --profile 6\n- If no package-level code changes are present, mark this step skipped with a clear reason."
+            "- Identify modified packages#{task_hint}.\n- For each modified package, run: cd <package> && ace-test all --profile 6\n- This subtree step verifies modified packages only; do not run the monorepo suite here.\n- If no package-level code changes are present, mark this step skipped with a clear reason."
           when /\Arelease(?:-.+)?\z/
             "- Release all modified packages and update both package and root changelogs.\n- Follow semantic versioning expectations for this step.\n- When auto-detecting packages, include `git diff origin/main...HEAD --name-only` in addition to working-tree state — prior steps may have already committed changes."
-          when "verify-e2e"
-            "- Check change scope: run `git diff origin/main --name-only` to list modified files.\n" \
-            "- **Skip criteria**: If ALL modified files match `*.md`, `*.yml` (non-CI config), `.ace-tasks/**`, or `.ace-retros/**`, skip E2E verification — mark step done with \"skipped: docs/task-spec only changes, no runnable code affected\".\n" \
-            "- Otherwise: detect modified packages, run E2E scenarios for each package with `test/e2e/` scenarios#{task_hint}.\n" \
-            "- If no modified package has E2E scenarios, mark step done with \"skipped: no E2E scenarios for modified packages\"."
           else
             "- Execute the #{sub_name} step."
           end
@@ -861,6 +854,8 @@ module Ace
             "instructions" => rendered_instructions,
             "workflow" => rendering["workflow"]
           )
+          resolved_source = resolved_step_source(step, rendering)
+          materialized["source"] = resolved_source if resolved_source && !resolved_source.empty?
           unless split_child_without_explicit_fork?(step)
             context_default = rendering.dig("context", "default")
             materialized["context"] ||= context_default if context_default
@@ -879,6 +874,24 @@ module Ace
         end
 
         def resolve_step_rendering(step)
+          explicit_source = step["source"]&.to_s&.strip
+          if explicit_source && !explicit_source.empty?
+            canonical_step = find_step_definition_with_source_fallback(step, explicit_source: explicit_source)
+            if canonical_step && split_child_without_explicit_fork?(step)
+              canonical_step = canonical_step.dup
+              canonical_step.delete("context")
+              canonical_step.delete("fork")
+            end
+            source_skill = step["source_skill"]&.to_s&.strip
+            source_skill = canonical_step&.dig("source_skill") if source_skill.nil? || source_skill.empty?
+            rendering = skill_source_resolver.resolve_source_rendering(
+              explicit_source,
+              step_name: step["name"]&.to_s,
+              source_skill: source_skill
+            )
+            return canonical_step ? canonical_step.merge(rendering || {}) : rendering if rendering
+          end
+
           explicit_workflow = step["workflow"]&.to_s&.strip
           if explicit_workflow && !explicit_workflow.empty?
             canonical_step = find_step_definition(step["name"]&.to_s)
@@ -1039,6 +1052,15 @@ module Ace
         end
 
         def resolve_step_assign_config(step)
+          source_ref = step["source"]&.to_s&.strip
+          if source_ref && !source_ref.empty?
+            return skill_source_resolver.resolve_source_assign_config(
+              source_ref,
+              step_name: step["name"]&.to_s,
+              source_skill: step["source_skill"]&.to_s
+            )
+          end
+
           explicit_workflow = step["workflow"]&.to_s&.strip
           if explicit_workflow && !explicit_workflow.empty?
             return skill_source_resolver.resolve_workflow_assign_config(
@@ -1119,30 +1141,120 @@ module Ace
           Atoms::CatalogLoader.find_by_name(step_catalog, step_name)
         end
 
+        def find_step_definition_with_source_fallback(step, explicit_source:)
+          step_name = step["name"]&.to_s
+          canonical_step = find_step_definition(step_name)
+          return canonical_step if canonical_step
+
+          source = explicit_source.to_s.strip
+          return nil if source.empty?
+
+          source_skill = step["source_skill"]&.to_s&.strip
+          source_skill = source.delete_prefix("skill://").strip if source_skill.to_s.empty? && source.start_with?("skill://")
+
+          step_catalog.find do |entry|
+            next unless entry.is_a?(Hash)
+
+            entry_source = entry["source"]&.to_s&.strip
+            entry_workflow = entry["workflow"]&.to_s&.strip
+            entry_source_skill = entry["source_skill"]&.to_s&.strip
+            entry_skill = entry["skill"]&.to_s&.strip
+
+            next true if entry_source == source || entry_workflow == source
+            next true if !source_skill.to_s.empty? && (entry_source_skill == source_skill || entry_skill == source_skill)
+
+            false
+          end
+        end
+
         # Load step catalog from project override or gem defaults.
         #
         # @return [Array<Hash>] Loaded step definitions
         def step_catalog
-          @step_catalog ||= begin
-            project_root = Ace::Support::Fs::Molecules::ProjectRootFinder.find_or_current
-            gem_root = Gem.loaded_specs["ace-assign"]&.gem_dir || File.expand_path("../../../..", __dir__)
+          return @step_catalog if @step_catalog_loaded
 
-            project_catalog = File.join(project_root, ".ace", "assign", "catalog", "steps")
-            default_catalog = File.join(gem_root, ".ace-defaults", "assign", "catalog", "steps")
+          if @step_catalog_from_fixture_set
+            @step_catalog_loaded = true
+            @step_catalog = @step_catalog_from_fixture
+            return @step_catalog
+          end
 
-            default_steps = Atoms::CatalogLoader.load_all(default_catalog)
-            base_catalog = if File.directory?(project_catalog)
-              project_steps = Atoms::CatalogLoader.load_all(project_catalog)
-              merge_step_catalog(default_steps, project_steps)
-            else
-              default_steps
-            end
+          cached = self.class.send(:cached_value, :step_catalog_cache, step_catalog_signature)
+          return @step_catalog = cached if cached
+
+          @step_catalog_loaded = true
+          @step_catalog = load_step_catalog
+          self.class.send(:store_cached_value, :step_catalog_cache, step_catalog_signature, @step_catalog)
+          @step_catalog
+        end
+
+        def step_catalog_signature
+          [
+            PROJECT_ROOT_SIGNAL,
+            project_catalog_signature,
+            default_catalog_signature,
+            step_catalog_cache_token,
+            CATALOG_SIGNAL
+          ].join("|")
+        end
+
+        def project_catalog_signature
+          @project_catalog_signature ||= catalog_signature(File.join(project_root, ".ace", "assign", "catalog", "steps"))
+        end
+
+        def default_catalog_signature
+          @default_catalog_signature ||= catalog_signature(File.join(gem_root, ".ace-defaults", "assign", "catalog", "steps"))
+        end
+
+        def load_step_catalog
+          project_catalog = File.join(project_root, ".ace", "assign", "catalog", "steps")
+          default_catalog = File.join(gem_root, ".ace-defaults", "assign", "catalog", "steps")
+
+          canonical_steps = @skill_source_resolver.assign_step_catalog
+          default_steps = Atoms::CatalogLoader.load_all(default_catalog, canonical_steps: false)
+          base_catalog = merge_step_catalog(default_steps, canonical_steps)
 
-            canonical_steps = skill_source_resolver.assign_step_catalog
-            merge_step_catalog(base_catalog, canonical_steps)
+          if File.directory?(project_catalog)
+            project_steps = Atoms::CatalogLoader.load_all(project_catalog, canonical_steps: false)
+            merge_step_catalog(base_catalog, project_steps)
+          else
+            base_catalog
           end
         end
 
+        def catalog_signature(catalog_dir)
+          return "missing" unless File.directory?(catalog_dir)
+
+          Dir.glob(File.join(catalog_dir, "*.step.yml")).sort.map do |path|
+            "#{path}:#{file_signature(path)}"
+          end.join("|")
+        end
+
+        def file_signature(path)
+          stat = File.stat(path)
+          "#{stat.mtime.to_f}:#{stat.size}"
+        rescue
+          "missing"
+        end
+
+        def step_catalog_cache_token
+          token = if @skill_source_resolver.respond_to?(:cache_signature)
+            @skill_source_resolver.cache_signature
+          else
+            "resolver:#{@skill_source_resolver.object_id}"
+          end
+
+          "resolver:#{token}"
+        end
+
+        def project_root
+          @project_root ||= Ace::Support::Fs::Molecules::ProjectRootFinder.find_or_current
+        end
+
+        def gem_root
+          @gem_root ||= Gem.loaded_specs["ace-assign"]&.gem_dir || File.expand_path("../../../..", __dir__)
+        end
+
         # Merge default and project step catalogs by step name.
         # Later definitions override earlier ones with matching names.
         #
@@ -1178,6 +1290,11 @@ module Ace
 
           merged = base.dup
           override.each do |key, value|
+            if runtime_binding_override_key?(key, base, override)
+              merged[key] = base[key]
+              next
+            end
+
             merged[key] =
               if merged[key].is_a?(Hash) && value.is_a?(Hash)
                 deep_merge_step_definition(merged[key], value)
@@ -1188,6 +1305,33 @@ module Ace
           merged
         end
 
+        def runtime_binding_override_key?(key, base, override)
+          return false unless %w[source workflow skill source_skill].include?(key)
+          return false unless local_runtime_binding_present?(base)
+          canonical_binding_present?(override)
+        end
+
+        def local_runtime_binding_present?(entry)
+          entry.is_a?(Hash) && (
+            present_string?(entry["source"]) ||
+            present_string?(entry["workflow"]) ||
+            present_string?(entry["skill"])
+          )
+        end
+
+        def canonical_binding_present?(entry)
+          entry.is_a?(Hash) && (
+            present_string?(entry["source"]) ||
+            present_string?(entry["workflow"]) ||
+            present_string?(entry["skill"]) ||
+            present_string?(entry["source_skill"])
+          )
+        end
+
+        def present_string?(value)
+          value.is_a?(String) && !value.strip.empty?
+        end
+
         # Archive source config into the task's jobs/ directory.
         # If config is already in a jobs/ or steps/ directory, keeps it in place.
         # Otherwise moves job.yaml to <task>/jobs/<assignment_id>-job.yml for provenance.
@@ -1212,13 +1356,11 @@ module Ace
         end
 
         def rebalance_after_child_injection(assignment:, state:, parent_number:)
-          current = state.current
-          return unless current && current.number == parent_number
+          parent = state.find_by_number(parent_number)
+          return unless parent&.status == :active
+          return if parent.fork?
 
-          step_writer.mark_pending(current.file_path)
-          rebalanced_state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
-          next_step = rebalanced_state.next_workable_in_subtree(parent_number)
-          step_writer.mark_in_progress(next_step.file_path) if next_step
+          step_writer.mark_pending(parent.file_path)
         end
 
         # Normalize instructions to a string.
@@ -1281,10 +1423,27 @@ module Ace
         def canonical_batch_insert_requested?(step_config)
           raw_sub_steps = step_config["sub_steps"] || step_config["sub-steps"]
           has_declared_sub_steps = raw_sub_steps.is_a?(Array) && raw_sub_steps.any?
+          has_source = !step_config["source"].to_s.strip.empty?
           has_workflow = !step_config["workflow"].to_s.strip.empty?
           has_skill = !step_config["skill"].to_s.strip.empty?
 
-          has_declared_sub_steps || has_workflow || has_skill
+          has_declared_sub_steps || has_source || has_workflow || has_skill
+        end
+
+        def resolved_step_source(step, rendering)
+          explicit_source = step["source"]&.to_s&.strip
+          return explicit_source unless explicit_source.nil? || explicit_source.empty?
+
+          rendered_source = rendering["source"]&.to_s&.strip
+          return rendered_source unless rendered_source.nil? || rendered_source.empty?
+
+          workflow_source = rendering["workflow"]&.to_s&.strip
+          return workflow_source unless workflow_source.nil? || workflow_source.empty?
+
+          skill_name = rendering["skill"]&.to_s&.strip
+          return nil if skill_name.nil? || skill_name.empty?
+
+          "skill://#{skill_name}"
         end
 
         def insert_canonical_batch_step_tree(step_config, after:, as_child:, added_by:, location:)
@@ -1515,6 +1674,28 @@ module Ace
           DEFAULT_DYNAMIC_STEP_INSTRUCTIONS
         end
 
+        def targeted_batch_parent_startable?(target, fork_root:)
+          return false unless fork_root.nil? || fork_root.empty?
+
+          target.batch_parent == true
+        end
+
+        def find_target_step_for_fail(state, fork_root)
+          fork_root = fork_root&.strip
+          current = state.current
+          return current if fork_root.nil? || fork_root.empty?
+
+          raise StepErrors::NotFound, "Subtree root #{fork_root} not found in assignment." unless state.find_by_number(fork_root)
+          if state.active_branch_conflict_in_subtree?(fork_root)
+            active_refs = state.active_in_subtree(fork_root).map { |step| "#{step.number}(#{step.name})" }.join(", ")
+            raise StepErrors::InvalidState, "Cannot fail in subtree #{fork_root}: multiple active branches exist (#{active_refs})."
+          end
+
+          return current if current && state.in_subtree?(fork_root, current.number)
+
+          state.current_in_subtree(fork_root)
+        end
+
         def find_target_step_for_start(state, step_number, fork_root)
           target = state.find_by_number(step_number)
           raise StepErrors::NotFound, "Step #{step_number} not found in queue" unless target
@@ -1524,13 +1705,40 @@ module Ace
             raise StepErrors::InvalidState, "Step #{target.number} is outside scoped subtree #{fork_root}." unless state.in_subtree?(fork_root, target.number)
           end
           raise StepErrors::InvalidState, "Cannot start step #{target.number}: status is #{target.status}, expected pending." unless target.status == :pending
-          if state.has_incomplete_children?(target.number)
+          if state.has_incomplete_children?(target.number) && !targeted_batch_parent_startable?(target, fork_root: fork_root)
             raise StepErrors::InvalidState, "Cannot start step #{target.number}: has incomplete children."
           end
 
           target
         end
 
+        def validate_start_activation!(state, target, fork_root:)
+          root_ref = fork_root if fork_root && !fork_root.empty?
+          active_fork_root = if root_ref
+            state.find_by_number(root_ref)
+          else
+            state.nearest_fork_ancestor(target.number)
+          end
+
+          if active_fork_root &&
+              target.number != active_fork_root.number &&
+              active_fork_root.status != :active
+            raise StepErrors::InvalidState,
+              "Cannot start step #{target.number}: fork root #{active_fork_root.number} is not active."
+          end
+
+          return unless active_fork_root
+
+          if state.active_branch_conflict_in_subtree?(active_fork_root.number, extra_active: [target.number])
+            active_refs = (
+              state.active_in_subtree(active_fork_root.number).map { |step| "#{step.number}(#{step.name})" } +
+              ["#{target.number}(#{target.name})"]
+            ).uniq.join(", ")
+            raise StepErrors::InvalidState,
+              "Cannot start step #{target.number}: subtree #{active_fork_root.number} already has multiple active branches (#{active_refs})."
+          end
+        end
+
         def find_target_step_for_finish(state, step_number, fork_root)
           fork_root = fork_root&.strip
           if step_number && !step_number.to_s.strip.empty?
@@ -1539,7 +1747,7 @@ module Ace
             if fork_root && !fork_root.empty? && !state.in_subtree?(fork_root, target.number)
               raise StepErrors::InvalidState, "Step #{target.number} is outside scoped subtree #{fork_root}."
             end
-            raise StepErrors::InvalidState, "Cannot finish step #{target.number}: status is #{target.status}, expected in_progress." unless target.status == :in_progress
+            raise StepErrors::InvalidState, "Cannot finish step #{target.number}: status is #{target.status}, expected active." unless target.status == :active
 
             return target
           end
@@ -1547,10 +1755,9 @@ module Ace
           current = state.current
           if fork_root && !fork_root.empty?
             raise StepErrors::NotFound, "Subtree root #{fork_root} not found in assignment." unless state.find_by_number(fork_root)
-            active_in_subtree = state.in_progress_in_subtree(fork_root)
-            if active_in_subtree.size > 1
-              active_refs = active_in_subtree.map { |step| "#{step.number}(#{step.name})" }.join(", ")
-              raise StepErrors::InvalidState, "Cannot finish in subtree #{fork_root}: multiple steps are in progress (#{active_refs})."
+            if state.active_branch_conflict_in_subtree?(fork_root)
+              active_refs = state.active_in_subtree(fork_root).map { |step| "#{step.number}(#{step.name})" }.join(", ")
+              raise StepErrors::InvalidState, "Cannot finish in subtree #{fork_root}: multiple active branches exist (#{active_refs})."
             end
             if current.nil? || !state.in_subtree?(fork_root, current.number)
               current = state.current_in_subtree(fork_root)
@@ -1561,6 +1768,48 @@ module Ace
           current
         end
 
+        def scoped_retry_state(state, assignment:, fork_root:)
+          fork_root = fork_root&.strip
+          return state if fork_root.nil? || fork_root.empty?
+
+          scoped_steps = state.subtree_steps(fork_root)
+          Models::QueueState.new(steps: scoped_steps, assignment: assignment)
+        end
+
+        def validate_retry_scope!(state, original, fork_root)
+          fork_root = fork_root&.strip
+          return if fork_root.nil? || fork_root.empty?
+
+          raise StepErrors::NotFound, "Subtree root #{fork_root} not found in assignment." unless state.find_by_number(fork_root)
+          return if state.in_subtree?(fork_root, original.number)
+
+          raise StepErrors::InvalidState, "Step #{original.number} is outside scoped subtree #{fork_root}."
+        end
+
+        def normalize_scoped_insertion_anchor(state, after:, as_child:, fork_root:)
+          fork_root = fork_root&.strip
+          return [after, as_child] if fork_root.nil? || fork_root.empty?
+
+          root = state.find_by_number(fork_root)
+          raise StepErrors::NotFound, "Subtree root #{fork_root} not found in assignment." unless root
+
+          after_ref = after&.to_s&.strip
+          if after_ref && !after_ref.empty?
+            unless state.in_subtree?(fork_root, after_ref)
+              raise StepErrors::InvalidState, "Step #{after_ref} is outside scoped subtree #{fork_root}."
+            end
+
+            return [after_ref, as_child]
+          end
+
+          subtree = state.subtree_steps(fork_root)
+          last_subtree_step = subtree.last
+          return [fork_root, true] unless last_subtree_step
+          return [fork_root, true] if last_subtree_step.number == fork_root
+
+          [last_subtree_step.number, false]
+        end
+
         # Auto-complete parent steps when all their children are done.
         # Walks up the hierarchy marking parents as done, handling multi-level
         # completion in a single pass (grandparents become eligible when parents complete).
@@ -1583,9 +1832,9 @@ module Ace
             iterations += 1
             completed_any = false
 
-            # Find all pending/in_progress parent steps that have children
+            # Find all pending/active parent steps that have children
             eligible_parents = state.steps.select do |s|
-              (s.status == :pending || s.status == :in_progress) &&
+              (s.status == :pending || s.status == :active) &&
                 !completed_this_pass.include?(s.number)
             end