robot_lab 0.1.0 → 0.2.6

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,14 +36,98 @@ 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"
+desc "Check code complexity with Flog (warn ≥20, fail ≥50)"
+task :flog_check do
+  require 'flog'
+
+  # Target to work toward; methods above this are warned but don't fail the gate.
+  METHOD_WARN = 20.0
+  # Current baseline floor — established from first run. Reduce incrementally.
+  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')  # skip file-level non-method code
+    if score > METHOD_FAIL
+      failures  << "#{'%.1f' % score}: #{method}"
+    elsif score > METHOD_WARN
+      warnings  << "#{'%.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 "Auto-correct RuboCop offenses"
-task :rubocop_fix do
-  sh "bundle exec rubocop -a"
+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 = {}
+
+  puts "\n#{'=' * 60}"
+  puts "Quality Gate: Tests + Coverage"
+  puts '=' * 60
+  results[:tests] = system("bundle exec rake test") ? :pass : :fail
+
+  puts "\n#{'=' * 60}"
+  puts "Quality Gate: RuboCop"
+  puts '=' * 60
+  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
+  results.each do |gate, status|
+    icon = status == :pass ? 'PASS' : 'FAIL'
+    puts "  [#{icon}] #{gate}"
+  end
+  puts '=' * 60
+
+  abort "\nQuality gate failed" if results.values.any?(:fail)
+  puts "\nAll quality gates passed."
 end
 
 namespace :examples do
@@ -58,14 +144,37 @@ namespace :examples do
     "18_rails" => { setup: "bin/setup", run: "bin/dev" }
   }.freeze
 
+  # Examples that require external services or user setup not guaranteed to be present
+  EXTERNAL_SERVICE_EXAMPLES = {
+    "33_stock_generator.rb" => "Redis server on localhost:6379",
+    "33_stock_predictor.rb" => "Redis server on localhost:6379 + running 33_stock_generator",
+    "34_agentskills.rb"     => "AgentSkills skill file at ~/.prompts/skills/code_reviewer/SKILL.md"
+  }.freeze
+
   desc "Run all examples (excludes standalone apps like 18_rails)"
   task :all do
+    failed = []
+
     # Single-file examples
-    Dir.glob("examples/*.rb").sort.each do |example|
+    Dir.glob("examples/*.rb").each do |example|
+      base = File.basename(example)
+
+      if EXTERNAL_SERVICE_EXAMPLES.key?(base)
+        puts "\n#{'=' * 60}"
+        puts "Skipped: #{example} (requires #{EXTERNAL_SERVICE_EXAMPLES[base]})"
+        puts '=' * 60
+        next
+      end
+
       puts "\n#{'=' * 60}"
       puts "Running: #{example}"
       puts '=' * 60
-      ruby example
+      begin
+        ruby example
+      rescue RuntimeError => e
+        puts "FAILED: #{example} — #{e.message}"
+        failed << example
+      end
     end
 
     # Subdirectory-based demos
@@ -76,7 +185,12 @@ namespace :examples do
       puts "\n#{'=' * 60}"
       puts "Running: #{path}"
       puts '=' * 60
-      ruby path
+      begin
+        ruby path
+      rescue RuntimeError => e
+        puts "FAILED: #{path} — #{e.message}"
+        failed << path
+      end
     end
 
     # Remind about standalone apps
@@ -87,6 +201,14 @@ namespace :examples do
       puts "  Run:   cd examples/#{dir} && #{commands[:run]}"
       puts '=' * 60
     end
+
+    if failed.any?
+      puts "\n#{'=' * 60}"
+      puts "#{failed.size} example(s) failed:"
+      failed.each { |f| puts "  #{f}" }
+      puts '=' * 60
+      exit 1
+    end
   end
 
   desc "Run a specific example by number (e.g., rake examples:run[1])"

data/agent2agent_review.md

