ace-coworker 0.6.0

data/lib/ace/coworker/models/preparation.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Ace
+  module Coworker
+    module Models
+      # Immutable preparation result for `ace-coworker prepare`: the accepted
+      # commission (task + roles), the resolved worktree (path/branch/
+      # disposition) or the conflict that blocked it, plus the executor
+      # evidence collected from the worktree. No IO.
+      class Preparation
+        attr_reader :task, :task_path, :roles, :worktree, :worktree_assignments,
+          :active_executor, :conflict, :assignments, :start_configs, :report, :dry_run
+
+        # worktree: {"path" =>, "branch" =>, "disposition" =>} or nil
+        # conflict: {"kind" =>, "detail" =>, "hitl_event" =>, "delivered" =>}
+        #   or nil; a non-nil conflict replaces the worktree in #to_h.
+        # assignments: ordered role-sequence assignments composed by the
+        #   planner (L4.2): {"role", "position", "of", "assignment",
+        #   "disposition", "steps", "outcome"} per role, stored by
+        #   ace-assign in the worktree.
+        # start_configs: per-role leg configs written by the planner
+        #   (L4.3): {"role", "assignment", "path", "disposition"} per leg,
+        #   at .ace-local/coworker/prepare/<role>.yml in the worktree.
+        # report: the planner's readiness report to the overseer via
+        #   ace-hitl (L4.4) on success: {"kind" => "readiness",
+        #   "event" =>, "delivered" =>} or {"kind" =>, "error" =>} when
+        #   the report could not be created; nil when no report applies
+        #   (dry-run) or a conflict escalation replaced it.
+        def initialize(task:, task_path:, roles:, worktree: nil,
+          worktree_assignments: [], active_executor: nil, conflict: nil,
+          assignments: [], start_configs: [], report: nil, dry_run: false)
+          @task = task
+          @task_path = task_path
+          @roles = roles.map(&:freeze).freeze
+          @worktree = worktree
+          @worktree_assignments = worktree_assignments.map(&:freeze).freeze
+          @active_executor = active_executor
+          @conflict = conflict
+          @assignments = assignments.map(&:freeze).freeze
+          @start_configs = start_configs.map(&:freeze).freeze
+          @report = report ? report.dup.freeze : nil
+          @dry_run = dry_run
+        end
+
+        def conflict?
+          !conflict.nil?
+        end
+
+        def to_h
+          payload = {
+            "task" => task,
+            "task_path" => task_path,
+            "roles" => roles,
+            "assignments" => assignments,
+            "start_configs" => start_configs,
+            "report" => report,
+            "active_executor" => active_executor,
+            "worktree_assignments" => worktree_assignments,
+            "conflict" => conflict
+          }
+          payload["worktree"] = worktree unless conflict?
+          payload
+        end
+      end
+    end
+  end
+end

