lex-agentic-self 0.1.8 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c660e26600da2bf1c6e0ec3ff8c8d81a1eabebc3859d3de838e30f22b4ba91d
-  data.tar.gz: ec3d26a5dd95ad077de1880fd60f48d23ff0a34aa841f82cda7bcbfdad99e5d0
+  metadata.gz: '081b534c7eaf4efbc0265eada2d3b8f11b37b93a3fb34be77068d0ce4f0e842d'
+  data.tar.gz: ce8a3839f617dc41d904ccf54a98a208037178cd89eefb39cd031fce8a89e315
 SHA512:
-  metadata.gz: ffbe4a9cee92f015c0d167fa98327aceb9641c8dd448d99f0649ff42e87eb531b51eec961729f615e274c2854422cdb0b3e2cc77d02f456b9ceeb944a6088ebb
-  data.tar.gz: f418467e5090f41939297b8907288f4ef29b95fbc9def510bbc1efb503abd79cdf8a3420b7ec2ce707d5d29d06e0569531da88395658a3901b80a8d7356b53b9
+  metadata.gz: 49409e3e358267476770c66db88a4eff2f7968857c130e547cc3170a3c3e891b27358d7b28ac77e81e5733d480ab65480b38c10c908ef9323738b4159bab527e
+  data.tar.gz: fd913ef78cfa8b14ccb5bdadbd95e3133e5bcf67d21a40332ba360ba6393ebd1b34e7db0ccebe3a4bf177aea506d1fc666dcb0efc89820e26853e0574888998d

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.1.10] - 2026-03-31
+
+### Added
+- RelationshipArc sub-module for Phase C relational intelligence
+- Constants: chapters, milestone types, health weights, chapter thresholds
+- Milestone: typed data class with UUID, significance clamping, serialization
+- ArcEngine: chapter progression, milestone tracking, relationship health, Apollo Local persistence
+- RelationshipArc runner: record_milestone, update_arc, arc_stats with NarrativeIdentity episode stamping
+
+## [0.1.9] - 2026-03-31
+
+### Added
+- add `PARTNER_SIGNAL_MAP` and `PARTNER_SIGNAL_THRESHOLD` constants to Personality::Helpers::Constants for partner-specific OCEAN nudges (weight 0.2 per signal)
+- add `TraitModel#apply_partner_signals` to nudge extraversion, agreeableness, openness, and conscientiousness from partner engagement patterns; signals below threshold (0.3) are ignored
+- wire partner signal extraction into `PersonalityStore#update` via `tick_results[:social]` reputation data (engagement frequency, direct address ratio, content diversity, consistency)
+- add 16 specs covering PARTNER_SIGNAL_MAP entries, threshold gating, multi-signal application, and no observation_count side-effect
+
 ## [0.1.8] - 2026-03-30
 
 ### Fixed

data/lib/legion/extensions/agentic/self/personality/helpers/constants.rb

@@ -70,6 +70,20 @@ module Legion
                 mood_stability:        [:neuroticism, :negative, 0.3]
               }.freeze
 
+              # Partner-specific signal map: partner interaction patterns that slowly nudge OCEAN traits.
+              # Lower weight (0.2) than general signals — personality should drift very slowly from
+              # partner engagement alone.
+              # Each entry: [trait, direction, weight]
+              PARTNER_SIGNAL_MAP = {
+                partner_engagement_frequency: [:extraversion, :positive, 0.2],
+                partner_direct_address_ratio: [:agreeableness, :positive, 0.2],
+                partner_content_diversity:    [:openness, :positive, 0.2],
+                partner_consistency:          [:conscientiousness, :positive, 0.2]
+              }.freeze
+
+              # Minimum signal value required to apply a partner nudge (0.0–1.0)
+              PARTNER_SIGNAL_THRESHOLD = 0.3
+
               # Threshold for "high" trait descriptor
               HIGH_THRESHOLD = 0.65
 

data/lib/legion/extensions/agentic/self/personality/helpers/personality_store.rb

@@ -16,6 +16,8 @@ module Legion
               def update(tick_results)
                 signals = extract_signals(tick_results)
                 @model.update(signals)
+                partner_signals = extract_partner_signals(tick_results)
+                @model.apply_partner_signals(partner_signals) unless partner_signals.empty?
               end
 
               def full_description