@@ -0,0 +1,192 @@
+# Review: `agent2agent` Ruby Gem
+
+**Source:** https://github.com/general-intelligence-systems/agent2agent
+**Docs:** https://general-intelligence-systems.github.io/agent2agent/
+**License:** Apache 2.0
+**Ruby:** >= 3.2
+**Reviewed:** 2026-05-05
+
+---
+
+## What It Is
+
+A complete Ruby implementation of Google's A2A (Agent-to-Agent) protocol — an open standard for interoperable, cross-vendor AI agent communication over HTTP. The gem provides both a server (Rack app) and a client, plus SSE streaming, task persistence, and push notifications.
+
+---
+
+## Wire Protocol
+
+Two parallel transport bindings, both implemented:
+
+| Transport | Path | Format |
+|---|---|---|
+| JSON-RPC 2.0 | `POST /a2a` | `{"jsonrpc":"2.0","method":"SendMessage","params":{...}}` |
+| HTTP+JSON/REST | `POST /message:send`, `GET /tasks/{id}`, etc. | Plain JSON |
+| Agent Discovery | `GET /.well-known/agent-card.json` | Capabilities manifest |
+
+### The 11 Protocol Operations
+
+1. `SendMessage` — POST `/message:send` (synchronous)
+2. `SendStreamingMessage` — POST `/message:stream` (SSE, server-streaming)
+3. `GetTask` — GET `/tasks/{id}`
+4. `ListTasks` — GET `/tasks`
+5. `CancelTask` — POST `/tasks/{id}:cancel`
+6. `SubscribeToTask` — SSE stream of task updates
+7. `CreateTaskPushNotificationConfig` — POST `/tasks/{id}/push`
+8. `GetTaskPushNotificationConfig` — GET `/tasks/{id}/push/{config_id}`
+9. `ListTaskPushNotificationConfigs` — GET `/tasks/{id}/push`
+10. `DeleteTaskPushNotificationConfig` — DELETE `/tasks/{id}/push/{config_id}`
+11. `GetExtendedAgentCard` — GET extended agent card
+
+### Task State Machine
+
+`SUBMITTED → WORKING → INPUT_REQUIRED → COMPLETED / FAILED / CANCELED / REJECTED`
+
+---
+
+## Key Classes and Their Roles
+
+| Class | Role |
+|---|---|
+| `A2A::Agent` | DSL: `on("SendMessage") { \|req\| respond(...) }` — registers operation handlers |
+| `A2A::Server` | Rack app — mountable in any Rack stack or Rails router |
+| `A2A::Client` | Async-HTTP client; all 11 ops auto-generated as snake_case methods |
+| `A2A::Proto` | Parses the real `data/a2a.proto` file — single source of truth for operations |
+| `A2A::Schema` | Loads 47-type `data/a2a.json`; validates with `json_schemer`; camelCase/snake_case |
+| `A2A::TaskStore` | In-memory task CRUD with `Thread::Queue` pub/sub and webhook delivery |
+| `A2A::Store::SQLite` | Production drop-in: WAL mode, indexed, fiber-safe `Async::Queue` pub/sub |
+| `A2A::SSE::Stream` | Subclasses `Protocol::HTTP::Body::Writable`; Falcon passes it untouched |
+| `A2A::Bindings::JsonRpc` | Rack middleware that parses JSON-RPC envelopes and wraps responses |
+
+### Agent DSL Example
+
+```ruby
+agent = A2A::Agent.new do
+  on "SendMessage", "SendStreamingMessage" do |context|
+    task = context.store.create(context.request)
+    stream = context.stream
+
+    Async do
+      result = robot.run(context.request.params[:message])
+      context.store.complete(task.id, result)
+      stream.event(result, type: "result")
+      stream.finish
+    end
+
+    context.respond(task)
+  end
+end
+
+server = A2A::Server.new
+server.register(agent)
+run server
+```
+
+### Client Example
+
+```ruby
+Async do
+  client = A2A::Client.new("http://localhost:9292")
+  card = client.agent_card
+  result = client.send_message(message: { role: "user", parts: [{ text: "Hello" }] })
+  puts result
+end
+```
+
+---
+
+## Notable Patterns
+
+- **Duck-typed stores:** Any object implementing the task store interface can be swapped in — `TaskStore` (in-memory) or `Store::SQLite` (production), or a custom implementation.
+- **Proto as source of truth:** `Proto` parses `data/a2a.proto` directly to extract operation metadata — stays in sync with the Google A2A spec automatically.
+- **Fiber-native:** The SQLite store's pub/sub uses `Async::Queue`; SSE bodies use `Protocol::HTTP::Body::Writable`. Fully fiber-safe when run under Falcon.
+- **`returnImmediately` flag:** Background jobs return a task ID immediately; updates stream via SSE as work proceeds.
+- **`STATE_INPUT_REQUIRED`:** Multi-turn conversations — agent transitions to this state when it needs more user input before continuing. Client sends another `SendMessage` referencing the same task context.
+- **Inline tests via `scampi`:** Tests live inside source files (`test do ... end`), not a separate test directory.
+- **Tenant-prefixed paths:** Every REST route has a variant: `/{tenant}/message:send` for multi-tenant deployments.
+
+---
+
+## Authentication
+
+- **AgentCard** declares supported auth schemes in the capabilities manifest
+- **Push notification configs** carry per-webhook auth: `scheme` + `credentials` sent as `Authorization: Bearer <credentials>` on webhook delivery; optionally also `X-A2A-Notification-Token`
+- Incoming request authentication is left to the application layer (standard Rack middleware pattern)
+
+---
+
+## Dependencies
+
+**Runtime:**
+- `async (~> 2.0)`, `async-http (~> 0.95)` — fiber concurrency and HTTP
+- `rack (~> 3.0)` — server composition (pure Rack, Rails-mountable)
+- `json_schemer (~> 2.5)` — schema validation against 47 A2A types
+- `google-protobuf (~> 4.34)` — proto file parsing
+- `sqlite3` — persistent task store
+- `protocol-http (~> 0.62)` — `Body::Writable` for SSE
+- `scampi` — inline test framework
+- `console` — structured logging
+
+**Development:**
+- `falcon (~> 0.55)` — async HTTP server for running agents
+
+---
+
+## Applicability to Your Projects
+
+### RobotLab — High Value
+
+The most compelling integration: expose each `Robot` or `Network` as a standard A2A service. This enables cross-language orchestration (Python LangChain, JS Genkit, Go agents, Google Cloud agents) without any shared code.
+
+**Robot-as-A2A-Service:**
+- `A2A::Agent` adapter delegates `SendMessage` → `robot.run(request.message)`, result becomes the A2A task result
+- Publish an AgentCard at `/.well-known/agent-card.json` advertising each robot's capabilities and tools
+- Use `A2A::Store::SQLite` to persist tasks across requests (stateless HTTP tier in front of stateful robots)
+
+**Streaming:**
+- `SendStreamingMessage` + `SSE::Stream` maps directly onto RubyLLM's streaming callbacks
+- Streaming events become real-time SSE — no additional infrastructure needed
+
+**Cross-process robot networks:**
+- Instead of `TypedBus` (in-process pub/sub only), robots in separate processes or machines call each other via `A2A::Client`
+- A Network router can delegate to remote robots via `client.send_message(...)` — standard HTTP replaces shared-memory message passing
+
+**Background jobs:**
+- A2A's push notification config CRUD gives external systems a standard webhook protocol for task completion
+- Maps cleanly onto RobotLab's existing async robot semantics
+
+**Multi-turn conversations:**
+- `STATE_INPUT_REQUIRED` maps directly to RobotLab's `AskUser` tool pattern — robot needs user input before continuing
+- Web clients get a proper protocol for handling confirmation flows rather than a terminal prompt
+
+**Compatibility note:** Both RobotLab and `agent2agent` use the `async` gem — they compose cleanly. The main requirement is running under Falcon rather than a plain Ruby process. `TypedBus` (`Async::Queue`) and `A2A::Store::PubSub` (`Async::Queue`) are both fiber-based and compatible.
+
+### AIA — Moderate Value
+
+- `A2A::Client` could delegate tasks to remote A2A-compliant agents (specialized coding agents, search agents, etc.) instead of calling LLM APIs directly
+- AIA could optionally expose itself as a local A2A server on `localhost:PORT` so IDE plugins or other tools can send it tasks via standard protocol
+- AgentCard discovery would let AIA auto-configure available capabilities when connecting to remote agents
+
+### Rails Apps Generally
+
+`A2A::Server` is pure Rack:
+
+```ruby
+# config/routes.rb
+mount A2A::Server.new(agent: my_agent), at: "/agents/myagent"
+```
+
+This works as-is. The 47-type schema validation via `json_schemer` is also useful standalone for validating A2A protocol payloads.
+
+---
+
+## Bottom Line
+
+Production-quality gem for its scope. Clean architecture: Rack middleware chain, duck-typed stores, fiber-safe pub/sub, SSE via `protocol-http`. Inline test coverage is extensive.
+
+**Highest-value opportunity for RobotLab:** Robot-as-A2A-Service — exposing robots as standards-compliant HTTP endpoints enables cross-language agent orchestration that the current `TypedBus` approach (in-process only) cannot support. This would position RobotLab robots as first-class participants in the emerging A2A ecosystem alongside Python, JavaScript, and Go agent frameworks.
+
+**Specific algorithms/patterns worth porting:**
+1. `A2A::Store::SQLite` pub/sub pattern (Async::Queue-based) — applicable to RobotLab's Memory system
+2. AgentCard capability manifest — useful for RobotLab's planned tool/capability discovery
+3. `STATE_INPUT_REQUIRED` state machine entry — formalizes the `AskUser` pattern with a standard protocol state

