lex-agentic-executive 0.1.0

data/spec/legion/extensions/agentic/executive/cognitive_debt/runners/cognitive_debt_spec.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/executive/cognitive_debt/client'
+
+RSpec.describe Legion::Extensions::Agentic::Executive::CognitiveDebt::Runners::CognitiveDebt do
+  let(:engine) { Legion::Extensions::Agentic::Executive::CognitiveDebt::Helpers::DebtEngine.new }
+  let(:client) { Legion::Extensions::Agentic::Executive::CognitiveDebt::Client.new(engine: engine) }
+
+  describe '#create_debt' do
+    it 'creates a debt via the engine' do
+      result = client.create_debt(label: 'decide on auth', debt_type: :deferred_decision)
+      expect(result[:created]).to be true
+    end
+
+    it 'returns a debt_id' do
+      result = client.create_debt(label: 'decide on auth', debt_type: :deferred_decision)
+      expect(result[:debt_id]).not_to be_nil
+    end
+
+    it 'passes custom principal' do
+      result = client.create_debt(label: 'x', debt_type: :unprocessed_input, principal: 0.7)
+      expect(result[:debt][:principal]).to eq(0.7)
+    end
+
+    it 'passes custom domain' do
+      result = client.create_debt(label: 'x', debt_type: :incomplete_analysis, domain: 'security')
+      expect(result[:debt][:domain]).to eq('security')
+    end
+
+    it 'uses default principal when not specified' do
+      result = client.create_debt(label: 'x', debt_type: :deferred_decision)
+      expected = Legion::Extensions::Agentic::Executive::CognitiveDebt::Helpers::Constants::DEFAULT_PRINCIPAL
+      expect(result[:debt][:principal]).to eq(expected)
+    end
+
+    it 'returns created: false for invalid type' do
+      result = client.create_debt(label: 'x', debt_type: :nonexistent)
+      expect(result[:created]).to be false
+    end
+  end
+
+  describe '#repay_debt' do
+    let!(:debt_id) do
+      client.create_debt(label: 'unresolved thing', debt_type: :unresolved_conflict)[:debt_id]
+    end
+
+    it 'repays an existing debt' do
+      result = client.repay_debt(debt_id: debt_id)
+      expect(result[:repaid]).to be true
+    end
+
+    it 'returns found: false for unknown id' do
+      result = client.repay_debt(debt_id: 'no-such-id')
+      expect(result[:found]).to be false
+    end
+
+    it 'uses custom amount' do
+      result = client.repay_debt(debt_id: debt_id, amount: 0.05)
+      expect(result[:found]).to be true
+    end
+  end
+
+  describe '#accrue_interest' do
+    before { client.create_debt(label: 'pending work', debt_type: :pending_integration, principal: 0.4) }
+
+    it 'accrues interest on active debts' do
+      result = client.accrue_interest
+      expect(result[:accrued]).to eq(1)
+    end
+
+    it 'returns total_debt' do
+      result = client.accrue_interest
+      expect(result[:total_debt]).to be > 0.4
+    end
+  end
+
+  describe '#total_debt' do
+    it 'returns 0 for empty engine' do
+      result = client.total_debt
+      expect(result[:total_debt]).to eq(0.0)
+    end
+
+    it 'reflects created debts' do
+      client.create_debt(label: 'x', debt_type: :deferred_decision, principal: 0.5)
+      result = client.total_debt
+      expect(result[:total_debt]).to be_within(1e-10).of(0.5)
+    end
+  end
+
+  describe '#debt_by_type' do
+    before do
+      client.create_debt(label: 'a', debt_type: :deferred_decision)
+      client.create_debt(label: 'b', debt_type: :deferred_decision)
+      client.create_debt(label: 'c', debt_type: :unprocessed_input)
+    end
+
+    it 'returns count for the specified type' do
+      result = client.debt_by_type(debt_type: :deferred_decision)
+      expect(result[:count]).to eq(2)
+    end
+
+    it 'returns 0 for type with no debts' do
+      result = client.debt_by_type(debt_type: :unresolved_conflict)
+      expect(result[:count]).to eq(0)
+    end
+  end
+
+  describe '#debt_by_domain' do
+    before do
+      client.create_debt(label: 'a', debt_type: :deferred_decision, domain: 'perf')
+      client.create_debt(label: 'b', debt_type: :unprocessed_input, domain: 'perf')
+    end
+
+    it 'returns count for the specified domain' do
+      result = client.debt_by_domain(domain: 'perf')
+      expect(result[:count]).to eq(2)
+    end
+
+    it 'returns 0 for unknown domain' do
+      result = client.debt_by_domain(domain: 'unknown')
+      expect(result[:count]).to eq(0)
+    end
+  end
+
+  describe '#most_costly' do
+    before do
+      client.create_debt(label: 'cheap', debt_type: :deferred_decision, principal: 0.1)
+      client.create_debt(label: 'expensive', debt_type: :deferred_decision, principal: 0.9)
+    end
+
+    it 'returns most costly first' do
+      result = client.most_costly(limit: 2)
+      expect(result[:items].first[:principal]).to eq(0.9)
+    end
+
+    it 'respects the limit' do
+      result = client.most_costly(limit: 1)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#oldest_debts' do
+    it 'returns debts ordered by age' do
+      client.create_debt(label: 'old', debt_type: :deferred_decision)
+      sleep(0.01)
+      client.create_debt(label: 'newer', debt_type: :deferred_decision)
+      result = client.oldest_debts(limit: 2)
+      expect(result[:items].first[:label]).to eq('old')
+    end
+  end
+
+  describe '#debt_report' do
+    before do
+      client.create_debt(label: 'decision', debt_type: :deferred_decision, principal: 0.3)
+      client.create_debt(label: 'analysis', debt_type: :incomplete_analysis, principal: 0.6)
+    end
+
+    it 'includes total_debt' do
+      report = client.debt_report
+      expect(report[:total_debt]).to be > 0.0
+    end
+
+    it 'includes active_count' do
+      report = client.debt_report
+      expect(report[:active_count]).to eq(2)
+    end
+
+    it 'includes by_type with all five types' do
+      report = client.debt_report
+      expect(report[:by_type].keys).to match_array(
+        Legion::Extensions::Agentic::Executive::CognitiveDebt::Helpers::Constants::DEBT_TYPES
+      )
+    end
+
+    it 'includes recommended_priority' do
+      report = client.debt_report
+      expect(report[:recommended_priority]).not_to be_empty
+    end
+  end
+
+  describe '#prune_repaid' do
+    it 'prunes repaid debts and returns counts' do
+      id = client.create_debt(label: 'done', debt_type: :deferred_decision)[:debt_id]
+      client.repay_debt(debt_id: id, amount: 99.0)
+      result = client.prune_repaid
+      expect(result[:pruned]).to eq(1)
+      expect(result[:remaining]).to eq(0)
+    end
+
+    it 'returns pruned: 0 when nothing to prune' do
+      client.create_debt(label: 'active', debt_type: :deferred_decision)
+      result = client.prune_repaid
+      expect(result[:pruned]).to eq(0)
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Executive::Compass::Client do
+  subject(:client) { described_class.new }
+
+  it 'includes the runner module' do
+    expect(client).to respond_to(:take_bearing)
+  end
+
+  it 'includes all runner methods' do
+    %i[take_bearing register_bias calibrate
+       list_bearings list_biases compass_status].each do |m|
+      expect(client).to respond_to(m)
+    end
+  end
+end

