lex-cognitive-lucidity 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1fec45d2331b7f2662ee40b89229acd4de755c0fa9b86cffce4349aa35fa60dd
+  data.tar.gz: f052e627356cab0d38372d2348ec26389769719ba3cfb017180956cf9fe74091
+SHA512:
+  metadata.gz: '09313a8814401598f155aac12b0f4ddcc6d37eee479f06c6ae83c75f32111a15a40208c1484dc3c96e17be8e5700c23758630868b703d273aeae6cf1d6fa3459'
+  data.tar.gz: 5a344a1b0d96e9003e88a1d654bb101410b5a04326f4606de39e2a79c1d06b5312c8c35869b3e72df771b33eefe6f9958c9a588bc0f635b845c5d59577582147

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/OneClassPerFile:
+  Exclude:
+    - 'spec/spec_helper.rb'
+
+Style/SymbolArray:
+  Enabled: true
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Naming/FileName:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false

data/CLAUDE.md

@@ -0,0 +1,105 @@
+# lex-cognitive-lucidity
+
+**Level 3 Leaf Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+
+## Purpose
+
+Lucid dreaming metaphor for meta-cognitive awareness. Models dream states with continuously tracked lucidity levels. Reality tests (text_stability, hand_check, time_check, memory_check, logic_check) either boost or reduce lucidity depending on their result. When lucidity is sufficient (>= 0.5), the dream can be steered (directed). False awakenings are detected probabilistically, and completed dreams are recorded in an immutable journal with full metadata.
+
+## Gem Info
+
+- **Gem name**: `lex-cognitive-lucidity`
+- **Module**: `Legion::Extensions::CognitiveLucidity`
+- **Version**: `0.1.0`
+- **Ruby**: `>= 3.4`
+- **License**: MIT
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_lucidity/
+  version.rb
+  client.rb
+  helpers/
+    constants.rb
+    dream_state.rb
+    journal_entry.rb
+    lucidity_engine.rb
+  runners/
+    cognitive_lucidity.rb
+```
+
+## Key Constants
+
+| Constant | Value | Purpose |
+|---|---|---|
+| `MAX_JOURNAL_ENTRIES` | `500` | Journal ring buffer capacity |
+| `MAX_DREAMS` | `100` | Maximum simultaneous active dreams |
+| `LUCIDITY_LEVELS` | range hash | From `:somnambulant` to `:hyper_lucid` |
+| `REALITY_TEST_TYPES` | `%i[text_stability hand_check time_check memory_check logic_check]` | Valid test types |
+| `LUCIDITY_DECAY` | `0.05` | Lucidity lost per tick without stimulation |
+| `FALSE_AWAKENING_CHANCE` | `0.1` | Base probability of false awakening per reality test |
+| `DREAM_QUALITY_LABELS` | range hash | From `:incoherent` to `:vivid` |
+
+## Helpers
+
+### `Helpers::DreamState`
+Active dream session. Has `id`, `lucidity`, `themes` (array), `insights` (array), `false_awakening_count`, and `steered` flag.
+
+- `reality_test!(test_type)` — performs a reality check; returns test result hash including lucidity delta. May trigger false awakening (raises `false_awakening_count`).
+- `steer!(direction)` — sets a narrative direction; requires lucidity >= 0.5, returns error hash otherwise
+- `destabilize!` — applies `LUCIDITY_DECAY` to lucidity
+- `stabilize!(amount)` — increases lucidity
+- `end!` — marks dream inactive
+- `lucidity_label`
+
+### `Helpers::JournalEntry`
+Immutable (frozen) record of a completed dream. Captures: `lucidity_achieved`, `reality_tests_performed`, `themes`, `insights`, `false_awakening_count`, `duration_seconds`, `steered`.
+
+- Frozen at creation: no mutation after recording
+- `to_h` for serialization
+
+### `Helpers::LucidityEngine`
+Manages active dreams and the journal.
+
+- `begin_dream(themes:)` → new `DreamState`
+- `reality_test(dream_id:, test_type:)` → test result hash
+- `steer_dream(dream_id:, direction:)` → steer result hash
+- `end_dream(dream_id:)` → creates `JournalEntry`, returns entry hash
+- `all_dreams` → all active dream states
+- `active_dream` → most recently begun active dream
+- `lucidity_report` → aggregate stats
+- `most_lucid_dreams(limit:)` → journal entries sorted by lucidity
+- `theme_analysis` → hash of theme frequencies across all journal entries
+
+## Runners
+
+Module: `Runners::CognitiveLucidity`
+
+| Runner Method | Description |
+|---|---|
+| `begin_dream(themes:)` | Start a new dream state |
+| `reality_test(dream_id:, test_type:)` | Perform a reality check |
+| `steer_dream(dream_id:, direction:)` | Steer the dream narrative |
+| `end_dream(dream_id:)` | Complete and journal the dream |
+| `lucidity_status` | Aggregate lucidity report |
+| `journal_entries(limit:)` | Recent journal entries |
+
+All runners return `{success: true/false, ...}` hashes.
+
+## Integration Points
+
+- Directly parallels `lex-dream`'s dream cycle: lucidity can be attached to lex-dream association walks
+- `reality_test` fits `lex-tick` `identity_entropy_check` phase (grounding checks)
+- High lucidity states can boost `lex-emotion` arousal positively
+- False awakening count over a threshold can trigger `lex-conflict` internal conflict
+- Journal themes feed into `lex-memory` semantic trace creation
+
+## Development Notes
+
+- `Client` instantiates `@lucidity_engine = Helpers::LucidityEngine.new`
+- `JournalEntry` is frozen: records are write-once for integrity
+- `reality_test!` applies a lucidity delta depending on test type and result; passing tests increase lucidity, failing tests decrease it
+- False awakening uses `rand < FALSE_AWAKENING_CHANCE` check per test; it resets some state but does not end the dream
+- `steer!` fails silently with `{success: false, error: :insufficient_lucidity}` when lucidity < 0.5

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,49 @@
+# lex-cognitive-lucidity
+
+Lucid dreaming metaphor for meta-cognitive awareness in LegionIO cognitive agents. Dream states have continuously tracked lucidity levels; reality tests stabilize or destabilize lucidity; sufficiently lucid states can be steered. Completed dreams are journaled as immutable records.
+
+## What It Does
+
+- Begin dream states with thematic content
+- Five reality test types: `text_stability`, `hand_check`, `time_check`, `memory_check`, `logic_check`
+- Passing tests boost lucidity; failing tests reduce it
+- False awakening: 10% chance per reality test to trigger a false-awakening event
+- Steer the dream narrative when lucidity >= 0.5
+- End dreams and record them in a journal with full metadata (lucidity achieved, test count, themes, insights, false awakenings, duration)
+- Journal analysis: most-lucid entries and theme frequency analysis
+
+## Usage
+
+```ruby
+# Begin a dream
+result = runner.begin_dream(themes: [:problem_solving, :creativity])
+dream_id = result[:dream][:id]
+
+# Run reality tests to stabilize lucidity
+runner.reality_test(dream_id: dream_id, test_type: :logic_check)
+# => { success: true, test_type: :logic_check, passed: true, lucidity_delta: 0.1, lucidity: 0.6, false_awakening: false }
+
+# Steer once lucid enough
+runner.steer_dream(dream_id: dream_id, direction: 'explore the architectural pattern more deeply')
+
+# End and journal
+runner.end_dream(dream_id: dream_id)
+# => { success: true, journal_entry: { lucidity_achieved: 0.6, steered: true, ... } }
+
+# Analyze journal
+runner.journal_entries(limit: 10)
+runner.lucidity_status
+# => { success: true, active_dreams: 0, journal_size: 1, ... }
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-lucidity.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_lucidity/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-lucidity'
+  spec.version       = Legion::Extensions::CognitiveLucidity::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Lucidity'
+  spec.description   = 'Lucid dreaming for AI — self-aware dream processing with lucidity levels, ' \
+                       'reality testing, dream steering, and false awakening detection'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-lucidity'
+  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-lucidity'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-cognitive-lucidity'
+  spec.metadata['changelog_uri']     = 'https://github.com/LegionIO/lex-cognitive-lucidity'
+  spec.metadata['bug_tracker_uri']   = 'https://github.com/LegionIO/lex-cognitive-lucidity/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_lucidity/client.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLucidity
+      class Client
+        include Runners::CognitiveLucidity
+
+        attr_reader :engine
+
+        def initialize(engine: nil, **)
+          @default_engine = engine || Helpers::LucidityEngine.new
+        end
+
+        private
+
+        attr_reader :default_engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLucidity
+      module Helpers
+        module Constants
+          MAX_JOURNAL_ENTRIES = 500
+          MAX_DREAMS          = 100
+
+          LUCIDITY_LEVELS = %i[non_lucid pre_lucid semi_lucid lucid fully_lucid].freeze
+
+          REALITY_TEST_TYPES = %i[
+            text_stability
+            hand_check
+            time_check
+            memory_check
+            logic_check
+          ].freeze
+
+          LUCIDITY_DECAY = 0.05
+          FALSE_AWAKENING_CHANCE = 0.1
+
+          DREAM_QUALITY_LABELS = {
+            0.0..0.2 => :poor,
+            0.2..0.4 => :fragmented,
+            0.4..0.6 => :ordinary,
+            0.6..0.8 => :vivid,
+            0.8..1.0 => :hyper_vivid
+          }.freeze
+
+          module_function
+
+          def label_for(value)
+            DREAM_QUALITY_LABELS.each do |range, label|
+              return label if range.cover?(value.clamp(0.0, 1.0))
+            end
+            :ordinary
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_lucidity/helpers/dream_state.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveLucidity
+      module Helpers
+        class DreamState
+          attr_reader :id, :lucidity_level, :awareness, :content, :theme, :vividness, :stability, :emotional_tone, :started_at, :reality_tests_performed,
+                      :false_awakening_count, :steered, :ended_at
+
+          def initialize(theme:, content:, vividness: 0.5, stability: 0.7,
+                         emotional_tone: :neutral, lucidity_level: 0.0, **)
+            @id                      = SecureRandom.uuid
+            @theme                   = theme
+            @content                 = content
+            @vividness               = vividness.clamp(0.0, 1.0)
+            @stability               = stability.clamp(0.0, 1.0)
+            @emotional_tone          = emotional_tone
+            @lucidity_level          = lucidity_level.clamp(0.0, 1.0)
+            @awareness               = @lucidity_level > 0.0
+            @started_at              = Time.now.utc
+            @reality_tests_performed = []
+            @false_awakening_count   = 0
+            @steered                 = false
+            @active                  = true
+          end
+
+          def active?
+            @active
+          end
+
+          def lucidity_label
+            thresholds = [
+              [0.0, :non_lucid],
+              [0.2, :pre_lucid],
+              [0.5, :semi_lucid],
+              [0.75, :lucid],
+              [0.9, :fully_lucid]
+            ]
+            label = :non_lucid
+            thresholds.each do |threshold, lbl|
+              label = lbl if @lucidity_level >= threshold
+            end
+            label
+          end
+
+          def reality_test!(test_type)
+            raise ArgumentError, "unknown test type: #{test_type}" unless Constants::REALITY_TEST_TYPES.include?(test_type)
+
+            result = perform_reality_test(test_type)
+            @reality_tests_performed << {
+              test_type:      test_type,
+              result:         result[:outcome],
+              lucidity_delta: result[:lucidity_delta],
+              tested_at:      Time.now.utc
+            }
+
+            if result[:false_awakening]
+              @false_awakening_count += 1
+              return { outcome: :false_awakening, lucidity_delta: 0.0, false_awakening: true }
+            end
+
+            @lucidity_level = (@lucidity_level + result[:lucidity_delta]).clamp(0.0, 1.0)
+            @awareness = @lucidity_level > 0.0
+
+            { outcome: result[:outcome], lucidity_delta: result[:lucidity_delta], false_awakening: false }
+          end
+
+          def steer!(direction)
+            return { success: false, reason: :insufficient_lucidity } if @lucidity_level < 0.5
+
+            @content   = "#{@content} [steered: #{direction}]"
+            @steered   = true
+            @stability = (@stability - 0.1).clamp(0.0, 1.0)
+
+            { success: true, direction: direction, new_stability: @stability }
+          end
+
+          def destabilize!(amount)
+            @stability = (@stability - amount.clamp(0.0, 1.0)).clamp(0.0, 1.0)
+            @lucidity_level = (@lucidity_level - Constants::LUCIDITY_DECAY).clamp(0.0, 1.0)
+            @awareness = @lucidity_level > 0.0
+            { stability: @stability, lucidity_level: @lucidity_level }
+          end
+
+          def stabilize!(amount)
+            @stability = (@stability + amount.clamp(0.0, 1.0)).clamp(0.0, 1.0)
+            { stability: @stability, lucidity_level: @lucidity_level }
+          end
+
+          def end!
+            @active = false
+            @ended_at = Time.now.utc
+          end
+
+          def duration_seconds
+            end_time = @ended_at || Time.now.utc
+            (end_time - @started_at).round(10)
+          end
+
+          private
+
+          def perform_reality_test(test_type)
+            false_awakening = rand < Constants::FALSE_AWAKENING_CHANCE
+
+            return { outcome: :failed, lucidity_delta: 0.0, false_awakening: true } if false_awakening
+
+            base_gain = test_base_gain(test_type)
+            stability_modifier = @stability < 0.3 ? 0.5 : 1.0
+            lucidity_delta = (base_gain * stability_modifier).round(10)
+
+            { outcome: :passed, lucidity_delta: lucidity_delta, false_awakening: false }
+          end
+
+          def test_base_gain(test_type)
+            gains = {
+              text_stability: 0.15,
+              hand_check:     0.20,
+              time_check:     0.10,
+              memory_check:   0.12,
+              logic_check:    0.18
+            }
+            gains.fetch(test_type, 0.10)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_lucidity/helpers/journal_entry.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveLucidity
+      module Helpers
+        class JournalEntry
+          attr_reader :id, :dream_state_id, :content_summary, :lucidity_achieved,
+                      :reality_tests_performed, :themes, :insights, :recorded_at,
+                      :false_awakening_count, :duration_seconds, :steered
+
+          def initialize(dream_state:, insights: [], **)
+            @id                    = SecureRandom.uuid
+            @dream_state_id        = dream_state.id
+            @content_summary       = dream_state.content.to_s
+            @lucidity_achieved     = dream_state.lucidity_level.round(10)
+            @reality_tests_performed = dream_state.reality_tests_performed.dup.freeze
+            @themes                = Array(dream_state.theme).freeze
+            @insights              = Array(insights).freeze
+            @recorded_at           = Time.now.utc
+            @false_awakening_count = dream_state.false_awakening_count
+            @duration_seconds      = dream_state.duration_seconds
+            @steered               = dream_state.steered
+            freeze
+          end
+
+          def lucidity_label
+            thresholds = [
+              [0.0, :non_lucid],
+              [0.2, :pre_lucid],
+              [0.5, :semi_lucid],
+              [0.75, :lucid],
+              [0.9, :fully_lucid]
+            ]
+            label = :non_lucid
+            thresholds.each do |threshold, lbl|
+              label = lbl if @lucidity_achieved >= threshold
+            end
+            label
+          end
+
+          def to_h
+            {
+              id:                      @id,
+              dream_state_id:          @dream_state_id,
+              content_summary:         @content_summary,
+              lucidity_achieved:       @lucidity_achieved,
+              lucidity_label:          lucidity_label,
+              reality_tests_performed: @reality_tests_performed,
+              themes:                  @themes,
+              insights:                @insights,
+              false_awakening_count:   @false_awakening_count,
+              duration_seconds:        @duration_seconds,
+              steered:                 @steered,
+              recorded_at:             @recorded_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_lucidity/helpers/lucidity_engine.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLucidity
+      module Helpers
+        class LucidityEngine
+          attr_reader :journal
+
+          def initialize
+            @dreams  = {}
+            @journal = []
+          end
+
+          def begin_dream(theme:, content:, vividness: 0.5, stability: 0.7,
+                          emotional_tone: :neutral, lucidity_level: 0.0, **)
+            evict_oldest_dream! if @dreams.size >= Constants::MAX_DREAMS
+
+            state = DreamState.new(
+              theme:          theme,
+              content:        content,
+              vividness:      vividness,
+              stability:      stability,
+              emotional_tone: emotional_tone,
+              lucidity_level: lucidity_level
+            )
+            @dreams[state.id] = state
+            {
+              dream_id:       state.id,
+              theme:          state.theme,
+              lucidity_level: state.lucidity_level,
+              stability:      state.stability
+            }
+          end
+
+          def reality_test(dream_id:, test_type:, **)
+            state = @dreams[dream_id]
+            return { success: false, error: 'dream not found' } unless state
+            return { success: false, error: 'dream is not active' } unless state.active?
+
+            result = state.reality_test!(test_type.to_sym)
+            {
+              success:         true,
+              dream_id:        dream_id,
+              outcome:         result[:outcome],
+              lucidity_delta:  result[:lucidity_delta],
+              lucidity_level:  state.lucidity_level,
+              false_awakening: result[:false_awakening]
+            }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def steer_dream(dream_id:, direction:, **)
+            state = @dreams[dream_id]
+            return { success: false, error: 'dream not found' } unless state
+            return { success: false, error: 'dream is not active' } unless state.active?
+
+            result = state.steer!(direction)
+            result.merge(dream_id: dream_id)
+          end
+
+          def end_dream(dream_id:, insights: [], **)
+            state = @dreams[dream_id]
+            return { success: false, error: 'dream not found' } unless state
+            return { success: false, error: 'dream is not active' } unless state.active?
+
+            state.end!
+            entry = JournalEntry.new(dream_state: state, insights: insights)
+            add_journal_entry(entry)
+
+            {
+              success:           true,
+              dream_id:          dream_id,
+              journal_entry_id:  entry.id,
+              lucidity_achieved: entry.lucidity_achieved,
+              duration_seconds:  entry.duration_seconds
+            }
+          end
+
+          def all_dreams
+            @dreams.values
+          end
+
+          def active_dream
+            @dreams.values.find(&:active?)
+          end
+
+          def lucidity_report
+            return base_report if @journal.empty?
+
+            {
+              total_dreams:          @journal.size,
+              avg_lucidity:          compute_avg_lucidity,
+              false_awakening_count: @journal.sum(&:false_awakening_count),
+              steered_count:         @journal.count(&:steered),
+              test_success_rates:    compute_test_success_rates
+            }
+          end
+
+          def most_lucid_dreams(limit: 5, **)
+            sorted = @journal.sort_by { |e| -e.lucidity_achieved }
+            sorted.first(limit).map(&:to_h)
+          end
+
+          def theme_analysis
+            theme_map, lucidity_by_theme = build_theme_maps
+            results = theme_map.map do |theme, count|
+              avg = compute_theme_avg(lucidity_by_theme[theme])
+              { theme: theme, occurrences: count, avg_lucidity: avg }
+            end
+            results.sort_by { |t| -t[:occurrences] }
+          end
+
+          private
+
+          def compute_avg_lucidity
+            (@journal.sum(&:lucidity_achieved) / @journal.size.to_f).round(10)
+          end
+
+          def compute_test_success_rates
+            test_totals = Hash.new(0)
+            test_passes = Hash.new(0)
+            @journal.each do |entry|
+              entry.reality_tests_performed.each do |rt|
+                test_totals[rt[:test_type]] += 1
+                test_passes[rt[:test_type]] += 1 if rt[:result] == :passed
+              end
+            end
+            test_totals.to_h do |test_type, count|
+              rate = count.positive? ? (test_passes[test_type].to_f / count).round(10) : 0.0
+              [test_type, rate]
+            end
+          end
+
+          def build_theme_maps
+            theme_map = Hash.new(0)
+            lucidity_by_theme = Hash.new { |h, k| h[k] = [] }
+            @journal.each do |entry|
+              Array(entry.themes).each do |theme|
+                theme_map[theme] += 1
+                lucidity_by_theme[theme] << entry.lucidity_achieved
+              end
+            end
+            [theme_map, lucidity_by_theme]
+          end
+
+          def compute_theme_avg(values)
+            return 0.0 if values.empty?
+
+            (values.sum / values.size.to_f).round(10)
+          end
+
+          def add_journal_entry(entry)
+            @journal.shift while @journal.size >= Constants::MAX_JOURNAL_ENTRIES
+            @journal << entry
+          end
+
+          def evict_oldest_dream!
+            oldest_id = @dreams.min_by { |_id, state| state.started_at }&.first
+            @dreams.delete(oldest_id) if oldest_id
+          end
+
+          def base_report
+            {
+              total_dreams:          0,
+              avg_lucidity:          0.0,
+              false_awakening_count: 0,
+              steered_count:         0,
+              test_success_rates:    {}
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLucidity
+      module Runners
+        module CognitiveLucidity
+          extend self
+
+          def begin_dream(theme:, content:, engine: nil, **)
+            eng = engine || default_engine
+            result = eng.begin_dream(theme: theme, content: content, **)
+            Legion::Logging.debug "[cognitive_lucidity] begin_dream theme=#{theme} id=#{result[:dream_id]}"
+            result.merge(success: true)
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def reality_test(dream_id:, test_type:, engine: nil, **)
+            eng = engine || default_engine
+            result = eng.reality_test(dream_id: dream_id, test_type: test_type)
+            Legion::Logging.debug "[cognitive_lucidity] reality_test dream_id=#{dream_id} " \
+                                  "test=#{test_type} outcome=#{result[:outcome]}"
+            result
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def steer_dream(dream_id:, direction:, engine: nil, **)
+            eng = engine || default_engine
+            result = eng.steer_dream(dream_id: dream_id, direction: direction)
+            Legion::Logging.debug "[cognitive_lucidity] steer_dream dream_id=#{dream_id} " \
+                                  "direction=#{direction} success=#{result[:success]}"
+            result
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def end_dream(dream_id:, insights: [], engine: nil, **)
+            eng = engine || default_engine
+            result = eng.end_dream(dream_id: dream_id, insights: insights)
+            Legion::Logging.debug "[cognitive_lucidity] end_dream dream_id=#{dream_id} " \
+                                  "lucidity=#{result[:lucidity_achieved]}"
+            result
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def lucidity_status(engine: nil, **)
+            eng = engine || default_engine
+            active = eng.active_dream
+            report = eng.lucidity_report
+            Legion::Logging.debug "[cognitive_lucidity] lucidity_status active=#{!active.nil?}"
+            {
+              success:      true,
+              active_dream: if active
+                              {
+                                id:             active.id,
+                                theme:          active.theme,
+                                lucidity_level: active.lucidity_level,
+                                stability:      active.stability,
+                                lucidity_label: active.lucidity_label
+                              }
+                            end,
+              report:       report
+            }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def journal_entries(limit: 20, engine: nil, **)
+            eng     = engine || default_engine
+            entries = eng.journal.last(limit).map(&:to_h)
+            Legion::Logging.debug "[cognitive_lucidity] journal_entries count=#{entries.size}"
+            { success: true, count: entries.size, entries: entries }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+          private
+
+          def default_engine
+            @default_engine ||= Helpers::LucidityEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_lucidity.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require 'legion/extensions/cognitive_lucidity/version'
+require 'legion/extensions/cognitive_lucidity/helpers/constants'
+require 'legion/extensions/cognitive_lucidity/helpers/dream_state'
+require 'legion/extensions/cognitive_lucidity/helpers/journal_entry'
+require 'legion/extensions/cognitive_lucidity/helpers/lucidity_engine'
+require 'legion/extensions/cognitive_lucidity/runners/cognitive_lucidity'
+require 'legion/extensions/cognitive_lucidity/client'
+
+module Legion
+  module Extensions
+    module CognitiveLucidity
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: lex-cognitive-lucidity
+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: Lucid dreaming for AI — self-aware dream processing with lucidity levels,
+  reality testing, dream steering, and false awakening detection
+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-lucidity.gemspec
+- lib/legion/extensions/cognitive_lucidity.rb
+- lib/legion/extensions/cognitive_lucidity/client.rb
+- lib/legion/extensions/cognitive_lucidity/helpers/constants.rb
+- lib/legion/extensions/cognitive_lucidity/helpers/dream_state.rb
+- lib/legion/extensions/cognitive_lucidity/helpers/journal_entry.rb
+- lib/legion/extensions/cognitive_lucidity/helpers/lucidity_engine.rb
+- lib/legion/extensions/cognitive_lucidity/runners/cognitive_lucidity.rb
+- lib/legion/extensions/cognitive_lucidity/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-lucidity
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-lucidity
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-lucidity
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-lucidity
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-lucidity
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-lucidity/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 Lucidity
+test_files: []