robot_lab 0.2.1 → 0.2.7

data/README.md

@@ -1,7 +1,7 @@
 # RobotLab
 
-> [!INFO]
-> See the [CHANGELOG](CHANGELOG.md) for the latest changes.  The [examples directory has a good cross section  of demo apps](examples/README.md) that show-off the various capabilities of the RobotLab library.
+> [!NOTE]
+> See the [CHANGELOG](CHANGELOG.md) for the latest changes.  The [examples directory has a good cross section of demo apps](examples/README.md) that show-off the various capabilities of the RobotLab library.
 
 <br>
 <table>
@@ -21,14 +21,16 @@
 - <strong>Human-in-the-Loop</strong> - AskUser tool for interactive prompting<br>
 - <strong>Content Streaming</strong> - Stored callbacks, per-call blocks, or both<br>
 - <strong>MCP Integration</strong> - Connect to external tool servers with timeouts and retry<br>
-- <strong>Local LLM Providers</strong> - Ollama, GPUStack, LM Studio via provider passthrough<br>
+- <strong>Local LLM Providers</strong> - Ollama and GPUStack via provider passthrough<br>
 - <strong>Shared Memory</strong> - Reactive key-value store with subscriptions<br>
 - <strong>Message Bus</strong> - Bidirectional robot communication via TypedBus<br>
 - <strong>Dynamic Spawning</strong> - Robots create new robots at runtime<br>
+- <strong>Hook System</strong> - Lifecycle hooks across every execution boundary for instrumentation, caching, and extensions<br>
 - <strong>Layered Configuration</strong> - Cascading YAML, env vars, and RunConfig<br>
 - <strong>Rails Integration</strong> - Generators, background jobs, Turbo Stream broadcasting (via <a href="https://github.com/MadBomber/robot_lab-rails">robot_lab-rails</a>)<br>
 - <strong>Token &amp; Cost Tracking</strong> - Per-run and cumulative token counts on every robot<br>
 - <strong>Tool Loop Circuit Breaker</strong> - <code>max_tool_rounds:</code> guards against runaway tool call loops<br>
+- <strong>Doom Loop Detection</strong> - always-on detection of repeated or cyclic tool call patterns, tunable via <code>doom_loop_threshold:</code><br>
 - <strong>Learning Accumulation</strong> - <code>robot.learn()</code> builds up cross-run observations with deduplication<br>
 - <strong>Context Window Compression</strong> - <code>robot.compress_history()</code> prunes irrelevant old turns via TF cosine scoring<br>
 - <strong>Convergence Detection</strong> - <code>RobotLab::Convergence</code> detects when independent agents agree, enabling reconciler fast-path<br>
@@ -37,7 +39,7 @@
 </tr>
 </table>
 
