lex-swarm-github 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 61d22af3c76a1f33ab47be20d57136e7d0ef11f37731f061876def2d5521dfdd
+  data.tar.gz: ac3a2e94eadd471471797c65a322c161855b0c6fe8941cf866693a0aaab3899c
+SHA512:
+  metadata.gz: ff1696a0d7d26f1abeafb6297c44eecd047919c6eeaef2bf0a5c74228d90bc1f8fdf85ce69a7ab42f0bec2b130d2bf607a76d272ad0eaa9dcc0393546d9dd389
+  data.tar.gz: ac02d9ff34695164586433ea124bd22ce665f3a689fb74d55982bd89cd44c90397373891535240fd077664aeb962856eae298eeec5d13c8208d35a0e14a8ce71

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-swarm-github.gemspec

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

data/lib/legion/extensions/swarm_github/actors/stale_issues.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module SwarmGithub
+      module Actor
+        class StaleIssues < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::SwarmGithub::Runners::GithubSwarm
+          end
+
+          def runner_function
+            'mark_stale_issues'
+          end
+
+          def time
+            3600
+          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/swarm_github/client.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/swarm_github/helpers/pipeline'
+require 'legion/extensions/swarm_github/helpers/issue_tracker'
+require 'legion/extensions/swarm_github/runners/github_swarm'
+
+module Legion
+  module Extensions
+    module SwarmGithub
+      class Client
+        include Runners::GithubSwarm
+
+        def initialize(**)
+          @issue_tracker = Helpers::IssueTracker.new
+        end
+
+        private
+
+        attr_reader :issue_tracker
+      end
+    end
+  end
+end

