robot_lab-to 0.2.6

data/Rakefile

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb', 'test/**/test_*.rb'].exclude('**/*_helper.rb')
+  t.verbose = true
+  t.ruby_opts << '-rtest_helper'
+end
+
+task default: :test
+
+desc 'Run tests with verbose output'
+task :test_verbose do
+  ENV['TESTOPTS'] = '--verbose'
+  Rake::Task[:test].invoke
+end
+
+desc 'Run a single test file'
+task :test_file, [:file] do |_t, args|
+  ruby "test/#{args[:file]}"
+end
+
+desc 'Check code complexity with Flog (warn >=20, fail >=50)'
+task :flog_check do
+  require 'flog'
+
+  method_warn = 20.0
+  method_fail = 50.0
+
+  flogger = Flog.new(all: true)
+  flogger.flog(*Dir.glob('lib/**/*.rb'))
+
+  warnings = []
+  failures = []
+
+  flogger.each_by_score do |method, score|
+    next if method.end_with?('#none')
+
+    if score > method_fail
+      failures << "#{format('%.1f', score)}: #{method}"
+    elsif score > method_warn
+      warnings << "#{format('%.1f', score)}: #{method}"
+    end
+  end
+
+  unless warnings.empty?
+    puts "\nFlog warnings (#{method_warn}–#{method_fail}) — target for future refactoring:"
+    warnings.each { |v| puts "  #{v}" }
+  end
+
+  if failures.empty?
+    puts "\nFlog: no methods exceed the failure threshold (>=#{method_fail})"
+  else
+    puts "\nFlog failures (>=#{method_fail}) — must be refactored:"
+    failures.each { |v| puts "  #{v}" }
+    abort "\nFlog quality gate failed: #{failures.size} method(s) exceed #{method_fail}"
+  end
+end
+
+desc 'Check for structural code duplication with Flay (mass >= 50)'
+task :flay_check do
+  require 'flay'
+
+  mass_threshold = 50
+
+  flay = Flay.new({ mass: mass_threshold, diff: false, verbose: false, summary: false, timeout: 60 })
+  flay.process(*Dir.glob('lib/**/*.rb'))
+  flay.analyze
+
+  if flay.hashes.empty?
+    puts "\nFlay: no structural duplication detected (mass >= #{mass_threshold})"
+  else
+    puts "\nFlay found structural duplication (mass >= #{mass_threshold}):"
+    flay.report
+    abort "\nFlay quality gate failed: #{flay.hashes.length} pattern(s) detected"
+  end
+end
+
+desc 'Run all quality checks: tests (with coverage), RuboCop, Flog, and Flay'
+task :quality do
+  gates = [
+    ['Tests + Coverage', 'bundle exec rake test'],
+    ['RuboCop',          'bundle exec rubocop'],
+    ['Flog Complexity',  'bundle exec rake flog_check'],
+    ['Flay Duplication', 'bundle exec rake flay_check']
+  ]
+
+  results = gates.map do |label, command|
+    puts "\n#{'=' * 60}"
+    puts "Quality Gate: #{label}"
+    puts '=' * 60
+    [label, system(command) ? :pass : :fail]
+  end
+
+  green = ->(s) { "\e[32m#{s}\e[0m" }
+  red   = ->(s) { "\e[31m#{s}\e[0m" }
+  width = results.map { |label, _| label.length }.max
+
+  puts "\n#{'=' * 60}"
+  puts 'Quality Gate Summary'
+  puts '=' * 60
+  results.each do |label, status|
+    badge = status == :pass ? green.call('PASS') : red.call('FAIL')
+    puts "  [#{badge}] #{label.ljust(width)}"
+  end
+  puts '-' * 60
+
+  passed = results.count { |_, s| s == :pass }
+  failed = results.count { |_, s| s == :fail }
+  tally  = "#{passed} passed, #{failed} failed"
+  puts "  #{failed.zero? ? green.call(tally) : red.call(tally)}"
+  puts '=' * 60
+
+  abort "\n#{red.call('Quality gate failed.')}" unless failed.zero?
+  puts "\n#{green.call('All quality gates passed.')}"
+end
+
+namespace :docs do
+  desc 'Build MkDocs documentation'
+  task :build do
+    sh 'mkdocs build'
+  end
+
+  desc 'Serve MkDocs documentation locally on http://localhost:8000'
+  task :serve do
+    sh 'mkdocs serve'
+  end
+end

