ace-assign 0.41.10 → 0.42.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '06674279e2b0b541d4da053a4bb8e385ea6e76b8d8cb58e6fc4b5032dac2e15e'
-  data.tar.gz: aa8e3423d01ebe3b86e355474b1a77e506cc1efcdf68f953e449f9bc671fbd72
+  metadata.gz: 214f383018bb2b9861e03cedf52c8eca4df627d9787357d00998725be36cbe36
+  data.tar.gz: 5f8d577f6f0eacd399c2a317d8dee720f237194af70968b65fcca8a1de676dea
 SHA512:
-  metadata.gz: 51a4be473d02363c49c5439b4f4814c4c22dddfa30d2c7674aeae68f2c29a98f9dfe44440cd26aa4d5fc1633f5918d045cc24a190ab68a38e41d797a95e3e00f
-  data.tar.gz: f97ce64ca4fecb86f9bdad9312f6864e70f5cbe098c8f00a4db408d77e91b4d0691f36868b6728238231e2ce923effd3e73c1f242d2c94cdb16e18f3a89526d9
+  metadata.gz: 3be4c93c1264e83f808bd0fed4d92780a65e00da59561c428bf3d7a6f65ce63c21398d256113d601e3849ba25dc546c1eb841e6dbf9db21804809c3afac35239
+  data.tar.gz: daab1a233b937ef79fa3d3b406404350b6b34ca0ade254cb7ff96b6f11c810f0c7dc255fe271e8e00cd8c194c6a941330ed8af725e22d49dfcceb0c627ad1ddf

data/.ace-defaults/assign/catalog/steps/plan-task.step.yml

@@ -5,10 +5,6 @@ description: Analyze task requirements and create an implementation plan
 produces: [implementation-plan]
 consumes: [project-base-context, task-spec]
 
-context:
-  default: fork
-  reason: "Planning benefits from focused exploration"
-
 when_to_skip:
   - "Task is trivial and doesn't need a plan"
   - "Implementation plan already exists"

data/.ace-defaults/assign/catalog/steps/review-pr.step.yml

@@ -10,10 +10,6 @@ prerequisites:
 produces: [review-feedback]
 consumes: [pull-request]
 
-context:
-  default: fork
-  reason: "Review benefits from isolated analysis without implementation bias"
-
 when_to_skip:
   - "No code changes since last review"
   - "Changes are trivial (typo fix, config update)"

data/.ace-defaults/assign/catalog/steps/work-on-task.step.yml

@@ -11,10 +11,6 @@ intent:
 produces: [code-changes, commits]
 consumes: [project-base-context, task-spec]
 
-context:
-  default: fork
-  reason: "Substantial implementation benefits from focused agent"
-
 when_to_skip:
   - "Task is documentation-only"
   - "Changes are already implemented"

data/CHANGELOG.md

@@ -7,6 +7,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.42.4] - 2026-04-05
+
+### Fixed
+- Scoped canonical `skill://` and `wfi://` source discovery to in-project defaults and explicitly registered external sources so ambient installed gems no longer leak into assign resolution.
+- Preserved child `skill` metadata only for hand-authored explicit split sub-steps while keeping inferred and preset-expanded canonical sub-steps fully materialized.
+
+## [0.42.3] - 2026-04-02
+
+### Changed
+- Updated HITL guidance wording in `ace-assign status` and assignment workflow/docs to use canonical "event" terminology (`Review event`, `HITL event`).
+
+### Technical
+- Refreshed status command test expectations for the updated HITL wording contract.
+
+## [0.42.2] - 2026-04-02
+
+### Technical
+- Updated HITL stall-path fixture expectations in status command coverage from `.ace-hitl/...` to `.ace-local/hitl/...` to match the new default HITL root.
+
+## [0.42.1] - 2026-04-02
+
+### Changed
+- Updated `wfi://assign/drive` HITL guidance to use per-item polling (`ace-hitl wait <id>`) as the default requester path and `ace-hitl update --resume` as fallback dispatch.
+
+### Fixed
+- Updated `ace-assign status` HITL operator guidance output to display polling-first and fallback resume commands aligned with the current HITL contract.
+
+### Technical
+- Refreshed command-level status tests for the new HITL guidance text contract.
+
+## [0.42.0] - 2026-04-01
+
+### Changed
+- Added a dedicated HITL stall protocol to `wfi://assign/drive`, documenting `ace-hitl` create/list/show/update usage, canonical `ace-assign fail --message "HITL: <id> <path>"` formatting, and resume/archive flow without reintroducing gate-state mechanics.
+
+### Fixed
+- `ace-assign status` now detects HITL-formatted stall reasons and prints direct operator guidance for `ace-hitl show <id>` plus stored-path hints.
+
+### Technical
+- Added command-level status coverage for HITL and non-HITL stall reason rendering to prevent regressions in current-step guidance output.
+
+## [0.41.12] - 2026-04-01
+
+### Fixed
+- Restored parent-only fork boundaries for generated split subtrees by preventing child steps from inheriting fork context defaults when the parent step is the fork root.
+- Removed default fork context declarations from canonical `plan-task`, `work-on-task`, and `review-pr` catalog steps so only explicitly fork-root parent steps run in forked context.
+
+### Technical
+- Added regression coverage for symbolized/string fork-context normalization in child-step materialization paths.
+
+## [0.41.11] - 2026-04-01
+
+### Fixed
+- Restored parent-only fork semantics for split-subtree execution by preventing canonical child-step `context: fork` defaults from being materialized onto generated subtree children (notably `plan-task` and `work-on-task`).
+- Updated workflow-backed child-step rendering to strip inherited fork context/provider metadata when the child did not explicitly declare fork settings.
+
+### Technical
+- Added regression coverage for split-subtree child materialization and scoped status output to ensure child `plan-task` does not emit fork-execution guidance.
+
 ## [0.41.10] - 2026-03-31
 
 ### Changed