data/lib/legion/extensions/swarm_github/helpers/issue_tracker.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module SwarmGithub
+      module Helpers
+        class IssueTracker
+          attr_reader :issues
+
+          def initialize
+            @issues = {}
+          end
+
+          def track(repo:, issue_number:, title:, labels: [])
+            key = "#{repo}##{issue_number}"
+            @issues[key] = {
+              repo:         repo,
+              issue_number: issue_number,
+              title:        title,
+              labels:       labels,
+              state:        :received,
+              fix_attempts: 0,
+              validations:  [],
+              pr_number:    nil,
+              created_at:   Time.now.utc,
+              updated_at:   Time.now.utc
+            }
+            key
+          end
+
+          def transition(key, to_state)
+            issue = @issues[key]
+            return nil unless issue
+            return :invalid_state unless Pipeline.valid_state?(to_state)
+
+            issue[:state] = to_state
+            issue[:updated_at] = Time.now.utc
+            issue[:labels] = [Pipeline.label_for_state(to_state)]
+            to_state
+          end
+
+          def record_fix_attempt(key)
+            issue = @issues[key]
+            return nil unless issue
+
+            issue[:fix_attempts] += 1
+            issue[:fix_attempts]
+          end
+
+          def record_validation(key, validator:, approved:, reason: nil)
+            issue = @issues[key]
+            return nil unless issue
+
+            issue[:validations] << { validator: validator, approved: approved, reason: reason, at: Time.now.utc }
+            check_validation_consensus(key)
+          end
+
+          def attach_pr(key, pr_number:)
+            issue = @issues[key]
+            return nil unless issue
+
+            issue[:pr_number] = pr_number
+            issue[:state] = :pr_open
+            issue[:updated_at] = Time.now.utc
+          end
+
+          def get(key)
+            @issues[key]
+          end
+
+          def by_state(state)
+            @issues.values.select { |i| i[:state] == state }
+          end
+
+          def count
+            @issues.size
+          end
+
+          private
+
+          def check_validation_consensus(key)
+            issue = @issues[key]
+            approvals = issue[:validations].count { |v| v[:approved] }
+            rejections = issue[:validations].count { |v| !v[:approved] }
+
+            if approvals >= Pipeline::ADVERSARIAL_REVIEW_K
+              :approved
+            elsif rejections >= Pipeline::ADVERSARIAL_REVIEW_K
+              :rejected
+            else
+              :pending
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/swarm_github/helpers/pipeline.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SwarmGithub
+      module Helpers
+        module Pipeline
+          # GitHub swarm state machine (spec: swarm-implementation-spec.md)
+          STATES = %i[received found fixing validating approved pr_open rejected stale].freeze
+          LABELS = STATES.map { |s| :"swarm:#{s}" }.freeze
+
+          # Agent roles in the GitHub pipeline
+          PIPELINE_ROLES = %i[finder fixer validator pr_swarm].freeze
+
+          # Validation
+          ADVERSARIAL_REVIEW_K = 3 # number of independent validators
+          MAX_FIX_ATTEMPTS     = 3
+          STALE_TIMEOUT        = 86_400 # 24 hours
+
+          module_function
+
+          def valid_state?(state)
+            STATES.include?(state)
+          end
+
+          def label_for_state(state)
+            "swarm:#{state}"
+          end
+
+          def next_state(current)
+            {
+              received:   :found,
+              found:      :fixing,
+              fixing:     :validating,
+              validating: :approved,
+              approved:   :pr_open
+            }[current]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/swarm_github/runners/github_swarm.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SwarmGithub
+      module Runners
+        module GithubSwarm
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def ingest_issue(repo:, issue_number:, title:, labels: [], **)
+            key = issue_tracker.track(repo: repo, issue_number: issue_number, title: title, labels: labels)
+            Legion::Logging.info "[github-swarm] ingested: key=#{key} title=#{title}"
+            { tracked: true, key: key, state: :received }
+          end
+
+          def claim_issue(key:, **)
+            result = issue_tracker.transition(key, :found)
+            if result == :found
+              Legion::Logging.info "[github-swarm] claimed: key=#{key}"
+              { claimed: true, state: :found }
+            else
+              Legion::Logging.debug "[github-swarm] claim failed: key=#{key} result=#{result}"
+              { error: result || :not_found }
+            end
+          end
+
+          def start_fix(key:, **)
+            issue_tracker.transition(key, :fixing)
+            attempt = issue_tracker.record_fix_attempt(key)
+            if attempt && attempt > Helpers::Pipeline::MAX_FIX_ATTEMPTS
+              Legion::Logging.warn "[github-swarm] max attempts exceeded: key=#{key} attempts=#{attempt}"
+              { error: :max_attempts_exceeded, attempts: attempt }
+            else
+              Legion::Logging.info "[github-swarm] fix started: key=#{key} attempt=#{attempt}"
+              { fixing: true, attempt: attempt }
+            end
+          end
+
+          def submit_validation(key:, validator:, approved:, reason: nil, **)
+            consensus = issue_tracker.record_validation(key, validator: validator,
+                                                            approved: approved, reason: reason)
+            if consensus
+              Legion::Logging.info "[github-swarm] validation: key=#{key} validator=#{validator} approved=#{approved} consensus=#{consensus}"
+              { recorded: true, consensus: consensus }
+            else
+              Legion::Logging.debug "[github-swarm] validation failed: key=#{key} not found"
+              { error: :not_found }
+            end
+          end
+
+          def attach_pr(key:, pr_number:, **)
+            result = issue_tracker.attach_pr(key, pr_number: pr_number)
+            if result
+              Legion::Logging.info "[github-swarm] PR attached: key=#{key} pr=##{pr_number}"
+              { attached: true, pr_number: pr_number }
+            else
+              Legion::Logging.debug "[github-swarm] PR attach failed: key=#{key} not found"
+              { error: :not_found }
+            end
+          end
+
+          def get_issue(key:, **)
+            issue = issue_tracker.get(key)
+            Legion::Logging.debug "[github-swarm] get: key=#{key} found=#{!issue.nil?}"
+            issue ? { found: true, issue: issue } : { found: false }
+          end
+
+          def issues_by_state(state:, **)
+            issues = issue_tracker.by_state(state)
+            Legion::Logging.debug "[github-swarm] by_state: state=#{state} count=#{issues.size}"
+            { issues: issues, count: issues.size }
+          end
+
+          def pipeline_status(**)
+            status = Helpers::Pipeline::STATES.to_h do |state|
+              [state, issue_tracker.by_state(state).size]
+            end
+            summary = status.select { |_, v| v.positive? }.map { |k, v| "#{k}=#{v}" }.join(' ')
+            Legion::Logging.debug "[github-swarm] pipeline: total=#{issue_tracker.count} #{summary}"
+            { states: status, total: issue_tracker.count }
+          end
+
+          def mark_stale_issues(**)
+            terminal  = %i[approved pr_open rejected stale]
+            now       = Time.now.utc
+            timeout   = Helpers::Pipeline::STALE_TIMEOUT
+            stale_keys = []
+            issue_tracker.issues.each do |key, issue|
+              next if terminal.include?(issue[:state])
+              next unless now - issue[:updated_at] > timeout
+
+              issue_tracker.transition(key, :stale)
+              stale_keys << key
+            end
+            Legion::Logging.debug "[swarm-github] stale check: checked=#{issue_tracker.count} stale=#{stale_keys.size}"
+            { checked: issue_tracker.count, marked_stale: stale_keys.size, stale_keys: stale_keys }
+          end
+
+          private
+
+          def issue_tracker
+            @issue_tracker ||= Helpers::IssueTracker.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/swarm_github.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/swarm_github/version'
+require 'legion/extensions/swarm_github/helpers/pipeline'
+require 'legion/extensions/swarm_github/helpers/issue_tracker'
+require 'legion/extensions/swarm_github/runners/github_swarm'
+
+module Legion
+  module Extensions
+    module SwarmGithub
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