@@ -41,6 +43,42 @@ module Legion
 
               private
 
+              def extract_partner_signals(tick_results)
+                counts = partner_records(tick_results)
+                return {} if counts.empty?
+
+                {
+                  partner_engagement_frequency: partner_engagement_frequency(counts),
+                  partner_direct_address_ratio: avg_partner_field(counts, :direct_address_ratio),
+                  partner_content_diversity:    avg_partner_diversity(counts),
+                  partner_consistency:          avg_partner_field(counts, :consistency)
+                }.compact
+              end
+
+              def partner_records(tick_results)
+                social = tick_results[:social] || tick_results[:social_cognition] || {}
+                return [] unless social.is_a?(Hash)
+
+                reputation = social[:reputation_updates] || social[:partners] || {}
+                return [] unless reputation.is_a?(Hash) && reputation.any?
+
+                reputation.values.grep(Hash)
+              end
+
+              def partner_engagement_frequency(counts)
+                (counts.count { |p| p[:message_count].to_i.positive? } / counts.size.to_f).clamp(0.0, 1.0)
+              end
+
+              def avg_partner_field(counts, key)
+                vals = counts.filter_map { |p| p[key] }.grep(Numeric)
+                vals.any? ? (vals.sum / vals.size.to_f).clamp(0.0, 1.0) : nil
+              end
+
+              def avg_partner_diversity(counts)
+                vals = counts.filter_map { |p| p[:topic_diversity] || p[:content_diversity] }.grep(Numeric)
+                vals.any? ? (vals.sum / vals.size.to_f).clamp(0.0, 1.0) : nil
+              end
+
               def extract_signals(tick_results)
                 signals = {}
 

data/lib/legion/extensions/agentic/self/personality/helpers/trait_model.rb

@@ -30,6 +30,14 @@ module Legion
                 @traits[name.to_sym]
               end
 
+              def apply_partner_signals(signals)
+                observations = extract_partner_observations(signals)
+                return if observations.empty?
+
+                apply_observations(observations)
+                record_snapshot
+              end
+
               def formed?
                 @observation_count >= Constants::FORMATION_THRESHOLD
               end
@@ -105,6 +113,21 @@ module Legion
 
               private
 
+              def extract_partner_observations(signals)
+                observations = Hash.new { |h, k| h[k] = [] }
+
+                Constants::PARTNER_SIGNAL_MAP.each do |signal_key, (trait, direction, weight)|
+                  value = signals[signal_key]
+                  next unless value.is_a?(Numeric)
+                  next if value <= Constants::PARTNER_SIGNAL_THRESHOLD
+
+                  effective = direction == :positive ? value : 1.0 - value
+                  observations[trait] << { value: effective, weight: weight }
+                end
+
+                observations
+              end
+
               def extract_observations(signals)
                 observations = Hash.new { |h, k| h[k] = [] }
 

