lex-governance 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 872e980260f49400124a887b0a30dc0acb5a763440d17b20afc7c837a1e0ce4d
+  data.tar.gz: d6912d4151a41cac307e1e828733306b7ea1f32d85c126b13f2b8b5ac2fe4cb7
+SHA512:
+  metadata.gz: 7c6bf0e53ee3d3b6de474c5c3ff4f5d4d0dfc41dfa2ccf288af43e94056937ba4d4202426caf6ad24a8258fef0a330ef96e13f1b4db2935e82f367b9d03d4e0f
+  data.tar.gz: a62fda0ef8c6434646bed44760708f28bc8826c92a3e0a4572b2a68693c5ceac23defcd3b4f43b529ccb2050eb44a67ec8a65d9f0cfb16172ff5f347810ff66d

data/Gemfile

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

data/lex-governance.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/governance/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-governance'
+  spec.version       = Legion::Extensions::Governance::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Governance'
+  spec.description   = 'Four-layer distributed governance protocol for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-governance'
+  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-governance'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-governance'
+  spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-governance'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/LegionIO/lex-governance/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-governance.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/governance/actors/vote_timeout.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Governance
+      module Actor
+        class VoteTimeout < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::Governance::Runners::Governance
+          end
+
+          def runner_function
+            'timeout_proposals'
+          end
+
+          def time
+            300
+          end
+
+          def run_now?
+            false
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/governance/helpers/layers'
+require 'legion/extensions/governance/helpers/proposal'
+require 'legion/extensions/governance/runners/governance'
+
+module Legion
+  module Extensions
+    module Governance
+      class Client
+        include Runners::Governance
+
+        def initialize(**)
+          @proposal_store = Helpers::Proposal.new
+        end
+
+        private
+
+        attr_reader :proposal_store
+      end
+    end
+  end
+end

