lex-prospective-memory 0.1.0

data/spec/legion/extensions/prospective_memory/helpers/intention_spec.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::ProspectiveMemory::Helpers::Intention do
+  subject(:intention) do
+    described_class.new(
+      description:       'send follow-up email',
+      trigger_type:      :time_based,
+      trigger_condition: { at: '2026-04-01T09:00:00Z' },
+      urgency:           0.6,
+      domain:            'communication'
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(intention.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets status to :pending' do
+      expect(intention.status).to eq(:pending)
+    end
+
+    it 'clamps urgency to 0.0-1.0' do
+      over = described_class.new(description: 'x', trigger_type: :time_based, trigger_condition: {}, urgency: 1.5)
+      expect(over.urgency).to eq(1.0)
+    end
+
+    it 'clamps urgency below 0.0' do
+      under = described_class.new(description: 'x', trigger_type: :time_based, trigger_condition: {}, urgency: -0.3)
+      expect(under.urgency).to eq(0.0)
+    end
+
+    it 'defaults urgency to DEFAULT_URGENCY' do
+      default_intention = described_class.new(description: 'x', trigger_type: :time_based, trigger_condition: {})
+      expect(default_intention.urgency).to eq(Legion::Extensions::ProspectiveMemory::Helpers::Constants::DEFAULT_URGENCY)
+    end
+
+    it 'sets created_at to a UTC time' do
+      expect(intention.created_at).to be_a(Time)
+    end
+
+    it 'leaves triggered_at nil initially' do
+      expect(intention.triggered_at).to be_nil
+    end
+
+    it 'leaves executed_at nil initially' do
+      expect(intention.executed_at).to be_nil
+    end
+  end
+
+  describe '#monitor!' do
+    it 'sets status to :monitoring' do
+      intention.monitor!
+      expect(intention.status).to eq(:monitoring)
+    end
+  end
+
+  describe '#trigger!' do
+    it 'sets status to :triggered' do
+      intention.trigger!
+      expect(intention.status).to eq(:triggered)
+    end
+
+    it 'sets triggered_at' do
+      intention.trigger!
+      expect(intention.triggered_at).to be_a(Time)
+    end
+  end
+
+  describe '#execute!' do
+    it 'sets status to :executed' do
+      intention.execute!
+      expect(intention.status).to eq(:executed)
+    end
+
+    it 'sets executed_at' do
+      intention.execute!
+      expect(intention.executed_at).to be_a(Time)
+    end
+  end
+
+  describe '#expire!' do
+    it 'sets status to :expired' do
+      intention.expire!
+      expect(intention.status).to eq(:expired)
+    end
+  end
+
+  describe '#cancel!' do
+    it 'sets status to :cancelled' do
+      intention.cancel!
+      expect(intention.status).to eq(:cancelled)
+    end
+  end
+
+  describe '#expired?' do
+    it 'returns false when expires_at is nil' do
+      expect(intention.expired?).to be false
+    end
+
+    it 'returns false when expires_at is in the future' do
+      future = described_class.new(
+        description: 'x', trigger_type: :time_based, trigger_condition: {},
+        expires_at: Time.now.utc + 3600
+      )
+      expect(future.expired?).to be false
+    end
+
+    it 'returns true when expires_at is in the past' do
+      past = described_class.new(
+        description: 'x', trigger_type: :time_based, trigger_condition: {},
+        expires_at: Time.now.utc - 1
+      )
+      expect(past.expired?).to be true
+    end
+  end
+
+  describe '#boost_urgency!' do
+    it 'increases urgency by URGENCY_BOOST by default' do
+      original = intention.urgency
+      intention.boost_urgency!
+      expect(intention.urgency).to eq((original + Legion::Extensions::ProspectiveMemory::Helpers::Constants::URGENCY_BOOST).clamp(0.0, 1.0).round(10))
+    end
+
+    it 'accepts a custom amount' do
+      intention.boost_urgency!(amount: 0.2)
+      expect(intention.urgency).to be > 0.6
+    end
+
+    it 'does not exceed 1.0' do
+      high = described_class.new(description: 'x', trigger_type: :time_based, trigger_condition: {}, urgency: 0.95)
+      high.boost_urgency!(amount: 0.5)
+      expect(high.urgency).to eq(1.0)
+    end
+  end
+
+  describe '#decay_urgency!' do
+    it 'decreases urgency by URGENCY_DECAY' do
+      original = intention.urgency
+      intention.decay_urgency!
+      expect(intention.urgency).to be < original
+    end
+
+    it 'does not go below 0.0' do
+      low = described_class.new(description: 'x', trigger_type: :time_based, trigger_condition: {}, urgency: 0.005)
+      low.decay_urgency!
+      expect(low.urgency).to eq(0.0)
+    end
+
+    it 'rounds to 10 decimal places' do
+      intention.decay_urgency!
+      expect(intention.urgency.to_s.split('.').last.length).to be <= 10
+    end
+  end
+
+  describe '#urgency_label' do
+    it 'returns :critical for urgency >= 0.8' do
+      high = described_class.new(description: 'x', trigger_type: :time_based, trigger_condition: {}, urgency: 0.9)
+      expect(high.urgency_label).to eq(:critical)
+    end
+
+    it 'returns :high for urgency in 0.6...0.8' do
+      expect(intention.urgency_label).to eq(:high)
+    end
+
+    it 'returns :moderate for urgency in 0.4...0.6' do
+      mid = described_class.new(description: 'x', trigger_type: :time_based, trigger_condition: {}, urgency: 0.5)
+      expect(mid.urgency_label).to eq(:moderate)
+    end
+
+    it 'returns :low for urgency in 0.2...0.4' do
+      low = described_class.new(description: 'x', trigger_type: :time_based, trigger_condition: {}, urgency: 0.3)
+      expect(low.urgency_label).to eq(:low)
+    end
+
+    it 'returns :deferred for urgency < 0.2' do
+      very_low = described_class.new(description: 'x', trigger_type: :time_based, trigger_condition: {}, urgency: 0.1)
+      expect(very_low.urgency_label).to eq(:deferred)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all fields' do
+      h = intention.to_h
+      expect(h[:id]).to eq(intention.id)
+      expect(h[:description]).to eq('send follow-up email')
+      expect(h[:trigger_type]).to eq(:time_based)
+      expect(h[:status]).to eq(:pending)
+      expect(h[:domain]).to eq('communication')
+      expect(h[:urgency_label]).to eq(:high)
+    end
+  end
+end

data/spec/legion/extensions/prospective_memory/helpers/prospective_engine_spec.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::ProspectiveMemory::Helpers::ProspectiveEngine do
+  subject(:engine) { described_class.new }
+
+  let(:basic_params) do
+    {
+      description:       'check in with team',
+      trigger_type:      :event_based,
+      trigger_condition: { event: 'sprint_end' },
+      domain:            'work'
+    }
+  end
+
+  def make_intention(**overrides)
+    engine.create_intention(**basic_params, **overrides)
+  end
+
+  describe '#create_intention' do
+    it 'returns an Intention object' do
+      expect(make_intention).to be_a(Legion::Extensions::ProspectiveMemory::Helpers::Intention)
+    end
+
+    it 'stores the intention' do
+      intention = make_intention
+      expect(engine.intentions[intention.id]).to eq(intention)
+    end
+
+    it 'creates intention with :pending status' do
+      expect(make_intention.status).to eq(:pending)
+    end
+
+    it 'respects custom urgency' do
+      intention = make_intention(urgency: 0.8)
+      expect(intention.urgency).to eq(0.8)
+    end
+
+    it 'evicts oldest when at capacity' do
+      stub_const('Legion::Extensions::ProspectiveMemory::Helpers::Constants::MAX_INTENTIONS', 2)
+      first = make_intention
+      _second = make_intention
+      _third  = make_intention
+      expect(engine.intentions.key?(first.id)).to be false
+      expect(engine.intentions.size).to eq(2)
+    end
+  end
+
+  describe '#monitor_intention' do
+    it 'sets status to :monitoring' do
+      intention = make_intention
+      engine.monitor_intention(intention_id: intention.id)
+      expect(intention.status).to eq(:monitoring)
+    end
+
+    it 'returns nil for unknown id' do
+      expect(engine.monitor_intention(intention_id: 'nope')).to be_nil
+    end
+  end
+
+  describe '#trigger_intention' do
+    it 'sets status to :triggered' do
+      intention = make_intention
+      engine.trigger_intention(intention_id: intention.id)
+      expect(intention.status).to eq(:triggered)
+    end
+
+    it 'returns nil for unknown id' do
+      expect(engine.trigger_intention(intention_id: 'nope')).to be_nil
+    end
+  end
+
+  describe '#execute_intention' do
+    it 'sets status to :executed' do
+      intention = make_intention
+      engine.execute_intention(intention_id: intention.id)
+      expect(intention.status).to eq(:executed)
+    end
+  end
+
+  describe '#cancel_intention' do
+    it 'sets status to :cancelled' do
+      intention = make_intention
+      engine.cancel_intention(intention_id: intention.id)
+      expect(intention.status).to eq(:cancelled)
+    end
+  end
+
+  describe '#check_expirations' do
+    it 'expires overdue pending intentions' do
+      expired_intention = make_intention(expires_at: Time.now.utc - 1)
+      engine.check_expirations
+      expect(expired_intention.status).to eq(:expired)
+    end
+
+    it 'expires overdue monitoring intentions' do
+      intention = make_intention(expires_at: Time.now.utc - 1)
+      engine.monitor_intention(intention_id: intention.id)
+      engine.check_expirations
+      expect(intention.status).to eq(:expired)
+    end
+
+    it 'does not expire future intentions' do
+      future = make_intention(expires_at: Time.now.utc + 3600)
+      engine.check_expirations
+      expect(future.status).to eq(:pending)
+    end
+
+    it 'does not expire already-executed intentions' do
+      intention = make_intention(expires_at: Time.now.utc - 1)
+      engine.execute_intention(intention_id: intention.id)
+      engine.check_expirations
+      expect(intention.status).to eq(:executed)
+    end
+
+    it 'returns the count of expired intentions' do
+      make_intention(expires_at: Time.now.utc - 1)
+      make_intention(expires_at: Time.now.utc - 1)
+      make_intention(expires_at: Time.now.utc + 3600)
+      expect(engine.check_expirations).to eq(2)
+    end
+  end
+
+  describe '#pending_intentions' do
+    it 'returns only pending intentions' do
+      i1 = make_intention
+      i2 = make_intention
+      engine.monitor_intention(intention_id: i2.id)
+      expect(engine.pending_intentions).to contain_exactly(i1)
+    end
+  end
+
+  describe '#monitoring_intentions' do
+    it 'returns only monitoring intentions' do
+      intention = make_intention
+      engine.monitor_intention(intention_id: intention.id)
+      expect(engine.monitoring_intentions).to contain_exactly(intention)
+    end
+  end
+
+  describe '#triggered_intentions' do
+    it 'returns only triggered intentions' do
+      intention = make_intention
+      engine.trigger_intention(intention_id: intention.id)
+      expect(engine.triggered_intentions).to contain_exactly(intention)
+    end
+  end
+
+  describe '#by_domain' do
+    it 'filters by domain' do
+      work_intention = make_intention(domain: 'work')
+      make_intention(domain: 'personal')
+      results = engine.by_domain(domain: 'work')
+      expect(results).to contain_exactly(work_intention)
+    end
+  end
+
+  describe '#by_urgency' do
+    it 'returns intentions at or above min_urgency' do
+      high   = make_intention(urgency: 0.8)
+      _low   = make_intention(urgency: 0.3)
+      result = engine.by_urgency(min_urgency: 0.5)
+      expect(result).to contain_exactly(high)
+    end
+  end
+
+  describe '#most_urgent' do
+    it 'returns intentions sorted by descending urgency' do
+      i1 = make_intention(urgency: 0.9)
+      i2 = make_intention(urgency: 0.4)
+      i3 = make_intention(urgency: 0.7)
+      result = engine.most_urgent(limit: 3)
+      expect(result).to eq([i1, i3, i2])
+    end
+
+    it 'excludes executed/expired/cancelled intentions' do
+      executed = make_intention(urgency: 0.9)
+      active   = make_intention(urgency: 0.5)
+      engine.execute_intention(intention_id: executed.id)
+      result = engine.most_urgent(limit: 5)
+      expect(result).to contain_exactly(active)
+    end
+
+    it 'respects the limit parameter' do
+      5.times { make_intention }
+      expect(engine.most_urgent(limit: 3).size).to eq(3)
+    end
+  end
+
+  describe '#decay_all_urgency' do
+    it 'decreases urgency of pending intentions' do
+      intention = make_intention(urgency: 0.5)
+      engine.decay_all_urgency
+      expect(intention.urgency).to be < 0.5
+    end
+
+    it 'decreases urgency of monitoring intentions' do
+      intention = make_intention(urgency: 0.5)
+      engine.monitor_intention(intention_id: intention.id)
+      engine.decay_all_urgency
+      expect(intention.urgency).to be < 0.5
+    end
+
+    it 'does not decay executed intentions' do
+      intention = make_intention(urgency: 0.5)
+      engine.execute_intention(intention_id: intention.id)
+      engine.decay_all_urgency
+      expect(intention.urgency).to eq(0.5)
+    end
+  end
+
+  describe '#execution_rate' do
+    it 'returns 0.0 with no terminal intentions' do
+      make_intention
+      expect(engine.execution_rate).to eq(0.0)
+    end
+
+    it 'computes fraction of executed vs total terminal' do
+      i1 = make_intention
+      i2 = make_intention
+      i3 = make_intention
+      engine.execute_intention(intention_id: i1.id)
+      engine.execute_intention(intention_id: i2.id)
+      engine.cancel_intention(intention_id: i3.id)
+      expect(engine.execution_rate).to be_within(0.001).of(2.0 / 3.0)
+    end
+  end
+
+  describe '#intention_report' do
+    it 'returns a hash with total, by_status, execution_rate, most_urgent' do
+      make_intention
+      report = engine.intention_report
+      expect(report[:total]).to eq(1)
+      expect(report[:by_status]).to be_a(Hash)
+      expect(report[:execution_rate]).to be_a(Float)
+      expect(report[:most_urgent]).to be_an(Array)
+    end
+
+    it 'includes all status types in by_status' do
+      report = engine.intention_report
+      Legion::Extensions::ProspectiveMemory::Helpers::Constants::STATUS_TYPES.each do |status|
+        expect(report[:by_status]).to have_key(status)
+      end
+    end
+  end
+
+  describe '#to_h' do
+    it 'serializes the engine state' do
+      make_intention
+      h = engine.to_h
+      expect(h[:intention_count]).to eq(1)
+      expect(h[:intentions]).to be_a(Hash)
+      expect(h[:execution_rate]).to be_a(Float)
+    end
+  end
+end

data/spec/legion/extensions/prospective_memory/runners/prospective_memory_spec.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/prospective_memory/client'
+
+RSpec.describe Legion::Extensions::ProspectiveMemory::Runners::ProspectiveMemory do
+  let(:client) { Legion::Extensions::ProspectiveMemory::Client.new }
+
+  let(:base_params) do
+    {
+      description:       'review open pull requests',
+      trigger_type:      :activity_based,
+      trigger_condition: { activity: 'commit_pushed' }
+    }
+  end
+
+  def create(**overrides)
+    client.create_intention(**base_params, **overrides)
+  end
+
+  describe '#create_intention' do
+    it 'creates an intention and returns a hash with :created true' do
+      result = create
+      expect(result[:created]).to be true
+      expect(result[:intention]).to be_a(Hash)
+      expect(result[:intention][:id]).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'rejects invalid trigger_type' do
+      result = create(trigger_type: :bogus)
+      expect(result[:error]).to eq(:invalid_trigger_type)
+      expect(result[:valid_types]).to include(:time_based)
+    end
+
+    it 'stores urgency on the intention' do
+      result = create(urgency: 0.75)
+      expect(result[:intention][:urgency]).to eq(0.75)
+    end
+
+    it 'stores domain on the intention' do
+      result = create(domain: 'engineering')
+      expect(result[:intention][:domain]).to eq('engineering')
+    end
+
+    it 'sets status to :pending' do
+      result = create
+      expect(result[:intention][:status]).to eq(:pending)
+    end
+  end
+
+  describe '#monitor_intention' do
+    it 'transitions status to :monitoring' do
+      created = create
+      result  = client.monitor_intention(intention_id: created[:intention][:id])
+      expect(result[:updated]).to be true
+      expect(result[:intention][:status]).to eq(:monitoring)
+    end
+
+    it 'returns not_found for unknown id' do
+      result = client.monitor_intention(intention_id: 'nonexistent')
+      expect(result[:updated]).to be false
+      expect(result[:reason]).to eq(:not_found)
+    end
+  end
+
+  describe '#trigger_intention' do
+    it 'transitions status to :triggered' do
+      created = create
+      result  = client.trigger_intention(intention_id: created[:intention][:id])
+      expect(result[:updated]).to be true
+      expect(result[:intention][:status]).to eq(:triggered)
+    end
+
+    it 'records triggered_at timestamp' do
+      created = create
+      result  = client.trigger_intention(intention_id: created[:intention][:id])
+      expect(result[:intention][:triggered_at]).not_to be_nil
+    end
+  end
+
+  describe '#execute_intention' do
+    it 'transitions status to :executed' do
+      created = create
+      result  = client.execute_intention(intention_id: created[:intention][:id])
+      expect(result[:updated]).to be true
+      expect(result[:intention][:status]).to eq(:executed)
+    end
+
+    it 'records executed_at timestamp' do
+      created = create
+      result  = client.execute_intention(intention_id: created[:intention][:id])
+      expect(result[:intention][:executed_at]).not_to be_nil
+    end
+
+    it 'returns not_found for unknown id' do
+      result = client.execute_intention(intention_id: 'nope')
+      expect(result[:updated]).to be false
+    end
+  end
+
+  describe '#cancel_intention' do
+    it 'transitions status to :cancelled' do
+      created = create
+      result  = client.cancel_intention(intention_id: created[:intention][:id])
+      expect(result[:updated]).to be true
+      expect(result[:intention][:status]).to eq(:cancelled)
+    end
+  end
+
+  describe '#check_expirations' do
+    it 'returns expired_count' do
+      client.create_intention(
+        description:       'expired',
+        trigger_type:      :time_based,
+        trigger_condition: {},
+        expires_at:        Time.now.utc - 1
+      )
+      result = client.check_expirations
+      expect(result[:expired_count]).to eq(1)
+    end
+  end
+
+  describe '#pending_intentions' do
+    it 'lists pending intentions with count' do
+      create
+      create
+      result = client.pending_intentions
+      expect(result[:count]).to eq(2)
+      expect(result[:intentions]).to all(include(status: :pending))
+    end
+  end
+
+  describe '#monitoring_intentions' do
+    it 'lists monitoring intentions' do
+      created = create
+      client.monitor_intention(intention_id: created[:intention][:id])
+      result = client.monitoring_intentions
+      expect(result[:count]).to eq(1)
+      expect(result[:intentions].first[:status]).to eq(:monitoring)
+    end
+  end
+
+  describe '#triggered_intentions' do
+    it 'lists triggered intentions' do
+      created = create
+      client.trigger_intention(intention_id: created[:intention][:id])
+      result = client.triggered_intentions
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#intentions_by_domain' do
+    it 'filters by domain' do
+      create(domain: 'ops')
+      create(domain: 'dev')
+      result = client.intentions_by_domain(domain: 'ops')
+      expect(result[:count]).to eq(1)
+      expect(result[:domain]).to eq('ops')
+    end
+  end
+
+  describe '#intentions_by_urgency' do
+    it 'filters by min_urgency' do
+      create(urgency: 0.9)
+      create(urgency: 0.2)
+      result = client.intentions_by_urgency(min_urgency: 0.5)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#most_urgent_intentions' do
+    it 'returns sorted by descending urgency' do
+      create(urgency: 0.3)
+      create(urgency: 0.8)
+      result = client.most_urgent_intentions(limit: 5)
+      urgencies = result[:intentions].map { |i| i[:urgency] }
+      expect(urgencies).to eq(urgencies.sort.reverse)
+    end
+
+    it 'respects the limit' do
+      3.times { create }
+      result = client.most_urgent_intentions(limit: 2)
+      expect(result[:count]).to eq(2)
+    end
+  end
+
+  describe '#decay_urgency' do
+    it 'returns decayed: true' do
+      create
+      result = client.decay_urgency
+      expect(result[:decayed]).to be true
+    end
+  end
+
+  describe '#execution_rate' do
+    it 'returns a float execution_rate' do
+      result = client.execution_rate
+      expect(result[:execution_rate]).to be_a(Float)
+    end
+
+    it 'computes rate after executions' do
+      c1 = create
+      c2 = create
+      client.execute_intention(intention_id: c1[:intention][:id])
+      client.cancel_intention(intention_id: c2[:intention][:id])
+      result = client.execution_rate
+      expect(result[:execution_rate]).to be_within(0.001).of(0.5)
+    end
+  end
+
+  describe '#intention_report' do
+    it 'returns total, by_status, execution_rate, most_urgent' do
+      create
+      report = client.intention_report
+      expect(report[:total]).to be >= 1
+      expect(report[:by_status]).to be_a(Hash)
+      expect(report[:execution_rate]).to be_a(Float)
+      expect(report[:most_urgent]).to be_an(Array)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+module Legion
+  module Logging
+    def self.debug(_msg); end
+    def self.info(_msg); end
+    def self.warn(_msg); end
+    def self.error(_msg); end
+  end
+end
+
+require 'legion/extensions/prospective_memory'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end