lex-cognitive-labyrinth 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8e80874f5d806cabd4e0b5a3873fc35e6ceffda2e32268105fd2ae694fcdc3d0
+  data.tar.gz: ac099ce9a1c5365b456d09933fb5d09183ac4526ac0b362c7bd2972b1cca7117
+SHA512:
+  metadata.gz: 2662fd410758e942642ee4a9aeac9d01c1d2512706c6aac86442ed7a11e000a443fa6bcc780c838dc17fb66c2fe48f38d0b898e3c34f6c18bc14078940b7d83c
+  data.tar.gz: c4c1114b70ba860416567281e4123193d7194f4edad034feb42c127015907bf5f795d51b8a96dfbdfd532279e4fd749b65fad3c410ef170fbf2dbce1fa8fe288

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.gem
+.rspec_status
+Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,64 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/LineLength:
+  Max: 160
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: space
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/ModuleLength:
+  Max: 150
+
+Metrics/BlockLength:
+  Max: 40
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 17
+
+Metrics/ParameterLists:
+  Max: 8
+  MaxOptionalParameters: 8
+
+Style/Documentation:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: true
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Style/OneClassPerFile:
+  Exclude:
+    - 'spec/spec_helper.rb'
+
+Naming/FileName:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false

data/CLAUDE.md

