lex-agentic-learning 0.1.0

data/spec/legion/extensions/agentic/learning/chrysalis/helpers/metamorphosis_engine_spec.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::MetamorphosisEngine do
+  subject(:engine) { described_class.new }
+
+  let(:chrysalis_id) { engine.create_chrysalis(chrysalis_type: :silk, content: 'raw idea')[:chrysalis][:id] }
+  let(:cocoon_id)    { engine.create_cocoon(environment: 'garden')[:cocoon][:id] }
+
+  describe '#create_chrysalis' do
+    it 'returns success: true' do
+      result = engine.create_chrysalis(chrysalis_type: :silk, content: 'test')
+      expect(result[:success]).to be true
+    end
+
+    it 'returns a chrysalis hash' do
+      result = engine.create_chrysalis(chrysalis_type: :bark, content: 'test')
+      expect(result[:chrysalis]).to be_a(Hash)
+      expect(result[:chrysalis][:chrysalis_type]).to eq(:bark)
+    end
+
+    it 'returns success: false when at capacity' do
+      stub_const('Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Constants::MAX_CHRYSALISES', 1)
+      engine.create_chrysalis(chrysalis_type: :silk, content: 'first')
+      result = engine.create_chrysalis(chrysalis_type: :paper, content: 'second')
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:capacity_exceeded)
+    end
+  end
+
+  describe '#create_cocoon' do
+    it 'returns success: true' do
+      result = engine.create_cocoon(environment: 'meadow')
+      expect(result[:success]).to be true
+    end
+
+    it 'includes cocoon hash with environment' do
+      result = engine.create_cocoon(environment: 'meadow')
+      expect(result[:cocoon][:environment]).to eq('meadow')
+    end
+  end
+
+  describe '#spin' do
+    it 'transitions the chrysalis to :spinning' do
+      result = engine.spin(chrysalis_id: chrysalis_id)
+      expect(result[:success]).to be true
+      expect(result[:stage]).to eq(:spinning)
+    end
+
+    it 'returns failure for unknown chrysalis_id' do
+      result = engine.spin(chrysalis_id: 'bad-id')
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:not_found)
+    end
+
+    it 'returns failure when already spun' do
+      engine.spin(chrysalis_id: chrysalis_id)
+      result = engine.spin(chrysalis_id: chrysalis_id)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#enclose' do
+    it 'spins, cocoons, and shelters the chrysalis' do
+      result = engine.enclose(chrysalis_id: chrysalis_id, cocoon_id: cocoon_id)
+      expect(result[:success]).to be true
+      expect(result[:stage]).to eq(:cocooned)
+    end
+
+    it 'returns failure for unknown chrysalis' do
+      result = engine.enclose(chrysalis_id: 'bad-id', cocoon_id: cocoon_id)
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:chrysalis_not_found)
+    end
+
+    it 'returns failure for unknown cocoon' do
+      result = engine.enclose(chrysalis_id: chrysalis_id, cocoon_id: 'bad-cocoon')
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:cocoon_not_found)
+    end
+  end
+
+  describe '#incubate' do
+    before { engine.enclose(chrysalis_id: chrysalis_id, cocoon_id: cocoon_id) }
+
+    it 'increases transformation_progress' do
+      result = engine.incubate(chrysalis_id: chrysalis_id)
+      expect(result[:success]).to be true
+      expect(result[:progress]).to be > 0.0
+    end
+
+    it 'returns failure for unknown chrysalis' do
+      result = engine.incubate(chrysalis_id: 'bad-id')
+      expect(result[:success]).to be false
+    end
+
+    it 'returns failure for an already-butterfly chrysalis' do
+      12.times { engine.incubate(chrysalis_id: chrysalis_id) }
+      engine.force_emerge(chrysalis_id: chrysalis_id)
+      result = engine.incubate(chrysalis_id: chrysalis_id)
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:already_butterfly)
+    end
+
+    it 'applies cocoon growth_modifier for ideal conditions' do
+      ideal_cocoon = engine.create_cocoon(environment: 'ideal')[:cocoon][:id]
+      engine.enclose(chrysalis_id: engine.create_chrysalis(chrysalis_type: :leaf, content: 'c2')[:chrysalis][:id],
+                     cocoon_id:    ideal_cocoon)
+      cid2 = engine.instance_variable_get(:@chrysalises).values.last.id
+      result = engine.incubate(chrysalis_id: cid2)
+      expect(result[:progress]).to be_within(0.01).of(0.18)
+    end
+  end
+
+  describe '#force_emerge' do
+    it 'forces butterfly regardless of progress' do
+      result = engine.force_emerge(chrysalis_id: chrysalis_id)
+      expect(result[:success]).to be true
+      expect(result[:stage]).to eq(:butterfly)
+    end
+
+    it 'returns failure for unknown chrysalis' do
+      result = engine.force_emerge(chrysalis_id: 'bad-id')
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#natural_emerge' do
+    context 'when not ready' do
+      it 'returns failure with :not_ready reason' do
+        result = engine.natural_emerge(chrysalis_id: chrysalis_id)
+        expect(result[:success]).to be false
+        expect(result[:reason]).to eq(:not_ready)
+      end
+    end
+
+    context 'when ready (progress >= EMERGENCE_THRESHOLD)' do
+      before do
+        engine.enclose(chrysalis_id: chrysalis_id, cocoon_id: cocoon_id)
+        12.times { engine.incubate(chrysalis_id: chrysalis_id) }
+      end
+
+      it 'successfully emerges when progress is sufficient' do
+        result = engine.natural_emerge(chrysalis_id: chrysalis_id)
+        expect(result[:success]).to be true
+        expect(result[:stage]).to eq(:butterfly)
+      end
+    end
+
+    it 'returns failure for unknown chrysalis' do
+      result = engine.natural_emerge(chrysalis_id: 'bad-id')
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:not_found)
+    end
+  end
+
+  describe '#disturb_cocoon' do
+    before do
+      engine.enclose(chrysalis_id: chrysalis_id, cocoon_id: cocoon_id)
+    end
+
+    it 'reduces protection of sheltered chrysalises' do
+      engine.disturb_cocoon(cocoon_id: cocoon_id, force: 0.1)
+      c = engine.instance_variable_get(:@chrysalises)[chrysalis_id]
+      expect(c.protection).to be < 0.8
+    end
+
+    it 'returns disturbed array with chrysalis info' do
+      result = engine.disturb_cocoon(cocoon_id: cocoon_id, force: 0.1)
+      expect(result[:disturbed]).not_to be_empty
+      expect(result[:disturbed].first[:chrysalis_id]).to eq(chrysalis_id)
+    end
+
+    it 'returns failure for unknown cocoon' do
+      result = engine.disturb_cocoon(cocoon_id: 'bad-id', force: 0.1)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#incubate_all!' do
+    it 'incubates all cocooned and transforming chrysalises' do
+      cid2 = engine.create_chrysalis(chrysalis_type: :bark, content: 'idea 2')[:chrysalis][:id]
+      cid3 = engine.create_chrysalis(chrysalis_type: :leaf, content: 'idea 3')[:chrysalis][:id]
+      coc2 = engine.create_cocoon(environment: 'forest')[:cocoon][:id]
+      engine.enclose(chrysalis_id: cid2, cocoon_id: coc2)
+      engine.enclose(chrysalis_id: cid3, cocoon_id: coc2)
+      result = engine.incubate_all!
+      expect(result[:success]).to be true
+      expect(result[:incubated]).to eq(2)
+    end
+
+    it 'returns empty results when no eligible chrysalises' do
+      result = engine.incubate_all!
+      expect(result[:incubated]).to eq(0)
+    end
+  end
+
+  describe '#butterflies' do
+    it 'returns empty array initially' do
+      expect(engine.butterflies).to eq([])
+    end
+
+    it 'returns emerged butterflies' do
+      engine.force_emerge(chrysalis_id: chrysalis_id)
+      expect(engine.butterflies.size).to eq(1)
+    end
+  end
+
+  describe '#metamorphosis_report' do
+    it 'returns a hash with report keys' do
+      result = engine.metamorphosis_report
+      expect(result).to include(
+        :total_chrysalises,
+        :total_cocoons,
+        :butterflies_count,
+        :premature_count,
+        :avg_beauty,
+        :avg_progress,
+        :cocooned_count,
+        :transforming_count
+      )
+    end
+
+    it 'reflects created chrysalises and cocoons' do
+      engine.create_chrysalis(chrysalis_type: :silk, content: 'counted')
+      engine.create_cocoon(environment: 'a')
+      engine.create_cocoon(environment: 'b')
+      result = engine.metamorphosis_report
+      expect(result[:total_chrysalises]).to eq(1)
+      expect(result[:total_cocoons]).to eq(2)
+    end
+
+    it 'counts butterflies correctly' do
+      engine.force_emerge(chrysalis_id: chrysalis_id)
+      report = engine.metamorphosis_report
+      expect(report[:butterflies_count]).to eq(1)
+    end
+
+    it 'returns avg_beauty 0.0 when no butterflies' do
+      expect(engine.metamorphosis_report[:avg_beauty]).to eq(0.0)
+    end
+
+    it 'returns avg_progress 0.0 when no chrysalises' do
+      empty_engine = described_class.new
+      expect(empty_engine.metamorphosis_report[:avg_progress]).to eq(0.0)
+    end
+  end
+end

