ace-assign 0.42.4 → 0.55.0

data/handbook/workflow-instructions/assign/mark-task-done-internal.wf.md

@@ -0,0 +1,12 @@
+# mark-task-done-internal
+
+## Purpose
+
+Mark a task as done and verify the state transition persisted.
+
+## Steps
+
+1. Run `ace-task update <taskref> --set status=done --move-to archive --git-commit`.
+2. Verify with `ace-task show <taskref>` and confirm `status: done`.
+3. If the task has a parent, check whether siblings are all done; when true, mark the parent done and verify.
+4. Repeat upward only while all siblings remain done.

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

@@ -141,6 +141,11 @@ For `--taskrefs 148,149,150`, expansion generates:
 030 finalize
 ```
 
+Generated batch parents should carry scheduler metadata:
+
+- `010 batch-tasks (parent, auto-completes, batch_parent: true, parallel: false)`
+- `fork_retry_limit: 1`
+
 The hierarchical numbering enables:
 - Parent auto-completion when all children are done
 - Parent-only fork markers for subtree delegation
@@ -336,7 +341,7 @@ session:
 
 steps:
   - name: <step-name>
-    skill: <skill-reference>  # If present in preset
+    source: <source-reference>  # Canonical: skill://... or wfi://...
     instructions:
       - <resolved instruction line>
   # ... more steps
@@ -344,7 +349,7 @@ steps:
 
 ### 8. Output Result
 
-Default output: `<task>/jobs/<timestamp>-job.yml` (e.g., `.ace-taskflow/v.0.9.0/tasks/229-xxx/jobs/k5abc123-job.yml`)
+Default output: `<task>/jobs/<timestamp>-job.yml` (e.g., `.ace-task/v.0.9.0/tasks/229-xxx/jobs/k5abc123-job.yml`)
 
 Custom output: Use `--output path/to/custom.yaml`
 
@@ -379,19 +384,19 @@ session:
 
 steps:
   - name: onboard
-    skill: as-onboard
+    source: skill://as-onboard
     instructions:
       - Onboard yourself to the codebase.
       - Load context and understand the project structure.
 
   - name: work-on-task
-    skill: as-task-work
+    source: skill://as-task-work
     instructions:
       - Work on task 123.
       - Implement the required changes following project conventions.
 
   - name: create-pr
-    skill: as-github-pr-create
+    source: skill://as-github-pr-create
     instructions:
       - Create a pull request for the changes.
       - Capture the PR number for subsequent review steps.

data/handbook/workflow-instructions/assign/reflect-and-refactor-internal.wf.md

@@ -0,0 +1,14 @@
+# reflect-and-refactor-internal
+
+## Purpose
+
+Run architecture reflection and bounded refactoring before release/closeout.
+
+## Steps
+
+1. Validate implementation/demo state.
+2. Run architecture-focused review on the active diff.
+3. Categorize findings (refactor/accept/skip).
+4. Execute bounded refactoring for selected findings only.
+5. Commit refactor changes separately.
+6. If a replan trigger is hit, inject follow-up implementation steps and rerun once.

data/handbook/workflow-instructions/assign/run-in-batches.wf.md

@@ -3,7 +3,7 @@ doc-type: workflow
 title: Run In Batches Workflow
 purpose: workflow instruction for reusable repeated-item orchestration with deterministic assignment creation
 ace-docs:
-  last-updated: 2026-03-18
+  last-updated: 2026-04-07
   last-checked: 2026-03-21
 ---
 
@@ -163,6 +163,8 @@ If `--run` is present:
 /as-assign-drive <assignment-id>
 ```
 
+This handoff must continue through the full batch execution, including all child fork subtrees, until the assignment is complete or an explicit blocker/failure stop condition is reached. Child completion is not a valid stop boundary.
+
 If no workable step is available, keep creation successful and report why drive did not continue.
 
 ### 7. Report Result
@@ -203,6 +205,7 @@ Show:
 - Parent/child metadata reflects scheduler intent (`parallel`, `max_parallel`, `fork_retry_limit`)
 - `{{item}}` substitution and `Target item:` fallback are deterministic
 - Optional `--run` handoff delegates to `/as-assign-drive`
