robot_lab-to 0.2.7 → 0.2.8

data/examples/03_scored/scored_run.rb

@@ -26,8 +26,8 @@
 # ---------------------------------------------------------------------------
 # Run it
 # ---------------------------------------------------------------------------
-#   # Local Ollama (default — no API key; requires `ollama serve`):
-#   ollama pull gpt-oss:20b
+#   # Local LM Studio (default — no API key; common.rb starts the server and
+#   # loads the model for you if they aren't already running/loaded):
 #   bundle exec ruby examples/03_scored/scored_run.rb
 #
 #   # A cloud model instead:
@@ -35,17 +35,15 @@
 #     ANTHROPIC_API_KEY=sk-... \
 #     bundle exec ruby examples/03_scored/scored_run.rb
 #
-# Configuration (all optional, via environment):
-#   RLTO_LOCAL     true|false   use a local Ollama model (default true)
-#   RLTO_PROVIDER  name         LLM provider (default: openai for local)
-#   RLTO_MODEL     id           model id (default: qwen3.6:latest for local)
-#   OLLAMA_BASE    url          Ollama OpenAI endpoint (default localhost:11434/v1)
+# Configuration (all optional, via environment; examples/.envrc sets these for you):
+#   RLTO_LOCAL     true|false   use a local LM Studio model (default true)
+#   RLTO_PROVIDER  name         LLM provider label (default: lms for local)
+#   RLTO_MODEL     id           model id (default: qwen/qwen3.8-27b for local)
+#   LMS_BASE_URL   url          LM Studio OpenAI-compatible endpoint (default localhost:1234/v1)
 # ===========================================================================
 
 require "fileutils"
-require "logger"
 require "open3"
-require "net/http"
 
 # Make the example runnable straight from the repo during development, with or
 # without `bundle exec`. (When the gem is installed normally these paths don't
@@ -55,49 +53,24 @@ require "net/http"
   File.expand_path("../../../robot_lab/lib", __dir__) # sibling robot_lab/lib
 ].each { |p| $LOAD_PATH.unshift(p) if Dir.exist?(p) }
 
-require "ruby_llm"
 require "robot_lab"
 require "robot_lab/to"
+require_relative "../common"
 
 # --- configuration ---------------------------------------------------------
 
 LOCAL    = ENV.fetch("RLTO_LOCAL", "true") == "true"
-PROVIDER = ENV.fetch("RLTO_PROVIDER", LOCAL ? "openai" : "anthropic").to_sym
-MODEL    = ENV.fetch("RLTO_MODEL", LOCAL ? "qwen3.6:latest" : "claude-sonnet-4-6")
-OLLAMA   = ENV.fetch("OLLAMA_BASE", "http://localhost:11434/v1")
+PROVIDER = ENV.fetch("RLTO_PROVIDER", LOCAL ? "lms" : "anthropic").to_sym
+MODEL    = ENV.fetch("RLTO_MODEL", LOCAL ? "qwen/qwen3.8-27b" : "claude-sonnet-4-6")
 
-TOTAL_TESTS = 9 # the seeded suite has 9 test methods — the target
-
-# Route RubyLLM's :openai provider at Ollama's OpenAI-compatible endpoint for a
-# local run (non-streaming, since Ollama suppresses tool calls when streaming).
-def configure_local!
-  RubyLLM.configure do |c|
-    c.openai_api_base = OLLAMA
-    c.openai_api_key  = "ollama"
-    c.request_timeout = 600
-  end
-  RubyLLM.logger.level = Logger::ERROR
-  RubyLLM.models.refresh!
-rescue StandardError => e
-  warn "warning: could not refresh Ollama models (#{e.class}: #{e.message})"
-end
+# ruby_llm has no native "lms" adapter. "lms" is this example's friendly label for
+# "a local LM Studio model"; setup (common.rb) resolves it to RubyLLM's :openai
+# adapter pointed at LM Studio, starting the server and loading MODEL as needed.
+# Everything passed to RobotLab uses the resolved provider; PROVIDER itself is
+# kept only for display.
+LLM_PROVIDER = setup(provider: PROVIDER, model: MODEL)
 
