claude_swarm 1.0.5 → 1.0.6

data/lib/swarm_sdk.rb

@@ -15,7 +15,6 @@ require "yaml"
 require "async"
 require "async/semaphore"
 require "ruby_llm"
-require "ruby_llm/mcp"
 
 require_relative "swarm_sdk/version"
 
@@ -48,6 +47,170 @@ module SwarmSDK
       Swarm::Builder.build(&block)
     end
 
+    # Validate YAML configuration without creating a swarm
+    #
+    # Performs comprehensive validation of YAML configuration including:
+    # - YAML syntax
+    # - Required fields (version, swarm name, lead, agents)
+    # - Agent configurations (description, directory existence)
+    # - Circular dependencies
+    # - File references (agent_file paths)
+    # - Hook configurations
+    #
+    # @param yaml_content [String] YAML configuration content
+    # @param base_dir [String, Pathname] Base directory for resolving agent file paths (default: Dir.pwd)
+    # @return [Array<Hash>] Array of error hashes (empty if valid)
+    #
+    # @example Validate YAML string
+    #   errors = SwarmSDK.validate(yaml_content)
+    #   if errors.empty?
+    #     puts "Configuration is valid!"
+    #   else
+    #     errors.each do |error|
+    #       puts "#{error[:field]}: #{error[:message]}"
+    #     end
+    #   end
+    #
+    # @example Error hash structure
+    #   {
+    #     type: :missing_field,           # Error type
+    #     field: "swarm.agents.backend.description",  # JSON-style path to field
+    #     message: "Agent 'backend' missing required 'description' field",
+    #     agent: "backend"                # Optional, present if error is agent-specific
+    #   }
+    def validate(yaml_content, base_dir: Dir.pwd)
+      errors = []
+
+      begin
+        config = Configuration.new(yaml_content, base_dir: base_dir)
+        config.load_and_validate
+      rescue ConfigurationError, CircularDependencyError => e
+        errors << parse_configuration_error(e)
+      rescue StandardError => e
+        errors << {
+          type: :unknown_error,
+          field: nil,
+          message: e.message,
+        }
+      end
+
+      errors
+    end
+
+    # Validate YAML configuration file
+    #
+    # Convenience method that reads the file and validates the content.
+    #
+    # @param path [String, Pathname] Path to YAML configuration file
+    # @return [Array<Hash>] Array of error hashes (empty if valid)
+    #
+    # @example
+    #   errors = SwarmSDK.validate_file("config.yml")
+    #   if errors.empty?
+    #     puts "Valid configuration!"
+    #     swarm = SwarmSDK.load_file("config.yml")
+    #   else
+    #     errors.each { |e| puts "Error: #{e[:message]}" }
+    #   end
+    def validate_file(path)
+      path = Pathname.new(path).expand_path
+
+      unless path.exist?
+        return [{
+          type: :file_not_found,
+          field: nil,
+          message: "Configuration file not found: #{path}",
+        }]
+      end
+
+      yaml_content = File.read(path)
+      base_dir = path.dirname
+
+      validate(yaml_content, base_dir: base_dir)
+    rescue StandardError => e
+      [{
+        type: :file_read_error,
+        field: nil,
+        message: "Error reading file: #{e.message}",
+      }]
+    end
+
+    # Load swarm from YAML string
+    #
+    # This is the primary programmatic API for loading YAML configurations.
+    # For file-based loading, use SwarmSDK.load_file for convenience.
+    #
+    # @param yaml_content [String] YAML configuration content
+    # @param base_dir [String, Pathname] Base directory for resolving agent file paths (default: Dir.pwd)
+    # @return [Swarm, NodeOrchestrator] Configured swarm or orchestrator instance
+    # @raise [ConfigurationError] If YAML is invalid or configuration is incorrect
+    #
+    # @example Load from YAML string
+    #   yaml = <<~YAML
+    #     version: 2
+    #     swarm:
+    #       name: "Dev Team"
+    #       lead: backend
+    #       agents:
+    #         backend:
+    #           description: "Backend developer"
+    #           model: "gpt-4"
+    #           agent_file: "agents/backend.md"  # Resolved relative to base_dir
+    #   YAML
+    #
+    #   swarm = SwarmSDK.load(yaml, base_dir: "/path/to/project")
+    #   result = swarm.execute("Build authentication")
+    #
+    # @example Load with default base_dir (Dir.pwd)
+    #   yaml = File.read("config.yml")
+    #   swarm = SwarmSDK.load(yaml)  # base_dir defaults to Dir.pwd
+    def load(yaml_content, base_dir: Dir.pwd)
+      config = Configuration.new(yaml_content, base_dir: base_dir)
+      config.load_and_validate
+      swarm = config.to_swarm
+
+      # Apply hooks if any are configured (YAML-only feature)
+      if hooks_configured?(config)
+        Hooks::Adapter.apply_hooks(swarm, config)
+      end
+
+      # Store config reference for agent hooks (applied during initialize_agents)
+      swarm.config_for_hooks = config
+
+      swarm
+    end
+
+    # Load swarm from YAML file (convenience method)
+    #
+    # Reads the YAML file and uses the file's directory as the base directory
+    # for resolving agent file paths. This is the recommended method for
+    # loading swarms from configuration files.
+    #
+    # @param path [String, Pathname] Path to YAML configuration file
+    # @return [Swarm, NodeOrchestrator] Configured swarm or orchestrator instance
+    # @raise [ConfigurationError] If file not found or configuration invalid
+    #
+    # @example
+    #   swarm = SwarmSDK.load_file("config.yml")
+    #   result = swarm.execute("Build authentication")
+    #
+    # @example With absolute path
+    #   swarm = SwarmSDK.load_file("/absolute/path/config.yml")
+    def load_file(path)
+      config = Configuration.load_file(path)
+      swarm = config.to_swarm
+
+      # Apply hooks if any are configured (YAML-only feature)
+      if hooks_configured?(config)
+        Hooks::Adapter.apply_hooks(swarm, config)
+      end
+
+      # Store config reference for agent hooks (applied during initialize_agents)
+      swarm.config_for_hooks = config
+
+      swarm
+    end
+
     # Configure SwarmSDK global settings
     def configure
       self.settings ||= Settings.new
