lex-agentic-executive 0.1.0 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d156eef0f39f669acfc3f33e496196921f1b34e882c810d1416740349fc4fb84
-  data.tar.gz: 97171fb40218dca7e06373731545b30e6eadc36a51c649b3e68e75d7e067e509
+  metadata.gz: 23b732c1b95a31e26ca8ac967dc4c6902ab7164afdd5756f8e61ddb9306c86b8
+  data.tar.gz: 2c0de464889108f22b0602433f7d1903a9f46523733e1dc3a644126a34ba70f3
 SHA512:
-  metadata.gz: 97708ee5421c6401db3bd4899e1c0c6f62e059dfe6687d9524327e52b0b7c07ebcae937e8f5da1312467e082d8a56c5123064a0390b696cbbcb2de3b4adbbc72
-  data.tar.gz: 77360d4645be017e164d28feb1420890e990661091261a6dcc0bc15b84f169af3346a3e63af38e71162c079513357d780dffd7b073a43fd0015aa5dc79bc07ea
+  metadata.gz: e5f64ae22b38be241957bfc1fe828ec2060ab4241765e8927353123bfb6af4042997f885ee8a831ffce3680a0f29715859a8509c96d8a853461acc18892c18bd
+  data.tar.gz: 5bc0e25e7e2c76c4ff513337288d47a88b2ef02bc5a5ccdee24f4b2569700b3555b6c1c19a4024656cccfac9d1ceceaa1adccef5fe976f379c69c2dd5a3e62d9

data/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [0.1.3] - 2026-03-21
+
+### Changed
+- Working memory CAPACITY reduced from 7 to 4 (Cowan 2001)
+- Chunking WORKING_MEMORY_CAPACITY updated from 7 to 4
+- Effective max remains 7 via CHUNK_BONUS (4 base + 3 bonus)
+
+## [0.1.1] - 2026-03-18
+
+### Changed
+- Enforce IMPULSE_TYPES validation in InhibitionStore#create_impulse (returns nil for invalid type)
+- Enforce STRATEGIES validation in ResolutionEngine#apply_strategy (returns nil for invalid strategy)
+- Enforce DISENGAGE_REASONS validation in DisengagementEngine#disengage_goal (raises ArgumentError)
+- Enforce DECISION_OUTCOMES validation in DualProcessEngine#record_outcome (returns failure hash)
+
 ## [0.1.0] - 2026-03-18
 
 ### Added

data/README.md

@@ -1,13 +1,60 @@
 # lex-agentic-executive
 
-LEX agentic executive domain: planning, working memory, cognitive control
+Domain consolidation gem for executive function, goal management, planning, and cognitive control. Bundles 23 source extensions into one loadable unit under `Legion::Extensions::Agentic::Executive`.
 
-## Sub-modules
+## Overview
 
-*(populated as extensions are consolidated)*
+**Gem**: `lex-agentic-executive`
+**Version**: 0.1.1
+**Namespace**: `Legion::Extensions::Agentic::Executive`
+
+## Sub-Modules
+
+| Sub-Module | Source Gem | Purpose |
+|---|---|---|
+| `Executive::Control` | `lex-cognitive-control` | Conflict monitoring, error detection, adaptive control signals |
+| `Executive::ExecutiveFunction` | `lex-executive-function` | Miyake three-factor model: updating, flexibility, inhibition |
+| `Executive::GoalManagement` | `lex-goal-management` | Hierarchical goal registry — decomposition, priority, lifecycle |
+| `Executive::Inhibition` | `lex-inhibition` | Stop-signal model, prepotent response suppression |
+| `Executive::Planning` | `lex-planning` | Goal-directed plan management — dependency graphs, replan limit |
+| `Executive::Volition` | `lex-volition` | Five drives synthesized into intention stack — maps to `action_selection` tick phase |
+| `Executive::WorkingMemory` | `lex-working-memory` | Baddeley & Hitch — capacity-limited buffer, verbal/spatial/episodic channels |
+| `Executive::Flexibility` | `lex-cognitive-flexibility` | Cognitive flexibility — task switching, mental set shifting |
+| `Executive::FlexibilityTraining` | `lex-cognitive-flexibility-training` | Structured training for cognitive flexibility improvement |
+| `Executive::Load` | `lex-cognitive-load` | Sweller three-component model — intrinsic/extraneous/germane load |
+| `Executive::LoadBalancing` | `lex-cognitive-load-balancing` | Load distribution across cognitive resources |
+| `Executive::Disengagement` | `lex-cognitive-disengagement` | Controlled disengagement from tasks or mental sets |
+| `Executive::Triage` | `lex-cognitive-triage` | Priority-based task selection under resource constraints |
+| `Executive::Chunking` | `lex-cognitive-chunking` | Information compression into manageable units |
+| `Executive::Inertia` | `lex-cognitive-inertia` | Resistance to switching — persistence in current cognitive mode |
+| `Executive::Dwell` | `lex-cognitive-dwell` | Sustained focus on a single topic or problem |
+| `Executive::Autopilot` | `lex-cognitive-autopilot` | Habitual/automatic processing mode |
+| `Executive::DissonanceResolution` | `lex-cognitive-dissonance-resolution` | Resolution strategies for cognitive dissonance |
+| `Executive::Compass` | `lex-cognitive-compass` | Goal-direction and navigation toward targets |
+| `Executive::DecisionFatigue` | `lex-decision-fatigue` | Decision quality degradation after sustained choices |
+| `Executive::DualProcess` | `lex-dual-process` | Kahneman System 1/System 2 routing |
+| `Executive::ProspectiveMemory` | `lex-prospective-memory` | Memory for future intentions — reminder management |
+| `Executive::CognitiveDebt` | `lex-cognitive-debt` | Accumulated cognitive obligations and deferred processing |
+
+## Actors
+
+- `Executive::ExecutiveFunction::Actors::Recovery` — interval actor, runs executive function recovery cycle
+- `Executive::Flexibility::Actors::Tick` — interval actor, processes cognitive flexibility tick
 
 ## Installation
 
 ```ruby
 gem 'lex-agentic-executive'
 ```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec        # 2067 examples, 0 failures
