lex-agentic-executive 0.1.0

data/spec/legion/extensions/agentic/executive/triage/runners_spec.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Executive::Triage::Runners::CognitiveTriage do
+  let(:engine) { Legion::Extensions::Agentic::Executive::Triage::Helpers::TriageEngine.new }
+  let(:runner) do
+    obj = Object.new
+    obj.extend(described_class)
+    obj.instance_variable_set(:@default_engine, engine)
+    obj
+  end
+
+  describe '#add_demand' do
+    it 'returns success with demand hash' do
+      result = runner.add_demand(description: 'urgent fix', severity: :critical, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:demand][:severity]).to eq(:critical)
+    end
+
+    it 'includes current capacity' do
+      result = runner.add_demand(description: 'test', engine: engine)
+      expect(result[:capacity]).to be_between(0.0, 1.0)
+    end
+  end
+
+  describe '#process_demand' do
+    it 'returns success for active demand' do
+      demand = engine.add_demand(description: 'test')
+      result = runner.process_demand(demand_id: demand.id, engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns failure for unknown demand' do
+      result = runner.process_demand(demand_id: 'bad', engine: engine)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#complete_demand' do
+    it 'returns success with capacity' do
+      demand = engine.add_demand(description: 'test')
+      result = runner.complete_demand(demand_id: demand.id, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:capacity]).to be_a(Float)
+    end
+  end
+
+  describe '#defer_demand' do
+    it 'returns success' do
+      demand = engine.add_demand(description: 'test')
+      result = runner.defer_demand(demand_id: demand.id, engine: engine)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#drop_demand' do
+    it 'returns success' do
+      demand = engine.add_demand(description: 'test')
+      result = runner.drop_demand(demand_id: demand.id, engine: engine)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#next_demand' do
+    it 'returns found: false when empty' do
+      result = runner.next_demand(engine: engine)
+      expect(result[:found]).to be false
+    end
+
+    it 'returns the highest priority demand' do
+      engine.add_demand(description: 'low', severity: :trivial)
+      engine.add_demand(description: 'high', severity: :critical, urgency: :immediate)
+      result = runner.next_demand(engine: engine)
+      expect(result[:found]).to be true
+      expect(result[:demand][:severity]).to eq(:critical)
+    end
+  end
+
+  describe '#active_demands' do
+    it 'returns active demands list' do
+      engine.add_demand(description: 'test')
+      result = runner.active_demands(engine: engine)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#red_demands' do
+    it 'returns red demands' do
+      engine.add_demand(description: 'red', severity: :critical, urgency: :immediate)
+      result = runner.red_demands(engine: engine)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#demands_by_severity' do
+    it 'filters correctly' do
+      engine.add_demand(description: 'a', severity: :critical)
+      engine.add_demand(description: 'b', severity: :trivial)
+      result = runner.demands_by_severity(severity: :critical, engine: engine)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#demands_by_domain' do
+    it 'filters correctly' do
+      engine.add_demand(description: 'a', domain: :security)
+      result = runner.demands_by_domain(domain: :security, engine: engine)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#capacity_status' do
+    it 'returns capacity info' do
+      result = runner.capacity_status(engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:capacity]).to eq(1.0)
+      expect(result[:overloaded]).to be false
+    end
+  end
+
+  describe '#triage_report' do
+    it 'returns comprehensive report' do
+      result = runner.triage_report(engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:report]).to include(:total_demands, :capacity)
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Executive::Volition::Client do
+  subject(:client) { described_class.new }
+
+  it 'initializes with a default intention stack' do
+    expect(client.intention_stack).to be_a(Legion::Extensions::Agentic::Executive::Volition::Helpers::IntentionStack)
+  end
+
+  it 'accepts an injected stack' do
+    custom = Legion::Extensions::Agentic::Executive::Volition::Helpers::IntentionStack.new
+    client = described_class.new(stack: custom)
+    expect(client.intention_stack).to be(custom)
+  end
+
+  it 'includes the Volition runner' do
+    expect(client).to respond_to(:form_intentions)
+    expect(client).to respond_to(:current_intention)
+    expect(client).to respond_to(:complete_intention)
+    expect(client).to respond_to(:suspend_intention)
+    expect(client).to respond_to(:resume_intention)
+    expect(client).to respond_to(:volition_status)
+    expect(client).to respond_to(:intention_history)
+  end
+end