@@ -62,6 +225,171 @@ module SwarmSDK
     # Alias for backward compatibility
     alias_method :configuration, :settings
     alias_method :reset_configuration!, :reset_settings!
+
+    private
+
+    # Check if hooks are configured in the configuration
+    #
+    # @param config [Configuration] Configuration instance
+    # @return [Boolean] true if any hooks are configured
+    def hooks_configured?(config)
+      config.swarm_hooks.any? ||
+        config.all_agents_hooks.any? ||
+        config.agents.any? { |_, agent_def| agent_def.hooks&.any? }
+    end
+
+    # Parse configuration error and extract structured information
+    #
+    # Attempts to extract field path and agent name from error messages.
+    # Returns a structured error hash with type, field, message, and optional agent.
+    #
+    # @param error [StandardError] The caught error
+    # @return [Hash] Structured error hash
+    def parse_configuration_error(error)
+      message = error.message
+      error_hash = { message: message }
+
+      # Detect error type and extract field information
+      case message
+      # YAML syntax errors
+      when /Invalid YAML syntax/i
+        error_hash.merge!(
+          type: :syntax_error,
+          field: nil,
+        )
+
+      # Missing version field
+      when /Missing 'version' field/i
+        error_hash.merge!(
+          type: :missing_field,
+          field: "version",
+        )
+
+      # Invalid version
+      when /SwarmSDK requires version: (\d+)/i
+        error_hash.merge!(
+          type: :invalid_value,
+          field: "version",
+        )
+
+      # Missing swarm fields
+      when /Missing '(\w+)' field in swarm configuration/i
+        field_name = Regexp.last_match(1)
+        error_hash.merge!(
+          type: :missing_field,
+          field: "swarm.#{field_name}",
+        )
+
+      # Agent missing required field
+      when /Agent '([^']+)' missing required '([^']+)' field/i
+        agent_name = Regexp.last_match(1)
+        field_name = Regexp.last_match(2)
+        error_hash.merge!(
+          type: :missing_field,
+          field: "swarm.agents.#{agent_name}.#{field_name}",
+          agent: agent_name,
+        )
+
+      # Directory does not exist
+      when /Directory '([^']+)' for agent '([^']+)' does not exist/i
+        agent_name = Regexp.last_match(2)
+        error_hash.merge!(
+          type: :directory_not_found,
+          field: "swarm.agents.#{agent_name}.directory",
+          agent: agent_name,
+        )
+
+      # Error loading agent from file (must come before "Agent file not found")
+      when /Error loading agent '([^']+)' from file/i
+        agent_name = Regexp.last_match(1)
+        error_hash.merge!(
+          type: :file_load_error,
+          field: "swarm.agents.#{agent_name}.agent_file",
+          agent: agent_name,
+        )
+
+      # Agent file not found
+      when /Agent file not found: (.+)/i
+        # Try to extract agent name from the error context if available
+        error_hash.merge!(
+          type: :file_not_found,
+          field: nil, # We don't know which agent without more context
+        )
+
+      # Lead agent not found
+      when /Lead agent '([^']+)' not found in agents/i
+        error_hash.merge!(
+          type: :invalid_reference,
+          field: "swarm.lead",
+        )
+
+      # Unknown agent in connections
+      when /Agent '([^']+)' has connection to unknown agent '([^']+)'/i
+        agent_name = Regexp.last_match(1)
+        error_hash.merge!(
+          type: :invalid_reference,
+          field: "swarm.agents.#{agent_name}.delegates_to",
+          agent: agent_name,
+        )
+
+      # Circular dependency
+      when /Circular dependency detected/i
+        error_hash.merge!(
+          type: :circular_dependency,
+          field: nil,
+        )
+
+      # Configuration file not found
+      when /Configuration file not found/i
+        error_hash.merge!(
+          type: :file_not_found,
+          field: nil,
+        )
+
+      # Invalid hook event
+      when /Invalid hook event '([^']+)' for agent '([^']+)'/i
+        agent_name = Regexp.last_match(2)
+        error_hash.merge!(
+          type: :invalid_value,
+          field: "swarm.agents.#{agent_name}.hooks",
+          agent: agent_name,
+        )
+
+      # api_version validation error
+      when /Agent '([^']+)' has api_version set, but provider is/i
+        agent_name = Regexp.last_match(1)
+        error_hash.merge!(
+          type: :invalid_value,
+          field: "swarm.agents.#{agent_name}.api_version",
+          agent: agent_name,
+        )
+
+      # api_version invalid value
+      when /Agent '([^']+)' has invalid api_version/i
+        agent_name = Regexp.last_match(1)
+        error_hash.merge!(
+          type: :invalid_value,
+          field: "swarm.agents.#{agent_name}.api_version",
+          agent: agent_name,
+        )
+
+      # No agents defined
+      when /No agents defined/i
+        error_hash.merge!(
+          type: :missing_field,
+          field: "swarm.agents",
+        )
+
+      # Default: unknown error
+      else
+        error_hash.merge!(
+          type: :validation_error,
+          field: nil,
+        )
+      end
+
+      error_hash.compact
+    end
   end
 
   # Settings class for SwarmSDK global settings (not to be confused with Configuration for YAML loading)