+- Optional `--run` handoff preserves drive's run-until-complete-or-blocked semantics across the whole batch
 
 ## Verification
 

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

@@ -3,7 +3,7 @@ doc-type: workflow
 title: Start Assignment Workflow (Legacy Compatibility)
 purpose: preserve compatibility for as-assign-start while routing to public assign/create + assign/drive flow
 ace-docs:
-  last-updated: 2026-03-18
+  last-updated: 2026-04-07
   last-checked: 2026-03-21
 ---
 
@@ -39,8 +39,11 @@ Primary public UX remains:
 /as-assign-drive <assignment-id>
 ```
 
+When this handoff occurs, `/as-assign-drive` must continue until the assignment is complete or explicitly blocked. It is not a single-step progress probe.
+
 ## Success Criteria
 
 - Preserves compatibility entrypoint for orchestration examples.
 - Delegates behavior to `assign/create` and `assign/drive`.
-- Does not redefine the public assignment flow.
+- Does not redefine the public assignment flow.
+- Preserves drive's run-until-complete-or-blocked semantics.

data/handbook/workflow-instructions/assign/task-load-internal.wf.md

@@ -0,0 +1,12 @@
+# task-load-internal
+
+## Purpose
+
+Load task behavioral specification and dependency context for assignment execution.
+
+## Steps
+
+1. Run `ace-bundle task://<taskref>` for the target task reference.
+2. If task dependencies are declared, run `ace-bundle task://<dep-ref>` for each dependency.
+3. Review relevant dependency reports under `.ace-local/assign/` so the plan/work steps build on prior implementation.
+4. Confirm context is loaded before proceeding.

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/preset_expander.rb

@@ -192,6 +192,10 @@ module Ace
 
           step["skill"] = config["skill"] if config["skill"]
           step["context"] = config["context"] if config["context"]
+          step["batch_parent"] = config["batch_parent"] unless config["batch_parent"].nil?
+          step["parallel"] = config["parallel"] unless config["parallel"].nil?
+          step["max_parallel"] = config["max_parallel"] if config["max_parallel"]
+          step["fork_retry_limit"] = config["fork_retry_limit"] unless config["fork_retry_limit"].nil?
 
           step
         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/atoms/tree_formatter.rb

@@ -14,14 +14,14 @@ module Ace
       #   #     +-- onboard (completed)
       #   #     +-- work-on-task (running)
       #   #     |   +-- onboard (completed)
-      #   #     |   +-- implement (in_progress)
+      #   #     |   +-- implement (active)
       #   #     |   \-- verify-tests (pending)
       #   #     \-- review-pr (pending)
       module TreeFormatter
         # State display labels matching list command
         STATE_LABELS = {
           pending: "pending",
-          in_progress: "in_progress",
+          active: "active",
           running: "running",
           paused: "paused",
           completed: "completed",

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

@@ -35,11 +35,11 @@ module Ace
             mode = selected_mode(options)
             case mode
             when :yaml
-              handle_yaml_mode(executor, options)
+              handle_yaml_mode(executor, options, target)
             when :step
-              handle_step_mode(executor, options)
+              handle_step_mode(executor, options, target)
             when :task
-              handle_task_mode(executor, options)
+              handle_task_mode(executor, options, target)
             else
               raise Ace::Support::Cli::Error, "Exactly one of --yaml, --step, or --task is required"
             end
@@ -77,20 +77,21 @@ module Ace
             insertion_modes(options).find { |_, value| !value.to_s.strip.empty? }&.first
           end
 
-          def handle_yaml_mode(executor, options)
+          def handle_yaml_mode(executor, options, target)
             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],
-              source_file: yaml_path
+              source_file: yaml_path,
+              fork_root: target.scope
             )
             print_yaml_result(result, yaml_path) unless options[:quiet]
             nil
           end
 
-          def handle_step_mode(executor, options)
+          def handle_step_mode(executor, options, target)
             preset_name = resolve_preset_name(executor, options)
             preset = Atoms::PresetLoader.load(preset_name)
             requested = parse_step_names(options[:step])
@@ -111,7 +112,8 @@ module Ace
                 steps: [step],
                 after: options[:child] ? options[:after] : sibling_cursor,
                 as_child: options[:child],