data/lib/legion/extensions/agentic/self/relationship_arc/client.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/self/relationship_arc/helpers/constants'
+require 'legion/extensions/agentic/self/relationship_arc/helpers/milestone'
+require 'legion/extensions/agentic/self/relationship_arc/helpers/arc_engine'
+require 'legion/extensions/agentic/self/relationship_arc/runners/relationship_arc'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module RelationshipArc
+          class Client
+            include Runners::RelationshipArc
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/relationship_arc/helpers/arc_engine.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module RelationshipArc
+          module Helpers
+            class ArcEngine
+              attr_reader :agent_id, :current_chapter, :milestones
+
+              BOND_STAGE_ORDER = %i[initial forming established deep].freeze
+              private_constant :BOND_STAGE_ORDER
+
+              def initialize(agent_id:)
+                @agent_id        = agent_id
+                @current_chapter = :formative
+                @milestones      = []
+                @dirty           = false
+              end
+
+              def add_milestone(type:, description:, significance:, **)
+                ms = Milestone.new(type: type, description: description, significance: significance)
+                @milestones << ms
+                @milestones.shift while @milestones.size > Constants::MAX_MILESTONES
+                @dirty = true
+                ms
+              end
+
+              def update_chapter!(bond_stage: :initial, **)
+                new_chapter = derive_chapter(bond_stage)
+                return if Constants::CHAPTERS.index(new_chapter) <= Constants::CHAPTERS.index(@current_chapter)
+
+                @current_chapter = new_chapter
+                @dirty = true
+              end
+
+              def relationship_health(attachment_strength: 0.0, reciprocity_balance: 0.5,
+                                      communication_consistency: 0.5, **)
+                w = Constants::HEALTH_WEIGHTS
+                score = (attachment_strength.to_f * w[:attachment_strength]) +
+                        (reciprocity_balance.to_f * w[:reciprocity_balance]) +
+                        (communication_consistency.to_f * w[:communication_consistency])
+                score.clamp(0.0, 1.0)
+              end
+
+              def dirty?
+                @dirty
+              end
+
+              def mark_clean!
+                @dirty = false
+                self
+              end
+
+              def to_apollo_entries
+                tags = Constants::TAG_PREFIX.dup + [@agent_id]
+                tags << 'partner' if partner?(@agent_id)
+                [{ content: serialize(arc_state_hash), tags: tags }]
+              end
+
+              def from_apollo(store:)
+                result = store.query(text: 'relationship_arc', tags: Constants::TAG_PREFIX + [@agent_id])
+                return false unless result[:success] && result[:results]&.any?
+
+                parsed = deserialize(result[:results].first[:content])
+                return false unless parsed
+
+                @current_chapter = parsed[:current_chapter]&.to_sym || :formative
+                @milestones = (parsed[:milestones] || []).map { |mh| Milestone.from_h(mh.transform_keys(&:to_sym)) }
+                true
+              rescue StandardError => e
+                warn "[arc_engine] from_apollo error: #{e.message}"
+                false
+              end
+
+              def to_h
+                { agent_id: @agent_id, current_chapter: @current_chapter,
+                  milestones: @milestones.map(&:to_h),
+                  relationship_health: nil, milestone_count: @milestones.size }
+              end
+
+              private
+
+              def arc_state_hash
+                { agent_id: @agent_id, current_chapter: @current_chapter,
+                  milestones: @milestones.map(&:to_h) }
+              end
+
+              def derive_chapter(bond_stage)
+                Constants::CHAPTER_THRESHOLDS.each_key.reverse_each do |chapter|
+                  threshold = Constants::CHAPTER_THRESHOLDS[chapter]
+                  stage_idx = BOND_STAGE_ORDER.index(threshold[:stage]) || 0
+                  current_stage_idx = BOND_STAGE_ORDER.index(bond_stage) || 0
+
+                  return chapter if @milestones.size >= threshold[:milestones] &&
+                                    current_stage_idx >= stage_idx
+                end
+                :formative
+              end
+
+              def partner?(agent_id)
+                defined?(Legion::Gaia::BondRegistry) && Legion::Gaia::BondRegistry.partner?(agent_id)
+              end
+
+              def serialize(hash)
+                defined?(Legion::JSON) ? Legion::JSON.dump(hash) : ::JSON.dump(hash)
+              end
+
+              def deserialize(content)
+                parsed = defined?(Legion::JSON) ? Legion::JSON.parse(content) : ::JSON.parse(content, symbolize_names: true)
+                parsed.is_a?(Hash) ? parsed.transform_keys(&:to_sym) : nil
+              rescue StandardError => _e
+                nil
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/relationship_arc/helpers/constants.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module RelationshipArc
+          module Helpers
+            module Constants
+              CHAPTERS = %i[formative developing established deepening].freeze
+
+              MILESTONE_TYPES = %i[
+                first_interaction first_direct_address stage_transition
+                prediction_accuracy communication_shift absence_return
+              ].freeze
+
+              HEALTH_WEIGHTS = {
+                attachment_strength:       0.4,
+                reciprocity_balance:       0.3,
+                communication_consistency: 0.3
+              }.freeze
+
+              MAX_MILESTONES = 200
+
+              CHAPTER_THRESHOLDS = {
+                developing:  { milestones: 3,  stage: :forming },
+                established: { milestones: 10, stage: :established },
+                deepening:   { milestones: 25, stage: :deep }
+              }.freeze
+
+              TAG_PREFIX = %w[bond relationship_arc].freeze
+              MILESTONE_TAG_PREFIX = %w[bond milestone].freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/relationship_arc/helpers/milestone.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module RelationshipArc
+          module Helpers
+            class Milestone
+              attr_reader :id, :type, :description, :significance, :created_at
+
+              def initialize(type:, description:, significance:, id: nil, created_at: nil)
+                @id           = id || SecureRandom.uuid
+                @type         = type.to_sym
+                @description  = description
+                @significance = significance.to_f.clamp(0.0, 1.0)
+                @created_at   = created_at || Time.now.utc
+              end
+
+              def to_h
+                { id: @id, type: @type, description: @description,
+                  significance: @significance, created_at: @created_at.iso8601 }
+              end
+
+              def self.from_h(hash)
+                new(
+                  id:           hash[:id],
+                  type:         hash[:type],
+                  description:  hash[:description],
+                  significance: hash[:significance],
+                  created_at:   hash[:created_at] ? Time.parse(hash[:created_at].to_s) : nil
+                )
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/relationship_arc/runners/relationship_arc.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module RelationshipArc
+          module Runners
+            module RelationshipArc
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex, false)
+
+              def record_milestone(agent_id:, type:, description:, significance:, **)
+                unless Helpers::Constants::MILESTONE_TYPES.include?(type.to_sym)
+                  return { success: false,
+                           error:   "unknown type: #{type}" }
+                end
+
+                engine = arc_engine_for(agent_id)
+                ms = engine.add_milestone(type: type, description: description, significance: significance)
+
+                stamp_narrative_episode(ms)
+
+                { success: true, milestone: ms.to_h }
+              rescue StandardError => e
+                { success: false, error: e.message }
+              end
+
+              def update_arc(agent_id:, attachment_state: {}, **)
+                engine = arc_engine_for(agent_id)
+                engine.update_chapter!(bond_stage: attachment_state[:bond_stage] || :initial)
+
+                { success: true, current_chapter: engine.current_chapter,
+                  milestone_count: engine.milestones.size }
+              rescue StandardError => e
+                { success: false, error: e.message }
+              end
+
+              def arc_stats(agent_id:, **)
+                engine = arc_engine_for(agent_id)
+                engine.to_h
+              end
+
+              private
+
+              def arc_engine_for(agent_id)
+                @arc_engines ||= {}
+                @arc_engines[agent_id.to_s] ||= Helpers::ArcEngine.new(agent_id: agent_id.to_s)
+              end
+
+              def stamp_narrative_episode(milestone)
+                narrator = resolve_narrative_identity
+                return unless narrator
+
+                narrator.record_episode(
+                  content:           milestone.description,
+                  episode_type:      :relationship,
+                  emotional_valence: 0.3,
+                  significance:      milestone.significance,
+                  domain:            :relationship,
+                  tags:              ['partner', 'milestone', milestone.type.to_s]
+                )
+              rescue StandardError => e
+                warn "[relationship_arc] narrative stamp failed: #{e.message}"
+              end
+
+              def resolve_narrative_identity
+                return nil unless defined?(Legion::Extensions::Agentic::Self::NarrativeIdentity::Client)
+
+                @narrative_client ||= Legion::Extensions::Agentic::Self::NarrativeIdentity::Client.new
+              rescue StandardError => _e
+                nil
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/relationship_arc/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module RelationshipArc
+          VERSION = '0.1.0'
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/relationship_arc.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'relationship_arc/version'
+require_relative 'relationship_arc/helpers/constants'
+require_relative 'relationship_arc/helpers/milestone'
+require_relative 'relationship_arc/helpers/arc_engine'
+require_relative 'relationship_arc/runners/relationship_arc'
+require_relative 'relationship_arc/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module RelationshipArc
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/version.rb

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Agentic
       module Self
