ace-assign 0.37.0

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

@@ -0,0 +1,212 @@
+---
+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-checked: 2026-03-21
+---
+
+# Run In Batches Workflow
+
+## Purpose
+
+Create a reusable repeated-item assignment from:
+
+1. One instruction template
+2. One explicit `--items` list
+3. Optional execution modifiers (`--sequential`, `--max-parallel`, `--run`)
+
+This workflow keeps creation deterministic:
+
+1. Render hidden spec under `.ace-local/assign/jobs/`
+2. Call `ace-assign create <hidden-spec-path>`
+3. Optionally hand off to `/as-assign-drive <assignment-id>`
+
+## Supported Inputs
+
+```bash
+/as-assign-run-in-batches "Run E2E scenario {{item}}" --items TS-001,TS-002 --run
+/as-assign-run-in-batches "Update docs for {{item}}" --items ace-assign,ace-task --sequential
+/as-assign-run-in-batches "Review {{item}}" --items ace-git,ace-docs,ace-lint --max-parallel 3
+```
+
+## Runtime Boundary (Hard Rule)
+
+`ace-assign create FILE` remains the deterministic runtime boundary.
+
+- Parse and normalize workflow arguments in this workflow layer.
+- Render a concrete hidden spec file.
+- Pass the hidden spec file path to `ace-assign create`.
+- Do not add natural-language parsing inside `ace-assign create`.
+
+## Process
+
+### 1. Parse Input
+
+Required:
+- One instruction template string (first positional argument)
+- `--items <comma-separated-list>`
+
+Optional:
+- `--sequential` (run children one-by-one, still in fork context)
+- `--max-parallel <N>` (parallel mode only, default: `3`; treated as rolling in-flight concurrency cap)
+- `--run` (immediate handoff to `/as-assign-drive`)
+
+If template or `--items` is missing, fail with an actionable message.
+
+### 2. Normalize and Validate Item List
+
+Normalize `--items` as:
+
+1. Split by commas
+2. Trim whitespace around each item
+3. Drop empty entries
+4. Preserve original order
+
+Validation:
+- If normalized list is empty → fail
+- If duplicates exist after normalization → fail
+- If `--max-parallel` is provided and is not an integer >= 1 → fail
+
+Example failure messages:
+- `--items is required (example: --items TS-001,TS-002)`
+- `--items produced no valid values after normalization`
+- `--items contains duplicates after normalization: TS-002`
+
+### 3. Render Per-Item Instructions
+
+For each normalized item:
+
+- If template contains `{{item}}`, substitute with the item value.
+- If template omits `{{item}}`, prepend a deterministic line:
+
+```text
+Target item: <item>
+```
+
+Then append the original template text unchanged.
+
+### 4. Render Hidden Spec
+
+Create hidden spec directory if missing:
+
+```bash
+mkdir -p .ace-local/assign/jobs
+```
+
+Write hidden spec:
+
+```bash
+.ace-local/assign/jobs/<timestamp>-run-in-batches.yml
+```
+
+Minimal structure:
+
+```yaml
+session:
+  name: run-in-batches-<timestamp>
+  description: Execute repeated-item assignment for explicit items.
+
+steps:
+  - number: "010"
+    name: batch-items
+    batch_parent: true
+    parallel: true            # false when --sequential is set
+    max_parallel: 3           # default 3 when parallel=true and flag omitted
+    fork_retry_limit: 1
+    instructions: |
+      Batch container for repeated-item execution.
+      Items: <item-1>, <item-2>, <item-3>
+      Scheduler: parallel=true, max_parallel=3.
+
+  - number: "010.01"
+    name: run-<item-1>
+    parent: "010"
+    context: fork
+    parallel: true            # mirrors parent mode; false when --sequential
+    instructions: |
+      <rendered instruction for item-1>
+
+  - number: "010.02"
+    name: run-<item-2>
+    parent: "010"
+    context: fork
+    parallel: true            # mirrors parent mode; false when --sequential
+    instructions: |
+      <rendered instruction for item-2>
+```
+
+Rules:
+- Always create one parent plus one child per item.
+- A single item still creates a valid parent/child tree.
+- Child steps always keep `context: fork` so every item is delegated in a forked environment.
+- `--sequential` sets `parallel: false` and `max_parallel: 1` on parent/children.
+- Parallel mode sets `parallel: true`; `max_parallel` is explicit or defaults to `3`.
+- In parallel mode, `max_parallel` means maximum concurrent in-flight children; it is not a fixed wave size.
+- Parent and child metadata are workflow-level scheduling hints consumed by `/as-assign-drive`.
+- Each invocation writes a new hidden spec file.
+
+### 5. Create Assignment Deterministically
+
+Invoke:
+
+```bash
+ace-assign create .ace-local/assign/jobs/<timestamp>-run-in-batches.yml
+```
+
+### 6. Optional Immediate Handoff (`--run`)
+
+If `--run` is present:
+
+```bash
+/as-assign-drive <assignment-id>
+```
+
+If no workable step is available, keep creation successful and report why drive did not continue.
+
+### 7. Report Result
+
+Show:
+- Assignment ID and name
+- Assignment path
+- Hidden spec provenance path
+- Whether drive handoff ran
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| Missing template | Fail with usage + example |
+| Missing `--items` | Fail with actionable message |
+| Empty normalized items | Fail; no assignment created |
+| Duplicate normalized items | Fail; no assignment created |
+| Invalid `--max-parallel` | Fail; no assignment created |
+| Hidden-spec render failure | Fail with concrete error |
+| `ace-assign create` rejection | Surface CLI error unchanged |
+| `--run` requested but no workable step | Keep create success; report handoff reason |
+
+## Edge Cases
+
+- Template omits `{{item}}` → prepend deterministic `Target item:` line.
+- Single-item list still uses parent + one child.
+- `--sequential` keeps fork context and only changes scheduler metadata.
+- Item normalization preserves order of first occurrences.
+
+## Success Criteria
+
+- `/as-assign-run-in-batches` accepts one template plus explicit `--items`
+- Supports `--max-parallel` with default `3` when omitted in parallel mode
+- Hidden spec is written under `.ace-local/assign/jobs/`
+- Assignment has one parent plus one child step per item
+- Child steps always include `context: fork`
+- 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`
+
+## Verification
+
+```bash
+# Ensure new workflow exists and is discoverable
+ace-bundle wfi://assign/run-in-batches
+```

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

@@ -0,0 +1,46 @@
+---
+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-checked: 2026-03-21
+---
+
+# Start Assignment Workflow (Legacy Compatibility)
+
+## Purpose
+
+`assign/start` is retained as an orchestration compatibility layer for typed canonical skill examples.
+It delegates to create/drive flows that compose steps from assign-capable canonical skills.
+
+Primary public UX remains:
+- `/as-assign-create ...`
+- `/as-assign-drive <assignment-id>`
+
+## Process
+
+1. Parse incoming arguments.
+2. If `--run` is provided, run create with run handoff enabled:
+
+```bash
+/as-assign-create $ARGUMENTS --run
+```
+
+3. Otherwise, run create without immediate handoff:
+
+```bash
+/as-assign-create $ARGUMENTS
+```
+
+4. If create succeeds and the caller requests explicit continuation, invoke:
+
+```bash
+/as-assign-drive <assignment-id>
+```
+
+## Success Criteria
+
+- Preserves compatibility entrypoint for orchestration examples.
+- Delegates behavior to `assign/create` and `assign/drive`.
+- Does not redefine the public assignment flow.

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

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module Ace
+  module Assign
+    module Atoms
+      # Pure function: extracts and validates `assign:` block from markdown frontmatter.
+      #
+      # Takes a raw YAML frontmatter hash (already parsed from a .s.md or .wf.md file),
+      # extracts the `assign:` block, validates fields, and returns a structured result.
+      #
+      # No file I/O — reuses existing frontmatter extraction from StepFileParser or ace-support-markdown.
+      #
+      # @example
+      #   frontmatter = { "id" => "v.0.9.0+task.148", "status" => "in-progress",
+      #                    "assign" => { "goal" => "implement-with-pr", "variables" => { "taskref" => "148" } } }
+      #   result = AssignFrontmatterParser.parse(frontmatter)
+      #   result[:config][:goal]  # => "implement-with-pr"
+      #   result[:valid]          # => true
+      module AssignFrontmatterParser
+        VALID_FIELDS = %w[goal variables hints sub-steps context parent].freeze
+        VALID_HINT_ACTIONS = %w[include skip].freeze
+        VALID_CONTEXTS = %w[fork].freeze
+
+        # Parse and validate the assign: block from frontmatter.
+        #
+        # @param frontmatter [Hash] Full frontmatter hash from any .s.md or .wf.md file
+        # @return [Hash] { config: Hash|nil, valid: Boolean, errors: Array<String> }
+        def self.parse(frontmatter)
+          return {config: nil, valid: true, errors: []} if frontmatter.nil? || !frontmatter.is_a?(Hash)
+
+          assign_block = frontmatter["assign"]
+          return {config: nil, valid: true, errors: []} if assign_block.nil?
+
+          errors = validate(assign_block)
+          return {config: nil, valid: false, errors: errors} if errors.any?
+
+          config = extract_config(assign_block)
+          {config: config, valid: true, errors: []}
+        end
+
+        # Validate the assign block fields.
+        #
+        # @param assign_block [Hash] The assign: block from frontmatter
+        # @return [Array<String>] List of validation errors (empty if valid)
+        def self.validate(assign_block)
+          errors = []
+
+          unless assign_block.is_a?(Hash)
+            errors << "assign: must be a mapping (Hash), got #{assign_block.class}"
+            return errors
+          end
+
+          # Check for unknown fields
+          unknown = assign_block.keys - VALID_FIELDS
+          errors << "Unknown assign fields: #{unknown.join(", ")}" if unknown.any?
+
+          # Validate goal (string)
+          if assign_block.key?("goal") && !assign_block["goal"].is_a?(String)
+            errors << "assign.goal must be a string"
+          end
+
+          # Validate variables (hash)
+          if assign_block.key?("variables") && !assign_block["variables"].is_a?(Hash)
+            errors << "assign.variables must be a mapping (Hash)"
+          end
+
+          # Validate hints (array of hashes with include/skip keys)
+          if assign_block.key?("hints")
+            errors.concat(validate_hints(assign_block["hints"]))
+          end
+
+          # Validate sub-steps (array of strings)
+          if assign_block.key?("sub-steps")
+            if !assign_block["sub-steps"].is_a?(Array)
+              errors << "assign.sub-steps must be an array"
+            elsif assign_block["sub-steps"].any? { |s| !s.is_a?(String) }
+              errors << "assign.sub-steps entries must be strings"
+            end
+          end
+
+          # Validate context (string, must be in VALID_CONTEXTS)
+          if assign_block.key?("context")
+            ctx = assign_block["context"]
+            if !ctx.is_a?(String)
+              errors << "assign.context must be a string"
+            elsif !VALID_CONTEXTS.include?(ctx)
+              errors << "assign.context must be one of: #{VALID_CONTEXTS.join(", ")}"
+            end
+          end
+
+          # Validate parent (string)
+          if assign_block.key?("parent") && !assign_block["parent"].is_a?(String)
+            errors << "assign.parent must be a string"
+          end
+
+          errors
+        end
+        private_class_method :validate
+
+        # Extract structured config from a validated assign block.
+        #
+        # @param assign_block [Hash] Validated assign: block
+        # @return [Hash] Structured config with symbolized keys
+        def self.extract_config(assign_block)
+          {
+            goal: assign_block["goal"],
+            variables: assign_block["variables"] || {},
+            hints: normalize_hints(assign_block["hints"] || []),
+            sub_steps: assign_block["sub-steps"] || [],
+            context: assign_block["context"],
+            parent: assign_block["parent"]
+          }
+        end
+        private_class_method :extract_config
+
+        # Validate hints array entries.
+        #
+        # @param hints [Object] The hints value to validate
+        # @return [Array<String>] Validation errors
+        def self.validate_hints(hints)
+          errors = []
+
+          unless hints.is_a?(Array)
+            errors << "assign.hints must be an array"
+            return errors
+          end
+
+          hints.each_with_index do |hint, idx|
+            unless hint.is_a?(Hash)
+              errors << "assign.hints[#{idx}] must be a mapping (Hash)"
+              next
+            end
+
+            actions = hint.keys & VALID_HINT_ACTIONS
+            if actions.empty?
+              errors << "assign.hints[#{idx}] must have an 'include' or 'skip' key"
+            elsif actions.size > 1
+              errors << "assign.hints[#{idx}] cannot have both 'include' and 'skip'"
+            else
+              value = hint[actions.first]
+              unless value.is_a?(String)
+                errors << "assign.hints[#{idx}].#{actions.first} must be a string, got #{value.class}"
+              end
+            end
+
+            unknown_keys = hint.keys - VALID_HINT_ACTIONS
+            if unknown_keys.any?
+              errors << "assign.hints[#{idx}] has unknown keys: #{unknown_keys.join(", ")}"
+            end
+          end
+
+          errors
+        end
+        private_class_method :validate_hints
+
+        # Normalize hints into a consistent structure.
+        #
+        # @param hints [Array<Hash>] Raw hints from frontmatter
+        # @return [Array<Hash>] Normalized hints with :action and :step keys
+        def self.normalize_hints(hints)
+          hints.map do |hint|
+            if hint.key?("include")
+              {action: :include, step: hint["include"]}
+            elsif hint.key?("skip")
+              {action: :skip, step: hint["skip"]}
+            end
+          end.compact
+        end
+        private_class_method :normalize_hints
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ace
+  module Assign
+    module Atoms
+      # Pure functions for loading and querying the step catalog.
+      #
+      # The step catalog is a directory of YAML files describing available
+      # step types, their prerequisites, artifacts, and metadata.
+      #
+      # @example Loading the catalog
+      #   steps = CatalogLoader.load_all("/path/to/catalog/steps")
+      #   # => [{ "name" => "onboard", "skill" => "onboard", ... }, ...]
+      #
+      # @example Finding a step
+      #   step = CatalogLoader.find_by_name(steps, "work-on-task")
+      #   # => { "name" => "work-on-task", "skill" => "ace:work-on-task", ... }
+      module CatalogLoader
+        # Load all step definitions from a catalog directory.
+        #
+        # @param steps_dir [String] Path to catalog/steps/ directory
+        # @return [Array<Hash>] Array of step definition hashes
+        def self.load_all(steps_dir)
+          return [] unless File.directory?(steps_dir)
+
+          Dir.glob(File.join(steps_dir, "*.step.yml")).sort.filter_map do |path|
+            parse_step_file(path)
+          end
+        end
+
+        # Find a step definition by name.
+        #
+        # @param steps [Array<Hash>] Loaded step definitions
+        # @param name [String] Step name to find
+        # @return [Hash, nil] Step definition or nil if not found
+        def self.find_by_name(steps, name)
+          steps.find { |p| p["name"] == name }
+        end
+
+        # Filter steps by tag.
+        #
+        # @param steps [Array<Hash>] Loaded step definitions
+        # @param tag [String] Tag to filter by
+        # @return [Array<Hash>] Steps matching the tag
+        def self.filter_by_tag(steps, tag)
+          steps.select { |p| (p["tags"] || []).include?(tag) }
+        end
+
+        # Find steps that produce a given artifact.
+        #
+        # @param steps [Array<Hash>] Loaded step definitions
+        # @param artifact [String] Artifact name (e.g., "code-changes")
+        # @return [Array<Hash>] Steps that produce the artifact
+        def self.producers_of(steps, artifact)
+          steps.select { |p| (p["produces"] || []).include?(artifact) }
+        end
+
+        # Validate that prerequisites are satisfied for a selection of steps.
+        #
+        # @param selected [Array<String>] Names of selected steps
+        # @param catalog [Array<Hash>] Full step catalog
+        # @return [Array<Hash>] Validation issues, each with :step, :prerequisite, :strength, :reason
+        def self.validate_prerequisites(selected, catalog)
+          issues = []
+
+          selected.each do |step_name|
+            step_def = find_by_name(catalog, step_name)
+            next unless step_def
+
+            (step_def["prerequisites"] || []).each do |prereq|
+              next if selected.include?(prereq["name"])
+
+              issues << {
+                step: step_name,
+                prerequisite: prereq["name"],
+                strength: prereq["strength"] || "recommended",
+                reason: prereq["reason"]
+              }
+            end
+          end
+
+          issues
+        end
+
+        # Parse a single step YAML file.
+        #
+        # @param path [String] File path
+        # @return [Hash, nil] Parsed step definition or nil on error
+        def self.parse_step_file(path)
+          YAML.safe_load_file(path, permitted_classes: [Date])
+        rescue => e
+          warn "Warning: Failed to parse step file #{path}: #{e.message}"
+          nil
+        end
+        private_class_method :parse_step_file
+      end
+    end
+  end
+end