ace-assign 0.42.4 → 0.53.4

data/handbook/workflow-instructions/assign/verify-test-suite.wf.md

@@ -0,0 +1,36 @@
+---
+doc-type: workflow
+title: Assign Verify Test Suite Workflow
+purpose: Narrow deterministic verification contract for ace-assign orchestration
+ace-docs:
+  last-updated: 2026-04-13
+  last-checked: 2026-04-13
+---
+
+# Verify Test Suite Workflow
+
+## Purpose
+
+Run the deterministic verification contract used by `ace-assign`:
+- package-scoped `ace-test <package> all --profile 6` for modified packages
+- monorepo verification with `ace-test-suite --target all`
+
+Do not run `ace-test-e2e` or `ace-test-e2e-suite` from this workflow.
+
+## Steps
+
+1. Detect whether modified files affect runnable code.
+2. If changes are docs-only or otherwise non-runnable, skip with a clear reason.
+3. Detect modified packages from the current diff or working tree.
+4. Run `ace-test <package> all --profile 6` for each modified package.
+5. Run `ace-test-suite --target all`.
+
+## Skip Guidance
+
+Skip only when all modified files are documentation, retrospectives, task specs, or similarly non-runnable metadata.
+
+## Success Criteria
+
+- All modified packages pass `ace-test <package> all --profile 6`
+- `ace-test-suite --target all` passes
+- No E2E commands are used as part of this step

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

@@ -21,13 +21,19 @@ module Ace
         # Load all step definitions from a catalog directory.
         #
         # @param steps_dir [String] Path to catalog/steps/ directory
+        # @param canonical_steps [Array<Hash>, Symbol, Boolean, nil] Canonical
+        #   step metadata to merge. `:auto` (default) loads from skill sources.
+        #   `false` disables canonical merge and returns raw YAML definitions.
         # @return [Array<Hash>] Array of step definition hashes
-        def self.load_all(steps_dir)
+        def self.load_all(steps_dir, canonical_steps: :auto)
           return [] unless File.directory?(steps_dir)
 
-          Dir.glob(File.join(steps_dir, "*.step.yml")).sort.filter_map do |path|
+          yaml_steps = Dir.glob(File.join(steps_dir, "*.step.yml")).sort.filter_map do |path|
             parse_step_file(path)
           end
+          return [] if yaml_steps.empty?
+
+          merge_step_catalog(yaml_steps, resolve_canonical_steps(canonical_steps))
         end
 
         # Find a step definition by name.
@@ -94,6 +100,103 @@ module Ace
           warn "Warning: Failed to parse step file #{path}: #{e.message}"
           nil
         end
+
+        def self.resolve_canonical_steps(canonical_steps)
+          case canonical_steps
+          when false
+            []
+          when :auto, nil
+            begin
+              require_relative "../molecules/skill_assign_source_resolver"
+              Molecules::SkillAssignSourceResolver.new.assign_step_catalog
+            rescue LoadError, StandardError
+              []
+            end
+          when Array
+            canonical_steps
+          else
+            []
+          end
+        end
+        private_class_method :resolve_canonical_steps
+
+        def self.merge_step_catalog(base_steps, override_steps)
+          index = {}
+          order = []
+
+          Array(base_steps).each do |step|
+            name = step["name"]
+            next if name.nil? || name.empty?
+
+            index[name] = step
+            order << name
+          end
+
+          Array(override_steps).each do |step|
+            name = step["name"]
+            next if name.nil? || name.empty?
+
+            order << name unless index.key?(name)
+            index[name] = deep_merge_step_definition(index[name], step)
+          end
+
+          order.map { |name| index[name] }.compact
+        end
+        private_class_method :merge_step_catalog
+
+        def self.deep_merge_step_definition(base, override)
+          return override unless base.is_a?(Hash)
+          return base unless override.is_a?(Hash)
+
+          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)
+              else
+                value
+              end
+          end
+          merged
+        end
+        private_class_method :deep_merge_step_definition
+
+        def self.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
+        private_class_method :runtime_binding_override_key?
+
+        def self.local_runtime_binding_present?(entry)
+          entry.is_a?(Hash) && (
+            present_string?(entry["source"]) ||
+            present_string?(entry["workflow"]) ||
+            present_string?(entry["skill"])
+          )
+        end
+        private_class_method :local_runtime_binding_present?
+
+        def self.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
+        private_class_method :canonical_binding_present?
+
+        def self.present_string?(value)
+          value.is_a?(String) && !value.strip.empty?
+        end
+        private_class_method :present_string?
+
         private_class_method :parse_step_file
       end
     end

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