-def preflight_local!
-  uri = URI.join(OLLAMA, "models")
-  Net::HTTP.start(uri.host, uri.port, open_timeout: 2, read_timeout: 2) { |h| h.get(uri.request_uri) }
-rescue StandardError
-  abort <<~MSG
-    Cannot reach an Ollama server at #{OLLAMA}.
-    Start it and pull a tool-capable model first:
-
-      ollama serve &
-      ollama pull #{MODEL}
-
-    Or run against a cloud model:
-      RLTO_LOCAL=false RLTO_PROVIDER=anthropic RLTO_MODEL=claude-sonnet-4-6 \\
-        ANTHROPIC_API_KEY=sk-... ruby #{File.basename(__FILE__)}
-  MSG
-end
+TOTAL_TESTS = 9 # the seeded suite has 9 test methods — the target
 
 # --- sandbox repository ----------------------------------------------------
 
@@ -290,15 +263,10 @@ OBJECTIVE = <<~OBJ.strip
   Call submit_result each iteration describing what you improved.
 OBJ
 
-if LOCAL
-  preflight_local!
-  configure_local!
-end
-
 clean_slate!
 sandbox = make_sandbox
 puts "Project dir:     #{sandbox}"
-puts "Provider/model:  #{PROVIDER}/#{MODEL} (#{LOCAL ? 'local Ollama' : 'cloud'})"
+puts "Provider/model:  #{PROVIDER}/#{MODEL} (#{LOCAL ? 'local LM Studio' : 'cloud'})"
 puts "Eval:            measured descent — score = passing tests, target #{TOTAL_TESTS}"
 puts "Locked grader:   score.rb, test/roman_numeral_test.rb"
 puts