data/spec/legion/extensions/agentic/executive/volition/helpers/drive_synthesizer_spec.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Executive::Volition::Helpers::DriveSynthesizer do
+  let(:synth) { described_class }
+
+  describe '.synthesize' do
+    it 'returns all five drives' do
+      drives = synth.synthesize(tick_results: {}, cognitive_state: {})
+      expect(drives).to have_key(:curiosity)
+      expect(drives).to have_key(:corrective)
+      expect(drives).to have_key(:urgency)
+      expect(drives).to have_key(:epistemic)
+      expect(drives).to have_key(:social)
+    end
+
+    it 'all drives are between 0 and 1' do
+      drives = synth.synthesize(
+        tick_results:    { emotional_evaluation: { arousal: 0.9 }, gut_instinct: { signal: :alarm } },
+        cognitive_state: { curiosity: { intensity: 0.9, active_count: 10 } }
+      )
+      drives.each_value { |v| expect(v).to be_between(0.0, 1.0) }
+    end
+  end
+
+  describe '.compute_curiosity_drive' do
+    it 'increases with curiosity intensity' do
+      low = synth.compute_curiosity_drive({}, { curiosity: { intensity: 0.1, active_count: 0 } })
+      high = synth.compute_curiosity_drive({}, { curiosity: { intensity: 0.9, active_count: 5 } })
+      expect(high).to be > low
+    end
+  end
+
+  describe '.compute_corrective_drive' do
+    it 'increases with low health and pending adaptations' do
+      healthy = synth.compute_corrective_drive({ reflection: { health: 0.95, pending_adaptations: 0 } })
+      unhealthy = synth.compute_corrective_drive({ reflection: { health: 0.4, pending_adaptations: 3 } })
+      expect(unhealthy).to be > healthy
+    end
+  end
+
+  describe '.compute_urgency_drive' do
+    it 'increases with high arousal and alarm gut signal' do
+      calm = synth.compute_urgency_drive({ emotional_evaluation: { arousal: 0.2 }, gut_instinct: { signal: :calm } }, {})
+      urgent = synth.compute_urgency_drive({ emotional_evaluation: { arousal: 0.9 }, gut_instinct: { signal: :alarm } }, {})
+      expect(urgent).to be > calm
+    end
+  end
+
+  describe '.compute_epistemic_drive' do
+    it 'increases with low prediction confidence' do
+      confident = synth.compute_epistemic_drive({ prediction_engine: { confidence: 0.9 } }, {})
+      uncertain = synth.compute_epistemic_drive({ prediction_engine: { confidence: 0.2 } }, {})
+      expect(uncertain).to be > confident
+    end
+  end
+
+  describe '.compute_social_drive' do
+    it 'increases with peer count and trust' do
+      alone = synth.compute_social_drive({ mesh: { peer_count: 0 }, trust: { avg_composite: 0.2 } })
+      social = synth.compute_social_drive({ mesh: { peer_count: 5 }, trust: { avg_composite: 0.8 } })
+      expect(social).to be > alone
+    end
+  end
+
+  describe '.dominant_drive' do
+    it 'returns the strongest drive' do
+      drives = { curiosity: 0.8, corrective: 0.3, urgency: 0.5, epistemic: 0.2, social: 0.1 }
+      expect(synth.dominant_drive(drives)).to eq(:curiosity)
+    end
+
+    it 'returns nil for empty drives' do
+      expect(synth.dominant_drive({})).to be_nil
+    end
+  end
+
+  describe '.generate_intentions' do
+    it 'generates intentions for drives above threshold' do
+      drives = { curiosity: 0.8, corrective: 0.05, urgency: 0.6, epistemic: 0.02, social: 0.01 }
+      intentions = synth.generate_intentions(drives)
+      expect(intentions.size).to eq(2) # curiosity and urgency above 0.15
+      expect(intentions.first[:salience]).to be >= intentions.last[:salience]
+    end
+
+    it 'returns empty for all drives below threshold' do
+      drives = { curiosity: 0.05, corrective: 0.01, urgency: 0.02, epistemic: 0.01, social: 0.01 }
+      expect(synth.generate_intentions(drives)).to be_empty
+    end
+  end
+
+  describe '.extract_gut_strength' do
+    it 'maps gut signal symbols to numeric strength' do
+      expect(synth.extract_gut_strength({ signal: :alarm })).to eq(1.0)
+      expect(synth.extract_gut_strength({ signal: :heightened })).to eq(0.7)
+      expect(synth.extract_gut_strength({ signal: :calm })).to eq(0.1)
+      expect(synth.extract_gut_strength({ signal: :neutral })).to eq(0.3)
+      expect(synth.extract_gut_strength({})).to eq(0.3)
+    end
+  end
+end