data/lib/legion/extensions/governance/helpers/layers.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Governance
+      module Helpers
+        module Layers
+          # Four governance layers (spec: governance-protocol-spec.md)
+          GOVERNANCE_LAYERS = %i[agent_validation anomaly_detection human_deliberation transparency].freeze
+
+          # Council quorum requirements
+          MIN_COUNCIL_SIZE    = 3
+          QUORUM_FRACTION     = 0.66
+          VOTE_TIMEOUT        = 86_400 # 24 hours
+          PROPOSAL_CATEGORIES = %i[policy_change resource_allocation access_control emergency protocol_update].freeze
+
+          module_function
+
+          def valid_layer?(layer)
+            GOVERNANCE_LAYERS.include?(layer)
+          end
+
+          def valid_category?(category)
+            PROPOSAL_CATEGORIES.include?(category)
+          end
+
+          def quorum_met?(votes, council_size)
+            return false if council_size < MIN_COUNCIL_SIZE
+
+            votes >= (council_size * QUORUM_FRACTION).ceil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/governance/helpers/proposal.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Governance
+      module Helpers
+        class Proposal
+          attr_reader :proposals
+
+          def initialize
+            @proposals = {}
+          end
+
+          def create(category:, description:, proposer:, council_size: Layers::MIN_COUNCIL_SIZE)
+            id = SecureRandom.uuid
+            @proposals[id] = {
+              proposal_id:   id,
+              category:      category,
+              description:   description,
+              proposer:      proposer,
+              council_size:  council_size,
+              votes_for:     [],
+              votes_against: [],
+              status:        :open,
+              created_at:    Time.now.utc,
+              resolved_at:   nil
+            }
+            id
+          end
+
+          def vote(proposal_id, voter:, approve:)
+            prop = @proposals[proposal_id]
+            return nil unless prop && prop[:status] == :open
+
+            # Prevent double-voting
+            all_voters = prop[:votes_for] + prop[:votes_against]
+            return :already_voted if all_voters.include?(voter)
+
+            if approve
+              prop[:votes_for] << voter
+            else
+              prop[:votes_against] << voter
+            end
+
+            check_resolution(proposal_id)
+          end
+
+          def get(proposal_id)
+            @proposals[proposal_id]
+          end
+
+          def open_proposals
+            @proposals.values.select { |p| p[:status] == :open }
+          end
+
+          def resolve_timed_out(proposal_id)
+            prop = @proposals[proposal_id]
+            return nil unless prop && prop[:status] == :open
+
+            prop[:status]      = :timed_out
+            prop[:resolved_at] = Time.now.utc
+            prop
+          end
+
+          private
+
+          def check_resolution(proposal_id)
+            prop = @proposals[proposal_id]
+            total_votes = prop[:votes_for].size + prop[:votes_against].size
+
+            if Layers.quorum_met?(prop[:votes_for].size, prop[:council_size])
+              prop[:status] = :approved
+              prop[:resolved_at] = Time.now.utc
+              :approved
+            elsif Layers.quorum_met?(prop[:votes_against].size, prop[:council_size]) ||
+                  total_votes >= prop[:council_size]
+              prop[:status] = :rejected
+              prop[:resolved_at] = Time.now.utc
+              :rejected
+            else
+              :pending
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Governance
+      module Runners
+        module Governance
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_proposal(category:, description:, proposer:, council_size: nil, **)
+            return { error: :invalid_category, valid: Helpers::Layers::PROPOSAL_CATEGORIES } unless Helpers::Layers.valid_category?(category)
+
+            size = council_size || Helpers::Layers::MIN_COUNCIL_SIZE
+            id = proposal_store.create(category: category, description: description,
+                                       proposer: proposer, council_size: size)
+            Legion::Logging.info "[governance] proposal created: id=#{id[0..7]} category=#{category} proposer=#{proposer} council=#{size}"
+            { proposal_id: id, category: category, status: :open }
+          end
+
+          def vote_on_proposal(proposal_id:, voter:, approve:, **)
+            result = proposal_store.vote(proposal_id, voter: voter, approve: approve)
+            case result
+            when nil
+              Legion::Logging.debug "[governance] vote failed: proposal=#{proposal_id[0..7]} not found or closed"
+              { error: :not_found_or_closed }
+            when :already_voted
+              Legion::Logging.debug "[governance] vote failed: proposal=#{proposal_id[0..7]} voter=#{voter} already voted"
+              { error: :already_voted }
+            else
+              Legion::Logging.info "[governance] vote: proposal=#{proposal_id[0..7]} voter=#{voter} approve=#{approve} resolution=#{result}"
+              { voted: true, resolution: result }
+            end
+          end
+
+          def get_proposal(proposal_id:, **)
+            prop = proposal_store.get(proposal_id)
+            Legion::Logging.debug "[governance] get: proposal=#{proposal_id[0..7]} found=#{!prop.nil?}"
+            prop ? { found: true, proposal: prop } : { found: false }
+          end
+
+          def open_proposals(**)
+            props = proposal_store.open_proposals
+            Legion::Logging.debug "[governance] open proposals: count=#{props.size}"
+            { proposals: props, count: props.size }
+          end
+
+          def timeout_proposals(**)
+            open  = proposal_store.open_proposals
+            timed = open.select { |p| Time.now.utc - p[:created_at] > Helpers::Layers::VOTE_TIMEOUT }
+            timed.each { |p| proposal_store.resolve_timed_out(p[:proposal_id]) }
+            timed_ids = timed.map { |p| p[:proposal_id] }
+            Legion::Logging.debug "[governance] vote timeout sweep: open=#{open.size} timed_out=#{timed.size}"
+            { checked: open.size, timed_out: timed.size, timed_out_ids: timed_ids }
+          end
+
+          def validate_action(layer:, action: nil, _context: {}, **) # rubocop:disable Lint/UnusedMethodArgument
+            return { error: :invalid_layer } unless Helpers::Layers.valid_layer?(layer)
+
+            result = case layer
+                     when :agent_validation
+                       { allowed: true, layer: layer, reason: :self_validated }
+                     when :anomaly_detection
+                       { allowed: true, layer: layer, reason: :no_anomaly }
+                     when :human_deliberation
+                       { allowed: false, layer: layer, reason: :requires_human_approval }
+                     when :transparency
+                       { allowed: true, layer: layer, reason: :logged, audit_required: true }
+                     end
+            Legion::Logging.debug "[governance] validate: layer=#{layer} allowed=#{result[:allowed]} reason=#{result[:reason]}"
+            result
+          end
+
+          private
+
+          def proposal_store
+            @proposal_store ||= Helpers::Proposal.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/governance.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/governance/version'
+require 'legion/extensions/governance/helpers/layers'
+require 'legion/extensions/governance/helpers/proposal'
+require 'legion/extensions/governance/runners/governance'
+
+module Legion
+  module Extensions
+    module Governance
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