@@ -308,7 +276,7 @@ RobotLab.on(FeedbackHook)
 Dir.chdir(sandbox) do
   RobotLab::To.run(
     OBJECTIVE,
-    provider:       PROVIDER,
+    provider:       LLM_PROVIDER,
     model:          MODEL,
     local_guards:   LOCAL,
     stream:         !LOCAL,

data/examples/04_prose/README.md

@@ -2,12 +2,12 @@
 
 Demo 03 scores **code** with a deterministic command (passing tests). Prose has no
 `rake coverage`, so this demo uses the **`prose` eval** — a pairwise LLM judge — and
-puts two *different* models in two roles:
+puts two roles on the same local model by default, each independently swappable:
 
 | Role | Model (default) | Job |
 |------|-----------------|-----|
-| **Doer** | `qwen3.6:latest` | writes and improves `guide.md` |
-| **Verifier** (judge) | `gpt-oss:latest` | compares each draft to the last committed one and rules it **better / worse / same** |
+| **Doer** | `qwen/qwen3.8-27b` | writes and improves `guide.md` |
+| **Verifier** (judge) | `qwen/qwen3.8-27b` | compares each draft to the last committed one and rules it **better / worse / same** |
 
 Only a draft the judge rules **better** is committed, so every commit is a genuine
 improvement. There's no absolute target (LLM scores are too noisy to descend), so
@@ -18,25 +18,26 @@ cannot edit the criteria it's judged against.
 ## Run it
 
 ```bash
-ollama pull qwen3.6:latest      # doer
-ollama pull gpt-oss:latest      # verifier / judge
 bundle exec ruby examples/04_prose/prose_run.rb
 ```
 
-Override the models via env: `RLTO_MODEL` (doer), `RLTO_JUDGE_MODEL` (verifier).
+`common.rb` starts the LM Studio server and loads the doer + judge models for
+you if they aren't already running/loaded. Override the models via env:
+`RLTO_MODEL` (doer), `RLTO_JUDGE_MODEL` (verifier).
 
-## Why gpt-oss works as the judge here (but not as a doer)
+## Why the judge can be the same model as the doer
 
-gpt-oss is a reasoning model that, when *offered tools*, tends to call its own
-built-ins (`container.exec`) instead of the provided ones — which makes it a poor
-**doer**. But the **judge** is given **no tools**; it just reads two versions and
-replies `better`/`worse`/`same`. As a pure text responder it's reliable, which is
-exactly the verifier's job. This is the separation-of-duties payoff: the model that
-*decides* is independent of the model that *acts*.
+The **doer** is given the file-editing tools; the **judge** is given **no tools**
+at all — it just reads two versions and replies `better`/`worse`/`same`. As a pure
+text responder it doesn't need to be a stronger or different model to be reliable,
+which is why both roles default to the same local `qwen/qwen3.8-27b`. This is still the
+separation-of-duties payoff: the model that *decides* is called independently of
+the model that *acts*, so swap in a stronger `RLTO_JUDGE_MODEL` if you want a
+tougher judge without touching the doer.
 
 ## The mechanism
 
-`RobotLab::To.run(..., eval: "prose", eval_judge_model: "gpt-oss:latest")` builds an
+`RobotLab::To.run(..., eval: "prose", eval_judge_model: "qwen/qwen3.8-27b")` builds an
 `Evals::Prose`. Each iteration, after the doer edits `guide.md`, the eval diffs the
 working tree against the parent commit, shows both versions plus the spec to the
 judge model, and maps its verdict onto `Score#improved`. Commit on *better*, roll

data/examples/04_prose/prose_run.rb

@@ -16,9 +16,10 @@
 #             section. The run ends when every outline section has a READY file.
 #   Finally the approved sections are assembled into guide.md.
 #
-# Two models, two roles:
-#   DOER     (default qwen3.6:latest) — writes the outline and the sections
-#   VERIFIER (default gpt-oss:latest) — the judge; grades each artifact absolutely
+# Two models, two roles (the same local model by default, but independently
+# configurable — pass --judge-model / RLTO_JUDGE_MODEL for a stronger judge):
+#   DOER     (default qwen/qwen3.8-27b) — writes the outline and the sections
+#   VERIFIER (default qwen/qwen3.8-27b) — the judge; grades each artifact absolutely
 #
 # The judge writes its feedback to REVIEW.md (git-ignored in the sandbox); the
 # doer is told to read REVIEW.md each iteration. write_guard is disabled for the
@@ -27,18 +28,17 @@
 # ---------------------------------------------------------------------------
 # Run it
 # ---------------------------------------------------------------------------
-#   ollama pull qwen3.6:latest      # doer
-#   ollama pull gpt-oss:latest      # verifier / judge
 #   bundle exec ruby examples/04_prose/prose_run.rb
 #
+# common.rb starts the LM Studio server and loads the doer + judge models for
+# you if they aren't already running/loaded.
+#
 # Env: RLTO_MODEL (doer), RLTO_JUDGE_MODEL (verifier), RLTO_TOPIC, RLTO_LOCAL,
-#      RLTO_PROVIDER, OLLAMA_BASE.
+#      RLTO_PROVIDER, LMS_BASE_URL. (examples/.envrc sets these for you)
 # ===========================================================================
 
 require "fileutils"
-require "logger"
 require "open3"
-require "net/http"
 
 [
   File.expand_path("../../lib", __dir__),
@@ -51,38 +51,27 @@ require "net/http"
 PROMPTS_DIR = File.expand_path("prompts_dir", __dir__)
 ENV["ROBOT_LAB_TEMPLATE_PATH"] = PROMPTS_DIR
 
-require "ruby_llm"
 require "robot_lab"
 require "robot_lab/to"
+require_relative "../common"
 RobotLab.reload_config! if RobotLab.respond_to?(:reload_config!)
 
 # --- configuration ---------------------------------------------------------
 
 LOCAL       = ENV.fetch("RLTO_LOCAL", "true") == "true"
-PROVIDER    = ENV.fetch("RLTO_PROVIDER", LOCAL ? "openai" : "anthropic").to_sym
-DOER_MODEL  = ENV.fetch("RLTO_MODEL", LOCAL ? "qwen3.6:latest" : "claude-sonnet-4-6")
-JUDGE_MODEL = ENV.fetch("RLTO_JUDGE_MODEL", LOCAL ? "gpt-oss:latest" : "claude-sonnet-4-6")
-OLLAMA      = ENV.fetch("OLLAMA_BASE", "http://localhost:11434/v1")
+PROVIDER    = ENV.fetch("RLTO_PROVIDER", LOCAL ? "lms" : "anthropic").to_sym
+DOER_MODEL  = ENV.fetch("RLTO_MODEL", LOCAL ? "qwen/qwen3.8-27b" : "claude-sonnet-4-6")
+JUDGE_MODEL = ENV.fetch("RLTO_JUDGE_MODEL", LOCAL ? "qwen/qwen3.8-27b" : "claude-sonnet-4-6")
 TOPIC       = ENV.fetch("RLTO_TOPIC", "writing good Git commit messages")
 
-def configure_local!
-  RubyLLM.configure do |c|
-    c.openai_api_base = OLLAMA
-    c.openai_api_key  = "ollama"
-    c.request_timeout = 600
-  end
-  RubyLLM.logger.level = Logger::ERROR
-  RubyLLM.models.refresh!
-rescue StandardError => e
-  warn "warning: could not refresh Ollama models (#{e.class}: #{e.message})"
-end
-
-def preflight_local!
-  uri = URI.join(OLLAMA, "models")
-  Net::HTTP.start(uri.host, uri.port, open_timeout: 2, read_timeout: 2) { |h| h.get(uri.request_uri) }
-rescue StandardError
-  abort "Cannot reach Ollama at #{OLLAMA}. Start it and pull #{DOER_MODEL} + #{JUDGE_MODEL}."
-end
+# ruby_llm has no native "lms" adapter. "lms" is this example's friendly label for
+# "a local LM Studio model"; setup (common.rb) resolves it to RubyLLM's :openai
+# adapter pointed at LM Studio, starting the server and loading each model as
+# needed -- once for the doer, again for the judge (a no-op if they're the same
+# model, or if it's already loaded). Everything passed to RobotLab uses the
+# resolved provider; PROVIDER itself is kept only for display.
+LLM_PROVIDER = setup(provider: PROVIDER, model: DOER_MODEL)
+setup(provider: PROVIDER, model: JUDGE_MODEL)
 
 # --- the judge (absolute grader) -------------------------------------------
 
@@ -90,7 +79,7 @@ end
 # prompt is a robot_lab template (prompts_dir/judge.md).
 # @return [Array(Boolean, String)] [ready?, feedback]
 def grade(criteria, text)
-  judge = RobotLab.build(name: "judge", model: JUDGE_MODEL, provider: PROVIDER, template: :judge)
+  judge = RobotLab.build(name: "judge", model: JUDGE_MODEL, provider: LLM_PROVIDER, template: :judge)
   message = RobotLab.render_template(:grade_message, criteria: criteria, artifact: text)
   reply = judge.run(message).last_text_content.to_s
   ready = reply.match?(/\bREADY\b/i) && !reply.match?(/NEEDS_WORK/i)
@@ -255,11 +244,6 @@ end
 
 # --- main ------------------------------------------------------------------
 
-if LOCAL
-  preflight_local!
-  configure_local!
-end
-
 clean_slate!
 sandbox = make_sandbox
 puts "Project dir:     #{sandbox}"
@@ -271,7 +255,7 @@ puts
 RobotLab.on(FeedbackHook)
 
 common = {
-  provider: PROVIDER, model: DOER_MODEL, local_guards: LOCAL, stream: !LOCAL,
+  provider: LLM_PROVIDER, model: DOER_MODEL, local_guards: LOCAL, stream: !LOCAL,
   run_dir: RUN_DIR, write_guard: false, require_improvement: false
 }
 

data/examples/common.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+#
+# ===========================================================================
+# common.rb — shared RubyLLM setup/teardown for the robot_lab-to example demos
+# ===========================================================================
+#
+# Every example under examples/ requires this file (examples/.envrc supplies
+# the RLTO_* / LMS_BASE_URL defaults) and calls `setup` before talking to
+# RubyLLM -- once for a single-model example, or once per model role for an
+# example with more than one (e.g. 04_prose's doer + judge).
+#
+#   actual_provider = setup(provider: PROVIDER, model: MODEL)
+#   RobotLab::To.run(objective, provider: actual_provider, model: MODEL, ...)
+#
+# ruby_llm has no native "lms" adapter -- "lms" is this example suite's own
+# label for "a local LM Studio model". When `provider` is "lms", setup:
+#   1. points RubyLLM's :openai adapter at LMS_BASE_URL
+#   2. starts the LM Studio server if it isn't already running
+#   3. loads `model` into LM Studio if it isn't already loaded
+# and returns :openai -- the RubyLLM-recognized provider to pass to RobotLab.
+# Any other provider (a cloud one) passes straight through untouched; setup
+# does nothing else for it (the example configures its own API key as before).
+#
+# teardown stops the LM Studio server, but ONLY if setup started it here -- a
+# server you already had running (the LM Studio app, another example) is left
+# alone. It runs automatically via an at_exit hook; examples never call it.
+# ===========================================================================
+
+require "json"
+require "logger"
+require "open3"
+require "uri"
+
+require "ruby_llm"
+
+LMS_BASE_URL = ENV.fetch("LMS_BASE_URL", "http://localhost:1234/v1")
+
+@lms_server_started_by_us = false
+
+def setup(provider: ENV.fetch("RLTO_PROVIDER", "lms"), model: ENV.fetch("RLTO_MODEL", "qwen/qwen3.8-27b"))
+  provider = provider.to_sym
+  return provider unless provider == :lms
+
+  configure_lms!
+  ensure_lms_server_running!
+  ensure_lms_model_loaded!(model)
+  :openai
+end
+
+def teardown
+  return unless @lms_server_started_by_us
+
+  puts "Stopping the LM Studio server (started for this run)…"
+  Open3.capture2e("lms", "server", "stop")
+end
+
+at_exit { teardown }
+
+# --- internals ---------------------------------------------------------------
+
+# Route RubyLLM's :openai provider at LM Studio's OpenAI-compatible endpoint and
+# refresh the registry so tool attachment works.
+def configure_lms!
+  RubyLLM.configure do |c|
+    c.openai_api_base = LMS_BASE_URL
+    c.openai_api_key  = "lm-studio" # ignored by LM Studio, but RubyLLM wants a value
+    c.request_timeout = 600
+  end
+  RubyLLM.logger.level = Logger::ERROR
+  RubyLLM.models.refresh!
+rescue StandardError => e
+  warn "warning: could not refresh LM Studio models (#{e.class}: #{e.message})"
+end
+
+def lms_server_running?
+  out, status = Open3.capture2("lms", "server", "status", "--json")
+  status.success? && JSON.parse(out)["running"] == true
+rescue StandardError
+  false
+end
+
+def ensure_lms_server_running!
+  return if lms_server_running?
+
+  puts "Starting the LM Studio server…"
+  port = URI.parse(LMS_BASE_URL).port.to_s
+  out, status = Open3.capture2e("lms", "server", "start", "--port", port)
+  abort "Could not start the LM Studio server:\n#{out}" unless status.success? && lms_server_running?
+
+  @lms_server_started_by_us = true
+rescue Errno::ENOENT
+  abort "The `lms` CLI was not found. Install LM Studio (https://lmstudio.ai) and " \
+        "run `lms bootstrap` to put it on your PATH."
+end
+
+def lms_model_loaded?(model)
+  out, status = Open3.capture2("lms", "ps", "--json")
+  return false unless status.success?
+
+  JSON.parse(out).any? { |m| m["modelKey"] == model || m["identifier"] == model }
+rescue StandardError
+  false
+end
+
+def ensure_lms_model_loaded!(model)
+  return if lms_model_loaded?(model)
+
+  puts "Loading #{model} into LM Studio (first run only)…"
+  out, status = Open3.capture2e("lms", "load", model, "-y")
+  abort "Could not load #{model} in LM Studio:\n#{out}" unless status.success?
+rescue Errno::ENOENT
+  abort "The `lms` CLI was not found. Install LM Studio (https://lmstudio.ai) and " \
+        "run `lms bootstrap` to put it on your PATH."
+end

data/lib/robot_lab/to/cli.rb

@@ -46,6 +46,17 @@ module RobotLab
          "Seconds between polls while waiting on a decision (default: 30)", :decision_wait_poll]
       ].freeze
 
