minerva-sky · Oct 19, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,7 @@
 ## [Unreleased]
 
 ### Fixed
+- Every file under `lib/agentic/` now loads through Zeitwerk alone: the 57 `require_relative` lines between loader-managed files are gone, and `spec/zeitwerk_spec.rb` eager-loads the gem in a fresh process and fails on any `require_relative` that comes back
 - Test suite loads on Ruby 4.0: `benchmark` is a bundled (not default) gem there, so it is now declared in the Gemfile
 - `EventDispatcher` slow-observer spec uses a monotonic clock and a looser bound so it no longer flakes on loaded hosts
 

diff --git a/lib/agentic/artifact_generator.rb b/lib/agentic/artifact_generator.rb
@@ -1,10 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "artifact"
-require_relative "artifact_generation_result"
-require_relative "workspace"
-require_relative "capabilities/file_generation_capability"
-
 module Agentic
   # Coordinates artifact generation using LLM agents
   #

diff --git a/lib/agentic/capabilities/file_generation_capability.rb b/lib/agentic/capabilities/file_generation_capability.rb
@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "../artifact"
-require_relative "../workspace"
 require "json"
 
 module Agentic

diff --git a/lib/agentic/capabilities/register_file_generation.rb b/lib/agentic/capabilities/register_file_generation.rb
@@ -1,10 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "file_generation_capability"
-require_relative "../capability_specification"
-require_relative "../capability_provider"
-require_relative "../agent_capability_registry"
-
 module Agentic
   module Capabilities
     # Register the file_generation capability with the registry

diff --git a/lib/agentic/cli/execution_observer.rb b/lib/agentic/cli/execution_observer.rb
@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "progress_tracker"
-
 module Agentic
   class CLI < Thor
     # Observer that provides real-time feedback during plan execution

diff --git a/lib/agentic/cli/human_intervention_commands.rb b/lib/agentic/cli/human_intervention_commands.rb
@@ -3,7 +3,6 @@
 require "thor"
 require "json"
 require "yaml"
-require_relative "../human_intervention/portal"
 
 module Agentic
   class CLI

diff --git a/lib/agentic/cli/streaming/enhanced_progress_tracker.rb b/lib/agentic/cli/streaming/enhanced_progress_tracker.rb
@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "multi_zone_display"
-
 module Agentic
   class CLI < Thor
     module Streaming

diff --git a/lib/agentic/cli/streaming/multi_zone_display.rb b/lib/agentic/cli/streaming/multi_zone_display.rb
@@ -3,8 +3,6 @@
 require "tty-box"
 require "tty-cursor"
 require "tty-screen"
-require_relative "streaming_zone"
-require_relative "progress_zone"
 
 module Agentic
   class CLI < Thor

diff --git a/lib/agentic/configuration.rb b/lib/agentic/configuration.rb
@@ -1,10 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "configuration/schema"
-require_relative "configuration/schema_registry"
-require_relative "configuration/schemas"
-require_relative "configuration/builder"
-
 module Agentic
   # Unified configuration system with schema validation and type checking
   #

diff --git a/lib/agentic/configuration/builder.rb b/lib/agentic/configuration/builder.rb
@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "schemas"
-
 module Agentic
   module Configuration
     # Configuration builder with fluent interface and validation

diff --git a/lib/agentic/configuration/schema_registry.rb b/lib/agentic/configuration/schema_registry.rb
@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "schema"
-
 module Agentic
   module Configuration
     # Central registry for managing configuration schemas

diff --git a/lib/agentic/configuration/schemas.rb b/lib/agentic/configuration/schemas.rb
@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "schema"
-require_relative "schema_registry"
-
 module Agentic
   module Configuration
     # Pre-defined schemas for core Agentic configuration objects

diff --git a/lib/agentic/human_intervention/portal.rb b/lib/agentic/human_intervention/portal.rb
@@ -3,9 +3,6 @@
 require "json"
 require "securerandom"
 require "monitor"
-require_relative "workflow_manager"
-require_relative "monitoring_system"
-require_relative "authentication_system"
 
 module Agentic
   module HumanIntervention

diff --git a/lib/agentic/observability/adapter_factory.rb b/lib/agentic/observability/adapter_factory.rb
@@ -1,9 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base_adapter"
-require_relative "console_adapter"
-require_relative "file_adapter"
-
 module Agentic
   module Observability
     # Factory for creating observability adapters

diff --git a/lib/agentic/observability/console_adapter.rb b/lib/agentic/observability/console_adapter.rb
@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base_adapter"
-
 module Agentic
   module Observability
     # Console adapter for outputting events to STDOUT/STDERR

diff --git a/lib/agentic/observability/event_dispatcher.rb b/lib/agentic/observability/event_dispatcher.rb
@@ -2,8 +2,6 @@
 
 require "async"
 require "async/queue"
-require_relative "event_pipeline"
-require_relative "event_context"
 
 module Agentic
   module Observability

diff --git a/lib/agentic/observability/file_adapter.rb b/lib/agentic/observability/file_adapter.rb
@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base_adapter"
-require_relative "file_observer"
-
 module Agentic
   module Observability
     # File adapter for logging events to local files