data/spec/legion/extensions/governance/actors/vote_timeout_spec.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Actors
+      class Every; end # rubocop:disable Lint/EmptyClass
+    end
+  end
+end
+
+$LOADED_FEATURES << 'legion/extensions/actors/every'
+
+require_relative '../../../../../lib/legion/extensions/governance/actors/vote_timeout'
+
+RSpec.describe Legion::Extensions::Governance::Actor::VoteTimeout do
+  subject(:actor) { described_class.new }
+
+  describe '#runner_class' do
+    it { expect(actor.runner_class).to eq Legion::Extensions::Governance::Runners::Governance }
+  end
+
+  describe '#runner_function' do
+    it { expect(actor.runner_function).to eq 'timeout_proposals' }
+  end
+
+  describe '#time' do
+    it { expect(actor.time).to eq 300 }
+  end
+
+  describe '#run_now?' do
+    it { expect(actor.run_now?).to be false }
+  end
+
+  describe '#use_runner?' do
+    it { expect(actor.use_runner?).to be false }
+  end
+
+  describe '#check_subtask?' do
+    it { expect(actor.check_subtask?).to be false }
+  end
+
+  describe '#generate_task?' do
+    it { expect(actor.generate_task?).to be false }
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/governance/client'
+
+RSpec.describe Legion::Extensions::Governance::Client do
+  it 'responds to governance runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:create_proposal)
+    expect(client).to respond_to(:vote_on_proposal)
+    expect(client).to respond_to(:get_proposal)
+    expect(client).to respond_to(:open_proposals)
+    expect(client).to respond_to(:validate_action)
+  end
+end