data/lib/ace/coworker/models/resume_plan.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Ace
+  module Coworker
+    module Models
+      # Immutable resume plan derived from the assignment snapshot, the
+      # worktree git state, and the report helper state. No IO.
+      class ResumePlan
+        attr_reader :disposition, :preserved_steps, :remaining_steps,
+          :in_flight, :in_flight_cause, :step_report_path,
+          :effect_caution_steps, :git, :redeliver_event_id
+
+        def initialize(disposition:, preserved_steps: [], remaining_steps: [],
+          in_flight: nil, in_flight_cause: nil, step_report_path: nil,
+          effect_caution_steps: [], git: {}, redeliver_event_id: nil)
+          @disposition = disposition
+          @preserved_steps = preserved_steps.map(&:freeze).freeze
+          @remaining_steps = remaining_steps.map(&:freeze).freeze
+          @in_flight = in_flight
+          @in_flight_cause = in_flight_cause
+          @step_report_path = step_report_path
+          @effect_caution_steps = effect_caution_steps.map(&:freeze).freeze
+          @git = git.freeze
+          @redeliver_event_id = redeliver_event_id
+        end
+
+        def continue?
+          disposition == :continue
+        end
+
+        def to_h
+          {
+            "disposition" => disposition.to_s,
+            "preserved_steps" => preserved_steps,
+            "remaining_steps" => remaining_steps,
+            "in_flight" => in_flight,
+            "in_flight_cause" => in_flight_cause,
+            "step_report_path" => step_report_path,
+            "effect_caution_steps" => effect_caution_steps,
+            "git" => git,
+            "redeliver_event_id" => redeliver_event_id
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ace
+  module Coworker
+    module Molecules
+      # Reads the assignment's own metadata (.ace-local/assign/<id>/assignment.yaml)
+      # for the task↔assignment match check. Read-only: ace-assign owns the files.
+      class AssignmentMetadata
+        ASSIGN_DIR = File.join(".ace-local", "assign")
+
+        def initialize(project_root:)
+          @project_root = project_root
+        end
+
+        def assignment_dir(assignment_id)
+          id = assignment_id.to_s
+          unless id.match?(/\A[\w.-]+\z/) && !id.match?(/\A\.+\z/)
+            raise Error, "invalid assignment id '#{id}': expected letters, digits, dot, dash, or underscore"
+          end
+
+          File.join(@project_root, ASSIGN_DIR, id)
+        end
+
+        def assignment_file(assignment_id)
+          File.join(assignment_dir(assignment_id), "assignment.yaml")
+        end
+
+        # @return [String, nil] the task_id recorded by ace-assign
+        # @raise [Error] when the assignment does not exist under .ace-local/assign/
+        def task_id!(assignment_id)
+          path = assignment_file(assignment_id)
+          unless File.file?(path)
+            raise Error, "assignment '#{assignment_id}' not found under #{File.join(ASSIGN_DIR, assignment_id)}"
+          end
+
+          data = YAML.safe_load_file(path, permitted_classes: [Date], aliases: true) || {}
+          data["task_id"].to_s.strip
+        end
+
+        # @raise [Error] when the assignment belongs to a different task
+        def verify_task_match!(assignment_id, task_ref)
+          recorded = task_id!(assignment_id)
+          if recorded.empty?
+            raise Error, "assignment '#{assignment_id}' has no task_id; cannot match task '#{task_ref}'"
+          end
+          if recorded != task_ref.to_s
+            raise Error, "assignment '#{assignment_id}' belongs to task '#{recorded}', not '#{task_ref}'"
+          end
+
+          recorded
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "open3"
+require "json"
+
+module Ace
+  module Coworker
+    module Molecules
+      # Probes assignment truth via `ace-assign status --assignment <id> --format json`
+      # with an injectable runner (ADR-031: argv array + explicit cwd).
+      class AssignmentProbe
+        DEFAULT_RUNNER = ->(argv, cwd) { Open3.capture3(*argv, chdir: cwd) }
+
+        def initialize(project_root:, runner: DEFAULT_RUNNER)
+          @project_root = project_root
+          @runner = runner
+        end
+
+        # @return [Models::AssignmentSnapshot]
+        # @raise [Error] when the assignment is unknown or status cannot be read
+        def snapshot(assignment_id)
+          argv = [assign_binary, "status", "--assignment", assignment_id.to_s, "--format", "json"]
+          begin
+            out, err, status = run(argv)
+          rescue Errno::ENOENT
+            raise Error, "required CLI '#{assign_binary}' not found; install the ace-assign gem"
+          end
+          unless status.success?
+            message = err.to_s.strip.empty? ? out.to_s.strip : err.to_s.strip
+            raise Error, "cannot read assignment '#{assignment_id}': #{message}"
+          end
+
+          begin
+            payload = JSON.parse(out)
+          rescue JSON::ParserError => e
+            raise Error, "cannot parse ace-assign status for '#{assignment_id}': #{e.message}"
+          end
+
+          Models::AssignmentSnapshot.from_status_json(payload)
+        end
+
+        private
+
+        def run(argv)
+          @runner.call(argv, @project_root)
+        end
+
+        # Prefer the repo binstub when present (agent shells do not activate
+        # mise, so bare ace-* may resolve to stale installed gems).
+        def assign_binary
+          binstub = File.join(@project_root, "bin", "ace-assign")
+          File.executable?(binstub) ? binstub : "ace-assign"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ace
+  module Coworker
+    module Molecules
+      # Loads and validates .ace-local/coworker/config.yml.
+      #
+      # Missing or invalid input produces specific errors; the loader never
+      # guesses a substitute commission.
+      class ConfigLoader
+        DEFAULT_CONFIG_PATH = File.join(".ace-local", "coworker", "config.yml")
+
+        # @param project_root [String] absolute project root
+        # @param path [String, nil] explicit config path (absolute or root-relative)
+        # @param defaults [Hash] cascade defaults (config_path override)
+        def initialize(project_root:, defaults: {})
+          @project_root = project_root
+          @defaults = defaults || {}
+        end
+
+        def config_path
+          configured = @defaults["config_path"].to_s.strip
+          relative = configured.empty? ? DEFAULT_CONFIG_PATH : configured
+          File.expand_path(relative, @project_root)
+        end
+
+        # @return [Models::Config]
+        def load(path: nil)
+          target = path ? File.expand_path(path, @project_root) : config_path
+          raise Error, "not ready: #{relativize(target)} not found" unless File.file?(target)
+
+          begin
+            raw = YAML.safe_load_file(target, permitted_classes: [Date], aliases: true)
+          rescue Psych::SyntaxError => e
+            raise Error, "invalid config #{relativize(target)}: #{e.message}"
+          end
+          raw = {} if raw.nil?
+          unless raw.is_a?(Hash)
+            raise Error, "invalid config #{relativize(target)}: expected a mapping, got #{raw.class}"
+          end
+
+          errors = Atoms::ConfigSchema.errors(raw)
+          unless errors.empty?
+            raise Error, "invalid config #{relativize(target)}: #{errors.join('; ')}"
+          end
+
+          build_config(Atoms::ConfigSchema.normalize(raw), target)
+        end
+
+        def ready?(path: nil)
+          target = path ? File.expand_path(path, @project_root) : config_path
+          File.file?(target)
+        end
+
+        # Lenient overseer lookup for escalation fallbacks: reads the raw
+        # file without full-schema validation so a partial (planner-side)
+        # config can still name its overseer. Returns nil when the field is
+        # absent or the file cannot be read.
+        #
+        # @return [String, nil]
+        def overseer(path: nil)
+          target = path ? File.expand_path(path, @project_root) : config_path
+          return nil unless File.file?(target)
+
+          raw = YAML.safe_load_file(target, permitted_classes: [Date], aliases: true)
+          return nil unless raw.is_a?(Hash)
+
+          overseer = raw["overseer"].to_s
+          overseer.strip.empty? ? nil : overseer
+        rescue
+          nil
+        end
+
+        private
+
+        def build_config(normalized, target)
+          Models::Config.new(
+            role: normalized["role"],
+            instructions: normalized["instructions"],
+            start_prompt: start_prompt(normalized),
+            start_prompt_file: normalized["start_prompt_file"].to_s.empty? ? nil : normalized["start_prompt_file"],
+            task: normalized["task"],
+            assignment: normalized["assignment"],
+            overseer: normalized["overseer"],
+            reporting_channel: normalized.dig("reporting", "channel"),
+            on_failure: normalized.dig("errors", "on_failure"),
+            source_path: target
+          )
+        end
+
+        # start_prompt_file content is the prompt; the file must exist, be
+        # readable, and stay inside the project root (same containment rule
+        # as InstructionResolver: paths never escape the worktree).
+        def start_prompt(normalized)
+          literal = normalized["start_prompt"]
+          return literal unless literal.to_s.empty?
+
+          file = normalized["start_prompt_file"].to_s
+          path = File.expand_path(file, @project_root)
+          unless path.start_with?("#{@project_root}/")
+            raise Error, "start_prompt_file '#{file}' escapes the project root"
+          end
+          raise Error, "start_prompt_file '#{file}' not found in this worktree" unless File.file?(path)
+
+          content = File.read(path).strip
+          raise Error, "start_prompt_file '#{file}' is empty" if content.empty?
+
+          content
+        end
+
+        def relativize(path)
+          path.start_with?(@project_root) ? path.delete_prefix("#{@project_root}/") : path
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Ace
+  module Coworker
+    module Molecules
+      # Read-only worktree truth for resume: current branch, ahead/behind,
+      # dirty entries, last commit. Never issues mutating git subcommands;
+      # the worktree state IS the checkpoint (no journal, ADR-034).
+      class GitStateProbe
+        DEFAULT_RUNNER = ->(argv, cwd) { Open3.capture3(*argv, chdir: cwd) }
+
+        def initialize(project_root:, runner: DEFAULT_RUNNER)
+          @project_root = project_root
+          @runner = runner
+        end
+
+        # @return [Hash] frozen {branch, ahead_behind, dirty_entries, last_commit}
+        # @raise [Error] when the worktree is not a git repository
+        def state
+          status_out, status_err, status = run(%w[status --porcelain=v1 -b])
+          unless status.success?
+            raise Error, "cannot read worktree state: #{status_err.to_s.strip.empty? ? "git status failed" : status_err.strip}"
+          end
+
+          branch_line = status_out.lines.first.to_s.strip
+          branch, ahead_behind = parse_branch(branch_line)
+          dirty = status_out.lines.drop(1).map(&:strip).reject(&:empty?)
+
+          log_out, _log_err, log_status = run(%w[log -1 --pretty=format:%h|%s])
+          last_commit = log_status.success? ? log_out.to_s.strip : nil
+
+          {
+            "branch" => branch,
+            "ahead_behind" => ahead_behind,
+            "dirty_entries" => dirty,
+            "last_commit" => last_commit
+          }.freeze
+        end
+
+        private
+
+        def parse_branch(line)
+          # "## main...origin/main [ahead 1, behind 2]"
+          header = line.sub(/\A##\s+/, "")
+          return [nil, nil] if header.empty? || header.include?("no branch")
+          header = header.sub(/\ANo commits yet on /, "")
+
+          branch, tracking = header.split("...", 2)
+          ahead_behind = tracking.to_s[/\[(.+)\]/, 1]
+          [branch, ahead_behind]
+        end
+
+        def run(args)
+          @runner.call(["git", *args], @project_root)
+        rescue Errno::ENOENT
+          raise Error, "cannot read worktree state: git binary not found"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Ace
+  module Coworker
+    module Molecules
+      # Sends the coworker's report through the ace-hitl CLI (subprocess
+      # argv contract, ADR-031; injectable runner). ace-hitl owns its files;
+      # this molecule never writes HITL state directly.
+      class HitlReporter
+        DEFAULT_RUNNER = ->(argv, cwd) { Open3.capture3(*argv, chdir: cwd) }
+
+        Failure = Struct.new(:stage, :message, keyword_init: true)
+
+        def initialize(project_root:, runner: DEFAULT_RUNNER)
+          @project_root = project_root
+          @runner = runner
+        end
+
+        # @param outcome [Models::Outcome]
+        # @param cfg [Models::Config]
+        # @return [String, Failure] created event id, or Failure when the
+        #   ace-hitl create command fails
+        # @raise [Error] when ace-hitl is not available at all
+        def create(outcome, cfg)
+          argv = [hitl_binary, "create", title(outcome, cfg)]
+          argv += ["--type", "report", "--result", outcome.result]
+          body_lines(outcome, cfg).each { |line| argv += ["--body", line] }
+          argv += ["--task", cfg.task, "--assignment", cfg.assignment]
+          argv += ["--step", outcome.step.number.to_s] if outcome.step&.number
+          argv += ["--step-name", outcome.step.name.to_s] if outcome.step&.name && !outcome.step.name.to_s.empty?
+          argv += ["--to", cfg.overseer] unless cfg.overseer.to_s.strip.empty?
+
+          create_event(argv)
+        end
+
+        # Creates a report-type event (no reply expected): the planner's
+        # readiness report (L4.4) uses this. A report requires a result
+        # ("success"/"error") per the ace-hitl CLI contract.
+        #
+        # @param title [String] event title
+        # @param body_lines [Array<String>] report body lines
+        # @param task [String] task reference
+        # @param result [String] "success" or "error"
+        # @param to [String, nil] recipient address
+        # @return [String, Failure] created event id, or Failure when the
+        #   ace-hitl create command fails
+        # @raise [Error] when ace-hitl is not available at all
+        def create_report(title:, body_lines:, task:, result:, to: nil)
+          argv = [hitl_binary, "create", title]
+          argv += ["--type", "report", "--result", result]
+          body_lines.each { |line| argv += ["--body", line] }
+          argv += ["--task", task]
+          argv += ["--to", to] unless to.to_s.strip.empty?
+
+          create_event(argv)
+        end
+
+        # Creates a decision-type question event for a preparation conflict.
+        #
+        # @param title [String] event title
+        # @param question_lines [Array<String>] question body lines
+        # @param task [String] task reference
+        # @param to [String, nil] escalation recipient
+        # @return [String, Failure] created event id, or Failure when the
+        #   ace-hitl create command fails
+        # @raise [Error] when ace-hitl is not available at all
+        def create_conflict(title:, question_lines:, task:, to: nil)
+          argv = [hitl_binary, "create", title]
+          argv += ["--type", "question", "--kind", "decision"]
+          question_lines.each { |line| argv += ["--question", line] }
+          argv += ["--task", task]
+          argv += ["--to", to] unless to.to_s.strip.empty?
+
+          create_event(argv)
+        end
+
+        # @return [true, Failure]
+        def send_report(event_id)
+          out, err, status = run([hitl_binary, "send", event_id])
+          return true if status.success?
+
+          message = err.to_s.strip.empty? ? out.to_s.strip : err.to_s.strip
+          Failure.new(stage: "send", message: message)
+        end
+
+        # @return [Boolean] whether ace-hitl knows the event. Delegates to
+        # the ace-hitl CLI so its own configured root_dir (possibly not
+        # .ace-local/hitl) decides; this molecule never reconstructs HITL
+        # storage paths.
+        def event_exists?(event_id)
+          _out, _err, status = run([hitl_binary, "show", event_id, "--path"])
+          status.success?
+        end
+
+        private
+
+        def create_event(argv)
+          out, err, status = run(argv)
+          unless status.success?
+            message = err.to_s.strip.empty? ? out.to_s.strip : err.to_s.strip
+            return Failure.new(stage: "create", message: message)
+          end
+
+          out.to_s.match(/HITL event created: ([0-9a-z]{6})/) do |match|
+            return match[1]
+          end
+          Failure.new(stage: "create", message: "could not parse event id from ace-hitl output: #{out.to_s.strip}")
+        end
+
+        def run(argv)
+          @runner.call(argv, @project_root)
+        rescue Errno::ENOENT
+          raise Error, "required CLI '#{hitl_binary}' not found; install the ace-hitl gem"
+        end
+
+        # Prefer the repo binstub when present (agent shells do not activate
+        # mise, so bare ace-* may resolve to stale installed gems).
+        def hitl_binary
+          binstub = File.join(@project_root, "bin", "ace-hitl")
+          File.executable?(binstub) ? binstub : "ace-hitl"
+        end
+
+        def title(outcome, cfg)
+          outcome.success? ? "Work done - #{cfg.task}/#{cfg.assignment}" : "Assignment failed - #{cfg.task}/#{cfg.assignment}"
+        end
+
+        def body_lines(outcome, cfg)
+          lines = []
+          if outcome.success?
+            lines << "Assignment #{cfg.assignment} completed (#{outcome.evidence["progress"]})."
+          else
+            step = outcome.step
+            lines << "failed at step #{step&.number} #{step&.name}: #{outcome.cause}"
+            outcome.unfinished_steps.each { |unfinished| lines << "unfinished: #{unfinished}" }
+          end
+          lines << "record: .ace-tasks/<task>/coworker/#{cfg.assignment}.md"
+          lines << "evidence: .ace-local/assign/#{cfg.assignment}/reports/"
+          lines
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Ace
+  module Coworker
+    module Molecules
+      # Resolves the role instruction source: a file path relative to the
+      # project root, or a protocol URI (wfi://, prompt:// tmpl://) resolved
+      # through ace-nav.
+      class InstructionResolver
+        DEFAULT_NAV_RUNNER = ->(argv, cwd) { Open3.capture3(*argv, chdir: cwd) }
+
+        # The ace-nav CLI itself is missing (ENOENT on exec): the resolver
+        # never ran, so no verdict exists. Prepare treats this distinctly
+        # from a resolver that RUNS and fails — the former is a
+        # non-blocking unknown, the latter a never-ready gap.
+        class NavUnavailableError < Error; end
+
+        def initialize(project_root:, nav_runner: DEFAULT_NAV_RUNNER)
+          @project_root = project_root
+          @nav_runner = nav_runner
+        end
+
+        # @return [String] resolved absolute path of the instruction source
+        # @raise [Error] when the source cannot be resolved
+        def resolve!(instructions)
+          value = instructions.to_s.strip
+          if Atoms::ConfigSchema.protocol?(value)
+            resolve_protocol(value)
+          else
+            resolve_file(value)
+          end
+        end
+
+        private
+
+        def resolve_protocol(uri)
+          begin
+            out, err, status = @nav_runner.call([nav_binary, "resolve", uri], @project_root)
+          rescue Errno::ENOENT
+            raise NavUnavailableError,
+              "protocol instructions require the ace-nav CLI ('#{nav_binary}' not found)"
+          end
+          unless status.success?
+            message = err.to_s.strip.empty? ? out.to_s.strip : err.to_s.strip
+            raise Error, "cannot resolve instruction source '#{uri}': #{message}"
+          end
+
+          path = out.to_s.lines.map(&:strip).reject(&:empty?).first.to_s
+          raise Error, "cannot resolve instruction source '#{uri}': ace-nav returned no path" if path.empty?
+          raise Error, "instruction source '#{uri}' resolved to missing file '#{path}'" unless File.file?(path)
+
+          path
+        end
+
+        def resolve_file(relative)
+          candidate = File.expand_path(relative, @project_root)
+          # Containment first: an outside-root path must never depend on
+          # whether the outside file exists to pick its error message.
+          unless candidate.start_with?("#{@project_root}/")
+            raise Error, "instruction file '#{relative}' escapes the project root"
+          end
+          unless File.file?(candidate)
+            raise Error, "instruction file '#{relative}' not found in this worktree"
+          end
+
+          candidate
+        end
+
+        # Same binary choice as start; a privileged (root) run never
+        # executes the repository-controlled binstub — PATH only
+        # (trust-posture parity with ace-lab Verify#nav_binary).
+        def nav_binary
+          binstub = File.join(@project_root, "bin", "ace-nav")
+          use_binstub = !Process.uid.zero? && File.executable?(binstub)
+          use_binstub ? binstub : "ace-nav"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Ace
+  module Coworker
+    module Molecules
+      # Resolves the current project root (Git worktree top) with an
+      # injectable runner (ADR-031 argv contract).
+      class ProjectRoot
+        DEFAULT_GIT_RUNNER = ->(*args) { Open3.capture3("git", *args) }
+
+        def initialize(git_runner: DEFAULT_GIT_RUNNER)
+          @git_runner = git_runner
+        end
+
+        # @return [String] absolute project root; falls back to Dir.pwd
+        def resolve(from: Dir.pwd)
+          out, _err, _status = @git_runner.call("-C", from, "rev-parse", "--show-toplevel")
+          root = out.to_s.strip
+          root.empty? ? File.expand_path(from) : root
+        end
+      end
+    end
+  end
+end