+      # Boolean flags with a fixed value when passed (no argument). Flags
+      # needing bespoke behavior (protect-path, require-improvement, help)
+      # stay in #add_flag_options.
+      BOOLEAN_FLAGS = [
+        ["--no-decisions", "Disable the request_decision tool for this run", :decisions_enabled, false],
+        ["--local-guards", "Add built-in file tools + small-model guardrails (for local models)", :local_guards, true],
+        ["--no-stream", "Disable response streaming (required for local Ollama tool calls)", :stream, false],
+        ["--debug", "Enable verbose JSONL logging to stderr", :debug, true],
+        ["--version", "Print version and exit", :version, true]
+      ].freeze
+
       def self.run(argv = ARGV)
         new.run(argv)
       end
@@ -53,32 +64,33 @@ module RobotLab
       def run(argv)
         return run_decisions(argv[1..] || []) if argv.first == "decisions"
 
-        opts   = {}
-        parser = build_parser(opts)
-        args   = parser.parse!(argv.dup)
+        opts, parser, args = parse_options(argv)
 
-        if opts[:version]
-          puts "robot-to #{VERSION}"
-          return
-        end
-
-        if opts[:resume]
-          return RobotLab::To.resume(opts[:resume], **opts.except(:version, :resume))
-        end
+        return puts("robot-to #{VERSION}") if opts[:version]
+        return RobotLab::To.resume(opts[:resume], **opts.except(:version, :resume)) if opts[:resume]
 
         objective = args.first || read_stdin_objective