data/docs/usage.md

@@ -1,10 +1,11 @@
 ---
 doc-type: user
 title: ace-assign Usage Guide
-purpose: Complete command reference for ace-assign queue orchestration, hierarchy, and fork execution.
+purpose: Complete command reference for ace-assign queue orchestration, hierarchy,
+  and fork execution.
 ace-docs:
-  last-updated: 2026-03-26
-  last-checked: 2026-03-26
+  last-updated: '2026-04-01'
+  last-checked: '2026-04-01'
 ---
 
 # ace-assign Usage Guide
@@ -92,6 +93,18 @@ Options:
 - `--quiet, -q`
 - `--debug, -d`
 
+HITL stall behavior:
+
+- Canonical contract lives in `wfi://hitl` (`ace-hitl` package workflow).
+- If a step is failed with canonical message format `HITL: <id> <path>`, `ace-assign status` prints operator guidance with the matching `ace-hitl show <id>` command and available path hint.
+- Recommended resume flow:
+  - `ace-hitl show <id>`
+  - requester path (default): `ace-hitl wait <id>`
+  - fallback path (when waiter inactive): `ace-hitl update <id> --answer "<decision>" --resume`
+  - `ace-assign retry <failed-step> --assignment <assignment-id>`
+- Completion-attention flow:
+  - When assignment work is complete but explicit user action is needed, create an approval HITL event (`kind=approval`) and include the resume instruction for `/as-assign-drive <assignment-id>`.
+
 ### `ace-assign start [STEP]`
 
 Start next workable pending step, or an explicit pending step in the active assignment.

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