data/agentf_improvements.md

@@ -0,0 +1,253 @@
+# `agentf` Gem Analysis
+
+**Repository:** https://github.com/nealdeters/agentf
+**Author:** Neal Deters
+**Ruby:** 3.3.0+ | **Runtime deps:** `redis ~> 4.8`, `dotenv ~> 2.8`
+
+---
+
+## What It Is
+
+A Ruby multi-agent workflow engine for software development. Orchestrates
+role-specialized agents (Planner, Engineer, QA, Reviewer, Security) that share
+Redis memory — but **never calls an LLM itself**. It runs as an MCP server over
+stdio and lets the IDE's AI (Copilot, OpenCode) do the actual inference.
+It is scaffolding, not an API wrapper.
+
+Three surfaces:
+- **CLI** (`agentf <subcommand>`) — memory management, code exploration, metrics, evals
+- **MCP server** (`agentf mcp-server`) — 19 tools over stdio for IDE integrations
+- **Ruby API** — `WorkflowEngine`, `Agents::*`, `RedisMemory` for programmatic use
+
+---
+
+## Architecture
+
+| Layer | Files | Role |
+|---|---|---|
+| Entry point | `agentf.rb`, `bin/agentf` | Config singleton + CLI boot |
+| CLI | `cli/router.rb`, `cli/memory.rb`, `cli/code.rb` | Subcommand dispatch |
+| Agents | `agents/base.rb`, role subclasses | Role-based agent classes |
+| Workflow | `workflow_engine.rb` | Orchestrator / sequencer |
+| Memory | `memory.rb`, `memory/confirmation_handler.rb` | Redis-backed storage |
+| Contracts | `workflow_contract.rb`, `agent_execution_contract.rb` | Constraint enforcement |
+| Tools | `tools/`, `tools.rb` | Primitive capabilities |
+| Commands | `commands/registry.rb`, `commands/*.rb` | Named command registry |
+| MCP | `mcp/server.rb`, `mcp/stub.rb` | stdio MCP protocol server |
+| Service | `service/providers.rb` | Provider adapters |
+| Installer | `installer.rb` | Manifest generation and provider setup |
+
+---
+
+## Patterns Worth Stealing
+
+### 1. Agents That Describe Themselves at the Class Level
+
+All agent metadata — `description`, `deliverables`, `policy_boundaries`,
+`when_to_use`, `commands` — are class methods, not instance state or external
+YAML. Agents are self-documenting, introspectable at install time, and
+verifiable without instantiating anything. The `Installer` reads these at
+install time to generate markdown manifests.
+
+### 2. Three-Mode Contract Enforcement (advisory / enforcing / off)
+
+A contract object wraps agent execution with `before!`/`after!` validation.
+Run workflows in `advisory` mode during development (log violations, don't
+stop), flip to `enforcing` for production. TDD phase discipline (`"red"` vs
+`"green"`) is enforced at the contract layer, not by convention.
+
+### 3. Human-in-the-Loop Memory Writes
+
+`ConfirmationHandler` wraps Redis writes so that when confirmation is needed,
+instead of raising it returns `{ confirmation: true, payload: ..., instructions: ... }`.
+The caller re-invokes with `confirmedWrite: "confirmed"`. Works identically
+across CLI, MCP, and programmatic callers.
+
+### 4. Deterministic Local Embeddings With No ML Dependency
+
+`EmbeddingProvider` SHA256-hashes tokens, uses the hash to pick a dimension in
+a 64-element float vector, then normalizes it. Zero API calls, zero latency,
+fully reproducible. Crude but sufficient for semantic memory search in a
+dev-tool context.
+
+### 5. Black-Box Shell Script Evals
+
+Each eval scenario is three files: `prompt.txt`, `scenario.yml`, and
+`verify.sh`. The shell script asserts postconditions against real Redis state.
+Simple, portable, no mocking — `agentf eval run all` just executes them.
+
+### 6. Graceful Redis Capability Degradation
+
+The memory layer detects at runtime whether Redis Stack's JSON/Search/Vector
+modules are present and degrades silently. Full semantic search if available;
+plain key-value otherwise. No config flag needed — baked into `RedisMemory`.
+
+### 7. Ruby Generating Its Own TypeScript Integration
+
+The installer generates TypeScript plugin files (`agentf-plugin.ts`,
+`tsconfig.json`, `package.json`) from within Ruby for OpenCode integration.
+A Ruby gem producing its own typed IDE plugin layer is unusual and practical.
+
+### 8. Policies Stored in Code, Not Config
+
+`policy_boundaries` returns `{ "always" => [...], "ask_first" => [...], "never" => [...] }`
+directly from Ruby class methods. Changing a policy means changing Ruby, not
+YAML — no config drift.
+
+### 9. Workflow Profiles as Constants
+
+Workflow compositions are defined as constants in `WorkflowEngine::PROFILES`
+(e.g., `rails_standard`, `rails_37signals`), mapping task types to ordered
+agent sequences. One canonical source of truth for workflow shapes.
+
+---
+
+## RobotLab Applicability Analysis
+
+### Patterns That Don't Apply
+
+**Pattern 7 — Ruby Generating Its Own TypeScript Integration**
+agentf is an IDE tool targeting Copilot/OpenCode. RobotLab is a Ruby library with no IDE integration surface. Not relevant.
+
+**Pattern 6 — Graceful Redis Capability Degradation**
+Already handled. `Memory` already degrades `redis → hash` fallback at initialization. `DocumentStore` uses fastembed, not Redis Stack — separate concern covered below.
+
+---
+
+### Patterns Worth Implementing
+
+---
+
+#### Pattern 1 — Self-Describing Robots/Tools (HIGH VALUE)
+
+This is the missing piece for `tool_manifest_plan.md`. Nothing auto-registers today because there is nowhere to register *to* and no class-level metadata to register. agentf's insight: put descriptors at the class level, not in instances.
+
+```ruby
+class MyTool < RobotLab::Tool
+  self.description = "Fetch current weather for a location"
+  self.tags        = [:network, :read_only]
+end
+```
+
+At class-load time, Zeitwerk triggers auto-registration into `RobotLab.tool_registry`. The selector-robot pattern becomes viable without any explicit registration ceremony. Live callable instances stay per-robot; the global registry holds lightweight descriptors only (name + description). This is the v1 the `tool_manifest_plan.md` actually needs — and avoids the MCP auto-registration problem identified in that plan's review notes.
+
+Robot subclasses get the same treatment:
+```ruby
+class SupportBot < RobotLab::Robot
+  self.description  = "Handles tier-1 customer support"
+  self.capabilities = [:search, :ticket_creation]
+end
+```
+
+This also enables the `Installer`-style manifest generation: `RobotLab.tool_registry.summary` produces the compact name+description list the selector robot reasons over.
+
+---
+
+#### Patterns 2 + 8 — Contract Enforcement + Policy Boundaries (HIGH VALUE, medium effort)
+
+RobotLab has a circuit breaker (`max_tool_rounds`) and an error hierarchy — but no *pre/post validation layer* on execution. As AIA drives RobotLab into production use, this gap is significant.
+
+The three modes map cleanly to the dev→prod lifecycle:
+- `advisory` — log violations, don't block (development default)
+- `enforcing` — raise on violation (production default)
+- `off` — no overhead (test default)
+
+Policies declared at the Tool class level:
+```ruby
+class DeleteFileTool < RobotLab::Tool
+  policy :ask_first   # always prompt user before executing
+end
+
+class FormatDriveTool < RobotLab::Tool
+  policy :never       # contract blocks execution entirely in enforcing mode
+end
+```
+
+The contract wraps `robot.run()` with `before!`/`after!` hooks — checks token budget, validates tool policies, enforces max cost. A `RunConfig` field (`contract: :advisory`) controls the mode and flows through the standard hierarchy. This pairs naturally with the existing `RunConfig` merge semantics and would be the first true safety/governance layer in RobotLab.
+
+---
+
+#### Pattern 9 — Workflow Profiles (LOW EFFORT, good discoverability)
+
+Networks are currently built by hand each time. A `RobotLab::Profiles` module with named constants would reduce boilerplate and document canonical topologies:
+
+```ruby
+RobotLab::Profiles::CONSENSUS   # fan-out to N robots → reconciler
+RobotLab::Profiles::PIPELINE    # sequential chain
+RobotLab::Profiles::PARALLEL    # concurrent, no synthesis
+RobotLab::Profiles::MCP_FAN_OUT # one robot per MCP server
+```
+
+Each profile is a lambda/factory that takes robots + optional router and returns a configured network. This also gives AIA's `RobotFactory` topologies a canonical home in the library itself rather than application-level code.
+
+---
+
+#### Pattern 5 — Eval Framework (MEDIUM EFFORT, high long-term value)
+
+RobotLab has 22 example scripts but **zero assertions**. They are demos, not evals. agentf's `prompt.txt + scenario.yml + verify.sh` per scenario is the right shape.
+
+For RobotLab the natural form:
+- `evals/scenarios/convergence_basic/` — prompt, expected behavior description, `verify.rb` script
+- `rake eval:run[convergence_basic]` replays against a VCR cassette and asserts postconditions
+- `rake eval:run:all` becomes a regression suite for agent behavior
+
+This connects directly to AIA's EDD (Eval-Driven Development) vision and would give confidence before a 1.0 release. The existing VCR/WebMock infrastructure is the right foundation.
+
+---
+
+#### Pattern 4 — Deterministic Embedding Fallback (LOW EFFORT)
+
+`DocumentStore` hard-requires fastembed — no fallback. On first use it downloads an ONNX model, which is slow and requires a working network. `word_hash` (stemmed TF vectors) already exists in the codebase and is used by `compress_history`, `search_history`, and `Convergence`.
+
+A simple degradation path: when fastembed raises `LoadError` or the model is unavailable, `DocumentStore` falls back to `word_hash` cosine similarity with a logged warning. Zero new infrastructure — just wiring what already exists into `DocumentStore#embed`.
+
+---
+
+#### Pattern 3 — HITL Confirmation Protocol (LOW VALUE given AskUser)
+
+The agentf pattern — return `{ confirmation: true, payload: }` instead of raising, re-invoke with `confirmedWrite: "confirmed"` — is elegant for memory writes that need approval. However, RobotLab already has `AskUser` for the primary HITL use case. This pattern only becomes interesting if RobotLab needs programmatic HITL that doesn't require a terminal (e.g., web apps pausing for user approval via HTTP callback). Not urgent.
+
+---
+
+### Priority Ranking
+
+| Priority | Pattern | Effort | Connects To |
+|---|---|---|---|
+| 1 | Self-describing tools/robots (class-level metadata) | Medium | `tool_manifest_plan.md` — makes ToolManifest v1 actionable |
+| 2 | Contract enforcement + Policy boundaries | Medium | Production safety gap; RunConfig integration |
+| 3 | Eval framework | Medium | Long-term regression confidence; AIA EDD |
+| 4 | Workflow profiles | Low | AIA's RobotFactory; discoverability |
+| 5 | DocumentStore word_hash fallback | Low | Dev ergonomics; no ONNX download needed |
+
+**Natural weekly pairing:** Pattern 1 (self-describing classes → ToolManifest v1) + Pattern 9 (workflow profiles) form a coherent "discoverability and composability" theme. Patterns 2+8 are the right *next* architectural investment but scope to a separate week.
+
+---
+
+## Comparison to Other Agent Frameworks
+
+| Aspect | `agentf` | LangChain (Python) | CrewAI (Python) |
+|---|---|---|---|
+| Language | Ruby | Python | Python |
+| LLM calls | None (delegates to IDE) | Direct | Direct |
+| Agent communication | Shared Redis memory | In-process state | Sequential/hierarchical |
+| Memory | Episodic + semantic (Redis Stack) | Various vector stores | Basic |
+| IDE integration | MCP server (Copilot, OpenCode) | None native | None native |
+| Contract enforcement | 3-mode advisory/enforcing/off | None | None |
+| Self-describing agents | Class-method metadata | No | Role strings in YAML |
+| Eval framework | Black-box shell scripts | Unit tests | Unit tests |
+| TDD enforcement | Built-in (red/green contracts) | None | None |
+
+Within Ruby there is essentially no direct equivalent. `ruby-openai` and
+`omniai` handle LLM API calls but have no orchestration. `agentf` is novel in
+the Ruby ecosystem for combining Redis-backed episodic memory, role-specialized
+agent classes, contract enforcement, and an MCP stdio server in one gem.
+
+---
+
+## The Big Takeaway
+
+The most instructive thing about `agentf` is its **division of responsibility**:
+the gem owns memory, sequencing, policies, and tool-exposure via MCP — the
+IDE's AI owns inference. That separation means no API keys, no HTTP calls to
+LLM providers, and no model coupling. If building AI-assisted tooling in Ruby,
+that architecture is worth emulating.