-        VERSION = '0.1.8'
+        VERSION = '0.1.10'
       end
     end
   end

data/lib/legion/extensions/agentic/self.rb

@@ -17,6 +17,7 @@ require_relative 'self/agency'
 require_relative 'self/reflection'
 require_relative 'self/anosognosia'
 require_relative 'self/default_mode_network'
+require_relative 'self/relationship_arc'
 
 module Legion
   module Extensions

data/spec/legion/extensions/agentic/self/personality/helpers/partner_signals_spec.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Self::Personality::Helpers::TraitModel do
+  subject(:model) { described_class.new }
+
+  let(:constants) { Legion::Extensions::Agentic::Self::Personality::Helpers::Constants }
+
+  describe 'PARTNER_SIGNAL_MAP constant' do
+    it 'defines partner_engagement_frequency nudging extraversion positively' do
+      entry = constants::PARTNER_SIGNAL_MAP[:partner_engagement_frequency]
+      expect(entry).to eq([:extraversion, :positive, 0.2])
+    end
+
+    it 'defines partner_direct_address_ratio nudging agreeableness positively' do
+      entry = constants::PARTNER_SIGNAL_MAP[:partner_direct_address_ratio]
+      expect(entry).to eq([:agreeableness, :positive, 0.2])
+    end
+
+    it 'defines partner_content_diversity nudging openness positively' do
+      entry = constants::PARTNER_SIGNAL_MAP[:partner_content_diversity]
+      expect(entry).to eq([:openness, :positive, 0.2])
+    end
+
+    it 'defines partner_consistency nudging conscientiousness positively' do
+      entry = constants::PARTNER_SIGNAL_MAP[:partner_consistency]
+      expect(entry).to eq([:conscientiousness, :positive, 0.2])
+    end
+
+    it 'has all entries with weights of 0.2' do
+      constants::PARTNER_SIGNAL_MAP.each_value do |_trait, _direction, weight|
+        expect(weight).to eq(0.2)
+      end
+    end
+
+    it 'references only valid OCEAN traits' do
+      constants::PARTNER_SIGNAL_MAP.each_value do |trait, _direction, _weight|
+        expect(constants::TRAITS).to include(trait)
+      end
+    end
+  end
+
+  describe '#apply_partner_signals' do
+    it 'nudges extraversion upward when partner_engagement_frequency is high' do
+      baseline = model.trait(:extraversion)
+      model.apply_partner_signals(partner_engagement_frequency: 0.9)
+      expect(model.trait(:extraversion)).to be > baseline
+    end
+
+    it 'nudges agreeableness upward when partner_direct_address_ratio is high' do
+      baseline = model.trait(:agreeableness)
+      model.apply_partner_signals(partner_direct_address_ratio: 0.8)
+      expect(model.trait(:agreeableness)).to be > baseline
+    end
+
+    it 'nudges openness upward when partner_content_diversity is high' do
+      baseline = model.trait(:openness)
+      model.apply_partner_signals(partner_content_diversity: 0.8)
+      expect(model.trait(:openness)).to be > baseline
+    end
+
+    it 'nudges conscientiousness upward when partner_consistency is high' do
+      baseline = model.trait(:conscientiousness)
+      model.apply_partner_signals(partner_consistency: 0.8)
+      expect(model.trait(:conscientiousness)).to be > baseline
+    end
+
+    it 'ignores signals below the minimum threshold' do
+      baseline = model.trait(:extraversion)
+      model.apply_partner_signals(partner_engagement_frequency: 0.1)
+      expect(model.trait(:extraversion)).to eq(baseline)
+    end
+
+    it 'ignores signals exactly at the threshold boundary' do
+      baseline = model.trait(:extraversion)
+      model.apply_partner_signals(partner_engagement_frequency: 0.3)
+      expect(model.trait(:extraversion)).to eq(baseline)
+    end
+
+    it 'applies multiple signals in a single call' do
+      extraversion_before = model.trait(:extraversion)
+      agreeableness_before = model.trait(:agreeableness)
+
+      model.apply_partner_signals(
+        partner_engagement_frequency: 0.9,
+        partner_direct_address_ratio: 0.8
+      )
+
+      expect(model.trait(:extraversion)).to be > extraversion_before
+      expect(model.trait(:agreeableness)).to be > agreeableness_before
+    end
+
+    it 'ignores unrecognized signal keys' do
+      expect { model.apply_partner_signals(unknown_signal: 0.9) }.not_to raise_error
+    end
+
+    it 'does not change observation_count' do
+      model.apply_partner_signals(partner_engagement_frequency: 0.9)
+      expect(model.observation_count).to eq(0)
+    end
+
+    it 'records a history snapshot after applying signals' do
+      model.apply_partner_signals(partner_engagement_frequency: 0.9)
+      expect(model.history.size).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/agentic/self/relationship_arc/helpers/arc_engine_spec.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/agentic/self/relationship_arc/helpers/constants'
+require 'legion/extensions/agentic/self/relationship_arc/helpers/milestone'
+require 'legion/extensions/agentic/self/relationship_arc/helpers/arc_engine'
+
+RSpec.describe Legion::Extensions::Agentic::Self::RelationshipArc::Helpers::ArcEngine do
+  subject(:engine) { described_class.new(agent_id: 'partner-1') }
+
+  describe '#initialize' do
+    it 'starts in formative chapter' do
+      expect(engine.current_chapter).to eq(:formative)
+    end
+
+    it 'starts with empty milestones' do
+      expect(engine.milestones).to be_empty
+    end
+  end
+
+  describe '#add_milestone' do
+    it 'adds a milestone' do
+      engine.add_milestone(type: :first_interaction, description: 'Hello', significance: 0.8)
+      expect(engine.milestones.size).to eq(1)
+    end
+
+    it 'returns the milestone' do
+      ms = engine.add_milestone(type: :first_interaction, description: 'Hello', significance: 0.8)
+      expect(ms).to be_a(Legion::Extensions::Agentic::Self::RelationshipArc::Helpers::Milestone)
+    end
+
+    it 'marks dirty' do
+      engine.add_milestone(type: :first_interaction, description: 'Hello', significance: 0.8)
+      expect(engine).to be_dirty
+    end
+
+    it 'caps at MAX_MILESTONES' do
+      201.times { |i| engine.add_milestone(type: :first_interaction, description: "ms #{i}", significance: 0.1) }
+      expect(engine.milestones.size).to eq(200)
+    end
+  end
+
+  describe '#update_chapter!' do
+    it 'transitions to developing after enough milestones' do
+      4.times { engine.add_milestone(type: :first_interaction, description: 'x', significance: 0.5) }
+      engine.update_chapter!(bond_stage: :forming)
+      expect(engine.current_chapter).to eq(:developing)
+    end
+
+    it 'never regresses' do
+      engine.instance_variable_set(:@current_chapter, :established)
+      engine.update_chapter!(bond_stage: :initial)
+      expect(engine.current_chapter).to eq(:established)
+    end
+  end
+
+  describe '#relationship_health' do
+    it 'computes weighted health score' do
+      health = engine.relationship_health(
+        attachment_strength:       0.8,
+        reciprocity_balance:       0.6,
+        communication_consistency: 0.7
+      )
+      expected = (0.8 * 0.4) + (0.6 * 0.3) + (0.7 * 0.3)
+      expect(health).to be_within(0.01).of(expected)
+    end
+
+    it 'clamps to 0.0..1.0' do
+      health = engine.relationship_health(
+        attachment_strength:       1.5,
+        reciprocity_balance:       1.5,
+        communication_consistency: 1.5
+      )
+      expect(health).to eq(1.0)
+    end
+  end
+
+  describe '#dirty? and #mark_clean!' do
+    it 'starts clean' do
+      expect(engine).not_to be_dirty
+    end
+
+    it 'cleans up' do
+      engine.add_milestone(type: :first_interaction, description: 'x', significance: 0.5)
+      engine.mark_clean!
+      expect(engine).not_to be_dirty
+    end
+  end
+
+  describe '#to_apollo_entries' do
+    before { engine.add_milestone(type: :first_interaction, description: 'Hello', significance: 0.8) }
+
+    it 'returns entries with arc state' do
+      entries = engine.to_apollo_entries
+      expect(entries).to be_an(Array)
+      expect(entries.first[:tags]).to include('bond', 'relationship_arc', 'partner-1')
+    end
+  end
+
+  describe '#from_apollo' do
+    let(:mock_store) { double('apollo_local') }
+
+    it 'restores state from Apollo' do
+      engine.add_milestone(type: :first_interaction, description: 'Hello', significance: 0.8)
+      engine.instance_variable_set(:@current_chapter, :developing)
+      content = engine.send(:serialize, engine.send(:arc_state_hash))
+
+      new_engine = described_class.new(agent_id: 'partner-1')
+      allow(mock_store).to receive(:query)
+        .and_return({ success: true, results: [{ content: content, tags: %w[bond relationship_arc partner-1] }] })
+
+      expect(new_engine.from_apollo(store: mock_store)).to be true
+      expect(new_engine.current_chapter).to eq(:developing)
+      expect(new_engine.milestones.size).to eq(1)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all fields' do
+      h = engine.to_h
+      expect(h).to include(:agent_id, :current_chapter, :milestones, :relationship_health)
+    end
+  end
+end