data/spec/legion/extensions/swarm_github/actors/stale_issues_spec.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Actors
+      class Every # rubocop:disable Lint/EmptyClass
+      end
+    end
+  end
+end
+
+$LOADED_FEATURES << 'legion/extensions/actors/every'
+
+require_relative '../../../../../lib/legion/extensions/swarm_github/actors/stale_issues'
+
+RSpec.describe Legion::Extensions::SwarmGithub::Actor::StaleIssues do
+  subject(:actor) { described_class.new }
+
+  describe '#runner_class' do
+    it { expect(actor.runner_class).to eq Legion::Extensions::SwarmGithub::Runners::GithubSwarm }
+  end
+
+  describe '#runner_function' do
+    it { expect(actor.runner_function).to eq 'mark_stale_issues' }
+  end
+
+  describe '#time' do
+    it { expect(actor.time).to eq 3600 }
+  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/swarm_github/client_spec.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/swarm_github/client'
+
+RSpec.describe Legion::Extensions::SwarmGithub::Client do
+  it 'responds to github swarm runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:ingest_issue)
+    expect(client).to respond_to(:claim_issue)
+    expect(client).to respond_to(:start_fix)
+    expect(client).to respond_to(:submit_validation)
+    expect(client).to respond_to(:attach_pr)
+    expect(client).to respond_to(:get_issue)
+    expect(client).to respond_to(:issues_by_state)
+    expect(client).to respond_to(:pipeline_status)
+  end
+end