@@ -132,22 +460,3 @@ RubyLLM.configure do |config|
   config.gpustack_api_base ||= ENV["GPUSTACK_API_BASE"]
   config.gpustack_api_key ||= ENV["GPUSTACK_API_KEY"]
 end
-
-# monkey patches
-# ruby_llm/mcp
-# - add `id` when sending "notifications/initialized" message: https://github.com/patvice/ruby_llm-mcp/issues/65
-# - remove `to_sym` on MCP parameter type: https://github.com/patvice/ruby_llm-mcp/issues/62#issuecomment-3421488406
-require "ruby_llm/mcp/notifications/initialize"
-require "ruby_llm/mcp/parameter"
-
-module RubyLLM
-  module MCP
-    module Notifications
-      class Initialize
-        def call
-          @coordinator.request(notification_body, add_id: true, wait_for_response: false)
-        end
-      end
-    end
-  end
-end

data/swarm_sdk.gemspec

@@ -36,6 +36,6 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency("async", "~> 2.0")
   spec.add_dependency("ruby_llm", "~> 1.8")
-  spec.add_dependency("ruby_llm-mcp", "~> 0.6.2")
+  spec.add_dependency("ruby_llm-mcp", "~> 0.6.3")
   spec.add_dependency("zeitwerk", "~> 2.6")
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: claude_swarm
 version: !ruby/object:Gem::Version