data/spec/legion/extensions/agentic/learning/chrysalis/helpers/transformation_phase_spec.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+# Tests focused on Cocoon environment modifiers and their effect on transformation
+RSpec.describe 'Cocoon environment effects' do
+  let(:engine) { Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::MetamorphosisEngine.new }
+
+  describe 'ideal cocoon' do
+    let(:ideal_cocoon) do
+      Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Cocoon.new(
+        environment: 'greenhouse',
+        temperature: 0.55,
+        humidity:    0.55
+      )
+    end
+
+    it 'reports ideal? true' do
+      expect(ideal_cocoon.ideal?).to be true
+    end
+
+    it 'has growth_modifier of 0.1' do
+      expect(ideal_cocoon.growth_modifier).to eq(0.1)
+    end
+
+    it 'accelerates transformation compared to bare incubation' do
+      base_rate = Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Constants::TRANSFORMATION_RATE
+      rate_with_cocoon = base_rate + ideal_cocoon.growth_modifier
+      expect(rate_with_cocoon).to be > base_rate
+    end
+  end
+
+  describe 'hostile cocoon' do
+    let(:hostile_cocoon) do
+      Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Cocoon.new(
+        environment: 'furnace',
+        temperature: 0.95,
+        humidity:    0.5
+      )
+    end
+
+    it 'reports hostile? true' do
+      expect(hostile_cocoon.hostile?).to be true
+    end
+
+    it 'has negative growth_modifier' do
+      expect(hostile_cocoon.growth_modifier).to be < 0
+    end
+
+    it 'slows transformation below base rate' do
+      base_rate = Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Constants::TRANSFORMATION_RATE
+      rate_with_cocoon = base_rate + hostile_cocoon.growth_modifier
+      expect(rate_with_cocoon).to be < base_rate
+    end
+  end
+
+  describe 'neutral cocoon' do
+    let(:neutral_cocoon) do
+      Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Cocoon.new(
+        environment: 'plain',
+        temperature: 0.2,
+        humidity:    0.5
+      )
+    end
+
+    it 'has growth_modifier of 0.0' do
+      expect(neutral_cocoon.growth_modifier).to eq(0.0)
+    end
+
+    it 'does not accelerate or slow transformation' do
+      base_rate = Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Constants::TRANSFORMATION_RATE
+      expect(base_rate + neutral_cocoon.growth_modifier).to eq(base_rate)
+    end
+  end
+
+  describe 'temperature and humidity adjustments' do
+    let(:cocoon) { Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Cocoon.new(environment: 'test') }
+
+    it 'moisten and dry are inverse operations (roughly)' do
+      original = cocoon.humidity
+      cocoon.moisten!
+      cocoon.dry!
+      expect(cocoon.humidity).to be_within(0.001).of(original)
+    end
+
+    it 'warm and cool are inverse operations (roughly)' do
+      original = cocoon.temperature
+      cocoon.warm!
+      cocoon.cool!
+      expect(cocoon.temperature).to be_within(0.001).of(original)
+    end
+
+    it 'sheltering and exposing a chrysalis affects chrysalis_ids' do
+      cocoon.shelter('c-1')
+      expect(cocoon.chrysalis_ids).to include('c-1')
+      cocoon.expose('c-1')
+      expect(cocoon.chrysalis_ids).not_to include('c-1')
+    end
+  end
+end

