lex-cognitive-aurora 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fe4d61baead511e96254003b84950b26847ebf177baaf120303154e8f26ec22f
+  data.tar.gz: c20973ddc48c53238ae4e400df4fd82fb53849809eb7a8cb5dcfa97766c7eef5
+SHA512:
+  metadata.gz: 6256f15cd80ab5a6657284ad7bbccc8d8f990e103fb0652b148d1dcd4281dfb66b5c029a4311efb8d0cb5dc7664846801b1a1feba3bc67a3a09137ca9c0d342b
+  data.tar.gz: 685e45529ec37c6abb3f9ae7d5e416c4bb41b784e8515fc5654a4e9eca9d65283810d77a249e3dc1d384e2cdb7d8441ccc6a0d2dd410f7f438acf208eab22110

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,2 @@
+.rspec_status
+Gemfile.lock

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--format documentation

data/.rubocop.yml

@@ -0,0 +1,65 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/LineLength:
+  Max: 160
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: space
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/ModuleLength:
+  Max: 200
+
+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/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Style/SymbolArray:
+  Enabled: true
+
+Style/OneClassPerFile:
+  Enabled: false
+  Exclude:
+    - 'spec/spec_helper.rb'
+
+Naming/FileName:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false

data/CLAUDE.md

@@ -0,0 +1,76 @@
+# lex-cognitive-aurora
+
+**Level 3 Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+- **Grandparent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+Emergent beauty and aesthetic pattern detection for the LegionIO cognitive architecture. Detects moments of harmony, elegance, and resonance across cognitive subsystems. Aurora events represent fleeting moments of cognitive coherence — not sustained states but bursts of cross-domain alignment.
+
+## Gem Info
+
+- **Gem name**: `lex-cognitive-aurora`
+- **Version**: `0.1.0`
+- **Module**: `Legion::Extensions::CognitiveAurora`
+- **Ruby**: `>= 3.4`
+- **License**: MIT
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_aurora/
+  cognitive_aurora.rb
+  version.rb
+  client.rb
+  helpers/
+    constants.rb
+    aurora_engine.rb
+    aurora_event.rb
+    spectral_band.rb
+  runners/
+    cognitive_aurora.rb
+```
+
+## Key Constants
+
+From `helpers/constants.rb`:
+
+- `AURORA_TYPES` — `%i[harmonic resonant cascading convergent emergent serendipitous synchronous prismatic]`
+- `SPECTRAL_COLORS` — `%i[violet indigo blue green yellow orange red ultraviolet]`
+- `DOMAINS` — `%i[memory emotion prediction identity trust consent governance perception]`
+- `MAX_EVENTS` = `300`, `MAX_BANDS` = `50`
+- `DEFAULT_LUMINOSITY` = `0.5`, `LUMINOSITY_DECAY` = `0.03`, `LUMINOSITY_BOOST` = `0.1`
+- `HARMONY_THRESHOLD` = `0.7`, `BRILLIANCE_THRESHOLD` = `0.8`, `FAINT_THRESHOLD` = `0.2`
+- `LUMINOSITY_LABELS` — `0.8+` = `:brilliant`, `0.6` = `:bright`, `0.4` = `:moderate`, `0.2` = `:dim`, below = `:faint`
+- `HARMONY_LABELS` — `0.9+` = `:perfect`, `0.7` = `:harmonious`, `0.5` = `:resonating`, `0.3` = `:unsettled`, below = `:discordant`
+- `BRILLIANCE_LABELS` — `0.75+` = `:transcendent`, `0.5` = `:radiant`, `0.25` = `:emerging`, below = `:nascent`
+
+## Runners
+
+All methods in `Runners::CognitiveAurora`:
+
+- `detect_aurora(type:, domain:, contributing_subsystems:, luminosity:, harmony_score:, engine: nil)` — records a new aurora event; prunes faint events when `MAX_EVENTS` reached
+- `fade_all(engine: nil)` — applies luminosity decay to all events; returns before/after brilliant count
+- `list_brilliant(limit: 10, engine: nil)` — returns events sorted by luminosity descending
+- `aurora_status(engine: nil)` — returns full aurora report: totals, luminosity, harmony, band distribution
+
+## Helpers
+
+- `AuroraEngine` — stores events in `@events` array and `@spectral_bands` keyed by aurora type. Computes aggregate luminosity and harmony as simple averages. Pruning removes faint events first, then oldest.
+- `AuroraEvent` — individual aurora occurrence with `aurora_type`, `domain`, `contributing_subsystems`, `luminosity`, `harmony_score`, `id`. Methods: `fade!`, `brilliant?`, `harmonious?`, `faint?`.
+- `SpectralBand` — groups events by aurora type; tracks band-level intensity.
+
+## Integration Points
+
+- Designed to be called from tick phases when cross-domain alignment is detected — e.g., when emotion + memory + prediction all converge on a consistent signal.
+- `contributing_subsystems` links aurora events back to named subsystems in `lex-cognitive-architecture`.
+- `DOMAINS` list maps to the core agentic LEXs (memory, emotion, prediction, identity, trust, consent, governance, perception).
+- No hard dependency on any other LEX; callers pass domain context via arguments.
+
+## Development Notes
+
+- `AuroraEngine` is per-runner-instance in-memory state (no persistence).
+- Pruning strategy: removes faint events first; if none are faint, removes the oldest event. This preserves brilliance at the cost of history.
+- `overall_luminosity` and `overall_harmony` are simple arithmetic means, not weighted. Large numbers of faint events pull these values down.
+- `SpectralBand` intensity tracks the running signal across all events of a given aurora type — useful for detecting which type of cognitive harmony fires most frequently.

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/Gemfile.lock

@@ -0,0 +1,78 @@
+PATH
+  remote: .
+  specs:
+    lex-cognitive-aurora (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    bigdecimal (4.0.1)
+    diff-lcs (1.6.2)
+    json (2.19.1)
+    json-schema (6.2.0)
+      addressable (~> 2.8)
+      bigdecimal (>= 3.1, < 5)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    mcp (0.8.0)
+      json-schema (>= 4.1)
+    parallel (1.27.0)
+    parser (3.3.10.2)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    public_suffix (7.0.5)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    regexp_parser (2.11.3)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.85.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-rspec (3.9.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.81)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  lex-cognitive-aurora!
+  rspec (~> 3.13)
+  rubocop (~> 1.75)
+  rubocop-rspec
+
+BUNDLED WITH
+   2.6.9

data/README.md

@@ -0,0 +1,39 @@
+# lex-cognitive-aurora
+
+Emergent beauty and aesthetic pattern detection for the LegionIO cognitive architecture. Detects moments of harmony, elegance, and resonance across cognitive subsystems.
+
+## What It Does
+
+Aurora events model fleeting moments when cognitive subsystems align — bursts of harmony that feel like insight, elegance, or unexpected coherence. The extension tracks these events with luminosity (brightness/intensity) and harmony scores, groups them into spectral bands by type, and provides reports on when and how often cognitive brilliance emerges.
+
+Aurora types include harmonic, resonant, cascading, convergent, emergent, serendipitous, synchronous, and prismatic. Luminosity decays over time; brilliant events (luminosity > 0.8) are preserved as long as possible during pruning.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::CognitiveAurora::Client.new
+
+result = client.detect_aurora(
+  type: :emergent,
+  domain: :memory,
+  contributing_subsystems: [:memory, :emotion],
+  luminosity: 0.85,
+  harmony_score: 0.78
+)
+
+client.list_brilliant(limit: 5)
+client.fade_all
+client.aurora_status
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-aurora.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_aurora/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-aurora'
+  spec.version       = Legion::Extensions::CognitiveAurora::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Aurora'
+  spec.description   = 'Emergent beauty and aesthetic pattern detection for the LegionIO ' \
+                       'cognitive architecture — detects moments of harmony, elegance, and ' \
+                       'resonance across cognitive subsystems'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-aurora'
+  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-aurora'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-cognitive-aurora'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-cognitive-aurora'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-cognitive-aurora/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{\A(?:test|spec|features)/})
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_aurora/helpers/constants'
+require 'legion/extensions/cognitive_aurora/helpers/aurora_event'
+require 'legion/extensions/cognitive_aurora/helpers/spectral_band'
+require 'legion/extensions/cognitive_aurora/helpers/aurora_engine'
+require 'legion/extensions/cognitive_aurora/runners/cognitive_aurora'
+
+module Legion
+  module Extensions
+    module CognitiveAurora
+      class Client
+        include Runners::CognitiveAurora
+
+        def initialize(**)
+          @default_engine = Helpers::AuroraEngine.new
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_aurora/helpers/aurora_engine.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveAurora
+      module Helpers
+        class AuroraEngine
+          include Constants
+
+          def initialize
+            @events = []
+            @spectral_bands = {}
+          end
+
+          def detect_aurora(type:, domain:, contributing_subsystems:, luminosity:, harmony_score:)
+            event = AuroraEvent.new(
+              aurora_type:             type,
+              domain:                  domain,
+              contributing_subsystems: contributing_subsystems,
+              luminosity:              luminosity,
+              harmony_score:           harmony_score
+            )
+
+            prune_events if @events.size >= MAX_EVENTS
+
+            @events << event
+            register_in_band(event)
+            event
+          end
+
+          def fade_all!
+            @events.each(&:fade!)
+          end
+
+          def brilliant_events
+            @events.select(&:brilliant?)
+          end
+
+          def harmonious_events
+            @events.select(&:harmonious?)
+          end
+
+          def events_by_domain(domain)
+            @events.select { |e| e.domain == domain.to_sym }
+          end
+
+          def events_by_type(type)
+            @events.select { |e| e.aurora_type == type.to_sym }
+          end
+
+          def spectral_distribution
+            AURORA_TYPES.each_with_object({}) do |type, dist|
+              band = @spectral_bands[type]
+              dist[type] = band ? band.intensity : 0.0
+            end
+          end
+
+          def overall_luminosity
+            return 0.0 if @events.empty?
+
+            total = @events.sum(&:luminosity).round(10)
+            (total / @events.size).round(10)
+          end
+
+          def overall_harmony
+            return 0.0 if @events.empty?
+
+            total = @events.sum(&:harmony_score).round(10)
+            (total / @events.size).round(10)
+          end
+
+          def aurora_frequency
+            @events.size
+          end
+
+          def most_brilliant(limit: 5)
+            @events.sort_by { |e| -e.luminosity }.first(limit)
+          end
+
+          def active_bands
+            @spectral_bands.values.select(&:active?)
+          end
+
+          def aurora_report
+            {
+              total_events:          @events.size,
+              overall_luminosity:    overall_luminosity,
+              overall_harmony:       overall_harmony,
+              brilliant_count:       brilliant_events.size,
+              harmonious_count:      harmonious_events.size,
+              active_band_count:     active_bands.size,
+              spectral_distribution: spectral_distribution,
+              luminosity_label:      Constants.label_for(overall_luminosity, LUMINOSITY_LABELS),
+              harmony_label:         Constants.label_for(overall_harmony, HARMONY_LABELS)
+            }
+          end
+
+          def events
+            @events.dup
+          end
+
+          private
+
+          def register_in_band(event)
+            type = event.aurora_type
+            @spectral_bands[type] ||= SpectralBand.new(aurora_type: type)
+            @spectral_bands[type].add_event(event)
+          end
+
+          def prune_events
+            faint = @events.select(&:faint?)
+            to_remove = faint.size.positive? ? faint : [@events.first]
+            to_remove.each { |e| @events.delete(e) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_aurora/helpers/aurora_event.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'time'
+
+module Legion
+  module Extensions
+    module CognitiveAurora
+      module Helpers
+        class AuroraEvent
+          include Constants
+
+          attr_reader :id, :aurora_type, :domain, :contributing_subsystems, :harmony_score, :created_at
+          attr_accessor :luminosity
+
+          def initialize(aurora_type:, domain:, contributing_subsystems:, luminosity:, harmony_score:)
+            @id                     = SecureRandom.uuid
+            @aurora_type            = aurora_type
+            @domain                 = domain
+            @contributing_subsystems = Array(contributing_subsystems).map(&:to_sym)
+            @luminosity             = luminosity.clamp(0.0, 1.0)
+            @harmony_score          = harmony_score.clamp(0.0, 1.0)
+            @created_at             = Time.now.utc
+          end
+
+          def fade!
+            @luminosity = (@luminosity - LUMINOSITY_DECAY).round(10).clamp(0.0, 1.0)
+          end
+
+          def brilliant?
+            @luminosity > BRILLIANCE_THRESHOLD
+          end
+
+          def faint?
+            @luminosity < FAINT_THRESHOLD
+          end
+
+          def harmonious?
+            @harmony_score > HARMONY_THRESHOLD
+          end
+
+          def multi_source?
+            @contributing_subsystems.size > 2
+          end
+
+          def spectral_color
+            index = (@luminosity * (SPECTRAL_COLORS.size - 1)).round
+            SPECTRAL_COLORS[index.clamp(0, SPECTRAL_COLORS.size - 1)]
+          end
+
+          def luminosity_label
+            Constants.label_for(@luminosity, LUMINOSITY_LABELS)
+          end
+
+          def harmony_label
+            Constants.label_for(@harmony_score, HARMONY_LABELS)
+          end
+
+          def to_h
+            {
+              id:                      @id,
+              aurora_type:             @aurora_type,
+              domain:                  @domain,
+              contributing_subsystems: @contributing_subsystems,
+              luminosity:              @luminosity,
+              harmony_score:           @harmony_score,
+              spectral_color:          spectral_color,
+              luminosity_label:        luminosity_label,
+              harmony_label:           harmony_label,
+              brilliant:               brilliant?,
+              faint:                   faint?,
+              harmonious:              harmonious?,
+              multi_source:            multi_source?,
+              created_at:              @created_at.iso8601
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveAurora
+      module Helpers
+        module Constants
+          MAX_EVENTS  = 300
+          MAX_BANDS   = 50
+
+          DEFAULT_LUMINOSITY = 0.5
+          LUMINOSITY_DECAY   = 0.03
+          LUMINOSITY_BOOST   = 0.1
+
+          HARMONY_THRESHOLD = 0.7
+          BRILLIANCE_THRESHOLD = 0.8
+          FAINT_THRESHOLD = 0.2
+
+          AURORA_TYPES = %i[
+            harmonic
+            resonant
+            cascading
+            convergent
+            emergent
+            serendipitous
+            synchronous
+            prismatic
+          ].freeze
+
+          SPECTRAL_COLORS = %i[
+            violet
+            indigo
+            blue
+            green
+            yellow
+            orange
+            red
+            ultraviolet
+          ].freeze
+
+          DOMAINS = %i[
+            memory
+            emotion
+            prediction
+            identity
+            trust
+            consent
+            governance
+            perception
+          ].freeze
+
+          LUMINOSITY_LABELS = {
+            (0.0...0.2) => :faint,
+            (0.2...0.4) => :dim,
+            (0.4...0.6) => :moderate,
+            (0.6...0.8) => :bright,
+            (0.8..1.0)  => :brilliant
+          }.freeze
+
+          HARMONY_LABELS = {
+            (0.0...0.3) => :discordant,
+            (0.3...0.5) => :unsettled,
+            (0.5...0.7) => :resonating,
+            (0.7...0.9) => :harmonious,
+            (0.9..1.0)  => :perfect
+          }.freeze
+
+          BRILLIANCE_LABELS = {
+            (0.0...0.25) => :nascent,
+            (0.25...0.5) => :emerging,
+            (0.5...0.75) => :radiant,
+            (0.75..1.0)  => :transcendent
+          }.freeze
+
+          module_function
+
+          def label_for(value, label_map)
+            label_map.each do |range, label|
+              return label if range.cover?(value)
+            end
+            label_map.values.last
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_aurora/helpers/spectral_band.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveAurora
+      module Helpers
+        class SpectralBand
+          include Constants
+
+          attr_reader :id, :aurora_type, :events
+
+          def initialize(aurora_type:)
+            @id          = SecureRandom.uuid
+            @aurora_type = aurora_type
+            @events      = []
+          end
+
+          def add_event(event)
+            @events << event
+          end
+
+          def intensity
+            return 0.0 if @events.empty?
+
+            total = @events.sum(&:luminosity).round(10)
+            (total / @events.size).round(10)
+          end
+
+          def average_harmony
+            return 0.0 if @events.empty?
+
+            total = @events.sum(&:harmony_score).round(10)
+            (total / @events.size).round(10)
+          end
+
+          def dominant_color
+            return SPECTRAL_COLORS.first if @events.empty?
+
+            color_counts = Hash.new(0)
+            @events.each { |e| color_counts[e.spectral_color] += 1 }
+            color_counts.max_by { |_, count| count }&.first || SPECTRAL_COLORS.first
+          end
+
+          def active?
+            @events.any? { |e| !e.faint? }
+          end
+
+          def bandwidth
+            return (0.0..0.0) if @events.empty?
+
+            luminosities = @events.map(&:luminosity)
+            (luminosities.min..luminosities.max)
+          end
+
+          def event_count
+            @events.size
+          end
+
+          def to_h
+            {
+              id:              @id,
+              aurora_type:     @aurora_type,
+              event_count:     event_count,
+              intensity:       intensity,
+              average_harmony: average_harmony,
+              dominant_color:  dominant_color,
+              active:          active?,
+              bandwidth:       { min: bandwidth.min, max: bandwidth.max }
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveAurora
+      module Runners
+        module CognitiveAurora
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def detect_aurora(type: :emergent, domain: :perception, contributing_subsystems: [],
+                            luminosity: Helpers::Constants::DEFAULT_LUMINOSITY,
+                            harmony_score: 0.5, engine: nil, **)
+            target_engine = engine || default_engine
+            event = target_engine.detect_aurora(
+              type:                    type,
+              domain:                  domain,
+              contributing_subsystems: contributing_subsystems,
+              luminosity:              luminosity,
+              harmony_score:           harmony_score
+            )
+
+            Legion::Logging.debug "[cognitive_aurora] detected aurora: type=#{type} domain=#{domain} " \
+                                  "luminosity=#{luminosity.round(2)} harmony=#{harmony_score.round(2)} " \
+                                  "id=#{event.id}"
+
+            { success: true, event: event.to_h }
+          rescue StandardError => e
+            Legion::Logging.error "[cognitive_aurora] detect_aurora failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def fade_all(engine: nil, **)
+            target_engine = engine || default_engine
+            before_count = target_engine.brilliant_events.size
+            target_engine.fade_all!
+            after_count = target_engine.brilliant_events.size
+
+            Legion::Logging.debug "[cognitive_aurora] fade_all: brilliant #{before_count} -> #{after_count}"
+            { success: true, faded: true, brilliant_before: before_count, brilliant_after: after_count }
+          rescue StandardError => e
+            Legion::Logging.error "[cognitive_aurora] fade_all failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def list_brilliant(limit: 10, engine: nil, **)
+            target_engine = engine || default_engine
+            events = target_engine.brilliant_events.sort_by { |e| -e.luminosity }.first(limit)
+
+            Legion::Logging.debug "[cognitive_aurora] list_brilliant: found #{events.size} brilliant events (limit=#{limit})"
+            { success: true, events: events.map(&:to_h), count: events.size }
+          rescue StandardError => e
+            Legion::Logging.error "[cognitive_aurora] list_brilliant failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def aurora_status(engine: nil, **)
+            target_engine = engine || default_engine
+            report = target_engine.aurora_report
+
+            Legion::Logging.debug "[cognitive_aurora] status: total=#{report[:total_events]} " \
+                                  "luminosity=#{report[:overall_luminosity].round(2)} " \
+                                  "harmony=#{report[:overall_harmony].round(2)}"
+
+            { success: true, report: report }
+          rescue StandardError => e
+            Legion::Logging.error "[cognitive_aurora] aurora_status failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          private
+
+          def default_engine
+            @default_engine ||= Helpers::AuroraEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_aurora.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require 'legion/extensions/cognitive_aurora/version'
+require 'legion/extensions/cognitive_aurora/helpers/constants'
+require 'legion/extensions/cognitive_aurora/helpers/aurora_event'
+require 'legion/extensions/cognitive_aurora/helpers/spectral_band'
+require 'legion/extensions/cognitive_aurora/helpers/aurora_engine'
+require 'legion/extensions/cognitive_aurora/runners/cognitive_aurora'
+require 'legion/extensions/cognitive_aurora/client'
+
+module Legion
+  module Extensions
+    module CognitiveAurora
+      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-aurora
+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: Emergent beauty and aesthetic pattern detection for the LegionIO cognitive
+  architecture — detects moments of harmony, elegance, and resonance across cognitive
+  subsystems
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CLAUDE.md
+- Gemfile
+- Gemfile.lock
+- README.md
+- lex-cognitive-aurora.gemspec
+- lib/legion/extensions/cognitive_aurora.rb
+- lib/legion/extensions/cognitive_aurora/client.rb
+- lib/legion/extensions/cognitive_aurora/helpers/aurora_engine.rb
+- lib/legion/extensions/cognitive_aurora/helpers/aurora_event.rb
+- lib/legion/extensions/cognitive_aurora/helpers/constants.rb
+- lib/legion/extensions/cognitive_aurora/helpers/spectral_band.rb
+- lib/legion/extensions/cognitive_aurora/runners/cognitive_aurora.rb
+- lib/legion/extensions/cognitive_aurora/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-aurora
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-aurora
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-aurora
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-aurora
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-aurora
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-aurora/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 Aurora
+test_files: []