data/spec/legion/extensions/agentic/executive/volition/helpers/intention_spec.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Executive::Volition::Helpers::Intention do
+  let(:helper) { described_class }
+
+  describe '.new_intention' do
+    it 'creates an intention with required fields' do
+      intention = helper.new_intention(drive: :curiosity, domain: :terraform, goal: 'explore gaps', salience: 0.7)
+      expect(intention[:intention_id]).to be_a(String)
+      expect(intention[:drive]).to eq(:curiosity)
+      expect(intention[:domain]).to eq(:terraform)
+      expect(intention[:goal]).to eq('explore gaps')
+      expect(intention[:salience]).to eq(0.7)
+      expect(intention[:state]).to eq(:active)
+      expect(intention[:age_ticks]).to eq(0)
+    end
+
+    it 'clamps salience to [0.0, 1.0]' do
+      high = helper.new_intention(drive: :urgency, domain: :general, goal: 'respond', salience: 1.5)
+      low = helper.new_intention(drive: :urgency, domain: :general, goal: 'respond', salience: -0.5)
+      expect(high[:salience]).to eq(1.0)
+      expect(low[:salience]).to eq(0.0)
+    end
+  end
+
+  describe '.decay' do
+    it 'reduces salience and increments age' do
+      intention = helper.new_intention(drive: :curiosity, domain: :general, goal: 'test', salience: 0.5)
+      decayed = helper.decay(intention)
+      expect(decayed[:salience]).to be < 0.5
+      expect(decayed[:age_ticks]).to eq(1)
+    end
+
+    it 'floors at 0.0' do
+      intention = helper.new_intention(drive: :curiosity, domain: :general, goal: 'test', salience: 0.01)
+      decayed = helper.decay(intention)
+      expect(decayed[:salience]).to eq(0.0)
+    end
+  end
+
+  describe '.reinforce' do
+    it 'increases salience' do
+      intention = helper.new_intention(drive: :curiosity, domain: :general, goal: 'test', salience: 0.5)
+      reinforced = helper.reinforce(intention, amount: 0.2)
+      expect(reinforced[:salience]).to eq(0.7)
+    end
+
+    it 'caps at 1.0' do
+      intention = helper.new_intention(drive: :curiosity, domain: :general, goal: 'test', salience: 0.9)
+      reinforced = helper.reinforce(intention, amount: 0.5)
+      expect(reinforced[:salience]).to eq(1.0)
+    end
+  end
+
+  describe '.expired?' do
+    it 'returns true when salience below floor' do
+      intention = helper.new_intention(drive: :curiosity, domain: :general, goal: 'test', salience: 0.05)
+      expect(helper.expired?(intention)).to be true
+    end
+
+    it 'returns true when age exceeds max' do
+      intention = helper.new_intention(drive: :curiosity, domain: :general, goal: 'test', salience: 0.8)
+      intention[:age_ticks] = 101
+      expect(helper.expired?(intention)).to be true
+    end
+
+    it 'returns false for fresh intention' do
+      intention = helper.new_intention(drive: :curiosity, domain: :general, goal: 'test', salience: 0.5)
+      expect(helper.expired?(intention)).to be false
+    end
+  end
+
+  describe '.active?' do
+    it 'returns true for active non-expired intentions' do
+      intention = helper.new_intention(drive: :curiosity, domain: :general, goal: 'test', salience: 0.5)
+      expect(helper.active?(intention)).to be true
+    end
+
+    it 'returns false for completed intentions' do
+      intention = helper.new_intention(drive: :curiosity, domain: :general, goal: 'test', salience: 0.5)
+      intention[:state] = :completed
+      expect(helper.active?(intention)).to be false
+    end
+  end
+
+  describe '.drive_label' do
+    it 'returns human-readable labels' do
+      expect(helper.drive_label(:curiosity)).to eq('knowledge seeking')
+      expect(helper.drive_label(:corrective)).to eq('self-improvement')
+      expect(helper.drive_label(:urgency)).to eq('urgent response')
+    end
+  end
+end