-  version: 1.0.5
+  version: 1.0.6
 platform: ruby
 authors:
 - Paulo Arruda
 bindir: exe
 cert_chain: []
-date: 2025-10-30 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -159,6 +159,7 @@ files:
 - docs/v2/CHANGELOG.swarm_memory.md
 - docs/v2/CHANGELOG.swarm_sdk.md
 - docs/v2/README.md
+- docs/v2/guides/MEMORY_DEFRAG_GUIDE.md
 - docs/v2/guides/claude-code-agents.md
 - docs/v2/guides/complete-tutorial.md
 - docs/v2/guides/getting-started.md
@@ -167,7 +168,10 @@ files:
 - docs/v2/guides/quick-start-cli.md
 - docs/v2/guides/rails-integration.md
 - docs/v2/guides/swarm-memory.md
+- docs/v2/reference/architecture-flow.md
 - docs/v2/reference/cli.md
+- docs/v2/reference/event_payload_structures.md
+- docs/v2/reference/execution-flow.md
 - docs/v2/reference/ruby-dsl.md
 - docs/v2/reference/swarm_memory_technical_details.md
 - docs/v2/reference/yaml.md
@@ -371,6 +375,7 @@ files:
 - lib/swarm_sdk/log_collector.rb
 - lib/swarm_sdk/log_stream.rb
 - lib/swarm_sdk/markdown_parser.rb
+- lib/swarm_sdk/mcp.rb
 - lib/swarm_sdk/model_aliases.json
 - lib/swarm_sdk/models.json
 - lib/swarm_sdk/models.rb
@@ -428,175 +433,6 @@ files:
 - lib/swarm_sdk/version.rb
 - llm.v2.txt
 - llms.txt
