lex-cognitive-compass 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: aabc5df25b6e0b4abd5a92508175ad6da5d036b5ce8f245540558f3f1702ab02
+  data.tar.gz: 41b0628f4ddfba105e7deda09d369b5e7f1bd9dba30a695f0b0cb427d42c1c07
+SHA512:
+  metadata.gz: 4b97868fcac953522701fe87cfef7523d0f03fd37541656d77f3f983ba7a390099e29c9aea2fb762df115c61d442de55d209cf4a303fe7f6be8c3e254ef7e437
+  data.tar.gz: 3986bc6d68d324dc34d8b3ef032db800ecb233c9984bc254ee798cc7677bd2bf20b60c2435c5c5f8a79519fb076dbbb1ce6572268a52af12b2f127ec8acf9741

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-compass
+
+**Level 3 Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+- **Grandparent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+Maps cardinal directions to value axes (truth/utility/beauty/safety), tracks magnetic declination from cognitive biases, and provides true north calibration for aligned decision-making. Bearings represent directional assessments toward value axes; biases cause declination that skews bearings away from true north.
+
+## Gem Info
+
+- **Gem name**: `lex-cognitive-compass`
+- **Version**: `0.1.0`
+- **Module**: `Legion::Extensions::CognitiveCompass`
+- **Ruby**: `>= 3.4`
+- **License**: MIT
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_compass/
+  cognitive_compass.rb
+  version.rb
+  client.rb
+  helpers/
+    constants.rb
+    compass_engine.rb
+    bearing.rb
+    magnetic_bias.rb
+  runners/
+    cognitive_compass.rb
+```
+
+## Key Constants
+
+From `helpers/constants.rb`:
+
+- `CARDINAL_DIRECTIONS` — `{ north: :truth, east: :utility, south: :beauty, west: :safety }`
+- `INTERCARDINAL_DIRECTIONS` — `{ northeast: [:truth, :utility], southeast: [:utility, :beauty], southwest: [:beauty, :safety], northwest: [:safety, :truth] }`
+- `BIAS_TYPES` — `%i[confirmation anchoring availability recency authority framing sunk_cost optimism]`
+- `MAX_COMPASSES` = `50`, `MAX_BIASES` = `20`
+- `DECLINATION_DECAY` = `0.02`, `CALIBRATION_BOOST` = `0.15`
+- `ACCURACY_LABELS` — `0.8+` = `:precise`, `0.6` = `:reliable`, `0.4` = `:approximate`, `0.2` = `:drifting`, below = `:lost`
+- `DECLINATION_LABELS` — `0.8+` = `:severe`, `0.6` = `:significant`, `0.4` = `:moderate`, `0.2` = `:mild`, below = `:negligible`
+
+## Runners
+
+All methods in `Runners::CognitiveCompass` (`extend self`):
+
+- `take_bearing(direction:, context:, confidence: nil)` — records a directional assessment toward a value axis; returns `Bearing` with accuracy derived from confidence
+- `register_bias(bias_type:, domain:, declination: nil, strength: nil)` — registers a cognitive bias that causes magnetic declination; validates against `BIAS_TYPES`
+- `calibrate(bias_id:, amount: nil)` — reduces declination on a bias by `CALIBRATION_BOOST` (or custom amount); represents active bias correction
+- `list_bearings(direction: nil)` — all bearings, optionally filtered by direction
+- `list_biases` — all registered biases with current declination
+- `compass_status` — full compass report: bearing distribution, total declination, true north alignment
+
+## Helpers
+
+- `CompassEngine` — manages bearings and biases. `compass_report` computes aggregate: directional distribution, average declination, calibration state.
+- `Bearing` — directional assessment with `direction`, `context`, `confidence`, `accuracy`. `direction` must be a valid cardinal or intercardinal value.
+- `MagneticBias` — cognitive bias with `bias_type`, `domain`, `declination`, `strength`. `calibrate!(amount)` reduces declination. `declination_label` classifies severity.
+
+## Integration Points
+
+- `lex-cognitive-blindspot` tracks unknown-unknowns; compass tracks known value misalignments (biases that are registered and measurable).
+- `lex-tick` action selection phase can check compass bearing toward `:safety` and `:truth` before executing high-stakes decisions — bearings with low accuracy or high declination should trigger deliberate mode.
+- `calibrate` can be called after a `lex-conflict` resolution event, representing bias reduction through adversarial challenge.
+
+## Development Notes
+
+- `CARDINAL_DIRECTIONS` maps direction symbols to value names — north=truth is the primary alignment axis. "True north" metaphor: an unbiased agent points north (toward truth) reliably.
+- Intercardinal directions blend two value axes; callers use these for nuanced assessments (e.g., `northeast` = truth + utility balance).
+- `MAX_BIASES = 20` is intentionally small — too many registered biases suggests the calibration model is incomplete; address biases, don't just log them.
+- `DECLINATION_DECAY = 0.02` models natural bias reduction over time without active calibration (slow passive correction).

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-compass (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-compass!
+  rspec (~> 3.13)
+  rubocop (~> 1.75)
+  rubocop-rspec
+
+BUNDLED WITH
+   2.6.9

data/README.md

@@ -0,0 +1,39 @@
+# lex-cognitive-compass
+
+Cognitive compass LEX — internal directional sense for decision-making. Maps cardinal directions to value axes (truth/utility/beauty/safety), tracks magnetic declination from cognitive biases, and provides true north calibration for aligned decision-making.
+
+## What It Does
+
+Decision-making has a direction — toward truth, utility, beauty, or safety. This extension models an internal compass that takes bearings (directional assessments in context), registers cognitive biases that cause magnetic declination (pulling bearings away from true north), and supports active calibration (reducing bias-driven drift).
+
+Eight bias types are modeled: confirmation, anchoring, availability, recency, authority, framing, sunk cost, and optimism. Intercardinal directions blend two value axes for nuanced assessments.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::CognitiveCompass::Client.new
+
+client.take_bearing(direction: :north, context: 'fact-checking response accuracy', confidence: 0.8)
+client.take_bearing(direction: :west, context: 'evaluating action safety', confidence: 0.7)
+
+bias = client.register_bias(
+  bias_type: :confirmation,
+  domain: :reasoning,
+  declination: 0.6
+)
+
+client.calibrate(bias_id: bias[:bias][:id])  # reduce declination
+client.compass_status
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-compass.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_compass/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-compass'
+  spec.version       = Legion::Extensions::CognitiveCompass::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+  spec.license       = 'MIT'
+
+  spec.summary       = 'Cognitive compass LEX — internal directional sense for decision-making'
+  spec.description   = 'Maps cardinal directions to value axes (truth/utility/beauty/safety), ' \
+                       'tracks magnetic declination from cognitive biases, and provides true ' \
+                       'north calibration for aligned decision-making.'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-compass'
+
+  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_compass/client.rb

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

data/lib/legion/extensions/cognitive_compass/helpers/bearing.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveCompass
+      module Helpers
+        class Bearing
+          attr_reader :id, :direction, :value_axis, :context,
+                      :taken_at
+          attr_accessor :confidence
+
+          def initialize(direction:, context:, confidence: nil)
+            validate_direction!(direction)
+            @id         = SecureRandom.uuid
+            @direction  = direction.to_sym
+            @value_axis = resolve_axis(direction.to_sym)
+            @context    = context.to_s
+            @confidence = (confidence || 0.7).to_f.clamp(0.0, 1.0).round(10)
+            @taken_at   = Time.now.utc
+          end
+
+          def reliable?
+            @confidence >= 0.6
+          end
+
+          def lost?
+            @confidence < 0.2
+          end
+
+          def cardinal?
+            Constants::CARDINAL_DIRECTIONS.key?(@direction)
+          end
+
+          def accuracy_label
+            Constants.label_for(Constants::ACCURACY_LABELS, @confidence)
+          end
+
+          def to_h
+            {
+              id:             @id,
+              direction:      @direction,
+              value_axis:     @value_axis,
+              context:        @context,
+              confidence:     @confidence,
+              accuracy_label: accuracy_label,
+              cardinal:       cardinal?,
+              reliable:       reliable?,
+              lost:           lost?,
+              taken_at:       @taken_at
+            }
+          end
+
+          private
+
+          def resolve_axis(dir)
+            Constants::CARDINAL_DIRECTIONS.fetch(dir) do
+              Constants::INTERCARDINAL_DIRECTIONS.fetch(dir) do
+                raise ArgumentError, "unknown direction: #{dir}"
+              end
+            end
+          end
+
+          def validate_direction!(val)
+            sym = val.to_sym
+            return if Constants::CARDINAL_DIRECTIONS.key?(sym) ||
+                      Constants::INTERCARDINAL_DIRECTIONS.key?(sym)
+
+            raise ArgumentError,
+                  "unknown direction: #{val.inspect}; must be cardinal or intercardinal"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_compass/helpers/compass_engine.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveCompass
+      module Helpers
+        class CompassEngine
+          def initialize
+            @bearings = {}
+            @biases   = {}
+          end
+
+          def take_bearing(direction:, context:, confidence: nil)
+            bearing = Bearing.new(direction: direction, context: context,
+                                  confidence: confidence)
+            @bearings[bearing.id] = bearing
+            bearing
+          end
+
+          def register_bias(bias_type:, domain:, declination: nil, strength: nil)
+            raise ArgumentError, 'too many biases' if @biases.size >= Constants::MAX_BIASES
+
+            bias = MagneticBias.new(bias_type: bias_type, domain: domain,
+                                    declination: declination, strength: strength)
+            @biases[bias.id] = bias
+            bias
+          end
+
+          def calibrate(bias_id:, amount: Constants::CALIBRATION_BOOST)
+            fetch_bias(bias_id).correct!(amount: amount)
+          end
+
+          def true_north_offset
+            return 0.0 if @biases.empty?
+
+            total = @biases.values.sum(&:declination)
+            (total / @biases.size).round(10)
+          end
+
+          def accuracy
+            offset = true_north_offset
+            (1.0 - offset).clamp(0.0, 1.0).round(10)
+          end
+
+          def accuracy_label
+            Constants.label_for(Constants::ACCURACY_LABELS, accuracy)
+          end
+
+          def decay_biases!(rate: Constants::DECLINATION_DECAY)
+            @biases.each_value { |b| b.decay!(rate: rate) }
+            pruned = @biases.select { |_, b| b.negligible? && b.strength < 0.1 }.keys
+            pruned.each { |id| @biases.delete(id) }
+            { remaining: @biases.size, pruned: pruned.size }
+          end
+
+          def dominant_direction
+            return nil if @bearings.empty?
+
+            counts = Hash.new(0)
+            @bearings.each_value { |b| counts[b.direction] += b.confidence }
+            counts.max_by { |_, v| v }&.first
+          end
+
+          def bearings_by_direction
+            result = Hash.new(0)
+            @bearings.each_value { |b| result[b.direction] += 1 }
+            result
+          end
+
+          def strongest_biases(limit: 5)
+            @biases.values.sort_by { |b| -b.strength }.first(limit)
+          end
+
+          def compass_report
+            {
+              total_bearings:     @bearings.size,
+              total_biases:       @biases.size,
+              accuracy:           accuracy,
+              accuracy_label:     accuracy_label,
+              true_north_offset:  true_north_offset,
+              dominant_direction: dominant_direction,
+              by_direction:       bearings_by_direction,
+              severe_biases:      @biases.count { |_, b| b.severe? }
+            }
+          end
+
+          def all_bearings
+            @bearings.values
+          end
+
+          def all_biases
+            @biases.values
+          end
+
+          private
+
+          def fetch_bias(id)
+            @biases.fetch(id) { raise ArgumentError, "bias not found: #{id}" }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveCompass
+      module Helpers
+        module Constants
+          # Cardinal directions mapped to value axes
+          CARDINAL_DIRECTIONS = {
+            north: :truth,
+            east:  :utility,
+            south: :beauty,
+            west:  :safety
+          }.freeze
+
+          # Intercardinal directions (blended values)
+          INTERCARDINAL_DIRECTIONS = {
+            northeast: %i[truth utility],
+            southeast: %i[utility beauty],
+            southwest: %i[beauty safety],
+            northwest: %i[safety truth]
+          }.freeze
+
+          # Bias types that cause magnetic declination
+          BIAS_TYPES = %i[
+            confirmation anchoring availability recency
+            authority framing sunk_cost optimism
+          ].freeze
+
+          MAX_COMPASSES     = 50
+          MAX_BIASES        = 20
+          DECLINATION_DECAY = 0.02
+          CALIBRATION_BOOST = 0.15
+
+          # Bearing accuracy labels
+          ACCURACY_LABELS = [
+            [(0.8..),      :precise],
+            [(0.6...0.8),  :reliable],
+            [(0.4...0.6),  :approximate],
+            [(0.2...0.4),  :drifting],
+            [(..0.2),      :lost]
+          ].freeze
+
+          # Declination severity labels
+          DECLINATION_LABELS = [
+            [(0.8..),      :severe],
+            [(0.6...0.8),  :significant],
+            [(0.4...0.6),  :moderate],
+            [(0.2...0.4),  :mild],
+            [(..0.2),      :negligible]
+          ].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_compass/helpers/magnetic_bias.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveCompass
+      module Helpers
+        class MagneticBias
+          attr_reader :id, :bias_type, :domain, :detected_at
+          attr_accessor :declination, :strength
+
+          def initialize(bias_type:, domain:, declination: nil, strength: nil)
+            validate_bias!(bias_type)
+            @id           = SecureRandom.uuid
+            @bias_type    = bias_type.to_sym
+            @domain       = domain.to_sym
+            @declination  = (declination || 0.3).to_f.clamp(0.0, 1.0).round(10)
+            @strength     = (strength || 0.5).to_f.clamp(0.0, 1.0).round(10)
+            @detected_at  = Time.now.utc
+          end
+
+          def correct!(amount: Constants::CALIBRATION_BOOST)
+            @declination = (@declination - amount.abs).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def intensify!(amount: 0.1)
+            @strength = (@strength + amount.abs).clamp(0.0, 1.0).round(10)
+            @declination = (@declination + (amount.abs * 0.5)).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def decay!(rate: Constants::DECLINATION_DECAY)
+            @strength = (@strength - rate.abs).clamp(0.0, 1.0).round(10)
+            @declination = (@declination - (rate.abs * 0.5)).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def severe?
+            @declination >= 0.8
+          end
+
+          def negligible?
+            @declination < 0.2
+          end
+
+          def declination_label
+            Constants.label_for(Constants::DECLINATION_LABELS, @declination)
+          end
+
+          def to_h
+            {
+              id:                @id,
+              bias_type:         @bias_type,
+              domain:            @domain,
+              declination:       @declination,
+              declination_label: declination_label,
+              strength:          @strength,
+              severe:            severe?,
+              negligible:        negligible?,
+              detected_at:       @detected_at
+            }
+          end
+
+          private
+
+          def validate_bias!(val)
+            return if Constants::BIAS_TYPES.include?(val.to_sym)
+
+            raise ArgumentError,
+                  "unknown bias type: #{val.inspect}; " \
+                  "must be one of #{Constants::BIAS_TYPES.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveCompass
+      module Runners
+        module CognitiveCompass
+          extend self
+
+          def take_bearing(direction:, context:, confidence: nil, engine: nil, **)
+            eng     = resolve_engine(engine)
+            bearing = eng.take_bearing(direction: direction, context: context,
+                                       confidence: confidence)
+            { success: true, bearing: bearing.to_h }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def register_bias(bias_type:, domain:, declination: nil,
+                            strength: nil, engine: nil, **)
+            eng  = resolve_engine(engine)
+            bias = eng.register_bias(bias_type: bias_type, domain: domain,
+                                     declination: declination, strength: strength)
+            { success: true, bias: bias.to_h }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def calibrate(bias_id:, amount: nil, engine: nil, **)
+            eng  = resolve_engine(engine)
+            opts = { bias_id: bias_id }
+            opts[:amount] = amount if amount
+            bias = eng.calibrate(**opts)
+            { success: true, bias: bias.to_h }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def list_bearings(engine: nil, direction: nil, **)
+            eng     = resolve_engine(engine)
+            results = eng.all_bearings
+            results = results.select { |b| b.direction == direction.to_sym } if direction
+            { success: true, bearings: results.map(&:to_h), count: results.size }
+          end
+
+          def list_biases(engine: nil, **)
+            eng = resolve_engine(engine)
+            { success: true, biases: eng.all_biases.map(&:to_h),
+              count: eng.all_biases.size }
+          end
+
+          def compass_status(engine: nil, **)
+            eng = resolve_engine(engine)
+            { success: true, report: eng.compass_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::CompassEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_compass.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require_relative 'cognitive_compass/version'
+require_relative 'cognitive_compass/helpers/constants'
+require_relative 'cognitive_compass/helpers/bearing'
+require_relative 'cognitive_compass/helpers/magnetic_bias'
+require_relative 'cognitive_compass/helpers/compass_engine'
+require_relative 'cognitive_compass/runners/cognitive_compass'
+require_relative 'cognitive_compass/client'
+
+module Legion
+  module Extensions
+    module CognitiveCompass
+      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-compass
+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 cardinal directions to value axes (truth/utility/beauty/safety),
+  tracks magnetic declination from cognitive biases, and provides true north calibration
+  for aligned decision-making.
+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-compass.gemspec
+- lib/legion/extensions/cognitive_compass.rb
+- lib/legion/extensions/cognitive_compass/client.rb
+- lib/legion/extensions/cognitive_compass/helpers/bearing.rb
+- lib/legion/extensions/cognitive_compass/helpers/compass_engine.rb
+- lib/legion/extensions/cognitive_compass/helpers/constants.rb
+- lib/legion/extensions/cognitive_compass/helpers/magnetic_bias.rb
+- lib/legion/extensions/cognitive_compass/runners/cognitive_compass.rb
+- lib/legion/extensions/cognitive_compass/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-compass
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-compass
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-compass
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-compass#readme
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-compass/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-compass/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 compass LEX — internal directional sense for decision-making
+test_files: []