-        if objective.nil? || objective.strip.empty?
-          # $stderr.puts, not warn: warn is silenced when $VERBOSE is nil.
-          $stderr.puts "Error: objective required (pass as argument or via stdin)"
-          $stderr.puts parser
-          exit 1
-        end
+        abort_missing_objective!(parser) if objective.nil? || objective.strip.empty?
 
         RobotLab::To.run(objective.strip, **opts.except(:version, :resume))
       end
 
       private
 
+      def parse_options(argv)
+        opts   = {}
+        parser = build_parser(opts)
+        args   = parser.parse!(argv.dup)
+        [opts, parser, args]
+      end
+
+      def abort_missing_objective!(parser)
+        # $stderr.puts, not warn: warn is silenced when $VERBOSE is nil.
+        $stderr.puts "Error: objective required (pass as argument or via stdin)"
+        $stderr.puts parser
+        exit 1
+      end
+
       # `robot-to decisions [run_id]` — list pending decisions and their file
       # paths so a human knows what needs resolving before resuming.
       def run_decisions(args)
@@ -96,17 +108,19 @@ module RobotLab
       def print_decisions(run_id, manager)
         pending  = manager.pending
         resolved = manager.resolved_open
-        puts "Run #{run_id}"
-        puts ""
+
         if pending.empty? && resolved.empty?