data/spec/legion/extensions/swarm_github/helpers/issue_tracker_spec.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::SwarmGithub::Helpers::IssueTracker do
+  let(:tracker) { described_class.new }
+  let(:pipeline) { Legion::Extensions::SwarmGithub::Helpers::Pipeline }
+
+  let(:repo) { 'org/repo' }
+  let(:issue_number) { 42 }
+  let(:key) { "#{repo}##{issue_number}" }
+
+  before { tracker.track(repo: repo, issue_number: issue_number, title: 'Fix the bug') }
+
+  describe '#initialize' do
+    it 'starts with an empty issues hash' do
+      expect(described_class.new.issues).to eq({})
+    end
+  end
+
+  describe '#track' do
+    it 'returns the composite key' do
+      k = described_class.new.track(repo: 'a/b', issue_number: 1, title: 'test')
+      expect(k).to eq('a/b#1')
+    end
+
+    it 'stores the issue under the composite key' do
+      expect(tracker.issues[key]).not_to be_nil
+    end
+
+    it 'sets initial state to :received' do
+      expect(tracker.issues[key][:state]).to eq(:received)
+    end
+
+    it 'stores the repo' do
+      expect(tracker.issues[key][:repo]).to eq(repo)
+    end
+
+    it 'stores the issue_number' do
+      expect(tracker.issues[key][:issue_number]).to eq(issue_number)
+    end
+
+    it 'stores the title' do
+      expect(tracker.issues[key][:title]).to eq('Fix the bug')
+    end
+
+    it 'starts fix_attempts at 0' do
+      expect(tracker.issues[key][:fix_attempts]).to eq(0)
+    end
+
+    it 'starts with an empty validations array' do
+      expect(tracker.issues[key][:validations]).to eq([])
+    end
+
+    it 'starts with pr_number nil' do
+      expect(tracker.issues[key][:pr_number]).to be_nil
+    end
+
+    it 'stores provided labels' do
+      t = described_class.new
+      t.track(repo: 'a/b', issue_number: 1, title: 'test', labels: %w[bug critical])
+      expect(t.issues['a/b#1'][:labels]).to eq(%w[bug critical])
+    end
+
+    it 'defaults labels to empty array' do
+      expect(tracker.issues[key][:labels]).to eq([])
+    end
+
+    it 'records created_at as a UTC Time' do
+      before = Time.now.utc
+      t = described_class.new
+      t.track(repo: 'a/b', issue_number: 1, title: 'test')
+      after = Time.now.utc
+      expect(t.issues['a/b#1'][:created_at]).to be_between(before, after)
+    end
+
+    it 'records updated_at as a UTC Time on creation' do
+      expect(tracker.issues[key][:updated_at]).not_to be_nil
+    end
+  end
+
+  describe '#transition' do
+    it 'returns the new state when valid' do
+      result = tracker.transition(key, :found)
+      expect(result).to eq(:found)
+    end
+
+    it 'updates the issue state' do
+      tracker.transition(key, :found)
+      expect(tracker.issues[key][:state]).to eq(:found)
+    end
+
+    it 'updates the labels array to the single swarm label for the new state' do
+      tracker.transition(key, :found)
+      expect(tracker.issues[key][:labels]).to eq([pipeline.label_for_state(:found)])
+    end
+
+    it 'updates updated_at on transition' do
+      before = Time.now.utc
+      tracker.transition(key, :found)
+      after = Time.now.utc
+      expect(tracker.issues[key][:updated_at]).to be_between(before, after)
+    end
+
+    it 'returns :invalid_state for an unknown state symbol' do
+      expect(tracker.transition(key, :nonexistent)).to eq(:invalid_state)
+    end
+
+    it 'returns nil for an unknown issue key' do
+      expect(tracker.transition('bad/key#99', :found)).to be_nil
+    end
+
+    it 'can transition through multiple valid states' do
+      tracker.transition(key, :found)
+      tracker.transition(key, :fixing)
+      expect(tracker.issues[key][:state]).to eq(:fixing)
+    end
+  end
+
+  describe '#record_fix_attempt' do
+    it 'returns 1 on the first attempt' do
+      expect(tracker.record_fix_attempt(key)).to eq(1)
+    end
+
+    it 'increments fix_attempts on the issue' do
+      tracker.record_fix_attempt(key)
+      expect(tracker.issues[key][:fix_attempts]).to eq(1)
+    end
+
+    it 'returns the running total after multiple calls' do
+      tracker.record_fix_attempt(key)
+      tracker.record_fix_attempt(key)
+      expect(tracker.record_fix_attempt(key)).to eq(3)
+    end
+
+    it 'returns nil for an unknown key' do
+      expect(tracker.record_fix_attempt('bad/key#0')).to be_nil
+    end
+  end
+
+  describe '#record_validation' do
+    it 'appends the validation to the validations array' do
+      tracker.record_validation(key, validator: 'v1', approved: true)
+      expect(tracker.issues[key][:validations].size).to eq(1)
+    end
+
+    it 'stores the validator identifier' do
+      tracker.record_validation(key, validator: 'v1', approved: true)
+      expect(tracker.issues[key][:validations].first[:validator]).to eq('v1')
+    end
+
+    it 'stores the approved flag' do
+      tracker.record_validation(key, validator: 'v1', approved: false)
+      expect(tracker.issues[key][:validations].first[:approved]).to be false
+    end
+
+    it 'stores an optional reason' do
+      tracker.record_validation(key, validator: 'v1', approved: false, reason: 'needs more tests')
+      expect(tracker.issues[key][:validations].first[:reason]).to eq('needs more tests')
+    end
+
+    it 'stores nil for reason when not provided' do
+      tracker.record_validation(key, validator: 'v1', approved: true)
+      expect(tracker.issues[key][:validations].first[:reason]).to be_nil
+    end
+
+    it 'records a timestamp on each validation' do
+      before = Time.now.utc
+      tracker.record_validation(key, validator: 'v1', approved: true)
+      after = Time.now.utc
+      expect(tracker.issues[key][:validations].first[:at]).to be_between(before, after)
+    end
+
+    it 'returns :pending when fewer than ADVERSARIAL_REVIEW_K approvals exist' do
+      tracker.record_validation(key, validator: 'v1', approved: true)
+      result = tracker.record_validation(key, validator: 'v2', approved: true)
+      expect(result).to eq(:pending)
+    end
+
+    it 'returns :approved when ADVERSARIAL_REVIEW_K approvals are reached' do
+      tracker.record_validation(key, validator: 'v1', approved: true)
+      tracker.record_validation(key, validator: 'v2', approved: true)
+      result = tracker.record_validation(key, validator: 'v3', approved: true)
+      expect(result).to eq(:approved)
+    end
+
+    it 'returns :rejected when ADVERSARIAL_REVIEW_K rejections are reached' do
+      tracker.record_validation(key, validator: 'v1', approved: false)
+      tracker.record_validation(key, validator: 'v2', approved: false)
+      result = tracker.record_validation(key, validator: 'v3', approved: false)
+      expect(result).to eq(:rejected)
+    end
+
+    it 'returns :pending when approvals and rejections are mixed below threshold' do
+      tracker.record_validation(key, validator: 'v1', approved: true)
+      result = tracker.record_validation(key, validator: 'v2', approved: false)
+      expect(result).to eq(:pending)
+    end
+
+    it 'returns nil for an unknown key' do
+      expect(tracker.record_validation('bad/key#0', validator: 'v1', approved: true)).to be_nil
+    end
+  end
+
+  describe '#attach_pr' do
+    it 'sets the pr_number on the issue' do
+      tracker.attach_pr(key, pr_number: 100)
+      expect(tracker.issues[key][:pr_number]).to eq(100)
+    end
+
+    it 'transitions state to :pr_open' do
+      tracker.attach_pr(key, pr_number: 100)
+      expect(tracker.issues[key][:state]).to eq(:pr_open)
+    end
+
+    it 'updates updated_at' do
+      before = Time.now.utc
+      tracker.attach_pr(key, pr_number: 100)
+      after = Time.now.utc
+      expect(tracker.issues[key][:updated_at]).to be_between(before, after)
+    end
+
+    it 'returns nil for an unknown key' do
+      expect(tracker.attach_pr('bad/key#0', pr_number: 1)).to be_nil
+    end
+  end
+
+  describe '#get' do
+    it 'returns the issue hash for a known key' do
+      result = tracker.get(key)
+      expect(result[:title]).to eq('Fix the bug')
+    end
+
+    it 'returns nil for an unknown key' do
+      expect(tracker.get('unknown/repo#999')).to be_nil
+    end
+  end
+
+  describe '#by_state' do
+    it 'returns all issues in the given state' do
+      tracker.track(repo: 'a/b', issue_number: 1, title: 'other')
+      results = tracker.by_state(:received)
+      expect(results.size).to eq(2)
+    end
+
+    it 'excludes issues not in the given state' do
+      tracker.transition(key, :found)
+      results = tracker.by_state(:received)
+      expect(results).to be_empty
+    end
+
+    it 'returns an empty array when no issues match' do
+      expect(tracker.by_state(:approved)).to eq([])
+    end
+
+    it 'reflects state changes after transitions' do
+      tracker.transition(key, :found)
+      expect(tracker.by_state(:found).size).to eq(1)
+    end
+  end
+
+  describe '#count' do
+    it 'returns 0 for an empty tracker' do
+      expect(described_class.new.count).to eq(0)
+    end
+
+    it 'returns the number of tracked issues' do
+      expect(tracker.count).to eq(1)
+    end
+
+    it 'increments when additional issues are tracked' do
+      tracker.track(repo: 'a/b', issue_number: 2, title: 'another')
+      expect(tracker.count).to eq(2)
+    end
+  end
+end