data/spec/legion/extensions/governance/helpers/layers_spec.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/governance/helpers/layers'
+
+RSpec.describe Legion::Extensions::Governance::Helpers::Layers do
+  describe 'GOVERNANCE_LAYERS' do
+    it 'contains four layers as symbols' do
+      expect(described_class::GOVERNANCE_LAYERS.size).to eq(4)
+    end
+
+    it 'includes agent_validation' do
+      expect(described_class::GOVERNANCE_LAYERS).to include(:agent_validation)
+    end
+
+    it 'includes anomaly_detection' do
+      expect(described_class::GOVERNANCE_LAYERS).to include(:anomaly_detection)
+    end
+
+    it 'includes human_deliberation' do
+      expect(described_class::GOVERNANCE_LAYERS).to include(:human_deliberation)
+    end
+
+    it 'includes transparency' do
+      expect(described_class::GOVERNANCE_LAYERS).to include(:transparency)
+    end
+
+    it 'is frozen' do
+      expect(described_class::GOVERNANCE_LAYERS).to be_frozen
+    end
+  end
+
+  describe 'PROPOSAL_CATEGORIES' do
+    it 'contains five categories' do
+      expect(described_class::PROPOSAL_CATEGORIES.size).to eq(5)
+    end
+
+    it 'includes policy_change' do
+      expect(described_class::PROPOSAL_CATEGORIES).to include(:policy_change)
+    end
+
+    it 'includes resource_allocation' do
+      expect(described_class::PROPOSAL_CATEGORIES).to include(:resource_allocation)
+    end
+
+    it 'includes access_control' do
+      expect(described_class::PROPOSAL_CATEGORIES).to include(:access_control)
+    end
+
+    it 'includes emergency' do
+      expect(described_class::PROPOSAL_CATEGORIES).to include(:emergency)
+    end
+
+    it 'includes protocol_update' do
+      expect(described_class::PROPOSAL_CATEGORIES).to include(:protocol_update)
+    end
+
+    it 'is frozen' do
+      expect(described_class::PROPOSAL_CATEGORIES).to be_frozen
+    end
+  end
+
+  describe 'numeric constants' do
+    it 'sets MIN_COUNCIL_SIZE to 3' do
+      expect(described_class::MIN_COUNCIL_SIZE).to eq(3)
+    end
+
+    it 'sets QUORUM_FRACTION to 0.66' do
+      expect(described_class::QUORUM_FRACTION).to eq(0.66)
+    end
+
+    it 'sets VOTE_TIMEOUT to 86400' do
+      expect(described_class::VOTE_TIMEOUT).to eq(86_400)
+    end
+  end
+
+  describe '.valid_layer?' do
+    it 'returns true for agent_validation' do
+      expect(described_class.valid_layer?(:agent_validation)).to be true
+    end
+
+    it 'returns true for anomaly_detection' do
+      expect(described_class.valid_layer?(:anomaly_detection)).to be true
+    end
+
+    it 'returns true for human_deliberation' do
+      expect(described_class.valid_layer?(:human_deliberation)).to be true
+    end
+
+    it 'returns true for transparency' do
+      expect(described_class.valid_layer?(:transparency)).to be true
+    end
+
+    it 'returns false for unknown layer symbol' do
+      expect(described_class.valid_layer?(:unknown)).to be false
+    end
+
+    it 'returns false for nil' do
+      expect(described_class.valid_layer?(nil)).to be false
+    end
+
+    it 'returns false for string version of valid layer' do
+      expect(described_class.valid_layer?('agent_validation')).to be false
+    end
+  end
+
+  describe '.valid_category?' do
+    it 'returns true for policy_change' do
+      expect(described_class.valid_category?(:policy_change)).to be true
+    end
+
+    it 'returns true for resource_allocation' do
+      expect(described_class.valid_category?(:resource_allocation)).to be true
+    end
+
+    it 'returns true for access_control' do
+      expect(described_class.valid_category?(:access_control)).to be true
+    end
+
+    it 'returns true for emergency' do
+      expect(described_class.valid_category?(:emergency)).to be true
+    end
+
+    it 'returns true for protocol_update' do
+      expect(described_class.valid_category?(:protocol_update)).to be true
+    end
+
+    it 'returns false for unknown category' do
+      expect(described_class.valid_category?(:invalid)).to be false
+    end
+
+    it 'returns false for nil' do
+      expect(described_class.valid_category?(nil)).to be false
+    end
+
+    it 'returns false for string version of valid category' do
+      expect(described_class.valid_category?('emergency')).to be false
+    end
+  end
+
+  describe '.quorum_met?' do
+    context 'when council_size is below minimum' do
+      it 'returns false for council_size of 2' do
+        expect(described_class.quorum_met?(2, 2)).to be false
+      end
+
+      it 'returns false for council_size of 1' do
+        expect(described_class.quorum_met?(1, 1)).to be false
+      end
+
+      it 'returns false for council_size of 0' do
+        expect(described_class.quorum_met?(0, 0)).to be false
+      end
+    end
+
+    context 'with minimum council size of 3' do
+      it 'returns true when 2 of 3 vote (meets ceil(3 * 0.66) = 2)' do
+        expect(described_class.quorum_met?(2, 3)).to be true
+      end
+
+      it 'returns true when all 3 vote' do
+        expect(described_class.quorum_met?(3, 3)).to be true
+      end
+
+      it 'returns false when only 1 of 3 vote' do
+        expect(described_class.quorum_met?(1, 3)).to be false
+      end
+    end
+
+    context 'with larger council sizes' do
+      it 'requires ceil(4 * 0.66) = 3 votes for council of 4' do
+        expect(described_class.quorum_met?(3, 4)).to be true
+        expect(described_class.quorum_met?(2, 4)).to be false
+      end
+
+      it 'requires ceil(5 * 0.66) = 4 votes for council of 5' do
+        expect(described_class.quorum_met?(4, 5)).to be true
+        expect(described_class.quorum_met?(3, 5)).to be false
+      end
+
+      it 'requires ceil(9 * 0.66) = 6 votes for council of 9' do
+        expect(described_class.quorum_met?(6, 9)).to be true
+        expect(described_class.quorum_met?(5, 9)).to be false
+      end
+    end
+
+    it 'returns false for zero votes regardless of council size' do
+      expect(described_class.quorum_met?(0, 3)).to be false
+    end
+  end
+end

