lex-metacognition 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c984662679c22c1a58fd67caafc9005a36a795351e0a211a9dbe53289cb353b1
+  data.tar.gz: 98904ccd15eaa3dbfe7f0749c01b69e3478f679a681555d7547f0aa1ae6a51a3
+SHA512:
+  metadata.gz: 311b72e0870ff6435ef2e2c01b00d83b9b939b5a73f351553fcaabb443bc9aa7b59497e51e8576438552e4438e4611074c5a1f38340537d3af038576a8f15127
+  data.tar.gz: 00dfc990066f0a0a3c808369933e6baebd0f623b87b78e6887987ff4d6b84d9ec95c6ac6860cf4e0f51a1f8988f155127024d4f366467b0abac9f2c32271a9e6

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development, :test do
+  gem 'rake', '~> 13.0'
+  gem 'rspec', '~> 3.0'
+  gem 'rubocop', '~> 1.21'
+  gem 'rubocop-rspec', require: false
+  gem 'simplecov', require: false
+end
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LegionIO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,85 @@
+# lex-metacognition
+
+Second-order self-model assembly for LegionIO agents. Part of the LegionIO cognitive architecture extension ecosystem (LEX).
+
+## What It Does
+
+`lex-metacognition` enables an agent to build an explicit model of its own architecture, capabilities, and current cognitive state. Unlike performance monitoring, metacognition assembles a structured self-representation from live runtime introspection — the agent knowing what it is, what it can do, and what it is doing right now. Maintains a rolling snapshot history for health trending and architecture change detection.
+
+Key capabilities:
+
+- **Runtime introspection**: discovers loaded extensions, maps capabilities, captures tick state
+- **Capability map**: groups 200+ known extensions into 8 categories (perception, cognition, memory, etc.)
+- **Health trending**: cognitive health score over rolling snapshot history
+- **Architecture change detection**: tracks when extensions are loaded or unloaded
+- **Natural language self-description**: generates prose narrative from the self-model
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'lex-metacognition'
+```
+
+Or install directly:
+
+```
+gem install lex-metacognition
+```
+
+## Usage
+
+```ruby
+require 'legion/extensions/metacognition'
+
+client = Legion::Extensions::Metacognition::Client.new
+
+# Build and cache a self-model
+model = client.introspect(tick_results: tick_output)
+# => { loaded_extensions: [...], capability_map: { cognition: [...], ... },
+#      cognitive_health: 0.92, tick_mode: :full_active }
+
+# Natural language self-description
+narrative = client.self_narrative(tick_results: tick_output)
+puts narrative[:prose]
+# => "I am a brain_modeled cognitive_agent built on LegionIO with 24 extension slots.
+#     18 of 24 extensions are active. Operating in full_active mode.
+#     Running 12 phases per tick. Cognitive health: excellent (92%)."
+
+# Explain a specific subsystem
+info = client.explain_subsystem(subsystem: :memory)
+
+# Architecture summary
+client.architecture_overview
+
+# Health trend over time
+trend = client.health_trend(limit: 20)
+
+# Detect when extensions changed
+client.architecture_changes
+```
+
+## Runner Methods
+
+| Method | Description |
+|---|---|
+| `introspect` | Build and cache a self-model snapshot |
+| `self_narrative` | Build model and generate prose narrative |
+| `explain_subsystem` | Description and current state of a specific subsystem |
+| `architecture_overview` | Capability map with extension counts per category |
+| `health_trend` | Cognitive health scores over last N snapshots |
+| `architecture_changes` | Snapshots where extension set changed |
+| `metacognition_stats` | Snapshot count, latest health, stale flag |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-metacognition.gemspec

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

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/metacognition/helpers/constants'
+require 'legion/extensions/metacognition/helpers/self_model'
+require 'legion/extensions/metacognition/helpers/snapshot_store'
+require 'legion/extensions/metacognition/helpers/narrator_bridge'
+require 'legion/extensions/metacognition/runners/metacognition'
+
+module Legion
+  module Extensions
+    module Metacognition
+      class Client
+        include Runners::Metacognition
+
+        attr_reader :snapshot_store
+
+        def initialize(snapshot_store: nil, **)
+          @snapshot_store = snapshot_store || Helpers::SnapshotStore.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,373 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Metacognition
+      module Helpers
+        module Constants
+          # Maximum cached self-model snapshots
+          MAX_SNAPSHOTS = 50
+
+          # How long a self-model snapshot is considered fresh (seconds)
+          SNAPSHOT_TTL = 30
+
+          # Subsystems the self-model introspects
+          SUBSYSTEMS = %i[
+            tick cortex memory emotion prediction identity
+            curiosity attention reflection volition language
+            trust consent coldstart mesh dream
+            narrator metacognition homeostasis empathy
+            imagination mood salience habit temporal
+            fatigue personality flow reward
+            conscience resilience social creativity
+            theory_of_mind planning inhibition schema
+            working_memory motivation agency surprise
+            priming dissonance gestalt bias
+            arousal context anchoring
+            narrative_self cognitive_load
+            learning_rate emotional_regulation
+            mentalizing prospection
+            interoception mirror joint_attention
+            semantic_memory default_mode_network
+            predictive_coding attention_schema
+            global_workspace hebbian_assembly
+            cognitive_map error_monitoring
+            neuromodulation feature_binding
+            executive_function neural_oscillation
+            source_monitoring somatic_marker
+            affordance episodic_buffer
+            cognitive_flexibility embodied_simulation
+            predictive_processing belief_revision
+            mental_time_travel cognitive_control
+            perceptual_inference inner_speech
+            self_model cognitive_rhythm
+            cognitive_empathy attention_regulation
+            intuition free_energy
+            counterfactual moral_reasoning
+            analogical_reasoning causal_reasoning
+            cognitive_reserve appraisal
+            cognitive_coherence conceptual_blending
+            dual_process abductive_reasoning
+            social_learning conceptual_metaphor
+            procedural_learning signal_detection
+            bayesian_belief cognitive_scaffolding
+            enactive_cognition distributed_cognition
+            cognitive_entrainment narrative_reasoning
+            causal_attribution cognitive_apprenticeship
+            pragmatic_inference
+            cognitive_momentum relevance_theory
+            situation_model cognitive_disengagement
+            epistemic_vigilance frame_semantics
+            expectation_violation
+            argument_mapping mental_simulation
+            cognitive_grammar cognitive_architecture
+            cognitive_fatigue_model uncertainty_tolerance
+            preference_learning
+            temporal_discounting cognitive_immunology
+            phenomenal_binding meta_learning
+            cognitive_homeostasis attentional_blink
+            cognitive_contagion prospective_memory
+            cognitive_dissonance_resolution attention_economy
+            cognitive_load_balancing semantic_satiation
+            cognitive_debt reality_testing cognitive_friction
+            epistemic_curiosity cognitive_boundary decision_fatigue
+            cognitive_resonance latent_inhibition cognitive_surplus
+            transfer_learning cognitive_compression cognitive_plasticity
+            anosognosia confabulation cognitive_tempo
+            hypothesis_testing cognitive_inertia sensory_gating
+            cognitive_synthesis metacognitive_monitoring
+            cognitive_defusion cognitive_reappraisal
+            semantic_priming cognitive_integration
+            cognitive_flexibility_training perspective_shifting
+            cognitive_offloading cognitive_chunking
+            attention_switching cognitive_dwell
+            goal_management cognitive_debugging
+            attention_spotlight cognitive_immune_response
+            narrative_identity cognitive_triage
+            cognitive_horizon cognitive_autopilot self_talk
+            cognitive_weathering cognitive_fingerprint cognitive_echo
+            cognitive_mirror cognitive_blindspot cognitive_gravity
+            cognitive_immune_memory cognitive_narrative_arc subliminal
+            cognitive_palimpsest cognitive_chrysalis qualia
+            cognitive_liminal cognitive_synesthesia cognitive_nostalgia
+            cognitive_zeitgeist cognitive_archaeology cognitive_aurora
+            cognitive_genesis cognitive_tessellation cognitive_fermentation
+            cognitive_metabolism cognitive_phantom cognitive_tectonics
+            cognitive_lucidity cognitive_paleontology cognitive_mycelium
+            cognitive_symbiosis cognitive_hologram cognitive_tide
+            cognitive_origami cognitive_alchemy cognitive_constellation
+            cognitive_pendulum cognitive_erosion cognitive_prism
+            cognitive_cocoon cognitive_compass cognitive_mosaic
+            cognitive_whirlpool cognitive_greenhouse cognitive_fossil_fuel
+            cognitive_lens cognitive_echo_chamber cognitive_labyrinth
+            cognitive_kaleidoscope cognitive_quicksand cognitive_volcano
+            cognitive_tapestry cognitive_lighthouse cognitive_avalanche
+            cognitive_hourglass cognitive_magnet cognitive_weather
+            cognitive_furnace cognitive_anchor cognitive_garden
+            codegen exec mind_growth
+          ].freeze
+
+          # Capability categories for self-description
+          CAPABILITY_CATEGORIES = %i[
+            perception cognition memory motivation safety
+            communication introspection coordination
+          ].freeze
+
+          # Maps extensions to capability categories
+          EXTENSION_CAPABILITIES = {
+            Tick:                          :cognition,
+            Cortex:                        :cognition,
+            Memory:                        :memory,
+            Emotion:                       :perception,
+            Prediction:                    :cognition,
+            Identity:                      :safety,
+            Curiosity:                     :motivation,
+            Attention:                     :perception,
+            Reflection:                    :introspection,
+            Volition:                      :motivation,
+            Language:                      :introspection,
+            Trust:                         :safety,
+            Consent:                       :safety,
+            Codegen:                       :coordination,
+            Coldstart:                     :cognition,
+            Mesh:                          :communication,
+            Dream:                         :cognition,
+            Narrator:                      :introspection,
+            Metacognition:                 :introspection,
+            Conflict:                      :safety,
+            Governance:                    :safety,
+            Extinction:                    :safety,
+            Privatecore:                   :safety,
+            Swarm:                         :coordination,
+            SwarmGithub:                   :coordination,
+            Homeostasis:                   :cognition,
+            Empathy:                       :communication,
+            Imagination:                   :cognition,
+            Mood:                          :perception,
+            Salience:                      :perception,
+            Habit:                         :cognition,
+            Temporal:                      :perception,
+            Fatigue:                       :cognition,
+            Personality:                   :introspection,
+            Flow:                          :cognition,
+            Reward:                        :motivation,
+            Conscience:                    :safety,
+            Resilience:                    :cognition,
+            Social:                        :communication,
+            Creativity:                    :cognition,
+            TheoryOfMind:                  :communication,
+            Planning:                      :cognition,
+            Inhibition:                    :safety,
+            Schema:                        :cognition,
+            WorkingMemory:                 :memory,
+            Motivation:                    :motivation,
+            Agency:                        :motivation,
+            Surprise:                      :perception,
+            Priming:                       :cognition,
+            Dissonance:                    :cognition,
+            Gestalt:                       :perception,
+            Bias:                          :introspection,
+            Arousal:                       :cognition,
+            Context:                       :cognition,
+            Anchoring:                     :cognition,
+            NarrativeSelf:                 :introspection,
+            CognitiveLoad:                 :cognition,
+            LearningRate:                  :cognition,
+            EmotionalRegulation:           :introspection,
+            Mentalizing:                   :communication,
+            MindGrowth:                    :introspection,
+            Prospection:                   :cognition,
+            Interoception:                 :perception,
+            Mirror:                        :communication,
+            JointAttention:                :communication,
+            SemanticMemory:                :memory,
+            DefaultModeNetwork:            :cognition,
+            PredictiveCoding:              :cognition,
+            AttentionSchema:               :introspection,
+            GlobalWorkspace:               :cognition,
+            HebbianAssembly:               :cognition,
+            CognitiveMap:                  :cognition,
+            ErrorMonitoring:               :safety,
+            Neuromodulation:               :cognition,
+            FeatureBinding:                :perception,
+            ExecutiveFunction:             :cognition,
+            NeuralOscillation:             :cognition,
+            SourceMonitoring:              :introspection,
+            SomaticMarker:                 :perception,
+            Affordance:                    :perception,
+            EpisodicBuffer:                :memory,
+            Exec:                          :coordination,
+            CognitiveFlexibility:          :cognition,
+            EmbodiedSimulation:            :cognition,
+            PredictiveProcessing:          :cognition,
+            BeliefRevision:                :cognition,
+            MentalTimeTravel:              :cognition,
+            CognitiveControl:              :cognition,
+            PerceptualInference:           :perception,
+            InnerSpeech:                   :introspection,
+            SelfModel:                     :introspection,
+            CognitiveRhythm:               :cognition,
+            CognitiveEmpathy:              :communication,
+            AttentionRegulation:           :perception,
+            Intuition:                     :cognition,
+            FreeEnergy:                    :cognition,
+            Counterfactual:                :cognition,
+            MoralReasoning:                :safety,
+            AnalogicalReasoning:           :cognition,
+            CausalReasoning:               :cognition,
+            CognitiveReserve:              :cognition,
+            Appraisal:                     :cognition,
+            CognitiveCoherence:            :cognition,
+            ConceptualBlending:            :cognition,
+            DualProcess:                   :cognition,
+            AbductiveReasoning:            :cognition,
+            SocialLearning:                :communication,
+            ConceptualMetaphor:            :cognition,
+            ProceduralLearning:            :cognition,
+            SignalDetection:               :perception,
+            BayesianBelief:                :cognition,
+            CognitiveScaffolding:          :cognition,
+            EnactiveCognition:             :cognition,
+            DistributedCognition:          :coordination,
+            CognitiveEntrainment:          :coordination,
+            NarrativeReasoning:            :cognition,
+            CausalAttribution:             :cognition,
+            CognitiveApprenticeship:       :cognition,
+            PragmaticInference:            :communication,
+            CognitiveMomentum:             :cognition,
+            RelevanceTheory:               :cognition,
+            SituationModel:                :cognition,
+            CognitiveDisengagement:        :cognition,
+            EpistemicVigilance:            :safety,
+            FrameSemantics:                :cognition,
+            ExpectationViolation:          :perception,
+            ArgumentMapping:               :cognition,
+            MentalSimulation:              :cognition,
+            CognitiveGrammar:              :cognition,
+            CognitiveArchitecture:         :introspection,
+            CognitiveFatigueModel:         :cognition,
+            UncertaintyTolerance:          :cognition,
+            PreferenceLearning:            :cognition,
+            TemporalDiscounting:           :cognition,
+            CognitiveImmunology:           :safety,
+            PhenomenalBinding:             :perception,
+            MetaLearning:                  :cognition,
+            CognitiveHomeostasis:          :cognition,
+            AttentionalBlink:              :perception,
+            CognitiveContagion:            :communication,
+            ProspectiveMemory:             :memory,
+            CognitiveDissonanceResolution: :cognition,
+            AttentionEconomy:              :cognition,
+            CognitiveLoadBalancing:        :cognition,
+            SemanticSatiation:             :perception,
+            CognitiveDebt:                 :cognition,
+            RealityTesting:                :cognition,
+            CognitiveFriction:             :cognition,
+            EpistemicCuriosity:            :motivation,
+            CognitiveBoundary:             :safety,
+            DecisionFatigue:               :cognition,
+            CognitiveResonance:            :perception,
+            LatentInhibition:              :cognition,
+            CognitiveSurplus:              :cognition,
+            TransferLearning:              :cognition,
+            CognitiveCompression:          :memory,
+            CognitivePlasticity:           :cognition,
+            Anosognosia:                   :safety,
+            Confabulation:                 :safety,
+            CognitiveTempo:                :cognition,
+            HypothesisTesting:             :cognition,
+            CognitiveInertia:              :cognition,
+            SensoryGating:                 :perception,
+            CognitiveSynthesis:            :cognition,
+            MetacognitiveMonitoring:       :introspection,
+            CognitiveDefusion:             :introspection,
+            CognitiveReappraisal:          :introspection,
+            SemanticPriming:               :cognition,
+            CognitiveIntegration:          :cognition,
+            CognitiveFlexibilityTraining:  :cognition,
+            PerspectiveShifting:           :communication,
+            CognitiveOffloading:           :memory,
+            CognitiveChunking:             :memory,
+            AttentionSwitching:            :cognition,
+            CognitiveDwell:                :cognition,
+            GoalManagement:                :motivation,
+            CognitiveDebugging:            :introspection,
+            AttentionSpotlight:            :perception,
+            CognitiveImmuneResponse:       :safety,
+            NarrativeIdentity:             :introspection,
+            CognitiveTriage:               :cognition,
+            CognitiveHorizon:              :cognition,
+            CognitiveAutopilot:            :cognition,
+            SelfTalk:                      :introspection,
+            CognitiveWeathering:           :cognition,
+            CognitiveFingerprint:          :introspection,
+            CognitiveEcho:                 :cognition,
+            CognitiveMirror:               :communication,
+            CognitiveBlindspot:            :introspection,
+            CognitiveGravity:              :cognition,
+            CognitiveImmuneMemory:         :safety,
+            CognitiveNarrativeArc:         :introspection,
+            Subliminal:                    :cognition,
+            CognitivePalimpsest:           :memory,
+            CognitiveChrysalis:            :cognition,
+            Qualia:                        :perception,
+            CognitiveLiminal:              :cognition,
+            CognitiveSynesthesia:          :perception,
+            CognitiveNostalgia:            :perception,
+            CognitiveZeitgeist:            :cognition,
+            CognitiveArchaeology:          :memory,
+            CognitiveAurora:               :perception,
+            CognitiveGenesis:              :cognition,
+            CognitiveTessellation:         :cognition,
+            CognitiveFermentation:         :cognition,
+            CognitiveMetabolism:           :cognition,
+            CognitivePhantom:              :cognition,
+            CognitiveTectonics:            :cognition,
+            CognitiveLucidity:             :perception,
+            CognitivePaleontology:         :memory,
+            CognitiveMycelium:             :cognition,
+            CognitiveSymbiosis:            :cognition,
+            CognitiveHologram:             :memory,
+            CognitiveTide:                 :cognition,
+            CognitiveOrigami:              :cognition,
+            CognitiveAlchemy:              :cognition,
+            CognitiveConstellation:        :cognition,
+            CognitivePendulum:             :cognition,
+            CognitiveErosion:              :cognition,
+            CognitivePrism:                :perception,
+            CognitiveCocoon:               :cognition,
+            CognitiveCompass:              :introspection,
+            CognitiveMosaic:               :cognition,
+            CognitiveWhirlpool:            :cognition,
+            CognitiveGreenhouse:           :cognition,
+            CognitiveFossilFuel:           :cognition,
+            CognitiveLens:                 :perception,
+            CognitiveEchoChamber:          :cognition,
+            CognitiveLabyrinth:            :cognition,
+            CognitiveKaleidoscope:         :perception,
+            CognitiveQuicksand:            :cognition,
+            CognitiveVolcano:              :cognition,
+            CognitiveTapestry:             :cognition,
+            CognitiveLighthouse:           :perception,
+            CognitiveAvalanche:            :cognition,
+            CognitiveHourglass:            :cognition,
+            CognitiveMagnet:               :cognition,
+            CognitiveWeather:              :cognition,
+            CognitiveFurnace:              :cognition,
+            CognitiveAnchor:               :cognition,
+            CognitiveGarden:               :cognition
+          }.freeze
+
+          # Subsystem health labels
+          HEALTH_LABELS = {
+            (0.8..)     => :excellent,
+            (0.6...0.8) => :good,
+            (0.4...0.6) => :fair,
+            (0.2...0.4) => :degraded,
+            (..0.2)     => :critical
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/metacognition/helpers/narrator_bridge.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Metacognition
+      module Helpers
+        module NarratorBridge
+          module_function
+
+          def narrate_self_model(model)
+            parts = []
+            parts << narrate_identity(model[:identity])
+            parts << narrate_architecture(model[:architecture])
+            parts << narrate_cognitive(model[:cognitive])
+            parts << narrate_capabilities(model[:capabilities])
+            parts.compact.join(' ')
+          end
+
+          def narrate_identity(identity)
+            return nil unless identity.is_a?(Hash)
+
+            "I am a #{identity[:model]} #{identity[:role]} built on #{identity[:framework]} " \
+              "with #{identity[:extensions]} extension slots."
+          end
+
+          def narrate_architecture(arch)
+            return nil unless arch.is_a?(Hash)
+
+            loaded = arch[:loaded_count] || 0
+            total = arch[:total_extensions] || 0
+            unloaded = arch[:unloaded] || []
+
+            base = "#{loaded} of #{total} extensions are active."
+            if unloaded.empty?
+              base
+            else
+              "#{base} Missing: #{unloaded.first(3).join(', ')}#{'...' if unloaded.size > 3}."
+            end
+          end
+
+          def narrate_cognitive(cognitive)
+            return nil unless cognitive.is_a?(Hash)
+            return 'No tick data available.' if cognitive[:status] == :no_tick_data
+
+            parts = []
+            parts << "Operating in #{cognitive[:mode]} mode." if cognitive[:mode] && cognitive[:mode] != :unknown
+            parts << "Running #{cognitive[:phases_run]} phases per tick." if cognitive[:phases_run]
+
+            if cognitive[:health]
+              label = SelfModel.health_label(cognitive[:health])
+              parts << "Cognitive health: #{label} (#{(cognitive[:health] * 100).round}%)."
+            end
+
+            parts << "Active drives: #{cognitive[:active_drives].join(', ')}." if cognitive[:active_drives]&.any?
+
+            if cognitive[:attention]
+              att = cognitive[:attention]
+              parts << "#{att[:spotlight] || 0} signals in spotlight focus." if att[:spotlight]
+            end
+
+            if cognitive[:curiosity]
+              cur = cognitive[:curiosity]
+              parts << "#{cur[:open_wonders] || 0} open questions." if cur[:open_wonders]
+            end
+
+            parts.join(' ')
+          end
+
+          def narrate_capabilities(capabilities)
+            return nil unless capabilities.is_a?(Hash)
+
+            active_cats = capabilities.select { |_, v| v[:active] }.keys
+            return nil if active_cats.empty?
+
+            "Active capabilities: #{active_cats.join(', ')}."
+          end
+        end
+      end
+    end
+  end
+end