@@ -49,6 +49,7 @@ module Ace
           {
             name: fm["name"],
             status: (fm["status"] || "pending").to_sym,
+            source: normalize_source(fm["source"], fm["workflow"], fm["skill"]),
             skill: fm["skill"],
             workflow: fm["workflow"],
             context: context, # "fork" triggers Task tool execution
@@ -212,6 +213,20 @@ module Ace
           parsed
         end
         private_class_method :parse_non_negative_integer
+
+        def self.normalize_source(source, workflow, skill)
+          source_ref = source.to_s.strip
+          return source_ref unless source_ref.empty?
+
+          workflow_ref = workflow.to_s.strip
+          return workflow_ref unless workflow_ref.empty?
+
+          skill_ref = skill.to_s.strip
+          return nil if skill_ref.empty?
+
+          "skill://#{skill_ref}"
+        end
+        private_class_method :normalize_source
       end
     end
   end

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

@@ -11,6 +11,7 @@ module Ace
         # - <assignment-id>@<step-number>
         module AssignmentTarget
           Target = Struct.new(:assignment_id, :scope, keyword_init: true)
+          View = Struct.new(:assignment, :state, :scoped_state, :current_step, :scope_root, keyword_init: true)
 
           private
 
@@ -48,6 +49,58 @@ module Ace
             executor.assignment_manager.define_singleton_method(:find_active) { assignment }
             executor
           end
+
+          def resolve_assignment_view(target)
+            executor = build_executor_for_target(target)
+            result = executor.status
+            state = result[:state]
+            scoped = scoped_status_view(state, target.scope)
+
+            View.new(
+              assignment: result[:assignment],
+              state: state,
+              scoped_state: scoped[:state],
+              current_step: scoped[:current],
+              scope_root: scoped[:root]
+            )
+          end
+
+          def scoped_status_view(state, scope)
+            return {state: state, current: state.current || state.next_workable, root: nil} if scope.nil? || scope.strip.empty?
+
+            root = state.find_by_number(scope.strip)
+            raise StepErrors::NotFound, "Step #{scope} not found in queue" unless root
+
+            scoped_steps = state.subtree_steps(root.number)
+            scoped_state = Models::QueueState.new(steps: scoped_steps, assignment: state.assignment)
+            current = scoped_state.current || scoped_state.next_workable
+
+            {state: scoped_state, current: current, root: root.number}
+          end
+
+          def fork_scope_root(state, current_step)
+            return nil unless current_step
+            return current_step if current_step.fork?
+
+            state.nearest_fork_ancestor(current_step.number)
+          end
+
+          def scoped_fork_metadata_step(state, current_step, scope, scope_root)
+            return nil unless current_step
+
+            if scope && !scope.strip.empty?
+              return state.find_by_number(scope_root || scope.strip)
+            end
+
+            fork_scope_root(state, current_step)
+          end
+
+          def effective_fork_provider_for(current_step, scoped_fork_step)
+            return nil unless current_step
+
+            provider = current_step.fork_provider || scoped_fork_step&.fork_provider
+            provider.to_s.strip.empty? ? nil : provider
+          end
         end
       end
     end

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

@@ -43,11 +43,8 @@ module Ace
 
             if result[:current]
               puts "Advancing to step #{result[:current].number}: #{result[:current].name}"
-              puts
-              puts "Instructions:"
-              puts result[:current].instructions
+              puts "Next: ace-assign step#{step_target_suffix(result[:current].number, options[:assignment])}"
             else
-              puts
               fork_root = target.scope&.strip
               if fork_root && result[:state].subtree_complete?(fork_root)
                 puts "Fork subtree #{fork_root} completed."
@@ -81,6 +78,12 @@ module Ace
           rescue IOError, Errno::EBADF
             nil
           end
+
+          def step_target_suffix(step_number, assignment_target)
+            return " #{step_number}" if assignment_target.nil? || assignment_target.to_s.strip.empty?
+
+            %( #{step_number} --assignment "#{assignment_target}")
+          end
         end
       end
     end

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

@@ -21,6 +21,7 @@ module Ace
           option :provider, desc: "LLM provider:model override (e.g., codex:gpt-5, claude:sonnet)"
           option :cli_args, desc: "Extra CLI args for provider process"
           option :timeout, type: :integer, desc: "Execution timeout in seconds"
+          option :launch_mode, desc: "Launch mode: auto, headless, or tmux"
           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"
 
@@ -51,6 +52,7 @@ module Ace
               puts "Starting fork subtree execution: #{root_step.number} - #{root_step.name}"
               puts "Assignment: #{assignment.id}"
               puts "Provider: #{resolved_provider}"
+              puts "Launch mode: #{options[:launch_mode] || Molecules::ForkSessionLauncher::DEFAULT_LAUNCH_MODE}"
               puts "Timeout: #{options[:timeout] || Ace::Assign.config.dig("execution", "timeout") || Molecules::ForkSessionLauncher::DEFAULT_TIMEOUT}s"
               puts "Next step: #{next_step.number} - #{next_step.name}" if next_step
             end
@@ -77,7 +79,8 @@ module Ace
               provider: resolved_provider,
               cli_args: options[:cli_args],
               timeout: options[:timeout],
-              cache_dir: assignment.cache_dir
+              cache_dir: assignment.cache_dir,
+              launch_mode: options[:launch_mode]
             )
             record_fork_pid_info(root_step, launch_result)
 

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Ace
+  module Assign
+    module CLI
+      module Commands
+        # Internal command used by tmux-backed fork panes to launch the provider session once.
+        class ForkSession < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Run one provider-backed fork session for a subtree"
+
+          option :assignment, required: true, desc: "Target assignment ID"
+          option :root, required: true, desc: "Fork subtree root step number"
+          option :provider, desc: "LLM provider:model override (e.g., codex:gpt-5, claude:sonnet)"
+          option :cli_args, desc: "Extra CLI args for provider process"
+          option :timeout, type: :integer, desc: "Execution timeout in seconds"
+          option :cache_dir, desc: "Assignment cache directory override"
+          option :last_message_file, desc: "Explicit path for fork last-message capture"
+          option :session_meta_file, desc: "Explicit path for fork session metadata"
+
+          def initialize(launcher: nil)
+            super()
+            @launcher = launcher || Molecules::ForkSessionLauncher.new
+          end
+
+          def call(**options)
+            launcher.launch_provider_session(
+              assignment_id: options[:assignment],
+              fork_root: options[:root],
+              provider: options[:provider],
+              cli_args: options[:cli_args],
+              timeout: options[:timeout],
+              cache_dir: options[:cache_dir],
+              last_message_file: options[:last_message_file],
+              session_meta_file: options[:session_meta_file]
+            )
+
+            0
+          rescue Error, Ace::LLM::Error => e
+            warn e.message
+            1
+          end
+
+          private
+
+          attr_reader :launcher
+        end
+      end
+    end
+  end
+end

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

@@ -29,9 +29,15 @@ module Ace
 
             started = result[:started]
             puts "Step #{started.number} (#{started.name}) started"
-            puts
-            puts "Instructions:"
-            puts started.instructions
+            puts "Next: ace-assign step#{step_target_suffix(started.number, options[:assignment])}"
+          end
+
+          private
+
+          def step_target_suffix(step_number, assignment_target)
+            return " #{step_number}" if assignment_target.nil? || assignment_target.to_s.strip.empty?
+
+            %( #{step_number} --assignment "#{assignment_target}")
           end
         end
       end