robot_lab-to 0.2.6

data/lib/robot_lab/to/commit_manager.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module RobotLab
+  module To
+    # All git operations needed by the orchestrator.
+    #
+    # All subprocess calls use explicit argv arrays (no shell interpolation).
+    # GIT_TERMINAL_PROMPT=0 prevents credential prompts from hanging the loop.
+    class CommitManager
+      GIT_ENV = { "GIT_TERMINAL_PROMPT" => "0" }.freeze
+
+      def initialize(work_dir: Dir.pwd)
+        @work_dir = work_dir
+      end
+
+      def current_branch
+        git("rev-parse", "--abbrev-ref", "HEAD").chomp
+      end
+
+      def head_sha
+        git("rev-parse", "HEAD").chomp
+      end
+
+      def create_branch(name)
+        git("checkout", "-b", name)
+      end
+
+      # Switch to an existing branch (used when resuming a prior run).
+      def checkout_branch(name)
+        git("checkout", name)
+      end
+
+      def staged?
+        _out, _err, status = Open3.capture3(GIT_ENV, "git", "diff", "--cached", "--quiet",
+                                            chdir: @work_dir)
+        !status.success? # exit 1 = changes are staged
+      end
+
+      def add_all
+        git("add", "-A")
+      end
+
+      def commit(message)
+        out, err, status = Open3.capture3(
+          GIT_ENV, "git", "-c", "commit.gpgsign=false", "-c", "tag.gpgsign=false",
+          "commit", "-m", message,
+          chdir: @work_dir
+        )
+        return if status.success?
+
+        raise CommitFailedError.new("git commit failed", output: (out + err).strip)
+      end
+
+      def head_exists?
+        _out, _err, status = Open3.capture3(GIT_ENV, "git", "rev-parse", "--verify", "HEAD",
+                                            chdir: @work_dir)
+        status.success?
+      end
+
+      def reset_hard
+        return unless head_exists?
+
+        git("reset", "--hard", "HEAD")
+        git("clean", "-fd")
+      end
+
+      def diff_stat(base_sha)
+        out, _err, _status = Open3.capture3(GIT_ENV, "git", "diff", "--stat",
+                                            "#{base_sha}..HEAD", chdir: @work_dir)
+        parse_diff_stat(out)
+      end
+
+      def add_to_local_exclude(entry)
+        exclude = Pathname.new(@work_dir).join(".git", "info", "exclude")
+        exclude.parent.mkpath
+        content = exclude.exist? ? exclude.read : ""
+        return if content.include?(entry)
+
+        File.open(exclude, "a") { |f| f.puts(entry) }
+      end
+
+      def changed_files_since(base_sha)
+        out, _err, _status = Open3.capture3(GIT_ENV, "git", "diff", "--name-only",
+                                            "#{base_sha}..HEAD", chdir: @work_dir)
+        out.lines.map(&:chomp).reject(&:empty?)
+      end
+
+      # Files differing between a ref and the current working tree (uncommitted
+      # changes), INCLUDING new untracked files. Used by pairwise evals to compare
+      # a draft against its parent -- and a prose doer typically CREATES the
+      # document, so the untracked case is the common one (`git diff` alone misses
+      # new files).
+      def changed_vs_worktree(ref)
+        tracked, = Open3.capture3(GIT_ENV, "git", "diff", "--name-only", ref, chdir: @work_dir)
+        untracked, = Open3.capture3(GIT_ENV, "git", "ls-files", "--others", "--exclude-standard",
+                                    chdir: @work_dir)
+        (tracked.lines + untracked.lines).map(&:chomp).reject(&:empty?).uniq
+      end
+
+      # Contents of a path at a given ref, or "" when it did not exist there.
+      def show(ref, path)
+        out, _err, status = Open3.capture3(GIT_ENV, "git", "show", "#{ref}:#{path}",
+                                           chdir: @work_dir)
+        status.success? ? out : ""
+      end
+
+      # All tracked files — the project's committed layout. Excludes the run dir
+      # (it's in .git/info/exclude), so it's a clean workspace digest.
+      def tracked_files
+        out, _err, status = Open3.capture3(GIT_ENV, "git", "ls-files", chdir: @work_dir)
+        return [] unless status.success?
+
+        out.lines.map(&:chomp).reject(&:empty?)
+      end
+
+      private
+
+      def git(*args)
+        out, err, status = Open3.capture3(GIT_ENV, "git", *args, chdir: @work_dir)
+        raise PermanentError, "git #{args.first} failed: #{err.strip}" unless status.success?
+
+        out
+      end
+
+      def parse_diff_stat(text)
+        insertions = text.scan(/(\d+) insertion/).flatten.map(&:to_i).sum
+        deletions  = text.scan(/(\d+) deletion/).flatten.map(&:to_i).sum
+        files      = text.scan(/(\d+) file/).flatten.map(&:to_i).first || 0
+        { insertions: insertions, deletions: deletions, files: files }
+      end
+    end
+  end
+end