@@ -437,6 +437,41 @@ For external-facing steps (for example PR/review/release/push/update lifecycle s
 ace-assign fail --message "Command failed: <cmd>. Error: <exact stderr>" --assignment "$ASSIGNMENT_TARGET"
 ```
 
+### Human-in-the-Loop (HITL) Stall Protocol
+
+Canonical source of truth: `wfi://hitl`.
+
+Use HITL when:
+
+- the active step is blocked by human judgment (ambiguity, product decision, policy choice), or
+- the assignment is complete but explicit user attention is required before next action.
+
+For a blocked step:
+
+1. Create a HITL event with assignment and step context:
+   ```bash
+   ace-hitl create "Need product decision" --question "Should retries be visible?" --assignment <id> --step <number> --step-name <name> --resume "/as-assign-drive <id>"
+   ```
+2. Fail the step using canonical stall format:
+   ```bash
+   ace-assign fail --message "HITL: <hitl-id> <hitl-path>" --assignment "$ASSIGNMENT_TARGET"
+   ```
+3. Human/operator resolves:
+   ```bash
+   ace-hitl show <hitl-id>
+   ace-hitl update <hitl-id> --answer "Yes, show retries in user-facing output."
+   ace-hitl wait <hitl-id>
+   ```
+4. Discover pending HITL work:
+   - Main checkout default (smart local-first): `ace-hitl list`
+   - Explicit scope controls: `ace-hitl list --scope current` and `ace-hitl list --scope all`
+5. Polling is default: requesting agent waits on its own HITL id (`ace-hitl wait <hitl-id>`), not global queues.
+6. Resume dispatch is fallback: if waiter is no longer active, run:
+   ```bash
+   ace-hitl update <hitl-id> --answer "<decision>" --resume
+   ```
+7. On retry/resume, read the answer from the HITL event and continue normal fail/retry mechanics. Do not introduce gate phases, assignment-level paused state, or extra resume commands in `ace-assign`.
+
 ### 5. Write Report (Only After Real Execution)
 
 After completing the step work, write a brief report summarizing what was accomplished:
@@ -536,6 +571,12 @@ Summarize the assignment results to the user:
 - Any artifacts created (PRs, commits, etc.)
 - Next steps or follow-up actions
 
+If completion requires explicit user action/decision, create an approval HITL event:
+
+```bash
+ace-hitl create "Review completed assignment results" --kind approval --question "Please confirm next action for <assignment-id>." --assignment <assignment-id> --step completion --step-name assignment-complete --resume "/as-assign-drive <assignment-id>"
+```
+
 ## Skill Invocation Pattern
 
 When executing a step with a `skill:` field:
@@ -663,4 +704,4 @@ $ ace-assign finish --message task-done.md --assignment "$ASSIGNMENT_TARGET"
 # 7. Eventually...
 $ ace-assign status --assignment "$ASSIGNMENT_TARGET"
 All steps complete!
-```
+```

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

@@ -233,7 +233,8 @@ module Ace
         # @param parameters [Hash] Parameter values
         # @return [Hash] Step with substituted values
         def self.substitute_parameters(step, parameters)
-          substitute_value(step, parameters)
+          substituted = substitute_value(step, parameters)
+          mark_preset_sub_steps_origin(substituted)
         end
         private_class_method :substitute_parameters
 
@@ -253,6 +254,16 @@ module Ace
         end
         private_class_method :substitute_value
 
+        def self.mark_preset_sub_steps_origin(step)
+          return step unless step.is_a?(Hash)
+
+          sub_steps = step["sub_steps"] || step["sub-steps"]
+          return step unless sub_steps.is_a?(Array) && sub_steps.any?
+
+          step.merge("sub_steps_origin" => "preset")
+        end
+        private_class_method :mark_preset_sub_steps_origin
+
         # Substitute {{placeholder}} tokens in a string.
         #
         # @param text [String, nil] Text with placeholders

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

@@ -90,6 +90,7 @@ module Ace
                   lines = current_for_display.stall_reason.to_s.strip.lines
                   puts "Stall Reason: #{lines.first&.chomp}"
                   lines[1..].each { |l| puts "             #{l.chomp}" } if lines.length > 1
+                  print_hitl_stall_guidance(lines.first.to_s)
                 end
                 if current_for_display.workflow
                   puts "Workflow: #{current_for_display.workflow}"
@@ -369,6 +370,29 @@ module Ace
             puts
           end
 
+          def print_hitl_stall_guidance(first_line)
+            hitl = parse_hitl_stall_reason(first_line)
+            return unless hitl
+
+            puts "HITL Guidance:"
+            puts "  Review event: ace-hitl show #{hitl[:id]}"
+            puts "  Stored path: #{hitl[:path]}" if hitl[:path]
+            puts "  Requester default: ace-hitl wait #{hitl[:id]}"
+            puts "  Fallback dispatch: ace-hitl update #{hitl[:id]} --answer \"<decision>\" --resume"
+          end
+
+          def parse_hitl_stall_reason(line)
+            stripped = line.to_s.strip
+            return nil unless stripped.start_with?("HITL:")
+
+            payload = stripped.sub(/^HITL:\s*/, "")
+            id, path = payload.split(/\s+/, 2)
+            return nil if id.to_s.strip.empty?
+
+            path = path.to_s.strip
+            {id: id, path: path.empty? ? nil : path}
+          end
+
           # Print other assignments section
           def print_other_assignments(current_assignment_id, include_completed:)
             discoverer = Molecules::AssignmentDiscoverer.new

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

@@ -297,13 +297,16 @@ module Ace
         end
 
         def discover_protocol_source_paths(protocol:, package_glob:)
-          registry_paths = Dir.chdir(project_root) do
-            registry = Ace::Support::Nav::Molecules::SourceRegistry.new
+          registry_paths = with_project_root do
+            registry = Ace::Support::Nav::Molecules::SourceRegistry.new(start_path: project_root)
             registry.sources_for_protocol(protocol).filter_map do |source|
               next if source.config.is_a?(Hash) && source.config["enabled"] == false
 
               candidate = resolve_source_directory(source)
-              File.directory?(candidate) ? candidate : nil
+              next unless File.directory?(candidate)
+              next if external_implicit_source?(source, candidate)
+
+              candidate
             rescue
               nil
             end
@@ -312,6 +315,12 @@ module Ace
           (registry_paths + discover_package_default_source_paths(package_glob)).uniq
         end
 
+        def with_project_root
+          Dir.chdir(project_root) { yield }
+        rescue Errno::ENOENT
+          yield
+        end
+
         def resolve_source_directory(source)
           candidate = source.full_path
           return candidate if File.directory?(candidate)
@@ -326,6 +335,23 @@ module Ace
           File.directory?(fallback) ? fallback : nil
         end
 
+        def external_implicit_source?(source, directory)
+          return false if path_within_project?(directory)
+          return false if explicit_registration?(source)
+
+          true
+        end
+
+        def explicit_registration?(source)
+          %w[project user].include?(source.origin.to_s)
+        end
+
+        def path_within_project?(path)
+          candidate = Pathname.new(File.expand_path(path))
+          root = Pathname.new(File.expand_path(project_root))
+          candidate == root || candidate.to_s.start_with?("#{root}/")
+        end
+
         def discover_package_default_source_paths(source_glob)
           source_files = Dir.glob(source_glob).sort
           source_files.filter_map do |source_file|

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

@@ -479,7 +479,11 @@ module Ace
             next step unless step.is_a?(Hash)
 
             sub_steps = step["sub_steps"] || step["sub-steps"]
-            next step if sub_steps.is_a?(Array) && sub_steps.any?
+            if sub_steps.is_a?(Array) && sub_steps.any?
+              explicit = step.dup
+              explicit["sub_steps_origin"] ||= "explicit"
+              next explicit
+            end
 
             assign_config = resolve_step_assign_config(step)
             next step unless assign_config
@@ -487,7 +491,10 @@ module Ace
             resolved_sub_steps = assign_config[:sub_steps]
             next step unless resolved_sub_steps.is_a?(Array) && resolved_sub_steps.any?
 
-            enriched = step.merge("sub_steps" => resolved_sub_steps)
+            enriched = step.merge(
+              "sub_steps" => resolved_sub_steps,
+              "sub_steps_origin" => "inferred"
+            )
             enriched["context"] ||= assign_config[:context] if assign_config[:context]
             enriched
           end
@@ -523,6 +530,7 @@ module Ace
               # Create split parent orchestration node
               parent_context = step["context"] || "fork"
               parent_instructions = step["instructions"]
+              sub_steps_origin = step["sub_steps_origin"] || "explicit"
               parent_step = build_split_parent_step(
                 step: step,
                 parent_number: parent_number,
@@ -540,7 +548,8 @@ module Ace
                   parent_number: parent_number,
                   parent_step: step,
                   parent_instructions: parent_instructions,
-                  parent_context: parent_context
+                  parent_context: parent_context,
+                  sub_steps_origin: sub_steps_origin
                 )
               end
             else
@@ -680,8 +689,9 @@ module Ace
         # @param parent_step [Hash] Parent step config
         # @param parent_instructions [String, Array<String>, nil] Parent instructions
         # @param parent_context [String, nil] Parent execution context
+        # @param sub_steps_origin [String] Whether the subtree was declared explicitly or inferred
         # @return [Hash] Child step config
-        def build_child_sub_step(sub_name:, child_number:, parent_number:, parent_step:, parent_instructions:, parent_context:)
+        def build_child_sub_step(sub_name:, child_number:, parent_number:, parent_step:, parent_instructions:, parent_context:, sub_steps_origin: "inferred")
           step_def = find_step_definition(sub_name)
           parent_task_ref = extract_parent_taskref(parent_step, parent_instructions)
           instructions = if step_def&.dig("skill")
@@ -693,16 +703,18 @@ module Ace
             "number" => child_number,
             "name" => sub_name,
             "instructions" => instructions,
-            "parent" => parent_number
+            "parent" => parent_number,
+            "sub_steps_origin" => sub_steps_origin
           }
           child["taskref"] = parent_task_ref if parent_task_ref
 
           if step_def
             child["workflow"] = step_def["workflow"] if step_def["workflow"]
