lex-cognitive-coherence 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ac076a2d936cd58c3c50f7f70bb5e965adeccf4eb20efa211c74537f5b087690
+  data.tar.gz: e6824ef6d7b996b078253e9058e46a301e9ada591b712a5908f4abf19005d5a0
+SHA512:
+  metadata.gz: 787518a385ff89e680e194041bb5631a3cca34fe998eaf8d0f9d56670205d430cb05cbe0ba4bd390706f4dccce23ae0a76d1a8aade33335eb92662aac0942d93
+  data.tar.gz: 12cc72c797be5e285a34beb643629f346bcec4afd0e9f3e80af5d6426571073b332d368af14562200e6058aa5ec1e8524fdd0dbe60d84f95a41d232271942cd6

data/Gemfile

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

data/lex-cognitive-coherence.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_coherence/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-coherence'
+  spec.version       = Legion::Extensions::CognitiveCoherence::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Coherence'
+  spec.description   = "Thagard's coherence theory: constraint satisfaction across beliefs, " \
+                       'goals, and evidence for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-coherence'
+  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-cognitive-coherence'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-cognitive-coherence'
+  spec.metadata['changelog_uri']     = 'https://github.com/LegionIO/lex-cognitive-coherence'
+  spec.metadata['bug_tracker_uri']   = 'https://github.com/LegionIO/lex-cognitive-coherence/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-cognitive-coherence.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_coherence/helpers/constants'
+require 'legion/extensions/cognitive_coherence/helpers/proposition'
+require 'legion/extensions/cognitive_coherence/helpers/coherence_engine'
+require 'legion/extensions/cognitive_coherence/runners/cognitive_coherence'
+
+module Legion
+  module Extensions
+    module CognitiveCoherence
+      class Client
+        include Runners::CognitiveCoherence
+
+        def initialize(**)
+          @engine = Helpers::CoherenceEngine.new
+        end
+
+        private
+
+        attr_reader :engine
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_coherence/helpers/coherence_engine.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveCoherence
+      module Helpers
+        class CoherenceEngine
+          include Constants
+
+          attr_reader :propositions, :history
+
+          def initialize
+            @propositions = {}
+            @history      = []
+          end
+
+          def add_proposition(content:, domain: :general, acceptance: DEFAULT_ACCEPTANCE)
+            return nil if @propositions.size >= MAX_PROPOSITIONS
+
+            prop = Proposition.new(content: content, domain: domain, acceptance: acceptance)
+            @propositions[prop.id] = prop
+            record_history(:add_proposition, { id: prop.id, domain: domain })
+            prop.id
+          end
+
+          def add_constraint(prop_a_id:, prop_b_id:, constraint_type:, positive: true)
+            prop_a = @propositions[prop_a_id]
+            prop_b = @propositions[prop_b_id]
+            return { success: false, reason: :proposition_not_found } unless prop_a && prop_b
+
+            unless CONSTRAINT_TYPES.include?(constraint_type)
+              return { success: false,
+                       reason:  :invalid_constraint_type }
+            end
+
+            if positive
+              prop_a.add_positive_constraint(proposition_id: prop_b_id)
+              prop_b.add_positive_constraint(proposition_id: prop_a_id)
+            else
+              prop_a.add_negative_constraint(proposition_id: prop_b_id)
+              prop_b.add_negative_constraint(proposition_id: prop_a_id)
+            end
+
+            record_history(:add_constraint,
+                           { prop_a: prop_a_id, prop_b: prop_b_id, type: constraint_type, positive: positive })
+            { success: true, constraint_type: constraint_type, positive: positive }
+          end
+
+          def compute_coherence(proposition_id:)
+            prop = @propositions[proposition_id]
+            return 0.0 unless prop
+
+            positive_sum = prop.positive_constraints.sum do |pid|
+              neighbor = @propositions[pid]
+              neighbor ? neighbor.acceptance * COHERENCE_WEIGHT : 0.0
+            end
+
+            negative_sum = prop.negative_constraints.sum do |pid|
+              neighbor = @propositions[pid]
+              neighbor ? neighbor.acceptance * INCOHERENCE_PENALTY : 0.0
+            end
+
+            (prop.acceptance + positive_sum - negative_sum).clamp(0.0, 1.0)
+          end
+
+          def maximize_coherence
+            return { success: true, iterations: 0, proposition_count: 0 } if @propositions.empty?
+
+            @propositions.each_value { |prop| adjust_proposition(prop) }
+
+            record_history(:maximize_coherence, { overall: overall_coherence })
+            {
+              success:           true,
+              iterations:        1,
+              proposition_count: @propositions.size,
+              overall_coherence: overall_coherence
+            }
+          end
+
+          def overall_coherence
+            return 0.0 if @propositions.empty?
+
+            total = @propositions.values.sum { |prop| compute_coherence(proposition_id: prop.id) }
+            total / @propositions.size
+          end
+
+          def coherence_label
+            val = overall_coherence
+            COHERENCE_LABELS.find { |range, _| range.cover?(val) }&.last || :unknown
+          end
+
+          def find_contradictions
+            accepted = @propositions.values.select(&:accepted?)
+            pairs    = []
+            accepted.each { |prop| collect_contradiction_pairs(prop, pairs) }
+            pairs
+          end
+
+          def partition
+            result = { accepted: [], rejected: [], undecided: [] }
+            @propositions.each_value { |prop| result[prop.state] << prop.to_h }
+            result
+          end
+
+          def by_domain(domain:)
+            @propositions.values.select { |prop| prop.domain == domain }.map(&:to_h)
+          end
+
+          def decay_all
+            count = 0
+            @propositions.each_value do |prop|
+              next if prop.acceptance == DEFAULT_ACCEPTANCE
+
+              delta = (DEFAULT_ACCEPTANCE - prop.acceptance) * DECAY_RATE
+              prop.adjust_acceptance(amount: delta) unless delta.abs < 0.0001
+              count += 1
+            end
+            { success: true, decayed_count: count }
+          end
+
+          def to_h
+            {
+              proposition_count: @propositions.size,
+              overall_coherence: overall_coherence,
+              coherence_label:   coherence_label,
+              partition:         partition,
+              history_size:      @history.size
+            }
+          end
+
+          private
+
+          def adjust_proposition(prop)
+            positive_pull = prop.positive_constraints.sum do |pid|
+              neighbor = @propositions[pid]
+              neighbor ? neighbor.acceptance * COHERENCE_WEIGHT : 0.0
+            end
+
+            negative_push = prop.negative_constraints.sum do |pid|
+              neighbor = @propositions[pid]
+              neighbor ? neighbor.acceptance * INCOHERENCE_PENALTY : 0.0
+            end
+
+            delta = positive_pull - negative_push
+            prop.adjust_acceptance(amount: delta) unless delta.abs < 0.001
+          end
+
+          def collect_contradiction_pairs(prop, pairs)
+            prop.negative_constraints.each do |neg_id|
+              neighbor = @propositions[neg_id]
+              next unless neighbor&.accepted?
+              next if pairs.any? { |pair| pair[:prop_b] == prop.id && pair[:prop_a] == neg_id }
+
+              pairs << { prop_a: prop.id, prop_b: neg_id }
+            end
+          end
+
+          def record_history(event, data)
+            @history << { event: event, data: data, at: Time.now.utc }
+            @history.shift while @history.size > MAX_HISTORY
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveCoherence
+      module Helpers
+        module Constants
+          MAX_PROPOSITIONS   = 200
+          MAX_CONSTRAINTS    = 500
+          MAX_HISTORY        = 300
+          DEFAULT_ACCEPTANCE = 0.5
+          ACCEPTANCE_THRESHOLD = 0.6
+          COHERENCE_WEIGHT = 0.1
+          INCOHERENCE_PENALTY = 0.15
+          DECAY_RATE         = 0.01
+
+          CONSTRAINT_TYPES = %i[explanatory deductive analogical perceptual conceptual deliberative].freeze
+          PROPOSITION_STATES = %i[accepted rejected undecided].freeze
+
+          COHERENCE_LABELS = {
+            (0.8..)     => :highly_coherent,
+            (0.6...0.8) => :coherent,
+            (0.4...0.6) => :mixed,
+            (0.2...0.4) => :incoherent,
+            (..0.2)     => :contradictory
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_coherence/helpers/proposition.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveCoherence
+      module Helpers
+        class Proposition
+          include Constants
+
+          attr_reader :id, :content, :domain, :acceptance,
+                      :positive_constraints, :negative_constraints,
+                      :evidence_count, :created_at, :updated_at
+
+          def initialize(content:, domain: :general, acceptance: DEFAULT_ACCEPTANCE)
+            @id                  = SecureRandom.uuid
+            @content             = content
+            @domain              = domain
+            @acceptance          = acceptance.clamp(0.0, 1.0)
+            @positive_constraints = []
+            @negative_constraints = []
+            @evidence_count      = 0
+            @created_at          = Time.now.utc
+            @updated_at          = Time.now.utc
+          end
+
+          def state
+            if @acceptance >= ACCEPTANCE_THRESHOLD
+              :accepted
+            elsif @acceptance < (1.0 - ACCEPTANCE_THRESHOLD)
+              :rejected
+            else
+              :undecided
+            end
+          end
+
+          def accepted?
+            state == :accepted
+          end
+
+          def rejected?
+            state == :rejected
+          end
+
+          def undecided?
+            state == :undecided
+          end
+
+          def add_positive_constraint(proposition_id:)
+            return false if @positive_constraints.include?(proposition_id)
+
+            @positive_constraints << proposition_id
+            @updated_at = Time.now.utc
+            true
+          end
+
+          def add_negative_constraint(proposition_id:)
+            return false if @negative_constraints.include?(proposition_id)
+
+            @negative_constraints << proposition_id
+            @updated_at = Time.now.utc
+            true
+          end
+
+          def adjust_acceptance(amount:)
+            @acceptance = (@acceptance + amount).clamp(0.0, 1.0)
+            @updated_at = Time.now.utc
+            @acceptance
+          end
+
+          def add_evidence
+            @evidence_count += 1
+            @updated_at = Time.now.utc
+            @evidence_count
+          end
+
+          def to_h
+            {
+              id:                   @id,
+              content:              @content,
+              domain:               @domain,
+              acceptance:           @acceptance,
+              state:                state,
+              positive_constraints: @positive_constraints.dup,
+              negative_constraints: @negative_constraints.dup,
+              evidence_count:       @evidence_count,
+              created_at:           @created_at,
+              updated_at:           @updated_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveCoherence
+      module Runners
+        module CognitiveCoherence
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def add_coherence_proposition(content:, domain: :general, acceptance: Helpers::Constants::DEFAULT_ACCEPTANCE,
+                                        **)
+            return { success: false, reason: :missing_content } if content.nil? || content.empty?
+
+            prop_id = engine.add_proposition(content: content, domain: domain, acceptance: acceptance)
+            if prop_id
+              Legion::Logging.debug "[cognitive_coherence] add_proposition domain=#{domain} id=#{prop_id[0..7]}"
+              { success: true, proposition_id: prop_id, domain: domain, acceptance: acceptance }
+            else
+              Legion::Logging.warn '[cognitive_coherence] add_proposition failed: max propositions reached'
+              { success: false, reason: :max_propositions_reached }
+            end
+          end
+
+          def add_coherence_constraint(prop_a_id:, prop_b_id:, constraint_type:, positive: true, **)
+            unless Helpers::Constants::CONSTRAINT_TYPES.include?(constraint_type)
+              return { success: false, reason: :invalid_constraint_type,
+                       valid_types: Helpers::Constants::CONSTRAINT_TYPES }
+            end
+
+            result = engine.add_constraint(
+              prop_a_id:       prop_a_id,
+              prop_b_id:       prop_b_id,
+              constraint_type: constraint_type,
+              positive:        positive
+            )
+
+            Legion::Logging.debug "[cognitive_coherence] add_constraint type=#{constraint_type} " \
+                                  "positive=#{positive} success=#{result[:success]}"
+            result
+          end
+
+          def compute_proposition_coherence(proposition_id:, **)
+            score = engine.compute_coherence(proposition_id: proposition_id)
+            prop  = engine.propositions[proposition_id]
+
+            unless prop
+              Legion::Logging.debug "[cognitive_coherence] compute_coherence: #{proposition_id[0..7]} not found"
+              return { success: false, reason: :not_found }
+            end
+
+            Legion::Logging.debug '[cognitive_coherence] compute_coherence ' \
+                                  "id=#{proposition_id[0..7]} score=#{score.round(3)}"
+            { success: true, proposition_id: proposition_id, coherence_score: score, state: prop.state }
+          end
+
+          def maximize_coherence(**)
+            result = engine.maximize_coherence
+            overall = result[:overall_coherence]&.round(3)
+            Legion::Logging.info '[cognitive_coherence] maximize_coherence ' \
+                                 "overall=#{overall} props=#{result[:proposition_count]}"
+            result
+          end
+
+          def find_contradictions(**)
+            pairs = engine.find_contradictions
+            Legion::Logging.debug "[cognitive_coherence] find_contradictions count=#{pairs.size}"
+            { success: true, contradictions: pairs, count: pairs.size }
+          end
+
+          def coherence_partition(**)
+            result = engine.partition
+            totals = result.transform_values(&:size)
+            Legion::Logging.debug "[cognitive_coherence] partition accepted=#{totals[:accepted]} " \
+                                  "rejected=#{totals[:rejected]} undecided=#{totals[:undecided]}"
+            { success: true, partition: result, counts: totals }
+          end
+
+          def update_cognitive_coherence(**)
+            coherence_result = engine.maximize_coherence
+            decay_result     = engine.decay_all
+
+            overall = coherence_result[:overall_coherence]&.round(3)
+            Legion::Logging.info "[cognitive_coherence] update overall=#{overall} " \
+                                 "decayed=#{decay_result[:decayed_count]}"
+            {
+              success:           true,
+              overall_coherence: coherence_result[:overall_coherence],
+              coherence_label:   engine.coherence_label,
+              decayed_count:     decay_result[:decayed_count]
+            }
+          end
+
+          def cognitive_coherence_stats(**)
+            part   = engine.partition
+            counts = part.transform_values(&:size)
+            Legion::Logging.debug "[cognitive_coherence] stats propositions=#{engine.propositions.size} " \
+                                  "coherence=#{engine.overall_coherence.round(3)}"
+            {
+              success:             true,
+              proposition_count:   engine.propositions.size,
+              overall_coherence:   engine.overall_coherence,
+              coherence_label:     engine.coherence_label,
+              partition_counts:    counts,
+              contradiction_count: engine.find_contradictions.size,
+              history_size:        engine.history.size
+            }
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::CoherenceEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_coherence.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_coherence/version'
+require 'legion/extensions/cognitive_coherence/helpers/constants'
+require 'legion/extensions/cognitive_coherence/helpers/proposition'
+require 'legion/extensions/cognitive_coherence/helpers/coherence_engine'
+require 'legion/extensions/cognitive_coherence/runners/cognitive_coherence'
+
+module Legion
+  module Extensions
+    module CognitiveCoherence
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_coherence/client'
+
+RSpec.describe Legion::Extensions::CognitiveCoherence::Client do
+  it 'responds to all runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:add_coherence_proposition)
+    expect(client).to respond_to(:add_coherence_constraint)
+    expect(client).to respond_to(:compute_proposition_coherence)
+    expect(client).to respond_to(:maximize_coherence)
+    expect(client).to respond_to(:find_contradictions)
+    expect(client).to respond_to(:coherence_partition)
+    expect(client).to respond_to(:update_cognitive_coherence)
+    expect(client).to respond_to(:cognitive_coherence_stats)
+  end
+end

data/spec/legion/extensions/cognitive_coherence/runners/cognitive_coherence_spec.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_coherence/client'
+
+RSpec.describe Legion::Extensions::CognitiveCoherence::Runners::CognitiveCoherence do
+  let(:client) { Legion::Extensions::CognitiveCoherence::Client.new }
+
+  describe '#add_coherence_proposition' do
+    it 'adds a proposition and returns its id' do
+      result = client.add_coherence_proposition(content: 'The sky is blue', domain: :perception)
+      expect(result[:success]).to be true
+      expect(result[:proposition_id]).to match(/\A[0-9a-f-]{36}\z/)
+      expect(result[:domain]).to eq(:perception)
+    end
+
+    it 'uses default acceptance when none provided' do
+      result = client.add_coherence_proposition(content: 'Water is wet')
+      expect(result[:acceptance]).to eq(Legion::Extensions::CognitiveCoherence::Helpers::Constants::DEFAULT_ACCEPTANCE)
+    end
+
+    it 'accepts a custom acceptance value' do
+      result = client.add_coherence_proposition(content: 'Fire is hot', acceptance: 0.9)
+      expect(result[:acceptance]).to eq(0.9)
+    end
+
+    it 'returns failure for empty content' do
+      result = client.add_coherence_proposition(content: '')
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:missing_content)
+    end
+
+    it 'accepts extra keyword arguments via splat' do
+      result = client.add_coherence_proposition(content: 'test', extra_param: 'ignored')
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#add_coherence_constraint' do
+    let(:prop_a_id) { client.add_coherence_proposition(content: 'A')[:proposition_id] }
+    let(:prop_b_id) { client.add_coherence_proposition(content: 'B')[:proposition_id] }
+
+    it 'adds a positive coherence constraint between two propositions' do
+      result = client.add_coherence_constraint(
+        prop_a_id:       prop_a_id,
+        prop_b_id:       prop_b_id,
+        constraint_type: :explanatory,
+        positive:        true
+      )
+      expect(result[:success]).to be true
+      expect(result[:constraint_type]).to eq(:explanatory)
+      expect(result[:positive]).to be true
+    end
+
+    it 'adds a negative (incoherence) constraint' do
+      result = client.add_coherence_constraint(
+        prop_a_id:       prop_a_id,
+        prop_b_id:       prop_b_id,
+        constraint_type: :deductive,
+        positive:        false
+      )
+      expect(result[:success]).to be true
+      expect(result[:positive]).to be false
+    end
+
+    it 'rejects invalid constraint types' do
+      result = client.add_coherence_constraint(
+        prop_a_id:       prop_a_id,
+        prop_b_id:       prop_b_id,
+        constraint_type: :invalid_type
+      )
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:invalid_constraint_type)
+    end
+
+    it 'returns failure when proposition not found' do
+      result = client.add_coherence_constraint(
+        prop_a_id:       'nonexistent-id',
+        prop_b_id:       prop_b_id,
+        constraint_type: :explanatory
+      )
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:proposition_not_found)
+    end
+  end
+
+  describe '#compute_proposition_coherence' do
+    it 'computes coherence score for an existing proposition' do
+      result = client.add_coherence_proposition(content: 'test proposition', acceptance: 0.7)
+      prop_id = result[:proposition_id]
+
+      coherence = client.compute_proposition_coherence(proposition_id: prop_id)
+      expect(coherence[:success]).to be true
+      expect(coherence[:coherence_score]).to be_a(Float)
+      expect(coherence[:coherence_score]).to be_between(0.0, 1.0)
+    end
+
+    it 'returns not_found for missing proposition' do
+      result = client.compute_proposition_coherence(proposition_id: 'no-such-id')
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:not_found)
+    end
+
+    it 'increases coherence score when positive constraints are linked' do
+      prop_a = client.add_coherence_proposition(content: 'A', acceptance: 0.8)[:proposition_id]
+      prop_b = client.add_coherence_proposition(content: 'B', acceptance: 0.8)[:proposition_id]
+
+      score_before = client.compute_proposition_coherence(proposition_id: prop_a)[:coherence_score]
+
+      client.add_coherence_constraint(
+        prop_a_id:       prop_a,
+        prop_b_id:       prop_b,
+        constraint_type: :explanatory,
+        positive:        true
+      )
+
+      score_after = client.compute_proposition_coherence(proposition_id: prop_a)[:coherence_score]
+      expect(score_after).to be > score_before
+    end
+
+    it 'decreases coherence score when negative constraints are linked' do
+      prop_a = client.add_coherence_proposition(content: 'A', acceptance: 0.8)[:proposition_id]
+      prop_b = client.add_coherence_proposition(content: 'B', acceptance: 0.9)[:proposition_id]
+
+      score_before = client.compute_proposition_coherence(proposition_id: prop_a)[:coherence_score]
+
+      client.add_coherence_constraint(
+        prop_a_id:       prop_a,
+        prop_b_id:       prop_b,
+        constraint_type: :deductive,
+        positive:        false
+      )
+
+      score_after = client.compute_proposition_coherence(proposition_id: prop_a)[:coherence_score]
+      expect(score_after).to be < score_before
+    end
+  end
+
+  describe '#maximize_coherence' do
+    it 'returns success with iteration info when propositions exist' do
+      client.add_coherence_proposition(content: 'p1', acceptance: 0.7)
+      client.add_coherence_proposition(content: 'p2', acceptance: 0.3)
+
+      result = client.maximize_coherence
+      expect(result[:success]).to be true
+      expect(result[:proposition_count]).to eq(2)
+      expect(result[:overall_coherence]).to be_a(Float)
+    end
+
+    it 'returns success with zero iterations when no propositions' do
+      result = client.maximize_coherence
+      expect(result[:success]).to be true
+      expect(result[:iterations]).to eq(0)
+    end
+
+    it 'adjusts propositions toward coherent neighbors' do
+      prop_a = client.add_coherence_proposition(content: 'A', acceptance: 0.9)[:proposition_id]
+      prop_b = client.add_coherence_proposition(content: 'B', acceptance: 0.1)[:proposition_id]
+
+      client.add_coherence_constraint(
+        prop_a_id:       prop_a,
+        prop_b_id:       prop_b,
+        constraint_type: :explanatory,
+        positive:        true
+      )
+
+      client.maximize_coherence
+
+      prop_b_coherence = client.compute_proposition_coherence(proposition_id: prop_b)
+      expect(prop_b_coherence[:coherence_score]).to be > 0.1
+    end
+  end
+
+  describe '#find_contradictions' do
+    it 'returns empty list when no contradictions exist' do
+      client.add_coherence_proposition(content: 'p1', acceptance: 0.8)
+      result = client.find_contradictions
+      expect(result[:success]).to be true
+      expect(result[:contradictions]).to be_empty
+      expect(result[:count]).to eq(0)
+    end
+
+    it 'detects contradictory accepted propositions' do
+      prop_a = client.add_coherence_proposition(content: 'A', acceptance: 0.9)[:proposition_id]
+      prop_b = client.add_coherence_proposition(content: 'B', acceptance: 0.9)[:proposition_id]
+
+      client.add_coherence_constraint(
+        prop_a_id:       prop_a,
+        prop_b_id:       prop_b,
+        constraint_type: :deductive,
+        positive:        false
+      )
+
+      result = client.find_contradictions
+      expect(result[:count]).to eq(1)
+      expect(result[:contradictions].first).to include(:prop_a, :prop_b)
+    end
+
+    it 'does not flag contradictions when one proposition is rejected' do
+      prop_a = client.add_coherence_proposition(content: 'A', acceptance: 0.9)[:proposition_id]
+      prop_b = client.add_coherence_proposition(content: 'B', acceptance: 0.1)[:proposition_id]
+
+      client.add_coherence_constraint(
+        prop_a_id:       prop_a,
+        prop_b_id:       prop_b,
+        constraint_type: :deductive,
+        positive:        false
+      )
+
+      result = client.find_contradictions
+      expect(result[:count]).to eq(0)
+    end
+  end
+
+  describe '#coherence_partition' do
+    it 'partitions propositions by state' do
+      client.add_coherence_proposition(content: 'accepted', acceptance: 0.9)
+      client.add_coherence_proposition(content: 'rejected', acceptance: 0.1)
+      client.add_coherence_proposition(content: 'undecided', acceptance: 0.5)
+
+      result = client.coherence_partition
+      expect(result[:success]).to be true
+      expect(result[:counts][:accepted]).to be >= 1
+      expect(result[:counts][:rejected]).to be >= 1
+      expect(result[:counts][:undecided]).to be >= 1
+    end
+
+    it 'returns partition with proposition hashes' do
+      client.add_coherence_proposition(content: 'high', acceptance: 0.8)
+      result = client.coherence_partition
+      expect(result[:partition][:accepted].first).to include(:id, :content, :acceptance, :state)
+    end
+  end
+
+  describe '#update_cognitive_coherence' do
+    it 'runs maximize and decay, returning coherence info' do
+      client.add_coherence_proposition(content: 'p1', acceptance: 0.8)
+      client.add_coherence_proposition(content: 'p2', acceptance: 0.2)
+
+      result = client.update_cognitive_coherence
+      expect(result[:success]).to be true
+      expect(result[:overall_coherence]).to be_a(Float)
+      expect(result[:coherence_label]).to be_a(Symbol)
+      expect(result).to have_key(:decayed_count)
+    end
+  end
+
+  describe '#cognitive_coherence_stats' do
+    it 'returns stats summary' do
+      client.add_coherence_proposition(content: 'stat test', acceptance: 0.7)
+
+      result = client.cognitive_coherence_stats
+      expect(result[:success]).to be true
+      expect(result[:proposition_count]).to eq(1)
+      expect(result[:overall_coherence]).to be_a(Float)
+      expect(result[:coherence_label]).to be_a(Symbol)
+      expect(result[:partition_counts]).to be_a(Hash)
+      expect(result[:contradiction_count]).to be_a(Integer)
+      expect(result[:history_size]).to be_a(Integer)
+    end
+
+    it 'reports zero when no propositions' do
+      result = client.cognitive_coherence_stats
+      expect(result[:proposition_count]).to eq(0)
+      expect(result[:overall_coherence]).to eq(0.0)
+    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/cognitive_coherence'
+
+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,73 @@
+--- !ruby/object:Gem::Specification
+name: lex-cognitive-coherence
+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: 'Thagard''s coherence theory: constraint satisfaction across beliefs,
+  goals, and evidence for brain-modeled agentic AI'
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-cognitive-coherence.gemspec
+- lib/legion/extensions/cognitive_coherence.rb
+- lib/legion/extensions/cognitive_coherence/client.rb
+- lib/legion/extensions/cognitive_coherence/helpers/coherence_engine.rb
+- lib/legion/extensions/cognitive_coherence/helpers/constants.rb
+- lib/legion/extensions/cognitive_coherence/helpers/proposition.rb
+- lib/legion/extensions/cognitive_coherence/runners/cognitive_coherence.rb
+- lib/legion/extensions/cognitive_coherence/version.rb
+- spec/legion/extensions/cognitive_coherence/client_spec.rb
+- spec/legion/extensions/cognitive_coherence/runners/cognitive_coherence_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-cognitive-coherence
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-coherence
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-coherence
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-coherence
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-coherence
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-coherence/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LEX Cognitive Coherence
+test_files: []