data/spec/legion/extensions/agentic/executive/volition/helpers/intention_stack_spec.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Executive::Volition::Helpers::IntentionStack do
+  subject(:stack) { described_class.new }
+
+  let(:intention_mod) { Legion::Extensions::Agentic::Executive::Volition::Helpers::Intention }
+
+  def make_intention(drive: :curiosity, domain: :general, goal: 'test', salience: 0.5)
+    intention_mod.new_intention(drive: drive, domain: domain, goal: goal, salience: salience)
+  end
+
+  describe '#push' do
+    it 'adds an intention' do
+      expect(stack.push(make_intention)).to eq(:pushed)
+      expect(stack.size).to eq(1)
+    end
+
+    it 'rejects duplicates' do
+      stack.push(make_intention(goal: 'same goal'))
+      expect(stack.push(make_intention(goal: 'same goal'))).to eq(:duplicate)
+    end
+
+    it 'rejects when at capacity' do
+      Legion::Extensions::Agentic::Executive::Volition::Helpers::Constants::MAX_INTENTIONS.times do |i|
+        stack.push(make_intention(goal: "goal #{i}"))
+      end
+      expect(stack.push(make_intention(goal: 'overflow'))).to eq(:capacity_full)
+    end
+
+    it 'sorts by salience descending' do
+      stack.push(make_intention(goal: 'low', salience: 0.3))
+      stack.push(make_intention(goal: 'high', salience: 0.9))
+      expect(stack.top[:goal]).to eq('high')
+    end
+  end
+
+  describe '#active' do
+    it 'returns only active intentions' do
+      stack.push(make_intention(goal: 'active', salience: 0.5))
+      stack.push(make_intention(goal: 'completed', salience: 0.8))
+      stack.complete(stack.top[:intention_id])
+      expect(stack.active.size).to eq(1)
+    end
+  end
+
+  describe '#top' do
+    it 'returns highest-salience active intention' do
+      stack.push(make_intention(goal: 'low', salience: 0.3))
+      stack.push(make_intention(goal: 'high', salience: 0.9))
+      expect(stack.top[:goal]).to eq('high')
+    end
+
+    it 'returns nil when empty' do
+      expect(stack.top).to be_nil
+    end
+  end
+
+  describe '#by_drive' do
+    it 'filters by drive type' do
+      stack.push(make_intention(drive: :curiosity, goal: 'c1'))
+      stack.push(make_intention(drive: :urgency, goal: 'u1'))
+      expect(stack.by_drive(:curiosity).size).to eq(1)
+    end
+  end
+
+  describe '#complete' do
+    it 'marks an intention as completed' do
+      stack.push(make_intention(goal: 'task'))
+      id = stack.top[:intention_id]
+      expect(stack.complete(id)).to eq(:completed)
+      expect(stack.active).to be_empty
+    end
+
+    it 'returns :not_found for unknown id' do
+      expect(stack.complete('nonexistent')).to eq(:not_found)
+    end
+  end
+
+  describe '#suspend and #resume' do
+    it 'suspends and resumes' do
+      stack.push(make_intention(goal: 'task'))
+      id = stack.top[:intention_id]
+
+      expect(stack.suspend(id)).to eq(:suspended)
+      expect(stack.active).to be_empty
+
+      expect(stack.resume(id)).to eq(:resumed)
+      expect(stack.active.size).to eq(1)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'decays active intentions and expires low-salience ones' do
+      stack.push(make_intention(goal: 'fading', salience: 0.12))
+      # First decay: 0.12 - 0.05 = 0.07 < floor(0.1), so expires immediately
+      expired = stack.decay_all
+      expect(expired).to be >= 1
+      expect(stack.active_count).to eq(0)
+    end
+
+    it 'preserves high-salience intentions through decay' do
+      stack.push(make_intention(goal: 'strong', salience: 0.8))
+      stack.decay_all
+      expect(stack.active_count).to eq(1)
+      expect(stack.top[:salience]).to be < 0.8
+    end
+  end
+
+  describe '#reinforce' do
+    it 'increases intention salience' do
+      stack.push(make_intention(goal: 'task', salience: 0.5))
+      id = stack.top[:intention_id]
+      stack.reinforce(id, amount: 0.2)
+      expect(stack.find(id)[:salience]).to eq(0.7)
+    end
+  end
+
+  describe '#stats' do
+    it 'returns comprehensive stats' do
+      stack.push(make_intention(drive: :curiosity, goal: 'c1', salience: 0.8))
+      stack.push(make_intention(drive: :urgency, goal: 'u1', salience: 0.6))
+      stats = stack.stats
+      expect(stats[:total]).to eq(2)
+      expect(stats[:active]).to eq(2)
+      expect(stats[:by_drive][:curiosity]).to eq(1)
+      expect(stats[:top_intention][:goal]).to eq('c1')
+    end
+  end
+end

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

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Executive::Volition::Runners::Volition do
+  let(:client) { Legion::Extensions::Agentic::Executive::Volition::Client.new }
+
+  describe '#form_intentions' do
+    it 'synthesizes drives and forms intentions' do
+      result = client.form_intentions(
+        tick_results:    {
+          emotional_evaluation: { valence: 0.3, arousal: 0.7 },
+          gut_instinct:         { signal: :heightened },
+          prediction_engine:    { confidence: 0.3 }
+        },
+        cognitive_state: {
+          curiosity:  { intensity: 0.7, active_count: 4, top_question: 'Why are traces sparse?' },
+          reflection: { health: 0.6, pending_adaptations: 2 }
+        }
+      )
+
+      expect(result[:drives]).to be_a(Hash)
+      expect(result[:drives].size).to eq(5)
+      expect(result[:dominant_drive]).to be_a(Symbol)
+      expect(result[:active_intentions]).to be >= 1
+      expect(result[:current_intention]).to be_a(Hash)
+    end
+
+    it 'handles empty inputs' do
+      result = client.form_intentions(tick_results: {}, cognitive_state: {})
+      expect(result[:drives]).to be_a(Hash)
+      expect(result[:active_intentions]).to be >= 0
+    end
+
+    it 'decays existing intentions over multiple ticks' do
+      client.form_intentions(
+        tick_results:    {},
+        cognitive_state: { curiosity: { intensity: 0.9, active_count: 5, top_question: 'test' } }
+      )
+
+      # Several ticks with no reinforcement
+      5.times { client.form_intentions(tick_results: {}, cognitive_state: {}) }
+
+      stats = client.volition_status
+      # Intentions may have decayed/expired
+      expect(stats[:intention_stats][:total]).to be >= 0
+    end
+  end
+
+  describe '#current_intention' do
+    it 'returns nil when no intentions exist' do
+      result = client.current_intention
+      expect(result[:has_will]).to be false
+      expect(result[:intention]).to be_nil
+    end
+
+    it 'returns the active intention after forming' do
+      client.form_intentions(
+        tick_results:    {},
+        cognitive_state: { curiosity: { intensity: 0.8, active_count: 3, top_question: 'Why?' } }
+      )
+      result = client.current_intention
+      expect(result[:has_will]).to be true
+      expect(result[:goal]).to be_a(String)
+    end
+  end
+
+  describe '#complete_intention' do
+    it 'completes an active intention' do
+      client.form_intentions(
+        tick_results:    {},
+        cognitive_state: { curiosity: { intensity: 0.8, active_count: 3, top_question: 'test' } }
+      )
+      id = client.current_intention[:intention][:intention_id]
+      result = client.complete_intention(intention_id: id)
+      expect(result[:status]).to eq(:completed)
+    end
+
+    it 'returns :not_found for unknown id' do
+      result = client.complete_intention(intention_id: 'nonexistent')
+      expect(result[:status]).to eq(:not_found)
+    end
+  end
+
+  describe '#suspend_intention and #resume_intention' do
+    it 'suspends and resumes an intention' do
+      # Push a single intention directly to avoid multi-drive generation
+      intention = Legion::Extensions::Agentic::Executive::Volition::Helpers::Intention.new_intention(
+        drive: :curiosity, domain: :general, goal: 'test suspend', salience: 0.8
+      )
+      client.intention_stack.push(intention)
+      id = intention[:intention_id]
+
+      expect(client.suspend_intention(intention_id: id)[:status]).to eq(:suspended)
+      expect(client.current_intention[:has_will]).to be false
+
+      expect(client.resume_intention(intention_id: id)[:status]).to eq(:resumed)
+      expect(client.current_intention[:has_will]).to be true
+    end
+  end
+
+  describe '#reinforce_intention' do
+    it 'increases intention salience' do
+      client.form_intentions(
+        tick_results:    {},
+        cognitive_state: { curiosity: { intensity: 0.5, active_count: 2, top_question: 'test' } }
+      )
+      id = client.current_intention[:intention][:intention_id]
+      old_salience = client.current_intention[:salience]
+
+      client.reinforce_intention(intention_id: id, amount: 0.3)
+      expect(client.current_intention[:salience]).to be > old_salience
+    end
+  end
+
+  describe '#volition_status' do
+    it 'returns comprehensive status' do
+      status = client.volition_status
+      expect(status[:intention_stats]).to be_a(Hash)
+      expect(status[:current_drives]).to be_a(Hash)
+      expect(status).to have_key(:has_will)
+      expect(status).to have_key(:dominant_drive)
+    end
+  end
+
+  describe '#intention_history' do
+    it 'returns recent intentions' do
+      client.form_intentions(
+        tick_results:    {},
+        cognitive_state: { curiosity: { intensity: 0.7, active_count: 3, top_question: 'q1' } }
+      )
+      result = client.intention_history(limit: 10)
+      expect(result[:intentions]).not_to be_empty
+      expect(result[:count]).to be >= 1
+    end
+  end
+end