@@ -0,0 +1,129 @@
+# lex-cognitive-labyrinth
+
+**Level 3 Leaf Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+
+## Purpose
+
+Maze-like problem space navigation engine. Models a cognitive labyrinth as a directed graph of typed nodes (corridors, junctions, dead ends, entrances, exits, minotaur lairs). The agent explores by moving between nodes, dropping breadcrumbs for backtracking, following Ariadne's thread toward the exit, and encountering the Minotaur (dangerous misconceptions) at specially typed nodes.
+
+## Gem Info
+
+- **Gem name**: `lex-cognitive-labyrinth`
+- **Module**: `Legion::Extensions::CognitiveLabyrinth`
+- **Version**: `0.1.0`
+- **Ruby**: `>= 3.4`
+- **License**: MIT
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_labyrinth/
+  version.rb
+  client.rb
+  helpers/
+    constants.rb
+    node.rb
+    labyrinth.rb
+    labyrinth_engine.rb
+  runners/
+    cognitive_labyrinth.rb
+  actors/
+    thread_walker.rb
+```
+
+## Key Constants
+
+| Constant | Value | Purpose |
+|---|---|---|
+| `NODE_TYPES` | `%i[corridor junction dead_end entrance exit minotaur_lair]` | Valid node type values |
+| `MAX_LABYRINTHS` | `20` | Per-engine labyrinth capacity |
+| `MAX_NODES` | `200` | Per-engine node capacity |
+| `DEFAULT_DANGER_LEVEL` | `0.0` | Starting danger for non-minotaur nodes |
+| `MINOTAUR_DANGER_LEVEL` | `0.9` | Danger applied to `minotaur_lair` nodes |
+| `DEAD_END_COMPLEXITY_HIT` | `0.1` | Complexity added when entering a dead end |
+| `COMPLEXITY_LABELS` | range hash | Labels from `:trivial` to `:impossible` |
+| `DANGER_LABELS` | range hash | Labels from `:safe` to `:lethal` |
+
+## Helpers
+
+### `Helpers::Node`
+Graph node with `id`, `label`, `node_type`, `connections` (array of neighbor IDs), and `danger_level`.
+
+- `connect!(other_node_id)` — adds neighbor (idempotent)
+- `disconnect!(other_node_id)` — removes neighbor
+- `dead_end?` — true if `node_type == :dead_end`
+- `junction?` — true if `node_type == :junction`
+- `dangerous?` — true if `danger_level > 0.5`
+- `to_h` — serializes to hash
+
+### `Helpers::Labyrinth`
+Single labyrinth instance. Holds nodes hash, current position, breadcrumb trail, and Ariadne's thread.
+
+- `add_node(node)` — registers node
+- `move_to!(node_id)` — changes current position, drops breadcrumb, increments dead-end complexity
+- `backtrack!` — pops breadcrumb stack to return to previous node
+- `drop_breadcrumb` — records current position in trail
+- `follow_thread` — returns path toward exit node (thread set on entrance)
+- `solved?` — current node is the exit
+- `lost?` — no breadcrumbs and not at entrance
+- `path_length` — breadcrumb count
+- `complexity` / `complexity_label`
+- `to_h`
+
+### `Helpers::LabyrinthEngine`
+Top-level in-memory store. Enforces `MAX_LABYRINTHS` and `MAX_NODES`.
+
+- `create_labyrinth(name:)` → labyrinth or `{error: :capacity_exceeded}`
+- `add_node_to(labyrinth_id:, label:, node_type:, danger_level:)` → node or error
+- `connect_nodes(labyrinth_id:, from_id:, to_id:)` → status hash
+- `move(labyrinth_id:, node_id:)` → position hash
+- `backtrack(labyrinth_id:)` → position hash or `:at_entrance`
+- `follow_thread(labyrinth_id:)` → thread path
+- `check_minotaur(labyrinth_id:)` → danger result for current node
+- `labyrinth_report(labyrinth_id:)` → full status hash
+- `list_labyrinths` → array of labyrinth summaries
+- `delete_labyrinth(labyrinth_id:)` → boolean
+
+## Runners
+
+Module: `Runners::CognitiveLaby rinth` (included via `Client`)
+
+| Runner Method | Description |
+|---|---|
+| `create_labyrinth(name:)` | Create a new labyrinth |
+| `add_node(labyrinth_id:, label:, node_type:, danger_level:)` | Add a node |
+| `connect_nodes(labyrinth_id:, from_id:, to_id:)` | Connect two nodes |
+| `move(labyrinth_id:, node_id:)` | Move current position |
+| `backtrack(labyrinth_id:)` | Backtrack along breadcrumbs |
+| `follow_thread(labyrinth_id:)` | Follow Ariadne's thread toward exit |
+| `check_minotaur(labyrinth_id:)` | Check danger at current node |
+| `labyrinth_report(labyrinth_id:)` | Full labyrinth state |
+| `list_labyrinths` | All labyrinths summary |
+| `delete_labyrinth(labyrinth_id:)` | Remove labyrinth |
+
+All runners return `{success: true/false, ...}` hashes.
+
+## Actors
+
+### `Actors::ThreadWalker`
+- Subclass of `Legion::Extensions::Actors::Every`
+- Interval: `600` seconds
+- Calls `Runners::CognitiveLaby rinth#list_labyrinths`
+- `run_now? = false`, `use_runner? = false`
+- Passive periodic survey of all open labyrinths
+
+## Integration Points
+
+- No direct dependencies on other agentic LEX gems
+- Can integrate with `lex-tick` via `action_selection` phase handler to gate actions when the agent is "lost" in a problem space
+- Works alongside `lex-memory` for persisting explored paths as semantic traces
+- Minotaur encounters (high danger) can feed into `lex-emotion` arousal signal
+
+## Development Notes
+
+- `Client` instantiates `@labyrinth_engine = Helpers::LabyrinthEngine.new` — all state is per-client-instance
+- Ariadne's thread is set at entrance node creation and points toward the exit node ID
+- `backtrack!` returns `:at_entrance` when the breadcrumb stack is empty
+- Node connections are directed (one-way unless connected in both directions)
+- `MAX_LABYRINTHS` and `MAX_NODES` are enforced at engine level; runners receive error hashes on overflow

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :test do
+  gem 'rspec', '~> 3.13'
+  gem 'rubocop', '~> 1.75', require: false
+  gem 'rubocop-rspec', require: false
+end
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/README.md