data/lib/robot_lab/to/config/defaults.yml

@@ -0,0 +1,27 @@
+defaults:
+  provider: openai
+  model: gpt-5.5
+  max_tool_rounds: 100
+  max_consecutive_failures: 3
+  max_retries: 2
+  max_submit_nudges: 1
+  max_verify_repairs: 2
+  verify_timeout: 600
+  commit_format: default
+  run_dir: .robot_lab_to
+  local_guards: false
+  stream: true
+  debug: false
+  decisions_enabled: true
+  decision_mode: wait          # wait = poll until resolved; exit = stop and require --resume
+  decision_wait_poll: 30       # seconds between polls while waiting on a blocking decision
+  decision_timeout: null       # max seconds to wait (null = wait indefinitely)
+
+development:
+  debug: false
+
+test:
+  debug: false
+
+production:
+  debug: false

data/lib/robot_lab/to/config.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "myway_config"
+
+module RobotLab
+  module To
+    # Configuration for a robot-to run.
+    #
+    # Sources (lowest to highest precedence):
+    #   1. Bundled defaults (config/defaults.yml)
+    #   2. User config file (~/.config/robot_lab/to.yml)
+    #   3. Environment variables (ROBOT_LAB_TO_*)
+    #   4. Constructor keyword arguments (CLI overrides)
+    class Config < MywayConfig::Base
+      config_name :robot_lab_to
+      env_prefix :robot_lab_to
+      defaults_path File.expand_path("config/defaults.yml", __dir__)
+      auto_configure!
+
+      # Runtime CLI overrides — applied after load.
+      attr_writer :provider, :model, :max_iterations, :max_tokens, :stop_when,
+                  :max_consecutive_failures, :max_submit_nudges, :max_verify_repairs,
+                  :verify_command, :verify_timeout, :run_dir, :commit_format,
+                  :local_guards, :stream, :debug,
+                  :decisions_enabled, :decision_mode, :decision_wait_poll, :decision_timeout,
+                  :eval, :eval_measure, :eval_target, :require_improvement, :stop_on_plateau
+
+      # Prose/grader settings (Phase 3). attr_accessor keeps these off the reek
+      # method-count budget (Config sits at its TooManyMethods limit); they are
+      # assigned in initialize to avoid InstanceVariableAssumption. write_guard
+      # (default true) lets local_guards runs opt out of WriteGuard so a robot can
+      # freely overwrite files it is iteratively refining (e.g. prose drafts).
+      attr_accessor :eval_judge_model, :eval_spec, :eval_floor, :protect_paths, :write_guard
+
+      def initialize(**overrides)
+        super()
+        @eval = @eval_measure = @eval_target = nil
+        @require_improvement = @stop_on_plateau = nil
+        @eval_judge_model = @eval_spec = @eval_floor = nil
+        @protect_paths = []
+        @write_guard = true
+        overrides.each { |k, v| public_send(:"#{k}=", v) if respond_to?(:"#{k}=") }
+      end
+
+      # Keys defined in defaults.yml — super is safe
+      def provider                 = @provider || super
+      def model                    = @model || super
+      def max_consecutive_failures = @max_consecutive_failures || super
+      def max_submit_nudges        = @max_submit_nudges        || super
+      def max_verify_repairs       = @max_verify_repairs       || super
+      def verify_timeout           = @verify_timeout           || super
+
+      def run_dir                  = @run_dir          || super
+      def commit_format            = @commit_format    || super
+      def local_guards?            = @local_guards.nil? ? super : @local_guards
+      def stream?                  = @stream.nil? ? super : @stream
+      def debug?                   = @debug.nil? ? super : @debug
+
+      def decisions_enabled?       = @decisions_enabled.nil? ? super : @decisions_enabled
+      def decision_mode            = @decision_mode      || super
+      def decision_wait_poll       = @decision_wait_poll || super
+      # nil = wait indefinitely
+      def decision_timeout         = @decision_timeout   || super
+
+      # CLI-only options with no YAML default (nil means "no limit / not set")
+      def max_iterations           = @max_iterations
+      def max_tokens               = @max_tokens
+      def stop_when                = @stop_when
+      def verify_command           = @verify_command
+
+      # Eval strategy selection + tuning (see RobotLab::To::Evals.build). All
+      # CLI-only / nil-default. #eval may hold a strategy name ("code"/"null"), a
+      # registered symbol, an instance responding to #score, or a proc. The
+      # judge/spec/floor readers Prose needs arrive with Phase 3.
+      def eval                     = @eval
+      def eval_measure             = @eval_measure
+      def eval_target              = @eval_target
+      def stop_on_plateau          = @stop_on_plateau
+
+      # CLI/Ruby-only with a hardcoded default (MywayConfig does not generate a
+      # reliable `require_improvement?` predicate). Default true per design: the
+      # loop is strictly monotone unless --no-require-improvement is passed.
+      def require_improvement?     = @require_improvement.nil? || @require_improvement
+    end
+  end
+end

