lex-cognitive-constellation 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 420b47a6be614c2a1ab6c4b0f6ca074baac0e63d6fe1791b6845b617261602bc
+  data.tar.gz: 7071398b68ea8d56d0b39999a07de7b7c2e49aea66705cf17e8a0f0b370edae6
+SHA512:
+  metadata.gz: 3d48b04e425054702f7e0cfa8b83cfb4b676dda3c526afbe9eae74c1d966ef54db35d87c19985601afc7f035c08263fe8e550fcd1c8c61d8c740b5d0183a4fb5
+  data.tar.gz: 73de52721a9825aa606982f2770cd83813e0038f58edef196c4c030a317a6c2cdeb6a8f64bbb66d4debef820994c7d4e879863ea016f47a490c3b73340e98c0e

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,3 @@
+--require spec_helper
+--format documentation
+--color

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,75 @@
+# lex-cognitive-constellation
+
+**Level 3 Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+- **Grandparent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+Maps ideas as stars with magnitude and spectral class, groups them into constellations with pattern types, and enables celestial navigation between related concepts across cognitive domains. Provides a spatial metaphor for knowledge organization and cross-domain traversal.
+
+## Gem Info
+
+- **Gem name**: `lex-cognitive-constellation`
+- **Version**: `0.1.0`
+- **Module**: `Legion::Extensions::CognitiveConstellation`
+- **Ruby**: `>= 3.4`
+- **License**: MIT
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_constellation/
+  cognitive_constellation.rb
+  version.rb
+  client.rb
+  helpers/
+    constants.rb
+    sky_engine.rb
+    star.rb
+    constellation.rb
+  runners/
+    cognitive_constellation.rb
+```
+
+## Key Constants
+
+From `helpers/constants.rb`:
+
+- `SPECTRAL_CLASSES` — `%i[O B A F G K M]` (hottest to coolest — maps to idea intensity/age)
+- `PATTERN_TYPES` — `%i[linear circular spiral cluster cross arc ring scattered]`
+- `DOMAINS` — `%i[reasoning memory emotion language perception action planning social creativity logic intuition ethics]`
+- `MAX_STARS` = `500`, `MAX_CONSTELLATIONS` = `50`
+- `MAGNITUDE_DECAY` = `0.01`, `MIN_MAGNITUDE` = `0.05`
+- `MAGNITUDE_LABELS` — `0.8+` = `:supergiant`, `0.6` = `:giant`, `0.4` = `:main_sequence`, `0.2` = `:dwarf`, below = `:brown_dwarf`
+- `MATURITY_LABELS` — `0.8+` = `:ancient`, `0.6` = `:established`, `0.4` = `:forming`, `0.2` = `:nascent`, below = `:proto`
+
+## Runners
+
+All methods in `Runners::CognitiveConstellation` (`extend self`):
+
+- `discover_star(name:, domain:, content:, magnitude: nil, spectral_class: nil)` — registers a new concept as a star; magnitude and spectral class are optional
+- `form_constellation(name:, pattern_type:, star_ids: [])` — groups stars into a named constellation with a pattern type
+- `navigate(from_star_id:, target_domain:)` — finds reachable stars in the target domain starting from the source star
+- `list_stars(domain: nil)` — all stars, optionally filtered by domain
+- `list_constellations` — all constellations
+- `sky_status` — full sky report: star count, constellation count, brightest stars, domain distribution
+
+## Helpers
+
+- `SkyEngine` — manages `@stars` and `@constellations`. `navigate` traverses star connections to find domain-adjacent concepts.
+- `Star` — has `name`, `domain`, `content`, `magnitude`, `spectral_class`. `magnitude` decays over time if not reinforced. `magnitude_label` classifies brightness.
+- `Constellation` — named grouping of star IDs with `pattern_type` and maturity score derived from number of member stars and their average magnitude.
+
+## Integration Points
+
+- `lex-memory` traces have domains; stars map those domains into a navigable spatial structure — cross-domain navigation via `navigate` mirrors `walk_associations` in `lex-dream`.
+- `lex-cognitive-aurora` detects harmony events across domains; constellations are the structural groupings that make aurora detection meaningful (aurora fires when constellation members align).
+- `MAGNITUDE_DECAY` means unused concepts fade from the sky — magnitude is an attention proxy.
+
+## Development Notes
+
+- `discover_star` and `form_constellation` raise `ArgumentError` on invalid inputs; runners catch these and return `{ success: false, error: e.message }`.
+- `navigate` is BFS or similarity-based traversal starting from a known star, targeting a domain. The depth and algorithm are internal to `SkyEngine`.
+- `spectral_class` follows the OBAFGKM Harvard classification, repurposed as an idea intensity/age proxy. `:O` = hot/young/intense; `:M` = cool/old/stable.
+- Constellations do not need member stars at creation time — `star_ids: []` is valid. Stars can be added later.

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,78 @@
+PATH
+  remote: .
+  specs:
+    lex-cognitive-constellation (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-constellation!
+  rspec (~> 3.13)
+  rubocop (~> 1.75)
+  rubocop-rspec
+
+BUNDLED WITH
+   2.6.9

data/README.md

@@ -0,0 +1,51 @@
+# lex-cognitive-constellation
+
+Cognitive constellation LEX — star-mapping for concepts. Maps ideas as stars with magnitude and spectral class, groups them into constellations with pattern types, and enables celestial navigation between related concepts across cognitive domains.
+
+## What It Does
+
+Ideas are stars: some are supergiants (high magnitude, highly salient), others are brown dwarfs (faint, nearly forgotten). Related ideas form constellations — linear, circular, spiral, cluster, cross, arc, ring, or scattered patterns. Navigation between stars enables cross-domain traversal: starting from a known concept and finding related concepts in a target domain.
+
+Magnitude decays over time, modeling the natural fading of unused ideas from active consideration.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::CognitiveConstellation::Client.new
+
+star1 = client.discover_star(
+  name: 'trust_anchoring',
+  domain: :reasoning,
+  content: 'initial trust scores anchor all subsequent assessments',
+  magnitude: 0.8,
+  spectral_class: :G
+)
+
+star2 = client.discover_star(
+  name: 'anchoring_bias',
+  domain: :reasoning,
+  content: 'first information received disproportionately weights judgment',
+  magnitude: 0.7
+)
+
+client.form_constellation(
+  name: 'anchoring_cluster',
+  pattern_type: :cluster,
+  star_ids: [star1[:star][:id], star2[:star][:id]]
+)
+
+client.navigate(from_star_id: star1[:star][:id], target_domain: :emotion)
+client.sky_status
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-constellation.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_constellation/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-constellation'
+  spec.version       = Legion::Extensions::CognitiveConstellation::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+  spec.license       = 'MIT'
+
+  spec.summary       = 'Cognitive constellation LEX — star-mapping for concepts'
+  spec.description   = 'Maps ideas as stars with magnitude and spectral class, groups them into ' \
+                       'constellations with pattern types, and enables celestial navigation between ' \
+                       'related concepts across cognitive domains.'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-constellation'
+
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']      = spec.homepage
+  spec.metadata['source_code_uri']   = spec.homepage
+  spec.metadata['documentation_uri'] = "#{spec.homepage}#readme"
+  spec.metadata['changelog_uri']     = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['bug_tracker_uri']   = "#{spec.homepage}/issues"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject { |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_constellation/client.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveConstellation
+      class Client
+        include Runners::CognitiveConstellation
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveConstellation
+      module Helpers
+        module Constants
+          # Star spectral classes (hottest to coolest)
+          SPECTRAL_CLASSES = %i[O B A F G K M].freeze
+
+          # Constellation pattern types
+          PATTERN_TYPES = %i[
+            linear circular spiral cluster
+            cross arc ring scattered
+          ].freeze
+
+          # Star domains
+          DOMAINS = %i[
+            reasoning memory emotion language
+            perception action planning social
+            creativity logic intuition ethics
+          ].freeze
+
+          MAX_STARS          = 500
+          MAX_CONSTELLATIONS = 50
+          MAGNITUDE_DECAY    = 0.01
+          MIN_MAGNITUDE      = 0.05
+
+          # Magnitude labels (higher = brighter = more important)
+          MAGNITUDE_LABELS = [
+            [(0.8..),      :supergiant],
+            [(0.6...0.8),  :giant],
+            [(0.4...0.6),  :main_sequence],
+            [(0.2...0.4),  :dwarf],
+            [(..0.2),      :brown_dwarf]
+          ].freeze
+
+          # Constellation maturity labels
+          MATURITY_LABELS = [
+            [(0.8..),      :ancient],
+            [(0.6...0.8),  :established],
+            [(0.4...0.6),  :forming],
+            [(0.2...0.4),  :nascent],
+            [(..0.2),      :proto]
+          ].freeze
+
+          def self.label_for(table, value)
+            table.each { |range, label| return label if range.cover?(value) }
+            table.last.last
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_constellation/helpers/constellation.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveConstellation
+      module Helpers
+        class Constellation
+          attr_reader :id, :name, :pattern_type, :star_ids,
+                      :formed_at
+          attr_accessor :maturity
+
+          def initialize(name:, pattern_type:, maturity: nil)
+            validate_pattern!(pattern_type)
+            @id           = SecureRandom.uuid
+            @name         = name.to_s
+            @pattern_type = pattern_type.to_sym
+            @star_ids     = []
+            @maturity     = (maturity || 0.1).to_f.clamp(0.0, 1.0).round(10)
+            @formed_at    = Time.now.utc
+          end
+
+          def add_star(star_id)
+            return false if @star_ids.include?(star_id)
+
+            @star_ids << star_id
+            @maturity = (@maturity + 0.05).clamp(0.0, 1.0).round(10)
+            true
+          end
+
+          def remove_star(star_id)
+            return false unless @star_ids.include?(star_id)
+
+            @star_ids.delete(star_id)
+            @maturity = (@maturity - 0.05).clamp(0.0, 1.0).round(10)
+            true
+          end
+
+          def size
+            @star_ids.size
+          end
+
+          def empty?
+            @star_ids.empty?
+          end
+
+          def ancient?
+            @maturity >= 0.8
+          end
+
+          def nascent?
+            @maturity < 0.2
+          end
+
+          def maturity_label
+            Constants.label_for(Constants::MATURITY_LABELS, @maturity)
+          end
+
+          def to_h
+            {
+              id:             @id,
+              name:           @name,
+              pattern_type:   @pattern_type,
+              star_ids:       @star_ids.dup,
+              size:           size,
+              maturity:       @maturity,
+              maturity_label: maturity_label,
+              formed_at:      @formed_at,
+              ancient:        ancient?,
+              nascent:        nascent?
+            }
+          end
+
+          private
+
+          def validate_pattern!(val)
+            return if Constants::PATTERN_TYPES.include?(val.to_sym)
+
+            raise ArgumentError,
+                  "unknown pattern type: #{val.inspect}; " \
+                  "must be one of #{Constants::PATTERN_TYPES.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_constellation/helpers/sky_engine.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveConstellation
+      module Helpers
+        class SkyEngine
+          def initialize
+            @stars          = {}
+            @constellations = {}
+          end
+
+          def discover_star(name:, domain:, content:, magnitude: nil, spectral_class: nil)
+            raise ArgumentError, 'sky catalog full' if @stars.size >= Constants::MAX_STARS
+
+            star = Star.new(name: name, domain: domain, content: content,
+                            magnitude: magnitude, spectral_class: spectral_class)
+            @stars[star.id] = star
+            star
+          end
+
+          def form_constellation(name:, pattern_type:, star_ids: [])
+            raise ArgumentError, 'too many constellations' if @constellations.size >= Constants::MAX_CONSTELLATIONS
+
+            constellation = Constellation.new(name: name, pattern_type: pattern_type)
+            @constellations[constellation.id] = constellation
+
+            star_ids.each { |sid| link_star(star_id: sid, constellation_id: constellation.id) }
+            constellation
+          end
+
+          def link_star(star_id:, constellation_id:)
+            star = fetch_star(star_id)
+            constellation = fetch_constellation(constellation_id)
+
+            constellation.add_star(star_id)
+            star.join_constellation(constellation_id)
+          end
+
+          def brighten_star(star_id:, boost: 0.1)
+            fetch_star(star_id).brighten!(boost: boost)
+          end
+
+          def dim_all!(rate: Constants::MAGNITUDE_DECAY)
+            @stars.each_value { |s| s.dim!(rate: rate) }
+            pruned = @stars.select { |_, s| s.magnitude < Constants::MIN_MAGNITUDE }.keys
+            pruned.each { |id| remove_star(id) }
+            { remaining: @stars.size, pruned: pruned.size }
+          end
+
+          def navigate(from_star_id:, target_domain:)
+            from = fetch_star(from_star_id)
+            shared = from.constellation_ids.flat_map do |cid|
+              fetch_constellation(cid).star_ids
+            end.uniq - [from_star_id]
+
+            shared.filter_map { |sid| @stars[sid] }
+                  .select { |s| s.domain == target_domain.to_sym }
+                  .sort_by { |s| -s.magnitude }
+          end
+
+          def stars_by_domain
+            counts = Constants::DOMAINS.to_h { |d| [d, 0] }
+            @stars.each_value { |s| counts[s.domain] += 1 }
+            counts
+          end
+
+          def brightest(limit: 5)
+            @stars.values.sort_by { |s| -s.magnitude }.first(limit)
+          end
+
+          def faintest(limit: 5)
+            @stars.values.sort_by(&:magnitude).first(limit)
+          end
+
+          def largest_constellations(limit: 5)
+            @constellations.values.sort_by { |c| -c.size }.first(limit)
+          end
+
+          def sky_report
+            {
+              total_stars:          @stars.size,
+              total_constellations: @constellations.size,
+              by_domain:            stars_by_domain,
+              supergiants:          @stars.count { |_, s| s.supergiant? },
+              fading:               @stars.count { |_, s| s.fading? },
+              avg_magnitude:        avg_magnitude
+            }
+          end
+
+          def all_stars
+            @stars.values
+          end
+
+          def all_constellations
+            @constellations.values
+          end
+
+          private
+
+          def fetch_star(id)
+            @stars.fetch(id) { raise ArgumentError, "star not found: #{id}" }
+          end
+
+          def fetch_constellation(id)
+            @constellations.fetch(id) { raise ArgumentError, "constellation not found: #{id}" }
+          end
+
+          def remove_star(id)
+            star = @stars.delete(id)
+            return unless star
+
+            star.constellation_ids.each do |cid|
+              @constellations[cid]&.remove_star(id)
+            end
+          end
+
+          def avg_magnitude
+            return 0.0 if @stars.empty?
+
+            (@stars.values.sum(&:magnitude) / @stars.size).round(10)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_constellation/helpers/star.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveConstellation
+      module Helpers
+        class Star
+          attr_reader :id, :name, :domain, :content, :spectral_class,
+                      :discovered_at, :constellation_ids
+          attr_accessor :magnitude
+
+          def initialize(name:, domain:, content:,
+                         magnitude: nil, spectral_class: nil)
+            validate_domain!(domain)
+            assign_core(name, domain, content)
+            assign_metadata(magnitude, spectral_class)
+          end
+
+          def dim!(rate: Constants::MAGNITUDE_DECAY)
+            @magnitude = (@magnitude - rate.abs).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def brighten!(boost: 0.1)
+            @magnitude = (@magnitude + boost.abs).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def supergiant?
+            @magnitude >= 0.8
+          end
+
+          def fading?
+            @magnitude < 0.2
+          end
+
+          def join_constellation(constellation_id)
+            @constellation_ids << constellation_id unless @constellation_ids.include?(constellation_id)
+          end
+
+          def magnitude_label
+            Constants.label_for(Constants::MAGNITUDE_LABELS, @magnitude)
+          end
+
+          def to_h
+            {
+              id:                @id,
+              name:              @name,
+              domain:            @domain,
+              content:           @content,
+              spectral_class:    @spectral_class,
+              magnitude:         @magnitude,
+              magnitude_label:   magnitude_label,
+              discovered_at:     @discovered_at,
+              constellation_ids: @constellation_ids,
+              supergiant:        supergiant?,
+              fading:            fading?
+            }
+          end
+
+          private
+
+          def assign_core(name, domain, content)
+            @id      = SecureRandom.uuid
+            @name    = name.to_s
+            @domain  = domain.to_sym
+            @content = content.to_s
+          end
+
+          def assign_metadata(magnitude, spectral_class)
+            @magnitude         = (magnitude || 0.5).to_f.clamp(0.0, 1.0).round(10)
+            @spectral_class    = (spectral_class || Constants::SPECTRAL_CLASSES.sample).to_sym
+            @discovered_at     = Time.now.utc
+            @constellation_ids = []
+          end
+
+          def validate_domain!(val)
+            return if Constants::DOMAINS.include?(val.to_sym)
+
+            raise ArgumentError,
+                  "unknown domain: #{val.inspect}; " \
+                  "must be one of #{Constants::DOMAINS.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveConstellation
+      module Runners
+        module CognitiveConstellation
+          extend self
+
+          def discover_star(name:, domain:, content:,
+                            magnitude: nil, spectral_class: nil, engine: nil, **)
+            eng  = resolve_engine(engine)
+            star = eng.discover_star(name: name, domain: domain, content: content,
+                                     magnitude: magnitude, spectral_class: spectral_class)
+            { success: true, star: star.to_h }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def form_constellation(name:, pattern_type:, star_ids: [], engine: nil, **)
+            eng = resolve_engine(engine)
+            con = eng.form_constellation(name: name, pattern_type: pattern_type,
+                                         star_ids: star_ids)
+            { success: true, constellation: con.to_h }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def navigate(from_star_id:, target_domain:, engine: nil, **)
+            eng     = resolve_engine(engine)
+            results = eng.navigate(from_star_id:  from_star_id,
+                                   target_domain: target_domain)
+            { success: true, stars: results.map(&:to_h), count: results.size }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def list_stars(engine: nil, domain: nil, **)
+            eng     = resolve_engine(engine)
+            results = eng.all_stars
+            results = results.select { |s| s.domain == domain.to_sym } if domain
+            { success: true, stars: results.map(&:to_h), count: results.size }
+          end
+
+          def list_constellations(engine: nil, **)
+            eng = resolve_engine(engine)
+            { success:        true,
+              constellations: eng.all_constellations.map(&:to_h),
+              count:          eng.all_constellations.size }
+          end
+
+          def sky_status(engine: nil, **)
+            eng = resolve_engine(engine)
+            { success: true, report: eng.sky_report }
+          end
+
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+          private
+
+          def resolve_engine(engine)
+            engine || default_engine
+          end
+
+          def default_engine
+            @default_engine ||= Helpers::SkyEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_constellation.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require_relative 'cognitive_constellation/version'
+require_relative 'cognitive_constellation/helpers/constants'
+require_relative 'cognitive_constellation/helpers/star'
+require_relative 'cognitive_constellation/helpers/constellation'
+require_relative 'cognitive_constellation/helpers/sky_engine'
+require_relative 'cognitive_constellation/runners/cognitive_constellation'
+require_relative 'cognitive_constellation/client'
+
+module Legion
+  module Extensions
+    module CognitiveConstellation
+      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-constellation
+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: Maps ideas as stars with magnitude and spectral class, groups them into
+  constellations with pattern types, and enables celestial navigation between related
+  concepts across cognitive domains.
+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-constellation.gemspec
+- lib/legion/extensions/cognitive_constellation.rb
+- lib/legion/extensions/cognitive_constellation/client.rb
+- lib/legion/extensions/cognitive_constellation/helpers/constants.rb
+- lib/legion/extensions/cognitive_constellation/helpers/constellation.rb
+- lib/legion/extensions/cognitive_constellation/helpers/sky_engine.rb
+- lib/legion/extensions/cognitive_constellation/helpers/star.rb
+- lib/legion/extensions/cognitive_constellation/runners/cognitive_constellation.rb
+- lib/legion/extensions/cognitive_constellation/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-constellation
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-constellation
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-constellation
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-constellation#readme
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-constellation/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-constellation/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: Cognitive constellation LEX — star-mapping for concepts
+test_files: []