-<p>RobotLab enables sophisticated AI applications using multiple specialized robots (LLM agents) that work together to accomplish complex tasks. Each robot has its own instructions, skills, tools, and capabilities.  Review the [full documentation website](https://madbomber.github.io/robot_lab) snd explore the [many examples](examples/README.md) available as working demo applications.</p>
+<p>RobotLab enables sophisticated AI applications using multiple specialized robots (LLM agents) that work together to accomplish complex tasks. Each robot has its own instructions, skills, tools, and capabilities.  Review the [full documentation website](https://madbomber.github.io/robot_lab) and explore the [many examples](examples/README.md) available as working demo applications.</p>
 
 ## Installation
 
@@ -80,7 +82,11 @@ puts result.last_text_content
 
 ### Local LLM Providers
 
-For local LLM providers (Ollama, GPUStack, LM Studio, etc.), use the `provider:` parameter:
+For local LLM providers, use the `provider:` parameter. RubyLLM's provider list is the authority on valid values — `:ollama` and `:gpustack` are the local ones (alongside `:anthropic`, `:azure`, `:bedrock`, `:deepseek`, `:gemini`, `:mistral`, `:openai`, `:openrouter`, `:perplexity`, `:vertexai`, and `:xai`). The provider's API base must be configured first, or building the robot raises `RubyLLM::ConfigurationError`:
+
+```bash
+export ROBOT_LAB_RUBY_LLM__OLLAMA_API_BASE=http://localhost:11434/v1
+```
 
 ```ruby
 robot = RobotLab.build(
@@ -91,13 +97,15 @@ robot = RobotLab.build(
 )
 ```
 
+Specifying `provider:` also sets `assume_model_exists`, so the model name is not validated against a known-model list.
+
 ### Configuration
 
 RobotLab uses [MywayConfig](https://github.com/MadBomber/myway_config) for layered configuration. Configuration is loaded automatically from multiple sources in priority order:
 
 1. Bundled defaults (`lib/robot_lab/config/defaults.yml`)
 2. Environment-specific overrides (development, test, production)
-3. XDG user config (`~/.config/robot_lab/config.yml`)
+3. XDG user config (`~/.config/robot_lab/robot_lab.yml` — note the filename repeats the app name)
 4. Project config (`./config/robot_lab.yml`)
 5. Environment variables (`ROBOT_LAB_*` prefix)
 
@@ -112,7 +120,6 @@ export ROBOT_LAB_RUBY_LLM__MODEL=claude-sonnet-4
 # Access configuration values
 RobotLab.config.ruby_llm.model            #=> "claude-sonnet-4"
 RobotLab.config.ruby_llm.request_timeout  #=> 120
-RobotLab.config.streaming_enabled         #=> true
 ```
 
 Or create a project config file at `./config/robot_lab.yml`:
@@ -191,9 +198,10 @@ tools:
   - CodeSearchTool
 mcp:
   - name: github
-    transport: stdio
-    command: npx
-    args: ["-y", "@modelcontextprotocol/server-github"]
+    transport:
+      type: stdio
+      command: npx
+      args: ["-y", "@modelcontextprotocol/server-github"]
 model: claude-sonnet-4
 ---
 You are a GitHub assistant. Use available tools to help with repository tasks.
@@ -204,7 +212,10 @@ You are a GitHub assistant. Use available tools to help with repository tasks.
 robot = RobotLab.build(template: :github_assistant)
 ```
 
-Front matter supports: `description`, `robot_name`, `tools`, `mcp`, `skills`, `parameters`, and LLM config keys (`model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop`). Constructor-provided values always take precedence over front matter.
+Front matter supports: `description`, `robot_name`, `tools`, `mcp`, `skills`, `parameters`, and LLM config keys. Constructor-provided values always take precedence over front matter.
+
+> [!IMPORTANT]
+> Of the LLM config keys, only **`model`** and **`temperature`** currently take effect from front matter. `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, and `stop` are parsed but not applied — set those as constructor kwargs (or via `config:`), where they do work.
 
 ### Composable Skills
 
@@ -236,7 +247,7 @@ Skills are expanded depth-first and can reference other skills (with automatic c
 
 ### Combining Templates with System Prompts
 
-The `system_prompt` parameter can also be used alongside a template. When both are provided, the template renders first and the `system_prompt` is appended. This is particularly useful during development and testing when you want to add temporary instructions or context to an existing template:
+The `system_prompt` parameter can also be used alongside a template. When both are provided, the template renders first and the `system_prompt` is appended, producing a single combined system message. The appended text also survives template re-rendering, so it persists across `run()` calls that supply runtime context. This is particularly useful during development and testing when you want to add temporary instructions or context to an existing template:
 
 ```ruby
 robot = RobotLab.build(
@@ -249,7 +260,7 @@ robot = RobotLab.build(
 
 ### Shared Configuration with RunConfig
 
-`RunConfig` lets you define operational defaults that flow through the hierarchy: Network -> Robot -> Template -> Task -> Runtime. Use it to share LLM settings across multiple robots or an entire network.
+`RunConfig` lets you define operational defaults. For a single robot they cascade from least- to most-specific: template front matter -> `config:` -> constructor kwargs. Front matter is the *base*, not an override — constructor kwargs always win.
 
 ```ruby
 # Create a shared config
@@ -266,7 +277,7 @@ robot = RobotLab.build(
   config: shared
 )
 
-# Apply to an entire network (all robots inherit these defaults)
+# Apply at the network level (see the note below on what actually propagates)
 network = RobotLab.create_network(name: "pipeline", config: shared) do
   task :analyzer, analyzer_robot, depends_on: :none
   task :writer, writer_robot, depends_on: [:analyzer]
@@ -281,6 +292,11 @@ robot = RobotLab.build(
 )
 ```
 
+> [!IMPORTANT]
+> A network-level `config:` propagates only `mcp` and `tools` down to its robots, and only when the robot opts in with `mcp: :inherit` / `tools: :inherit` — `:none` at any level resolves to an empty list. LLM fields (`model`, `temperature`, `max_tokens`, …) and callbacks (`on_content`) are read from each robot's own config at construction time, so they are **not** inherited from the network. To share LLM settings, pass the same `RunConfig` to each robot via `config:`.
+>
+> `max_concurrent_robots` is the one field the network itself consumes.
+
 RunConfig supports keyword construction, block DSL, and merge semantics:
 
 ```ruby
@@ -300,7 +316,7 @@ effective.model        #=> "claude-sonnet-4"
 
 ### Chaining Configuration
 
-Robots support method chaining to adjust configuration after creation:
+Robots support method chaining to adjust configuration after creation. The `with_*` methods are delegated dynamically from the underlying `RubyLLM::Chat`, so the available set is whatever that class defines — currently `with_context`, `with_headers`, `with_instructions`, `with_model`, `with_params`, `with_schema`, `with_temperature`, `with_thinking`, `with_tool`, and `with_tools`. Each returns the robot, so calls chain.
 
 ```ruby
 robot = RobotLab.build(name: "writer", system_prompt: "You are a creative writer.")
@@ -308,10 +324,18 @@ robot = RobotLab.build(name: "writer", system_prompt: "You are a creative writer
 result = robot
   .with_temperature(0.9)
   .with_model("claude-sonnet-4")
-  .with_max_tokens(2000)
   .run("Write a haiku about Ruby programming")
 ```
 
+There is no `with_max_tokens`. Set token limits in the constructor, or pass them through `with_params`:
+
+```ruby
+robot = RobotLab.build(name: "writer", system_prompt: "...", max_tokens: 2000)
+
+# or, after creation
+robot.with_params(max_tokens: 2000)
+```
+
 ## Graceful Tool Error Handling
 
 `RobotLab::Tool` automatically catches exceptions in `execute` and returns a plain-text error to the LLM instead of crashing the run. The LLM can then reason about the error and try an alternative approach.
@@ -367,9 +391,22 @@ robot = RobotLab.build(
   local_tools: [Magic8Ball]
 )
 
-result = robot.run("Should I start learning Rust?")
+# NOTE the `tools: :inherit` — see the warning below
+result = robot.run("Should I start learning Rust?", tools: :inherit)
 ```
 
+> [!WARNING]
+> `run()` defaults to `tools: :none` and `mcp: :none`, and `:none` means **send zero tools this turn**. Attaching tools with `local_tools:` (or servers with `mcp:`) is therefore not enough on its own — a plain `robot.run("...")` sends the LLM no tools at all and connects no MCP servers.
+>
+> Pass `tools: :inherit` / `mcp: :inherit` on each run to use what the robot has attached:
+>
+> ```ruby
+> robot.run("...", tools: :inherit)              # send attached tools
+> robot.run("...", mcp: :inherit, tools: :inherit)  # connect MCP + send its tools
+> ```
+>
+> `:inherit` means "no filter, use everything attached"; an explicit array acts as a name allowlist. Note that `tools: :inherit` at *build* time behaves differently — it resolves against the parent level, so keep `:inherit` on the `run()` call.
+
 ## Orchestrating Multiple Robots
 
 Networks use [SimpleFlow](https://github.com/MadBomber/simple_flow) pipelines with optional task activation for intelligent routing:
@@ -422,24 +459,29 @@ puts result.value.last_text_content
 
 ## Memory
 
-Both robots and networks have inherent memory that persists across runs:
+Two independent mechanisms carry state across runs, and it is worth keeping them straight:
+
+- **Chat history** — each robot owns a persistent `RubyLLM::Chat`, so conversational context carries forward automatically with no work on your part.
+- **`RobotLab::Memory`** — an explicit key-value store you read and write yourself, shared across robots when they run inside a network.
 
 ```ruby
-# Standalone robot with inherent memory
 robot = RobotLab.build(name: "assistant", system_prompt: "You are helpful.")
 
 robot.run("My name is Alice")
-robot.run("What's my name?")  # Memory persists automatically
+robot.run("What's my name?")  # answered from the persistent chat history
 
-# Access robot's memory
+# Access robot's memory (the explicit key-value store)
 robot.memory[:user_id] = 123
 robot.memory.data[:category] = "billing"
 
 # Runtime memory injection
 robot.run("Help me", memory: { session_id: "abc123", tier: "premium" })
 
-# Reset memory when needed
+# Reset the key-value store (does NOT clear chat history)
 robot.reset_memory
+
+# Clear chat history instead, keeping the system prompt
+robot.clear_messages
 ```
 
 Networks pass context through SimpleFlow::Result:
@@ -466,6 +508,8 @@ billing_result = result.context[:billing]
 puts result.value.last_text_content
 ```
 
+Results are keyed in `result.context` by the **robot's** `name`, not by the task name given to `task`. Keep the two identical unless you have a reason not to.
+
 ## MCP Integration
 
 Connect to external tool servers via Model Context Protocol:
@@ -489,17 +533,18 @@ robot = RobotLab.build(
   mcp: [filesystem_server]
 )
 
-# Optionally connect eagerly (default is lazy on first run)
+# Connect. Do this explicitly — run() defaults to mcp: :none, so a plain
+# run() never connects the servers configured above.
 robot.connect_mcp!
 
 # Check connection status
 puts "Failed: #{robot.failed_mcp_server_names}" if robot.failed_mcp_server_names.any?
 
-# Robot can now use filesystem tools
-result = robot.run("List the files in the current directory")
+# Robot can now use filesystem tools — :inherit is required on the run
+result = robot.run("List the files in the current directory", mcp: :inherit, tools: :inherit)
 ```
 
-MCP connections are resilient: failed servers are automatically retried on subsequent `run()` calls, and one failing server does not prevent others from connecting.
+MCP connections are resilient: failed servers are automatically retried on subsequent `run(mcp: :inherit)` calls, and one failing server does not prevent others from connecting. Connection failures are logged and recorded in `failed_mcp_server_names` rather than raised, so a robot whose servers all failed still builds and runs — just without those tools.
 
 ## Message Bus
 
@@ -633,7 +678,7 @@ robot = RobotLab.build(
 robot.run("Tell me a story") { |chunk| stream_to_client(chunk.content) }
 ```
 
-The `on_content:` callback participates in the RunConfig cascade, so it can be set at the network or config level and inherited by robots.
+The `on_content:` callback is a `RunConfig` field, so it can also be supplied through a robot's `config:` instead of as a constructor kwarg. It is read from the robot's own config at construction time — a network-level `config:` does not supply it.
 
 ## Token & Cost Tracking
 
@@ -674,7 +719,8 @@ robot = RobotLab.build(
 begin
   robot.run("Run all steps.")
 rescue RobotLab::ToolLoopError => e
-  puts e.message  # "Tool call limit of 10 exceeded"
+  puts e.message
+  # "Circuit breaker triggered: 11 tool calls exceeded max_tool_rounds (10)"
 end
 ```
 
@@ -687,14 +733,16 @@ result = robot.run("Something new.")  # robot is healthy again
 
 ## Doom Loop Detection
 
-Doom loop detection catches the subtler failure mode where a robot repeats the same tool call pattern indefinitely — not hitting `max_tool_rounds`, but cycling through the same sequence over and over. Set `doom_loop_threshold:` to enable it:
+Doom loop detection catches the subtler failure mode where a robot repeats the same tool call pattern indefinitely — not hitting `max_tool_rounds`, but cycling through the same sequence over and over.
+
+Unlike the circuit breaker, doom loop detection is **always active** — it is installed on every run. `doom_loop_threshold:` tunes the sensitivity; it does not switch the feature on. The default threshold is `3`.
 
 ```ruby
 robot = RobotLab.build(
   name: "runner",
   system_prompt: "Execute steps.",
   local_tools: [StepTool],
-  doom_loop_threshold: 3   # alert after 3 identical consecutive or cyclic sequences
+  doom_loop_threshold: 5   # tolerate more repetition before warning (default: 3)
 )
 ```
 
@@ -709,27 +757,33 @@ robot  = RobotLab.build(name: "runner", system_prompt: "...", config: config)
 
 `auto_compact` triggers context window compression automatically before each `run()`, preventing context overflow without manual intervention.
 
+`auto_compact` and `compact_threshold` are `RunConfig` fields, not constructor keywords — pass them via `config:`:
+
 ```ruby
 # Built-in trigger: compact when estimated token usage exceeds 80% of context window
 robot = RobotLab.build(
   name: "analyst",
   system_prompt: "You are a research analyst.",
-  auto_compact: :context_window
+  config: RobotLab::RunConfig.new(auto_compact: :context_window)
 )
 
 # Tune the threshold (here: compact at 70%)
 robot = RobotLab.build(
   name: "analyst",
   system_prompt: "You are a research analyst.",
-  auto_compact:      :context_window,
-  compact_threshold: 0.70
+  config: RobotLab::RunConfig.new(
+    auto_compact:      :context_window,
+    compact_threshold: 0.70
+  )
 )
 
 # Application-owned compaction: full control over when and how
 robot = RobotLab.build(
   name: "analyst",
   system_prompt: "You are a research analyst.",
-  auto_compact: ->(r) { r.compress_history(recent_turns: 5) if r.chat.messages.size > 40 }
+  config: RobotLab::RunConfig.new(
+    auto_compact: ->(r) { r.compress_history(recent_turns: 5) if r.chat.messages.size > 40 }
+  )
 )
 ```
 
@@ -739,12 +793,7 @@ robot = RobotLab.build(
 | `:context_window` | Compact when estimated token usage exceeds `compact_threshold` fraction of model's context window |
 | `Proc` | Called with the robot before each `run()`; application decides when and how to compact |
 
-`compact_threshold` defaults to `0.80` (80%). Requires the `classifier` gem when using the built-in `:context_window` strategy. Via `RunConfig`:
-
-```ruby
-config = RobotLab::RunConfig.new(auto_compact: :context_window, compact_threshold: 0.75)
-robot  = RobotLab.build(name: "analyst", system_prompt: "...", config: config)
-```
+`compact_threshold` defaults to `0.80` (80%). The built-in `:context_window` strategy uses the optional `classifier` gem; if it is missing, compaction is skipped with a logged warning rather than raising.
 
 ## Learning Accumulation
 
@@ -762,18 +811,9 @@ reviewer.learn("This codebase prefers map/collect over manual array accumulation
 reviewer.run("Review snippet B")  # learning is injected automatically
 ```
 
-Pass `learn: true` in the constructor to enable automatic end-of-session learning promotion via the `robot_lab-durable` gem:
-
-```ruby
-reviewer = RobotLab.build(
-  name: "reviewer",
-  system_prompt: "You are a Ruby code reviewer.",
-  learn: true,
-  learn_domain: "ruby_review"
-)
-```
+Cross-session learning promotion is provided by the [robot_lab-durable](https://github.com/MadBomber/robot_lab-durable) gem, which hooks the `:learn` lifecycle family. See that gem's documentation for setup.
 
-Learnings deduplicate bidirectionally: if a broader learning is added that contains an existing narrower one, the narrower one is dropped. Learnings are persisted to the robot's `Memory` and survive a robot rebuild when the same `Memory` object is reused.
+Learnings deduplicate bidirectionally: if a broader learning is added that contains an existing narrower one, the narrower one is dropped. Learnings are persisted to the robot's `Memory` for the lifetime of that robot.
 
 ```ruby
 reviewer.learnings          # => ["This codebase prefers map/collect..."]
@@ -782,7 +822,9 @@ reviewer.learn("new fact")  # deduplicates before storing
 
 ## Context Window Compression
 
-`robot.compress_history` prunes old conversation turns using TF-IDF cosine similarity, keeping only turns that are relevant to the most recent context. System messages and tool call/result pairs are always preserved.
+`robot.compress_history` prunes old conversation turns using term-frequency cosine similarity, keeping only turns that are relevant to the most recent context. System messages and tool call/result pairs are always preserved.
+
+Scoring uses raw term frequencies without IDF weighting — on a topic-focused conversation, IDF would suppress exactly the recurring terms that signal relevance.
 
 ```ruby
 # Basic compression: protect the 3 most recent turns, drop unrelated old turns
@@ -810,7 +852,7 @@ gem "classifier", "~> 2.3"
 
 ## Convergence Detection
 
-`RobotLab::Convergence` detects when two independent agents have reached the same conclusion using TF-IDF cosine similarity. Use it as a router fast-path to skip an expensive reconciler LLM call when verifiers already agree.
+`RobotLab::Convergence` detects when two independent agents have reached the same conclusion using term-frequency cosine similarity (no IDF — on a two-document comparison, IDF collapses the shared terms to zero). Use it to skip an expensive reconciler LLM call when verifiers already agree.
 
 ```ruby
 # Check similarity directly
@@ -825,18 +867,30 @@ RobotLab::Convergence.detected?(result_a.reply, result_b.reply)
 RobotLab::Convergence.detected?(text_a, text_b, threshold: 0.75)
 ```
 
-A common pattern is wiring convergence into a network router to skip reconciliation:
+`similarity` returns `0.0` if either text is blank or shorter than 30 characters (`Convergence::MIN_TEXT_LENGTH`), since term-frequency scoring is not meaningful on very short strings. Short replies like `"yes"` will therefore never register as converged.
+
+A common pattern is a gate robot that decides whether reconciliation is needed. Routing is done by overriding `call` and activating an `depends_on: :optional` task — networks have no separate router parameter:
 
 ```ruby
-router = ->(args) do
-  a = args.context[:verifier_a]&.reply.to_s
-  b = args.context[:verifier_b]&.reply.to_s
-  RobotLab::Convergence.detected?(a, b) ? nil : ["reconciler"]
+class ConvergenceGate < RobotLab::Robot
+  def call(result)
+    a = result.context[:verifier_a]&.reply.to_s
+    b = result.context[:verifier_b]&.reply.to_s
+
+    # Converged? Pass the result straight through and leave :reconciler dormant.
+    RobotLab::Convergence.detected?(a, b) ? result : result.activate(:reconciler)
+  end
 end
 
-network = RobotLab.create_network(name: "verify", router: router) do
-  # ...
+network = RobotLab.create_network(name: "verify") do
+  task :verifier_a, verifier_a, depends_on: :none
+  task :verifier_b, verifier_b, depends_on: :none
+  task :gate,       ConvergenceGate.new(name: "gate"), depends_on: [:verifier_a, :verifier_b]
+  task :reconciler, reconciler,  depends_on: :optional
 end
+
+result = network.run(message: "Audit this change")
+result.context.key?(:reconciler)  # => false when the verifiers agreed
 ```
 
 Requires the `classifier` gem (`~> 2.3`).
@@ -876,17 +930,84 @@ future.robot_name     # => "analyst"
 future.delegated_by   # => "manager"
 ```
 
+## Hook System
+
+RobotLab's hook system lets you intercept any point in a robot's execution pipeline without modifying framework code. Hooks use handler classes — subclasses of `RobotLab::Hook` that define lifecycle callbacks as class methods.
+
+```ruby
+class TimerHook < RobotLab::Hook
+  # namespace is auto-derived: TimerHook → :timer_hook
+  # override with: self.namespace = :timer
+
+  def self.before_run(ctx)
+    ctx.local.start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+
+  def self.after_run(ctx)
+    elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - ctx.local.start) * 1000).round(1)
+    puts "[timer] #{ctx.robot.name} #{elapsed}ms"
+  end
+
+  def self.on_error(ctx)
+    puts "[timer] #{ctx.robot.name} failed: #{ctx.error.message}"
+  end
+end
+```
+
+Register at the global, network, or robot level — or for a single call:
+
+```ruby
+RobotLab.on(TimerHook)              # every robot in this process
+network.on(TimerHook)               # robots inside this network only
+robot.on(TimerHook)                 # this robot only
+robot.run("msg", hooks: TimerHook)  # this call only
+robot.run("msg", hooks: [TimerHook, OtherHook])
+```
+
+Pass `context:` to set default `DotState` values for the handler's namespace before each callback fires:
+
+```ruby
+RobotLab.on(TimerHook, context: { threshold_ms: 500 })
+```
+
+Around hooks receive a block and must call it — and return its value — so the actual work executes:
+
+```ruby
+class PerfHook < RobotLab::Hook
+  self.namespace = :perf
+
+  def self.around_run(ctx, &block)
+    t0     = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    result = block.call   # executes the run
+    ms     = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).round(1)
+    $stderr.puts "[perf] #{ctx.robot.name} #{ms}ms"
+    result                # must return the result
+  end
+end
+```
+
+Because handler classes are Ruby constants (not Procs), all hook registrations are natively Ractor-serializable.
+
+See the [full Hook System guide](docs/guides/hooks.md) for all hook families, context objects, and extension patterns.
+
 ## Extension Gems
 
 RobotLab's optional capabilities are packaged as separate gems:
 
 | Gem | Description |
 |-----|-------------|
-| [robot_lab-ractor](https://github.com/MadBomber/robot_lab-ractor) | CPU parallelism via Ruby Ractors — `ractor_safe` tools and DAG-scheduled parallel networks |
+| [robot_lab-a2a](https://github.com/MadBomber/robot_lab-a2a) | Expose robots and networks as Agent2Agent (A2A) protocol services over HTTP+SSE |
+| [robot_lab-audit](https://github.com/MadBomber/robot_lab-audit) | SQLite-backed execution audit log wired through the Hook system |
+| [robot_lab-discovery](https://github.com/MadBomber/robot_lab-discovery) | Zero-configuration mDNS/DNS-SD robot discovery on local networks |
+| [robot_lab-document_store](https://github.com/MadBomber/robot_lab-document_store) | Embedding-based semantic document store for search / RAG |
+| [robot_lab-durable](https://github.com/MadBomber/robot_lab-durable) | HTM-backed long-term memory and cross-session knowledge persistence |
+| [robot_lab-ractor](https://github.com/MadBomber/robot_lab-ractor) | Ractor-based parallel tool execution and DAG-scheduled parallel networks |
 | [robot_lab-rails](https://github.com/MadBomber/robot_lab-rails) | Rails Engine, generators, `RobotLab::Job` ActiveJob base with Turbo Stream broadcasting |
-| [robot_lab-durable](https://github.com/MadBomber/robot_lab-durable) | Cross-session knowledge persistence via YAML-backed durable store |
-| [robot_lab-document_store](https://github.com/MadBomber/robot_lab-document_store) | In-memory vector store with fastembed embeddings for semantic search / RAG |
-| [robot_lab-acp](https://github.com/MadBomber/robot_lab-acp) | Expose robots and networks as ACP (Agent Communication Protocol) HTTP+SSE services |
+| [robot_lab-to](https://github.com/MadBomber/robot_lab-to) | Autonomous overnight agent loop — iterate a robot toward an objective |
+| [robot_lab-web](https://github.com/MadBomber/robot_lab-web) | Browser console — stream a robot's run over Server-Sent Events |
+
+> [!NOTE]
+> `robot_lab-acp` is retired; its functionality is superseded by `robot_lab-a2a`.
 
 ## Documentation
 

data/Rakefile

@@ -3,6 +3,8 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
 
+RUBOCOP_ENV = { "RUBOCOP_CACHE_ROOT" => "tmp/rubocop_cache" }.freeze
+
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
@@ -34,16 +36,6 @@ Rake::TestTask.new(:integration) do |t|
   t.ruby_opts << "-rtest_helper"
 end
 
-desc "Check code style with RuboCop"
-task :rubocop do
-  sh "bundle exec rubocop"
-end
-
-desc "Auto-correct RuboCop offenses"
-task :rubocop_fix do
-  sh "bundle exec rubocop -a"
-end
-
 desc "Check code complexity with Flog (warn ≥20, fail ≥50)"
 task :flog_check do
   require 'flog'
@@ -82,7 +74,26 @@ task :flog_check do
   end
 end
 
-desc "Run all quality checks: tests (with coverage), RuboCop, and Flog"
+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
   results = {}
 
@@ -94,13 +105,18 @@ task :quality do
   puts "\n#{'=' * 60}"
   puts "Quality Gate: RuboCop"
   puts '=' * 60
-  results[:rubocop] = system("bundle exec rubocop") ? :pass : :fail
+  results[:rubocop] = system(RUBOCOP_ENV, "bundle exec rubocop") ? :pass : :fail
 
   puts "\n#{'=' * 60}"
   puts "Quality Gate: Flog Complexity"
   puts '=' * 60
   results[:flog] = system("bundle exec rake flog_check") ? :pass : :fail
 
+  puts "\n#{'=' * 60}"
+  puts "Quality Gate: Flay Duplication"
+  puts '=' * 60
+  results[:flay] = system("bundle exec rake flay_check") ? :pass : :fail
+
   puts "\n#{'=' * 60}"
   puts "Quality Summary"
   puts '=' * 60