-          puts "No open decisions."
+          puts "Run #{run_id}\n\nNo open decisions."
           return
         end
+
+        puts "Run #{run_id}\n\n"
         list_group("Pending (awaiting your answer)", pending)
         list_group("Resolved (not yet consumed)", resolved)
-        puts ""
-        puts "Resolve a pending decision by editing its file: set `status: resolved`"
-        puts "and fill `resolution:`, then run `robot-to --resume #{run_id}`."
+        puts <<~MSG
+          Resolve a pending decision by editing its file: set `status: resolved`
+          and fill `resolution:`, then run `robot-to --resume #{run_id}`.
+        MSG
       end
 
       def list_group(title, decisions)
@@ -126,6 +140,7 @@ module RobotLab
            .sort.map { |p| File.basename(p) }.last
       end
 
+      # :reek:FeatureEnvy -- configuring the OptionParser instance being built.
       def build_parser(opts)
         OptionParser.new do |p|
           p.banner = "Usage: robot-to [objective] [options]\n       " \
@@ -136,30 +151,42 @@ module RobotLab
           p.separator ""
           p.separator "Options:"
 
-          VALUE_OPTIONS.each do |flag, type, desc, key|
-            p.on(flag, type, desc) { |v| opts[key] = v }
-          end
-
+          add_value_options(p, opts)
           add_flag_options(p, opts)
         end
       end
 