data/spec/legion/extensions/agentic/learning/chrysalis/runners/cognitive_chrysalis_spec.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Learning::Chrysalis::Runners::CognitiveChrysalis do
+  subject(:runner) { described_class }
+
+  let(:engine) { Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::MetamorphosisEngine.new }
+
+  describe '.create_chrysalis' do
+    it 'returns success: true with a valid type' do
+      result = runner.create_chrysalis(chrysalis_type: :silk, content: 'thought', engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns success: false for an invalid type' do
+      result = runner.create_chrysalis(chrysalis_type: :invalid, content: 'x', engine: engine)
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:invalid_type)
+    end
+
+    it 'returns the valid_types list on invalid type' do
+      result = runner.create_chrysalis(chrysalis_type: :invalid, content: 'x', engine: engine)
+      expect(result[:valid_types]).to eq(Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Constants::CHRYSALIS_TYPES)
+    end
+
+    it 'defaults chrysalis_type to :silk when not provided' do
+      result = runner.create_chrysalis(content: 'default', engine: engine)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '.create_cocoon' do
+    it 'returns success: true' do
+      result = runner.create_cocoon(environment: 'meadow', engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'defaults environment to "default"' do
+      result = runner.create_cocoon(engine: engine)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '.spin' do
+    let(:chrysalis_id) { runner.create_chrysalis(chrysalis_type: :silk, content: 'c', engine: engine)[:chrysalis][:id] }
+
+    it 'returns success: true for a valid chrysalis' do
+      result = runner.spin(chrysalis_id: chrysalis_id, engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns failure for missing chrysalis_id' do
+      result = runner.spin(chrysalis_id: nil, engine: engine)
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:missing_chrysalis_id)
+    end
+
+    it 'returns failure for unknown chrysalis_id' do
+      result = runner.spin(chrysalis_id: 'ghost', engine: engine)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '.enclose' do
+    let(:chrysalis_id) { runner.create_chrysalis(chrysalis_type: :leaf, content: 'c', engine: engine)[:chrysalis][:id] }
+    let(:cocoon_id)    { runner.create_cocoon(environment: 'wood', engine: engine)[:cocoon][:id] }
+
+    it 'encloses a chrysalis in a cocoon' do
+      result = runner.enclose(chrysalis_id: chrysalis_id, cocoon_id: cocoon_id, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:stage]).to eq(:cocooned)
+    end
+
+    it 'returns failure for missing chrysalis_id' do
+      result = runner.enclose(chrysalis_id: nil, cocoon_id: cocoon_id, engine: engine)
+      expect(result[:success]).to be false
+    end
+
+    it 'returns failure for missing cocoon_id' do
+      result = runner.enclose(chrysalis_id: chrysalis_id, cocoon_id: nil, engine: engine)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '.incubate' do
+    let(:chrysalis_id) do
+      runner.create_chrysalis(chrysalis_type: :paper, content: 'c', engine: engine)[:chrysalis][:id]
+    end
+    let(:cocoon_id) { runner.create_cocoon(environment: 'nest', engine: engine)[:cocoon][:id] }
+
+    before { runner.enclose(chrysalis_id: chrysalis_id, cocoon_id: cocoon_id, engine: engine) }
+
+    it 'increases progress' do
+      result = runner.incubate(chrysalis_id: chrysalis_id, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:progress]).to be > 0.0
+    end
+
+    it 'returns failure for missing chrysalis_id' do
+      result = runner.incubate(chrysalis_id: nil, engine: engine)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '.emerge' do
+    let(:chrysalis_id) { runner.create_chrysalis(chrysalis_type: :bark, content: 'c', engine: engine)[:chrysalis][:id] }
+    let(:cocoon_id)    { runner.create_cocoon(environment: 'oak', engine: engine)[:cocoon][:id] }
+
+    before do
+      runner.enclose(chrysalis_id: chrysalis_id, cocoon_id: cocoon_id, engine: engine)
+      12.times { runner.incubate(chrysalis_id: chrysalis_id, engine: engine) }
+    end
+
+    it 'emerges naturally when ready' do
+      result = runner.emerge(chrysalis_id: chrysalis_id, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:stage]).to eq(:butterfly)
+    end
+
+    it 'force-emerges when force: true' do
+      cid2 = runner.create_chrysalis(chrysalis_type: :silk, content: 'fresh', engine: engine)[:chrysalis][:id]
+      result = runner.emerge(chrysalis_id: cid2, force: true, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:stage]).to eq(:butterfly)
+    end
+
+    it 'returns failure for missing chrysalis_id' do
+      result = runner.emerge(chrysalis_id: nil, engine: engine)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '.disturb' do
+    let(:chrysalis_id) { runner.create_chrysalis(chrysalis_type: :silk, content: 'c', engine: engine)[:chrysalis][:id] }
+    let(:cocoon_id)    { runner.create_cocoon(environment: 'pond', engine: engine)[:cocoon][:id] }
+
+    before { runner.enclose(chrysalis_id: chrysalis_id, cocoon_id: cocoon_id, engine: engine) }
+
+    it 'disturbs the cocoon' do
+      result = runner.disturb(cocoon_id: cocoon_id, force: 0.1, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:disturbed]).not_to be_empty
+    end
+
+    it 'returns failure for missing cocoon_id' do
+      result = runner.disturb(cocoon_id: nil, engine: engine)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '.list_chrysalises' do
+    it 'returns success: true' do
+      result = runner.list_chrysalises(engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns empty array when no chrysalises' do
+      result = runner.list_chrysalises(engine: engine)
+      expect(result[:chrysalises]).to eq([])
+    end
+
+    it 'lists all created chrysalises' do
+      runner.create_chrysalis(chrysalis_type: :silk, content: 'one', engine: engine)
+      runner.create_chrysalis(chrysalis_type: :paper, content: 'two', engine: engine)
+      result = runner.list_chrysalises(engine: engine)
+      expect(result[:count]).to eq(2)
+    end
+  end
+
+  describe '.metamorphosis_status' do
+    it 'returns success: true' do
+      result = runner.metamorphosis_status(engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'includes report keys' do
+      result = runner.metamorphosis_status(engine: engine)
+      expect(result).to include(:total_chrysalises, :butterflies_count, :avg_beauty)
+    end
+  end
+end

data/spec/legion/extensions/agentic/learning/chrysalis/runners/reporting_spec.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# Tests focused on status reporting and list operations
+RSpec.describe 'Metamorphosis status reporting' do
+  let(:engine) { Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::MetamorphosisEngine.new }
+  let(:runner) { Legion::Extensions::Agentic::Learning::Chrysalis::Runners::CognitiveChrysalis }
+
+  describe 'list_chrysalises' do
+    it 'returns empty list for a fresh engine' do
+      result = runner.list_chrysalises(engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:chrysalises]).to eq([])
+      expect(result[:count]).to eq(0)
+    end
+
+    it 'lists all created chrysalises with their hashes' do
+      runner.create_chrysalis(chrysalis_type: :silk, content: 'alpha', engine: engine)
+      runner.create_chrysalis(chrysalis_type: :paper, content: 'beta', engine: engine)
+      result = runner.list_chrysalises(engine: engine)
+      expect(result[:count]).to eq(2)
+      types = result[:chrysalises].map { |c| c[:chrysalis_type] }
+      expect(types).to contain_exactly(:silk, :paper)
+    end
+
+    it 'includes chrysalis details in each entry' do
+      runner.create_chrysalis(chrysalis_type: :bark, content: 'idea', engine: engine)
+      c = runner.list_chrysalises(engine: engine)[:chrysalises].first
+      expect(c).to have_key(:id)
+      expect(c).to have_key(:stage)
+      expect(c).to have_key(:transformation_progress)
+      expect(c).to have_key(:beauty)
+    end
+  end
+
+  describe 'metamorphosis_status' do
+    it 'returns success: true' do
+      expect(runner.metamorphosis_status(engine: engine)[:success]).to be true
+    end
+
+    it 'shows zeroed counts for empty engine' do
+      status = runner.metamorphosis_status(engine: engine)
+      expect(status[:total_chrysalises]).to eq(0)
+      expect(status[:butterflies_count]).to eq(0)
+      expect(status[:premature_count]).to eq(0)
+    end
+
+    it 'shows correct butterflies_count after natural emergence' do
+      cid = runner.create_chrysalis(chrysalis_type: :leaf, content: 'c', engine: engine)[:chrysalis][:id]
+      coc = runner.create_cocoon(environment: 'park', engine: engine)[:cocoon][:id]
+      runner.enclose(chrysalis_id: cid, cocoon_id: coc, engine: engine)
+      12.times { runner.incubate(chrysalis_id: cid, engine: engine) }
+      runner.emerge(chrysalis_id: cid, engine: engine)
+      expect(runner.metamorphosis_status(engine: engine)[:butterflies_count]).to eq(1)
+    end
+
+    it 'shows correct premature_count after forced emergence' do
+      cid = runner.create_chrysalis(chrysalis_type: :silk, content: 'forced', engine: engine)[:chrysalis][:id]
+      runner.emerge(chrysalis_id: cid, force: true, engine: engine)
+      expect(runner.metamorphosis_status(engine: engine)[:premature_count]).to eq(1)
+    end
+
+    it 'includes total_cocoons' do
+      runner.create_cocoon(environment: 'a', engine: engine)
+      runner.create_cocoon(environment: 'b', engine: engine)
+      expect(runner.metamorphosis_status(engine: engine)[:total_cocoons]).to eq(2)
+    end
+
+    it 'includes avg_beauty as 0.0 when no butterflies' do
+      runner.create_chrysalis(chrysalis_type: :bark, content: 'c', engine: engine)
+      expect(runner.metamorphosis_status(engine: engine)[:avg_beauty]).to eq(0.0)
+    end
+
+    it 'includes avg_progress > 0.0 after incubation' do
+      cid = runner.create_chrysalis(chrysalis_type: :paper, content: 'p', engine: engine)[:chrysalis][:id]
+      coc = runner.create_cocoon(environment: 'env', engine: engine)[:cocoon][:id]
+      runner.enclose(chrysalis_id: cid, cocoon_id: coc, engine: engine)
+      runner.incubate(chrysalis_id: cid, engine: engine)
+      expect(runner.metamorphosis_status(engine: engine)[:avg_progress]).to be > 0.0
+    end
+  end
+end

data/spec/legion/extensions/agentic/learning/chrysalis/runners/transformation_spec.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# Integration tests for the full metamorphosis pipeline
+RSpec.describe 'Full metamorphosis pipeline integration' do
+  let(:engine) { Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::MetamorphosisEngine.new }
+  let(:runner) { Legion::Extensions::Agentic::Learning::Chrysalis::Runners::CognitiveChrysalis }
+
+  it 'creates and fully transforms a chrysalis through the natural emergence path' do
+    cid = runner.create_chrysalis(chrysalis_type: :silk, content: 'deep insight', engine: engine)[:chrysalis][:id]
+    coc = runner.create_cocoon(environment: 'sacred_grove', engine: engine)[:cocoon][:id]
+    runner.enclose(chrysalis_id: cid, cocoon_id: coc, engine: engine)
+
+    # Incubate until ready (needs ~12 steps with base rate 0.08 to exceed 0.9)
+    result = nil
+    12.times { result = runner.incubate(chrysalis_id: cid, engine: engine) }
+    expect(result[:progress]).to be >= Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Constants::EMERGENCE_THRESHOLD
+
+    result = runner.emerge(chrysalis_id: cid, engine: engine)
+    expect(result[:success]).to be true
+    expect(result[:stage]).to eq(:butterfly)
+    expect(result[:premature]).to be false
+  end
+
+  it 'reports correct stats after full transformation' do
+    cid = runner.create_chrysalis(chrysalis_type: :leaf, content: 'wisdom', engine: engine)[:chrysalis][:id]
+    coc = runner.create_cocoon(environment: 'canopy', engine: engine)[:cocoon][:id]
+    runner.enclose(chrysalis_id: cid, cocoon_id: coc, engine: engine)
+    12.times { runner.incubate(chrysalis_id: cid, engine: engine) }
+    runner.emerge(chrysalis_id: cid, engine: engine)
+
+    status = runner.metamorphosis_status(engine: engine)
+    expect(status[:butterflies_count]).to eq(1)
+    expect(status[:premature_count]).to eq(0)
+    expect(status[:avg_beauty]).to eq(1.0)
+  end
+
+  it 'handles multiple concurrent chrysalises in the same engine' do
+    ids = (1..3).map do |i|
+      cid = runner.create_chrysalis(chrysalis_type: :bark, content: "idea #{i}", engine: engine)[:chrysalis][:id]
+      coc = runner.create_cocoon(environment: "env_#{i}", engine: engine)[:cocoon][:id]
+      runner.enclose(chrysalis_id: cid, cocoon_id: coc, engine: engine)
+      cid
+    end
+
+    12.times { runner.incubate_all(engine: engine) }
+    ids.each { |cid| runner.emerge(chrysalis_id: cid, engine: engine) }
+
+    status = runner.metamorphosis_status(engine: engine)
+    expect(status[:butterflies_count]).to eq(3)
+  end
+
+  it 'incubate_all applies modifiers from individual cocoons' do
+    cid1 = runner.create_chrysalis(chrysalis_type: :silk, content: 'c1', engine: engine)[:chrysalis][:id]
+    coc1 = runner.create_cocoon(environment: 'ideal', temperature: 0.55, humidity: 0.55, engine: engine)[:cocoon][:id]
+    runner.enclose(chrysalis_id: cid1, cocoon_id: coc1, engine: engine)
+
+    result = runner.incubate_all(engine: engine)
+    expect(result[:incubated]).to eq(1)
+    c = engine.instance_variable_get(:@chrysalises)[cid1]
+    expect(c.transformation_progress).to be > Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Constants::TRANSFORMATION_RATE
+  end
+
+  it 'disturbing a cocoon mid-transformation can force premature emergence' do
+    cid = runner.create_chrysalis(chrysalis_type: :underground, content: 'fragile', engine: engine)[:chrysalis][:id]
+    coc = runner.create_cocoon(environment: 'unstable', engine: engine)[:cocoon][:id]
+    runner.enclose(chrysalis_id: cid, cocoon_id: coc, engine: engine)
+    3.times { runner.incubate(chrysalis_id: cid, engine: engine) }
+    runner.disturb(cocoon_id: coc, force: 1.0, engine: engine)
+
+    c = engine.instance_variable_get(:@chrysalises)[cid]
+    expect(c.butterfly?).to be true
+    expect(c.premature?).to be true
+  end
+end