lex-volition 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 27f789ca078d28bc1c55193117a6c2e70c9471e9c3c984c990a60024bd3d8ee8
+  data.tar.gz: 98f6f351eea6127dbb3b9081fb17a0cc14807e02e90281e82d854c6c5a52f9e1
+SHA512:
+  metadata.gz: 18be092dd65a1e1af67170367d366f3db2b769063d672258155ebc13cace5d4f3fefc56ddb4922e70effdd8e642ea6a71ac86d53e12d92f82cebdebc5cec047e
+  data.tar.gz: 8bf6d6dbcd61f5c6ea75d4c7d80b106e1b2aac6116eaf01df45e90b657523614091982e83a39663e2e1218597545636f7c0e6e503b60e24f8c208e8186133b34

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development, :test do
+  gem 'rake', '~> 13.0'
+  gem 'rspec', '~> 3.0'
+  gem 'rubocop', '~> 1.21'
+  gem 'rubocop-rspec', require: false
+  gem 'simplecov', require: false
+end
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LegionIO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,64 @@
+# lex-volition
+
+Drive synthesis and intention formation for LegionIO cognitive agents. Computes five motivational drives from the cognitive tick cycle and produces a prioritized intention stack.
+
+## What It Does
+
+`lex-volition` is the `action_selection` phase of the cognitive cycle. Each tick, it reads the full output of preceding phases and synthesizes five motivational drives. Drives above the threshold generate intentions, which are pushed onto a salience-sorted stack (max 7, per Miller's Law). Intentions decay each tick and expire by age.
+
+- **Drives**: curiosity, corrective, urgency, epistemic, social
+- **Drive weights**: curiosity 0.25, corrective 0.20, urgency 0.20, epistemic 0.20, social 0.15
+- **Urgency source**: gut signal from lex-emotion (`:alarm`=1.0, `:heightened`=0.7, `:explore`=0.5, `:attend`=0.4, `:calm`=0.1)
+- **Intention decay**: -0.05 salience per tick; expire at floor (0.1) or max age (100 ticks)
+- **Stack capacity**: 7 intentions max; lowest salience evicted on overflow
+
+## Usage
+
+```ruby
+require 'legion/extensions/volition'
+
+client = Legion::Extensions::Volition::Client.new
+
+# Form intentions from tick results (called each cognitive cycle)
+result = client.form_intentions(
+  tick_results: {
+    gut_instinct: { signal: :heightened },
+    prediction_engine: { calibration_error: 0.4, uncertainty: 0.6 },
+    conflict_resolution: { severity: 0.3 }
+  }
+)
+# => { intentions_formed: 3, dominant_drive: :epistemic, stack_size: 3 }
+
+# Check current top intention
+client.current_intention
+# => { intention: { drive: :epistemic, domain: :prediction, goal: '...', salience: 0.8, state: :pending } }
+
+# Reinforce an intention (keep it salient)
+client.reinforce_intention(intention_id: 'int_1', amount: 0.2)
+
+# Complete an intention
+client.complete_intention(intention_id: 'int_1')
+
+# Suspend/resume
+client.suspend_intention(intention_id: 'int_2')
+client.resume_intention(intention_id: 'int_2')
+
+# Current volition state
+client.volition_status
+# => { intentions: [{ drive:, goal:, salience:, state:, age_ticks: }, ...] }
+
+# Recent history
+client.intention_history(limit: 20)
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-volition.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/volition/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-volition'
+  spec.version       = Legion::Extensions::Volition::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Volition'
+  spec.description   = 'Intention formation and drive synthesis for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-volition'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/LegionIO/lex-volition'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-volition'
+  spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-volition'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/LegionIO/lex-volition/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-volition.gemspec Gemfile LICENSE README.md]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/volition/helpers/constants'
+require 'legion/extensions/volition/helpers/intention'
+require 'legion/extensions/volition/helpers/intention_stack'
+require 'legion/extensions/volition/helpers/drive_synthesizer'
+require 'legion/extensions/volition/runners/volition'
+
+module Legion
+  module Extensions
+    module Volition
+      class Client
+        include Runners::Volition
+
+        attr_reader :intention_stack
+
+        def initialize(stack: nil, **)
+          @intention_stack = stack || Helpers::IntentionStack.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Volition
+      module Helpers
+        module Constants
+          # Maximum active intentions
+          MAX_INTENTIONS = 7
+
+          # Drive sources and their default weights
+          DRIVE_WEIGHTS = {
+            curiosity:  0.25,  # from lex-curiosity wonder intensity
+            corrective: 0.20,  # from lex-reflection adaptation recommendations
+            urgency:    0.20,  # from lex-emotion gut signal + arousal
+            epistemic:  0.20,  # from lex-prediction confidence gaps
+            social:     0.15   # from lex-trust + mesh signals
+          }.freeze
+
+          # Minimum drive strength to generate an intention
+          DRIVE_THRESHOLD = 0.15
+
+          # Intention decay per tick when not reinforced
+          INTENTION_DECAY = 0.05
+
+          # Intention salience floor before removal
+          INTENTION_FLOOR = 0.1
+
+          # Maximum intention age in ticks before forced expiry
+          MAX_INTENTION_AGE = 100
+
+          # Drive labels for narrative output
+          DRIVE_LABELS = {
+            curiosity:  'knowledge seeking',
+            corrective: 'self-improvement',
+            urgency:    'urgent response',
+            epistemic:  'uncertainty reduction',
+            social:     'collaborative engagement'
+          }.freeze
+
+          # Intention states
+          STATES = %i[active suspended completed expired].freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/volition/helpers/drive_synthesizer.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Volition
+      module Helpers
+        module DriveSynthesizer
+          module_function
+
+          def synthesize(tick_results: {}, cognitive_state: {})
+            drives = {}
+            drives[:curiosity] = compute_curiosity_drive(tick_results, cognitive_state)
+            drives[:corrective] = compute_corrective_drive(cognitive_state)
+            drives[:urgency] = compute_urgency_drive(tick_results, cognitive_state)
+            drives[:epistemic] = compute_epistemic_drive(tick_results, cognitive_state)
+            drives[:social] = compute_social_drive(cognitive_state)
+            drives
+          end
+
+          def weighted_drives(drives)
+            drives.each_with_object({}) do |(drive, strength), result|
+              weight = Constants::DRIVE_WEIGHTS[drive] || 0.0
+              result[drive] = {
+                raw:      strength,
+                weighted: (strength * weight).round(4),
+                weight:   weight
+              }
+            end
+          end
+
+          def dominant_drive(drives)
+            return nil if drives.empty?
+
+            drives.max_by { |_, strength| strength }&.first
+          end
+
+          def generate_intentions(drives, cognitive_state: {})
+            intentions = []
+
+            drives.each do |drive, strength|
+              next if strength < Constants::DRIVE_THRESHOLD
+
+              intention = build_intention_for_drive(drive, strength, cognitive_state)
+              intentions << intention if intention
+            end
+
+            intentions.sort_by { |i| -(i[:salience] || 0) }
+          end
+
+          def compute_curiosity_drive(tick_results, cognitive_state)
+            curiosity = cognitive_state[:curiosity] || {}
+            wonder_data = tick_results[:working_memory_integration] || {}
+
+            intensity = curiosity[:intensity] || wonder_data[:curiosity_intensity] || 0.0
+            active_count = curiosity[:active_count] || wonder_data[:active_wonders] || 0
+
+            count_factor = [active_count / 5.0, 1.0].min
+            ((intensity * 0.7) + (count_factor * 0.3)).clamp(0.0, 1.0)
+          end
+
+          def compute_corrective_drive(cognitive_state)
+            reflection = cognitive_state[:reflection] || {}
+            health = reflection[:health] || 1.0
+            pending = reflection[:pending_adaptations] || 0
+
+            health_gap = 1.0 - health
+            pending_factor = [pending / 3.0, 1.0].min
+            ((health_gap * 0.6) + (pending_factor * 0.4)).clamp(0.0, 1.0)
+          end
+
+          def compute_urgency_drive(tick_results, cognitive_state)
+            gut = tick_results[:gut_instinct] || cognitive_state[:gut] || {}
+            emotion = tick_results[:emotional_evaluation] || {}
+
+            arousal = emotion[:arousal] || cognitive_state.dig(:emotion, :arousal) || 0.5
+            gut_signal = extract_gut_strength(gut)
+
+            ((arousal * 0.5) + (gut_signal * 0.5)).clamp(0.0, 1.0)
+          end
+
+          def compute_epistemic_drive(tick_results, cognitive_state)
+            pred = tick_results[:prediction_engine] || {}
+            pred_state = cognitive_state[:prediction] || {}
+
+            confidence = pred[:confidence] || pred_state[:confidence] || 0.5
+            pending = pred_state[:pending_count] || 0
+
+            confidence_gap = 1.0 - confidence
+            pending_factor = [pending / 10.0, 1.0].min
+            ((confidence_gap * 0.6) + (pending_factor * 0.4)).clamp(0.0, 1.0)
+          end
+
+          def compute_social_drive(cognitive_state)
+            mesh = cognitive_state[:mesh] || {}
+            trust = cognitive_state[:trust] || {}
+
+            peer_count = mesh[:peer_count] || 0
+            trust_level = trust[:avg_composite] || 0.5
+
+            peer_factor = [peer_count / 5.0, 1.0].min
+            ((peer_factor * 0.4) + (trust_level * 0.6)).clamp(0.0, 1.0)
+          end
+
+          def extract_gut_strength(gut)
+            signal = gut[:signal]
+            return 0.3 unless signal
+
+            case signal
+            when :alarm then 1.0
+            when :heightened then 0.7
+            when :explore   then 0.5
+            when :attend    then 0.4
+            when :calm      then 0.1
+            else 0.3
+            end
+          end
+
+          def build_intention_for_drive(drive, strength, cognitive_state)
+            case drive
+            when :curiosity  then build_curiosity_intention(strength, cognitive_state)
+            when :corrective then build_corrective_intention(strength, cognitive_state)
+            when :urgency    then build_urgency_intention(strength, cognitive_state)
+            when :epistemic  then build_epistemic_intention(strength, cognitive_state)
+            when :social     then build_social_intention(strength, cognitive_state)
+            end
+          end
+
+          def build_curiosity_intention(strength, cognitive_state)
+            question = cognitive_state.dig(:curiosity, :top_question) || 'explore knowledge gaps'
+            domain = cognitive_state.dig(:curiosity, :top_domain) || :general
+            Intention.new_intention(drive: :curiosity, domain: domain, goal: question, salience: strength)
+          end
+
+          def build_corrective_intention(strength, cognitive_state)
+            severity = cognitive_state.dig(:reflection, :recent_severity) || 'cognitive health'
+            Intention.new_intention(drive: :corrective, domain: :self, goal: "address #{severity}", salience: strength)
+          end
+
+          def build_urgency_intention(strength, _cognitive_state)
+            Intention.new_intention(drive: :urgency, domain: :general, goal: 'respond to urgent signal', salience: strength)
+          end
+
+          def build_epistemic_intention(strength, _cognitive_state)
+            Intention.new_intention(drive: :epistemic, domain: :general, goal: 'reduce prediction uncertainty', salience: strength)
+          end
+
+          def build_social_intention(strength, _cognitive_state)
+            Intention.new_intention(drive: :social, domain: :general, goal: 'engage with peer agents', salience: strength)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/volition/helpers/intention.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Volition
+      module Helpers
+        module Intention
+          module_function
+
+          def new_intention(drive:, domain:, goal:, salience:, context: {})
+            {
+              intention_id: SecureRandom.hex(8),
+              drive:        drive.to_sym,
+              domain:       domain.to_sym,
+              goal:         goal,
+              salience:     salience.clamp(0.0, 1.0),
+              state:        :active,
+              created_at:   Time.now.utc,
+              age_ticks:    0,
+              context:      context
+            }
+          end
+
+          def decay(intention)
+            new_salience = [intention[:salience] - Constants::INTENTION_DECAY, 0.0].max
+            intention.merge(salience: new_salience, age_ticks: intention[:age_ticks] + 1)
+          end
+
+          def reinforce(intention, amount: 0.1)
+            new_salience = [intention[:salience] + amount, 1.0].min
+            intention.merge(salience: new_salience)
+          end
+
+          def expired?(intention)
+            intention[:age_ticks] >= Constants::MAX_INTENTION_AGE ||
+              intention[:salience] < Constants::INTENTION_FLOOR
+          end
+
+          def active?(intention)
+            intention[:state] == :active && !expired?(intention)
+          end
+
+          def drive_label(drive)
+            Constants::DRIVE_LABELS[drive.to_sym] || drive.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/volition/helpers/intention_stack.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Volition
+      module Helpers
+        class IntentionStack
+          attr_reader :intentions
+
+          def initialize
+            @intentions = []
+          end
+
+          def push(intention)
+            return :duplicate if duplicate?(intention)
+            return :capacity_full if @intentions.size >= Constants::MAX_INTENTIONS
+
+            @intentions << intention
+            sort!
+            :pushed
+          end
+
+          def active
+            @intentions.select { |i| Intention.active?(i) }
+          end
+
+          def top
+            active.first
+          end
+
+          def by_drive(drive)
+            @intentions.select { |i| i[:drive] == drive.to_sym && Intention.active?(i) }
+          end
+
+          def by_domain(domain)
+            @intentions.select { |i| i[:domain] == domain.to_sym && Intention.active?(i) }
+          end
+
+          def find(intention_id)
+            @intentions.find { |i| i[:intention_id] == intention_id }
+          end
+
+          def complete(intention_id)
+            intention = find(intention_id)
+            return :not_found unless intention
+
+            intention[:state] = :completed
+            intention[:completed_at] = Time.now.utc
+            :completed
+          end
+
+          def suspend(intention_id)
+            intention = find(intention_id)
+            return :not_found unless intention
+
+            intention[:state] = :suspended
+            :suspended
+          end
+
+          def resume(intention_id)
+            intention = find(intention_id)
+            return :not_found unless intention
+            return :not_suspended unless intention[:state] == :suspended
+
+            intention[:state] = :active
+            :resumed
+          end
+
+          def decay_all
+            @intentions.each do |intention|
+              next unless Intention.active?(intention)
+
+              updated = Intention.decay(intention)
+              intention.merge!(updated)
+
+              intention[:state] = :expired if Intention.expired?(intention)
+            end
+
+            expired_count = @intentions.count { |i| i[:state] == :expired }
+            prune_expired
+            expired_count
+          end
+
+          def reinforce(intention_id, amount: 0.1)
+            intention = find(intention_id)
+            return :not_found unless intention
+
+            updated = Intention.reinforce(intention, amount: amount)
+            intention.merge!(updated)
+            sort!
+            :reinforced
+          end
+
+          def size
+            @intentions.size
+          end
+
+          def active_count
+            active.size
+          end
+
+          def stats
+            by_state = @intentions.each_with_object(Hash.new(0)) { |i, h| h[i[:state]] += 1 }
+            by_drive = active.each_with_object(Hash.new(0)) { |i, h| h[i[:drive]] += 1 }
+            {
+              total:         @intentions.size,
+              active:        active_count,
+              by_state:      by_state,
+              by_drive:      by_drive,
+              top_intention: top&.slice(:intention_id, :drive, :domain, :goal, :salience)
+            }
+          end
+
+          private
+
+          def sort!
+            @intentions.sort_by! { |i| -(i[:salience] || 0) }
+          end
+
+          def duplicate?(intention)
+            @intentions.any? do |existing|
+              Intention.active?(existing) &&
+                existing[:drive] == intention[:drive] &&
+                existing[:domain] == intention[:domain] &&
+                existing[:goal] == intention[:goal]
+            end
+          end
+
+          def prune_expired
+            @intentions.reject! { |i| i[:state] == :expired }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Volition
+      module Runners
+        module Volition
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def form_intentions(tick_results: {}, cognitive_state: {}, **)
+            drives = Helpers::DriveSynthesizer.synthesize(
+              tick_results:    tick_results,
+              cognitive_state: cognitive_state
+            )
+
+            new_intentions = Helpers::DriveSynthesizer.generate_intentions(drives, cognitive_state: cognitive_state)
+            pushed = 0
+            new_intentions.each do |intention|
+              result = intention_stack.push(intention)
+              pushed += 1 if result == :pushed
+            end
+
+            expired = intention_stack.decay_all
+            dominant = Helpers::DriveSynthesizer.dominant_drive(drives)
+            current = intention_stack.top
+
+            Legion::Logging.debug "[volition] drives=#{format_drives(drives)} pushed=#{pushed} expired=#{expired} " \
+                                  "active=#{intention_stack.active_count} top=#{current&.dig(:goal)}"
+
+            {
+              drives:            drives,
+              dominant_drive:    dominant,
+              new_intentions:    pushed,
+              expired:           expired,
+              active_intentions: intention_stack.active_count,
+              current_intention: format_intention(current)
+            }
+          end
+
+          def current_intention(**)
+            intention = intention_stack.top
+            return { intention: nil, has_will: false } unless intention
+
+            {
+              intention: format_intention(intention),
+              has_will:  true,
+              drive:     intention[:drive],
+              goal:      intention[:goal],
+              salience:  intention[:salience]
+            }
+          end
+
+          def complete_intention(intention_id:, **)
+            result = intention_stack.complete(intention_id)
+            Legion::Logging.info "[volition] complete intention=#{intention_id} result=#{result}"
+            { status: result, intention_id: intention_id }
+          end
+
+          def suspend_intention(intention_id:, **)
+            result = intention_stack.suspend(intention_id)
+            Legion::Logging.info "[volition] suspend intention=#{intention_id} result=#{result}"
+            { status: result, intention_id: intention_id }
+          end
+
+          def resume_intention(intention_id:, **)
+            result = intention_stack.resume(intention_id)
+            Legion::Logging.info "[volition] resume intention=#{intention_id} result=#{result}"
+            { status: result, intention_id: intention_id }
+          end
+
+          def reinforce_intention(intention_id:, amount: 0.1, **)
+            result = intention_stack.reinforce(intention_id, amount: amount)
+            { status: result, intention_id: intention_id }
+          end
+
+          def volition_status(**)
+            stats = intention_stack.stats
+            drives = Helpers::DriveSynthesizer.synthesize(tick_results: {}, cognitive_state: {})
+
+            {
+              intention_stats: stats,
+              current_drives:  drives,
+              has_will:        stats[:active].positive?,
+              dominant_drive:  Helpers::DriveSynthesizer.dominant_drive(drives)
+            }
+          end
+
+          def intention_history(limit: 20, **)
+            all = intention_stack.intentions.last(limit)
+            {
+              intentions: all.map { |i| format_intention(i) },
+              count:      all.size
+            }
+          end
+
+          private
+
+          def intention_stack
+            @intention_stack ||= Helpers::IntentionStack.new
+          end
+
+          def format_intention(intention)
+            return nil unless intention
+
+            {
+              intention_id: intention[:intention_id],
+              drive:        intention[:drive],
+              drive_label:  Helpers::Intention.drive_label(intention[:drive]),
+              domain:       intention[:domain],
+              goal:         intention[:goal],
+              salience:     intention[:salience].round(3),
+              state:        intention[:state],
+              age_ticks:    intention[:age_ticks]
+            }
+          end
+
+          def format_drives(drives)
+            drives.map { |k, v| "#{k}=#{v.round(2)}" }.join(' ')
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/volition.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/volition/version'
+require 'legion/extensions/volition/helpers/constants'
+require 'legion/extensions/volition/helpers/intention'
+require 'legion/extensions/volition/helpers/intention_stack'
+require 'legion/extensions/volition/helpers/drive_synthesizer'
+require 'legion/extensions/volition/runners/volition'
+require 'legion/extensions/volition/client'
+
+module Legion
+  module Extensions
+    module Volition
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::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::Volition::Helpers::IntentionStack)
+  end
+
+  it 'accepts an injected stack' do
+    custom = Legion::Extensions::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/volition/helpers/drive_synthesizer_spec.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::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/volition/helpers/intention_spec.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::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/volition/helpers/intention_stack_spec.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Volition::Helpers::IntentionStack do
+  subject(:stack) { described_class.new }
+
+  let(:intention_mod) { Legion::Extensions::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::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/volition/runners/volition_spec.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Volition::Runners::Volition do
+  let(:client) { Legion::Extensions::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::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

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+module Legion
+  module Logging
+    def self.debug(_msg); end
+    def self.info(_msg); end
+    def self.warn(_msg); end
+    def self.error(_msg); end
+  end
+end
+
+require 'legion/extensions/volition'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: lex-volition
+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: Intention formation and drive synthesis for brain-modeled agentic AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- lex-volition.gemspec
+- lib/legion/extensions/volition.rb
+- lib/legion/extensions/volition/client.rb
+- lib/legion/extensions/volition/helpers/constants.rb
+- lib/legion/extensions/volition/helpers/drive_synthesizer.rb
+- lib/legion/extensions/volition/helpers/intention.rb
+- lib/legion/extensions/volition/helpers/intention_stack.rb
+- lib/legion/extensions/volition/runners/volition.rb
+- lib/legion/extensions/volition/version.rb
+- spec/legion/extensions/volition/client_spec.rb
+- spec/legion/extensions/volition/helpers/drive_synthesizer_spec.rb
+- spec/legion/extensions/volition/helpers/intention_spec.rb
+- spec/legion/extensions/volition/helpers/intention_stack_spec.rb
+- spec/legion/extensions/volition/runners/volition_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-volition
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-volition
+  source_code_uri: https://github.com/LegionIO/lex-volition
+  documentation_uri: https://github.com/LegionIO/lex-volition
+  changelog_uri: https://github.com/LegionIO/lex-volition
+  bug_tracker_uri: https://github.com/LegionIO/lex-volition/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 Volition
+test_files: []