data/spec/legion/extensions/swarm_github/helpers/pipeline_spec.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::SwarmGithub::Helpers::Pipeline do
+  describe 'constants' do
+    it 'defines STATES as the eight pipeline states' do
+      expect(described_class::STATES).to eq(%i[received found fixing validating approved pr_open rejected stale])
+    end
+
+    it 'defines LABELS derived from STATES with swarm: prefix' do
+      expected = described_class::STATES.map { |s| :"swarm:#{s}" }
+      expect(described_class::LABELS).to eq(expected)
+    end
+
+    it 'defines PIPELINE_ROLES as the four agent roles' do
+      expect(described_class::PIPELINE_ROLES).to eq(%i[finder fixer validator pr_swarm])
+    end
+
+    it 'defines ADVERSARIAL_REVIEW_K as 3' do
+      expect(described_class::ADVERSARIAL_REVIEW_K).to eq(3)
+    end
+
+    it 'defines MAX_FIX_ATTEMPTS as 3' do
+      expect(described_class::MAX_FIX_ATTEMPTS).to eq(3)
+    end
+
+    it 'defines STALE_TIMEOUT as 86400' do
+      expect(described_class::STALE_TIMEOUT).to eq(86_400)
+    end
+  end
+
+  describe '.valid_state?' do
+    it 'returns true for all defined STATES' do
+      described_class::STATES.each do |state|
+        expect(described_class.valid_state?(state)).to be true
+      end
+    end
+
+    it 'returns true for :received' do
+      expect(described_class.valid_state?(:received)).to be true
+    end
+
+    it 'returns true for :stale' do
+      expect(described_class.valid_state?(:stale)).to be true
+    end
+
+    it 'returns true for :pr_open' do
+      expect(described_class.valid_state?(:pr_open)).to be true
+    end
+
+    it 'returns false for an unknown state' do
+      expect(described_class.valid_state?(:pending)).to be false
+    end
+
+    it 'returns false for nil' do
+      expect(described_class.valid_state?(nil)).to be false
+    end
+
+    it 'returns false for a string version of a valid state' do
+      expect(described_class.valid_state?('received')).to be false
+    end
+  end
+
+  describe '.label_for_state' do
+    it 'returns swarm:received for :received' do
+      expect(described_class.label_for_state(:received)).to eq('swarm:received')
+    end
+
+    it 'returns swarm:fixing for :fixing' do
+      expect(described_class.label_for_state(:fixing)).to eq('swarm:fixing')
+    end
+
+    it 'returns swarm:pr_open for :pr_open' do
+      expect(described_class.label_for_state(:pr_open)).to eq('swarm:pr_open')
+    end
+
+    it 'returns a string result for every defined state' do
+      described_class::STATES.each do |state|
+        expect(described_class.label_for_state(state)).to eq("swarm:#{state}")
+      end
+    end
+  end
+
+  describe '.next_state' do
+    it 'returns :found for :received' do
+      expect(described_class.next_state(:received)).to eq(:found)
+    end
+
+    it 'returns :fixing for :found' do
+      expect(described_class.next_state(:found)).to eq(:fixing)
+    end
+
+    it 'returns :validating for :fixing' do
+      expect(described_class.next_state(:fixing)).to eq(:validating)
+    end
+
+    it 'returns :approved for :validating' do
+      expect(described_class.next_state(:validating)).to eq(:approved)
+    end
+
+    it 'returns :pr_open for :approved' do
+      expect(described_class.next_state(:approved)).to eq(:pr_open)
+    end
+
+    it 'returns nil for terminal states with no next state' do
+      expect(described_class.next_state(:pr_open)).to be_nil
+      expect(described_class.next_state(:rejected)).to be_nil
+      expect(described_class.next_state(:stale)).to be_nil
+    end
+
+    it 'returns nil for an unknown state' do
+      expect(described_class.next_state(:unknown)).to be_nil
+    end
+  end
+end