@@ -0,0 +1,56 @@
+# lex-cognitive-labyrinth
+
+Maze-like problem space navigation for LegionIO cognitive agents. Models complex reasoning challenges as labyrinths with typed nodes, directional connections, breadcrumb backtracking, and Ariadne's thread guidance toward the exit.
+
+## What It Does
+
+- Creates named labyrinths as directed graphs of cognitive nodes
+- Node types: `corridor`, `junction`, `dead_end`, `entrance`, `exit`, `minotaur_lair`
+- Navigation: move to nodes, drop breadcrumbs, backtrack along the crumb trail
+- Ariadne's thread: pre-computed guidance path toward the exit node
+- Minotaur detection: checks danger level at current position (minotaur lairs default to 0.9 danger)
+- Complexity tracking: increases when entering dead ends
+- Periodic survey via `ThreadWalker` actor (every 600s)
+
+## Usage
+
+```ruby
+# Create a labyrinth
+result = runner.create_labyrinth(name: 'problem_analysis')
+labyrinth_id = result[:labyrinth][:id]
+
+# Add nodes
+entrance = runner.add_node(labyrinth_id: labyrinth_id, label: 'start', node_type: :entrance, danger_level: 0.0)
+junction = runner.add_node(labyrinth_id: labyrinth_id, label: 'fork', node_type: :junction, danger_level: 0.0)
+danger   = runner.add_node(labyrinth_id: labyrinth_id, label: 'false assumption', node_type: :minotaur_lair, danger_level: 0.9)
+exit_n   = runner.add_node(labyrinth_id: labyrinth_id, label: 'solution', node_type: :exit, danger_level: 0.0)
+
+# Connect and navigate
+runner.connect_nodes(labyrinth_id: labyrinth_id, from_id: entrance[:node][:id], to_id: junction[:node][:id])
+runner.move(labyrinth_id: labyrinth_id, node_id: junction[:node][:id])
+
+# Check for danger
+runner.check_minotaur(labyrinth_id: labyrinth_id)
+# => { success: true, danger_level: 0.0, dangerous: false, ... }
+
+# Backtrack if stuck
+runner.backtrack(labyrinth_id: labyrinth_id)
+
+# Follow the thread toward exit
+runner.follow_thread(labyrinth_id: labyrinth_id)
+
+# Full status
+runner.labyrinth_report(labyrinth_id: labyrinth_id)
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-labyrinth.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_labyrinth/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-labyrinth'
+  spec.version       = Legion::Extensions::CognitiveLabyrinth::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Labyrinth'
+  spec.description   = 'Maze-like problem spaces for agentic reasoning — paths, dead ends, backtracking, ' \
+                       'breadcrumb trails, Ariadne\'s thread (guiding heuristic), and Minotaur encounters ' \
+                       '(dangerous misconceptions)'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-labyrinth'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']        = spec.homepage
+  spec.metadata['source_code_uri']     = 'https://github.com/LegionIO/lex-cognitive-labyrinth'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-cognitive-labyrinth'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-cognitive-labyrinth'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-cognitive-labyrinth/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/cognitive_labyrinth/actors/thread_walker.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module CognitiveLabyrinth
+      module Actor
+        class ThreadWalker < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::CognitiveLabyrinth::Runners::CognitiveLabyrinth
+          end
+
+          def runner_function
+            'list_labyrinths'
+          end
+
+          def time
+            600
+          end
+
+          def run_now?
+            false
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_labyrinth/client.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLabyrinth
+      class Client
+        include Runners::CognitiveLabyrinth
+
+        def initialize(**)
+          @labyrinth_engine = Helpers::LabyrinthEngine.new
+        end
+
+        private
+
+        attr_reader :labyrinth_engine
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_labyrinth/helpers/constants.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLabyrinth
+      module Helpers
+        module Constants
+          NODE_TYPES = %i[corridor junction dead_end entrance exit minotaur_lair].freeze
+
+          MAX_LABYRINTHS = 20
+          MAX_NODES      = 200
+
+          COMPLEXITY_LABELS = {
+            (0.0...0.2) => :trivial,
+            (0.2...0.4) => :simple,
+            (0.4...0.6) => :moderate,
+            (0.6...0.8) => :complex,
+            (0.8..1.0)  => :labyrinthine
+          }.freeze
+
+          DANGER_LABELS = {
+            (0.0...0.25) => :safe,
+            (0.25...0.5) => :uncertain,
+            (0.5...0.75) => :hazardous,
+            (0.75..1.0)  => :lethal
+          }.freeze
+
+          DEFAULT_DANGER_LEVEL    = 0.0
+          MINOTAUR_DANGER_LEVEL   = 0.9
+          DEAD_END_COMPLEXITY_HIT = 0.1
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_labyrinth/helpers/labyrinth.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLabyrinth
+      module Helpers
+        class Labyrinth
+          attr_reader :labyrinth_id, :name, :domain, :nodes, :breadcrumbs, :current_node_id
+          attr_accessor :solved
+
+          def initialize(labyrinth_id:, name:, domain: nil)
+            @labyrinth_id   = labyrinth_id
+            @name           = name
+            @domain         = domain
+            @nodes          = {}
+            @breadcrumbs    = []
+            @current_node_id = nil
+            @solved          = false
+          end
+
+          def add_node(node)
+            raise ArgumentError, "nodes must be a #{Node}" unless node.is_a?(Node)
+            raise ArgumentError, "max nodes (#{Constants::MAX_NODES}) reached" if @nodes.size >= Constants::MAX_NODES
+
+            @nodes[node.node_id] = node
+            @current_node_id ||= node.node_id if node.node_type == :entrance
+            node
+          end
+
+          def move_to!(node_id)
+            node = @nodes.fetch(node_id) { raise ArgumentError, "node #{node_id.inspect} not found in labyrinth" }
+
+            current = current_node
+            unless current.nil? || current.connections.include?(node_id)
+              raise ArgumentError, "cannot move to #{node_id.inspect}: not connected from current node #{@current_node_id.inspect}"
+            end
+
+            drop_breadcrumb
+            node.visited = true
+            @current_node_id = node_id
+            @solved = true if node.node_type == :exit
+            node
+          end
+
+          def backtrack!
+            return nil if @breadcrumbs.empty?
+
+            target_id = @breadcrumbs.pop
+            @current_node_id = target_id
+            current_node
+          end
+
+          def drop_breadcrumb
+            return unless @current_node_id
+
+            current = @nodes[@current_node_id]
+            current.visited = true if current
+            @breadcrumbs << @current_node_id if @breadcrumbs.last != @current_node_id
+          end
+
+          def follow_thread
+            return nil if current_node.nil?
+
+            unvisited = current_node.connections.find do |conn_id|
+              node = @nodes[conn_id]
+              node && !node.visited
+            end
+
+            return nil unless unvisited
+
+            move_to!(unvisited)
+          end
+
+          def solved?
+            @solved
+          end
+
+          def lost?
+            return false if @current_node_id.nil?
+            return false if solved?
+
+            current = current_node
+            return true if current.nil?
+
+            unvisited_exits = current.connections.any? do |conn_id|
+              node = @nodes[conn_id]
+              node && !node.visited
+            end
+
+            !unvisited_exits && !current.dead_end? && @breadcrumbs.empty?
+          end
+
+          def path_length
+            @breadcrumbs.size
+          end
+
+          def current_node
+            @nodes[@current_node_id]
+          end
+
+          def complexity
+            return 0.0 if @nodes.empty?
+
+            dead_end_count  = @nodes.values.count(&:dead_end?)
+            junction_count  = @nodes.values.count(&:junction?)
+            minotaur_count  = @nodes.values.count { |n| n.node_type == :minotaur_lair }
+
+            raw = ((dead_end_count * 0.3) + (junction_count * 0.2) + (minotaur_count * 0.5)) / @nodes.size.to_f
+            raw.clamp(0.0, 1.0).round(10)
+          end
+
+          def complexity_label
+            score = complexity
+            Constants::COMPLEXITY_LABELS.find { |range, _| range.cover?(score) }&.last || :labyrinthine
+          end
+
+          def to_h
+            {
+              labyrinth_id:     @labyrinth_id,
+              name:             @name,
+              domain:           @domain,
+              node_count:       @nodes.size,
+              current_node_id:  @current_node_id,
+              path_length:      path_length,
+              solved:           @solved,
+              complexity:       complexity,
+              complexity_label: complexity_label
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_labyrinth/helpers/labyrinth_engine.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLabyrinth
+      module Helpers
+        class LabyrinthEngine
+          attr_reader :labyrinths
+
+          def initialize
+            @labyrinths = {}
+          end
+
+          def create_labyrinth(name:, domain: nil, labyrinth_id: nil)
+            raise ArgumentError, "max labyrinths (#{Constants::MAX_LABYRINTHS}) reached" if @labyrinths.size >= Constants::MAX_LABYRINTHS
+
+            id = labyrinth_id || SecureRandom.uuid
+            labyrinth = Labyrinth.new(labyrinth_id: id, name: name, domain: domain)
+            @labyrinths[id] = labyrinth
+            Legion::Logging.debug "[cognitive_labyrinth] created labyrinth id=#{id[0..7]} name=#{name}"
+            labyrinth
+          end
+
+          def add_node_to(labyrinth_id:, node_type:, content: nil, danger_level: nil, node_id: nil)
+            labyrinth = fetch_labyrinth!(labyrinth_id)
+            id        = node_id || SecureRandom.uuid
+            level     = (danger_level || default_danger_for(node_type)).clamp(0.0, 1.0)
+
+            node = Node.new(node_id: id, node_type: node_type, content: content, danger_level: level)
+            labyrinth.add_node(node)
+            Legion::Logging.debug "[cognitive_labyrinth] added node #{id[0..7]} type=#{node_type} to labyrinth #{labyrinth_id[0..7]}"
+            node
+          end
+
+          def connect_nodes(labyrinth_id:, from_id:, to_id:, bidirectional: true)
+            labyrinth  = fetch_labyrinth!(labyrinth_id)
+            from_node  = fetch_node!(labyrinth, from_id)
+            to_node    = fetch_node!(labyrinth, to_id)
+
+            from_node.connect!(to_id)
+            to_node.connect!(from_id) if bidirectional
+            { connected: true, from: from_id, to: to_id, bidirectional: bidirectional }
+          end
+
+          def move(labyrinth_id:, node_id:, **)
+            labyrinth = fetch_labyrinth!(labyrinth_id)
+            node      = labyrinth.move_to!(node_id)
+
+            minotaur_result = check_minotaur(labyrinth_id: labyrinth_id)
+            Legion::Logging.debug "[cognitive_labyrinth] moved to #{node_id[0..7]} type=#{node.node_type}"
+
+            {
+              success:      true,
+              node_id:      node.node_id,
+              node_type:    node.node_type,
+              content:      node.content,
+              danger_level: node.danger_level,
+              solved:       labyrinth.solved?,
+              minotaur:     minotaur_result,
+              path_length:  labyrinth.path_length
+            }
+          end
+
+          def backtrack(labyrinth_id:, **)
+            labyrinth = fetch_labyrinth!(labyrinth_id)
+            node      = labyrinth.backtrack!
+
+            if node
+              Legion::Logging.debug "[cognitive_labyrinth] backtracked to #{node.node_id[0..7]}"
+              { success: true, node_id: node.node_id, node_type: node.node_type, path_length: labyrinth.path_length }
+            else
+              Legion::Logging.debug '[cognitive_labyrinth] backtrack failed: no breadcrumbs'
+              { success: false, reason: :no_breadcrumbs }
+            end
+          end
+
+          def follow_thread(labyrinth_id:, **)
+            labyrinth = fetch_labyrinth!(labyrinth_id)
+            node      = labyrinth.follow_thread
+
+            if node
+              minotaur_result = check_minotaur(labyrinth_id: labyrinth_id)
+              Legion::Logging.debug "[cognitive_labyrinth] thread followed to #{node.node_id[0..7]}"
+              {
+                success:      true,
+                node_id:      node.node_id,
+                node_type:    node.node_type,
+                content:      node.content,
+                danger_level: node.danger_level,
+                solved:       labyrinth.solved?,
+                minotaur:     minotaur_result
+              }
+            else
+              Legion::Logging.debug '[cognitive_labyrinth] thread exhausted: no unvisited nodes from current'
+              { success: false, reason: :thread_exhausted }
+            end
+          end
+
+          def check_minotaur(labyrinth_id:, **)
+            labyrinth = fetch_labyrinth!(labyrinth_id)
+            node      = labyrinth.current_node
+            return { encountered: false } unless node
+
+            if node.node_type == :minotaur_lair
+              Legion::Logging.debug "[cognitive_labyrinth] MINOTAUR ENCOUNTERED at #{node.node_id[0..7]}"
+              {
+                encountered:   true,
+                node_id:       node.node_id,
+                danger_level:  node.danger_level,
+                danger_label:  danger_label_for(node.danger_level),
+                misconception: node.content
+              }
+            elsif node.dangerous?
+              {
+                encountered:  false,
+                warning:      true,
+                danger_level: node.danger_level,
+                danger_label: danger_label_for(node.danger_level)
+              }
+            else
+              { encountered: false }
+            end
+          end
+
+          def labyrinth_report(labyrinth_id:, **)
+            labyrinth = fetch_labyrinth!(labyrinth_id)
+            nodes_by_type = labyrinth.nodes.values.group_by(&:node_type).transform_values(&:count)
+
+            labyrinth.to_h.merge(
+              nodes_by_type:    nodes_by_type,
+              visited_count:    labyrinth.nodes.values.count(&:visited),
+              breadcrumb_trail: labyrinth.breadcrumbs.dup,
+              lost:             labyrinth.lost?
+            )
+          end
+
+          def list_labyrinths(**)
+            @labyrinths.values.map(&:to_h)
+          end
+
+          def delete_labyrinth(labyrinth_id:, **)
+            raise ArgumentError, "labyrinth #{labyrinth_id.inspect} not found" unless @labyrinths.key?(labyrinth_id)
+
+            @labyrinths.delete(labyrinth_id)
+            { deleted: true, labyrinth_id: labyrinth_id }
+          end
+
+          private
+
+          def fetch_labyrinth!(labyrinth_id)
+            @labyrinths.fetch(labyrinth_id) do
+              raise ArgumentError, "labyrinth #{labyrinth_id.inspect} not found"
+            end
+          end
+
+          def fetch_node!(labyrinth, node_id)
+            labyrinth.nodes.fetch(node_id) do
+              raise ArgumentError, "node #{node_id.inspect} not found in labyrinth #{labyrinth.labyrinth_id.inspect}"
+            end
+          end
+
+          def default_danger_for(node_type)
+            node_type == :minotaur_lair ? Constants::MINOTAUR_DANGER_LEVEL : Constants::DEFAULT_DANGER_LEVEL
+          end
+
+          def danger_label_for(level)
+            Constants::DANGER_LABELS.find { |range, _| range.cover?(level) }&.last || :lethal
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_labyrinth/helpers/node.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLabyrinth
+      module Helpers
+        class Node
+          attr_reader   :node_id, :node_type, :content, :connections, :danger_level
+          attr_accessor :visited
+
+          def initialize(node_id:, node_type:, content: nil, danger_level: Constants::DEFAULT_DANGER_LEVEL)
+            unless Constants::NODE_TYPES.include?(node_type)
+              raise ArgumentError, "unknown node_type: #{node_type.inspect}; must be one of #{Constants::NODE_TYPES.inspect}"
+            end
+
+            @node_id      = node_id
+            @node_type    = node_type
+            @content      = content
+            @connections  = []
+            @visited      = false
+            @danger_level = danger_level.clamp(0.0, 1.0)
+          end
+
+          def connect!(other_id)
+            @connections << other_id unless @connections.include?(other_id)
+            self
+          end
+
+          def disconnect!(other_id)
+            @connections.delete(other_id)
+            self
+          end
+
+          def dead_end?
+            @node_type == :dead_end || (@connections.empty? && @node_type != :entrance && @node_type != :exit)
+          end
+
+          def junction?
+            @node_type == :junction || @connections.size >= 3
+          end
+
+          def dangerous?
+            @node_type == :minotaur_lair || @danger_level >= 0.5
+          end
+
+          def to_h
+            {
+              node_id:      @node_id,
+              node_type:    @node_type,
+              content:      @content,
+              connections:  @connections.dup,
+              visited:      @visited,
+              danger_level: @danger_level
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_labyrinth/runners/cognitive_labyrinth.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLabyrinth
+      module Runners
+        module CognitiveLabyrinth
+          extend self
+
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+          def create_labyrinth(name:, domain: nil, labyrinth_id: nil, engine: nil, **)
+            raise ArgumentError, 'name is required' if name.nil? || name.to_s.strip.empty?
+
+            result = resolve_engine(engine).create_labyrinth(name: name, domain: domain, labyrinth_id: labyrinth_id)
+            Legion::Logging.debug "[cognitive_labyrinth] runner: created labyrinth #{result.labyrinth_id[0..7]}"
+            { success: true, labyrinth_id: result.labyrinth_id, name: result.name, domain: result.domain }
+          rescue ArgumentError => e
+            Legion::Logging.debug "[cognitive_labyrinth] create_labyrinth error: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def add_node(labyrinth_id:, node_type:, content: nil, danger_level: nil, node_id: nil, engine: nil, **)
+            raise ArgumentError, 'labyrinth_id is required' if labyrinth_id.nil?
+            raise ArgumentError, 'node_type is required' if node_type.nil?
+
+            node = resolve_engine(engine).add_node_to(
+              labyrinth_id: labyrinth_id, node_type: node_type,
+              content: content, danger_level: danger_level, node_id: node_id
+            )
+            { success: true, node_id: node.node_id, node_type: node.node_type }
+          rescue ArgumentError => e
+            Legion::Logging.debug "[cognitive_labyrinth] add_node error: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def connect_nodes(labyrinth_id:, from_id:, to_id:, bidirectional: true, engine: nil, **)
+            raise ArgumentError, 'labyrinth_id is required' if labyrinth_id.nil?
+
+            resolve_engine(engine).connect_nodes(
+              labyrinth_id: labyrinth_id, from_id: from_id, to_id: to_id, bidirectional: bidirectional
+            )
+          rescue ArgumentError => e
+            Legion::Logging.debug "[cognitive_labyrinth] connect_nodes error: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def move(labyrinth_id:, node_id:, engine: nil, **)
+            raise ArgumentError, 'labyrinth_id is required' if labyrinth_id.nil?
+            raise ArgumentError, 'node_id is required' if node_id.nil?
+
+            resolve_engine(engine).move(labyrinth_id: labyrinth_id, node_id: node_id)
+          rescue ArgumentError => e
+            Legion::Logging.debug "[cognitive_labyrinth] move error: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def backtrack(labyrinth_id:, engine: nil, **)
+            raise ArgumentError, 'labyrinth_id is required' if labyrinth_id.nil?
+
+            resolve_engine(engine).backtrack(labyrinth_id: labyrinth_id)
+          rescue ArgumentError => e
+            Legion::Logging.debug "[cognitive_labyrinth] backtrack error: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def follow_thread(labyrinth_id:, engine: nil, **)
+            raise ArgumentError, 'labyrinth_id is required' if labyrinth_id.nil?
+
+            resolve_engine(engine).follow_thread(labyrinth_id: labyrinth_id)
+          rescue ArgumentError => e
+            Legion::Logging.debug "[cognitive_labyrinth] follow_thread error: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def check_minotaur(labyrinth_id:, engine: nil, **)
+            raise ArgumentError, 'labyrinth_id is required' if labyrinth_id.nil?
+
+            resolve_engine(engine).check_minotaur(labyrinth_id: labyrinth_id)
+          rescue ArgumentError => e
+            Legion::Logging.debug "[cognitive_labyrinth] check_minotaur error: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def labyrinth_report(labyrinth_id:, engine: nil, **)
+            raise ArgumentError, 'labyrinth_id is required' if labyrinth_id.nil?
+
+            result = resolve_engine(engine).labyrinth_report(labyrinth_id: labyrinth_id)
+            { success: true }.merge(result)
+          rescue ArgumentError => e
+            Legion::Logging.debug "[cognitive_labyrinth] labyrinth_report error: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def list_labyrinths(engine: nil, **)
+            result = resolve_engine(engine).list_labyrinths
+            { success: true, labyrinths: result, count: result.size }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def delete_labyrinth(labyrinth_id:, engine: nil, **)
+            raise ArgumentError, 'labyrinth_id is required' if labyrinth_id.nil?
+
+            resolve_engine(engine).delete_labyrinth(labyrinth_id: labyrinth_id)
+          rescue ArgumentError => e
+            Legion::Logging.debug "[cognitive_labyrinth] delete_labyrinth error: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          private
+
+          def labyrinth_engine
+            @labyrinth_engine ||= Helpers::LabyrinthEngine.new
+          end
+
+          def resolve_engine(engine)
+            engine || labyrinth_engine
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_labyrinth/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLabyrinth
+      VERSION = '0.1.0'
+    end
+  end
+end

data/lib/legion/extensions/cognitive_labyrinth.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require_relative 'cognitive_labyrinth/version'
+require_relative 'cognitive_labyrinth/helpers/constants'
+require_relative 'cognitive_labyrinth/helpers/node'
+require_relative 'cognitive_labyrinth/helpers/labyrinth'
+require_relative 'cognitive_labyrinth/helpers/labyrinth_engine'
+require_relative 'cognitive_labyrinth/runners/cognitive_labyrinth'
+require_relative 'cognitive_labyrinth/client'
+
+module Legion
+  module Extensions
+    module CognitiveLabyrinth
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: lex-cognitive-labyrinth
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Maze-like problem spaces for agentic reasoning — paths, dead ends, backtracking,
+  breadcrumb trails, Ariadne's thread (guiding heuristic), and Minotaur encounters
+  (dangerous misconceptions)
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CLAUDE.md
+- Gemfile
+- README.md
+- lex-cognitive-labyrinth.gemspec
+- lib/legion/extensions/cognitive_labyrinth.rb
+- lib/legion/extensions/cognitive_labyrinth/actors/thread_walker.rb
+- lib/legion/extensions/cognitive_labyrinth/client.rb
+- lib/legion/extensions/cognitive_labyrinth/helpers/constants.rb
+- lib/legion/extensions/cognitive_labyrinth/helpers/labyrinth.rb
+- lib/legion/extensions/cognitive_labyrinth/helpers/labyrinth_engine.rb
+- lib/legion/extensions/cognitive_labyrinth/helpers/node.rb
+- lib/legion/extensions/cognitive_labyrinth/runners/cognitive_labyrinth.rb
+- lib/legion/extensions/cognitive_labyrinth/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-labyrinth
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-labyrinth
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-labyrinth
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-labyrinth
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-labyrinth
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-labyrinth/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LEX Cognitive Labyrinth
+test_files: []