data/spec/legion/extensions/agentic/self/relationship_arc/helpers/constants_spec.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/agentic/self/relationship_arc/helpers/constants'
+
+RSpec.describe Legion::Extensions::Agentic::Self::RelationshipArc::Helpers::Constants do
+  describe 'CHAPTERS' do
+    it 'defines 4 chapters in order' do
+      expect(described_class::CHAPTERS).to eq(%i[formative developing established deepening])
+    end
+  end
+
+  describe 'MILESTONE_TYPES' do
+    it 'includes expected types' do
+      expect(described_class::MILESTONE_TYPES).to include(:first_interaction, :stage_transition,
+                                                          :prediction_accuracy, :absence_return)
+    end
+  end
+
+  describe 'HEALTH_WEIGHTS' do
+    it 'sums to 1.0' do
+      expect(described_class::HEALTH_WEIGHTS.values.sum).to eq(1.0)
+    end
+  end
+
+  describe 'MAX_MILESTONES' do
+    it 'caps at 200' do
+      expect(described_class::MAX_MILESTONES).to eq(200)
+    end
+  end
+end

data/spec/legion/extensions/agentic/self/relationship_arc/helpers/milestone_spec.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/agentic/self/relationship_arc/helpers/constants'
+require 'legion/extensions/agentic/self/relationship_arc/helpers/milestone'
+
+RSpec.describe Legion::Extensions::Agentic::Self::RelationshipArc::Helpers::Milestone do
+  subject(:milestone) do
+    described_class.new(type: :first_interaction, description: 'First hello', significance: 0.8)
+  end
+
+  describe '#initialize' do
+    it 'sets type' do
+      expect(milestone.type).to eq(:first_interaction)
+    end
+
+    it 'generates a UUID' do
+      expect(milestone.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'clamps significance to 0.0..1.0' do
+      ms = described_class.new(type: :first_interaction, description: 'test', significance: 1.5)
+      expect(ms.significance).to eq(1.0)
+    end
+
+    it 'records timestamp' do
+      expect(milestone.created_at).to be_a(Time)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns complete hash' do
+      h = milestone.to_h
+      expect(h).to include(:id, :type, :description, :significance, :created_at)
+    end
+  end
+
+  describe '.from_h' do
+    it 'round-trips' do
+      restored = described_class.from_h(milestone.to_h)
+      expect(restored.type).to eq(milestone.type)
+      expect(restored.description).to eq(milestone.description)
+      expect(restored.significance).to eq(milestone.significance)
+    end
+  end
+end

data/spec/legion/extensions/agentic/self/relationship_arc/runners/relationship_arc_spec.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/agentic/self/relationship_arc/helpers/constants'
+require 'legion/extensions/agentic/self/relationship_arc/helpers/milestone'
+require 'legion/extensions/agentic/self/relationship_arc/helpers/arc_engine'
+require 'legion/extensions/agentic/self/relationship_arc/runners/relationship_arc'
+
+RSpec.describe Legion::Extensions::Agentic::Self::RelationshipArc::Runners::RelationshipArc do
+  let(:described_module) { described_class }
+  let(:host) { Object.new.extend(described_module) }
+
+  before { host.instance_variable_set(:@arc_engines, nil) }
+
+  describe '#record_milestone' do
+    it 'records a milestone for an agent' do
+      result = host.record_milestone(agent_id: 'p1', type: :first_interaction,
+                                     description: 'Hello', significance: 0.8)
+      expect(result[:success]).to be true
+      expect(result[:milestone][:type]).to eq(:first_interaction)
+    end
+
+    it 'returns error for unknown type' do
+      result = host.record_milestone(agent_id: 'p1', type: :bogus,
+                                     description: 'x', significance: 0.5)
+      expect(result[:success]).to be false
+    end
+
+    it 'calls NarrativeIdentity record_episode when available' do
+      narrator = double('narrator')
+      allow(host).to receive(:resolve_narrative_identity).and_return(narrator)
+      allow(narrator).to receive(:record_episode).and_return({ success: true })
+
+      host.record_milestone(agent_id: 'p1', type: :first_interaction,
+                            description: 'Hello', significance: 0.8)
+      expect(narrator).to have_received(:record_episode)
+        .with(hash_including(episode_type: :relationship, significance: 0.8))
+    end
+  end
+
+  describe '#update_arc' do
+    it 'updates chapter based on attachment state' do
+      3.times do
+        host.record_milestone(agent_id: 'p1', type: :first_interaction,
+                              description: 'x', significance: 0.5)
+      end
+      result = host.update_arc(agent_id: 'p1', attachment_state: { bond_stage: :forming })
+      expect(result[:success]).to be true
+    end
+
+    it 'returns arc summary' do
+      result = host.update_arc(agent_id: 'p1', attachment_state: {})
+      expect(result).to have_key(:current_chapter)
+      expect(result).to have_key(:milestone_count)
+    end
+  end
+
+  describe '#arc_stats' do
+    it 'returns stats' do
+      result = host.arc_stats(agent_id: 'p1')
+      expect(result).to have_key(:current_chapter)
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-agentic-self
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.10
 platform: ruby
 authors:
 - Esity
@@ -309,6 +309,13 @@ files:
 - lib/legion/extensions/agentic/self/reflection/helpers/reflection_store.rb
 - lib/legion/extensions/agentic/self/reflection/runners/reflection.rb
 - lib/legion/extensions/agentic/self/reflection/version.rb
+- lib/legion/extensions/agentic/self/relationship_arc.rb
+- lib/legion/extensions/agentic/self/relationship_arc/client.rb
+- lib/legion/extensions/agentic/self/relationship_arc/helpers/arc_engine.rb
+- lib/legion/extensions/agentic/self/relationship_arc/helpers/constants.rb
+- lib/legion/extensions/agentic/self/relationship_arc/helpers/milestone.rb
+- lib/legion/extensions/agentic/self/relationship_arc/runners/relationship_arc.rb
+- lib/legion/extensions/agentic/self/relationship_arc/version.rb
 - lib/legion/extensions/agentic/self/self_model.rb
 - lib/legion/extensions/agentic/self/self_model/client.rb
 - lib/legion/extensions/agentic/self/self_model/helpers/capability.rb
@@ -406,6 +413,7 @@ files:
 - spec/legion/extensions/agentic/self/narrative_self/runners/narrative_self_spec.rb
 - spec/legion/extensions/agentic/self/personality/client_spec.rb
 - spec/legion/extensions/agentic/self/personality/helpers/constants_spec.rb
+- spec/legion/extensions/agentic/self/personality/helpers/partner_signals_spec.rb
 - spec/legion/extensions/agentic/self/personality/helpers/personality_store_spec.rb
 - spec/legion/extensions/agentic/self/personality/helpers/trait_model_spec.rb
 - spec/legion/extensions/agentic/self/personality/runners/personality_spec.rb
@@ -415,6 +423,10 @@ files:
 - spec/legion/extensions/agentic/self/reflection/helpers/reflection_spec.rb
 - spec/legion/extensions/agentic/self/reflection/helpers/reflection_store_spec.rb
 - spec/legion/extensions/agentic/self/reflection/runners/reflection_spec.rb
+- spec/legion/extensions/agentic/self/relationship_arc/helpers/arc_engine_spec.rb
+- spec/legion/extensions/agentic/self/relationship_arc/helpers/constants_spec.rb
+- spec/legion/extensions/agentic/self/relationship_arc/helpers/milestone_spec.rb
+- spec/legion/extensions/agentic/self/relationship_arc/runners/relationship_arc_spec.rb
 - spec/legion/extensions/agentic/self/self_model/client_spec.rb
 - spec/legion/extensions/agentic/self/self_model/helpers/capability_spec.rb
 - spec/legion/extensions/agentic/self/self_model/helpers/knowledge_domain_spec.rb