data/lib/robot_lab/to/decision.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module To
+    # An immutable snapshot of one decision file on disk.
+    #
+    # A decision is the artifact the robot writes when it hits a choice it
+    # should not make autonomously: the situation, the options, and its own
+    # recommended "lean". A human resolves it out-of-band by editing the file
+    # (set `status: resolved`, fill `resolution:`); a later iteration reads the
+    # resolution back in.
+    #
+    # Status lifecycle: pending -> resolved (by human) -> closed (resolution
+    # delivered to a robot and committed). `dismissed` is a terminal human veto.
+    Decision = Data.define(
+      :id,                # String  — d-YYYYMMDD-HHMMSS-<hex>
+      :status,            # String  — pending | resolved | closed | dismissed
+      :blocking,          # Boolean — does the loop pause until this is resolved?
+      :created_at,        # String  — ISO8601
+      :created_iteration, # Integer
+      :resolved_at,       # String or nil — ISO8601
+      :resolution,        # String or nil — the human's answer (best available)
+      :question,          # String
+      :situation,         # String
+      :options,           # Array<String>
+      :recommendation,    # String
+      :body,              # String  — full markdown body (below front matter)
+      :path               # String  — absolute path to the file
+    ) do
+      def pending?   = status.to_s == "pending"
+      def resolved?  = status.to_s == "resolved"
+      def closed?    = status.to_s == "closed"
+      def dismissed? = status.to_s == "dismissed"
+      def blocking?  = !!blocking
+
+      # True when a human has answered (resolved with a non-empty resolution).
+      def answered? = resolved? && !resolution.to_s.strip.empty?
+    end
+  end
+end