-            child["skill"] = step_def["skill"] if step_def["skill"] && !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"])
 
             context_default = step_def.dig("context", "default")
-            child["context"] = context_default if context_default && parent_context != "fork"
+            child["context"] = context_default if context_default && !fork_context_value?(parent_context)
             fork_context = step_def.dig("context", "fork")
             if child["context"] == "fork" && fork_context.is_a?(Hash) && !fork_context.empty?
               # Generated child sub-steps have no explicit frontmatter overrides.
@@ -849,18 +861,20 @@ module Ace
             "instructions" => rendered_instructions,
             "workflow" => rendering["workflow"]
           )
-          context_default = rendering.dig("context", "default")
-          materialized["context"] ||= context_default if context_default
-          fork_context = rendering.dig("context", "fork")
-          if materialized["context"] == "fork" && fork_context.is_a?(Hash) && !fork_context.empty?
-            # For materialized explicit steps, preserve frontmatter-provided fork config
-            # (`||=` semantics). Rendering contributes defaults only when the step
-            # itself did not declare fork options.
-            materialized["fork"] ||= fork_context
+          unless split_child_without_explicit_fork?(step)
+            context_default = rendering.dig("context", "default")
+            materialized["context"] ||= context_default if context_default
+            fork_context = rendering.dig("context", "fork")
+            if materialized["context"] == "fork" && fork_context.is_a?(Hash) && !fork_context.empty?
+              # For materialized explicit steps, preserve frontmatter-provided fork config
+              # (`||=` semantics). Rendering contributes defaults only when the step
+              # itself did not declare fork options.
+              materialized["fork"] ||= fork_context
+            end
           end
           materialized["source_skill"] = rendering["source_skill"] || rendering["skill"] if rendering["source_skill"] || rendering["skill"]
           materialized["source_workflow"] = rendering["workflow"] if rendering["workflow"] && !rendering["workflow"].empty?
