lex-cognitive-chrysalis 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c7aed07ab9c483e7513ebc0122e1c571c1d0edc409a568cd929bc3e5d75d6b79
+  data.tar.gz: c74edc3c6961ae25718351bebacdd8ed30a5a8964eff553428108292cbc3a0d4
+SHA512:
+  metadata.gz: bc485de3f19aef24d91a1ab266e22cc07b22744f58f47f83f6c6ecae8dba9cc05a8fb2068fa04c9f86982c5fb7d32897e77fb365b9c3e30a09b31777d3758c44
+  data.tar.gz: ec30ffc37864ca2282108040efbe4eb91113e6455b95584480219f60810894da6f7cc7e064e762693038c8322e7946dfb45c62710cc17065d2da4b8371168167

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+Gemfile.lock

data/.rspec

@@ -0,0 +1,4 @@
+--require spec_helper
+--format documentation
+--color
+--order random

data/.rubocop.yml

@@ -0,0 +1,32 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.4
+  SuggestExtensions: false
+Layout/LineLength:
+  Max: 160
+Style/Documentation:
+  Enabled: false
+Naming/PredicateMethod:
+  Enabled: false
+Naming/PredicatePrefix:
+  Enabled: false
+Metrics/ClassLength:
+  Max: 150
+Metrics/MethodLength:
+  Max: 25
+Metrics/AbcSize:
+  Max: 25
+Metrics/ParameterLists:
+  Max: 8
+  MaxOptionalParameters: 8
+Layout/HashAlignment:
+  EnforcedColonStyle: table
+  EnforcedHashRocketStyle: table
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+Style/FrozenStringLiteralComment:
+  Enabled: true
+Style/OneClassPerFile:
+  Exclude:
+    - 'spec/spec_helper.rb'

data/CLAUDE.md