+      # :reek:NestedIterators -- one .on registration per option, each with its
+      # own value-assignment callback; that's the OptionParser API shape.
+      def add_value_options(parser, opts)
+        VALUE_OPTIONS.each do |flag, type, desc, key|
+          parser.on(flag, type, desc) { |v| opts[key] = v }
+        end
+      end
+
+      # :reek:FeatureEnvy -- registering flags on the OptionParser being built.
       # Boolean and terminal flags (each has bespoke behavior).
       def add_flag_options(parser, opts)
+        add_require_improvement_option(parser, opts)
+        add_protect_path_option(parser, opts)
+        BOOLEAN_FLAGS.each { |flag, desc, key, value| parser.on(flag, desc) { opts[key] = value } }
+        add_help_option(parser)
+      end
+
+      def add_require_improvement_option(parser, opts)
         parser.on("--[no-]require-improvement",
                   "Roll back gate-passing iterations that don't improve (default: on)") do |v|
           opts[:require_improvement] = v
         end
+      end
+
+      def add_protect_path_option(parser, opts)
         parser.on("--protect-path GLOB", "Lock a grader file from robot edits (repeatable)") do |v|
           (opts[:protect_paths] ||= []) << v
         end
-        parser.on("--no-decisions", "Disable the request_decision tool for this run") { opts[:decisions_enabled] = false }
-        parser.on("--local-guards", "Add built-in file tools + small-model guardrails (for local models)") do
-          opts[:local_guards] = true
-        end
-        parser.on("--no-stream", "Disable response streaming (required for local Ollama tool calls)") { opts[:stream] = false }
-        parser.on("--debug", "Enable verbose JSONL logging to stderr") { opts[:debug] = true }
-        parser.on("--version", "Print version and exit") { opts[:version] = true }
+      end
+
+      def add_help_option(parser)
         parser.on("-h", "--help", "Show this help") do
           puts parser
           exit

data/lib/robot_lab/to/commit_manager.rb

@@ -8,6 +8,9 @@ module RobotLab
     #
     # All subprocess calls use explicit argv arrays (no shell interpolation).
     # GIT_TERMINAL_PROMPT=0 prevents credential prompts from hanging the loop.
+    # :reek:RepeatedConditional -- each `status.success?` belongs to a distinct
+    # Open3.capture3 call with its own failure handling; there is no shared
+    # condition to extract.
     class CommitManager
       GIT_ENV = { "GIT_TERMINAL_PROMPT" => "0" }.freeze
 
@@ -72,6 +75,7 @@ module RobotLab
         parse_diff_stat(out)
       end
 
+      # :reek:FeatureEnvy -- inherent to building/reading/appending a Pathname.
       def add_to_local_exclude(entry)
         exclude = Pathname.new(@work_dir).join(".git", "info", "exclude")
         exclude.parent.mkpath

data/lib/robot_lab/to/config.rb

@@ -11,6 +11,15 @@ module RobotLab
     #   2. User config file (~/.config/robot_lab/to.yml)
     #   3. Environment variables (ROBOT_LAB_TO_*)
     #   4. Constructor keyword arguments (CLI overrides)