data/lib/robot_lab/to/decision_manager.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "yaml"
+
+module RobotLab
+  module To
+    # Reads and writes decision files under <run_dir>/decisions/.
+    #
+    # Parallels NotesManager: the orchestrator records decisions the robot
+    # raises and queries their status each iteration; a human resolves them by
+    # editing the file between iterations (or between cron ticks).
+    #
+    # Each decision is a markdown file with a YAML front matter block:
+    #
+    #   ---
+    #   id: d-20260701-143022-a1b2c3
+    #   status: pending
+    #   blocking: true
+    #   created_at: 2026-07-01T14:30:22Z
+    #   created_iteration: 7
+    #   resolved_at:
+    #   resolution:
+    #   ---
+    #   # Decision: <question>
+    #   ...
+    #
+    # All writes go through AtomicFile so a crash never leaves a torn file.
+    class DecisionManager
+      GLOB = "d-*.md"
+
+      attr_reader :dir
+
+      def initialize(dir)
+        @dir = Pathname.new(dir)
+      end
+
+      def setup
+        @dir.mkpath
+      end
+
+      # Persist a decision the robot raised. Returns the parsed Decision.
+      def record(question:, situation: "", options: [], recommendation: "", blocking: false, iteration: 0)
+        id   = generate_id
+        path = @dir.join("#{id}.md")
+        AtomicFile.write(path, render_new(id: id, question: question, situation: situation,
+                                          options: Array(options), recommendation: recommendation.to_s,
+                                          blocking: blocking ? true : false, iteration: iteration.to_i))
+        parse(path)
+      end
+
+      # All decisions on disk, oldest first (ids sort chronologically).
+      def all
+        Dir.glob(@dir.join(GLOB)).map { |p| parse(p) }.compact
+      end
+
+      def pending       = all.select(&:pending?)
+      # resolved but not yet closed
+      def resolved_open = all.select(&:resolved?)
+      def blocking_pending = all.select { |d| d.pending? && d.blocking? }
+      def blocking_pending? = blocking_pending.any?
+
+      # Re-read a single decision from disk (a human may have edited it).
+      def reload(decision) = parse(decision.path)
+
+      # Mark a resolved decision closed: its resolution has been delivered to a
+      # robot and committed, so it should no longer be re-injected. Flips only
+      # the status line, preserving whatever the human wrote in the body.
+      def close(decision)
+        raw = File.read(decision.path)
+        AtomicFile.write(decision.path, flip_status(raw, "closed"))
+      end
+
+      private
+
+      def generate_id
+        "d-#{Time.now.strftime("%Y%m%d-%H%M%S")}-#{SecureRandom.hex(3)}"
+      end
+
+      # Replace the status: line inside the leading front matter block only.
+      def flip_status(raw, status)
+        raw.sub(/^status:.*$/, "status: #{status}")
+      end
+
+      def render_new(id:, question:, situation:, options:, recommendation:, blocking:, iteration:)
+        options_md = options.empty? ? "(none provided)\n" : options.each_with_index.map { |o, i| "#{i + 1}. #{o}" }.join("\n") + "\n"
+        # Build the front matter with YAML.dump so question/recommendation are
+        # escaped correctly (they can contain colons, quotes, etc.).
+        front = {
+          "id" => id, "status" => "pending", "blocking" => blocking,
+          "created_at" => Time.now.utc.iso8601, "created_iteration" => iteration,
+          "resolved_at" => nil, "resolution" => nil,
+          "question" => question, "recommendation" => recommendation
+        }
+        fm = YAML.dump(front).sub(/\A---\n/, "").chomp
+        <<~MD
+          ---
+          #{fm}
+          ---
+          # Decision: #{question}
+
+          ## Situation
+          #{situation.to_s.strip.empty? ? "(none provided)" : situation.strip}
+
+          ## Options
+          #{options_md}
+          ## Recommendation (robot's lean)
+          #{recommendation.strip.empty? ? "(none provided)" : recommendation.strip}
+
+          ## Your Decision
+          <!-- Human: set `status: resolved` and fill `resolution:` in the front
+               matter above (or write your answer below this line), then re-run
+               robot-to (or `robot-to --resume <run_id>`). -->
+        MD
+      end
+
+      # Split a file into (front_matter_hash, body). Returns a Decision or nil
+      # when the file is unreadable.
+      def parse(path)
+        text = File.read(path)
+        fm, body = split_front_matter(text)
+        Decision.new(
+          id:                fm["id"] || File.basename(path, ".md"),
+          status:            (fm["status"] || "pending").to_s,
+          blocking:          truthy?(fm["blocking"]),
+          created_at:        fm["created_at"].to_s,
+          created_iteration: fm["created_iteration"].to_i,
+          resolved_at:       presence(fm["resolved_at"]),
+          resolution:        resolution_for(fm, body),
+          question:          fm["question"].to_s,
+          situation:         fm["situation"].to_s,
+          options:           Array(fm["options"]),
+          recommendation:    fm["recommendation"].to_s,
+          body:              body,
+          path:              path.to_s
+        )
+      rescue SystemCallError
+        nil
+      end
+
+      def split_front_matter(text)
+        if text.start_with?("---\n") && (close_idx = text.index("\n---", 4))
+          raw_fm = text[4...close_idx]
+          body   = text[(close_idx + 4)..].to_s.sub(/\A\n/, "")
+          [safe_yaml(raw_fm), body]
+        else
+          [{}, text]
+        end
+      end
+
+      # YAML.safe_load, falling back to a lenient line scanner when a human's
+      # hand-edited front matter is not valid YAML.
+      def safe_yaml(raw)
+        parsed = YAML.safe_load(raw, permitted_classes: [Date, Time])
+        parsed.is_a?(Hash) ? stringify(parsed) : lenient_parse(raw)
+      rescue Psych::Exception
+        lenient_parse(raw)
+      end
+
+      def lenient_parse(raw)
+        raw.lines.each_with_object({}) do |line, h|
+          next unless (m = line.match(/^([a-z_]+):\s*(.*)$/))
+
+          h[m[1]] = m[2].strip
+        end
+      end
+
+      def stringify(hash)
+        hash.transform_keys(&:to_s).transform_values { |v| v.is_a?(Time) ? v.utc.iso8601 : v }
+      end
+
+      # Prefer the front matter resolution; fall back to prose under
+      # "## Your Decision" (stripping the HTML instruction comment).
+      def resolution_for(fm, body)
+        fm_res = presence(fm["resolution"])
+        return fm_res if fm_res
+
+        section = body[/^##\s+Your Decision\s*\n(.*)\z/m, 1].to_s
+        section = section.gsub(/<!--.*?-->/m, "").strip
+        presence(section)
+      end
+
+      def presence(value)
+        s = value.to_s.strip
+        s.empty? ? nil : s
+      end
+
+      def truthy?(value)
+        %w[true yes 1].include?(value.to_s.strip.downcase)
+      end
+    end
+  end
+end

data/lib/robot_lab/to/errors.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module To
+    class Error < StandardError; end
+
+    # Unrecoverable condition (e.g. credit exhaustion). Aborts the run immediately.
+    class PermanentError < Error; end
+
+    # git commit failed. Preserves uncommitted changes so the next iteration can repair them.
+    class CommitFailedError < Error
+      attr_reader :output
+
+      def initialize(msg, output: nil)
+        super(msg)
+        @output = output
+      end
+    end
+
+    # A stop condition was triggered. Results in a clean exit (not an error).
+    class AbortError < Error
+      attr_reader :reason
+
+      def initialize(reason)
+        super
+        @reason = reason
+      end
+    end
+  end
+end

data/lib/robot_lab/to/evals/base.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module To
+    module Evals
+      # Base class for an Eval strategy. An Eval scores the uncommitted working
+      # tree against a spec and returns a Score. It is the deciding authority for
+      # commit/rollback (via gate_ok/improved) and stop (via met_target) -- not
+      # the robot's self-report.
+      #
+      # Subclasses override #score. #protected_paths lists grader artifacts the
+      # robot must not edit (wired into GraderLock in a later phase); the default
+      # is none.
+      class Base
+        def score(context)
+          raise NotImplementedError, "#{self.class}#score must return an Evals::Score"
+        end
+
+        def protected_paths = []
+      end
+    end
+  end
+end

data/lib/robot_lab/to/evals/code.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module To
+    module Evals
+      # Measured / deterministic eval for software products.
+      #
+      #   verify  - floor gate; a command that must exit 0 (correctness)
+      #   measure - optional command printing a number to stdout; higher = better
+      #   target  - optional; met_target fires when measured value >= target
+      #
+      # Composes Verifier for command execution. With no `measure`, it behaves
+      # exactly like the original verify-command gate: improved == gate, and
+      # met_target never fires (stop falls back to --stop-when).
+      class Code < Base
+        def initialize(verify: nil, measure: nil, target: nil, timeout: 600, work_dir: Dir.pwd)
+          super()
+          @verify   = verify
+          @measure  = measure
+          @target   = target
+          @timeout  = timeout
+          @work_dir = work_dir
+        end
+
+        def score(context)
+          gate_ok, output = run_gate
+          value           = measure_value
+          Score.new(
+            gate_ok:    gate_ok,
+            improved:   improved?(gate_ok, value, context.previous_value),
+            met_target: target_met?(value),
+            value:      value,
+            detail:     detail_for(gate_ok, value),
+            output:     output
+          )
+        end
+
+        private
+
+        # Returns [passed?, output]. No verify command means the floor is open.
+        def run_gate
+          return [true, nil] unless @verify
+
+          result = Verifier.new(@verify, work_dir: @work_dir, timeout: @timeout).run
+          [result.passed?, result.output]
+        end
+
+        # First number the measure command prints, or nil when not measuring.
+        def measure_value
+          return nil unless @measure
+
+          output = Verifier.new(@measure, work_dir: @work_dir, timeout: @timeout).run.output
+          match  = output[/-?\d+(?:\.\d+)?/]
+          match&.to_f
+        end
+
+        # Without a measured value, any gate-passing change is progress. With one,
+        # progress means the value strictly beat the parent (or there is no parent).
+        def improved?(gate_ok, value, previous_value)
+          return gate_ok if value.nil?
+
+          previous_value.nil? || value > previous_value
+        end
+
+        def target_met?(value)
+          !@target.nil? && !value.nil? && value >= @target
+        end
+
+        def detail_for(gate_ok, value)
+          parts = ["verify=#{gate_ok}"]
+          parts << "measure=#{value}" unless value.nil?
+          parts.join(" ")
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/to/evals/context.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module To
+    module Evals
+      # What the orchestrator hands an Eval each iteration. One value object so
+      # new fields can be added without breaking custom evals.
+      #
+      #   work_dir       - the working tree holding the robot's uncommitted changes
+      #   previous_ref   - git ref of the last committed state (HEAD before this iter)
+      #   previous_value - last committed score value (nil until tracked; Phase 2)
+      #   objective      - the run objective
+      #   iteration      - 1-based iteration number
+      Context = Data.define(:work_dir, :previous_ref, :previous_value, :objective, :iteration)
+    end
+  end
+end