data/spec/legion/extensions/governance/helpers/proposal_spec.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/governance/helpers/layers'
+require 'legion/extensions/governance/helpers/proposal'
+
+RSpec.describe Legion::Extensions::Governance::Helpers::Proposal do
+  subject(:proposal_store) { described_class.new }
+
+  describe '#initialize' do
+    it 'starts with an empty proposals hash' do
+      expect(proposal_store.proposals).to eq({})
+    end
+  end
+
+  describe '#create' do
+    let(:created_id) do
+      proposal_store.create(category: :policy_change, description: 'Enable new policy', proposer: 'agent-1')
+    end
+
+    it 'returns a UUID string' do
+      expect(created_id).to match(/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/)
+    end
+
+    it 'stores the proposal under the returned ID' do
+      expect(proposal_store.proposals[created_id]).not_to be_nil
+    end
+
+    it 'stores the correct category' do
+      expect(proposal_store.proposals[created_id][:category]).to eq(:policy_change)
+    end
+
+    it 'stores the correct description' do
+      expect(proposal_store.proposals[created_id][:description]).to eq('Enable new policy')
+    end
+
+    it 'stores the correct proposer' do
+      expect(proposal_store.proposals[created_id][:proposer]).to eq('agent-1')
+    end
+
+    it 'defaults council_size to MIN_COUNCIL_SIZE' do
+      expect(proposal_store.proposals[created_id][:council_size])
+        .to eq(Legion::Extensions::Governance::Helpers::Layers::MIN_COUNCIL_SIZE)
+    end
+
+    it 'uses the provided council_size when specified' do
+      id = proposal_store.create(category: :emergency, description: 'urgent', proposer: 'agent-x', council_size: 7)
+      expect(proposal_store.proposals[id][:council_size]).to eq(7)
+    end
+
+    it 'initializes with status :open' do
+      expect(proposal_store.proposals[created_id][:status]).to eq(:open)
+    end
+
+    it 'initializes votes_for as empty array' do
+      expect(proposal_store.proposals[created_id][:votes_for]).to eq([])
+    end
+
+    it 'initializes votes_against as empty array' do
+      expect(proposal_store.proposals[created_id][:votes_against]).to eq([])
+    end
+
+    it 'sets created_at to a Time object' do
+      expect(proposal_store.proposals[created_id][:created_at]).to be_a(Time)
+    end
+
+    it 'sets resolved_at to nil initially' do
+      expect(proposal_store.proposals[created_id][:resolved_at]).to be_nil
+    end
+
+    it 'generates unique IDs for separate calls' do
+      id1 = proposal_store.create(category: :policy_change, description: 'a', proposer: 'x')
+      id2 = proposal_store.create(category: :policy_change, description: 'b', proposer: 'y')
+      expect(id1).not_to eq(id2)
+    end
+  end
+
+  describe '#get' do
+    it 'returns the proposal hash for a valid ID' do
+      id = proposal_store.create(category: :policy_change, description: 'test', proposer: 'agent-1')
+      result = proposal_store.get(id)
+      expect(result[:proposal_id]).to eq(id)
+    end
+
+    it 'returns nil for an unknown ID' do
+      expect(proposal_store.get('nonexistent-uuid')).to be_nil
+    end
+  end
+
+  describe '#open_proposals' do
+    it 'returns empty array when no proposals exist' do
+      expect(proposal_store.open_proposals).to eq([])
+    end
+
+    it 'returns all open proposals' do
+      proposal_store.create(category: :policy_change, description: 'first', proposer: 'a1')
+      proposal_store.create(category: :emergency, description: 'second', proposer: 'a2')
+      expect(proposal_store.open_proposals.size).to eq(2)
+    end
+
+    it 'excludes resolved proposals' do
+      id = proposal_store.create(category: :policy_change, description: 'vote me', proposer: 'a1', council_size: 3)
+      proposal_store.vote(id, voter: 'v1', approve: true)
+      proposal_store.vote(id, voter: 'v2', approve: true)
+      expect(proposal_store.open_proposals).to be_empty
+    end
+  end
+
+  describe '#vote' do
+    let(:proposal_id) do
+      proposal_store.create(category: :policy_change, description: 'test', proposer: 'agent-1', council_size: 3)
+    end
+
+    it 'returns nil for an unknown proposal ID' do
+      expect(proposal_store.vote('no-such-id', voter: 'v1', approve: true)).to be_nil
+    end
+
+    it 'returns :already_voted when the same voter votes twice' do
+      proposal_store.vote(proposal_id, voter: 'v1', approve: true)
+      result = proposal_store.vote(proposal_id, voter: 'v1', approve: false)
+      expect(result).to eq(:already_voted)
+    end
+
+    it 'prevents double voting even when switching approve/reject' do
+      proposal_store.vote(proposal_id, voter: 'v1', approve: false)
+      result = proposal_store.vote(proposal_id, voter: 'v1', approve: true)
+      expect(result).to eq(:already_voted)
+    end
+
+    it 'adds approve vote to votes_for' do
+      proposal_store.vote(proposal_id, voter: 'v1', approve: true)
+      expect(proposal_store.proposals[proposal_id][:votes_for]).to include('v1')
+    end
+
+    it 'adds reject vote to votes_against' do
+      proposal_store.vote(proposal_id, voter: 'v1', approve: false)
+      expect(proposal_store.proposals[proposal_id][:votes_against]).to include('v1')
+    end
+
+    it 'returns :pending when quorum is not yet met' do
+      result = proposal_store.vote(proposal_id, voter: 'v1', approve: true)
+      expect(result).to eq(:pending)
+    end
+
+    context 'when quorum for approval is met' do
+      it 'returns :approved and sets status' do
+        proposal_store.vote(proposal_id, voter: 'v1', approve: true)
+        result = proposal_store.vote(proposal_id, voter: 'v2', approve: true)
+        expect(result).to eq(:approved)
+        expect(proposal_store.proposals[proposal_id][:status]).to eq(:approved)
+      end
+
+      it 'sets resolved_at on approval' do
+        proposal_store.vote(proposal_id, voter: 'v1', approve: true)
+        proposal_store.vote(proposal_id, voter: 'v2', approve: true)
+        expect(proposal_store.proposals[proposal_id][:resolved_at]).to be_a(Time)
+      end
+    end
+
+    context 'when quorum for rejection is met' do
+      it 'returns :rejected when enough votes against' do
+        proposal_store.vote(proposal_id, voter: 'v1', approve: false)
+        result = proposal_store.vote(proposal_id, voter: 'v2', approve: false)
+        expect(result).to eq(:rejected)
+        expect(proposal_store.proposals[proposal_id][:status]).to eq(:rejected)
+      end
+
+      it 'sets resolved_at on rejection' do
+        proposal_store.vote(proposal_id, voter: 'v1', approve: false)
+        proposal_store.vote(proposal_id, voter: 'v2', approve: false)
+        expect(proposal_store.proposals[proposal_id][:resolved_at]).to be_a(Time)
+      end
+
+      it 'returns :rejected when all council members voted and no quorum for approval' do
+        proposal_store.vote(proposal_id, voter: 'v1', approve: true)
+        proposal_store.vote(proposal_id, voter: 'v2', approve: false)
+        result = proposal_store.vote(proposal_id, voter: 'v3', approve: false)
+        expect(result).to eq(:rejected)
+      end
+    end
+
+    it 'returns nil when voting on a resolved (approved) proposal' do
+      proposal_store.vote(proposal_id, voter: 'v1', approve: true)
+      proposal_store.vote(proposal_id, voter: 'v2', approve: true)
+      result = proposal_store.vote(proposal_id, voter: 'v3', approve: true)
+      expect(result).to be_nil
+    end
+  end
+end

