ace-coworker 0.6.0

data/lib/ace/coworker/molecules/report_state_store.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Ace
+  module Coworker
+    module Molecules
+      # Helper state for reporting runs (.ace-local/coworker/reports/
+      # <assignment_id>.json): the derived result and the created HITL event
+      # id, driving create-vs-resend on reruns. Coworker owns this location.
+      class ReportStateStore
+        def initialize(project_root:)
+          @project_root = project_root
+        end
+
+        def state_path(assignment_id)
+          id = validated(assignment_id)
+          File.join(@project_root, ".ace-local", "coworker", "reports", "#{id}.json")
+        end
+
+        def read(assignment_id)
+          path = state_path(assignment_id)
+          return nil unless File.file?(path)
+
+          JSON.parse(File.read(path))
+        rescue JSON::ParserError
+          nil
+        end
+
+        def write(assignment_id, state)
+          path = state_path(assignment_id)
+          FileUtils.mkdir_p(File.dirname(path))
+          tmp_path = "#{path}.tmp.#{Process.pid}"
+          File.write(tmp_path, JSON.pretty_generate(state))
+          File.rename(tmp_path, path)
+          path
+        end
+
+        private
+
+        def validated(assignment_id)
+          id = assignment_id.to_s
+          unless id.match?(/\A[\w.-]+\z/) && !id.match?(/\A\.+\z/)
+            raise Error, "invalid assignment id '#{id}'"
+          end
+
+          id
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/molecules/review_round_store.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require_relative "../atoms/round_rule"
+require_relative "../atoms/round_record_schema"
+
+module Ace
+  module Coworker
+    module Molecules
+      # File-based review-round history for one reviewer assignment
+      # (.ace-local/coworker/review-rounds/<assignment_id>.json), following
+      # ReportStateStore. Coworker owns this location; a restart reads the
+      # same file back, so the round counter and findings history survive
+      # (contract: "wznowienie zachowuje dotychczasowe ustalenia,
+      # liczniki i wyniki"). There is no separate journal - this file is
+      # the deterministic counterpart of the reviewer's step-report round
+      # record (reviewer.wf.md rule 6).
+      class ReviewRoundStore
+        def initialize(project_root:)
+          @project_root = project_root
+        end
+
+        def state_path(assignment_id)
+          File.join(@project_root, ".ace-local", "coworker", "review-rounds",
+                    "#{validated(assignment_id)}.json")
+        end
+
+        # @return [Array<Hash>] recorded rounds, [] when absent or unparseable
+        #   (lenient for pure readers; the destructive append in record!
+        #   refuses corrupt state instead of resetting history).
+        def read(assignment_id)
+          path = state_path(assignment_id)
+          return [] unless File.file?(path)
+
+          parsed = JSON.parse(File.read(path))
+          parsed.is_a?(Array) ? parsed : []
+        rescue JSON::ParserError
+          []
+        end
+
+        # Persist the full round list atomically; the tmp file never
+        # survives a failed write.
+        def write(assignment_id, records)
+          path = state_path(assignment_id)
+          FileUtils.mkdir_p(File.dirname(path))
+          tmp_path = "#{path}.tmp.#{Process.pid}"
+          begin
+            File.write(tmp_path, JSON.pretty_generate(records))
+            File.rename(tmp_path, path)
+          ensure
+            File.delete(tmp_path) if File.exist?(tmp_path)
+          end
+          path
+        end
+
+        # Record one round and return the resulting rule verdict, so a
+        # resumed reviewer process reconstructs counters from the same
+        # file: `store.record!(id, round)` => RoundRule verdict hash.
+        #
+        # Single-writer assumption: record! is an unsynchronized
+        # read-modify-write, so concurrent record! calls on the same
+        # assignment are last-write-wins (an earlier interleaved round
+        # is lost). The lab flow runs one executor per worktree, so one
+        # reviewer process owns this file at a time; no locking is added.
+        def record!(assignment_id, record)
+          errors = Atoms::RoundRecordSchema.errors(record)
+          unless errors.empty?
+            raise Error, "invalid round record for '#{assignment_id}': #{errors.join('; ')}"
+          end
+
+          records = strict_read(assignment_id) + [record]
+          write(assignment_id, records)
+          Atoms::RoundRule.evaluate(records)
+        end
+
+        private
+
+        # Corrupt or non-array state must never be silently reset by an
+        # append: an unparseable or non-array file raises, because
+        # discarding it would erase the 10-round cap and the unresolved
+        # High/Critical history - the exact evidence this store exists
+        # to keep. An absent file is a legitimate empty history.
+        def strict_read(assignment_id)
+          path = state_path(assignment_id)
+          return [] unless File.file?(path)
+
+          parsed = begin
+            JSON.parse(File.read(path))
+          rescue JSON::ParserError
+            raise Error, "corrupt round history at #{path}"
+          end
+          raise Error, "corrupt round history at #{path}: expected an array, got #{parsed.class}" unless parsed.is_a?(Array)
+
+          parsed.each_with_index do |element, index|
+            element_errors = Atoms::RoundRecordSchema.errors(element)
+            unless element_errors.empty?
+              raise Error, "corrupt round history at #{path}: record #{index}: #{element_errors.join('; ')}"
+            end
+          end
+          parsed
+        end
+
+        def validated(assignment_id)
+          id = assignment_id.to_s
+          unless id.match?(/\A[\w.-]+\z/) && !id.match?(/\A\.+\z/)
+            raise Error, "invalid assignment id '#{id}'"
+          end
+
+          id
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/molecules/role_preset_loader.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ace
+  module Coworker
+    module Molecules
+      # Discovers role presets from the shipped gem defaults
+      # (.ace-defaults/coworker/roles/*.yml) merged shallow-by-filename with
+      # project overrides (.ace/coworker/roles/*.yml, project wins). Every
+      # loaded preset is schema-validated; presets are convenience defaults,
+      # never a role allowlist (ADR-034: the overseer decides roles).
+      class RolePresetLoader
+        GEM_ROLES_DIR = File.join(".ace-defaults", "coworker", "roles")
+        PROJECT_ROLES_DIR = File.join(".ace", "coworker", "roles")
+
+        # @param project_root [String] absolute project root
+        # @param gem_roles_dir [String, nil] explicit gem roles dir (tests)
+        def initialize(project_root:, gem_roles_dir: nil, schema: Atoms::RolePresetSchema)
+          @project_root = project_root
+          @gem_roles_dir = gem_roles_dir || File.join(gem_root, GEM_ROLES_DIR)
+          @schema = schema
+        end
+
+        # @return [Array<Hash>] sorted presets, each with "name" and
+        #   "source" ("gem"|"project") plus the normalized preset fields
+        def list
+          presets.values.sort_by { |preset| preset["name"] }
+        end
+
+        # @return [Hash] the preset for name (with "source")
+        # @raise [Error] when the name is unknown
+        def fetch(name)
+          key = name.to_s.strip
+          preset = presets[key]
+          raise Error, "unknown role '#{key}' (available: #{presets.keys.sort.join(', ')})" if preset.nil?
+
+          preset
+        end
+
+        private
+
+        def presets
+          @presets ||= begin
+            merged = {}
+            load_dir(@gem_roles_dir, "gem", merged)
+            load_dir(project_roles_dir, "project", merged)
+            merged
+          end
+        end
+
+        def project_roles_dir
+          File.join(@project_root, PROJECT_ROLES_DIR)
+        end
+
+        def load_dir(dir, source, merged)
+          Dir.glob(File.join(dir, "*.yml")).sort.each do |path|
+            preset = read_preset(path)
+            preset["source"] = source
+            merged[File.basename(path, ".yml")] = preset
+          end
+        end
+
+        def read_preset(path)
+          raw = begin
+            YAML.safe_load_file(path, permitted_classes: [Date], aliases: true)
+          rescue Psych::Exception => e
+            raise Error, "invalid role preset '#{relative(path)}': #{e.message}"
+          end
+          errors = @schema.errors(raw)
+          unless errors.empty?
+            raise Error, "invalid role preset '#{relative(path)}': #{errors.join('; ')}"
+          end
+
+          preset = @schema.normalize(raw)
+          basename = File.basename(path, ".yml")
+          unless preset["name"] == basename
+            raise Error,
+              "invalid role preset '#{relative(path)}': name field '#{preset['name']}' must match the filename '#{basename}.yml'"
+          end
+
+          preset
+        end
+
+        def relative(path)
+          path.start_with?(@project_root) ? path.delete_prefix("#{@project_root}/") : path
+        end
+
+        def gem_root
+          ::Gem.loaded_specs["ace-coworker"]&.gem_dir || File.expand_path("../../../..", __dir__)
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/molecules/role_sequence_composer.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require "ace/assign"
+# Explicit (not transitive) requires for the ace-assign surface used below.
+require "ace/assign/molecules/assignment_manager"
+require "ace/assign/molecules/step_writer"
+require "ace/assign/atoms/number_generator"
+
+module Ace
+  module Coworker
+    module Molecules
+      # Composes the planner's role-sequence assignments (L4.2): ONE
+      # ace-assign assignment per role, in dependency order, stored by
+      # ace-assign in the prepared worktree's .ace-local/assign/ — the plan
+      # is the only place steps live (ADR-034; no second queue, no sequence
+      # copy in coworker config). Each role's process comes from its
+      # per-role sequence definition (shipped
+      # .ace-defaults/coworker/sequences/<role>.yml, project override
+      # .ace/coworker/sequences/<role>.yml), so worker and reviewer get
+      # different processes matched to the same task. A role without a
+      # preset or without its own process definition is reported and
+      # NOTHING is written: another role's process is never substituted.
+      # Composition is idempotent: an existing assignment named
+      # "<task>-<role>" with a matching task_id is reused without writes.
+      # dry_run resolves the same sequence with ZERO writes: existing
+      # assignments are read-only reused, missing legs are "planned".
+      class RoleSequenceComposer
+        GEM_SEQUENCES_DIR = File.join(".ace-defaults", "coworker", "sequences")
+        PROJECT_SEQUENCES_DIR = File.join(".ace", "coworker", "sequences")
+        ASSIGN_DIR = File.join(".ace-local", "assign")
+        # Step keys the composer itself owns: lifecycle-reserved frontmatter
+        # (status/added_by/parent) must never be overridable from definition
+        # data, and name/instructions are passed as explicit arguments.
+        RESERVED_STEP_KEYS = %w[name instructions status added_by parent].freeze
+
+        # @param project_root [String] absolute root the roles work in (the
+        #   prepared worktree)
+        # @param preset_loader [RolePresetLoader, #fetch] role preset source
+        # @param gem_sequences_dir [String, nil] explicit gem sequences dir
+        def initialize(project_root:, preset_loader: nil, gem_sequences_dir: nil)
+          @project_root = project_root
+          @preset_loader = preset_loader || RolePresetLoader.new(project_root: project_root)
+          @gem_sequences_dir = gem_sequences_dir || File.join(gem_root, GEM_SEQUENCES_DIR)
+        end
+
+        # @param task [String] canonical task id
+        # @param roles [Array<String>] role sequence in dependency order
+        # @param dry_run [Boolean] resolve the whole sequence without any
+        #   writes: existing assignments are reported as "existing" (a
+        #   read-only lookup), missing legs as "planned" with a nil
+        #   assignment id
+        # @return [Array<Hash>] ordered entries:
+        #   {"role", "position", "of", "assignment", "disposition"
+        #    ("created"|"existing"|"planned"), "steps", "outcome"}
+        # @raise [Error] when any role has no preset or no process
+        #   definition; raised BEFORE any assignment is written
+        def call(task:, roles:, dry_run: false)
+          role_list = Array(roles).map(&:to_s).map(&:strip).reject(&:empty?)
+          raise Error, "role sequence requires at least one role" if role_list.empty?
+
+          # Resolve every role's process first: a missing process aborts
+          # the whole composition instead of leaving a partial sequence.
+          definitions = role_list.map { |role| load_definition(role) }
+
+          previous = nil
+          role_list.each_with_index.map do |role, index|
+            definition = definitions[index]
+            existing = find_existing(task, role)
+            entry = if existing
+              entry_for(task: task, role: role, index: index, total: role_list.length,
+                assignment_id: existing, definition: definition, disposition: "existing")
+            elsif dry_run
+              entry_for(task: task, role: role, index: index, total: role_list.length,
+                assignment_id: nil, definition: definition, disposition: "planned")
+            else
+              assignment_id = create_assignment(task: task, role: role,
+                definition: definition, index: index, total: role_list.length,
+                previous: previous)
+              entry_for(task: task, role: role, index: index, total: role_list.length,
+                assignment_id: assignment_id, definition: definition, disposition: "created")
+            end
+            previous = {"role" => role, "assignment" => entry["assignment"]}
+            entry
+          end
+        end
+
+        private
+
+        def entry_for(task:, role:, index:, total:, assignment_id:, definition:, disposition:)
+          {
+            "role" => role,
+            "position" => index + 1,
+            "of" => total,
+            "assignment" => assignment_id,
+            "disposition" => disposition,
+            "steps" => definition["steps"].length,
+            "outcome" => render(definition["outcome"], {"task" => task, "role" => role})
+          }
+        end
+
+        def create_assignment(task:, role:, definition:, index:, total:, previous:)
+          context = {"task" => task, "role" => role}
+          description = render(definition["description"], context)
+          outcome = render(definition["outcome"], context)
+          description = "#{description} (sequence #{index + 1}/#{total}); expected outcome: #{outcome}"
+
+          manager = Ace::Assign::Molecules::AssignmentManager.new(
+            cache_base: File.join(@project_root, ASSIGN_DIR))
+          assignment = manager.create(
+            name: "#{task}-#{role}",
+            description: description,
+            source_config: definition["path"],
+            task_id: task)
+
+          writer = Ace::Assign::Molecules::StepWriter.new
+          entry_condition = previous ? entry_condition_line(previous) : nil
+          definition["steps"].each_with_index do |step, step_index|
+            instructions = step_instructions(step, context: context,
+              entry_condition: step_index.zero? ? entry_condition : nil)
+            extra = step.reject { |key, _| RESERVED_STEP_KEYS.include?(key) }
+            writer.create(
+              steps_dir: assignment.steps_dir,
+              number: Ace::Assign::Atoms::NumberGenerator.from_index(step_index),
+              name: step["name"],
+              instructions: instructions,
+              status: :pending,
+              extra: extra)
+          end
+
+          assignment.id
+        end
+
+        def entry_condition_line(previous)
+          "Entry condition: assignment #{previous['assignment']} (role #{previous['role']}) " \
+            "finished successfully before this role starts."
+        end
+
+        def step_instructions(step, context:, entry_condition: nil)
+          body = Array(step["instructions"])
+            .map { |line| render(line, context) }
+            .reject(&:empty?)
+            .join("\n")
+          lines = []
+          lines << entry_condition if entry_condition
+          lines << body
+          lines.reject(&:empty?).join("\n\n")
+        end
+
+        def render(template, context)
+          Atoms::PromptTemplate.render(template.to_s, context)
+        end
+
+        # Finds an existing sequence assignment for the task+role pair:
+        # exact name "<task>-<role>" with a matching recorded task_id.
+        # Read-only over ace-assign-owned files (like AssignmentMetadata).
+        def find_existing(task, role)
+          name = "#{task}-#{role}"
+          Dir.glob(File.join(@project_root, ASSIGN_DIR, "*", "assignment.yaml")).sort.each do |path|
+            data = YAML.safe_load_file(path, permitted_classes: [Time, Date], aliases: true) || {}
+            return File.basename(File.dirname(path)) if data["name"] == name && data["task_id"].to_s == task
+          end
+          nil
+        end
+
+        # Resolves the role's process definition: the preset must exist and
+        # the role must have its own sequence definition (project override
+        # first, then the shipped default). Never substitutes.
+        def load_definition(role)
+          @preset_loader.fetch(role) # raises Error for an unknown role
+          path = sequence_path(role)
+          if path.nil?
+            raise Error,
+              "role '#{role}' has no assignment process: no " \
+                "#{File.join(PROJECT_SEQUENCES_DIR, "#{role}.yml")} project override and no " \
+                "shipped default; refusing to substitute another role's process"
+          end
+
+          raw = begin
+            YAML.safe_load_file(path, permitted_classes: [Date], aliases: true)
+          rescue Psych::Exception => e
+            raise Error, "invalid assignment process '#{relative(path)}': #{e.message}"
+          end
+          errors = definition_errors(role, raw)
+          unless errors.empty?
+            raise Error, "invalid assignment process '#{relative(path)}': #{errors.join('; ')}"
+          end
+
+          raw.merge("path" => path)
+        end
+
+        def sequence_path(role)
+          project = File.join(@project_root, PROJECT_SEQUENCES_DIR, "#{role}.yml")
+          return project if File.file?(project)
+
+          shipped = File.join(@gem_sequences_dir, "#{role}.yml")
+          File.file?(shipped) ? shipped : nil
+        end
+
+        def definition_errors(role, raw)
+          # Mirror the RolePresetSchema raw-YAML guard: an empty file or a
+          # non-mapping document is an actionable process error, never a
+          # NoMethodError/TypeError on raw["role"].
+          return ["process is empty"] if raw.nil?
+          return ["process must be a mapping, got #{raw.class}"] unless raw.is_a?(Hash)
+
+          errors = []
+          errors << "required 'role' field is missing" if raw["role"].to_s.strip.empty?
+          if raw["role"].to_s != role
+            errors << "role field '#{raw["role"]}' must match the requested role '#{role}'"
+          end
+          errors << "required 'description' field is missing" if raw["description"].to_s.strip.empty?
+          errors << "required 'outcome' field is missing" if raw["outcome"].to_s.strip.empty?
+          steps = raw["steps"]
+          if !steps.is_a?(Array) || steps.empty?
+            errors << "at least one step is required"
+          else
+            steps.each_with_index do |step, index|
+              # A scalar/null step (steps: [42], steps: [null]) must be an
+              # actionable process error, never a TypeError from indexing a
+              # non-mapping — malformed user process data stays inside the
+              # role_sequence gap path.
+              unless step.is_a?(Hash)
+                errors << "step #{index + 1}: must be a mapping with 'name' and 'instructions', got #{step.class}"
+                next
+              end
+              errors << "step #{index + 1}: 'name' is required" if step["name"].to_s.strip.empty?
+              if Array(step["instructions"]).map(&:to_s).reject(&:empty?).empty?
+                errors << "step #{index + 1}: 'instructions' are required"
+              end
+            end
+          end
+          errors.uniq
+        end
+
+        def relative(path)
+          path.start_with?(@project_root) ? path.delete_prefix("#{@project_root}/") : path
+        end
+
+        def gem_root
+          ::Gem.loaded_specs["ace-coworker"]&.gem_dir || File.expand_path("../../../..", __dir__)
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/molecules/step_evidence_reader.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ace
+  module Coworker
+    module Molecules
+      # Reads failed-step evidence from the assignment's own step state
+      # (`.ace-local/assign/<id>/steps/<n>-*.st.md`, written by
+      # `ace-assign fail --message`). Read-only; ace-assign owns the files.
+      class StepEvidenceReader
+        def initialize(project_root:)
+          @project_root = project_root
+        end
+
+        # @param assignment_id [String]
+        # @param step_number [String, Integer, nil]
+        # @return [String, nil] the recorded error cause (nil when absent)
+        # @raise [Error] on an invalid assignment id (containment)
+        def read(assignment_id, step_number)
+          number = step_number.to_s.strip
+          return nil if number.empty?
+          unless number.match?(/\A[\w.-]+\z/)
+            raise Error, "invalid step number '#{number}'"
+          end
+
+          id = assignment_id.to_s
+          unless id.match?(/\A[\w.-]+\z/) && !id.match?(/\A\.+\z/)
+            raise Error, "invalid assignment id '#{id}'"
+          end
+
+          steps_dir = File.join(@project_root, ".ace-local", "assign", id, "steps")
+          return nil unless Dir.exist?(steps_dir)
+
+          path = Dir.glob(File.join(steps_dir, "#{step_number}-*.st.md")).sort.first
+          return nil unless path
+
+          error_from_step_file(path)
+        end
+
+        private
+
+        # The `error:` frontmatter line written by ace-assign fail carries
+        # the operator-visible cause. Parse the frontmatter as YAML so
+        # quoted/multiline values survive; fall back to a regex line scan.
+        def error_from_step_file(path)
+          content = File.read(path)
+          frontmatter = content.split(/^---\s*$/m)[1].to_s
+          parsed = YAML.safe_load(frontmatter, permitted_classes: [Date, Time], aliases: false)
+          cause = parsed.is_a?(Hash) ? parsed["error"].to_s.strip : ""
+          cause = content.match(/^error:\s*(.+)$/)[1].to_s.strip if cause.empty?
+          cause.empty? ? nil : cause
+        rescue StandardError
+          match = content.match(/^error:\s*(.+)$/)
+          match && !match[1].strip.empty? ? match[1].strip : nil
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/molecules/step_report_reader.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Ace
+  module Coworker
+    module Molecules
+      # Locates the in-flight step's report file
+      # (.ace-local/assign/<id>/reports/<n>-*.r.md). Read-only; ace-assign
+      # owns the files. Same id-containment rule as StepEvidenceReader.
+      class StepReportReader
+        def initialize(project_root:)
+          @project_root = project_root
+        end
+
+        # @return [Hash, nil] {path} for the step's report, nil absent
+        # @raise [Error] on an invalid assignment id (containment)
+        def read(assignment_id, step_number)
+          number = step_number.to_s.strip
+          return nil if number.empty?
+          unless number.match?(/\A[\w.-]+\z/)
+            raise Error, "invalid step number '#{number}'"
+          end
+
+          id = assignment_id.to_s
+          unless id.match?(/\A[\w.-]+\z/) && !id.match?(/\A\.+\z/)
+            raise Error, "invalid assignment id '#{id}'"
+          end
+
+          reports_dir = File.join(@project_root, ".ace-local", "assign", id, "reports")
+          return nil unless Dir.exist?(reports_dir)
+
+          path = Dir.glob(File.join(reports_dir, "#{step_number}-*.r.md")).sort.first
+          return nil unless path
+
+          {"path" => path}
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/molecules/task_probe.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "ace/task"
+require "ace/task/organisms/task_manager"
+
+module Ace
+  module Coworker
+    module Molecules
+      # Resolves the config task ref inside the project root using the
+      # ace-task library (same resolution ace-overseer relies on).
+      class TaskProbe
+        def initialize(project_root:, task_manager: nil)
+          @project_root = project_root
+          @task_manager = task_manager || Ace::Task::Organisms::TaskManager.new(root_dir: task_root)
+        end
+
+        # @return [Ace::Task::Models::Task, nil]
+        def resolve(ref)
+          @task_manager.show(ref.to_s)
+        end
+
+        # @return [String] absolute path of the task folder
+        # @raise [Error] when the ref does not resolve in this worktree
+        def resolve!(ref)
+          task = resolve(ref)
+          raise Error, "task '#{ref}' not found in this worktree" if task.nil?
+
+          dir = task.respond_to?(:path) ? task.path : nil
+          dir || File.join(task_root, task.id.to_s)
+        end
+
+        private
+
+        def task_root
+          File.join(@project_root, ".ace-tasks")
+        end
+      end
+    end
+  end
+end