robot_lab 0.1.0 → 0.2.1

data/CHANGELOG.md

@@ -8,6 +8,78 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-05-19
+
+### Added
+
+- **`examples/common.rb`** — shared setup file required by all numbered examples. Defines:
+  - `LlmConfig = Data.define(:provider, :model)` and a frozen `LLM` hash with `:default` (OpenAI/gpt-5.4), `:local` (Ollama/llama3.2), and `:anthropic` (claude-opus-4-7) entries — access as `LLM[:default].model`
+  - `RubyLLM.configure` with null logger and `LLM[:default].model` as `default_model`
+  - `RobotLab.configure` with null logger
+  - Output helpers: `banner(title)`, `section(title)`, `hr`, `show_code(ruby_string, label:)` using `rouge` for syntax highlighting
+- **`rouge` gem** added to development group for syntax-highlighted example output
+- **`.envrc` files** in `examples/`, `examples/14_rusty_circuit/`, `examples/15_memory_network_and_bus/`, and `examples/16_writers_room/` — each exports `ROBOT_LAB_TEMPLATE_PATH` pointing at the local `prompts/` directory for use with [direnv](https://direnv.net/)
+
+### Changed
+
+- **All 27+ numbered examples** refactored to `require_relative "common"` instead of requiring the gem directly, and to use `LLM[:default].model` instead of the hardcoded string `"gpt-5.4"`
+- **Example 04 (MCP)** now calls `robot.connect_mcp!` before inspecting MCP attributes, fixing a lazy-initialization issue where `mcp_clients` and `mcp_tools` were empty until the first `run()` call
+
+## [0.2.1] - 2026-05-11 (unreleased)
+
+### Added
+
+- **`flog` complexity gate** — `flog_check` Rake task enforces method-level complexity limits (warn ≥20, fail ≥50); `quality` task runs tests, RuboCop, and Flog in sequence with a unified pass/fail summary
+- `flog` gem added to development/test group
+- Branch coverage enabled unconditionally (previously CI-only) with minimum thresholds: line 95%, branch 75%
+
+### Changed
+
+- Bumped version to 0.2.1
+- **`Robot#initialize` decomposed** into focused private methods: `assign_identity_ivars`, `build_effective_config`, `extract_config_ivars`, `initialize_runtime_state`, `initialize_memory`, `configure_learning`, `apply_template`, `apply_system_prompt`, `apply_chat_params`, `register_chat_callbacks`
+- **`Robot#run` decomposed** into: `resolve_run_memory`, `prepare_tools`, `invoke_ask`, `enforce_token_budget!`
+- **`BusPoller#process_and_drain`** split into `drain_queued_deliveries` and `release_robot` for independent testability
+- **`TemplateRendering#apply_skills_and_template_to_chat`** split into `collect_prompt_content` (pure computation) and `apply_prompt_to_chat` (pure mutation)
+- Removed `.serena/` project configuration files from version control
+- Removed `.claude/memory.sqlite3` database files from version control
+
+## [0.2.0] - 2026-05-07
+
+### Added
+
+- **`Durable::Learning`** — cross-session and within-session learning capability for robots. Robots accept `learn: true` and `learn_domain:` constructor params to persist knowledge across sessions via `~/.robot_lab/durable/` YAML files.
+- **`Durable::Store`** — YAML-backed knowledge store with file locking, keyword recall, and confidence tracking.
+- **`Durable::Entry`** — immutable value object for knowledge records with confidence progression.
+- **`Durable::Reflector`** — promotes session learnings to durable storage at end of each run.
+- **`RecallKnowledge` tool** — robots query past knowledge before uncertain decisions.
+- **`RecordKnowledge` tool** — robots persist new knowledge learned during a session.
+- **`AgentSkill`** — value object for discoverable skills defined by `SKILL.md` files with YAML front matter (name, description, version, dependencies, parameters)
+- **`AgentSkillCatalog`** — service for locating and indexing `AgentSkills/` directories at runtime
+- **`AgentSkillMatching`** — `Robot` mixin enabling runtime embedding-based skill injection: the robot selects the most relevant skills from a catalog based on semantic similarity before each run
+- **`ScriptTool`** — factory that wraps shell scripts as robot tools; auto-generates JSON schema from script `--help` output
+- **`DoomLoopDetector`** — detects consecutive and cyclic tool-call repetition; wired into `Robot#run` via singleton `execute_tool` override
+- **`doom_loop_threshold`** field on `RunConfig` — configures the repetition threshold before a `ToolLoopError` is raised
+- **`auto_compact` and `compact_threshold`** fields on `RunConfig` — `:context_window` mode estimates token usage before each run and calls `compress_history` when usage exceeds the threshold (default 80%); a `Proc` value delegates the decision and strategy entirely to the caller
+
+### Changed
+
+- Bumped version to 0.2.0
+- **Extension gems extracted** — `robot_lab-document_store`, `robot_lab-durable`, `robot_lab-ractor`, and `robot_lab-rails` are now separate gems distributed via rubygems.org; the core gemspec drops `fastembed`, `ractor_queue`, and `ractor-wrapper` as hard dependencies
+- **`Durable::Learning` inclusion** is now conditional on the `robot_lab-durable` gem being loaded
+- **Tool Ractor routing** guarded on `RobotLab.respond_to?(:ractor_pool)` so the core gem runs without the ractor extension
+- **Memory drainer scheduling** — `@drainer_scheduled` remains `true` when rescheduling to prevent concurrent writers from spawning competing drain fibers
+- `@chat` state reset now uses `reset_messages!` / `add_message` public API instead of internal instance variable manipulation
+- Rails generators moved to `robot_lab-rails` extension gem
+
+### Fixed
+
+- Memory drainer double-schedule race when concurrent writers triggered overlapping drain cycles
+- `DocumentStore` instantiation guarded with a `LoadError` message when the extension gem is absent
+- `AgentSkill` YAML parsing hardened against empty strings and non-Hash front matter
+- Missing requires added to examples after gem extraction
+- `doom_loop_threshold` and `auto_compact` documented in README and guides
+- `learn:` parameter and `robot_lab-acp` documented in README
+
 ## [0.1.0] - 2026-04-29
 
 ### Added

data/CLAUDE.md

@@ -0,0 +1,139 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+RobotLab is a Ruby framework for building and orchestrating multi-robot LLM workflows. It provides:
+- **Robots**: LLM agents with tools, templates, and memory
+- **Networks**: Orchestration of multiple robots with routing logic
+- **MCP Integration**: Model Context Protocol for external tool servers
+- **Rails Integration**: Generators and ActiveRecord support for conversation history
+
+Built on top of [ruby_llm](https://rubyllm.com) and uses Zeitwerk for autoloading.
+
+## Commands
+
+```bash
+# Run all tests
+bundle exec rake test
+
+# Run a single test file
+bundle exec rake test_file[robot_lab/robot_test.rb]
+
+# Run tests with verbose output
+bundle exec rake test_verbose
+
+# Run integration tests only
+bundle exec rake integration
+
+# Lint with RuboCop
+bundle exec rubocop
+
+# Auto-fix RuboCop offenses
+bundle exec rubocop -a
+
+# Run all examples
+bundle exec rake examples:all
+
+# Run specific example by number (e.g., 01, 02)
+bundle exec rake examples:run[1]
+```
+
+## Architecture
+
+### Core Classes
+
+- **`RobotLab`** (`lib/robot_lab.rb`): Module entry point with factory methods `build()` for robots and `create_network()` for networks
+- **`Robot`** (`lib/robot_lab/robot.rb`): Subclass of `RubyLLM::Agent` with template-based prompts, tools, MCP clients, and memory. Creates a persistent chat on initialization. Use `robot.run("...")` to interact. When standalone uses its own memory; when in a network uses shared network memory
+- **`Network`** (`lib/robot_lab/network.rb`): Orchestrates multiple robots with routing logic. Robots execute sequentially sharing memory. Router is a lambda that returns robot names
+- **`NetworkRun`** (`lib/robot_lab/network_run.rb`): Stateful execution of a network run with isolated memory clone
+
+### RunConfig
+
+- **`RunConfig`** (`lib/robot_lab/run_config.rb`): Shared configuration object for LLM, tools, callbacks, and infrastructure settings. Flows through the hierarchy: `RobotLab.config -> Network -> Robot -> Template front matter -> Task -> Runtime`. Supports keyword construction, block DSL, merge semantics (more-specific wins), and `apply_to(chat)` for LLM field application. Both Robot and Network accept `config:` parameter. Infrastructure fields include: `bus`, `enable_cache`, `max_tool_rounds`, `token_budget`, `ractor_pool_size`, `max_concurrent_robots`, `doom_loop_threshold`, `auto_compact`, `compact_threshold`.
+
+### Memory System
+
+- **`Memory`** (`lib/robot_lab/memory.rb`): Key-value store with reserved keys (`:data`, `:results`, `:messages`, `:session_id`, `:cache`). Supports Redis backend. Includes semantic caching via RubyLLM::SemanticCache
+
+### MCP (Model Context Protocol)
+
+- **`MCP::Client`** (`lib/robot_lab/mcp/client.rb`): Connects to MCP servers
+- **Transports** (`lib/robot_lab/mcp/transports/`): stdio, websocket, SSE, streamable HTTP
+
+### Built-in Tools
+
+- **`AskUser`** (`lib/robot_lab/ask_user.rb`): Tool that lets a robot ask the user a question via the terminal. Supports open-ended text, multiple choice, and default values. IO sourced from `robot.input`/`robot.output` (defaults to `$stdin`/`$stdout`)
+
+### Adapters
+
+Provider adapters in `lib/robot_lab/adapters/`: Anthropic, OpenAI, Gemini (for provider-specific formatting)
+
+### Configuration Hierarchy
+
+Tools and MCP servers use hierarchical configuration: `runtime > robot > network > global config`. Values can be `:none`, `:inherit`, or explicit arrays.
+
+## Key Patterns
+
+### Creating Robots
+
+```ruby
+# Bare robot (no template or prompt)
+robot = RobotLab.build
+robot.with_instructions("You are helpful.").run("Hello!")
+
+# With template (.md file in prompts directory with YAML front matter)
+robot = RobotLab.build(name: "helper", template: :helper, context: { key: "value" })
+result = robot.run("Hello!")
+
+# With inline system prompt
+robot = RobotLab.build(name: "bot", system_prompt: "You are helpful.")
+result = robot.run("What can you do?")
+
+# With tools
+robot = RobotLab.build(name: "bot", system_prompt: "...", local_tools: [my_tool])
+
+# Chaining with_* methods
+robot.with_temperature(0.9).with_model("claude-sonnet-4").run("Be creative!")
+```
+
+### Creating Networks
+
+```ruby
+router = ->(args) { args.call_count.zero? ? ["classifier"] : nil }
+network = RobotLab.create_network(name: "support", robots: [robot1, robot2], router: router)
+result = network.run(message: "Hello")
+```
+
+### Router Args
+
+Router receives `Router::Args` with: `context`, `network`, `stack`, `call_count`, `last_result`
+
+## Testing
+
+- Uses Minitest with SimpleCov for coverage
+- Test helper at `test/test_helper.rb` provides `build_robot`, `build_network`, `build_tool` helpers
+- Templates for tests are in `examples/prompts/`
+- VCR and WebMock for HTTP stubbing
+
+## Dependencies
+
+Core: zeitwerk, ruby_llm (~> 1.12), ruby_llm-mcp, prompt_manager, ruby_llm-schema, ruby_llm-semantic_cache, async, simple_flow, state_machines
+
+### Templates
+
+Templates use prompt_manager format: single `.md` files with YAML front matter in the configured prompts directory.
+
+```markdown
+---
+description: A helpful assistant
+parameters:
+  company_name: null
+  tone: friendly
+---
+You are a helpful assistant for <%= company_name %>.
+Respond in a <%= tone %> manner.
+```
+
+Front matter supports: `description`, `parameters` (null = required), LLM config keys (`model`, `temperature`, `top_p`, `top_k`, `max_tokens`, etc.), and robot extras (`robot_name`, `tools`, `mcp`). Constructor-provided values always override front matter.

data/README.md

@@ -26,7 +26,7 @@
 - <strong>Message Bus</strong> - Bidirectional robot communication via TypedBus<br>
 - <strong>Dynamic Spawning</strong> - Robots create new robots at runtime<br>
 - <strong>Layered Configuration</strong> - Cascading YAML, env vars, and RunConfig<br>
-- <strong>Rails Integration</strong> - Generators, background jobs, Turbo Stream broadcasting<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>Learning Accumulation</strong> - <code>robot.learn()</code> builds up cross-run observations with deduplication<br>
@@ -93,7 +93,7 @@ robot = RobotLab.build(
 
 ### Configuration
 
-RobotLab uses [MywayConfig](https://github.com/MadBomber/myway_config) for layered configuration. There is no `configure` block. Configuration is loaded automatically from multiple sources in priority order:
+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)
@@ -124,6 +124,14 @@ ruby_llm:
   request_timeout: 180
 ```
 
+Runtime-only attributes (such as the logger) can be set with a `configure` block:
+
+```ruby
+RobotLab.configure do |c|
+  c.logger = Logger.new(File::NULL)   # silence logging
+end
+```
+
 ### Using Templates
 
 For production applications, RobotLab supports a template system built on [PromptManager](https://github.com/MadBomber/prompt_manager). Templates allow you to:
@@ -677,6 +685,67 @@ robot.clear_messages   # flushes broken history; system prompt is kept
 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:
+
+```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
+)
+```
+
+When a doom loop is detected, a warning is embedded directly into the tool result, prompting the LLM to try a different approach. Detection covers both consecutive repetition (`A,A,A`) and cyclic patterns (`A,B,C,A,B,C`). Via `RunConfig`:
+
+```ruby
+config = RobotLab::RunConfig.new(doom_loop_threshold: 3)
+robot  = RobotLab.build(name: "runner", system_prompt: "...", config: config)
+```
+
+## Automatic Context Compaction
+
+`auto_compact` triggers context window compression automatically before each `run()`, preventing context overflow without manual intervention.
+
+```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
+)
+
+# 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
+)
+
+# 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 }
+)
+```
+
+| Value | Behaviour |
+|-------|-----------|
+| `nil` / `:none` | No automatic compaction (default) |
+| `: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)
+```
+
 ## Learning Accumulation
 
 `robot.learn(text)` records a cross-run observation. On each subsequent `run()`, active learnings are automatically prepended to the user message as a `LEARNINGS FROM PREVIOUS RUNS:` block so the LLM can incorporate prior context without needing a persistent chat:
@@ -693,6 +762,17 @@ 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"
+)
+```
+
 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.
 
 ```ruby
@@ -796,101 +876,17 @@ future.robot_name     # => "analyst"
 future.delegated_by   # => "manager"
 ```
 