data/spec/legion/extensions/governance/runners/governance_spec.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/governance/client'
+
+RSpec.describe Legion::Extensions::Governance::Runners::Governance do
+  let(:client) { Legion::Extensions::Governance::Client.new }
+
+  describe '#create_proposal' do
+    it 'creates a proposal' do
+      result = client.create_proposal(category: :policy_change, description: 'test', proposer: 'agent-1')
+      expect(result[:proposal_id]).to match(/\A[0-9a-f-]{36}\z/)
+      expect(result[:status]).to eq(:open)
+    end
+
+    it 'rejects invalid category' do
+      result = client.create_proposal(category: :invalid, description: 'test', proposer: 'agent-1')
+      expect(result[:error]).to eq(:invalid_category)
+    end
+  end
+
+  describe '#vote_on_proposal' do
+    it 'records a vote' do
+      prop = client.create_proposal(category: :policy_change, description: 'test', proposer: 'agent-1', council_size: 3)
+      result = client.vote_on_proposal(proposal_id: prop[:proposal_id], voter: 'agent-2', approve: true)
+      expect(result[:voted]).to be true
+    end
+
+    it 'prevents double voting' do
+      prop = client.create_proposal(category: :policy_change, description: 'test', proposer: 'agent-1', council_size: 3)
+      client.vote_on_proposal(proposal_id: prop[:proposal_id], voter: 'agent-2', approve: true)
+      result = client.vote_on_proposal(proposal_id: prop[:proposal_id], voter: 'agent-2', approve: true)
+      expect(result[:error]).to eq(:already_voted)
+    end
+
+    it 'approves with quorum' do
+      prop = client.create_proposal(category: :policy_change, description: 'test', proposer: 'agent-1', council_size: 3)
+      client.vote_on_proposal(proposal_id: prop[:proposal_id], voter: 'v1', approve: true)
+      result = client.vote_on_proposal(proposal_id: prop[:proposal_id], voter: 'v2', approve: true)
+      expect(result[:resolution]).to eq(:approved)
+    end
+  end
+
+  describe '#validate_action' do
+    it 'allows agent_validation' do
+      result = client.validate_action(layer: :agent_validation, action: 'test')
+      expect(result[:allowed]).to be true
+    end
+
+    it 'blocks human_deliberation' do
+      result = client.validate_action(layer: :human_deliberation, action: 'test')
+      expect(result[:allowed]).to be false
+    end
+
+    it 'rejects invalid layer' do
+      result = client.validate_action(layer: :invalid, action: 'test')
+      expect(result[:error]).to eq(:invalid_layer)
+    end
+  end
+
+  describe '#open_proposals' do
+    it 'lists open proposals' do
+      client.create_proposal(category: :policy_change, description: 'test', proposer: 'agent-1')
+      result = client.open_proposals
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#timeout_proposals' do
+    it 'returns zero timed_out when no proposals exist' do
+      result = client.timeout_proposals
+      expect(result[:checked]).to eq(0)
+      expect(result[:timed_out]).to eq(0)
+      expect(result[:timed_out_ids]).to eq([])
+    end
+
+    it 'returns zero timed_out for recently created proposals' do
+      client.create_proposal(category: :policy_change, description: 'fresh', proposer: 'agent-1')
+      result = client.timeout_proposals
+      expect(result[:timed_out]).to eq(0)
+    end
+
+    it 'times out proposals older than VOTE_TIMEOUT' do
+      prop = client.create_proposal(category: :policy_change, description: 'old', proposer: 'agent-1')
+      store = client.instance_variable_get(:@proposal_store)
+      store.proposals[prop[:proposal_id]][:created_at] = Time.now.utc - (Legion::Extensions::Governance::Helpers::Layers::VOTE_TIMEOUT + 1)
+      result = client.timeout_proposals
+      expect(result[:timed_out]).to eq(1)
+      expect(result[:timed_out_ids]).to include(prop[:proposal_id])
+    end
+
+    it 'does not time out already-resolved proposals' do
+      prop = client.create_proposal(category: :policy_change, description: 'resolved', proposer: 'agent-1', council_size: 3)
+      store = client.instance_variable_get(:@proposal_store)
+      store.proposals[prop[:proposal_id]][:created_at] = Time.now.utc - (Legion::Extensions::Governance::Helpers::Layers::VOTE_TIMEOUT + 1)
+      client.vote_on_proposal(proposal_id: prop[:proposal_id], voter: 'v1', approve: true)
+      client.vote_on_proposal(proposal_id: prop[:proposal_id], voter: 'v2', approve: true)
+      result = client.timeout_proposals
+      expect(result[:timed_out]).to eq(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/governance'
+
+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,76 @@
+--- !ruby/object:Gem::Specification
+name: lex-governance
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+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: Four-layer distributed governance protocol for brain-modeled agentic
+  AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-governance.gemspec
+- lib/legion/extensions/governance.rb
+- lib/legion/extensions/governance/actors/vote_timeout.rb
+- lib/legion/extensions/governance/client.rb
+- lib/legion/extensions/governance/helpers/layers.rb
+- lib/legion/extensions/governance/helpers/proposal.rb
+- lib/legion/extensions/governance/runners/governance.rb
+- lib/legion/extensions/governance/version.rb
+- spec/legion/extensions/governance/actors/vote_timeout_spec.rb
+- spec/legion/extensions/governance/client_spec.rb
+- spec/legion/extensions/governance/helpers/layers_spec.rb
+- spec/legion/extensions/governance/helpers/proposal_spec.rb
+- spec/legion/extensions/governance/runners/governance_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-governance
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-governance
+  source_code_uri: https://github.com/LegionIO/lex-governance
+  documentation_uri: https://github.com/LegionIO/lex-governance
+  changelog_uri: https://github.com/LegionIO/lex-governance
+  bug_tracker_uri: https://github.com/LegionIO/lex-governance/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 Governance
+test_files: []