data/spec/legion/extensions/agentic/executive/compass/helpers/bearing_spec.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Executive::Compass::Helpers::Bearing do
+  subject(:bearing) do
+    described_class.new(direction: :north, context: 'seeking truth')
+  end
+
+  describe '#initialize' do
+    it 'sets direction' do
+      expect(bearing.direction).to eq(:north)
+    end
+
+    it 'resolves value axis' do
+      expect(bearing.value_axis).to eq(:truth)
+    end
+
+    it 'sets context' do
+      expect(bearing.context).to eq('seeking truth')
+    end
+
+    it 'generates uuid' do
+      expect(bearing.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'defaults confidence to 0.7' do
+      expect(bearing.confidence).to eq(0.7)
+    end
+
+    it 'accepts intercardinal directions' do
+      b = described_class.new(direction: :northeast, context: 'pragmatic truth')
+      expect(b.value_axis).to eq(%i[truth utility])
+    end
+
+    it 'rejects unknown directions' do
+      expect { described_class.new(direction: :up, context: 'x') }
+        .to raise_error(ArgumentError, /unknown direction/)
+    end
+
+    it 'accepts custom confidence' do
+      b = described_class.new(direction: :south, context: 'x', confidence: 0.95)
+      expect(b.confidence).to eq(0.95)
+    end
+  end
+
+  describe '#reliable?' do
+    it 'returns true at default confidence' do
+      expect(bearing.reliable?).to be true
+    end
+
+    it 'returns false at low confidence' do
+      b = described_class.new(direction: :east, context: 'x', confidence: 0.3)
+      expect(b.reliable?).to be false
+    end
+  end
+
+  describe '#lost?' do
+    it 'returns false at default confidence' do
+      expect(bearing.lost?).to be false
+    end
+
+    it 'returns true at very low confidence' do
+      b = described_class.new(direction: :west, context: 'x', confidence: 0.1)
+      expect(b.lost?).to be true
+    end
+  end
+
+  describe '#cardinal?' do
+    it 'returns true for cardinal directions' do
+      expect(bearing.cardinal?).to be true
+    end
+
+    it 'returns false for intercardinal' do
+      b = described_class.new(direction: :northeast, context: 'x')
+      expect(b.cardinal?).to be false
+    end
+  end
+
+  describe '#accuracy_label' do
+    it 'returns a symbol' do
+      expect(bearing.accuracy_label).to be_a(Symbol)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns all keys' do
+      h = bearing.to_h
+      %i[id direction value_axis context confidence accuracy_label
+         cardinal reliable lost taken_at].each do |k|
+        expect(h).to have_key(k)
+      end
+    end
+  end
+end

data/spec/legion/extensions/agentic/executive/compass/helpers/compass_engine_spec.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Executive::Compass::Helpers::CompassEngine do
+  subject(:engine) { described_class.new }
+
+  describe '#take_bearing' do
+    it 'creates a bearing' do
+      b = engine.take_bearing(direction: :north, context: 'truth seeking')
+      expect(b).to be_a(Legion::Extensions::Agentic::Executive::Compass::Helpers::Bearing)
+    end
+  end
+
+  describe '#register_bias' do
+    it 'creates a magnetic bias' do
+      b = engine.register_bias(bias_type: :confirmation, domain: :reasoning)
+      expect(b).to be_a(Legion::Extensions::Agentic::Executive::Compass::Helpers::MagneticBias)
+    end
+
+    it 'raises when too many biases' do
+      stub_const('Legion::Extensions::Agentic::Executive::Compass::Helpers::Constants::MAX_BIASES', 1)
+      engine.register_bias(bias_type: :confirmation, domain: :x)
+      expect { engine.register_bias(bias_type: :anchoring, domain: :y) }
+        .to raise_error(ArgumentError, /too many biases/)
+    end
+  end
+
+  describe '#calibrate' do
+    it 'reduces bias declination' do
+      bias = engine.register_bias(bias_type: :anchoring, domain: :x, declination: 0.5)
+      engine.calibrate(bias_id: bias.id)
+      expect(bias.declination).to be < 0.5
+    end
+
+    it 'raises for unknown bias' do
+      expect { engine.calibrate(bias_id: 'nope') }
+        .to raise_error(ArgumentError, /bias not found/)
+    end
+  end
+
+  describe '#true_north_offset' do
+    it 'returns 0.0 with no biases' do
+      expect(engine.true_north_offset).to eq(0.0)
+    end
+
+    it 'returns average declination' do
+      engine.register_bias(bias_type: :confirmation, domain: :x, declination: 0.4)
+      engine.register_bias(bias_type: :anchoring, domain: :y, declination: 0.6)
+      expect(engine.true_north_offset).to eq(0.5)
+    end
+  end
+
+  describe '#accuracy' do
+    it 'returns 1.0 with no biases' do
+      expect(engine.accuracy).to eq(1.0)
+    end
+
+    it 'decreases with biases' do
+      engine.register_bias(bias_type: :confirmation, domain: :x, declination: 0.5)
+      expect(engine.accuracy).to be < 1.0
+    end
+  end
+
+  describe '#decay_biases!' do
+    it 'decays all biases' do
+      bias = engine.register_bias(bias_type: :recency, domain: :x, strength: 0.5)
+      old = bias.strength
+      engine.decay_biases!
+      expect(bias.strength).to be < old
+    end
+  end
+
+  describe '#dominant_direction' do
+    it 'returns nil with no bearings' do
+      expect(engine.dominant_direction).to be_nil
+    end
+
+    it 'returns the most common direction weighted by confidence' do
+      engine.take_bearing(direction: :north, context: 'a', confidence: 0.9)
+      engine.take_bearing(direction: :south, context: 'b', confidence: 0.3)
+      expect(engine.dominant_direction).to eq(:north)
+    end
+  end
+
+  describe '#bearings_by_direction' do
+    it 'counts bearings per direction' do
+      engine.take_bearing(direction: :north, context: 'a')
+      engine.take_bearing(direction: :north, context: 'b')
+      engine.take_bearing(direction: :east, context: 'c')
+      result = engine.bearings_by_direction
+      expect(result[:north]).to eq(2)
+      expect(result[:east]).to eq(1)
+    end
+  end
+
+  describe '#strongest_biases' do
+    it 'returns biases sorted by strength' do
+      engine.register_bias(bias_type: :confirmation, domain: :x, strength: 0.3)
+      strong = engine.register_bias(bias_type: :anchoring, domain: :y, strength: 0.9)
+      expect(engine.strongest_biases(limit: 1).first).to eq(strong)
+    end
+  end
+
+  describe '#compass_report' do
+    it 'returns comprehensive report' do
+      engine.take_bearing(direction: :north, context: 'test')
+      report = engine.compass_report
+      %i[total_bearings total_biases accuracy accuracy_label
+         true_north_offset dominant_direction by_direction severe_biases].each do |k|
+        expect(report).to have_key(k)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Executive::Compass::Helpers::Constants do
+  describe 'CARDINAL_DIRECTIONS' do
+    it 'maps four cardinal points to value axes' do
+      expect(described_class::CARDINAL_DIRECTIONS.keys).to eq(%i[north east south west])
+    end
+
+    it 'maps north to truth' do
+      expect(described_class::CARDINAL_DIRECTIONS[:north]).to eq(:truth)
+    end
+  end
+
+  describe 'INTERCARDINAL_DIRECTIONS' do
+    it 'has four intercardinal points' do
+      expect(described_class::INTERCARDINAL_DIRECTIONS.size).to eq(4)
+    end
+
+    it 'blends two value axes per direction' do
+      expect(described_class::INTERCARDINAL_DIRECTIONS[:northeast]).to eq(%i[truth utility])
+    end
+  end
+
+  describe 'BIAS_TYPES' do
+    it 'includes common cognitive biases' do
+      %i[confirmation anchoring availability].each do |b|
+        expect(described_class::BIAS_TYPES).to include(b)
+      end
+    end
+  end
+
+  describe '.label_for' do
+    it 'returns precise for high accuracy' do
+      expect(described_class.label_for(described_class::ACCURACY_LABELS, 0.9)).to eq(:precise)
+    end
+
+    it 'returns lost for low accuracy' do
+      expect(described_class.label_for(described_class::ACCURACY_LABELS, 0.1)).to eq(:lost)
+    end
+
+    it 'returns severe for high declination' do
+      expect(described_class.label_for(described_class::DECLINATION_LABELS, 0.85)).to eq(:severe)
+    end
+  end
+end

data/spec/legion/extensions/agentic/executive/compass/helpers/magnetic_bias_spec.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Executive::Compass::Helpers::MagneticBias do
+  subject(:bias) do
+    described_class.new(bias_type: :confirmation, domain: :reasoning)
+  end
+
+  describe '#initialize' do
+    it 'sets bias type' do
+      expect(bias.bias_type).to eq(:confirmation)
+    end
+
+    it 'sets domain' do
+      expect(bias.domain).to eq(:reasoning)
+    end
+
+    it 'defaults declination to 0.3' do
+      expect(bias.declination).to eq(0.3)
+    end
+
+    it 'defaults strength to 0.5' do
+      expect(bias.strength).to eq(0.5)
+    end
+
+    it 'rejects unknown bias types' do
+      expect { described_class.new(bias_type: :laziness, domain: :x) }
+        .to raise_error(ArgumentError, /unknown bias type/)
+    end
+  end
+
+  describe '#correct!' do
+    it 'reduces declination' do
+      old = bias.declination
+      bias.correct!
+      expect(bias.declination).to be < old
+    end
+
+    it 'does not go below zero' do
+      10.times { bias.correct!(amount: 0.5) }
+      expect(bias.declination).to eq(0.0)
+    end
+  end
+
+  describe '#intensify!' do
+    it 'increases strength' do
+      old = bias.strength
+      bias.intensify!
+      expect(bias.strength).to be > old
+    end
+
+    it 'increases declination' do
+      old = bias.declination
+      bias.intensify!
+      expect(bias.declination).to be > old
+    end
+  end
+
+  describe '#decay!' do
+    it 'reduces strength' do
+      old = bias.strength
+      bias.decay!
+      expect(bias.strength).to be < old
+    end
+  end
+
+  describe '#severe?' do
+    it 'returns false at default declination' do
+      expect(bias.severe?).to be false
+    end
+
+    it 'returns true at high declination' do
+      b = described_class.new(bias_type: :anchoring, domain: :x, declination: 0.9)
+      expect(b.severe?).to be true
+    end
+  end
+
+  describe '#negligible?' do
+    it 'returns false at default declination' do
+      expect(bias.negligible?).to be false
+    end
+
+    it 'returns true after correction' do
+      5.times { bias.correct!(amount: 0.1) }
+      expect(bias.negligible?).to be true
+    end
+  end
+
+  describe '#declination_label' do
+    it 'returns a symbol' do
+      expect(bias.declination_label).to be_a(Symbol)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns all keys' do
+      h = bias.to_h
+      %i[id bias_type domain declination declination_label
+         strength severe negligible detected_at].each do |k|
+        expect(h).to have_key(k)
+      end
+    end
+  end
+end

data/spec/legion/extensions/agentic/executive/compass/runners/cognitive_compass_spec.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Executive::Compass::Runners::CognitiveCompass do
+  let(:engine) { Legion::Extensions::Agentic::Executive::Compass::Helpers::CompassEngine.new }
+
+  describe '.take_bearing' do
+    it 'returns success' do
+      result = described_class.take_bearing(
+        direction: :north, context: 'truth seeking', engine: engine
+      )
+      expect(result[:success]).to be true
+      expect(result[:bearing][:direction]).to eq(:north)
+    end
+
+    it 'returns failure for invalid direction' do
+      result = described_class.take_bearing(
+        direction: :up, context: 'x', engine: engine
+      )
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '.register_bias' do
+    it 'returns success' do
+      result = described_class.register_bias(
+        bias_type: :confirmation, domain: :reasoning, engine: engine
+      )
+      expect(result[:success]).to be true
+      expect(result[:bias][:bias_type]).to eq(:confirmation)
+    end
+
+    it 'returns failure for invalid bias' do
+      result = described_class.register_bias(
+        bias_type: :laziness, domain: :x, engine: engine
+      )
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '.calibrate' do
+    it 'reduces declination' do
+      bias = engine.register_bias(bias_type: :anchoring, domain: :x, declination: 0.5)
+      result = described_class.calibrate(bias_id: bias.id, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:bias][:declination]).to be < 0.5
+    end
+  end
+
+  describe '.list_bearings' do
+    it 'returns all bearings' do
+      engine.take_bearing(direction: :north, context: 'a')
+      engine.take_bearing(direction: :east, context: 'b')
+      result = described_class.list_bearings(engine: engine)
+      expect(result[:count]).to eq(2)
+    end
+
+    it 'filters by direction' do
+      engine.take_bearing(direction: :north, context: 'a')
+      engine.take_bearing(direction: :east, context: 'b')
+      result = described_class.list_bearings(engine: engine, direction: :north)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '.list_biases' do
+    it 'returns all biases' do
+      engine.register_bias(bias_type: :recency, domain: :x)
+      result = described_class.list_biases(engine: engine)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '.compass_status' do
+    it 'returns report' do
+      result = described_class.compass_status(engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:report]).to have_key(:accuracy)
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Executive::Control::Client do
+  subject(:client) { described_class.new }
+
+  it 'includes the CognitiveControl runner' do
+    expect(client).to respond_to(:set_control_goal)
+  end
+
+  it 'accepts an injected controller' do
+    controller = Legion::Extensions::Agentic::Executive::Control::Helpers::Controller.new
+    c = described_class.new(controller: controller)
+    expect(c.set_control_goal(description: 'test')[:success]).to be true
+  end
+
+  it 'creates goals end-to-end' do
+    result = client.set_control_goal(description: 'integration', priority: 0.8)
+    expect(result[:success]).to be true
+
+    stats = client.cognitive_control_stats
+    expect(stats[:goal_count]).to eq(1)
+  end
+end