data/bin/robot-to

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Activate bundler if running from the gem's own dev environment.
+if File.exist?(File.expand_path("../Gemfile", __dir__))
+  require "bundler/setup"
+end
+
+require "robot_lab"
+require "robot_lab/to"
+
+Signal.trap("INT") { exit 130 }
+
+RobotLab::To::CLI.run(ARGV)

data/docs/about/changelog.md

@@ -0,0 +1,82 @@
+# Changelog
+
+All notable changes to `robot_lab-to` are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/), and the project follows
+[Conventional Commits](https://www.conventionalcommits.org/) (see `COMMITS.md`).
+
+## Unreleased
+
+### Added
+
+- **Evals: orchestrator-owned scoring.** An `Eval` scores each iteration's
+  working tree and returns a `Score(gate_ok, improved, met_target, value, detail,
+  output)` — the deciding authority for commit/rollback and, for measurable
+  objectives, for when the run is done — instead of the robot's self-reported
+  `should_fully_stop`. See [Evals](../concepts/evals.md).
+    - `Evals::Code` — measured/deterministic: the existing `--verify-command`
+      floor plus an optional `--measure CMD` (a command printing a number,
+      higher is better) and `--target FLOAT`. Fully backward compatible: with no
+      `--measure`, behaves exactly like the original verify-only gate.
+    - `Evals::Prose` — judged/pairwise: an LLM judge (`--judge-model`, defaults
+      to `--model`) compares the working tree against the last committed
+      version and rules it `better`/`worse`/`same`; an optional `--floor CMD`
+      gates mechanizable checks before the judge is called.
+    - `Evals::Null` — the default when nothing is configured; preserves the
+      original "commit any reported success" behavior exactly.
+    - `--eval NAME`, `--stop-on-plateau N`, `--[no-]require-improvement`, and
+      Ruby-API extension points (`RobotLab::To.register_eval`, an instance
+      responding to `#score`, or a bare proc, all passable as `eval:`).
+    - `require_improvement` (default **true**) rolls back a gate-passing
+      iteration that doesn't beat the parent's score, keeping the branch
+      strictly descending.
+    - `--stop-on-plateau N` — a new stop condition: abort after `N` iterations
+      with no committed improvement. The primary terminator for `Evals::Prose`,
+      which never sets a measurable target.
+    - `PromptBuilder` **Score Feedback** section — for scored runs, tells each
+      iteration's robot the best score committed so far, the target, and
+      whether recent attempts plateaued, so each attempt is a hypothesis
+      against the target instead of a blind guess.
+- **`GraderLock` guard — grader lockdown.** Refuses `write`/`edit`/`bash` against
+  an eval's own grading criteria (`Evals::Prose#protected_paths`'s `--spec`, plus
+  any `--protect-path GLOB`), so the robot cannot "win" by rewriting the
+  criteria it is scored against. Unlike the small-model guardrails, it is always
+  installed when protected paths exist — independent of `--local-guards`. See
+  [Evals: Guarding the grader](../concepts/evals.md#guarding-the-grader-graderlock).
+- **`write_guard` config (Ruby-only, default `true`).** Lets a `--local-guards`
+  run opt out of `Guards::WriteGuard` (`write_guard: false`) so the robot can
+  freely overwrite a file it is iteratively rewriting whole, e.g. a prose draft.
+  See [Guardrails](../local-models/guardrails.md#write-guard).
+- **Local-model support.** Drive a local Ollama model end-to-end with
+  `--local-guards` and `--no-stream`. See [Local Models](../local-models/index.md).
+- **Built-in workspace tools** (`read`, `write`, `edit`, `bash`) attached when
+  `--local-guards` is set. See [Built-in Tools](../local-models/tools.md).
+- **Small-model guardrails** — `write-guard`, `read-before-edit`, `checkpoint`,
+  and `quality-monitor` hooks. See [Guardrails](../local-models/guardrails.md).
+- **`stream` setting** (`--no-stream`) — disable response streaming, required for
+  Ollama tool calls; tokens are then accounted from each iteration's result.
+- This documentation site.
+
+### Fixed
+
+- Tools were passed to `RobotLab.build` via `tools:` (a name allowlist filter)
+  instead of `local_tools:` (the instance list), so the `submit_iteration_result`
+  tool was never attached to the robot. Now passed via `local_tools:`, with a
+  regression test asserting the built robot exposes the tool.
+
+## 0.1.0
+
+Initial release.
+
+### Added
+
+- Autonomous overnight loop (`Orchestrator`): fresh robot per iteration, commit on
+  success, `git reset --hard` on failure.
+- `SubmitResult` tool and `IterationResult` value object.
+- Cross-iteration memory via `notes.md` (`NotesManager`).
+- Stop conditions: `--max-iterations`, `--max-tokens`,
+  `--max-consecutive-failures`, and natural-language `--stop-when`.
+- Independent verification gate (`--verify-command`, `Verifier`).
+- Interruptible exponential `Backoff` for transient-error retries.
+- JSONL event log (`JsonlLogger`) and post-run `ExitSummary`.
+- `robot-to` CLI and `RobotLab::To.run` programmatic entry point.
+- `Config` cascade (`myway_config`): defaults → user file → env → CLI.

data/docs/assets/architecture.svg

@@ -0,0 +1,110 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 640" font-family="Helvetica, Arial, sans-serif" role="img" aria-label="robot-to architecture">
+  <defs>
+    <marker id="a" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto" markerUnits="strokeWidth">
+      <path d="M0,0 L7,3 L0,6 Z" fill="#94a3b8"/>
+    </marker>
+  </defs>
+  <style>
+    .t  { fill:#ffffff; font-size:13px; font-weight:600; }
+    .s  { fill:#e2e8f0; font-size:10px; }
+    .hd { fill:#cbd5e1; font-size:12px; font-weight:700; letter-spacing:.5px; }
+    .lg { fill:#cbd5e1; font-size:11px; }
+  </style>
+
+  <!-- CLI / entry -->
+  <rect x="360" y="16" width="180" height="46" rx="10" fill="#0ea5e9"/>
+  <text x="450" y="38" text-anchor="middle" class="t">robot-to CLI / To.run</text>
+  <text x="450" y="54" text-anchor="middle" class="s">CLI · Config (myway_config)</text>
+  <line x1="450" y1="62" x2="450" y2="86" stroke="#94a3b8" stroke-width="2" marker-end="url(#a)"/>
+
+  <!-- Orchestrator -->
+  <rect x="330" y="88" width="240" height="52" rx="10" fill="#475569"/>
+  <text x="450" y="110" text-anchor="middle" class="t">Orchestrator</text>
+  <text x="450" y="127" text-anchor="middle" class="s">main loop · setup → iterate → finalize</text>
+
+  <!-- collaborators row -->
+  <text x="60" y="172" class="hd">PER-RUN COLLABORATORS</text>
+  <g>
+    <rect x="40" y="184" width="150" height="46" rx="9" fill="#6366f1"/>
+    <text x="115" y="205" text-anchor="middle" class="t">PromptBuilder</text>
+    <text x="115" y="221" text-anchor="middle" class="s">per-iteration system prompt</text>
+
+    <rect x="200" y="184" width="150" height="46" rx="9" fill="#f59e0b"/>
+    <text x="275" y="205" text-anchor="middle" class="t">CommitManager</text>
+    <text x="275" y="221" text-anchor="middle" class="s">git via Open3 (no shell)</text>
+
+    <rect x="360" y="184" width="150" height="46" rx="9" fill="#a855f7"/>
+    <text x="435" y="205" text-anchor="middle" class="t">NotesManager</text>
+    <text x="435" y="221" text-anchor="middle" class="s">notes.md memory</text>
+
+    <rect x="520" y="184" width="150" height="46" rx="9" fill="#64748b"/>
+    <text x="595" y="205" text-anchor="middle" class="t">StopConditions</text>
+    <text x="595" y="221" text-anchor="middle" class="s">iters · tokens · failures</text>
+
+    <rect x="680" y="184" width="160" height="46" rx="9" fill="#64748b"/>
+    <text x="760" y="205" text-anchor="middle" class="t">Verifier</text>
+    <text x="760" y="221" text-anchor="middle" class="s">independent test gate</text>
+  </g>
+  <g>
+    <rect x="120" y="244" width="150" height="46" rx="9" fill="#64748b"/>
+    <text x="195" y="265" text-anchor="middle" class="t">Backoff</text>
+    <text x="195" y="281" text-anchor="middle" class="s">interruptible retry</text>
+
+    <rect x="280" y="244" width="150" height="46" rx="9" fill="#64748b"/>
+    <text x="355" y="265" text-anchor="middle" class="t">JsonlLogger</text>
+    <text x="355" y="281" text-anchor="middle" class="s">run.log events</text>
+
+    <rect x="440" y="244" width="150" height="46" rx="9" fill="#64748b"/>
+    <text x="515" y="265" text-anchor="middle" class="t">ExitSummary</text>
+    <text x="515" y="281" text-anchor="middle" class="s">post-run report</text>
+
+    <rect x="600" y="244" width="150" height="46" rx="9" fill="#a855f7"/>
+    <text x="675" y="265" text-anchor="middle" class="t">Run</text>
+    <text x="675" y="281" text-anchor="middle" class="s">run state object</text>
+  </g>
+  <line x1="450" y1="140" x2="450" y2="180" stroke="#94a3b8" stroke-width="2" marker-end="url(#a)"/>
+
+  <!-- robot -->
+  <text x="60" y="330" class="hd">PER-ITERATION ROBOT (RobotLab)</text>
+  <rect x="330" y="342" width="240" height="50" rx="10" fill="#3b82f6"/>
+  <text x="450" y="364" text-anchor="middle" class="t">RobotLab::Robot</text>
+  <text x="450" y="380" text-anchor="middle" class="s">RubyLLM agent · persistent chat</text>
+  <line x1="450" y1="290" x2="450" y2="340" stroke="#94a3b8" stroke-width="2" marker-end="url(#a)"/>
+
+  <!-- tools -->
+  <rect x="120" y="420" width="150" height="46" rx="9" fill="#16a34a"/>
+  <text x="195" y="441" text-anchor="middle" class="t">SubmitResult</text>
+  <text x="195" y="457" text-anchor="middle" class="s">reports iteration result</text>
+
+  <rect x="290" y="420" width="320" height="46" rx="9" fill="#16a34a"/>
+  <text x="450" y="441" text-anchor="middle" class="t">File tools — read · write · edit · bash</text>
+  <text x="450" y="457" text-anchor="middle" class="s">attached only when local_guards is on</text>
+  <line x1="420" y1="392" x2="240" y2="418" stroke="#94a3b8" stroke-width="2" marker-end="url(#a)"/>
+  <line x1="460" y1="392" x2="460" y2="418" stroke="#94a3b8" stroke-width="2" marker-end="url(#a)"/>
+
+  <!-- guards -->
+  <text x="630" y="412" class="hd">GUARDRAILS (Hooks)</text>
+  <rect x="630" y="420" width="250" height="92" rx="10" fill="#dc2626"/>
+  <text x="755" y="440" text-anchor="middle" class="t">RobotLab::Hook guards</text>
+  <text x="755" y="460" text-anchor="middle" class="s">write_guard · read_before_edit</text>
+  <text x="755" y="476" text-anchor="middle" class="s">checkpoint · quality_monitor</text>
+  <text x="755" y="496" text-anchor="middle" class="s">intercept tool calls for small models</text>
+  <line x1="610" y1="450" x2="628" y2="455" stroke="#94a3b8" stroke-width="2" marker-end="url(#a)"/>
+
+  <!-- run state output -->
+  <rect x="290" y="540" width="320" height="60" rx="10" fill="#334155"/>
+  <text x="450" y="562" text-anchor="middle" class="t">.robot_lab_to/runs/&lt;run_id&gt;/</text>
+  <text x="450" y="580" text-anchor="middle" class="s">notes.md · run.log (JSONL) · checkpoints/</text>
+  <text x="450" y="595" text-anchor="middle" class="s">+ git branch robot-to/&lt;slug&gt;</text>
+  <line x1="450" y1="466" x2="450" y2="538" stroke="#94a3b8" stroke-width="2" marker-end="url(#a)"/>
+
+  <!-- legend -->
+  <g transform="translate(40,548)">
+    <rect x="0" y="0" width="14" height="11" rx="3" fill="#475569"/><text x="20" y="9" class="lg">orchestrator / control</text>
+    <rect x="0" y="18" width="14" height="11" rx="3" fill="#3b82f6"/><text x="20" y="27" class="lg">robot / LLM</text>
+    <rect x="0" y="36" width="14" height="11" rx="3" fill="#16a34a"/><text x="20" y="45" class="lg">tools</text>
+    <rect x="140" y="0" width="14" height="11" rx="3" fill="#dc2626"/><text x="160" y="9" class="lg">guardrails</text>
+    <rect x="140" y="18" width="14" height="11" rx="3" fill="#a855f7"/><text x="160" y="27" class="lg">memory / state</text>
+    <rect x="140" y="36" width="14" height="11" rx="3" fill="#f59e0b"/><text x="160" y="45" class="lg">git</text>
+  </g>
+</svg>

data/docs/assets/iteration-loop.svg

@@ -0,0 +1,97 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 880 720" font-family="Helvetica, Arial, sans-serif" role="img" aria-label="The robot-to iteration loop">
+  <!-- transparent background: no background rect -->
+  <defs>
+    <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto" markerUnits="strokeWidth">
+      <path d="M0,0 L8,3 L0,6 Z" fill="#94a3b8"/>
+    </marker>
+    <marker id="arrowGreen" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto" markerUnits="strokeWidth">
+      <path d="M0,0 L8,3 L0,6 Z" fill="#22c55e"/>
+    </marker>
+    <marker id="arrowRed" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto" markerUnits="strokeWidth">
+      <path d="M0,0 L8,3 L0,6 Z" fill="#ef4444"/>
+    </marker>
+  </defs>
+
+  <style>
+    .label { fill: #ffffff; font-size: 14px; font-weight: 600; }
+    .sub   { fill: #e2e8f0; font-size: 11px; }
+    .edge  { fill: #cbd5e1; font-size: 12px; font-weight: 600; }
+    .legend{ fill: #cbd5e1; font-size: 12px; }
+  </style>
+
+  <!-- setup -->
+  <rect x="300" y="20" width="280" height="54" rx="10" fill="#475569"/>
+  <text x="440" y="42" text-anchor="middle" class="label">setup_run</text>
+  <text x="440" y="60" text-anchor="middle" class="sub">create branch · init notes.md · base commit</text>
+  <line x1="440" y1="74" x2="440" y2="100" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrow)"/>
+
+  <!-- build robot -->
+  <rect x="300" y="102" width="280" height="54" rx="10" fill="#3b82f6"/>
+  <text x="440" y="124" text-anchor="middle" class="label">build fresh Robot</text>
+  <text x="440" y="142" text-anchor="middle" class="sub">system prompt + notes + tools (per iteration)</text>
+  <line x1="440" y1="156" x2="440" y2="182" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrow)"/>
+
+  <!-- run -->
+  <rect x="300" y="184" width="280" height="54" rx="10" fill="#3b82f6"/>
+  <text x="440" y="206" text-anchor="middle" class="label">robot.run — do work via tools</text>
+  <text x="440" y="224" text-anchor="middle" class="sub">read/write/edit/bash · then submit_result</text>
+  <line x1="440" y1="238" x2="440" y2="264" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrow)"/>
+
+  <!-- submitted? -->
+  <polygon points="440,266 560,310 440,354 320,310" fill="#64748b"/>
+  <text x="440" y="306" text-anchor="middle" class="label">submitted?</text>
+  <text x="440" y="324" text-anchor="middle" class="sub">called submit_result</text>
+  <!-- no -> nudge -->
+  <line x1="560" y1="310" x2="650" y2="310" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrow)"/>
+  <text x="600" y="300" text-anchor="middle" class="edge">no</text>
+  <rect x="650" y="284" width="190" height="52" rx="10" fill="#475569"/>
+  <text x="745" y="306" text-anchor="middle" class="label">nudge robot</text>
+  <text x="745" y="323" text-anchor="middle" class="sub">re-ask up to max_submit_nudges</text>
+  <path d="M745,284 C745,240 620,250 560,290" fill="none" stroke="#94a3b8" stroke-width="2" stroke-dasharray="4 3" marker-end="url(#arrow)"/>
+
+  <!-- success? -->
+  <line x1="440" y1="354" x2="440" y2="384" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrow)"/>
+  <text x="455" y="372" class="edge">yes</text>
+  <polygon points="440,386 560,430 440,474 320,430" fill="#64748b"/>
+  <text x="440" y="426" text-anchor="middle" class="label">success?</text>
+  <text x="440" y="444" text-anchor="middle" class="sub">+ verify_command</text>
+
+  <!-- success path: verify ok -> commit -->
+  <line x1="440" y1="474" x2="440" y2="504" stroke="#22c55e" stroke-width="2" marker-end="url(#arrowGreen)"/>
+  <text x="455" y="492" class="edge">pass</text>
+  <rect x="300" y="506" width="280" height="54" rx="10" fill="#22c55e"/>
+  <text x="440" y="528" text-anchor="middle" class="label">git add -A &amp; commit</text>
+  <text x="440" y="546" text-anchor="middle" class="sub">one focused change committed</text>
+
+  <!-- failure path: reset -->
+  <line x1="320" y1="430" x2="150" y2="430" stroke="#ef4444" stroke-width="2" marker-end="url(#arrowRed)"/>
+  <text x="235" y="420" text-anchor="middle" class="edge">fail / no submit</text>
+  <rect x="20" y="404" width="130" height="52" rx="10" fill="#ef4444"/>
+  <text x="85" y="426" text-anchor="middle" class="label">git reset</text>
+  <text x="85" y="443" text-anchor="middle" class="sub">--hard + clean</text>
+
+  <!-- notes update (purple) collects both paths -->
+  <line x1="440" y1="560" x2="440" y2="588" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrow)"/>
+  <path d="M85,456 C85,600 250,600 298,600" fill="none" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrow)"/>
+  <rect x="300" y="590" width="280" height="50" rx="10" fill="#a855f7"/>
+  <text x="440" y="612" text-anchor="middle" class="label">append to notes.md</text>
+  <text x="440" y="629" text-anchor="middle" class="sub">cross-iteration memory</text>
+
+  <!-- stop conditions -->
+  <line x1="440" y1="640" x2="440" y2="664" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrow)"/>
+  <rect x="300" y="666" width="280" height="44" rx="10" fill="#475569"/>
+  <text x="440" y="693" text-anchor="middle" class="label">stop conditions met? — else loop ↻</text>
+
+  <!-- loop back arrow -->
+  <path d="M300,688 C120,688 120,129 298,129" fill="none" stroke="#94a3b8" stroke-width="2" stroke-dasharray="6 4" marker-end="url(#arrow)"/>
+  <text x="95" y="410" text-anchor="middle" class="edge" transform="rotate(-90 95 410)">next iteration</text>
+
+  <!-- legend -->
+  <g transform="translate(620,560)">
+    <rect x="0" y="0" width="16" height="12" rx="3" fill="#3b82f6"/><text x="22" y="10" class="legend">robot / LLM</text>
+    <rect x="0" y="22" width="16" height="12" rx="3" fill="#22c55e"/><text x="22" y="32" class="legend">commit (success)</text>
+    <rect x="0" y="44" width="16" height="12" rx="3" fill="#ef4444"/><text x="22" y="54" class="legend">rollback (failure)</text>
+    <rect x="0" y="66" width="16" height="12" rx="3" fill="#a855f7"/><text x="22" y="76" class="legend">notes / memory</text>
+    <rect x="0" y="88" width="16" height="12" rx="3" fill="#475569"/><text x="22" y="98" class="legend">orchestrator control</text>
+  </g>
+</svg>