lex-cognitive-cocoon 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '015861041cc51dbe313a2557691ba5e0ff0b791ad8d85f847554943303eb6e94'
+  data.tar.gz: 52d9550926706ae26259b4f1f1e7dfb1ad1feab47aa8b22de87ae074bde16683
+SHA512:
+  metadata.gz: f6e19065a979162ccaa24c6cdb81a96806d7e2009b9573c3da0c54f553c5507e9d19221701241a6637f38065e558e3de112f1154c4df111ec6e9f9fd3667cd33
+  data.tar.gz: 1818eaedc7a0be8fbbee37f4c59b0f35a014c3c47c3495ba102c97d46bb470d5a628569564b221cd322c32596c4f956725e40ed989965a9c8732e4be6918ee97

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,2 @@
+.rspec_status
+Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,37 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.4
+
+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/OneClassPerFile:
+  Exclude:
+    - spec/spec_helper.rb

data/CLAUDE.md

@@ -0,0 +1,72 @@
+# lex-cognitive-cocoon
+
+**Level 3 Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+- **Grandparent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+Protective encapsulation of fragile ideas during development. Models cognitive cocooning: fragile ideas enter protective shells, gestate at complexity-appropriate rates, and emerge transformed. Premature exposure risks idea death (premature penalty). Distinct from `lex-cognitive-chrysalis` — cocoon focuses on the protective encapsulation container, while chrysalis models the full metamorphic transformation lifecycle.
+
+## Gem Info
+
+- **Gem name**: `lex-cognitive-cocoon`
+- **Version**: `0.1.0`
+- **Module**: `Legion::Extensions::CognitiveCocoon`
+- **Ruby**: `>= 3.4`
+- **License**: MIT
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_cocoon/
+  cognitive_cocoon.rb
+  version.rb
+  client.rb
+  helpers/
+    constants.rb
+    cocoon.rb
+    incubator.rb
+  runners/
+    cognitive_cocoon.rb
+```
+
+## Key Constants
+
+From `helpers/constants.rb`:
+
+- `GESTATION_STAGES` — `%i[encapsulating developing transforming ready emerged]`
+- `COCOON_TYPES` — `%i[silk chrysalis shell pod web]`
+- `PROTECTION_BY_TYPE` — `silk: 0.6, chrysalis: 0.8, shell: 0.9, pod: 0.7, web: 0.5`
+- `MAX_COCOONS` = `100`
+- `MATURITY_RATE` = `0.1`, `PREMATURE_PENALTY` = `0.5`
+- `MATURITY_LABELS` — `0.9+` = `:fully_gestated`, `0.7` = `:nearly_ready`, `0.5` = `:mid_gestation`, `0.3` = `:early_gestation`, `0.1` = `:just_encapsulated`, below = `:newly_formed`
+
+## Runners
+
+All methods in `Runners::CognitiveCocoon`:
+
+- `create_cocoon(cocoon_type:, domain:, content: '', maturity: nil, protection: nil)` — creates a new cocoon; protection defaults to `PROTECTION_BY_TYPE[cocoon_type]`
+- `gestate_all(rate: MATURITY_RATE)` — advances maturity on all non-emerged cocoons by rate
+- `harvest_ready` — returns all cocoons that have reached `:ready` or `:emerged` state
+- `force_emerge(id:)` — forces premature emergence; applies `PREMATURE_PENALTY`
+- `cocoon_status` — aggregate incubator report
+- `list_by_stage(stage:)` — filters cocoons by gestation stage
+
+## Helpers
+
+- `Incubator` — manages the cocoon collection. `harvest_ready` transitions ready cocoons to `:emerged` and returns them.
+- `Cocoon` — has `cocoon_type`, `domain`, `content`, `maturity`, `protection`. `gestate!(rate)` advances maturity; stage is derived from maturity value. `force_emerge!` applies premature penalty and sets stage to `:emerged`.
+
+## Integration Points
+
+- `lex-cognitive-chrysalis` composes with this extension: a chrysalis can be enclosed in a cocoon (the cocoon provides protection, the chrysalis undergoes transformation inside it).
+- Newly registered `lex-memory` traces during the imprint window (`lex-coldstart`) are conceptually in a cocooned state — fragile associations that should not be immediately overwritten or decayed.
+- `gestate_all` is the natural periodic runner to call each tick cycle.
+
+## Development Notes
+
+- `@default_engine` is referenced directly in runner methods (not via a private method helper) — this differs from other extensions. The runner accesses `@default_engine` directly; callers must pass `engine:` to avoid sharing state across runner instances.
+- `protection` defaults to `PROTECTION_BY_TYPE[cocoon_type]` if not specified — callers who want to set a custom protection must pass it explicitly.
+- `PREMATURE_PENALTY = 0.5` reduces maturity on forced emergence, not a separate beauty score.
+- `MAX_COCOONS = 100` — at capacity, new cocoon creation raises an error.

data/Gemfile

@@ -0,0 +1,11 @@
+# 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-cocoon (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-cocoon!
+  rspec (~> 3.13)
+  rubocop (~> 1.75)
+  rubocop-rspec
+
+BUNDLED WITH
+   2.6.9

data/README.md

@@ -0,0 +1,39 @@
+# lex-cognitive-cocoon
+
+Protective encapsulation of fragile ideas during development for LegionIO agents. Models cognitive cocooning — fragile ideas enter protective shells, gestate at complexity-appropriate rates, and emerge transformed.
+
+## What It Does
+
+Not all ideas are ready for the world. Some need protected incubation before they are robust enough to integrate with existing knowledge. This extension models that protective phase: ideas are wrapped in type-appropriate cocoons (silk, chrysalis, shell, pod, web) with different protection strengths, and gestate through stages until they are ready to emerge. Premature forced emergence applies a maturity penalty.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::CognitiveCocoon::Client.new
+
+cocoon = client.create_cocoon(
+  cocoon_type: :shell,
+  domain: :identity,
+  content: 'tentative belief about autonomy thresholds'
+)
+
+# Call periodically to advance gestation
+5.times { client.gestate_all(rate: 0.1) }
+
+client.cocoon_status
+# => { total: 1, ready: 0, emerged: 0, ... }
+
+ready = client.harvest_ready
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-cocoon.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_cocoon/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-cocoon'
+  spec.version       = Legion::Extensions::CognitiveCocoon::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+  spec.summary       = 'Protective encapsulation of fragile ideas during development for LegionIO agents'
+  spec.description   = 'Models cognitive cocooning — fragile ideas enter protective shells, gestate ' \
+                       'at complexity-appropriate rates, and emerge transformed. Premature exposure risks idea death.'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-cocoon'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata = {
+    'homepage_uri'          => spec.homepage,
+    'source_code_uri'       => spec.homepage,
+    'documentation_uri'     => "#{spec.homepage}/blob/master/README.md",
+    'changelog_uri'         => "#{spec.homepage}/blob/master/CHANGELOG.md",
+    'bug_tracker_uri'       => "#{spec.homepage}/issues",
+    '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_cocoon/client.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveCocoon
+      class Client
+        include Runners::CognitiveCocoon
+
+        def initialize
+          @default_engine = Helpers::Incubator.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveCocoon
+      module Helpers
+        class Cocoon
+          include Constants
+
+          attr_reader :id, :cocoon_type, :domain, :content, :maturity,
+                      :stage, :protection, :created_at
+
+          def initialize(cocoon_type:, domain:, content: '', maturity: nil, protection: nil)
+            @id = SecureRandom.uuid
+            @cocoon_type = cocoon_type.to_sym
+            @domain     = domain.to_sym
+            @content    = content
+            @maturity   = (maturity || 0.0).to_f.clamp(0.0, 1.0)
+            @protection = (protection || PROTECTION_BY_TYPE.fetch(@cocoon_type, 0.7)).to_f.clamp(0.0, 1.0)
+            @stage      = :encapsulating
+            @created_at = Time.now.utc
+            advance_stage!
+          end
+
+          def gestate!(rate = MATURITY_RATE)
+            return self if @stage == :emerged
+
+            @maturity = (@maturity + rate).clamp(0.0, 1.0).round(10)
+            advance_stage!
+            self
+          end
+
+          def emerge!
+            return { success: false, error: 'not ready', damaged: false } unless ready?
+
+            @stage = :emerged
+            { success: true, content: @content, damaged: false, maturity: @maturity }
+          end
+
+          def expose!
+            damaged = premature?
+            @maturity = (@maturity * PREMATURE_PENALTY).round(10) if damaged
+            @stage = :emerged
+            { success: true, content: @content, damaged: damaged, maturity: @maturity }
+          end
+
+          def ready?
+            @maturity >= 1.0 || @stage == :ready
+          end
+
+          def premature?
+            @stage != :ready && @stage != :emerged && @maturity < 1.0
+          end
+
+          def age_seconds
+            (Time.now.utc - @created_at).round(2)
+          end
+
+          def to_h
+            {
+              id:             @id,
+              cocoon_type:    @cocoon_type,
+              domain:         @domain,
+              content:        @content,
+              maturity:       @maturity.round(10),
+              stage:          @stage,
+              protection:     @protection.round(10),
+              ready:          ready?,
+              premature:      premature?,
+              maturity_label: Constants.label_for(MATURITY_LABELS, @maturity),
+              age_seconds:    age_seconds,
+              created_at:     @created_at.iso8601
+            }
+          end
+
+          private
+
+          def advance_stage!
+            @stage = compute_stage
+          end
+
+          def compute_stage
+            return :emerged if @stage == :emerged
+
+            if @maturity >= 1.0
+              :ready
+            elsif @maturity >= 0.75
+              :transforming
+            elsif @maturity >= 0.4
+              :developing
+            else
+              :encapsulating
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveCocoon
+      module Helpers
+        module Constants
+          MAX_COCOONS      = 100
+          MATURITY_RATE    = 0.1
+          PREMATURE_PENALTY = 0.5
+
+          GESTATION_STAGES = %i[encapsulating developing transforming ready emerged].freeze
+
+          COCOON_TYPES = %i[silk chrysalis shell pod web].freeze
+
+          PROTECTION_BY_TYPE = {
+            silk:      0.6,
+            chrysalis: 0.8,
+            shell:     0.9,
+            pod:       0.7,
+            web:       0.5
+          }.freeze
+
+          MATURITY_LABELS = {
+            (0.9..)     => :fully_gestated,
+            (0.7...0.9) => :nearly_ready,
+            (0.5...0.7) => :mid_gestation,
+            (0.3...0.5) => :early_gestation,
+            (0.1...0.3) => :just_encapsulated,
+            (..0.1)     => :newly_formed
+          }.freeze
+
+          def self.label_for(labels, value)
+            labels.each { |range, label| return label if range.cover?(value) }
+            :unknown
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_cocoon/helpers/incubator.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveCocoon
+      module Helpers
+        class Incubator
+          include Constants
+
+          def initialize
+            @cocoons = {}
+          end
+
+          def create_cocoon(cocoon_type:, domain:, content: '', maturity: nil, protection: nil)
+            prune_cocoons
+            cocoon = Cocoon.new(
+              cocoon_type: cocoon_type,
+              domain:      domain,
+              content:     content,
+              maturity:    maturity,
+              protection:  protection
+            )
+            @cocoons[cocoon.id] = cocoon
+            cocoon
+          end
+
+          def gestate_all!(rate = MATURITY_RATE)
+            @cocoons.each_value { |c| c.gestate!(rate) unless c.stage == :emerged }
+            self
+          end
+
+          def harvest_ready
+            ready = @cocoons.values.select(&:ready?)
+            results = ready.map(&:emerge!)
+            ready.each { |c| @cocoons.delete(c.id) if c.stage == :emerged }
+            results
+          end
+
+          def force_emerge(id)
+            cocoon = @cocoons[id]
+            return { success: false, error: 'cocoon not found' } unless cocoon
+
+            result = cocoon.expose!
+            @cocoons.delete(id) if cocoon.stage == :emerged
+            result
+          end
+
+          def by_stage(stage)
+            @cocoons.values.select { |c| c.stage == stage.to_sym }
+          end
+
+          def most_mature(limit: 5)
+            @cocoons.values.sort_by { |c| -c.maturity }.first(limit)
+          end
+
+          def incubator_report
+            total    = @cocoons.size
+            by_s     = Hash.new(0)
+            @cocoons.each_value { |c| by_s[c.stage] += 1 }
+            avg_mat  = total.zero? ? 0.0 : (@cocoons.values.sum(&:maturity) / total).round(10)
+            avg_prot = total.zero? ? 0.0 : (@cocoons.values.sum(&:protection) / total).round(10)
+
+            {
+              total_cocoons:      total,
+              average_maturity:   avg_mat,
+              maturity_label:     Constants.label_for(MATURITY_LABELS, avg_mat),
+              average_protection: avg_prot,
+              stage_distribution: by_s,
+              ready_count:        by_stage(:ready).size,
+              most_mature:        most_mature(limit: 3).map(&:to_h)
+            }
+          end
+
+          def to_h
+            {
+              total_cocoons:    @cocoons.size,
+              average_maturity: @cocoons.empty? ? 0.0 : (@cocoons.values.sum(&:maturity) / @cocoons.size).round(10)
+            }
+          end
+
+          private
+
+          def prune_cocoons
+            return if @cocoons.size < MAX_COCOONS
+
+            emerged = @cocoons.values.select { |c| c.stage == :emerged }
+            emerged.each { |c| @cocoons.delete(c.id) }
+            return if @cocoons.size < MAX_COCOONS
+
+            sorted = @cocoons.values.sort_by(&:maturity)
+            to_remove = sorted.first(@cocoons.size - MAX_COCOONS + 1)
+            to_remove.each { |c| @cocoons.delete(c.id) }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveCocoon
+      module Runners
+        module CognitiveCocoon
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+          def create_cocoon(cocoon_type:, domain:, content: '', maturity: nil,
+                            protection: nil, engine: nil, **)
+            eng = engine || @default_engine
+            cocoon = eng.create_cocoon(
+              cocoon_type: cocoon_type,
+              domain:      domain,
+              content:     content,
+              maturity:    maturity,
+              protection:  protection
+            )
+            { success: true, cocoon: cocoon.to_h }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def gestate_all(rate: nil, engine: nil, **)
+            eng = engine || @default_engine
+            eng.gestate_all!(rate || Helpers::Constants::MATURITY_RATE)
+            { success: true }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def harvest_ready(engine: nil, **)
+            eng = engine || @default_engine
+            emerged = eng.harvest_ready
+            { success: true, count: emerged.size, emerged: emerged }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def force_emerge(id:, engine: nil, **)
+            eng = engine || @default_engine
+            result = eng.force_emerge(id)
+            result.merge(success: result[:error].nil?)
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def cocoon_status(engine: nil, **)
+            eng = engine || @default_engine
+            report = eng.incubator_report
+            { success: true, **report }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def list_by_stage(stage:, engine: nil, **)
+            eng = engine || @default_engine
+            cocoons = eng.by_stage(stage)
+            { success: true, stage: stage, count: cocoons.size, cocoons: cocoons.map(&:to_h) }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_cocoon.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require_relative 'cognitive_cocoon/version'
+require_relative 'cognitive_cocoon/helpers/constants'
+require_relative 'cognitive_cocoon/helpers/cocoon'
+require_relative 'cognitive_cocoon/helpers/incubator'
+require_relative 'cognitive_cocoon/runners/cognitive_cocoon'
+require_relative 'cognitive_cocoon/client'
+
+module Legion
+  module Extensions
+    module CognitiveCocoon
+    end
+  end
+end
+
+Legion::Extensions.extend(Legion::Extensions::Core) if Legion::Extensions.const_defined?(:Core)