+bundle exec rubocop      # 0 offenses
+```
+
+## License
+
+MIT

data/lib/legion/extensions/agentic/executive/chunking/helpers/constants.rb

@@ -9,7 +9,7 @@ module Legion
             module Constants
               MAX_ITEMS               = 500
               MAX_CHUNKS              = 200
-              WORKING_MEMORY_CAPACITY = 7    # Miller's magic number
+              WORKING_MEMORY_CAPACITY = 4    # Cowan (2001) core capacity
               CAPACITY_VARIANCE       = 2    # +/- 2
               DEFAULT_COHERENCE       = 0.5
               COHERENCE_BOOST         = 0.08

data/lib/legion/extensions/agentic/executive/disengagement/helpers/disengagement_engine.rb

@@ -42,6 +42,11 @@ module Legion
               end
 
               def disengage_goal(goal_id:, reason:)
+                unless Constants::DISENGAGE_REASONS.include?(reason.to_sym)
+                  raise ArgumentError,
+                        "invalid reason: #{reason.inspect}, must be one of #{Constants::DISENGAGE_REASONS}"
+                end
+
                 goal = fetch_goal!(goal_id)
                 goal.disengage!(reason: reason)
                 goal

data/lib/legion/extensions/agentic/executive/disengagement/version.rb

@@ -5,7 +5,7 @@ module Legion
     module Agentic
       module Executive
         module Disengagement
-          VERSION = '0.1.0'
+          VERSION = '0.1.1'
         end
       end
     end

data/lib/legion/extensions/agentic/executive/dissonance_resolution/helpers/resolution_engine.rb

@@ -32,6 +32,8 @@ module Legion
                 return nil unless conflict
 
                 strat = strategy.to_sym
+                return nil unless STRATEGIES.include?(strat)
+
                 @strategy_history[strat] += 1
                 conflict.apply_strategy!(strategy: strat, effectiveness: effectiveness)
                 @strategy_successes[strat] += 1 if conflict.resolved?

data/lib/legion/extensions/agentic/executive/dissonance_resolution/version.rb

@@ -5,7 +5,7 @@ module Legion
     module Agentic
       module Executive
         module DissonanceResolution
-          VERSION = '0.1.0'
+          VERSION = '0.1.1'
         end
       end
     end

data/lib/legion/extensions/agentic/executive/dual_process/helpers/dual_process_engine.rb

@@ -92,6 +92,8 @@ module Legion
               end
 
               def record_outcome(decision_id:, outcome:)
+                return { success: false, reason: :invalid_outcome } unless Constants::DECISION_OUTCOMES.include?(outcome)
+
                 decision = @decisions.find { |d| d.id == decision_id }
                 return { success: false, reason: :not_found } unless decision
 

data/lib/legion/extensions/agentic/executive/dual_process/version.rb

@@ -5,7 +5,7 @@ module Legion
     module Agentic
       module Executive
         module DualProcess
-          VERSION = '0.1.0'
+          VERSION = '0.1.1'
         end
       end
     end

data/lib/legion/extensions/agentic/executive/inhibition/helpers/inhibition_store.rb

@@ -15,6 +15,8 @@ module Legion
               end
 
               def create_impulse(type:, action:, strength:, source: nil, context: {})
+                return nil unless Constants::IMPULSE_TYPES.include?(type.to_sym)
+
                 resolved_strength = resolve_strength(strength)
 
                 impulse = Impulse.new(

data/lib/legion/extensions/agentic/executive/inhibition/version.rb

@@ -5,7 +5,7 @@ module Legion
     module Agentic
       module Executive
         module Inhibition
-          VERSION = '0.1.0'
+          VERSION = '0.1.1'
         end
       end
     end

data/lib/legion/extensions/agentic/executive/version.rb

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Agentic
       module Executive
-        VERSION = '0.1.0'
+        VERSION = '0.1.4'
       end
     end
   end

data/lib/legion/extensions/agentic/executive/volition/runners/volition.rb

@@ -76,6 +76,38 @@ module Legion
                 { status: result, intention_id: intention_id }
               end
 
+              def form_absorption_intention(domains_at_risk:, neighboring_agents: [], severity: :warning, **)
+                domains = Array(domains_at_risk)
+                neighbors = Array(neighboring_agents)
+
+                return { success: false, reason: :no_domains } if domains.empty?
+
+                base_salience = severity.to_sym == :critical ? 0.85 : 0.55
+                salience = [base_salience + (domains.size * 0.05), 1.0].min
+
+                intention = Helpers::Intention.new_intention(
+                  drive:    :epistemic,
+                  domain:   :knowledge,
+                  goal:     "absorb knowledge for domains: #{domains.join(', ')}",
+                  salience: salience,
+                  context:  { domains_at_risk: domains, target_agents: neighbors, severity: severity,
+                             triggered_by: :knowledge_vulnerability }
+                )
+
+                result = intention_stack.push(intention)
+                Legion::Logging.info "[volition] absorption intention formed: domains=#{domains.join(',')} " \
+                                     "neighbors=#{neighbors.size} salience=#{salience.round(2)} result=#{result}"
+
+                {
+                  success:      %i[pushed duplicate].include?(result),
+                  result:       result,
+                  intention_id: intention[:intention_id],
+                  salience:     salience,
+                  domains:      domains,
+                  targets:      neighbors
+                }
+              end
+
               def volition_status(**)
                 stats = intention_stack.stats
                 drives = Helpers::DriveSynthesizer.synthesize(tick_results: {}, cognitive_state: {})

data/lib/legion/extensions/agentic/executive/working_memory/helpers/constants.rb

@@ -7,7 +7,7 @@ module Legion
         module WorkingMemory
           module Helpers
             module Constants
-              CAPACITY = 7
+              CAPACITY = 4
 
               CHUNK_BONUS = 3
 

data/lib/legion/extensions/agentic/executive/working_memory/version.rb

@@ -5,7 +5,7 @@ module Legion
     module Agentic
       module Executive
         module WorkingMemory
-          VERSION = '0.1.0'
+          VERSION = '0.1.1'
         end
       end
     end

data/spec/legion/extensions/agentic/executive/chunking/helpers/chunking_engine_spec.rb

@@ -174,7 +174,7 @@ RSpec.describe Legion::Extensions::Agentic::Executive::Chunking::Helpers::Chunki
       id = engine.add_item(content: 'x')[:item_id]
       cid = engine.create_chunk(label: 'x', item_ids: [id])[:chunk_id]
       engine.load_to_working_memory(chunk_id: cid)
-      expected = (1.0 / 7).round(10)
+      expected = (1.0 / 4).round(10)
       expect(engine.working_memory_load).to be_within(0.0001).of(expected)
     end
   end

data/spec/legion/extensions/agentic/executive/chunking/helpers/constants_spec.rb

@@ -10,8 +10,8 @@ RSpec.describe Legion::Extensions::Agentic::Executive::Chunking::Helpers::Consta
       expect(described_class::MAX_CHUNKS).to eq(200)
     end
 
-    it 'defines WORKING_MEMORY_CAPACITY as 7' do
-      expect(described_class::WORKING_MEMORY_CAPACITY).to eq(7)
+    it 'defines WORKING_MEMORY_CAPACITY as 4' do
+      expect(described_class::WORKING_MEMORY_CAPACITY).to eq(4)
     end
 
     it 'defines CAPACITY_VARIANCE as 2' do

data/spec/legion/extensions/agentic/executive/chunking/runners/cognitive_chunking_spec.rb

@@ -97,7 +97,7 @@ RSpec.describe Legion::Extensions::Agentic::Executive::Chunking::Runners::Cognit
     it 'returns success with capacity info' do
       result = client.working_memory_status(engine: engine)
       expect(result[:success]).to be true
-      expect(result[:capacity]).to eq(7)
+      expect(result[:capacity]).to eq(4)
     end
 
     it 'returns a capacity label' do

data/spec/legion/extensions/agentic/executive/disengagement/helpers/disengagement_engine_spec.rb

@@ -77,6 +77,19 @@ RSpec.describe Legion::Extensions::Agentic::Executive::Disengagement::Helpers::D
       expect { engine.disengage_goal(goal_id: 'nope', reason: :sunk_cost) }
         .to raise_error(ArgumentError)
     end
+
+    it 'raises ArgumentError for invalid reason' do
+      expect { engine.disengage_goal(goal_id: goal.id, reason: :boredom) }
+        .to raise_error(ArgumentError, /invalid reason/)
+    end
+
+    it 'accepts all valid DISENGAGE_REASONS' do
+      constants = Legion::Extensions::Agentic::Executive::Disengagement::Helpers::Constants
+      constants::DISENGAGE_REASONS.each do |reason|
+        g = engine.create_goal(label: "goal_#{reason}", domain: :test)
+        expect { engine.disengage_goal(goal_id: g.id, reason: reason) }.not_to raise_error
+      end
+    end
   end
 
   describe '#stalled_goals' do

data/spec/legion/extensions/agentic/executive/dissonance_resolution/helpers/resolution_engine_spec.rb

@@ -29,6 +29,19 @@ RSpec.describe Legion::Extensions::Agentic::Executive::DissonanceResolution::Hel
       reframe = report.find { |s| s[:strategy] == :reframe }
       expect(reframe[:uses]).to eq(1)
     end
+
+    it 'rejects invalid strategy' do
+      expect(engine.apply_strategy(conflict_id: conflict.id, strategy: :magic)).to be_nil
+    end
+
+    it 'accepts all valid STRATEGIES' do
+      constants = Legion::Extensions::Agentic::Executive::DissonanceResolution::Helpers::Constants
+      constants::STRATEGIES.each do |strat|
+        c = engine.create_conflict(belief_a: 'a', belief_b: 'b')
+        result = engine.apply_strategy(conflict_id: c.id, strategy: strat)
+        expect(result).not_to be_nil
+      end
+    end
   end
 
   describe '#escalate_conflict' do

data/spec/legion/extensions/agentic/executive/dual_process/helpers/dual_process_engine_spec.rb

@@ -165,6 +165,21 @@ RSpec.describe Legion::Extensions::Agentic::Executive::DualProcess::Helpers::Dua
       expect(result[:success]).to be false
       expect(result[:reason]).to eq(:not_found)
     end
+
+    it 'rejects invalid outcome' do
+      result = engine.record_outcome(decision_id: decision_id, outcome: :maybe)
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:invalid_outcome)
+    end
+
+    it 'accepts all valid DECISION_OUTCOMES' do
+      constants = Legion::Extensions::Agentic::Executive::DualProcess::Helpers::Constants
+      constants::DECISION_OUTCOMES.each do |out|
+        did = engine.execute_system_one(query: "test_#{out}", domain: :work)[:decision_id]
+        result = engine.record_outcome(decision_id: did, outcome: out)
+        expect(result[:success]).to be true
+      end
+    end
   end
 
   describe '#effort_level' do

data/spec/legion/extensions/agentic/executive/inhibition/helpers/inhibition_store_spec.rb

@@ -55,6 +55,18 @@ RSpec.describe Legion::Extensions::Agentic::Executive::Inhibition::Helpers::Inhi
       impulse = store.create_impulse(type: :reactive, action: :act, strength: :unknown_level)
       expect(impulse.strength).to eq(Legion::Extensions::Agentic::Executive::Inhibition::Helpers::Constants::IMPULSE_STRENGTHS[:moderate])
     end
+
+    it 'rejects invalid impulse type' do
+      expect(store.create_impulse(type: :telepathic, action: :act, strength: :moderate)).to be_nil
+    end
+
+    it 'accepts all valid IMPULSE_TYPES' do
+      constants = Legion::Extensions::Agentic::Executive::Inhibition::Helpers::Constants
+      constants::IMPULSE_TYPES.each do |itype|
+        result = store.create_impulse(type: itype, action: :act, strength: :moderate)
+        expect(result).not_to be_nil
+      end
+    end
   end
 
   describe '#evaluate_and_apply' do

data/spec/legion/extensions/agentic/executive/volition/runners/volition_spec.rb

@@ -132,4 +132,59 @@ RSpec.describe Legion::Extensions::Agentic::Executive::Volition::Runners::Voliti
       expect(result[:count]).to be >= 1
     end
   end
+
+  describe '#form_absorption_intention' do
+    it 'returns success false when no domains provided' do
+      result = client.form_absorption_intention(domains_at_risk: [])
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:no_domains)
+    end
+
+    it 'pushes an epistemic absorption intention onto the stack' do
+      result = client.form_absorption_intention(
+        domains_at_risk:    %w[pki dns],
+        neighboring_agents: %w[agent-b agent-c]
+      )
+      expect(result[:success]).to be true
+      expect(result[:result]).to eq(:pushed)
+      expect(result[:domains]).to eq(%w[pki dns])
+      expect(result[:targets]).to eq(%w[agent-b agent-c])
+    end
+
+    it 'returns the intention_id' do
+      result = client.form_absorption_intention(domains_at_risk: ['vault'])
+      expect(result[:intention_id]).to be_a(String)
+    end
+
+    it 'assigns higher salience for critical severity' do
+      warning = client.form_absorption_intention(
+        domains_at_risk: ['pki'], severity: :warning
+      )
+      critical_client = Legion::Extensions::Agentic::Executive::Volition::Client.new
+      critical = critical_client.form_absorption_intention(
+        domains_at_risk: ['pki'], severity: :critical
+      )
+      expect(critical[:salience]).to be > warning[:salience]
+    end
+
+    it 'scales salience with number of at-risk domains' do
+      few = client.form_absorption_intention(domains_at_risk: ['pki'])
+      many_client = Legion::Extensions::Agentic::Executive::Volition::Client.new
+      many = many_client.form_absorption_intention(domains_at_risk: %w[pki dns vault ssh consul nomad])
+      expect(many[:salience]).to be >= few[:salience]
+    end
+
+    it 'stores knowledge_vulnerability trigger context' do
+      result = client.form_absorption_intention(domains_at_risk: ['pki'])
+      intention = client.intention_stack.find(result[:intention_id])
+      expect(intention[:context][:triggered_by]).to eq(:knowledge_vulnerability)
+    end
+
+    it 'returns :duplicate on second call for same domains (capacity protection)' do
+      client.form_absorption_intention(domains_at_risk: ['pki'])
+      second = client.form_absorption_intention(domains_at_risk: ['pki'])
+      # Either duplicate (same drive/domain/goal match) or pushed — both acceptable
+      expect(%i[pushed duplicate]).to include(second[:result])
+    end
+  end
 end

data/spec/legion/extensions/agentic/executive/working_memory/client_spec.rb

@@ -71,10 +71,10 @@ RSpec.describe Legion::Extensions::Agentic::Executive::WorkingMemory::Client do
       expect(client.working_memory_stats[:size]).to eq(0)
     end
 
-    it 'models the 7 plus-or-minus 2 capacity limit' do
+    it 'models the 4 plus-or-minus 2 capacity limit' do
       # Fill to base capacity
-      7.times { |i| client.store_item(content: "item #{i}", priority: :normal) }
-      expect(client.buffer.size).to eq(7)
+      4.times { |i| client.store_item(content: "item #{i}", priority: :normal) }
+      expect(client.buffer.size).to eq(4)
 
       # Without chunking, adding more evicts lowest activation
       3.times { |i| client.store_item(content: "overflow #{i}", priority: :high) }

data/spec/legion/extensions/agentic/executive/working_memory/helpers/constants_spec.rb

@@ -4,8 +4,8 @@ require 'spec_helper'
 
 RSpec.describe Legion::Extensions::Agentic::Executive::WorkingMemory::Helpers::Constants do
   describe 'CAPACITY' do
-    it 'is 7 (Miller\'s Law)' do
-      expect(described_class::CAPACITY).to eq(7)
+    it 'is 4 (Cowan 2001)' do
+      expect(described_class::CAPACITY).to eq(4)
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-agentic-executive
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.4
 platform: ruby
 authors:
 - Esity