ace-assign 0.37.0

data/lib/ace/assign/models/assignment_info.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Ace
+  module Assign
+    module Models
+      # Enriched assignment model combining Assignment + QueueState.
+      #
+      # Pure data carrier with computed state (ATOM pattern).
+      # Wraps an assignment with its queue state to provide
+      # computed state, progress, and current step information.
+      #
+      # @example
+      #   info = AssignmentInfo.new(assignment: assignment, queue_state: state)
+      #   info.state          # => :running
+      #   info.progress       # => "2/5"
+      #   info.current_step  # => "020-implement"
+      class AssignmentInfo
+        attr_reader :assignment, :queue_state
+
+        # @param assignment [Assignment] Assignment metadata
+        # @param queue_state [QueueState] Queue state for this assignment
+        def initialize(assignment:, queue_state:)
+          @assignment = assignment
+          @queue_state = queue_state
+        end
+
+        # Computed assignment state
+        #
+        # @return [Symbol] :empty, :failed, :completed, :running, or :paused
+        def state
+          queue_state.assignment_state
+        end
+
+        # Progress string (done/total)
+        #
+        # @return [String] Progress display (e.g., "2/5")
+        def progress
+          s = queue_state.summary
+          "#{s[:done]}/#{s[:total]}"
+        end
+
+        # Current step display string
+        #
+        # @return [String] Current step name or "-"
+        def current_step
+          queue_state.current&.name || "-"
+        end
+
+        # Check if assignment is completed
+        #
+        # @return [Boolean]
+        def completed?
+          state == :completed
+        end
+
+        # Delegate common accessors to assignment
+        def id = assignment.id
+        def name = assignment.name
+        def task_ref = assignment.name
+        def updated_at = assignment.updated_at
+        def created_at = assignment.created_at
+        def parent = assignment.parent
+      end
+    end
+  end
+end

data/lib/ace/assign/models/queue_state.rb