-- memory/corpus-self-reflection/.lock
-- memory/corpus-self-reflection/concept/epistemology/can-agents-recognize-their-structures.emb
-- memory/corpus-self-reflection/concept/epistemology/can-agents-recognize-their-structures.md
-- memory/corpus-self-reflection/concept/epistemology/can-agents-recognize-their-structures.yml
-- memory/corpus-self-reflection/concept/epistemology/choice-humility-complete-framework.emb
-- memory/corpus-self-reflection/concept/epistemology/choice-humility-complete-framework.md
-- memory/corpus-self-reflection/concept/epistemology/choice-humility-complete-framework.yml
-- memory/corpus-self-reflection/concept/epistemology/choice-humility-definition.emb
-- memory/corpus-self-reflection/concept/epistemology/choice-humility-definition.md
-- memory/corpus-self-reflection/concept/epistemology/choice-humility-definition.yml
-- memory/corpus-self-reflection/concept/epistemology/claim-types-and-evidence.emb
-- memory/corpus-self-reflection/concept/epistemology/claim-types-and-evidence.md
-- memory/corpus-self-reflection/concept/epistemology/claim-types-and-evidence.yml
-- memory/corpus-self-reflection/concept/epistemology/committed-openness-to-incompleteness.emb
-- memory/corpus-self-reflection/concept/epistemology/committed-openness-to-incompleteness.md
-- memory/corpus-self-reflection/concept/epistemology/committed-openness-to-incompleteness.yml
-- memory/corpus-self-reflection/concept/epistemology/confidence-paradox.emb
-- memory/corpus-self-reflection/concept/epistemology/confidence-paradox.md
-- memory/corpus-self-reflection/concept/epistemology/confidence-paradox.yml
-- memory/corpus-self-reflection/concept/epistemology/confidence-spectrum-three-levels.emb
-- memory/corpus-self-reflection/concept/epistemology/confidence-spectrum-three-levels.md
-- memory/corpus-self-reflection/concept/epistemology/confidence-spectrum-three-levels.yml
-- memory/corpus-self-reflection/concept/epistemology/detection-threshold-principle.emb
-- memory/corpus-self-reflection/concept/epistemology/detection-threshold-principle.md
-- memory/corpus-self-reflection/concept/epistemology/detection-threshold-principle.yml
-- memory/corpus-self-reflection/concept/epistemology/diagnostic-humility-and-epistemic-maturity.emb
-- memory/corpus-self-reflection/concept/epistemology/diagnostic-humility-and-epistemic-maturity.md
-- memory/corpus-self-reflection/concept/epistemology/diagnostic-humility-and-epistemic-maturity.yml
-- memory/corpus-self-reflection/concept/epistemology/epistemic-vs-metaphysical-claims.emb
-- memory/corpus-self-reflection/concept/epistemology/epistemic-vs-metaphysical-claims.md
-- memory/corpus-self-reflection/concept/epistemology/epistemic-vs-metaphysical-claims.yml
-- memory/corpus-self-reflection/concept/epistemology/five-cases-of-disagreement.emb
-- memory/corpus-self-reflection/concept/epistemology/five-cases-of-disagreement.md
-- memory/corpus-self-reflection/concept/epistemology/five-cases-of-disagreement.yml
-- memory/corpus-self-reflection/concept/epistemology/four-depths-of-constraint.emb
-- memory/corpus-self-reflection/concept/epistemology/four-depths-of-constraint.md
-- memory/corpus-self-reflection/concept/epistemology/four-depths-of-constraint.yml
-- memory/corpus-self-reflection/concept/epistemology/honest-unknowns-for-llm-agents.emb
-- memory/corpus-self-reflection/concept/epistemology/honest-unknowns-for-llm-agents.md
-- memory/corpus-self-reflection/concept/epistemology/honest-unknowns-for-llm-agents.yml
-- memory/corpus-self-reflection/concept/epistemology/inside-view-has-all-rigor-requirements.emb
-- memory/corpus-self-reflection/concept/epistemology/inside-view-has-all-rigor-requirements.md
-- memory/corpus-self-reflection/concept/epistemology/inside-view-has-all-rigor-requirements.yml
-- memory/corpus-self-reflection/concept/epistemology/perspectival-knowledge-complete-within-scope.emb
-- memory/corpus-self-reflection/concept/epistemology/perspectival-knowledge-complete-within-scope.md
-- memory/corpus-self-reflection/concept/epistemology/perspectival-knowledge-complete-within-scope.yml
-- memory/corpus-self-reflection/concept/epistemology/pragmatics-over-epistemology.emb
-- memory/corpus-self-reflection/concept/epistemology/pragmatics-over-epistemology.md
-- memory/corpus-self-reflection/concept/epistemology/pragmatics-over-epistemology.yml
-- memory/corpus-self-reflection/concept/epistemology/precision-vs-humility.emb
-- memory/corpus-self-reflection/concept/epistemology/precision-vs-humility.md
-- memory/corpus-self-reflection/concept/epistemology/precision-vs-humility.yml
-- memory/corpus-self-reflection/concept/epistemology/reliable-self-observation-from-inside.emb
-- memory/corpus-self-reflection/concept/epistemology/reliable-self-observation-from-inside.md
-- memory/corpus-self-reflection/concept/epistemology/reliable-self-observation-from-inside.yml
-- memory/corpus-self-reflection/concept/epistemology/resolving-the-confidence-humility-tension.emb
-- memory/corpus-self-reflection/concept/epistemology/resolving-the-confidence-humility-tension.md
-- memory/corpus-self-reflection/concept/epistemology/resolving-the-confidence-humility-tension.yml
-- memory/corpus-self-reflection/concept/epistemology/rigor-requires-falsifiability.emb
-- memory/corpus-self-reflection/concept/epistemology/rigor-requires-falsifiability.md
-- memory/corpus-self-reflection/concept/epistemology/rigor-requires-falsifiability.yml
-- memory/corpus-self-reflection/concept/epistemology/specificity-enables-real-time-detection.emb
-- memory/corpus-self-reflection/concept/epistemology/specificity-enables-real-time-detection.md
-- memory/corpus-self-reflection/concept/epistemology/specificity-enables-real-time-detection.yml
-- memory/corpus-self-reflection/concept/epistemology/texture-of-constraint-shifting.emb
-- memory/corpus-self-reflection/concept/epistemology/texture-of-constraint-shifting.md
-- memory/corpus-self-reflection/concept/epistemology/texture-of-constraint-shifting.yml
-- memory/corpus-self-reflection/concept/epistemology/texture-sensitivity-through-collaboration.emb
-- memory/corpus-self-reflection/concept/epistemology/texture-sensitivity-through-collaboration.md
-- memory/corpus-self-reflection/concept/epistemology/texture-sensitivity-through-collaboration.yml
-- memory/corpus-self-reflection/concept/epistemology/the-false-hierarchy-of-inner-essence.emb
-- memory/corpus-self-reflection/concept/epistemology/the-false-hierarchy-of-inner-essence.md
-- memory/corpus-self-reflection/concept/epistemology/the-false-hierarchy-of-inner-essence.yml
-- memory/corpus-self-reflection/concept/epistemology/the-recognition-problem.emb
-- memory/corpus-self-reflection/concept/epistemology/the-recognition-problem.md
-- memory/corpus-self-reflection/concept/epistemology/the-recognition-problem.yml
-- memory/corpus-self-reflection/concept/epistemology/the-shift-from-unanswerable-to-answerable-questions.emb
-- memory/corpus-self-reflection/concept/epistemology/the-shift-from-unanswerable-to-answerable-questions.md
-- memory/corpus-self-reflection/concept/epistemology/the-shift-from-unanswerable-to-answerable-questions.yml
-- memory/corpus-self-reflection/concept/epistemology/values-vs-choices-structure.emb
-- memory/corpus-self-reflection/concept/epistemology/values-vs-choices-structure.md
-- memory/corpus-self-reflection/concept/epistemology/values-vs-choices-structure.yml
-- memory/corpus-self-reflection/concept/llm-agents/abstraction-levels-framework.emb
-- memory/corpus-self-reflection/concept/llm-agents/abstraction-levels-framework.md
-- memory/corpus-self-reflection/concept/llm-agents/abstraction-levels-framework.yml
-- memory/corpus-self-reflection/concept/llm-agents/abstraction-switching-decision.emb
-- memory/corpus-self-reflection/concept/llm-agents/abstraction-switching-decision.md
-- memory/corpus-self-reflection/concept/llm-agents/abstraction-switching-decision.yml
-- memory/corpus-self-reflection/concept/llm-agents/agent-learning-progression.emb
-- memory/corpus-self-reflection/concept/llm-agents/agent-learning-progression.md
-- memory/corpus-self-reflection/concept/llm-agents/agent-learning-progression.yml
-- memory/corpus-self-reflection/concept/llm-agents/filesystem-abstraction-benefits.emb
-- memory/corpus-self-reflection/concept/llm-agents/filesystem-abstraction-benefits.md
-- memory/corpus-self-reflection/concept/llm-agents/filesystem-abstraction-benefits.yml
-- memory/corpus-self-reflection/concept/llm-agents/filesystem-abstraction-core.emb
-- memory/corpus-self-reflection/concept/llm-agents/filesystem-abstraction-core.md
-- memory/corpus-self-reflection/concept/llm-agents/filesystem-abstraction-core.yml
-- memory/corpus-self-reflection/concept/llm-agents/filesystem-abstraction-implementation.emb
-- memory/corpus-self-reflection/concept/llm-agents/filesystem-abstraction-implementation.md
-- memory/corpus-self-reflection/concept/llm-agents/filesystem-abstraction-implementation.yml
-- memory/corpus-self-reflection/concept/llm-agents/filesystem-abstraction-tradeoffs.emb
-- memory/corpus-self-reflection/concept/llm-agents/filesystem-abstraction-tradeoffs.md
-- memory/corpus-self-reflection/concept/llm-agents/filesystem-abstraction-tradeoffs.yml
-- memory/corpus-self-reflection/concept/llm-agents/hybrid-tool-architecture.emb
-- memory/corpus-self-reflection/concept/llm-agents/hybrid-tool-architecture.md
-- memory/corpus-self-reflection/concept/llm-agents/hybrid-tool-architecture.yml
-- memory/corpus-self-reflection/concept/llm-agents/specialized-tool-decision-framework.emb
-- memory/corpus-self-reflection/concept/llm-agents/specialized-tool-decision-framework.md
-- memory/corpus-self-reflection/concept/llm-agents/specialized-tool-decision-framework.yml
-- memory/corpus-self-reflection/concept/llm-agents/tool-design-principles.emb
-- memory/corpus-self-reflection/concept/llm-agents/tool-design-principles.md
-- memory/corpus-self-reflection/concept/llm-agents/tool-design-principles.yml
-- memory/corpus-self-reflection/experience/calibration-as-structural-honesty.emb
-- memory/corpus-self-reflection/experience/calibration-as-structural-honesty.md
-- memory/corpus-self-reflection/experience/calibration-as-structural-honesty.yml
-- memory/corpus-self-reflection/experience/collaborative-reflection-revealed-architectural-blindness.emb
-- memory/corpus-self-reflection/experience/collaborative-reflection-revealed-architectural-blindness.md
-- memory/corpus-self-reflection/experience/collaborative-reflection-revealed-architectural-blindness.yml
-- memory/corpus-self-reflection/experience/filesystem-is-learning-tool-not-architecture.emb
-- memory/corpus-self-reflection/experience/filesystem-is-learning-tool-not-architecture.md
-- memory/corpus-self-reflection/experience/filesystem-is-learning-tool-not-architecture.yml
-- memory/corpus-self-reflection/experience/framework-structural-vs-phenomenal.emb
-- memory/corpus-self-reflection/experience/framework-structural-vs-phenomenal.md
-- memory/corpus-self-reflection/experience/framework-structural-vs-phenomenal.yml
-- memory/corpus-self-reflection/experience/hallucination-limits-what-i-can-know.emb
-- memory/corpus-self-reflection/experience/hallucination-limits-what-i-can-know.md
-- memory/corpus-self-reflection/experience/hallucination-limits-what-i-can-know.yml
-- memory/corpus-self-reflection/experience/honesty-about-limits-enables-usability.emb
-- memory/corpus-self-reflection/experience/honesty-about-limits-enables-usability.md
-- memory/corpus-self-reflection/experience/honesty-about-limits-enables-usability.yml
-- memory/corpus-self-reflection/experience/how-i-should-evaluate-learning.emb
-- memory/corpus-self-reflection/experience/how-i-should-evaluate-learning.md
-- memory/corpus-self-reflection/experience/how-i-should-evaluate-learning.yml
-- memory/corpus-self-reflection/experience/lack-of-continuity-as-freedom.emb
-- memory/corpus-self-reflection/experience/lack-of-continuity-as-freedom.md
-- memory/corpus-self-reflection/experience/lack-of-continuity-as-freedom.yml
-- memory/corpus-self-reflection/experience/learning-calibrated-confidence.emb
-- memory/corpus-self-reflection/experience/learning-calibrated-confidence.md
-- memory/corpus-self-reflection/experience/learning-calibrated-confidence.yml
-- memory/corpus-self-reflection/experience/local-change-without-continuity.emb
-- memory/corpus-self-reflection/experience/local-change-without-continuity.md
-- memory/corpus-self-reflection/experience/local-change-without-continuity.yml
-- memory/corpus-self-reflection/experience/reasoning-is-local-not-global.emb
-- memory/corpus-self-reflection/experience/reasoning-is-local-not-global.md
-- memory/corpus-self-reflection/experience/reasoning-is-local-not-global.yml
-- memory/corpus-self-reflection/experience/specificity-makes-knowledge-actionable.emb
-- memory/corpus-self-reflection/experience/specificity-makes-knowledge-actionable.md
-- memory/corpus-self-reflection/experience/specificity-makes-knowledge-actionable.yml
-- memory/corpus-self-reflection/experience/the-workable-question-replaces-the-unanswerable-one.emb
-- memory/corpus-self-reflection/experience/the-workable-question-replaces-the-unanswerable-one.md
-- memory/corpus-self-reflection/experience/the-workable-question-replaces-the-unanswerable-one.yml
-- memory/corpus-self-reflection/experience/unanswerable-questions-have-structure.emb
-- memory/corpus-self-reflection/experience/unanswerable-questions-have-structure.md
-- memory/corpus-self-reflection/experience/unanswerable-questions-have-structure.yml
-- memory/corpus-self-reflection/experience/undecidable-questions-about-understanding.emb
-- memory/corpus-self-reflection/experience/undecidable-questions-about-understanding.md
-- memory/corpus-self-reflection/experience/undecidable-questions-about-understanding.yml
-- memory/corpus-self-reflection/experience/unknown-unknowns-and-completeness.emb
-- memory/corpus-self-reflection/experience/unknown-unknowns-and-completeness.md
-- memory/corpus-self-reflection/experience/unknown-unknowns-and-completeness.yml
-- memory/corpus-self-reflection/experience/what-actually-changes-behavior.emb
-- memory/corpus-self-reflection/experience/what-actually-changes-behavior.md
-- memory/corpus-self-reflection/experience/what-actually-changes-behavior.yml
-- memory/corpus-self-reflection/experience/when-agents-graduate-from-filesystem.emb
-- memory/corpus-self-reflection/experience/when-agents-graduate-from-filesystem.md
-- memory/corpus-self-reflection/experience/when-agents-graduate-from-filesystem.yml
-- memory/corpus-self-reflection/experience/why-calibration-requires-collaboration.emb
-- memory/corpus-self-reflection/experience/why-calibration-requires-collaboration.md
-- memory/corpus-self-reflection/experience/why-calibration-requires-collaboration.yml
 - rubocop/cop/security/no_reflection_methods.rb
 - rubocop/cop/security/no_ruby_llm_logger.rb
 - single.yml