-## Ractor Parallelism
-
-RobotLab supports true CPU parallelism via Ruby Ractors — isolated execution contexts that bypass the GVL. Two modes are available:
-
-**CPU-bound tools** — mark a tool `ractor_safe true` and RobotLab automatically routes its calls through a global `RactorWorkerPool` instead of running inline:
-
-```ruby
-class TranscribeAudio < RubyLLM::Tool
-  ractor_safe true
-  description "Transcribe an audio file"
-  param :path, type: :string, desc: "Path to audio file"
-
-  def execute(path:)
-    AudioTranscriber.run(path)  # pure computation, no shared mutable state
-  end
-end
-```
-
-**Parallel robot networks** — pass `parallel_mode: :ractor` when creating a network to dispatch independent robots across hardware threads simultaneously:
-
-```ruby
-network = RobotLab.create_network(name: "analysis", parallel_mode: :ractor) do
-  task :fetch,     fetcher_robot,    depends_on: :none
-  task :sentiment, sentiment_robot,  depends_on: [:fetch]
-  task :entities,  entity_robot,     depends_on: [:fetch]   # runs in parallel with sentiment
-  task :summarize, summary_robot,    depends_on: [:sentiment, :entities]
-end
-
-results = network.run(message: "Analyze customer feedback")
-# => { "fetch" => "...", "sentiment" => "positive", "entities" => "...", "summarize" => "..." }
-```
-
-See the [Ractor Parallelism guide](https://madbomber.github.io/robot_lab/guides/ractor-parallelism) for constraints, the frozen-data contract, and `RactorMemoryProxy` for shared state.
-
-## Rails Integration
-
-```bash
-rails generate robot_lab:install
-rails db:migrate
-```
-
-This creates:
-- `config/initializers/robot_lab.rb` - Configuration
-- `app/robots/` - Directory for your robots
-- Database tables for conversation history
-
-### Background Jobs
-
-RobotLab ships with `RobotLab::Job`, an `ActiveJob::Base` subclass that handles the full robot-run lifecycle: robot class resolution, Turbo Stream wiring, thread-record persistence, and completion/error broadcasting.
-
-**Generic job** (robot class supplied at enqueue time):
-
-```bash
-rails generate robot_lab:install   # creates app/jobs/robot_run_job.rb
-```
-
-```ruby
-# app/jobs/robot_run_job.rb  (generated)
-class RobotRunJob < RobotLab::Job
-  queue_as :default
-end
-
-# Enqueue from a controller:
-RobotRunJob.perform_later(
-  robot_class: "SupportRobot",
-  message:     params[:message],
-  thread_id:   session_id
-)
-```
-
-**Dedicated job** (robot class bound at the class level via DSL):
-
-```bash
-rails generate robot_lab:job Support            # binds to SupportRobot, queue: default
-rails generate robot_lab:job Support --queue ai # custom queue
-```
-
-```ruby
-# app/jobs/support_job.rb  (generated)
-class SupportJob < RobotLab::Job
-  queue_as :default
-  robot_class SupportRobot
-end
-
-# Enqueue (no robot_class: needed):
-SupportJob.perform_later(message: params[:message], thread_id: session_id)
-```
-
-When `thread_id` is provided and [turbo-rails](https://github.com/hotwired/turbo-rails) is installed, `RobotLab::Job` automatically:
+## Extension Gems
 
-- Wires `on_content` / `on_tool_call` Turbo Stream callbacks so the UI updates in real time
-- Broadcasts a **completion** event to `"robot_lab_thread_#{thread_id}"` when the run finishes
-- Broadcasts an **error** event (HTML-escaped) if the job raises
+RobotLab's optional capabilities are packaged as separate gems:
 
-Omitting `thread_id` runs the robot in fire-and-forget mode — no persistence, no broadcasting.
+| 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-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 |
 
 ## Documentation
 

data/Rakefile

@@ -44,6 +44,76 @@ 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'
+
+  # 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 "Run all quality checks: tests (with coverage), RuboCop, and Flog"
+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("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 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
   # Map of subdirectory-based demos to their entry point scripts
   SUBDIR_ENTRY_POINTS = {
@@ -58,14 +128,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 +169,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 +185,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])"