diff --git a/lib/agentic/observability_engine.rb b/lib/agentic/observability_engine.rb
@@ -3,10 +3,6 @@
 require "set"
 require "json"
 require "async"
-require_relative "observability/event_data"
-require_relative "observability/file_observer"
-require_relative "observability/adapter_factory"
-require_relative "observability/event_dispatcher"
 
 module Agentic
   # Unified observability engine for all event coordination

diff --git a/lib/agentic/performance.rb b/lib/agentic/performance.rb
@@ -1,9 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "performance/cache"
-require_relative "performance/cache_manager"
-require_relative "performance/optimizer"
-
 module Agentic
   # Performance optimization framework for the Agentic system
   #

diff --git a/lib/agentic/performance/cache_manager.rb b/lib/agentic/performance/cache_manager.rb
@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "cache"
-
 module Agentic
   module Performance
     # Cache manager for coordinating multiple cache instances and strategies

diff --git a/lib/agentic/performance/optimizer.rb b/lib/agentic/performance/optimizer.rb
@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "cache_manager"
-
 module Agentic
   module Performance
     # Performance optimization framework with caching, pooling, and monitoring

diff --git a/lib/agentic/security.rb b/lib/agentic/security.rb
@@ -1,9 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "security/sanitizer"
-require_relative "security/config"
-require_relative "security/secure_error_mixin"
-
 module Agentic
   # Security module providing comprehensive PII sanitization and secure error handling
   #

diff --git a/lib/agentic/security/secure_error_mixin.rb b/lib/agentic/security/secure_error_mixin.rb
@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "config"
-
 module Agentic
   module Security
     # Mixin to add security-aware error handling to existing error classes

diff --git a/lib/agentic/verification/strategy_factory.rb b/lib/agentic/verification/strategy_factory.rb
@@ -1,9 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "verification_strategy"
-require_relative "llm_verification_strategy"
-require_relative "schema_verification_strategy"
-
 module Agentic
   module Verification
     # Factory for creating verification strategies with consistent configuration

diff --git a/lib/agentic/verification/verification_helpers.rb b/lib/agentic/verification/verification_helpers.rb
@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "strategy_factory"
-require_relative "verification_hub"
-
 module Agentic
   module Verification
     # Helper methods for setting up verification using standardized patterns

diff --git a/lib/agentic/verification/verification_hub.rb b/lib/agentic/verification/verification_hub.rb
@@ -42,7 +42,6 @@ def add_strategy(strategy)
       # @param dependencies [Hash] Strategy dependencies
       # @return [void]
       def add_strategy_from_factory(type, config: {}, **dependencies)
-        require_relative "strategy_factory"
         strategy = StrategyFactory.create(type, config: config, **dependencies)
         add_strategy(strategy)
       end

diff --git a/lib/agentic/workspace.rb b/lib/agentic/workspace.rb
@@ -2,10 +2,6 @@
 
 require "securerandom"
 require "fileutils"
-require_relative "artifact"
-require_relative "artifact_graph"
-require_relative "observable"
-require_relative "verification/artifact_verification_strategy"
 
 module Agentic
   # Manages an isolated workspace for artifact generation

diff --git a/spec/zeitwerk_spec.rb b/spec/zeitwerk_spec.rb
@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "open3"
+
+# Loader contract check. lib/agentic.rb makes Zeitwerk the single code loader
+# and tells files not to require_relative their siblings. Zeitwerk tolerates
+# a managed file being required directly, so a stray require never crashes;
+# it only hand-maintains a load-order edge the loader already owns, which is
+# how the rule came back 57 lines strong with no red build. The first example
+# tests the promise behind the rule, the second tests the rule.
+RSpec.describe "Zeitwerk loader" do
+  let(:lib_dir) { File.expand_path("../lib", __dir__) }
+
+  # A fresh interpreter, so no constant is already loaded by spec_helper and
+  # nothing in this process's state can hide a file that only loads because
+  # another file was required first. force: true also walks lib/agentic/cli,
+  # which the loader excludes from normal eager loading.
+  it "eager-loads every constant under lib/agentic/ in a fresh process" do
+    script = <<~RUBY
+      require "agentic"
+      loader = Zeitwerk::Registry.loaders.find { |l| l.tag == "agentic" }
+      abort "no Zeitwerk loader tagged agentic (did the gem name change?)" unless loader
+      loader.eager_load(force: true)
+      print Agentic::CLI.name
+    RUBY
+
+    out, err, status = Open3.capture3(RbConfig.ruby, "-W0", "-I", lib_dir, "-e", script)
+
+    expect(status).to be_success, "eager load failed:\n#{err}"
+    expect(out).to eq("Agentic::CLI")
+  end
+
+  it "manages every file under lib/agentic/ without require_relative" do
+    offenders = Dir[File.join(lib_dir, "agentic", "**", "*.rb")].sort.flat_map do |file|
+      File.foreach(file).with_index(1).filter_map do |line, number|
+        "#{file.delete_prefix("#{lib_dir}/")}:#{number}: #{line.strip}" if line.match?(/\A\s*require_relative\b/)
+      end
+    end
+
+    expect(offenders).to be_empty,
+      "require_relative between loader-managed files (reference the constant instead):\n  #{offenders.join("\n  ")}"
+  end
+end