lex-cognitive-liminal 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '0871023ea17e12821fa4bc8c1734a6206e13ab67c3c6edeceedb749a36fd1e74'
+  data.tar.gz: 8e2b1dfce63884782db8293b0605fadd40e3edecfaef92cf92d4afd4e7cf923a
+SHA512:
+  metadata.gz: 1bf9764fe3e730c9faf8f1e316f3d47561ecfa255be63dda7f891cd6dd940ec814fc1029f700798a513032fd7485b449e4ca2ebee6d47da1e4afbf391d097681
+  data.tar.gz: 0f9950a0098906cf1623cfad679f92ba211c3de35e13f20a48efd7d10161eaffb7a639d5abceefd91da3d25ed07cbe5b51e9fb43a2be7b4ecb3d9831a7dc5bb6

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,10 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+pkg
+spec/reports
+tmp
+Gemfile.lock
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--order random

data/.rubocop.yml

@@ -0,0 +1,37 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.4
+
+Style/Documentation:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/ParameterLists:
+  Max: 8
+  MaxOptionalParameters: 8
+
+Layout/HashAlignment:
+  EnforcedColonStyle: table
+  EnforcedHashRocketStyle: table
+
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/*
+
+Style/OneClassPerFile:
+  Exclude:
+    - spec/spec_helper.rb

data/CLAUDE.md

@@ -0,0 +1,116 @@
+# lex-cognitive-liminal
+
+**Level 3 Leaf Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+
+## Purpose
+
+Threshold crossing model based on anthropological liminality theory (van Gennep / Turner). Tracks cognitive transitions through three phases: `separation` (leaving the old state), `margin` (the liminal in-between), and `incorporation` (arriving at the new state). Each crossing tracks ambiguity (peaks at the liminal threshold), creative potential (highest in fertile liminal space), and progress (0.0 → 1.0).
+
+## Gem Info
+
+- **Gem name**: `lex-cognitive-liminal`
+- **Module**: `Legion::Extensions::CognitiveLiminal`
+- **Version**: `0.1.0`
+- **Ruby**: `>= 3.4`
+- **License**: MIT
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_liminal/
+  version.rb
+  client.rb
+  helpers/
+    constants.rb
+    threshold_crossing.rb
+    liminal_engine.rb
+  runners/
+    cognitive_liminal.rb
+```
+
+## Key Constants
+
+| Constant | Value | Purpose |
+|---|---|---|
+| `MAX_TRANSITIONS` | `200` | Per-engine crossing capacity |
+| `DEFAULT_AMBIGUITY` | `0.5` | Starting ambiguity for new crossings |
+| `AMBIGUITY_GROWTH` | `0.08` | Ambiguity increase per `dissolve!` call |
+| `AMBIGUITY_RESOLUTION` | `0.12` | Ambiguity decrease per `crystallize!` call |
+| `CREATIVE_POTENTIAL_PEAK` | `0.7` | Creative potential at peak liminality |
+| `DISSOLUTION_RATE` | `0.05` | Default progress regression rate |
+| `CRYSTALLIZATION_RATE` | `0.07` | Default progress advancement rate |
+| `SEPARATION_THRESHOLD` | `0.3` | Progress cutoff for separation phase |
+| `LIMINAL_PEAK` | `0.7` | Progress value for peak liminality |
+| `INCORPORATION_THRESHOLD` | `0.9` | Progress cutoff for incorporation phase |
+| `TRANSITION_PHASES` | `%i[separation margin incorporation complete]` | Valid phases |
+| `ORIGIN_STATES` / `DESTINATION_STATES` | symbol arrays | Valid state labels |
+| `LIMINAL_QUALITIES` | symbol array | Tags for the in-between quality |
+
+## Helpers
+
+### `Helpers::ThresholdCrossing`
+Single crossing instance. Has `id`, `origin_state`, `destination_state`, `domain`, `progress`, `ambiguity`, `creative_potential`, `phase`, and `completed_at`.
+
+- `advance!(rate)` — increases progress via `CRYSTALLIZATION_RATE`, advances phase
+- `dissolve!(rate)` — regresses progress, increases ambiguity
+- `crystallize!(rate)` — advances progress, reduces ambiguity
+- `complete!` — marks crossing done, sets `completed_at`
+- `liminal?` — phase is `:margin`
+- `separated?` — phase is `:separation`
+- `incorporated?` — phase is `:incorporation` or `:complete`
+- `peak_liminality?` — progress near `LIMINAL_PEAK`
+- `fertile?` — creative potential above a threshold
+- Label methods for ambiguity, creative potential, and phase
+
+### `Helpers::LiminalEngine`
+Manages all crossings. Enforces `MAX_TRANSITIONS`.
+
+- `begin_crossing(origin:, destination:, domain:)` → crossing
+- `advance_crossing(crossing_id:)` → crossing state
+- `dissolve_crossing(crossing_id:)` → crossing state
+- `crystallize_crossing(crossing_id:)` → crossing state
+- `active_crossings` → all incomplete crossings
+- `completed_crossings` → all complete crossings
+- `liminal_crossings` → crossings currently in margin phase
+- `fertile_crossings` → crossings with high creative potential
+- `peak_crossings` → crossings at peak liminality
+- `crossings_by_domain(domain:)` → filtered list
+- `average_ambiguity` → float
+- `average_creative_potential` → float
+- `liminal_density` → ratio of liminal to total active crossings
+- `most_liminal` → crossing with highest ambiguity
+- `liminal_report` → aggregate stats hash
+
+## Runners
+
+Module: `Runners::CognitiveLiminal`
+
+| Runner Method | Description |
+|---|---|
+| `begin_crossing(origin:, destination:, domain:)` | Start a new transition |
+| `advance_crossing(crossing_id:)` | Push crossing forward |
+| `dissolve_crossing(crossing_id:)` | Regress and increase ambiguity |
+| `crystallize_crossing(crossing_id:)` | Advance and reduce ambiguity |
+| `active_crossings` | All in-progress crossings |
+| `liminal_crossings` | Crossings in margin phase |
+| `fertile_crossings` | Crossings with high creative potential |
+| `liminal_status` | Full aggregate report |
+
+All runners return `{success: true/false, ...}` hashes.
+
+## Integration Points
+
+- No direct dependencies on other agentic LEX gems
+- Fits `lex-tick` `action_selection` phase: high ambiguity crossings can prompt consultation behavior
+- Creative potential peaks can feed into `lex-emotion` as a positive arousal signal
+- Peak liminality states represent prime conditions for insight — can trigger `lex-dream` association walks
+- `lex-identity` entropy checks may coincide with high-ambiguity transitions
+
+## Development Notes
+
+- `Client` instantiates `@liminal_engine = Helpers::LiminalEngine.new`
+- Phase transitions are implicit: `advance!` checks progress thresholds against `SEPARATION_THRESHOLD`, `LIMINAL_PEAK`, and `INCORPORATION_THRESHOLD`
+- A crossing can complete only by reaching `INCORPORATION_THRESHOLD` via `advance!` or `crystallize!`
+- `fertile?` is true when creative potential >= `CREATIVE_POTENTIAL_PEAK * 0.9` (near peak)
+- Ambiguity and creative potential are independent dimensions: high ambiguity + high creative potential = the fertile liminal state

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.75'
+gem 'rubocop-rspec'
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/README.md

@@ -0,0 +1,52 @@
+# lex-cognitive-liminal
+
+Threshold crossing model for LegionIO cognitive agents. Based on anthropological liminality theory, tracks transitions through separation, margin, and incorporation phases while measuring ambiguity and creative potential in the in-between space.
+
+## What It Does
+
+- Begin crossings from an origin state to a destination state within a domain
+- Three-phase progression: separation → margin (liminal) → incorporation
+- Track ambiguity (peaks mid-transition) and creative potential (highest in fertile liminal space)
+- `advance` / `crystallize` push crossings forward; `dissolve` regresses and increases ambiguity
+- Identify fertile crossings (high creative potential), peak-liminality crossings, and domain clusters
+- Supports up to 200 simultaneous transitions
+
+## Usage
+
+```ruby
+# Start a crossing
+result = runner.begin_crossing(
+  origin: :certainty, destination: :new_framework, domain: :architecture
+)
+crossing_id = result[:crossing][:id]
+
+# Advance through phases
+runner.advance_crossing(crossing_id: crossing_id)
+# => { success: true, crossing: { phase: :separation, progress: 0.07, ambiguity: 0.5, ... } }
+
+# In the margin — dissolve for more ambiguity (creative space)
+runner.dissolve_crossing(crossing_id: crossing_id)
+
+# Crystallize to resolve and advance
+runner.crystallize_crossing(crossing_id: crossing_id)
+
+# Find all crossings in the fertile liminal state
+runner.fertile_crossings
+# => { success: true, crossings: [...], count: N }
+
+# Overall status
+runner.liminal_status
+# => { success: true, total_active: N, liminal_count: N, avg_ambiguity: 0.XX, avg_creative_potential: 0.XX, ... }
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-liminal.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_liminal/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-liminal'
+  spec.version       = Legion::Extensions::CognitiveLiminal::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+  spec.summary       = 'Liminal threshold states between cognitive modes for LegionIO agents'
+  spec.description   = 'Models liminality — the creative in-between states during cognitive ' \
+                       'mode transitions with ambiguity, dissolution, and crystallization'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-liminal'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata = {
+    'homepage_uri'          => spec.homepage,
+    'source_code_uri'       => spec.homepage,
+    'documentation_uri'     => "#{spec.homepage}/blob/origin/README.md",
+    'changelog_uri'         => "#{spec.homepage}/blob/origin/CHANGELOG.md",
+    'bug_tracker_uri'       => "#{spec.homepage}/issues",
+    'rubygems_mfa_required' => 'true'
+  }
+
+  spec.files = Dir.chdir(__dir__) { `git ls-files -z`.split("\x0") }
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLiminal
+      class Client
+        include Runners::CognitiveLiminal
+
+        def initialize
+          @default_engine = Helpers::LiminalEngine.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLiminal
+      module Helpers
+        module Constants
+          MAX_TRANSITIONS = 200
+          MAX_THRESHOLDS = 100
+
+          # Liminal dynamics
+          DEFAULT_AMBIGUITY = 0.5
+          AMBIGUITY_GROWTH = 0.08
+          AMBIGUITY_RESOLUTION = 0.12
+          CREATIVE_POTENTIAL_PEAK = 0.7
+          DISSOLUTION_RATE = 0.05
+          CRYSTALLIZATION_RATE = 0.07
+
+          # Phase thresholds
+          SEPARATION_THRESHOLD = 0.3
+          LIMINAL_PEAK = 0.7
+          INCORPORATION_THRESHOLD = 0.9
+
+          TRANSITION_PHASES = %i[
+            separation margin incorporation
+          ].freeze
+
+          ORIGIN_STATES = %i[
+            analytical creative intuitive deliberate
+            receptive focused diffuse dormant
+          ].freeze
+
+          DESTINATION_STATES = %i[
+            analytical creative intuitive deliberate
+            receptive focused diffuse dormant
+          ].freeze
+
+          LIMINAL_QUALITIES = %i[
+            ambiguous fertile dissolving crystallizing
+            betwixt chaotic generative suspended
+          ].freeze
+
+          AMBIGUITY_LABELS = {
+            (0.8..)     => :maximally_liminal,
+            (0.6...0.8) => :deeply_liminal,
+            (0.4...0.6) => :liminal,
+            (0.2...0.4) => :transitioning,
+            (..0.2)     => :settled
+          }.freeze
+
+          POTENTIAL_LABELS = {
+            (0.8..)     => :explosive,
+            (0.6...0.8) => :high,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :low,
+            (..0.2)     => :depleted
+          }.freeze
+
+          PROGRESS_LABELS = {
+            (0.8..)     => :nearly_incorporated,
+            (0.6...0.8) => :deep_margin,
+            (0.4...0.6) => :peak_liminality,
+            (0.2...0.4) => :early_separation,
+            (..0.2)     => :pre_liminal
+          }.freeze
+
+          def self.label_for(labels, value)
+            labels.each { |range, label| return label if range.cover?(value) }
+            :unknown
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_liminal/helpers/liminal_engine.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLiminal
+      module Helpers
+        class LiminalEngine
+          include Constants
+
+          def initialize
+            @crossings = {}
+          end
+
+          def begin_crossing(origin:, destination:, domain: :general, ambiguity: DEFAULT_AMBIGUITY)
+            prune_completed
+            crossing = ThresholdCrossing.new(origin: origin, destination: destination,
+                                             domain: domain, ambiguity: ambiguity)
+            @crossings[crossing.id] = crossing
+            crossing
+          end
+
+          def advance_crossing(crossing_id:)
+            crossing = @crossings[crossing_id]
+            return nil unless crossing
+
+            crossing.advance!
+          end
+
+          def dissolve_crossing(crossing_id:)
+            crossing = @crossings[crossing_id]
+            return nil unless crossing
+
+            crossing.dissolve!
+          end
+
+          def crystallize_crossing(crossing_id:)
+            crossing = @crossings[crossing_id]
+            return nil unless crossing
+
+            crossing.crystallize!
+          end
+
+          def active_crossings = @crossings.values.select { |c| c.status == :active }
+          def completed_crossings = @crossings.values.select(&:incorporated?)
+          def liminal_crossings = @crossings.values.select(&:liminal?)
+          def fertile_crossings = @crossings.values.select(&:fertile?)
+          def peak_crossings = @crossings.values.select(&:peak_liminality?)
+
+          def crossings_by_domain(domain:)
+            @crossings.values.select { |c| c.domain == domain.to_sym }
+          end
+
+          def average_ambiguity
+            active = active_crossings
+            return 0.0 if active.empty?
+
+            (active.sum(&:ambiguity) / active.size).round(10)
+          end
+
+          def average_creative_potential
+            active = active_crossings
+            return 0.0 if active.empty?
+
+            (active.sum(&:creative_potential) / active.size).round(10)
+          end
+
+          def liminal_density
+            return 0.0 if @crossings.empty?
+
+            (liminal_crossings.size.to_f / [@crossings.size, 1].max).clamp(0.0, 1.0).round(10)
+          end
+
+          def most_liminal(limit: 5) = @crossings.values.sort_by { |c| -c.ambiguity }.first(limit)
+
+          def liminal_report
+            {
+              total_crossings:   @crossings.size,
+              active_count:      active_crossings.size,
+              liminal_count:     liminal_crossings.size,
+              completed_count:   completed_crossings.size,
+              fertile_count:     fertile_crossings.size,
+              peak_count:        peak_crossings.size,
+              average_ambiguity: average_ambiguity,
+              average_potential: average_creative_potential,
+              liminal_density:   liminal_density,
+              most_liminal:      most_liminal(limit: 3).map(&:to_h)
+            }
+          end
+
+          def to_h
+            {
+              total_crossings: @crossings.size,
+              active:          active_crossings.size,
+              liminal:         liminal_crossings.size,
+              avg_ambiguity:   average_ambiguity,
+              avg_potential:   average_creative_potential
+            }
+          end
+
+          private
+
+          def prune_completed
+            return if @crossings.size < MAX_TRANSITIONS
+
+            @crossings.reject! { |_, c| c.incorporated? }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_liminal/helpers/threshold_crossing.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveLiminal
+      module Helpers
+        class ThresholdCrossing
+          include Constants
+
+          attr_reader :id, :origin, :destination, :domain, :phase,
+                      :ambiguity, :creative_potential, :progress,
+                      :quality, :created_at, :ticks_in_liminal
+          attr_accessor :status
+
+          def initialize(origin:, destination:, domain: :general, ambiguity: DEFAULT_AMBIGUITY)
+            @id = SecureRandom.uuid
+            @origin = valid_state(origin, ORIGIN_STATES)
+            @destination = valid_state(destination, DESTINATION_STATES)
+            @domain = domain.to_sym
+            @ambiguity = ambiguity.to_f.clamp(0.0, 1.0).round(10)
+            @creative_potential = compute_creative_potential
+            @progress = 0.0
+            @phase = :separation
+            @quality = :ambiguous
+            @status = :active
+            @ticks_in_liminal = 0
+            @created_at = Time.now
+          end
+
+          def advance!
+            return self if @status == :completed
+
+            @ticks_in_liminal += 1
+            @progress = (@progress + CRYSTALLIZATION_RATE).clamp(0.0, 1.0).round(10)
+            update_phase!
+            update_ambiguity!
+            @creative_potential = compute_creative_potential
+            self
+          end
+
+          def dissolve!
+            @ambiguity = (@ambiguity + DISSOLUTION_RATE).clamp(0.0, 1.0).round(10)
+            @creative_potential = compute_creative_potential
+            @quality = :dissolving
+            self
+          end
+
+          def crystallize!
+            @ambiguity = (@ambiguity - AMBIGUITY_RESOLUTION).clamp(0.0, 1.0).round(10)
+            @progress = (@progress + CRYSTALLIZATION_RATE).clamp(0.0, 1.0).round(10)
+            @quality = :crystallizing
+            update_phase!
+            self
+          end
+
+          def complete!
+            @status = :completed
+            @phase = :incorporation
+            @progress = 1.0
+            @ambiguity = 0.0
+            @quality = :crystallizing
+            self
+          end
+
+          def liminal? = @phase == :margin && @status == :active
+          def separated? = @phase == :separation
+          def incorporated? = @status == :completed
+          def peak_liminality? = @ambiguity >= LIMINAL_PEAK
+          def fertile? = @creative_potential >= CREATIVE_POTENTIAL_PEAK
+
+          def ambiguity_label = Constants.label_for(AMBIGUITY_LABELS, @ambiguity)
+          def potential_label = Constants.label_for(POTENTIAL_LABELS, @creative_potential)
+          def progress_label = Constants.label_for(PROGRESS_LABELS, @progress)
+
+          def to_h
+            {
+              id:                 @id,
+              origin:             @origin,
+              destination:        @destination,
+              domain:             @domain,
+              phase:              @phase,
+              ambiguity:          @ambiguity,
+              creative_potential: @creative_potential,
+              progress:           @progress,
+              quality:            @quality,
+              status:             @status,
+              ticks_in_liminal:   @ticks_in_liminal,
+              liminal:            liminal?,
+              peak_liminality:    peak_liminality?,
+              fertile:            fertile?,
+              ambiguity_label:    ambiguity_label,
+              potential_label:    potential_label,
+              progress_label:     progress_label,
+              created_at:         @created_at.iso8601
+            }
+          end
+
+          private
+
+          def compute_creative_potential
+            peak_dist = (@ambiguity - CREATIVE_POTENTIAL_PEAK).abs
+            (1.0 - peak_dist).clamp(0.0, 1.0).round(10)
+          end
+
+          def update_phase!
+            if @progress >= INCORPORATION_THRESHOLD
+              @phase = :incorporation
+              complete!
+            elsif @progress >= SEPARATION_THRESHOLD
+              @phase = :margin
+            end
+          end
+
+          def update_ambiguity!
+            if @phase == :margin
+              @ambiguity = (@ambiguity + AMBIGUITY_GROWTH).clamp(0.0, 1.0).round(10)
+            elsif @phase == :incorporation
+              @ambiguity = (@ambiguity - AMBIGUITY_RESOLUTION).clamp(0.0, 1.0).round(10)
+            end
+          end
+
+          def valid_state(state, list)
+            sym = state.to_sym
+            list.include?(sym) ? sym : list.first
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLiminal
+      module Runners
+        module CognitiveLiminal
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+          def begin_crossing(origin:, destination:, domain: :general, ambiguity: nil, engine: nil, **)
+            eng = engine || @default_engine
+            crossing = eng.begin_crossing(origin: origin, destination: destination, domain: domain,
+                                          ambiguity: ambiguity || Helpers::Constants::DEFAULT_AMBIGUITY)
+            { success: true, crossing: crossing.to_h }
+          end
+
+          def advance_crossing(crossing_id:, engine: nil, **)
+            eng = engine || @default_engine
+            crossing = eng.advance_crossing(crossing_id: crossing_id)
+            return { success: false, error: 'crossing not found' } unless crossing
+
+            { success: true, crossing: crossing.to_h }
+          end
+
+          def dissolve_crossing(crossing_id:, engine: nil, **)
+            eng = engine || @default_engine
+            crossing = eng.dissolve_crossing(crossing_id: crossing_id)
+            return { success: false, error: 'crossing not found' } unless crossing
+
+            { success: true, crossing: crossing.to_h }
+          end
+
+          def crystallize_crossing(crossing_id:, engine: nil, **)
+            eng = engine || @default_engine
+            crossing = eng.crystallize_crossing(crossing_id: crossing_id)
+            return { success: false, error: 'crossing not found' } unless crossing
+
+            { success: true, crossing: crossing.to_h }
+          end
+
+          def active_crossings(engine: nil, **)
+            eng = engine || @default_engine
+            crossings = eng.active_crossings
+            { success: true, count: crossings.size, crossings: crossings.map(&:to_h) }
+          end
+
+          def liminal_crossings(engine: nil, **)
+            eng = engine || @default_engine
+            crossings = eng.liminal_crossings
+            { success: true, count: crossings.size, crossings: crossings.map(&:to_h) }
+          end
+
+          def fertile_crossings(engine: nil, **)
+            eng = engine || @default_engine
+            crossings = eng.fertile_crossings
+            { success: true, count: crossings.size, crossings: crossings.map(&:to_h) }
+          end
+
+          def liminal_status(engine: nil, **)
+            eng = engine || @default_engine
+            report = eng.liminal_report
+            { success: true, **report }
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_liminal.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'cognitive_liminal/version'
+require_relative 'cognitive_liminal/helpers/constants'
+require_relative 'cognitive_liminal/helpers/threshold_crossing'
+require_relative 'cognitive_liminal/helpers/liminal_engine'
+require_relative 'cognitive_liminal/runners/cognitive_liminal'
+require_relative 'cognitive_liminal/client'
+
+module Legion
+  module Extensions
+    module CognitiveLiminal
+    end
+  end
+end

data/spec/legion/extensions/cognitive_liminal/client_spec.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveLiminal::Client do
+  subject(:client) { described_class.new }
+
+  it 'responds to runner methods' do
+    expect(client).to respond_to(:begin_crossing, :advance_crossing, :liminal_status)
+  end
+
+  it 'runs a full liminal lifecycle' do
+    result = client.begin_crossing(origin: :analytical, destination: :creative, domain: :cognitive)
+    crossing_id = result[:crossing][:id]
+
+    5.times { client.advance_crossing(crossing_id: crossing_id) }
+    client.dissolve_crossing(crossing_id: crossing_id)
+    10.times { client.crystallize_crossing(crossing_id: crossing_id) }
+
+    status = client.liminal_status
+    expect(status[:total_crossings]).to eq(1)
+  end
+end

data/spec/legion/extensions/cognitive_liminal/helpers/liminal_engine_spec.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveLiminal::Helpers::LiminalEngine do
+  subject(:engine) { described_class.new }
+
+  describe '#begin_crossing' do
+    it 'creates a threshold crossing' do
+      crossing = engine.begin_crossing(origin: :analytical, destination: :creative)
+      expect(crossing.origin).to eq(:analytical)
+    end
+  end
+
+  describe '#advance_crossing' do
+    it 'advances known crossing' do
+      crossing = engine.begin_crossing(origin: :analytical, destination: :creative)
+      engine.advance_crossing(crossing_id: crossing.id)
+      expect(crossing.ticks_in_liminal).to eq(1)
+    end
+
+    it 'returns nil for unknown crossing' do
+      expect(engine.advance_crossing(crossing_id: 'bad')).to be_nil
+    end
+  end
+
+  describe '#dissolve_crossing' do
+    it 'dissolves known crossing' do
+      crossing = engine.begin_crossing(origin: :focused, destination: :diffuse)
+      original = crossing.ambiguity
+      engine.dissolve_crossing(crossing_id: crossing.id)
+      expect(crossing.ambiguity).to be > original
+    end
+  end
+
+  describe '#crystallize_crossing' do
+    it 'crystallizes known crossing' do
+      crossing = engine.begin_crossing(origin: :intuitive, destination: :deliberate)
+      original = crossing.ambiguity
+      engine.crystallize_crossing(crossing_id: crossing.id)
+      expect(crossing.ambiguity).to be < original
+    end
+  end
+
+  describe '#active_crossings' do
+    it 'returns active crossings' do
+      engine.begin_crossing(origin: :analytical, destination: :creative)
+      expect(engine.active_crossings.size).to eq(1)
+    end
+  end
+
+  describe '#completed_crossings' do
+    it 'returns completed crossings' do
+      crossing = engine.begin_crossing(origin: :analytical, destination: :creative)
+      20.times { crossing.advance! }
+      expect(engine.completed_crossings.size).to eq(1)
+    end
+  end
+
+  describe '#liminal_crossings' do
+    it 'returns crossings in margin phase' do
+      crossing = engine.begin_crossing(origin: :analytical, destination: :creative)
+      5.times { crossing.advance! }
+      expect(engine.liminal_crossings.size).to eq(1)
+    end
+  end
+
+  describe '#fertile_crossings' do
+    it 'returns fertile crossings' do
+      engine.begin_crossing(origin: :analytical, destination: :creative)
+      expect(engine.fertile_crossings.size).to eq(1)
+    end
+  end
+
+  describe '#crossings_by_domain' do
+    it 'filters by domain' do
+      engine.begin_crossing(origin: :analytical, destination: :creative, domain: :cognitive)
+      engine.begin_crossing(origin: :focused, destination: :diffuse, domain: :emotional)
+      expect(engine.crossings_by_domain(domain: :cognitive).size).to eq(1)
+    end
+  end
+
+  describe '#average_ambiguity' do
+    it 'returns 0.0 with no active crossings' do
+      expect(engine.average_ambiguity).to eq(0.0)
+    end
+
+    it 'returns average for active crossings' do
+      engine.begin_crossing(origin: :analytical, destination: :creative, ambiguity: 0.4)
+      engine.begin_crossing(origin: :focused, destination: :diffuse, ambiguity: 0.6)
+      expect(engine.average_ambiguity).to eq(0.5)
+    end
+  end
+
+  describe '#average_creative_potential' do
+    it 'returns 0.0 with no active crossings' do
+      expect(engine.average_creative_potential).to eq(0.0)
+    end
+  end
+
+  describe '#liminal_density' do
+    it 'returns 0.0 with no crossings' do
+      expect(engine.liminal_density).to eq(0.0)
+    end
+  end
+
+  describe '#most_liminal' do
+    it 'returns sorted by ambiguity descending' do
+      engine.begin_crossing(origin: :analytical, destination: :creative, ambiguity: 0.3)
+      high = engine.begin_crossing(origin: :focused, destination: :diffuse, ambiguity: 0.8)
+      expect(engine.most_liminal(limit: 1).first.id).to eq(high.id)
+    end
+  end
+
+  describe '#liminal_report' do
+    it 'includes all report fields' do
+      report = engine.liminal_report
+      expect(report).to include(
+        :total_crossings, :active_count, :liminal_count, :completed_count,
+        :fertile_count, :peak_count, :average_ambiguity, :average_potential,
+        :liminal_density, :most_liminal
+      )
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes summary fields' do
+      hash = engine.to_h
+      expect(hash).to include(:total_crossings, :active, :liminal, :avg_ambiguity, :avg_potential)
+    end
+  end
+end

data/spec/legion/extensions/cognitive_liminal/helpers/threshold_crossing_spec.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveLiminal::Helpers::ThresholdCrossing do
+  subject(:crossing) { described_class.new(origin: :analytical, destination: :creative) }
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(crossing.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores origin' do
+      expect(crossing.origin).to eq(:analytical)
+    end
+
+    it 'stores destination' do
+      expect(crossing.destination).to eq(:creative)
+    end
+
+    it 'defaults to separation phase' do
+      expect(crossing.phase).to eq(:separation)
+    end
+
+    it 'defaults ambiguity' do
+      expect(crossing.ambiguity).to eq(0.5)
+    end
+
+    it 'starts with active status' do
+      expect(crossing.status).to eq(:active)
+    end
+
+    it 'starts with 0 ticks' do
+      expect(crossing.ticks_in_liminal).to eq(0)
+    end
+
+    it 'validates origin state' do
+      bad = described_class.new(origin: :nonexistent, destination: :creative)
+      expect(bad.origin).to eq(:analytical)
+    end
+  end
+
+  describe '#advance!' do
+    it 'increments ticks' do
+      crossing.advance!
+      expect(crossing.ticks_in_liminal).to eq(1)
+    end
+
+    it 'increases progress' do
+      original = crossing.progress
+      crossing.advance!
+      expect(crossing.progress).to be > original
+    end
+
+    it 'transitions to margin phase' do
+      5.times { crossing.advance! }
+      expect(crossing.phase).to eq(:margin)
+    end
+
+    it 'eventually completes' do
+      20.times { crossing.advance! }
+      expect(crossing.incorporated?).to be true
+    end
+
+    it 'does not advance completed crossings' do
+      20.times { crossing.advance! }
+      ticks = crossing.ticks_in_liminal
+      crossing.advance!
+      expect(crossing.ticks_in_liminal).to eq(ticks)
+    end
+  end
+
+  describe '#dissolve!' do
+    it 'increases ambiguity' do
+      original = crossing.ambiguity
+      crossing.dissolve!
+      expect(crossing.ambiguity).to be > original
+    end
+
+    it 'sets quality to dissolving' do
+      crossing.dissolve!
+      expect(crossing.quality).to eq(:dissolving)
+    end
+  end
+
+  describe '#crystallize!' do
+    it 'decreases ambiguity' do
+      original = crossing.ambiguity
+      crossing.crystallize!
+      expect(crossing.ambiguity).to be < original
+    end
+
+    it 'increases progress' do
+      original = crossing.progress
+      crossing.crystallize!
+      expect(crossing.progress).to be > original
+    end
+
+    it 'sets quality to crystallizing' do
+      crossing.crystallize!
+      expect(crossing.quality).to eq(:crystallizing)
+    end
+  end
+
+  describe '#complete!' do
+    it 'sets status to completed' do
+      crossing.complete!
+      expect(crossing.status).to eq(:completed)
+    end
+
+    it 'sets progress to 1.0' do
+      crossing.complete!
+      expect(crossing.progress).to eq(1.0)
+    end
+
+    it 'clears ambiguity' do
+      crossing.complete!
+      expect(crossing.ambiguity).to eq(0.0)
+    end
+  end
+
+  describe '#liminal?' do
+    it 'is false in separation' do
+      expect(crossing.liminal?).to be false
+    end
+
+    it 'is true in margin phase' do
+      5.times { crossing.advance! }
+      expect(crossing.liminal?).to be true
+    end
+  end
+
+  describe '#peak_liminality?' do
+    it 'is true when ambiguity is high' do
+      5.times { crossing.dissolve! }
+      expect(crossing.peak_liminality?).to be true
+    end
+  end
+
+  describe '#fertile?' do
+    it 'detects creative potential peak' do
+      expect(crossing.fertile?).to be true
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all fields' do
+      hash = crossing.to_h
+      expect(hash).to include(
+        :id, :origin, :destination, :domain, :phase, :ambiguity,
+        :creative_potential, :progress, :quality, :status,
+        :ticks_in_liminal, :liminal, :peak_liminality, :fertile,
+        :ambiguity_label, :potential_label, :progress_label, :created_at
+      )
+    end
+  end
+end

data/spec/legion/extensions/cognitive_liminal/runners_spec.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveLiminal::Runners::CognitiveLiminal do
+  let(:engine) { Legion::Extensions::CognitiveLiminal::Helpers::LiminalEngine.new }
+  let(:runner) do
+    obj = Object.new
+    obj.extend(described_class)
+    obj.instance_variable_set(:@default_engine, engine)
+    obj
+  end
+
+  describe '#begin_crossing' do
+    it 'returns success with crossing hash' do
+      result = runner.begin_crossing(origin: :analytical, destination: :creative, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:crossing][:origin]).to eq(:analytical)
+    end
+  end
+
+  describe '#advance_crossing' do
+    it 'returns success for known crossing' do
+      crossing = engine.begin_crossing(origin: :analytical, destination: :creative)
+      result = runner.advance_crossing(crossing_id: crossing.id, engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns failure for unknown crossing' do
+      result = runner.advance_crossing(crossing_id: 'bad', engine: engine)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#dissolve_crossing' do
+    it 'returns success for known crossing' do
+      crossing = engine.begin_crossing(origin: :analytical, destination: :creative)
+      result = runner.dissolve_crossing(crossing_id: crossing.id, engine: engine)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#crystallize_crossing' do
+    it 'returns success for known crossing' do
+      crossing = engine.begin_crossing(origin: :analytical, destination: :creative)
+      result = runner.crystallize_crossing(crossing_id: crossing.id, engine: engine)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#active_crossings' do
+    it 'returns active list' do
+      engine.begin_crossing(origin: :analytical, destination: :creative)
+      result = runner.active_crossings(engine: engine)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#liminal_crossings' do
+    it 'returns liminal list' do
+      crossing = engine.begin_crossing(origin: :analytical, destination: :creative)
+      5.times { crossing.advance! }
+      result = runner.liminal_crossings(engine: engine)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#fertile_crossings' do
+    it 'returns fertile list' do
+      engine.begin_crossing(origin: :analytical, destination: :creative)
+      result = runner.fertile_crossings(engine: engine)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#liminal_status' do
+    it 'returns comprehensive status' do
+      result = runner.liminal_status(engine: engine)
+      expect(result[:success]).to be true
+      expect(result).to include(:total_crossings, :liminal_density)
+    end
+  end
+end

data/spec/legion/extensions/cognitive_liminal_spec.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveLiminal do
+  it 'has a version number' do
+    expect(Legion::Extensions::CognitiveLiminal::VERSION).to eq('0.1.0')
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_liminal'
+
+module Legion
+  module Extensions
+    module Helpers
+      module Lex; end
+    end
+  end
+
+  module Logging
+    def self.method_missing(_, *) = nil
+    def self.respond_to_missing?(_, _ = false) = true
+  end
+end
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+  config.order = :random
+  Kernel.srand config.seed
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: lex-cognitive-liminal
+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: Models liminality — the creative in-between states during cognitive mode
+  transitions with ambiguity, dissolution, and crystallization
+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-liminal.gemspec
+- lib/legion/extensions/cognitive_liminal.rb
+- lib/legion/extensions/cognitive_liminal/client.rb
+- lib/legion/extensions/cognitive_liminal/helpers/constants.rb
+- lib/legion/extensions/cognitive_liminal/helpers/liminal_engine.rb
+- lib/legion/extensions/cognitive_liminal/helpers/threshold_crossing.rb
+- lib/legion/extensions/cognitive_liminal/runners/cognitive_liminal.rb
+- lib/legion/extensions/cognitive_liminal/version.rb
+- spec/legion/extensions/cognitive_liminal/client_spec.rb
+- spec/legion/extensions/cognitive_liminal/helpers/liminal_engine_spec.rb
+- spec/legion/extensions/cognitive_liminal/helpers/threshold_crossing_spec.rb
+- spec/legion/extensions/cognitive_liminal/runners_spec.rb
+- spec/legion/extensions/cognitive_liminal_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-cognitive-liminal
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-liminal
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-liminal
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-liminal/blob/origin/README.md
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-liminal/blob/origin/CHANGELOG.md
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-liminal/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: Liminal threshold states between cognitive modes for LegionIO agents
+test_files: []