-                source_file: "preset:#{preset_name}"
+                source_file: "preset:#{preset_name}",
+                fork_root: target.scope
               )
 
               inserted_added = Array(inserted[:added])
@@ -126,7 +128,7 @@ module Ace
             nil
           end
 
-          def handle_task_mode(executor, options)
+          def handle_task_mode(executor, options, target)
             preset_name = resolve_preset_name(executor, options)
             preset = Atoms::PresetLoader.load(preset_name)
             task_ref = options[:task].to_s.strip
@@ -139,7 +141,8 @@ module Ace
             end
 
             parent_step = options[:after].to_s.strip
-            parent_step = detect_batch_parent(executor) if parent_step.empty?
+            parent_step = target.scope.to_s.strip if parent_step.empty? && !target.scope.to_s.strip.empty?
+            parent_step = detect_batch_parent(executor, target) 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
@@ -150,7 +153,8 @@ module Ace
               steps: [task_step],
               after: parent_step,
               as_child: insert_as_child,
-              source_file: "preset:#{preset_name}:task:#{task_ref}"
+              source_file: "preset:#{preset_name}:task:#{task_ref}",
+              fork_root: target.scope
             )
 
             print_task_result(result, task_ref, parent_step, as_child: insert_as_child) unless options[:quiet]
@@ -235,8 +239,13 @@ module Ace
             tokens.to_a.sort
           end
 
-          def detect_batch_parent(executor)
+          def detect_batch_parent(executor, target)
             state = executor.status[:state]
+            if target.scope && !target.scope.to_s.strip.empty?
+              scoped_steps = state.subtree_steps(target.scope.strip)
+              scoped_state = Ace::Assign::Models::QueueState.new(steps: scoped_steps, assignment: state.assignment)
+              state = scoped_state
+            end
 
             batch_parent = state.top_level.find { |step| step.name == "batch-tasks" }
             return batch_parent.number if batch_parent

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

@@ -10,17 +10,26 @@ module Ace
         # - <assignment-id>
         # - <assignment-id>@<step-number>
         module AssignmentTarget
+          DEFAULT_TARGET_ENV = "ACE_ASSIGN_DEFAULT_TARGET"
           Target = Struct.new(:assignment_id, :scope, keyword_init: true)
+          View = Struct.new(:assignment, :state, :scoped_state, :active_steps, :next_step, :focus_step, :scope_root, keyword_init: true)
 
           private
 
           def resolve_assignment_target(options)
             assignment_raw = options[:assignment]
-            unless assignment_raw.nil? || assignment_raw.to_s.strip.empty?
-              return parse_assignment_target(assignment_raw)
+            explicit_target = unless assignment_raw.nil? || assignment_raw.to_s.strip.empty?
+              parse_assignment_target(assignment_raw)
             end
 
-            Target.new(assignment_id: nil, scope: nil)
+            env_target = env_assignment_target
+            if explicit_target && env_target && target_identity(explicit_target) != target_identity(env_target)
+              raise Ace::Support::Cli::Error,
+                "Conflicting assignment targets: --assignment #{target_identity(explicit_target)} " \
+                "does not match #{DEFAULT_TARGET_ENV}=#{target_identity(env_target)}"
+            end
+
+            explicit_target || env_target || Target.new(assignment_id: nil, scope: nil)
           end
 
           def parse_assignment_target(raw)
@@ -37,6 +46,22 @@ module Ace
             Target.new(assignment_id: assignment_id, scope: scope)
           end
 
+          def env_assignment_target
+            raw = ENV[DEFAULT_TARGET_ENV].to_s.strip
+            return nil if raw.empty?
+
+            parse_assignment_target(raw)
+          end
+
+          def target_identity(target)
+            return "" unless target
+
+            scope = target.scope.to_s.strip
+            return target.assignment_id.to_s if scope.empty?
+
+            "#{target.assignment_id}@#{scope}"
+          end
+
           def build_executor_for_target(target)
             return Organisms::AssignmentExecutor.new unless target.assignment_id
 