-          materialized.delete("skill")
+          materialized.delete("skill") unless preserve_explicit_child_skill?(step)
           materialized
         end
 
@@ -868,6 +882,11 @@ module Ace
           explicit_workflow = step["workflow"]&.to_s&.strip
           if explicit_workflow && !explicit_workflow.empty?
             canonical_step = find_step_definition(step["name"]&.to_s)
+            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_workflow_rendering(
@@ -893,6 +912,20 @@ module Ace
           skill_source_resolver.resolve_step_rendering(step["name"]&.to_s)
         end
 
+        def split_child_without_explicit_fork?(step)
+          step["parent"] && !step.key?("context") && !step.key?("fork")
+        end
+
+        def preserve_explicit_child_skill?(step)
+          step["parent"] && step["sub_steps_origin"] == "explicit"
+        end
+
+        def fork_context_value?(value)
+          normalized = value.to_s.strip.downcase
+          normalized = normalized.delete_prefix(":")
+          normalized == "fork"
+        end
+
         def render_skill_backed_step_instructions(step:, rendering:)
           if step_render_mode(rendering) == "step_template"
             return render_step_template_instructions(step: step, rendering: rendering)
@@ -1201,6 +1234,7 @@ module Ace
 
         def insert_batch_step_tree(step_config, after:, as_child:, added_by:, location:)
           normalized = normalize_batch_step_hash(step_config, location: location)
+          normalized = apply_inferred_parent_for_sibling_insert(normalized, after: after, as_child: as_child)
 
           if canonical_batch_insert_requested?(normalized)
             canonical_inserted = insert_canonical_batch_step_tree(
@@ -1456,6 +1490,27 @@ module Ace
           end
         end
 
+        def apply_inferred_parent_for_sibling_insert(step_config, after:, as_child:)
+          return step_config unless step_config.is_a?(Hash)
+          return step_config if as_child
+          return step_config if after.nil? || after.to_s.strip.empty?
+          return step_config if step_config.key?("parent")
+
+          inferred_parent = infer_parent_from_anchor(after)
+          return step_config if inferred_parent.nil? || inferred_parent.to_s.strip.empty?
+
+          step_config.merge("parent" => inferred_parent)
+        end
+
+        def infer_parent_from_anchor(anchor_number)
+          assignment = assignment_manager.find_active
+          return nil unless assignment
+
+          state = queue_scanner.scan(assignment.steps_dir, assignment: assignment)
+          anchor = state.find_by_number(anchor_number.to_s.strip)
+          anchor&.parent
+        end
+
         def default_dynamic_step_instructions
           DEFAULT_DYNAMIC_STEP_INSTRUCTIONS
         end

data/lib/ace/assign/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Assign
-    VERSION = "0.41.10"
+    VERSION = "0.42.4"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-assign
 version: !ruby/object:Gem::Version
-  version: 0.41.10
+  version: 0.42.4
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-04-01 00:00:00.000000000 Z
+date: 2026-04-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli