lex-cognitive-phantom 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6b3ee604853dcc9f14a6d0d0d97fd23f8766ece92475d5abc06257139552b22c
+  data.tar.gz: 87bcb8aa7479fa4155c610e3969fdb667cee1b2f9962c3a7fd6e1f8c82ea69c7
+SHA512:
+  metadata.gz: 61f7abd1e3575004f8f7d3153b8b9838159b0662bc10ab6f9343876edcbd514cc5d6efd4685d428b17fe2beb2a61d9092fb02acb49364e6faccddf02d9258a51
+  data.tar.gz: e2356291933cea4b484e8b7fa8f239cd53d5bf7f7f0714c5c945d3dfa5eefbae24509ed12a60e0de306b6f4d46014c09e73d891239d7b5da18b525ea8dd765ee

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,12 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+Gemfile.lock

data/.rspec

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

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: 1500
+
+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,86 @@
+# lex-cognitive-phantom
+
+**Level 3 Leaf Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+
+## Purpose
+
+Phantom limb metaphor for removed cognitive capabilities. When a capability (tool, permission, access, skill, memory, context, etc.) is removed from the agent, a `PhantomLimb` is created representing the lingering ghost signal. Intensity decays over time; incoming stimuli that match the phantom's capability type trigger the phantom and slightly boost intensity. States progress from `acute` → `adapting` → `residual` → `resolved` as intensity decays.
+
+## Gem Info
+
+- **Gem name**: `lex-cognitive-phantom`
+- **Module**: `Legion::Extensions::CognitivePhantom`
+- **Version**: `0.1.0`
+- **Ruby**: `>= 3.4`
+- **License**: MIT
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_phantom/
+  version.rb
+  client.rb
+  helpers/
+    constants.rb
+    phantom_limb.rb
+  runners/
+    cognitive_phantom.rb
+```
+
+## Key Constants
+
+| Constant | Value | Purpose |
+|---|---|---|
+| `MAX_PHANTOMS` | `100` | Per-engine phantom capacity |
+| `INITIAL_INTENSITY` | `0.8` | Intensity when a phantom is first created |
+| `INTENSITY_DECAY` | `0.05` | Per-cycle intensity decay |
+| `MIN_INTENSITY` | `0.01` | Below this intensity, phantom is resolved |
+| `PHANTOM_STATES` | `%i[acute adapting residual resolved]` | Lifecycle states |
+| `TRIGGER_TYPES` | symbol array | Valid trigger categories (e.g., `:stimulus_match`, `:context_reminder`) |
+| `STATE_THRESHOLDS` | hash | Intensity thresholds per state |
+| `PHANTOM_LABELS` | range hash | Phantom intensity labels |
+
+## Helpers
+
+### `Helpers::PhantomLimb`
+Individual phantom record. Has `id`, `capability_type`, `domain`, `content`, `intensity`, `signals` (array of `PhantomSignal`), `trigger_count`, and `resolved_at`.
+
+- `trigger!(stimulus)` — classifies trigger type from stimulus, boosts intensity by 5% of remaining headroom, creates `PhantomSignal` record
+- `decay!` — reduces intensity by `INTENSITY_DECAY`; sets `resolved_at` if intensity drops to `MIN_INTENSITY`
+- `adapt!` — applies 2.5× decay rate (accelerated adaptation)
+- `resolved?` — intensity <= `MIN_INTENSITY`
+- `state` — returns `:acute` (>= 0.6), `:adapting` (>= 0.3), `:residual` (> MIN), or `:resolved`
+- `intensity` — current signal intensity
+
+### `PhantomSignal` (inline value object)
+Immutable record of a trigger event: `trigger_type`, `stimulus`, and `occurred_at`.
+
+## Runners
+
+Module: `Runners::CognitivePhantom`
+
+| Runner Method | Description |
+|---|---|
+| `register_removal(capability_type:, domain:, content:)` | Register a removed capability as a phantom |
+| `process_stimulus(phantom_id:, stimulus:)` | Process incoming stimulus against phantom |
+| `acknowledge_phantom(phantom_id:)` | Apply accelerated adaptation (adapt!) |
+| `phantom_status` | Aggregate phantom report |
+| `decay_all` | Apply standard decay to all phantoms; prune resolved ones |
+
+All runners return `{success: true/false, ...}` hashes.
+
+## Integration Points
+
+- `lex-extinction` level 1/2 operations: when capabilities are removed by an extinction protocol, register them as phantoms
+- `lex-tick` `action_selection`: check for triggered phantoms before executing actions that require the removed capability
+- `lex-emotion`: acute phantoms contribute negative valence; resolved phantoms are a positive signal
+- `lex-identity`: phantom signals reflect behavioral pattern disruption — high trigger count phantoms affect behavioral fingerprint
+
+## Development Notes
+
+- `Client` instantiates `@phantom_engine = Helpers::PhantomEngine.new`
+- `trigger!` boost is small (5% of headroom) to prevent re-escalation to acute state from residual
+- `adapt!` applies 2.5× decay — allows the agent to explicitly accelerate acceptance of capability loss
+- `decay_all` removes resolved phantoms from memory (garbage collection)
+- `INITIAL_INTENSITY = 0.8` models the immediate strong signal when something important is removed; starting intensity below `PHANTOM_STATES` `:acute` threshold (0.6) would bypass the acute state

data/Gemfile

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

data/Gemfile.lock

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

data/README.md

@@ -0,0 +1,53 @@
+# lex-cognitive-phantom
+
+Phantom limb model for removed cognitive capabilities in LegionIO agents. When a capability is removed, a phantom is registered with high initial intensity. Intensity decays over time; matching stimuli trigger the phantom; acknowledging it accelerates adaptation.
+
+## What It Does
+
+- Register removed capabilities (tool, permission, memory, context, skill, etc.) as phantoms
+- Initial intensity: 0.8 (acute state)
+- Four states: acute (>= 0.6) → adapting (>= 0.3) → residual (> 0.01) → resolved
+- Incoming stimuli trigger the phantom (small intensity boost + signal record)
+- `acknowledge_phantom` applies 2.5× decay for accelerated adaptation
+- Standard decay (INTENSITY_DECAY = 0.05/cycle) runs via `decay_all`
+- Resolved phantoms are pruned from memory automatically
+
+## Usage
+
+```ruby
+# Register a removed capability
+result = runner.register_removal(
+  capability_type: :tool_access, domain: :operations,
+  content: 'database write permission removed by governance'
+)
+phantom_id = result[:phantom][:id]
+
+# Process a stimulus that touches the removed capability
+runner.process_stimulus(phantom_id: phantom_id,
+                         stimulus: 'attempted to write to DB')
+# => { success: true, triggered: true, intensity: 0.81, trigger_type: :stimulus_match, state: :acute }
+
+# Acknowledge to accelerate adaptation
+runner.acknowledge_phantom(phantom_id: phantom_id)
+# => { success: true, phantom: { intensity: 0.68, state: :adapting } }
+
+# Apply standard decay each tick
+runner.decay_all
+# => { success: true, decayed: 1, resolved: 0 }
+
+# Overall status
+runner.phantom_status
+# => { success: true, total: 1, acute: 0, adapting: 1, residual: 0, resolved: 0 }
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-phantom.gemspec

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_phantom/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-phantom'
+  spec.version       = Legion::Extensions::CognitivePhantom::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Phantom'
+  spec.description   = 'Phantom limb model for AI: ghost signals from removed capabilities fade over time as the agent adapts'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-phantom'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']      = 'https://github.com/LegionIO/lex-cognitive-phantom'
+  spec.metadata['source_code_uri']   = 'https://github.com/LegionIO/lex-cognitive-phantom'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-cognitive-phantom'
+  spec.metadata['changelog_uri']     = 'https://github.com/LegionIO/lex-cognitive-phantom'
+  spec.metadata['bug_tracker_uri']   = 'https://github.com/LegionIO/lex-cognitive-phantom/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_phantom/helpers/constants'
+require 'legion/extensions/cognitive_phantom/helpers/phantom_signal'
+require 'legion/extensions/cognitive_phantom/helpers/phantom_limb'
+require 'legion/extensions/cognitive_phantom/helpers/phantom_engine'
+require 'legion/extensions/cognitive_phantom/runners/cognitive_phantom'
+
+module Legion
+  module Extensions
+    module CognitivePhantom
+      class Client
+        include Runners::CognitivePhantom
+
+        def initialize(**)
+          @phantom_engine = Helpers::PhantomEngine.new
+        end
+
+        private
+
+        attr_reader :phantom_engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitivePhantom
+      module Helpers
+        module Constants
+          MAX_PHANTOMS = 100
+          INITIAL_INTENSITY = 0.8
+          INTENSITY_DECAY   = 0.05
+          MIN_INTENSITY     = 0.01
+
+          PHANTOM_STATES = %i[acute adapting residual resolved].freeze
+          TRIGGER_TYPES  = %i[stimulus_match contextual_association temporal_pattern habitual].freeze
+
+          STATE_THRESHOLDS = {
+            acute:    0.6,
+            adapting: 0.3,
+            residual: MIN_INTENSITY
+          }.freeze
+
+          PHANTOM_LABELS = {
+            acute:    'Active phantom — strong ghost signals firing',
+            adapting: 'Adapting — agent learning to cope with absence',
+            residual: 'Residual — faint ghost signals, near resolution',
+            resolved: 'Resolved — phantom fully integrated and silent'
+          }.freeze
+
+          module_function
+
+          def label_for(state)
+            PHANTOM_LABELS.fetch(state, 'Unknown state')
+          end
+
+          def state_for(intensity)
+            if intensity >= STATE_THRESHOLDS[:acute]
+              :acute
+            elsif intensity >= STATE_THRESHOLDS[:adapting]
+              :adapting
+            elsif intensity > MIN_INTENSITY
+              :residual
+            else
+              :resolved
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_phantom/helpers/phantom_engine.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitivePhantom
+      module Helpers
+        class PhantomEngine
+          def initialize
+            @phantoms = {}
+          end
+
+          def register_removal(capability_name:, capability_domain: :general)
+            if @phantoms.size >= Constants::MAX_PHANTOMS
+              Legion::Logging.warn "[cognitive_phantom] MAX_PHANTOMS (#{Constants::MAX_PHANTOMS}) reached, skipping #{capability_name}"
+              return nil
+            end
+
+            limb = PhantomLimb.new(capability_name: capability_name, capability_domain: capability_domain)
+            @phantoms[limb.id] = limb
+            Legion::Logging.info "[cognitive_phantom] registered phantom: capability=#{capability_name} domain=#{capability_domain} id=#{limb.id[0..7]}"
+            limb
+          end
+
+          def process_stimulus(stimulus:, domain: :general)
+            fired = []
+            @phantoms.each_value do |limb|
+              next if limb.resolved?
+              next unless domain_match?(limb, domain)
+
+              signal = limb.trigger!(stimulus)
+              next unless signal
+
+              fired << signal
+              intensity_str = limb.intensity.round(3).to_s
+              Legion::Logging.debug "[cognitive_phantom] phantom fired: cap=#{limb.capability_name} trigger=#{signal.trigger_type} i=#{intensity_str}"
+            end
+            fired
+          end
+
+          def decay_all!
+            @phantoms.each_value(&:decay!)
+            resolve_check!
+          end
+
+          def acknowledge(phantom_id:)
+            limb = @phantoms[phantom_id]
+            return { acknowledged: false, reason: :not_found } unless limb
+
+            limb.adapt!
+            Legion::Logging.info "[cognitive_phantom] acknowledged phantom id=#{phantom_id[0..7]} intensity=#{limb.intensity.round(3)} state=#{limb.state}"
+            { acknowledged: true, phantom_id: phantom_id, state: limb.state, intensity: limb.intensity }
+          end
+
+          def all_phantoms
+            @phantoms.values
+          end
+
+          def active_phantoms
+            @phantoms.values.reject(&:resolved?)
+          end
+
+          def phantom_activity_report
+            all = @phantoms.values
+            by_state = Constants::PHANTOM_STATES.to_h { |s| [s, all.count { |p| p.state == s }] }
+            {
+              total:             all.size,
+              active:            active_phantoms.size,
+              by_state:          by_state,
+              total_activations: all.sum(&:activation_count)
+            }
+          end
+
+          def most_persistent(limit: 5)
+            active_phantoms.sort_by(&:activation_count).last(limit).reverse
+          end
+
+          def recently_triggered(limit: 5)
+            active_phantoms
+              .select(&:last_triggered)
+              .sort_by(&:last_triggered)
+              .last(limit)
+              .reverse
+          end
+
+          def resolve_check!
+            newly_resolved = @phantoms.values.select(&:resolved?)
+            newly_resolved.each do |limb|
+              Legion::Logging.info "[cognitive_phantom] resolved: capability=#{limb.capability_name} activations=#{limb.activation_count}"
+            end
+            newly_resolved.size
+          end
+
+          private
+
+          def domain_match?(limb, domain)
+            domain == :any || limb.capability_domain == domain || limb.capability_domain == :general
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_phantom/helpers/phantom_limb.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitivePhantom
+      module Helpers
+        class PhantomLimb
+          ADAPT_DECAY_MULTIPLIER = 2.5
+
+          attr_reader :id, :capability_name, :capability_domain, :removed_at,
+                      :activation_count, :last_triggered, :trigger_history
+
+          def initialize(capability_name:, capability_domain:)
+            @id                 = SecureRandom.uuid
+            @capability_name    = capability_name
+            @capability_domain  = capability_domain
+            @removed_at         = Time.now.utc
+            @intensity          = Constants::INITIAL_INTENSITY
+            @activation_count   = 0
+            @last_triggered     = nil
+            @trigger_history    = []
+          end
+
+          def intensity
+            @intensity.round(10)
+          end
+
+          def state
+            Constants.state_for(@intensity)
+          end
+
+          def trigger!(stimulus)
+            return false if resolved?
+
+            @activation_count += 1
+            prev_triggered = @last_triggered
+            @last_triggered = Time.now.utc
+            signal = PhantomSignal.new(
+              phantom_limb_id:      @id,
+              stimulus:             stimulus,
+              trigger_type:         classify_trigger(stimulus, prev_triggered),
+              intensity_at_trigger: @intensity
+            )
+            @trigger_history << signal
+            @trigger_history.shift while @trigger_history.size > 50
+            boost = (@intensity * 0.05).clamp(0.0, 0.1)
+            @intensity = (@intensity + boost).clamp(Constants::MIN_INTENSITY, 1.0)
+            signal
+          end
+
+          def decay!
+            return if resolved?
+
+            @intensity = (@intensity - Constants::INTENSITY_DECAY).clamp(Constants::MIN_INTENSITY, 1.0)
+          end
+
+          def adapt!
+            return if resolved?
+
+            accelerated = Constants::INTENSITY_DECAY * ADAPT_DECAY_MULTIPLIER
+            @intensity  = (@intensity - accelerated).clamp(Constants::MIN_INTENSITY, 1.0)
+          end
+
+          def resolved?
+            @intensity <= Constants::MIN_INTENSITY
+          end
+
+          def to_h
+            {
+              id:                @id,
+              capability_name:   @capability_name,
+              capability_domain: @capability_domain,
+              removed_at:        @removed_at,
+              intensity:         intensity,
+              activation_count:  @activation_count,
+              last_triggered:    @last_triggered,
+              state:             state,
+              resolved:          resolved?
+            }
+          end
+
+          private
+
+          def classify_trigger(stimulus, prev_triggered)
+            return :stimulus_match if stimulus.is_a?(String) && stimulus.include?(@capability_name.to_s)
+
+            return :temporal_pattern if prev_triggered && (Time.now.utc - prev_triggered) < 60
+
+            return :habitual if @activation_count > 10
+
+            :contextual_association
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_phantom/helpers/phantom_signal.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitivePhantom
+      module Helpers
+        class PhantomSignal
+          attr_reader :id, :phantom_limb_id, :stimulus, :trigger_type,
+                      :intensity_at_trigger, :timestamp
+
+          def initialize(phantom_limb_id:, stimulus:, trigger_type:, intensity_at_trigger:)
+            @id                  = SecureRandom.uuid
+            @phantom_limb_id     = phantom_limb_id
+            @stimulus            = stimulus
+            @trigger_type        = trigger_type
+            @intensity_at_trigger = intensity_at_trigger.clamp(0.0, 1.0)
+            @timestamp = Time.now.utc
+          end
+
+          def to_h
+            {
+              id:                   @id,
+              phantom_limb_id:      @phantom_limb_id,
+              stimulus:             @stimulus,
+              trigger_type:         @trigger_type,
+              intensity_at_trigger: @intensity_at_trigger.round(10),
+              timestamp:            @timestamp
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitivePhantom
+      module Runners
+        module CognitivePhantom
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def register_removal(capability_name:, capability_domain: :general, engine: nil, **)
+            raise ArgumentError, 'capability_name is required' if capability_name.nil? || capability_name.to_s.strip.empty?
+
+            eng  = engine || phantom_engine
+            limb = eng.register_removal(capability_name: capability_name, capability_domain: capability_domain)
+            return { success: false, error: 'MAX_PHANTOMS limit reached' } unless limb
+
+            Legion::Logging.debug "[cognitive_phantom] register_removal capability=#{capability_name}"
+            { success: true, phantom_id: limb.id, capability_name: capability_name, state: limb.state, intensity: limb.intensity }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def process_stimulus(stimulus:, domain: :general, engine: nil, **)
+            raise ArgumentError, 'stimulus is required' if stimulus.nil?
+
+            eng    = engine || phantom_engine
+            fired  = eng.process_stimulus(stimulus: stimulus, domain: domain)
+            Legion::Logging.debug "[cognitive_phantom] process_stimulus domain=#{domain} fired=#{fired.size}"
+            {
+              success:     true,
+              fired_count: fired.size,
+              signals:     fired.map(&:to_h),
+              domain:      domain
+            }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def acknowledge_phantom(phantom_id:, engine: nil, **)
+            raise ArgumentError, 'phantom_id is required' if phantom_id.nil? || phantom_id.to_s.strip.empty?
+
+            eng    = engine || phantom_engine
+            result = eng.acknowledge(phantom_id: phantom_id)
+            Legion::Logging.debug "[cognitive_phantom] acknowledge phantom_id=#{phantom_id[0..7]}"
+            result.merge(success: result[:acknowledged])
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def phantom_status(engine: nil, **)
+            eng    = engine || phantom_engine
+            report = eng.phantom_activity_report
+            Legion::Logging.debug "[cognitive_phantom] phantom_status total=#{report[:total]} active=#{report[:active]}"
+            { success: true, **report }
+          end
+
+          def decay_all(engine: nil, **)
+            eng = engine || phantom_engine
+            resolved_count = eng.decay_all!
+            report = eng.phantom_activity_report
+            Legion::Logging.debug "[cognitive_phantom] decay_all resolved=#{resolved_count}"
+            { success: true, resolved_this_cycle: resolved_count, **report }
+          end
+
+          private
+
+          def phantom_engine
+            @phantom_engine ||= Helpers::PhantomEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_phantom.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'legion/extensions/cognitive_phantom/version'
+require 'legion/extensions/cognitive_phantom/helpers/constants'
+require 'legion/extensions/cognitive_phantom/helpers/phantom_signal'
+require 'legion/extensions/cognitive_phantom/helpers/phantom_limb'
+require 'legion/extensions/cognitive_phantom/helpers/phantom_engine'
+require 'legion/extensions/cognitive_phantom/runners/cognitive_phantom'
+
+module Legion
+  module Extensions
+    module CognitivePhantom
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: lex-cognitive-phantom
+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: 'Phantom limb model for AI: ghost signals from removed capabilities fade
+  over time as the agent adapts'
+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-phantom.gemspec
+- lib/legion/extensions/cognitive_phantom.rb
+- lib/legion/extensions/cognitive_phantom/client.rb
+- lib/legion/extensions/cognitive_phantom/helpers/constants.rb
+- lib/legion/extensions/cognitive_phantom/helpers/phantom_engine.rb
+- lib/legion/extensions/cognitive_phantom/helpers/phantom_limb.rb
+- lib/legion/extensions/cognitive_phantom/helpers/phantom_signal.rb
+- lib/legion/extensions/cognitive_phantom/runners/cognitive_phantom.rb
+- lib/legion/extensions/cognitive_phantom/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-phantom
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-phantom
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-phantom
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-phantom
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-phantom
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-phantom/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 Phantom
+test_files: []