data/agents.md

@@ -0,0 +1,14 @@
+### Local Agent Context: Repository Root
+
+- Start here, then navigate to the closest directory AGENTS.md before coding.
+- Do not operate from root unless necessary.
+
+## Table of Contents
+
+- [.architecture/reviews](./.architecture/reviews/AGENTS.md): Access `config.yml` for architecture-related settings.
+- [.github/workflows](./.github/workflows/AGENTS.md): Review `deploy-github-pages.yml` for CI/CD pipeline specifics.
+- [.ruby-lsp](./.ruby-lsp/AGENTS.md): Initialize your environment with `Gemfile` dependencies.
+- [docs](./docs/AGENTS.md): Consult `/docs/api/core/robot.md` for robot-related API documentation.
+- [examples](./examples/AGENTS.md): Explore `14_rusty_circuit/open_mic.rb` for demo scripts in action.
+- [lib/generators/robot_lab](./lib/generators/robot_lab/AGENTS.md): Use `templates/initializer.rb.tt` for custom project setup.
+- [test/robot_lab](./test/robot_lab/AGENTS.md): Implement new tests based on `test_helper.rb` configurations.

data/docs/api/core/index.md

@@ -75,6 +75,7 @@ classDiagram
 | [AskUser](tool.md#built-in-askuser) | Built-in tool for terminal-based user interaction |
 | [Memory](memory.md) | Reactive key-value store for sharing data |
 | RobotMessage | Typed envelope for bus-based inter-robot communication |
+| `RobotLab::Runnable` | Shared interface (`crew`, `chief`, `run`) implemented by both `Robot` and `Network` — see [Runnable Protocol](../../architecture/core-concepts.md#runnable-protocol) |
 
 ## Quick Examples