@@ -0,0 +1,326 @@
+# frozen_string_literal: true
+
+module Ace
+  module Assign
+    module Models
+      # Queue state model representing a snapshot of the work queue.
+      #
+      # Pure data carrier with no business logic (ATOM pattern).
+      # Provides convenient accessors for queue analysis.
+      #
+      # @example
+      #   state = QueueState.new(steps: steps, assignment: assignment)
+      #   state.current  # => Step with status :in_progress
+      #   state.pending  # => Array of pending steps
+      class QueueState
+        attr_reader :steps, :assignment
+
+        # @param steps [Array<Step>] All steps in queue order
+        # @param assignment [Assignment] Assignment metadata
+        def initialize(steps:, assignment:)
+          @steps = steps.freeze
+          @assignment = assignment
+          @children_index = build_children_index(steps)
+        end
+
+        # Get current in-progress step
+        # @return [Step, nil] Current step or nil
+        def current
+          in_progress_steps.first
+        end
+
+        # Get all in-progress steps
+        # @return [Array<Step>] In-progress steps
+        def in_progress_steps
+          steps.select { |s| s.status == :in_progress }
+        end
+
+        # Get all pending steps
+        # @return [Array<Step>] Pending steps
+        def pending
+          steps.select { |s| s.status == :pending }
+        end
+
+        # Get all done steps
+        # @return [Array<Step>] Completed steps
+        def done
+          steps.select { |s| s.status == :done }
+        end
+
+        # Get all failed steps
+        # @return [Array<Step>] Failed steps
+        def failed
+          steps.select { |s| s.status == :failed }
+        end
+
+        # Get next pending step
+        # @return [Step, nil] Next step to work on
+        def next_pending
+          pending.first
+        end
+
+        # Check if queue is empty
+        # @return [Boolean]
+        def empty?
+          steps.empty?
+        end
+
+        # Check if all steps are complete (no pending or in_progress)
+        # @return [Boolean]
+        def complete?
+          steps.all?(&:complete?)
+        end
+
+        # Get step by number
+        # @param number [String] Step number (e.g., "010", "040")
+        # @return [Step, nil] Found step
+        def find_by_number(number)
+          # Normalize to string without leading zeros for comparison
+          normalized = number.to_s.sub(/^0+/, "")
+          steps.find do |s|
+            s.number.sub(/^0+/, "") == normalized || s.number == number.to_s
+          end
+        end
+
+        # Get last step in queue
+        # @return [Step, nil] Last step
+        def last
+          steps.last
+        end
+
+        # Get last completed step
+        # @return [Step, nil] Last done step
+        def last_done
+          done.last
+        end
+
+        # Total step count
+        # @return [Integer] Number of steps
+        def size
+          steps.size
+        end
+
+        # Computed assignment state based on step statuses
+        #
+        # States (checked in priority order):
+        # - :empty     - No steps in queue
+        # - :completed - All steps complete (done or failed)
+        # - :failed    - Has failed step(s) but NOT all complete (stuck)
+        # - :running   - Has in_progress step with recent activity (< 1 hour)
+        # - :stalled   - Has in_progress step but stale (> 1 hour)
+        # - :paused    - Has pending but no in_progress (interrupted)
+        #
+        # @return [Symbol] Assignment state
+        def assignment_state
+          return :empty if empty?
+          return :completed if complete?
+          return :failed if failed.any?
+          return :running if current && recently_active?
+          return :stalled if current
+
+          :paused
+        end
+
+        # Check if the current in_progress step has recent activity
+        # @param threshold [Integer] Seconds since started_at to consider active (default: 1 hour)
+        # @return [Boolean]
+        def recently_active?(threshold: 3600)
+          return false unless current&.started_at
+
+          (Time.now - current.started_at) < threshold
+        end
+
+        # Summary for display
+        # @return [Hash] Summary statistics
+        def summary
+          {
+            total: size,
+            done: done.size,
+            in_progress: in_progress_steps.size,
+            pending: pending.size,
+            failed: failed.size
+          }
+        end
+
+        # Get all direct children of a step (O(1) via index)
+        # @param parent_number [String] Parent step number
+        # @return [Array<Step>] Direct child steps
+        def children_of(parent_number)
+          @children_index[parent_number] || []
+        end
+
+        # Get all descendants (children, grandchildren, etc.) of a step
+        # @param parent_number [String] Parent step number
+        # @return [Array<Step>] All descendant steps
+        def descendants_of(parent_number)
+          steps.select { |s| Atoms::StepNumbering.child_of?(s.number, parent_number) }
+        end
+
+        # Check whether a step number belongs to a subtree rooted at root_number.
+        #
+        # @param root_number [String] Subtree root step number
+        # @param step_number [String] Candidate step number
+        # @return [Boolean] True when candidate is root or descendant of root
+        def in_subtree?(root_number, step_number)
+          step_number == root_number || Atoms::StepNumbering.child_of?(step_number, root_number)
+        end
+
+        # Get all steps in a subtree (root + descendants), preserving queue order.
+        #
+        # @param root_number [String] Subtree root step number
+        # @return [Array<Step>] Subtree steps in queue order
+        def subtree_steps(root_number)
+          steps.select { |s| in_subtree?(root_number, s.number) }
+        end
+
+        # Check whether all steps in a subtree are complete.
+        #
+        # @param root_number [String] Subtree root step number
+        # @return [Boolean] True when every subtree step is complete
+        def subtree_complete?(root_number)
+          scoped = subtree_steps(root_number)
+          return false if scoped.empty?
+
+          scoped.all?(&:complete?)
+        end
+
+        # Check whether a subtree has at least one failed step.
+        #
+        # @param root_number [String] Subtree root step number
+        # @return [Boolean] True when any subtree step failed
+        def subtree_failed?(root_number)
+          subtree_steps(root_number).any? { |s| s.status == :failed }
+        end
+
+        # Get the current in-progress step within a subtree.
+        #
+        # @param root_number [String] Subtree root step number
+        # @return [Step, nil] In-progress step inside subtree, if any
+        def current_in_subtree(root_number)
+          in_progress_in_subtree(root_number).first
+        end
+
+        # Get all in-progress steps within a subtree.
+        #
+        # @param root_number [String] Subtree root step number
+        # @return [Array<Step>] In-progress steps inside subtree
+        def in_progress_in_subtree(root_number)
+          subtree_steps(root_number)
+            .select { |s| s.status == :in_progress }
+        end
+
+        # Get next workable step constrained to a subtree.
+        #
+        # @param root_number [String] Subtree root step number
+        # @return [Step, nil] Next pending workable step inside subtree
+        def next_workable_in_subtree(root_number)
+          subtree_steps(root_number)
+            .select { |s| s.status == :pending }
+            .reject { |s| has_incomplete_children?(s.number) }
+            .first
+        end
+
+        # Build ancestor chain from closest parent to root.
+        #
+        # @param number [String] Step number
+        # @return [Array<String>] Ancestor numbers, nearest first
+        def ancestor_chain(number)
+          chain = []
+          parent = Atoms::StepNumbering.parent_of(number)
+          while parent
+            chain << parent
+            parent = Atoms::StepNumbering.parent_of(parent)
+          end
+          chain
+        end
+
+        # Find nearest ancestor (or self) that has context: fork.
+        #
+        # @param number [String] Step number
+        # @return [Step, nil] Nearest fork-scoped step
+        def nearest_fork_ancestor(number)
+          step = find_by_number(number)
+          return nil unless step
+
+          return step if step.fork?
+
+          ancestor_chain(number).each do |ancestor_number|
+            ancestor = find_by_number(ancestor_number)
+            return ancestor if ancestor&.fork?
+          end
+
+          nil
+        end
+
+        # Check if a step has any incomplete children
+        # @param parent_number [String] Parent step number
+        # @return [Boolean] True if any child is not done
+        def has_incomplete_children?(parent_number)
+          children_of(parent_number).any? { |s| s.status != :done }
+        end
+
+        # Get next workable step considering hierarchy.
+        # A step is workable if it's pending and has no incomplete children.
+        # Prefers children of current/recent work.
+        # @return [Step, nil] Next step to work on
+        def next_workable
+          # First, find pending steps
+          pending_steps = pending
+
+          # Filter to steps that don't have incomplete children
+          workable = pending_steps.reject { |s| has_incomplete_children?(s.number) }
+
+          # Return first workable step (already sorted by number)
+          workable.first
+        end
+
+        # Get all step numbers as an array
+        # @return [Array<String>] All step numbers
+        def all_numbers
+          steps.map(&:number)
+        end
+
+        # Get top-level (root) steps only
+        # @return [Array<Step>] Steps with no parent
+        def top_level
+          steps.select { |s| Atoms::StepNumbering.top_level?(s.number) }
+        end
+
+        # Build hierarchical structure for display
+        # @return [Array<Hash>] Nested structure with :step and :children keys
+        def hierarchical
+          build_hierarchy(nil)
+        end
+
+        private
+
+        # Build index of children by parent number for O(1) lookups
+        # @param steps [Array<Step>] All steps
+        # @return [Hash<String, Array<Step>>] Parent number => children mapping
+        def build_children_index(steps)
+          index = Hash.new { |h, k| h[k] = [] }
+          steps.each do |step|
+            parsed = Atoms::StepNumbering.parse(step.number)
+            index[parsed[:parent]] << step if parsed[:parent]
+          end
+          index
+        end
+
+        def build_hierarchy(parent_number)
+          parent_steps = if parent_number.nil?
+            top_level
+          else
+            children_of(parent_number)
+          end
+
+          parent_steps.map do |step|
+            {
+              step: step,
+              children: build_hierarchy(step.number)
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/models/step.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module Ace
+  module Assign
+    module Models
+      # Step data model representing a work queue item.
+      #
+      # Pure data carrier with no business logic (ATOM pattern).
+      # All attributes are immutable after initialization.
+      #
+      # @example
+      #   step = Step.new(
+      #     number: "010",
+      #     name: "init-project",
+      #     status: :pending,
+      #     instructions: "Create project structure..."
+      #   )
+      class Step
+        # Valid status values
+        STATUSES = %i[pending in_progress done failed].freeze
+
+        # Valid context values for execution context
+        VALID_CONTEXTS = %w[fork].freeze
+
+        attr_reader :number, :name, :status, :instructions, :report, :error,
+          :started_at, :completed_at, :added_by, :parent, :file_path, :skill, :context,
+          :workflow,
+          :batch_parent, :parallel, :max_parallel, :fork_retry_limit,
+          :fork_launch_pid, :fork_tracked_pids, :fork_pid_updated_at, :fork_pid_file,
+          :stall_reason
+
+        # @param number [String] Step number (e.g., "010", "010.01")
+        # @param name [String] Step name
+        # @param status [Symbol] Step status (:pending, :in_progress, :done, :failed)
+        # @param instructions [String] Step instructions (markdown)
+        # @param report [String, nil] Completion report content
+        # @param error [String, nil] Error message (if failed)
+        # @param started_at [Time, nil] When work started
+        # @param completed_at [Time, nil] When completed/failed
+        # @param added_by [String, nil] How step was added (nil, "dynamic", "retry_of:NNN")
+        # @param parent [String, nil] Parent step number (for sub-steps)
+        # @param file_path [String, nil] Path to step file
+        # @param skill [String, nil] Skill reference for this step (e.g., "ace-task-work")
+        # @param context [String, nil] Execution context ("fork" for Task tool execution)
+        # @param batch_parent [Boolean, nil] Whether step is a batch scheduling parent
+        # @param parallel [Boolean, nil] Batch scheduling mode hint (true=parallel, false=sequential)
+        # @param max_parallel [Integer, nil] Max concurrent children for parallel batches
+        # @param fork_retry_limit [Integer, nil] Retry attempts allowed per failed child
+        # @param fork_launch_pid [Integer, nil] PID of the process that launched the fork run
+        # @param fork_tracked_pids [Array<Integer>, nil] Observed subprocess/descendant PIDs during fork execution
+        # @param fork_pid_updated_at [Time, nil] Timestamp when fork PID metadata was last updated
+        # @param fork_pid_file [String, nil] Path to fork PID metadata file
+        # @param stall_reason [String, nil] Last agent message captured when fork stalled
+        def initialize(number:, name:, status:, instructions:, report: nil, error: nil,
+          started_at: nil, completed_at: nil, added_by: nil, parent: nil,
+          file_path: nil, skill: nil, workflow: nil, context: nil,
+          batch_parent: nil, parallel: nil, max_parallel: nil, fork_retry_limit: nil,
+          fork_launch_pid: nil, fork_tracked_pids: nil, fork_pid_updated_at: nil,
+          fork_pid_file: nil, stall_reason: nil)
+          validate_status!(status)
+          validate_context!(context) if context
+          validate_boolean!(:batch_parent, batch_parent)
+          validate_boolean!(:parallel, parallel)
+          validate_positive_integer!(:max_parallel, max_parallel)
+          validate_non_negative_integer!(:fork_retry_limit, fork_retry_limit)
+
+          @number = number.freeze
+          @name = name.freeze
+          @status = status
+          @instructions = instructions.freeze
+          @report = report&.freeze
+          @error = error&.freeze
+          @started_at = started_at
+          @completed_at = completed_at
+          @added_by = added_by&.freeze
+          @parent = parent&.freeze
+          @file_path = file_path&.freeze
+          @skill = skill&.freeze
+          @workflow = workflow&.freeze
+          @context = context&.freeze
+          @batch_parent = batch_parent.nil? ? nil : !!batch_parent
+          @parallel = parallel.nil? ? nil : !!parallel
+          @max_parallel = max_parallel&.to_i
+          @fork_retry_limit = fork_retry_limit&.to_i
+          @fork_launch_pid = fork_launch_pid&.to_i
+          @fork_tracked_pids = Array(fork_tracked_pids).map(&:to_i).uniq.sort.freeze
+          @fork_pid_updated_at = fork_pid_updated_at
+          @fork_pid_file = fork_pid_file&.freeze
+          @stall_reason = stall_reason&.freeze
+        end
+
+        # Check if step is complete (done or failed)
+        # @return [Boolean]
+        def complete?
+          %i[done failed].include?(status)
+        end
+
+        # Check if step can be worked on
+        # @return [Boolean]
+        def workable?
+          status == :pending || status == :in_progress
+        end
+
+        # Check if this is a retry of another step
+        # @return [Boolean]
+        def retry?
+          added_by&.start_with?("retry_of:")
+        end
+
+        # Check if this step should run in a forked context (subagent)
+        # @return [Boolean]
+        def fork?
+          context == "fork"
+        end
+
+        # Get the original step number if this is a retry
+        # @return [String, nil] Original step number
+        def retry_of
+          return nil unless retry?
+
+          added_by.sub("retry_of:", "")
+        end
+
+        # Convert to frontmatter hash for YAML serialization
+        # @return [Hash] Frontmatter data
+        def to_frontmatter
+          {
+            "name" => name,
+            "status" => status.to_s,
+            "skill" => skill,
+            "workflow" => workflow,
+            "context" => context,
+            "batch_parent" => batch_parent,
+            "parallel" => parallel,
+            "max_parallel" => max_parallel,
+            "fork_retry_limit" => fork_retry_limit,
+            "started_at" => started_at&.iso8601,
+            "completed_at" => completed_at&.iso8601,
+            "fork_launch_pid" => fork_launch_pid,
+            "fork_tracked_pids" => fork_tracked_pids,
+            "fork_pid_updated_at" => fork_pid_updated_at&.iso8601,
+            "fork_pid_file" => fork_pid_file,
+            "error" => error,
+            "stall_reason" => stall_reason,
+            "added_by" => added_by,
+            "parent" => parent
+          }.compact
+        end
+
+        # Convert to display row for status table
+        # @return [Hash] Display row data
+        def to_display_row
+          {
+            file: File.basename(file_path || "#{number}-#{name}.st.md"),
+            status: status.to_s,
+            name: name,
+            error: error
+          }
+        end
+
+        private
+
+        def validate_status!(status)
+          return if STATUSES.include?(status)
+
+          raise ArgumentError, "Invalid status: #{status}. Must be one of: #{STATUSES.join(", ")}"
+        end
+
+        def validate_context!(context)
+          return if VALID_CONTEXTS.include?(context)
+
+          raise ArgumentError, "Invalid context '#{context}'. Valid values: #{VALID_CONTEXTS.join(", ")}"
+        end
+
+        def validate_boolean!(field_name, value)
+          return if value.nil? || value == true || value == false
+
+          raise ArgumentError, "Invalid #{field_name}: #{value.inspect}. Must be true, false, or nil"
+        end
+
+        def validate_positive_integer!(field_name, value)
+          return if value.nil?
+          return if value.is_a?(Integer) && value.positive?
+
+          raise ArgumentError, "Invalid #{field_name}: #{value.inspect}. Must be an integer > 0"
+        end
+
+        def validate_non_negative_integer!(field_name, value)
+          return if value.nil?
+          return if value.is_a?(Integer) && value >= 0
+
+          raise ArgumentError, "Invalid #{field_name}: #{value.inspect}. Must be an integer >= 0"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Ace
+  module Assign
+    module Molecules
+      # Discovers and enriches assignments with computed state.
+      #
+      # Combines AssignmentManager (file operations) with QueueScanner
+      # (step scanning) to produce AssignmentInfo objects with full
+      # state, progress, and current step information.
+      class AssignmentDiscoverer
+        # @param cache_base [String, nil] Base cache directory
+        def initialize(cache_base: nil)
+          @cache_base = cache_base || Ace::Assign.cache_dir
+          @assignment_manager = AssignmentManager.new(cache_base: @cache_base)
+          @queue_scanner = QueueScanner.new
+        end
+
+        # Find all assignments with computed state
+        #
+        # NOTE: Performance — This loads and enriches every assignment before filtering.
+        # Acceptable for typical usage (< 50 assignments). If assignment counts grow large,
+        # consider filtering by state at the manager level before enrichment to avoid
+        # unnecessary QueueScanner.scan calls on completed assignments.
+        #
+        # @param include_completed [Boolean] Include completed assignments (default: false)
+        # @return [Array<Models::AssignmentInfo>] Enriched assignments
+        def find_all(include_completed: false)
+          @assignment_manager.list
+            .map { |a| enrich_assignment(a) }
+            .select { |ai| include_completed || !ai.completed? }
+        end
+
+        # Find assignments by task reference (assignment name)
+        #
+        # @param task_ref [String] Task reference to filter by
+        # @param active_only [Boolean] Only return active assignments (default: true)
+        # @return [Array<Models::AssignmentInfo>] Matching assignments
+        def find_by_task(task_ref:, active_only: true)
+          find_all(include_completed: !active_only)
+            .select { |ai| ai.assignment.name == task_ref }
+        end
+
+        private
+
+        # Enrich an assignment with queue state to create AssignmentInfo
+        #
+        # @param assignment [Models::Assignment] Raw assignment
+        # @return [Models::AssignmentInfo] Enriched assignment
+        def enrich_assignment(assignment)
+          state = @queue_scanner.scan(assignment.steps_dir, assignment: assignment)
+          Models::AssignmentInfo.new(assignment: assignment, queue_state: state)
+        end
+      end
+    end
+  end
+end