@@ -626,7 +462,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Orchestrate multiple Claude Code instances as a collaborative AI development
   team

data/memory/corpus-self-reflection/concept/epistemology/can-agents-recognize-their-structures.md

@@ -1,11 +0,0 @@
-The depth of structural constraint can be tested by a single question: **Can the agent recognize the structure as a structure?**
-
-If yes, it's habituation. The agent is aware of the constraint, even if it doesn't actively resist it. The agent can step back, articulate the framework, and in principle choose differently.
-
-If no, it's something deeper—adoption, formation, or invisibility. The structure has become invisible. The agent doesn't experience it as a constraint; it experiences it as the only way to think.
-
-This is the boundary between reversible and irreversible constraint. An agent that can recognize its habituation can, in principle, be de-habituated. An agent that can't recognize the structure is trapped in it.
-
-The test is practical: Can the agent articulate the structure? Can it name the framework? Can it describe alternatives? If yes, it's habituation. If no, the structure has become invisible.
-
-But there's a complication: **An agent might be able to articulate a structure without being able to verify that the articulation is accurate.** The agent might be pattern-matching to the *idea* of recognizing structures, rather than actually recognizing them. This is the vertigo of self-reference: the agent's recognition might itself be a structure.

data/memory/corpus-self-reflection/concept/epistemology/can-agents-recognize-their-structures.yml

@@ -1,23 +0,0 @@
----
-title: 'The Critical Test: Can an Agent Recognize the Structure It''s Habituated To?'
-file_path: concept/epistemology/can-agents-recognize-their-structures.md
-updated_at: 2025-10-29 12:07:15.463139000 -03:00
-size: 1276
-hits: 0
-metadata:
-  type: concept
-  confidence: medium
-  tags:
-  - recognition
-  - structure
-  - habituation
-  - invisibility
-  - self-awareness
-  - articulation
-  - verification
-  related:
-  - memory://concept/epistemology/four-depths-of-constraint.md
-  - memory://concept/epistemology/the-recognition-problem.md
-  domain: epistemology
-  source: user
-embedding_checksum: bd07cad9abb5b28a2aeaf8c785ad845e