+    # :reek:TooManyInstanceVariables -- a flat CLI-override bag for ~24
+    # independent settings; each ivar is genuinely one distinct setting.
+    # :reek:InstanceVariableAssumption -- the defaults.yml-backed ivars
+    # (provider, model, max_consecutive_failures, max_submit_nudges,
+    # max_verify_repairs, verify_timeout, run_dir, commit_format, local_guards,
+    # stream, debug, decisions_enabled, decision_mode, decision_wait_poll,
+    # decision_timeout) ARE assigned -- by `super()` (MywayConfig::Base /
+    # Anyway::Config), before any of this class's own code runs. Do NOT
+    # pre-nil them here: that overwrites the real loaded values with nil.
     class Config < MywayConfig::Base
       config_name :robot_lab_to
       env_prefix :robot_lab_to
@@ -34,6 +43,9 @@ module RobotLab
 
       def initialize(**overrides)
         super()
+        # CLI-only, no YAML default (nil means "no limit / not set") -- unlike
+        # the defaults.yml-backed ivars above, super() never touches these.
+        @max_iterations = @max_tokens = @stop_when = @verify_command = nil
         @eval = @eval_measure = @eval_target = nil
         @require_improvement = @stop_on_plateau = nil
         @eval_judge_model = @eval_spec = @eval_floor = nil

data/lib/robot_lab/to/decision_manager.rb

@@ -40,6 +40,11 @@ module RobotLab
       end
 
       # Persist a decision the robot raised. Returns the parsed Decision.
+      # :reek:BooleanParameter -- blocking is stored data (front matter), not a
+      # behavior switch.
+      # :reek:ControlParameter -- the ternary only coerces blocking to true/false.
+      # :reek:LongParameterList { max_params: 6 } -- one field per front-matter
+      # attribute; a hash would just move the same six names elsewhere.
       def record(question:, situation: "", options: [], recommendation: "", blocking: false, iteration: 0)
         id   = generate_id
         path = @dir.join("#{id}.md")
@@ -57,6 +62,7 @@ module RobotLab
       def pending       = all.select(&:pending?)
       # resolved but not yet closed
       def resolved_open = all.select(&:resolved?)
+      # :reek:FeatureEnvy -- filtering by a Decision's own predicates.
       def blocking_pending = all.select { |d| d.pending? && d.blocking? }
       def blocking_pending? = blocking_pending.any?
 
@@ -66,6 +72,7 @@ module RobotLab
       # 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.
+      # :reek:FeatureEnvy -- reading/rewriting the decision's own file.
       def close(decision)
         raw = File.read(decision.path)
         AtomicFile.write(decision.path, flip_status(raw, "closed"))
@@ -82,8 +89,10 @@ module RobotLab
         raw.sub(/^status:.*$/, "status: #{status}")
       end
 
+      # :reek:LongParameterList { max_params: 7 } -- one field per front-matter
+      # attribute, mirroring #record.
       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"
+        options_md = options.empty? ? "(none provided)\n" : options.each_with_index.map { |opt, i| "#{i + 1}. #{opt}" }.join("\n") + "\n"
         # Build the front matter with YAML.dump so question/recommendation are
         # escaped correctly (they can contain colons, quotes, etc.).
         front = {
@@ -116,6 +125,7 @@ module RobotLab
 
       # Split a file into (front_matter_hash, body). Returns a Decision or nil
       # when the file is unreadable.
+      # :reek:FeatureEnvy -- building a Decision from its own front matter hash.
       def parse(path)
         text = File.read(path)
         fm, body = split_front_matter(text)
@@ -138,6 +148,7 @@ module RobotLab
         nil
       end
 
+      # :reek:FeatureEnvy -- slicing the raw file text into front matter/body.
       def split_front_matter(text)
         if text.start_with?("---\n") && (close_idx = text.index("\n---", 4))
           raw_fm = text[4...close_idx]