@@ -0,0 +1,81 @@
+# lex-cognitive-chrysalis
+
+**Level 3 Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+- **Grandparent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+Metamorphic identity transformation for LegionIO agents. Models structured dissolution and reformation cycles: ideas or identity facets enter a chrysalis, transform through protected incubation, and emerge as something qualitatively different. Premature emergence (forced before transformation is complete) reduces beauty and can produce damaged outputs.
+
+## Gem Info
+
+- **Gem name**: `lex-cognitive-chrysalis`
+- **Version**: `0.1.0`
+- **Module**: `Legion::Extensions::CognitiveChrysalis`
+- **Ruby**: `>= 3.4`
+- **License**: MIT
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_chrysalis/
+  cognitive_chrysalis.rb
+  version.rb
+  client.rb
+  helpers/
+    constants.rb
+    chrysalis.rb
+    cocoon.rb
+    metamorphosis_engine.rb
+  runners/
+    cognitive_chrysalis.rb
+```
+
+## Key Constants
+
+From `helpers/constants.rb`:
+
+- `LIFE_STAGES` — `%i[larva spinning cocooned transforming emerging butterfly]`
+- `CHRYSALIS_TYPES` — `%i[silk paper bark leaf underground]`
+- `MAX_CHRYSALISES` = `200`, `MAX_BUTTERFLIES` = `500`
+- `TRANSFORMATION_RATE` = `0.08`, `PROTECTION_DECAY` = `0.03`
+- `EMERGENCE_THRESHOLD` = `0.9` (transformation_progress must reach this for natural emergence)
+- `PREMATURE_PENALTY` = `0.4` (beauty penalty for forced emergence before threshold)
+- `STAGE_LABELS` — progress-to-stage mapping: `0.0-0.20` = `:larva`, `0.20-0.40` = `:spinning`, up to `0.90-1.0` = `:butterfly`
+- `BEAUTY_LABELS` — `0.85+` = `:magnificent`, `0.65` = `:beautiful`, `0.40` = `:striking`, `0.20` = `:plain`, below = `:dull`
+
+## Runners
+
+All methods in `Runners::CognitiveChrysalis` (`extend self`):
+
+- `create_chrysalis(chrysalis_type: :silk, content: '')` — creates a new chrysalis in `:larva` stage
+- `create_cocoon(environment: 'default', temperature: 0.5, humidity: 0.5)` — creates a protective cocoon environment
+- `spin(chrysalis_id:)` — advances chrysalis from `:larva` to `:spinning`; must be in `:larva` state
+- `enclose(chrysalis_id:, cocoon_id:)` — places a chrysalis inside a cocoon
+- `incubate(chrysalis_id:)` — advances transformation progress by `TRANSFORMATION_RATE`
+- `incubate_all` — incubates all eligible (non-butterfly) chrysalises
+- `emerge(chrysalis_id:, force: false)` — natural emergence requires `transformation_progress >= 0.9`; forced emergence applies `PREMATURE_PENALTY` to beauty
+- `disturb(cocoon_id:, force: 0.1)` — degrades cocoon protection; if protection drops to 0 during active transformation, triggers forced emergence
+- `list_chrysalises` — all chrysalises with current state
+- `metamorphosis_status` — aggregate report
+
+## Helpers
+
+- `MetamorphosisEngine` — manages chrysalises and cocoons.
+- `Chrysalis` — state machine through `LIFE_STAGES`. `transform!(rate)` advances progress and beauty. `emerge!(force:)` checks threshold; forced emergence sets `@premature = true` and applies beauty penalty. `disturb!(force)` degrades protection.
+- `Cocoon` — protective environment with temperature, humidity, protection score.
+
+## Integration Points
+
+- `lex-cognitive-cocoon` is a related but distinct extension — cocoon models the protective encapsulation of fragile ideas; chrysalis models the full metamorphic transformation lifecycle (larva through butterfly). They can compose: a cocoon provides the environment, a chrysalis undergoes the transformation inside it.
+- `lex-memory` can hold chrysalis IDs as pending transformation traces — ideas that are not ready for activation but are undergoing gradual consolidation.
+- `lex-coldstart` imprint window is conceptually similar to the chrysalis state: ideas absorbed during cold start are in a protected transformation phase.
+
+## Development Notes
+
+- Stage progression is strictly one-directional: larva -> spinning -> cocooned -> transforming -> emerging -> butterfly. No regression.
+- `spin!` on a non-larva chrysalis raises `ArgumentError`. The runner returns `{ success: false, reason: e.message }`.
+- `transform!` auto-advances stage by comparing current stage rank vs progress-derived stage rank, taking the maximum. This means a chrysalis never regresses stages even if progress somehow decreases.
+- `premature?` convenience predicate: `butterfly? && beauty < 0.5`.
+- `beauty` is computed as `transformation_progress * 0.9` during incubation; full beauty (1.0) only on natural emergence.

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,78 @@
+PATH
+  remote: .
+  specs:
+    lex-cognitive-chrysalis (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    bigdecimal (4.0.1)
+    diff-lcs (1.6.2)
+    json (2.19.1)
+    json-schema (6.2.0)
+      addressable (~> 2.8)
+      bigdecimal (>= 3.1, < 5)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    mcp (0.8.0)
+      json-schema (>= 4.1)
+    parallel (1.27.0)
+    parser (3.3.10.2)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    public_suffix (7.0.5)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    regexp_parser (2.11.3)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.85.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-rspec (3.9.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.81)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  lex-cognitive-chrysalis!
+  rspec (~> 3.13)
+  rubocop (~> 1.75)
+  rubocop-rspec
+
+BUNDLED WITH
+   2.6.9

data/README.md

@@ -0,0 +1,42 @@
+# lex-cognitive-chrysalis
+
+Metamorphic identity transformation for LegionIO agents. Models structured dissolution and reformation cycles for the cognitive architecture.
+
+## What It Does
+
+Some ideas and identity facets require deep transformation before they are useful — not incremental improvement, but dissolution and reformation into something qualitatively different. This extension models that metamorphic process: a larva enters a protective chrysalis, incubates through multiple transformation stages, and emerges as a butterfly. Emergence quality (beauty) depends on whether the transformation ran to completion or was forced prematurely.
+
+Five chrysalis types provide different protection levels: silk (0.6), leaf (protected), bark (0.7), paper, and underground (highest). External disturbances can degrade cocoon protection and trigger premature emergence with a beauty penalty.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::CognitiveChrysalis::Client.new
+
+cocoon = client.create_cocoon(environment: 'quiet_space', temperature: 0.6, humidity: 0.5)
+
+chrysalis = client.create_chrysalis(
+  chrysalis_type: :silk,
+  content: 'core identity belief under revision'
+)
+
+client.spin(chrysalis_id: chrysalis[:chrysalis][:id])
+client.enclose(chrysalis_id: chrysalis[:chrysalis][:id],
+               cocoon_id: cocoon[:cocoon][:id])
+
+10.times { client.incubate(chrysalis_id: chrysalis[:chrysalis][:id]) }
+
+client.emerge(chrysalis_id: chrysalis[:chrysalis][:id])
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-chrysalis.gemspec

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_chrysalis/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-chrysalis'
+  spec.version       = Legion::Extensions::CognitiveChrysalis::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Chrysalis'
+  spec.description   = 'Metamorphic identity transformation for LegionIO agents — structured dissolution and reformation cycles'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-chrysalis'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']          = spec.homepage
+  spec.metadata['source_code_uri']       = 'https://github.com/LegionIO/lex-cognitive-chrysalis'
+  spec.metadata['documentation_uri']     = 'https://github.com/LegionIO/lex-cognitive-chrysalis'
+  spec.metadata['changelog_uri']         = 'https://github.com/LegionIO/lex-cognitive-chrysalis'
+  spec.metadata['bug_tracker_uri']       = 'https://github.com/LegionIO/lex-cognitive-chrysalis/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(__dir__) { `git ls-files -z`.split("\x0") }
+
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveChrysalis
+      class Client
+        include Runners::CognitiveChrysalis
+
+        attr_reader :engine
+
+        def initialize(**)
+          @engine         = Helpers::MetamorphosisEngine.new
+          @default_engine = @engine
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_chrysalis/helpers/chrysalis.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveChrysalis
+      module Helpers
+        class Chrysalis
+          attr_reader :id, :chrysalis_type, :content, :stage,
+                      :transformation_progress, :protection, :beauty, :created_at
+
+          def initialize(chrysalis_type:, content:, **)
+            @id                     = SecureRandom.uuid
+            @chrysalis_type         = chrysalis_type.to_sym
+            @content                = content.to_s
+            @stage                  = :larva
+            @transformation_progress = 0.0
+            @protection             = 0.8
+            @beauty                 = 0.0
+            @created_at             = Time.now.utc
+            @premature              = false
+          end
+
+          def spin!
+            raise ArgumentError, "must be :larva to spin, currently #{@stage}" unless @stage == :larva
+
+            @stage = :spinning
+            true
+          end
+
+          def cocoon!
+            raise ArgumentError, "must be :spinning to cocoon, currently #{@stage}" unless @stage == :spinning
+
+            @stage = :cocooned
+            true
+          end
+
+          def transform!(rate = Helpers::Constants::TRANSFORMATION_RATE)
+            return false if @stage == :butterfly
+
+            @transformation_progress = (@transformation_progress + rate).clamp(0.0, 1.0).round(10)
+            @beauty = (@transformation_progress * 0.9).clamp(0.0, 1.0).round(10)
+            update_stage_from_progress!
+            true
+          end
+
+          def emerge!(force: false)
+            if @transformation_progress >= Helpers::Constants::EMERGENCE_THRESHOLD
+              @stage  = :butterfly
+              @beauty = 1.0
+            elsif force
+              @premature = true
+              @stage     = :butterfly
+              @beauty    = (@beauty - Helpers::Constants::PREMATURE_PENALTY).clamp(0.0, 1.0).round(10)
+            else
+              return false
+            end
+            true
+          end
+
+          def decay_protection!
+            @protection = (@protection - Helpers::Constants::PROTECTION_DECAY).clamp(0.0, 1.0).round(10)
+          end
+
+          def disturb!(force)
+            @protection = (@protection - force.to_f).clamp(0.0, 1.0).round(10)
+            emerge!(force: true) if @protection <= 0 && %i[cocooned transforming].include?(@stage)
+          end
+
+          def butterfly?
+            @stage == :butterfly
+          end
+
+          def cocooned?
+            @stage == :cocooned
+          end
+
+          def transforming?
+            @stage == :transforming
+          end
+
+          def premature?
+            butterfly? && @beauty < 0.5
+          end
+
+          def stage_label
+            Helpers::Constants.label_for(Helpers::Constants::STAGE_LABELS, @transformation_progress)
+          end
+
+          def beauty_label
+            Helpers::Constants.label_for(Helpers::Constants::BEAUTY_LABELS, @beauty)
+          end
+
+          def to_h
+            {
+              id:                      @id,
+              chrysalis_type:          @chrysalis_type,
+              content:                 @content,
+              stage:                   @stage,
+              transformation_progress: @transformation_progress,
+              protection:              @protection,
+              beauty:                  @beauty,
+              stage_label:             stage_label,
+              beauty_label:            beauty_label,
+              premature:               @premature,
+              created_at:              @created_at
+            }
+          end
+
+          private
+
+          def update_stage_from_progress!
+            progress_stage = if @transformation_progress >= 0.8
+                               :emerging
+                             elsif @transformation_progress >= 0.6
+                               :transforming
+                             elsif @transformation_progress >= 0.4
+                               :cocooned
+                             elsif @transformation_progress >= 0.2
+                               :spinning
+                             else
+                               :larva
+                             end
+            current_rank  = Helpers::Constants::LIFE_STAGES.index(@stage) || 0
+            progress_rank = Helpers::Constants::LIFE_STAGES.index(progress_stage) || 0
+            @stage = Helpers::Constants::LIFE_STAGES[[current_rank, progress_rank].max]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_chrysalis/helpers/cocoon.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveChrysalis
+      module Helpers
+        class Cocoon
+          attr_reader :id, :environment, :temperature, :humidity, :chrysalis_ids, :created_at
+
+          TEMP_ADJUST = 0.05
+          HUMID_ADJUST = 0.05
+
+          def initialize(environment:, temperature: 0.5, humidity: 0.5, **)
+            @id            = SecureRandom.uuid
+            @environment   = environment.to_s
+            @temperature   = temperature.to_f.clamp(0.0, 1.0)
+            @humidity      = humidity.to_f.clamp(0.0, 1.0)
+            @chrysalis_ids = []
+            @created_at    = Time.now.utc
+          end
+
+          def shelter(chrysalis_id)
+            @chrysalis_ids << chrysalis_id unless @chrysalis_ids.include?(chrysalis_id)
+            true
+          end
+
+          def expose(chrysalis_id)
+            @chrysalis_ids.delete(chrysalis_id)
+            true
+          end
+
+          def warm!
+            @temperature = (@temperature + TEMP_ADJUST).clamp(0.0, 1.0).round(10)
+          end
+
+          def cool!
+            @temperature = (@temperature - TEMP_ADJUST).clamp(0.0, 1.0).round(10)
+          end
+
+          def moisten!
+            @humidity = (@humidity + HUMID_ADJUST).clamp(0.0, 1.0).round(10)
+          end
+
+          def dry!
+            @humidity = (@humidity - HUMID_ADJUST).clamp(0.0, 1.0).round(10)
+          end
+
+          def ideal?
+            @temperature.between?(0.4, 0.7) && @humidity.between?(0.4, 0.7)
+          end
+
+          def hostile?
+            @temperature > 0.9 || @humidity < 0.1
+          end
+
+          def growth_modifier
+            if ideal?
+              0.1
+            elsif hostile?
+              -0.05
+            else
+              0.0
+            end
+          end
+
+          def to_h
+            {
+              id:              @id,
+              environment:     @environment,
+              temperature:     @temperature,
+              humidity:        @humidity,
+              chrysalis_ids:   @chrysalis_ids.dup,
+              ideal:           ideal?,
+              hostile:         hostile?,
+              growth_modifier: growth_modifier,
+              created_at:      @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveChrysalis
+      module Helpers
+        module Constants
+          LIFE_STAGES = %i[larva spinning cocooned transforming emerging butterfly].freeze
+          CHRYSALIS_TYPES = %i[silk paper bark leaf underground].freeze
+
+          MAX_CHRYSALISES    = 200
+          MAX_BUTTERFLIES    = 500
+          TRANSFORMATION_RATE = 0.08
+          PROTECTION_DECAY = 0.03
+          EMERGENCE_THRESHOLD = 0.9
+          PREMATURE_PENALTY = 0.4
+
+          STAGE_LABELS = {
+            (0.0...0.20)  => :larva,
+            (0.20...0.40) => :spinning,
+            (0.40...0.60) => :cocooned,
+            (0.60...0.80) => :transforming,
+            (0.80...0.90) => :emerging,
+            (0.90..1.0)   => :butterfly
+          }.freeze
+
+          BEAUTY_LABELS = {
+            (0.0...0.20)  => :dull,
+            (0.20...0.40) => :plain,
+            (0.40...0.65) => :striking,
+            (0.65...0.85) => :beautiful,
+            (0.85..1.0)   => :magnificent
+          }.freeze
+
+          def self.label_for(table, value)
+            table.each do |range, label|
+              return label if range.cover?(value)
+            end
+            table.values.last
+          end
+        end
+      end
+    end
+  end
+end