@@ -48,6 +73,65 @@ 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],
+              active_steps: scoped[:active_steps],
+              next_step: scoped[:next_step],
+              focus_step: scoped[:focus_step],
+              scope_root: scoped[:root]
+            )
+          end
+
+          def scoped_status_view(state, scope)
+            if scope.nil? || scope.strip.empty?
+              active_steps = state.active_steps
+              next_step = active_steps.empty? ? state.next_workable : nil
+              return {state: state, active_steps: active_steps, next_step: next_step, focus_step: state.current || next_step, root: nil}
+            end
+
+            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)
+            active_steps = scoped_state.active_steps
+            next_step = active_steps.empty? ? state.next_workable_in_subtree(root.number) : nil
+
+            {state: scoped_state, active_steps: active_steps, next_step: next_step, focus_step: scoped_state.current || next_step, root: root.number}
+          end
+
+          def fork_scope_root(state, step)
+            return nil unless step
+            return step if step.fork?
+
+            state.nearest_fork_ancestor(step.number)
+          end
+
+          def scoped_fork_metadata_step(state, step, scope, scope_root)
+            return nil unless step
+
+            if scope && !scope.strip.empty?
+              return state.find_by_number(scope_root || scope.strip)
+            end
+
+            fork_scope_root(state, step)
+          end
+
+          def effective_fork_provider_for(step, scoped_fork_step)
+            return nil unless step
+
+            provider = 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/create.rb

@@ -32,7 +32,7 @@ module Ace
             unless options[:quiet]
               print_terminal_skip_summary(result[:skipped_terminal])
               print_assignment_header(result[:assignment])
-              print_step_instructions(result[:current])
+              print_step_instructions(result[:current] || result[:state]&.next_workable)
             end
           end
 

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

@@ -21,7 +21,7 @@ module Ace
 
             target = resolve_assignment_target(options)
             executor = build_executor_for_target(target)
-            result = executor.fail(message)
+            result = executor.fail(message, fork_root: target.scope)
 
             unless options[:quiet]
               failed = result[:failed]

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

@@ -4,12 +4,12 @@ module Ace
   module Assign
     module CLI
       module Commands
-        # Complete in-progress step with report content
+        # Complete active step with report content
         class Finish < Ace::Support::Cli::Command
           include Ace::Support::Cli::Base
           include AssignmentTarget
 
-          desc "Complete in-progress step with report content"
+          desc "Complete active step with report content"
 
           argument :step, required: false, desc: "Step number to finish (active assignment only)"
           option :message, aliases: ["-m"], desc: "Report content: string, file path, or pipe stdin"
@@ -41,13 +41,24 @@ module Ace
             report_path = File.join(assignment.reports_dir, report_filename)
             puts "Report saved to: #{report_path}"
 
-            if result[:current]
-              puts "Advancing to step #{result[:current].number}: #{result[:current].name}"
-              puts
-              puts "Instructions:"
-              puts result[:current].instructions
+            scoped_state = if target.scope && !target.scope.to_s.strip.empty?
+              Ace::Assign::Models::QueueState.new(
+                steps: result[:state].subtree_steps(target.scope.strip),
+                assignment: assignment
+              )
+            else
+              result[:state]
+            end
+
+            active_steps = scoped_state.active_steps
+            if active_steps.any?
+              focused = scoped_state.current
+              puts "Active steps remaining: #{active_steps.map { |step| "#{step.number} #{step.name}" }.join(', ')}"
+              puts "Next: ace-assign step#{step_target_suffix(focused.number, options[:assignment])}" if focused
+            elsif (next_step = next_pending_step(result[:state], scoped_state, target.scope))
+              puts "No active step selected."
+              puts "Next pending step: #{next_step.number} - #{next_step.name}"
             else
-              puts
               fork_root = target.scope&.strip
               if fork_root && result[:state].subtree_complete?(fork_root)
                 puts "Fork subtree #{fork_root} completed."
@@ -81,6 +92,19 @@ 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
+
+          def next_pending_step(state, scoped_state, scope_root)
+            scope_ref = scope_root.to_s.strip
+            return scoped_state.next_workable if scope_ref.empty?
+
+            state.next_workable_in_subtree(scope_ref)
+          end
         end
       end
     end