data/spec/legion/extensions/swarm_github/runners/github_swarm_spec.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/swarm_github/client'
+
+RSpec.describe Legion::Extensions::SwarmGithub::Runners::GithubSwarm do
+  let(:client) { Legion::Extensions::SwarmGithub::Client.new }
+
+  describe '#ingest_issue' do
+    it 'tracks a GitHub issue' do
+      result = client.ingest_issue(repo: 'org/repo', issue_number: 42, title: 'Bug fix needed')
+      expect(result[:tracked]).to be true
+      expect(result[:state]).to eq(:received)
+    end
+  end
+
+  describe '#claim_issue' do
+    it 'transitions issue to found state' do
+      client.ingest_issue(repo: 'org/repo', issue_number: 1, title: 'test')
+      result = client.claim_issue(key: 'org/repo#1')
+      expect(result[:claimed]).to be true
+    end
+  end
+
+  describe '#start_fix' do
+    it 'starts a fix attempt' do
+      client.ingest_issue(repo: 'org/repo', issue_number: 1, title: 'test')
+      client.claim_issue(key: 'org/repo#1')
+      result = client.start_fix(key: 'org/repo#1')
+      expect(result[:fixing]).to be true
+      expect(result[:attempt]).to eq(1)
+    end
+
+    it 'rejects after max attempts' do
+      client.ingest_issue(repo: 'org/repo', issue_number: 1, title: 'test')
+      4.times { client.start_fix(key: 'org/repo#1') }
+      result = client.start_fix(key: 'org/repo#1')
+      expect(result[:error]).to eq(:max_attempts_exceeded)
+    end
+  end
+
+  describe '#submit_validation' do
+    it 'records validation' do
+      client.ingest_issue(repo: 'org/repo', issue_number: 1, title: 'test')
+      result = client.submit_validation(key: 'org/repo#1', validator: 'v1', approved: true)
+      expect(result[:recorded]).to be true
+    end
+
+    it 'reaches consensus with k=3 approvals' do
+      client.ingest_issue(repo: 'org/repo', issue_number: 1, title: 'test')
+      client.submit_validation(key: 'org/repo#1', validator: 'v1', approved: true)
+      client.submit_validation(key: 'org/repo#1', validator: 'v2', approved: true)
+      result = client.submit_validation(key: 'org/repo#1', validator: 'v3', approved: true)
+      expect(result[:consensus]).to eq(:approved)
+    end
+  end
+
+  describe '#attach_pr' do
+    it 'attaches a PR to the issue' do
+      client.ingest_issue(repo: 'org/repo', issue_number: 1, title: 'test')
+      result = client.attach_pr(key: 'org/repo#1', pr_number: 100)
+      expect(result[:attached]).to be true
+    end
+  end
+
+  describe '#pipeline_status' do
+    it 'returns counts by state' do
+      client.ingest_issue(repo: 'org/repo', issue_number: 1, title: 'test1')
+      client.ingest_issue(repo: 'org/repo', issue_number: 2, title: 'test2')
+      status = client.pipeline_status
+      expect(status[:total]).to eq(2)
+      expect(status[:states][:received]).to eq(2)
+    end
+  end
+
+  describe '#mark_stale_issues' do
+    it 'returns zero marked when tracker is empty' do
+      result = client.mark_stale_issues
+      expect(result[:marked_stale]).to eq(0)
+      expect(result[:stale_keys]).to eq([])
+    end
+
+    it 'does not mark a freshly ingested issue as stale' do
+      client.ingest_issue(repo: 'org/repo', issue_number: 1, title: 'fresh')
+      result = client.mark_stale_issues
+      expect(result[:marked_stale]).to eq(0)
+    end
+
+    it 'marks a non-terminal issue as stale when past timeout' do
+      client.ingest_issue(repo: 'org/repo', issue_number: 1, title: 'old')
+      tracker = client.send(:issue_tracker)
+      tracker.issues['org/repo#1'][:updated_at] = Time.now.utc - 90_000
+      result = client.mark_stale_issues
+      expect(result[:marked_stale]).to eq(1)
+      expect(result[:stale_keys]).to include('org/repo#1')
+    end
+
+    it 'does not mark a terminal issue as stale' do
+      client.ingest_issue(repo: 'org/repo', issue_number: 1, title: 'done')
+      tracker = client.send(:issue_tracker)
+      tracker.issues['org/repo#1'][:state] = :approved
+      tracker.issues['org/repo#1'][:updated_at] = Time.now.utc - 90_000
+      result = client.mark_stale_issues
+      expect(result[:marked_stale]).to eq(0)
+    end
+
+    it 'reports correct checked count' do
+      client.ingest_issue(repo: 'org/repo', issue_number: 1, title: 't1')
+      client.ingest_issue(repo: 'org/repo', issue_number: 2, title: 't2')
+      result = client.mark_stale_issues
+      expect(result[:checked]).to eq(2)
+    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/swarm_github'
+
+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-swarm-github
+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: GitHub-specific swarm pipeline (finder/fixer/validator) for brain-modeled
+  agentic AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-swarm-github.gemspec
+- lib/legion/extensions/swarm_github.rb
+- lib/legion/extensions/swarm_github/actors/stale_issues.rb
+- lib/legion/extensions/swarm_github/client.rb
+- lib/legion/extensions/swarm_github/helpers/issue_tracker.rb
+- lib/legion/extensions/swarm_github/helpers/pipeline.rb
+- lib/legion/extensions/swarm_github/runners/github_swarm.rb
+- lib/legion/extensions/swarm_github/version.rb
+- spec/legion/extensions/swarm_github/actors/stale_issues_spec.rb
+- spec/legion/extensions/swarm_github/client_spec.rb
+- spec/legion/extensions/swarm_github/helpers/issue_tracker_spec.rb
+- spec/legion/extensions/swarm_github/helpers/pipeline_spec.rb
+- spec/legion/extensions/swarm_github/runners/github_swarm_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-swarm-github
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-swarm-github
+  source_code_uri: https://github.com/LegionIO/lex-swarm-github
+  documentation_uri: https://github.com/LegionIO/lex-swarm-github
+  changelog_uri: https://github.com/LegionIO/lex-swarm-github
+  bug_tracker_uri: https://github.com/LegionIO/lex-swarm-github/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 Swarm GitHub
+test_files: []