robot_lab-to 0.2.6

data/docs/getting-started/installation.md

@@ -0,0 +1,78 @@
+# Installation
+
+## Requirements
+
+| Requirement | Notes |
+|-------------|-------|
+| Ruby **>= 3.2** | Set in the gemspec `required_ruby_version`. |
+| Git | A repository with at least one commit. The loop creates a branch and commits there. |
+| `robot_lab` | The core framework `robot_lab-to` builds on. |
+| An LLM provider | A cloud API key, **or** a local [Ollama](https://ollama.com) server (see [Local Models](../local-models/index.md)). |
+
+## Install the gem
+
+```bash
+gem install robot_lab-to
+```
+
+Or add it to a `Gemfile`:
+
+```ruby
+gem "robot_lab-to"
+```
+
+```bash
+bundle install
+```
+
+This installs the `robot-to` executable on your `PATH`.
+
+## Provider credentials
+
+`robot_lab-to` passes your configured provider and model straight through to
+RobotLab / RubyLLM. Provide credentials the usual way for your provider:
+
+=== "Anthropic"
+
+    ```bash
+    export ANTHROPIC_API_KEY="sk-ant-..."
+    robot-to "..." --provider anthropic --model claude-sonnet-4-6
+    ```
+
+=== "OpenAI"
+
+    ```bash
+    export OPENAI_API_KEY="sk-..."
+    robot-to "..." --provider openai --model gpt-5.5
+    ```
+
+=== "Local (Ollama)"
+
+    No API key required. See [Ollama Setup](../local-models/ollama.md) for the
+    full configuration — local models need `--provider openai` against Ollama's
+    OpenAI-compatible endpoint plus `--no-stream` and `--local-guards`.
+
+The default provider/model is `openai` / `gpt-5.5` (see
+[Settings Reference](../configuration/settings.md)).
+
+## Verify the installation
+
+```bash
+robot-to --version
+```
+
+## Prepare your project
+
+The loop branches from `HEAD` and commits each successful iteration, so the
+working repository must have at least one commit:
+
+```bash
+git init
+git add -A
+git commit -m "initial"          # or: git commit --allow-empty -m "initial"
+```
+
+Run state is written under `.robot_lab_to/` and automatically added to
+`.git/info/exclude`, so it never pollutes your working tree or commits.
+
+You're ready — continue to the [Quick Start](quick-start.md).

data/docs/getting-started/quick-start.md

@@ -0,0 +1,105 @@
+# Quick Start
+
+This walkthrough takes you from a clean repository to a finished overnight run.
+
+## 1. Start in a git repository with a commit
+
+```bash
+cd my-project
+git status            # must be a git repo
+git log --oneline     # must have at least one commit
+```
+
+If there are no commits yet:
+
+```bash
+git commit --allow-empty -m "initial"
+```
+
+## 2. Run a bounded objective
+
+Give `robot-to` a clear, single-sentence objective and a stop condition. Keep
+the first run small and bounded so you can watch it work:
+
+```bash
+robot-to "Add a CHANGELOG.md and document the public API in the README" \
+  --max-iterations 5 \
+  --provider anthropic \
+  --model claude-sonnet-4-6
+```
+
+What happens:
+
+- A branch `robot-to/<slugified-objective>-<timestamp>` is created.
+- For up to 5 iterations, a fresh robot makes one focused change and reports a
+  result.
+- Each successful iteration becomes one commit on the branch.
+- Failures are rolled back (`git reset --hard`) and recorded in the notes.
+
+## 3. Add an independent verification gate
+
+The robot's self-reported success only counts if a command **you** choose
+passes. This is the single most important flag for unattended runs:
+
+```bash
+robot-to "Fix the failing tests in spec/parser" \
+  --verify-command "bundle exec rake test" \
+  --max-iterations 15 \
+  --max-consecutive-failures 4
+```
+
+If `--verify-command` exits non-zero (or times out), the iteration is rolled
+back even though the robot claimed success. See [Verification Gate](../concepts/verification.md).
+
+## 4. Let it stop itself
+
+For a true overnight run, combine a hard ceiling with a natural-language stop
+condition:
+
+```bash
+robot-to "Migrate the codebase from Minitest to RSpec" \
+  --verify-command "bundle exec rake" \
+  --max-iterations 50 \
+  --max-tokens 2000000 \
+  --stop-when "all test files are RSpec and the suite passes"
+```
+
+The robot evaluates `--stop-when` after each successful iteration and sets
+`should_fully_stop` when it judges the condition met. See
+[Stop Conditions](../concepts/stop-conditions.md).
+
+## 5. Review in the morning
+
+```bash
+git log --oneline robot-to/migrate-the-codebase-from-...   # the iteration history
+git diff main..HEAD                                         # the full change
+cat .robot_lab_to/runs/*/notes.md                           # the reasoning log
+```
+
+Each commit is one iteration. Squash, cherry-pick, or reset as you like — it's
+an ordinary branch.
+
+## Programmatic use
+
+You can also drive a run from Ruby instead of the CLI:
+
+```ruby
+require "robot_lab"
+require "robot_lab/to"
+
+RobotLab::To.run(
+  "Add a CHANGELOG.md and document the public API",
+  provider: :anthropic,
+  model: "claude-sonnet-4-6",
+  max_iterations: 5,
+  verify_command: "bundle exec rake test"
+)
+```
+
+`RobotLab::To.run(objective, **opts)` accepts the same options as the CLI flags
+(as keyword arguments). See the [Settings Reference](../configuration/settings.md).
+
+---
+
+Next: understand exactly what one run produces in
+[Anatomy of a Run](anatomy-of-a-run.md).

data/docs/index.md

@@ -0,0 +1,96 @@
+<p align="center">
+  <img src="assets/images/robot_lab-to.jpg" alt="robot_lab-to" width="320"><br />
+  "Robot, takeover!"
+</p>
+
+# robot_lab-to
+
+**Autonomous overnight agent loop for [RobotLab](https://github.com/MadBomber/robot_lab) — run a robot while you sleep.**
+
+`robot_lab-to` ("takeover") runs a RobotLab `Robot` in an autonomous loop toward a
+stated objective, committing **one focused change per iteration**. Each iteration
+spins up a fresh robot, lets it work, and asks it to report a result. Good
+iterations are committed; failures are rolled back. A running log (`notes.md`)
+carries memory across iterations so the robot learns from what came before.
+
+Start it before bed; review the branch in the morning.
+
+```bash
+robot-to "Increase test coverage of the parser to 90%" \
+  --max-iterations 20 \
+  --verify-command "bundle exec rake test"
+```
+
+---
+
+## How it works
+
+Every iteration is an independent, sandboxed attempt at *one* improvement. The
+orchestrator owns the git history and the stop conditions; the robot owns the
+work.
+
+![The robot-to iteration loop](assets/iteration-loop.svg)
+
+1. **Build a fresh robot** with a per-iteration system prompt that includes the
+   objective and the accumulated notes.
+2. **The robot works** and calls `submit_iteration_result` to report success or
+   failure.
+3. **The orchestrator decides** — an independent `--verify-command` (if set) must
+   pass, then the change is committed. Otherwise the working tree is reset.
+4. **Notes are updated** with what happened, becoming context for the next round.
+5. **Stop conditions are checked** — iterations, tokens, consecutive failures, or
+   a natural-language `--stop-when` — and the loop continues or ends.
+
+See [The Iteration Loop](concepts/iteration-loop.md) for the full lifecycle.
+
+---
+
+## Why use it
+
+- **Bounded, reviewable history.** Each iteration is a single commit on a
+  dedicated branch. Bad attempts never reach the branch — they are reset before
+  the next try.
+- **Cross-iteration memory.** `notes.md` records summaries, changes, and learnings
+  so the robot doesn't repeat itself. See [Cross-Iteration Memory](concepts/notes.md).
+- **Independent verification.** The robot can't self-certify success — a real
+  command you choose is the deciding authority. See [Verification Gate](concepts/verification.md).
+- **Scored, descending iterations.** An **eval** replaces the robot's self-report
+  with an orchestrator-owned measurable judgement — a deterministic `--measure`/
+  `--target` for code, or a pairwise LLM judge for prose — so the branch only
+  ever moves forward. See [Evals](concepts/evals.md).
+- **It stops on its own.** Hard limits plus a natural-language stop condition mean
+  you can leave it unattended. See [Stop Conditions](concepts/stop-conditions.md).
+- **It asks before overstepping.** For irreversible or ambiguous choices the robot
+  writes a **decision file** — situation, options, and its recommendation — that
+  you resolve out-of-band instead of letting it guess. Run `robot-to decisions`
+  to see what's waiting on you.
+- **Resumable & cron-friendly.** Run state is persisted to `run.json`, so
+  `robot-to --resume <run_id>` continues a stopped run and an external scheduler
+  can drive it one commit per tick.
+- **Runs on local models.** With `--local-guards` it ships built-in file tools and
+  small-model guardrails, so it can drive a local Ollama model offline. See
+  [Local Models](local-models/index.md).
+
+---
+
+## Quick links
+
+<div class="grid cards" markdown>
+
+- :material-rocket-launch: **[Installation](getting-started/installation.md)** — install the gem and the `robot-to` CLI.
+- :material-play: **[Quick Start](getting-started/quick-start.md)** — your first overnight run in five minutes.
+- :material-cog: **[Configuration](configuration/index.md)** — every setting, the config cascade, and the CLI.
+- :material-laptop: **[Local Models](local-models/index.md)** — drive a local Ollama model with guardrails.
+- :material-sitemap: **[Architecture](reference/architecture.md)** — how the pieces fit together.
+
+</div>
+
+---
+
+## Requirements
+
+- Ruby **>= 3.2**
+- A git repository with at least one commit (the loop branches and commits there)
+- The [`robot_lab`](https://github.com/MadBomber/robot_lab) gem and an LLM provider
+  (a cloud key such as `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`, **or** a local
+  [Ollama](https://ollama.com) server)

data/docs/local-models/guardrails.md

@@ -0,0 +1,117 @@
+# Guardrails
+
+The guardrails are `RobotLab::Hook` policies that intercept the robot's tool calls
+to catch the mistakes small local models reliably make. They are enabled with
+`--local-guards` and are no-ops you'd never notice with a frontier model — they
+exist for the 8–35B local case.
+
+They are adapted from the open-source [`little-coder`](https://github.com/itayinbarr/little-coder)
+harness, whose core finding is that a guard-rich scaffold raised the same small
+model's coding-benchmark score by **2.4×**. The harness, not the model, does the
+heavy lifting.
+
+## The four guards
+
+### write-guard
+
+**Problem:** small models love to "fix" a file by rewriting the whole thing with
+`write`, destroying everything they didn't think to include.
+
+**Policy:** refuse `write` to a file that already exists and tell the model to use
+`edit` instead. It also normalizes a root-bare path like `/foo.rb` (a common
+small-model mistake) to the working directory.
+
+Implemented as `around_tool_call` (to block) + `before_tool_call` (to normalize
+the path).
+
+**Opting out:** `write-guard` is the one guard in the set that can get in the way
+of *legitimate* work — a robot iteratively rewriting a whole prose draft each
+pass wants plain `write`, not a forced `edit`. Set `write_guard: false` (Ruby-only,
+default `true`; no CLI flag) to drop it from the installed set while keeping
+`read-before-edit`, `checkpoint`, and `quality-monitor`:
+
+```ruby
+RobotLab::To.run(objective, local_guards: true, write_guard: false)
+```
+
+Internally this calls `Guards.install(robot, run:, except: [Guards::WriteGuard])`.
+
+### read-before-edit
+
+**Problem:** models fire `edit` with an `old_text` they never actually saw —
+guessing the file's contents — which either fails the exact-match (a wasted turn)
+or, worse, matches the wrong span.
+
+**Policy:** refuse `edit` on any file that wasn't `read` this run, directing the
+model to read it first. A successful `read`, `edit`, or `write` marks the file as
+known. The read-set is per-run state.
+
+### checkpoint
+
+**Problem:** a single botched edit can spoil otherwise-good work within an
+iteration.
+
+**Policy:** before the first `write`/`edit` of a file, snapshot its current bytes
+(first-write-wins) to `runs/<run_id>/checkpoints/`. Files that didn't exist get an
+`.absent` sentinel. This is finer-grained than the orchestrator's
+`git reset --hard` rollback — it survives *within* an iteration. Best-effort:
+checkpointing never raises into the tool path.
+
+### quality-monitor
+
+**Problem:** a small model can get stuck repeating the exact same tool call, which
+on an unattended overnight run silently burns the entire token budget.
+
+**Policy:** detect the same `name` + arguments called on consecutive turns. After
+a couple of consecutive repeats it raises a `QualityError`, which the orchestrator
+handles like any iteration error — roll back, record the reason in `notes.md`, and
+move on. This is the load-bearing guard for long unattended runs.
+
+!!! info "Empty-response handling is intentionally left out"
+    An earlier version also flagged "empty" responses, but RobotLab fires the
+    generation hook once per *run* (not per turn), so that check false-tripped on
+    legitimate tool-using turns. Empty / no-progress is handled instead by the
+    orchestrator's existing nudge → "did not submit" path, which recovers
+    gracefully rather than hard-erroring.
+
+!!! info "A fifth guard, `GraderLock`, is not part of this set"
+    `Guards::GraderLock` (`guards/grader_lock.rb`) lives alongside these four but
+    is **not** gated by `--local-guards` — it locks an [eval's](../concepts/evals.md)
+    grading criteria (a spec, a floor script, `--protect-path` globs) from robot
+    edits, and is installed whenever such paths exist, regardless of model size.
+    A frontier model can reward-hack its own grading criteria just as easily as a
+    small model can mangle a file. See
+    [Evals: Guarding the grader](../concepts/evals.md#guarding-the-grader-graderlock).
+
+## How they're registered
+
+`Guards.install(robot, run:)` registers all four on the per-iteration robot. The
+orchestrator calls it from `build_robot` only when `local_guards` is enabled:
+
+```ruby
+robot = RobotLab.build(..., local_tools: iteration_tools(submit_tool))
+RobotLab::To::Guards.install(robot, run: @run) if @config.local_guards?
+```
+
+## Per-run state
+
+RobotLab builds a fresh hook context per tool call with no shared metadata across
+calls, so cross-call guard state (the read-set, the checkpoint-set, the loop
+tracker) can't live in the hook context. Because `robot_lab-to` runs each
+iteration in its own thread, the guards keep that state in a thread-local
+`RunStore` — the same idiom `robot_lab-audit` uses for run IDs. It's reset at the
+start of each run.
+
+## Relationship to the git rollback
+
+The guards and the orchestrator's git rollback are complementary, at two
+granularities:
+
+| Layer | Granularity | Recovers |
+|-------|-------------|----------|
+| `checkpoint` guard | a single file, within an iteration | a botched individual edit |
+| `git reset --hard` | the whole working tree, per iteration | a failed iteration |
+
+---
+
+Next: [Architecture](../reference/architecture.md).

data/docs/local-models/index.md

@@ -0,0 +1,88 @@
+# Local Models
+
+`robot_lab-to` can drive a **local** model — running entirely offline against an
+[Ollama](https://ollama.com) server — instead of a cloud API. This is the
+"local assistant" mode: no API keys, no per-token cost, no data leaving your
+machine.
+
+Local models are smaller and less forgiving than frontier models, so this mode
+adds two things:
+
+- **Built-in file tools** (`read`, `write`, `edit`, `bash`) — a small, predictable
+  tool surface the model can use to do real work.
+- **Guardrails** — `RobotLab::Hook` policies that catch the mistakes small models
+  reliably make, before they corrupt the working tree or burn the token budget.
+
+Both are enabled together with `--local-guards`.
+
+## The short version
+
+```bash
+# 1. Serve a tool-capable model
+ollama pull gpt-oss:20b
+
+# 2. Run robot-to against it
+robot-to "Add a greet(name) method in greeter.rb" \
+  --provider openai \
+  --model gpt-oss:20b \
+  --local-guards \
+  --no-stream \
+  --max-iterations 5
+```
+
+The full setup — including the RubyLLM configuration that points `:openai` at
+Ollama — is on the [Ollama Setup](ollama.md) page.
+
+## Why these flags
+
+Driving a local model end-to-end requires three non-obvious settings. Each exists
+because of a concrete limitation discovered in testing:
+
+| Flag / setting | Why |
+|----------------|-----|
+| `--provider openai` (+ Ollama base URL) | RubyLLM's native `:ollama` provider doesn't reliably get these models to emit tool calls. Routing through the `:openai` provider against Ollama's OpenAI-compatible `/v1` endpoint does. |
+| `--no-stream` | Ollama suppresses tool calls when the response is streamed. With streaming off, tool calls come through. |
+| `--local-guards` | Attaches the file tools the model needs to do work, plus guardrails that make those tools safe for a small model. |
+
+See [Ollama Setup → Streaming and tool calls](ollama.md#streaming-and-tool-calls)
+for the details.
+
+## The design philosophy
+
+This mode is inspired by the research behind
+[`little-coder`](https://github.com/itayinbarr/little-coder): the same small model
+scored **2.4× higher** on a coding benchmark through a guard-rich harness than it
+did unscaffolded. With small local models, **the harness is the product** — a
+frontier model forgives a sloppy tool loop; a 9–35B local model does not.
+
+The guardrails are policies that intercept the model's tool calls:
+
+- **`write-guard`** — refuses `write` on a file that already exists (small models
+  rewrite whole files and destroy content); redirects to `edit`.
+- **`read-before-edit`** — refuses `edit` on a file the model hasn't read this run,
+  so `oldText` reflects the real contents.
+- **`checkpoint`** — snapshots a file before the first Write/Edit, for fine-grained
+  recovery within an iteration.
+- **`quality-monitor`** — detects a model spinning on the same tool call and stops
+  it before it burns the token budget.
+
+See [Guardrails](guardrails.md) for how each works.
+
+## Choosing a model
+
+The model **must support tool calling**. In testing on an M2 Max:
+
+| Model | Size | Tool calls? | Notes |
+|-------|------|-------------|-------|
+| `gpt-oss:20b` | 20B | ✅ reliable | Called tools *and* `submit_iteration_result`; completed full runs cleanly. **Recommended.** |
+| `qwen3` | 8B | ✅ tools work | Created files via the write tool, but didn't reliably call `submit_iteration_result` (the final-report step). |
+| `phi4-mini` | 3.8B | ❌ | Explains instead of calling tools. |
+
+Prefer a larger, instruction-following model for the autonomous loop — it has to
+both use tools *and* remember to submit its result every iteration.
+
+---
+
+- [Ollama Setup](ollama.md) — install, serve, and configure.
+- [Built-in Tools](tools.md) — what `read`/`write`/`edit`/`bash` do.
+- [Guardrails](guardrails.md) — the small-model safety policies.

data/docs/local-models/ollama.md

@@ -0,0 +1,122 @@
+# Ollama Setup
+
+This page covers running `robot_lab-to` against a local
+[Ollama](https://ollama.com) server end-to-end.
+
+## 1. Install and start Ollama
+
+```bash
+# macOS / Linux
+curl -fsSL https://ollama.com/install.sh | sh
+
+# Ollama runs a server on http://localhost:11434
+```
+
+## 2. Pull a tool-capable model
+
+The model **must** support tool calling. `gpt-oss:20b` is the recommended choice
+(see [model selection](index.md#choosing-a-model)):
+
+```bash
+ollama pull gpt-oss:20b
+```
+
+You can confirm a model advertises tool support:
+
+```bash
+curl -s http://localhost:11434/api/tags | jq '.models[] | {name, caps: .capabilities}'
+```
+
+## 3. Point RubyLLM at Ollama
+
+`robot_lab-to` reaches the model through RobotLab / RubyLLM. The robust path is
+the **`:openai` provider** aimed at Ollama's OpenAI-compatible `/v1` endpoint.
+Configure RubyLLM once, before launching the run:
+
+```ruby
+require "ruby_llm"
+require "robot_lab"
+require "robot_lab/to"
+
+RubyLLM.configure do |c|
+  c.openai_api_base = "http://localhost:11434/v1"
+  c.openai_api_key  = "ollama"   # ignored by Ollama, but RubyLLM requires a value
+  c.request_timeout = 600
+end
+
+RobotLab::To.run(
+  "Add a greet(name) method in greeter.rb",
+  provider: :openai,
+  model: "gpt-oss:20b",
+  local_guards: true,
+  stream: false,
+  max_iterations: 5
+)
+```
+
+!!! note "Why a wrapper script"
+    The Ollama base-URL configuration lives in RubyLLM's global config, so it's
+    set in a small Ruby launcher (as above) rather than via a `robot-to` CLI flag.
+    The CLI flags `--provider openai --model gpt-oss:20b --local-guards --no-stream`
+    cover the rest; only the base URL needs the wrapper. You can also set it in
+    your application's RubyLLM initializer.
+
+## 4. Run
+
+From the launcher above, or — once the base URL is configured in your environment
+— from the CLI:
+
+```bash
+robot-to "Add a greet(name) method in greeter.rb" \
+  --provider openai \
+  --model gpt-oss:20b \
+  --local-guards \
+  --no-stream \
+  --max-iterations 5
+```
+
+## Streaming and tool calls
+
+**Local Ollama models must run non-streaming** (`--no-stream` / `stream: false`).
+
+Ollama's OpenAI-compatible endpoint suppresses tool calls when the response is
+streamed — the model "thinks" but never emits a tool call, so the robot can't do
+any work. With streaming disabled, tool calls come through normally.
+
+The trade-off: streaming is what enables per-chunk token accounting and
+mid-iteration token-budget enforcement. With `--no-stream`, tokens are accounted
+from each iteration's *result* instead, and `--max-tokens` is enforced at
+iteration boundaries rather than mid-stream. For overnight local runs this is
+almost always fine.
+
+## Why not the native `:ollama` provider?
+
+RubyLLM ships a native `:ollama` provider, but in testing it did **not** reliably
+get tool-capable models (e.g. qwen3) to emit tool calls — the same model tool-calls
+correctly through the `:openai` provider against Ollama's `/v1` endpoint. Until
+that changes, prefer `provider: :openai` + `openai_api_base` for `robot_lab-to`.
+
+## Registering models (if needed)
+
+RubyLLM validates models against its registry. `robot_lab-to` sets
+`assume_model_exists` when a provider is given, which is enough for a bare chat —
+but attaching tools triggers a capability lookup that can raise
+`ModelNotFoundError` for an unregistered model. If you hit that, refresh the
+registry so your local models are known:
+
+```ruby
+RubyLLM.models.refresh!   # discovers locally-served Ollama models
+```
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Model thinks but never calls a tool | Streaming is on | Add `--no-stream`. |
+| `RobotLab::ModelNotFoundError` when tools attach | Model not in RubyLLM registry | `RubyLLM.models.refresh!`. |
+| Every iteration "did not submit" | Model too small to follow the final-report step | Use a larger model (e.g. `gpt-oss:20b`). |
+| No tool calls at all, model only explains | Model lacks tool support | Pick a model whose `capabilities` include `tools`. |
+
+---
+
+Next: [Built-in Tools](tools.md).