lex-agentic-executive 0.1.12 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6805751b790687c13f7522cc607ed5f0a0451c294b4f083f34c2047b0c258b51
-  data.tar.gz: 1b9eba22204723a72da85a8b27236eebb9d2e86882ce964d1190475a31955e4e
+  metadata.gz: aaa8f955fd551b961fd735e5bbf9a0dc33b54134b4d5e2ab1506221687aa3195
+  data.tar.gz: 862042eb5a340dcacce8ec8f2c7cb5f2b9501640ca3d0f39e3307ab69c87d571
 SHA512:
-  metadata.gz: 949b320d2c02ee3bc45fb19d19d4aa7dac0b50517478e3633339405526ee4b52885c0ce351bd1ba05d200cfe011db4bc197124eaae34e106fb0e3b6a84ea315e
-  data.tar.gz: 96dbd48a9b22e4abefd9a0ffc12f88cc59891a674217cd66a7ad9ff2f7d9149bbb8e539d2a90cbc5ef72e9e7aa0fca13dd59be5d0fdbd3b788f96b7bcd78089a
+  metadata.gz: 51cbce9e25c1edb78855eeb7304663855d5f3b4cfc0072b074476f16c230786ea9bd7dfff15c43f10a55558463642218835d3ed3e9f1fcc7a444fbcce1893a74
+  data.tar.gz: 69f0e5e91e4f98c9b2a46d518301674bedf0bedf7ee04adb4a8b5117c450afedf0ebbe8dc2eef73143a6773e96df5bf2a13e6cdf0ab9c4a590b97c4af821559a

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.2.0] - 2026-04-21
+### Added
+- **Autonomous Goal-Setting Pipeline (G1-G5)** — GAIA can now convert intentions into goals, decompose them, dispatch execution, and receive feedback with no human intervention
+- `Volition::Helpers::GoalBridge` — converts volition intentions into proposed goals via GoalManagement (G1)
+- `GoalManagement::Helpers::Decomposer` — autonomous goal decomposition with domain-aware heuristic templates and optional LLM strategy (G2)
+- `GoalManagement::Helpers::TaskDispatcher` — dispatches leaf goals to runners via `Legion::Runner.run` or Client instantiation, with per-domain argument builders and load-order guards (G3)
+- `GoalEngine#reprioritize!` — event-driven priority adjustment with urgency-calibrated boost levels (G4)
+- `GoalManagement::Helpers::FeedbackListener` — subscribes to `Legion::Events` for `task.completed`/`task.failed` and updates goal progress/status (G5)
+- `GoalEngine#update_from_task_event` — thread-safe (Mutex) goal status update from task completion events
+- `Goal#assign_task!` — associates a dispatched task_id and runner_mapping with a goal
+- Auto-activation of proposed leaf goals before dispatch
+- Auto-start of FeedbackListener on GoalManagement::Client initialization
+
 ## [0.1.12] - 2026-04-15
 ### Changed
 - Set `mcp_tools?`, `mcp_tools_deferred?`, and `transport_required?` to `false` — internal cognitive pipeline extension

data/lib/legion/extensions/agentic/executive/goal_management/client.rb

@@ -2,7 +2,11 @@
 
 require 'legion/extensions/agentic/executive/goal_management/helpers/constants'
 require 'legion/extensions/agentic/executive/goal_management/helpers/goal'
+require 'legion/extensions/agentic/executive/goal_management/helpers/goal_persistence'
 require 'legion/extensions/agentic/executive/goal_management/helpers/goal_engine'
+require 'legion/extensions/agentic/executive/goal_management/helpers/task_dispatcher'
+require 'legion/extensions/agentic/executive/goal_management/helpers/feedback_listener'
+require 'legion/extensions/agentic/executive/goal_management/helpers/decomposer'
 require 'legion/extensions/agentic/executive/goal_management/runners/goal_management'
 
 module Legion
@@ -13,13 +17,32 @@ module Legion
           class Client
             include Runners::GoalManagement
 
+            LISTENER_MUTEX = Mutex.new
+            private_constant :LISTENER_MUTEX
+
+            @listener_started = false
+            class << self
+              attr_accessor :listener_started
+            end
+
             def initialize(**)
               @engine = Helpers::GoalEngine.new
+              @feedback_listener = Helpers::FeedbackListener.new(engine: @engine)
+              start_listener_once
             end
 
             private
 
             attr_reader :engine
+
+            def start_listener_once
+              LISTENER_MUTEX.synchronize do
+                return if self.class.listener_started
+
+                @feedback_listener.start_listening
+                self.class.listener_started = true
+              end
+            end
           end
         end
       end

data/lib/legion/extensions/agentic/executive/goal_management/helpers/decomposer.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module GoalManagement
+          module Helpers
+            module Decomposer
+              extend Legion::JSON::Helper if defined?(Legion::JSON::Helper)
+
+              module_function
+
+              def log
+                Legion::Logging
+              end
+
+              DOMAIN_TEMPLATES = {
+                safety:     ->(c) { ["diagnose: #{c}", "implement fix for: #{c}", "verify health after: #{c}"] },
+                cognition:  ->(c) { ["analyze gaps in: #{c}", "design approach for: #{c}", "validate: #{c}"] },
+                perception: ->(c) { ["observe current state of: #{c}", "identify patterns in: #{c}", "calibrate: #{c}"] }
+              }.freeze
+
+              def decompose(goal:, strategy: :heuristic)
+                sub_goals, strategy_used = case strategy
+                                           when :llm
+                                             result = decompose_with_llm(goal)
+                                             result ? [result, :llm] : [decompose_heuristic(goal), :heuristic]
+                                           else
+                                             [decompose_heuristic(goal), :heuristic]
+                                           end
+                log.info "[decomposer] decomposed goal=#{goal[:id]} strategy=#{strategy_used}"
+                { success: true, sub_goals: sub_goals, strategy_used: strategy_used }
+              rescue StandardError => e
+                log.error "Decomposer: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def decompose_heuristic(goal)
+                content = goal[:content].to_s.downcase
+                domain  = (goal[:domain] || :general).to_sym
+                steps   = decompose_by_domain(content, domain) || default_steps(content)
+                steps.map { |step| { content: step, domain: domain, priority: goal[:priority] || 0.5 } }
+              end
+
+              def decompose_with_llm(goal)
+                return nil unless defined?(Legion::LLM) && Legion::LLM.respond_to?(:chat)
+
+                prompt   = build_decomposition_prompt(goal)
+                response = Legion::LLM.chat(
+                  caller: { extension: 'lex-agentic-executive', operation: 'decompose' }
+                ).ask(prompt)
+                parse_sub_goals(response.content, goal[:domain])
+              rescue StandardError => e
+                log.error "Decomposer#decompose_with_llm: #{e.message}"
+                nil
+              end
+
+              def decompose_by_domain(content, domain)
+                template = DOMAIN_TEMPLATES[domain]
+                return nil unless template
+
+                template.call(content)
+              end
+
+              def default_steps(content)
+                [
+                  "analyze current state of: #{content}",
+                  "plan approach for: #{content}",
+                  "execute: #{content}",
+                  "verify result of: #{content}"
+                ]
+              end
+
+              def build_decomposition_prompt(goal)
+                <<~PROMPT
+                  Decompose this goal into 2-5 concrete sub-goals. Return JSON array.
+                  Goal: #{goal[:content]}
+                  Domain: #{goal[:domain]}
+                  Each sub-goal: {"content": "action description", "domain": "#{goal[:domain]}", "priority": 0.0-1.0}
+                  Return ONLY the JSON array, no other text.
+                PROMPT
+              end
+
+              def parse_sub_goals(content, domain)
+                cleaned = content.gsub(/```(?:json)?\s*\n?/, '').strip
+                data = json_load(cleaned)
+                return nil unless data.is_a?(Array) && !data.empty?
+
+                data.map do |sg|
+                  {
+                    content:  sg[:content].to_s,
+                    domain:   (sg[:domain] || domain).to_sym,
+                    priority: (sg[:priority] || 0.5).to_f.clamp(0.0, 1.0)
+                  }
+                end
+              rescue StandardError => e
+                log.error "Decomposer#parse_sub_goals: #{e.message}"
+                nil
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/executive/goal_management/helpers/feedback_listener.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module GoalManagement
+          module Helpers
+            class FeedbackListener
+              def initialize(engine:)
+                @engine    = engine
+                @listening = false
+              end
+
+              def handle_task_event(task_id:, status:, result: nil)
+                update = @engine.update_from_task_event(task_id: task_id, status: status, result: result)
+                goal_id = update[:goal_id] if update.is_a?(Hash)
+                new_status = update[:new_status] if update.is_a?(Hash)
+                unhandled_status = update[:unhandled_status] if update.is_a?(Hash)
+                log.info "[feedback_listener] task event task_id=#{task_id} goal_id=#{goal_id} " \
+                         "task_status=#{status} new_status=#{new_status} unhandled_status=#{unhandled_status}"
+                update
+              end
+
+              def start_listening
+                return if @listening
+                return unless defined?(Legion::Events)
+
+                Legion::Events.on('task.completed') do |event|
+                  handle_task_event(
+                    task_id: event[:task_id],
+                    status:  event[:status] || 'task.completed',
+                    result:  event[:result]
+                  )
+                end
+
+                Legion::Events.on('task.failed') do |event|
+                  handle_task_event(
+                    task_id: event[:task_id],
+                    status:  event[:status] || 'task.failed',
+                    result:  event[:result]
+                  )
+                end
+
+                @listening = true
+              end
+
+              def listening?
+                @listening
+              end
+
+              private
+
+              def log
+                Legion::Logging
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/executive/goal_management/helpers/goal.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'securerandom'
+require 'time'
 
 module Legion
   module Extensions
@@ -13,20 +14,40 @@ module Legion
 
               attr_reader :id, :content, :parent_id, :sub_goal_ids, :status,
                           :priority, :progress, :domain, :deadline,
-                          :created_at, :updated_at
+                          :created_at, :updated_at, :task_id, :runner_mapping
+
+              def self.from_h(hash)
+                goal = allocate
+                goal.instance_variable_set(:@id, hash[:id])
+                goal.instance_variable_set(:@content, hash[:content])
+                goal.instance_variable_set(:@parent_id, hash[:parent_id])
+                goal.instance_variable_set(:@sub_goal_ids, hash[:sub_goal_ids] || [])
+                goal.instance_variable_set(:@status, hash[:status]&.to_sym || :proposed)
+                goal.instance_variable_set(:@priority, hash[:priority]&.to_f || 0.5)
+                goal.instance_variable_set(:@progress, (hash[:progress] || 0.0).to_f)
+                goal.instance_variable_set(:@domain, hash[:domain]&.to_sym || :general)
+                goal.instance_variable_set(:@deadline, hash[:deadline])
+                goal.instance_variable_set(:@task_id, hash[:task_id])
+                goal.instance_variable_set(:@runner_mapping, hash[:runner_mapping])
+                goal.instance_variable_set(:@created_at, hash[:created_at] ? Time.parse(hash[:created_at].to_s) : Time.now)
+                goal.instance_variable_set(:@updated_at, hash[:updated_at] ? Time.parse(hash[:updated_at].to_s) : Time.now)
+                goal
+              end
 
               def initialize(content:, parent_id: nil, domain: :general, priority: DEFAULT_PRIORITY, deadline: nil)
-                @id           = SecureRandom.uuid
-                @content      = content
-                @parent_id    = parent_id
-                @sub_goal_ids = []
-                @status       = :proposed
-                @priority     = priority.clamp(0.0, 1.0)
-                @progress     = 0.0
-                @domain       = domain
-                @deadline     = deadline
-                @created_at   = Time.now
-                @updated_at   = Time.now
+                @id             = SecureRandom.uuid
+                @content        = content
+                @parent_id      = parent_id
+                @sub_goal_ids   = []
+                @status         = :proposed
+                @priority       = priority.clamp(0.0, 1.0)
+                @progress       = 0.0
+                @domain         = domain
+                @deadline       = deadline
+                @created_at     = Time.now
+                @updated_at     = Time.now
+                @task_id        = nil
+                @runner_mapping = nil
               end
 
               def activate!
@@ -88,6 +109,12 @@ module Legion
                 @updated_at = Time.now
               end
 
+              def assign_task!(task_id:, runner_mapping:)
+                @task_id        = task_id
+                @runner_mapping = runner_mapping
+                @updated_at     = Time.now
+              end
+
               def add_sub_goal(goal_id)
                 @sub_goal_ids << goal_id unless @sub_goal_ids.include?(goal_id)
               end
@@ -140,6 +167,8 @@ module Legion
                   overdue:        overdue?,
                   root:           root?,
                   leaf:           leaf?,
+                  task_id:        @task_id,
+                  runner_mapping: @runner_mapping,
                   created_at:     @created_at,
                   updated_at:     @updated_at
                 }

data/lib/legion/extensions/agentic/executive/goal_management/helpers/goal_engine.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'legion/extensions/agentic/executive/goal_management/helpers/goal_persistence'
+
 module Legion
   module Extensions
     module Agentic
@@ -14,6 +16,9 @@ module Legion
               def initialize
                 @goals         = {}
                 @root_goal_ids = []
+                @mutex         = Mutex.new
+                @persistence   = GoalPersistence.new
+                rehydrate_from_cache
               end
 
               def add_goal(content:, parent_id: nil, domain: :general, priority: DEFAULT_PRIORITY, deadline: nil)
@@ -36,7 +41,8 @@ module Legion
                   @root_goal_ids << goal.id
                 end
 
-                Legion::Logging.debug "[goal_management] add_goal id=#{goal.id} domain=#{domain} priority=#{priority.round(2)}"
+                persist_goal(goal)
+                log.debug "[goal_management] add_goal id=#{goal.id} domain=#{domain} priority=#{priority.round(2)}"
                 { success: true, goal: goal.to_h }
               end
 
@@ -55,7 +61,7 @@ module Legion
                 end
 
                 failures = created.reject { |r| r[:success] }
-                Legion::Logging.debug "[goal_management] decompose parent=#{goal_id} created=#{created.size - failures.size} failed=#{failures.size}"
+                log.debug "[goal_management] decompose parent=#{goal_id} created=#{created.size - failures.size} failed=#{failures.size}"
                 { success: true, parent_id: goal_id, created: created, failures: failures.size }
               end
 
@@ -64,7 +70,8 @@ module Legion
                 return { success: false, error: "goal #{goal_id} not found" } unless goal
 
                 activated = goal.activate!
-                Legion::Logging.debug "[goal_management] activate goal=#{goal_id} result=#{activated}"
+                persist_goal(goal) if activated
+                log.debug "[goal_management] activate goal=#{goal_id} result=#{activated}"
                 { success: activated, goal_id: goal_id, status: goal.status }
               end
 
@@ -73,7 +80,8 @@ module Legion
                 return { success: false, error: "goal #{goal_id} not found" } unless goal
 
                 completed = goal.complete!
-                Legion::Logging.debug "[goal_management] complete goal=#{goal_id} result=#{completed}"
+                persist_goal(goal) if completed
+                log.debug "[goal_management] complete goal=#{goal_id} result=#{completed}"
                 { success: completed, goal_id: goal_id, status: goal.status }
               end
 
@@ -82,7 +90,8 @@ module Legion
                 return { success: false, error: "goal #{goal_id} not found" } unless goal
 
                 abandoned = goal.abandon!
-                Legion::Logging.debug "[goal_management] abandon goal=#{goal_id} result=#{abandoned}"
+                persist_goal(goal) if abandoned
+                log.debug "[goal_management] abandon goal=#{goal_id} result=#{abandoned}"
                 { success: abandoned, goal_id: goal_id, status: goal.status }
               end
 
@@ -91,7 +100,8 @@ module Legion
                 return { success: false, error: "goal #{goal_id} not found" } unless goal
 
                 blocked = goal.block!
-                Legion::Logging.debug "[goal_management] block goal=#{goal_id} result=#{blocked}"
+                persist_goal(goal) if blocked
+                log.debug "[goal_management] block goal=#{goal_id} result=#{blocked}"
                 { success: blocked, goal_id: goal_id, status: goal.status }
               end
 
@@ -100,7 +110,8 @@ module Legion
                 return { success: false, error: "goal #{goal_id} not found" } unless goal
 
                 unblocked = goal.unblock!
-                Legion::Logging.debug "[goal_management] unblock goal=#{goal_id} result=#{unblocked}"
+                persist_goal(goal) if unblocked
+                log.debug "[goal_management] unblock goal=#{goal_id} result=#{unblocked}"
                 { success: unblocked, goal_id: goal_id, status: goal.status }
               end
 
@@ -110,7 +121,8 @@ module Legion
 
                 goal.advance_progress!(amount)
                 propagate_progress_to_parent(goal_id)
-                Legion::Logging.debug "[goal_management] advance_progress goal=#{goal_id} progress=#{goal.progress.round(2)}"
+                persist_goal(goal)
+                log.debug "[goal_management] advance_progress goal=#{goal_id} progress=#{goal.progress.round(2)}"
                 { success: true, goal_id: goal_id, progress: goal.progress }
               end
 
@@ -131,7 +143,7 @@ module Legion
                 conflicts = raw.select { |c| c[:conflict_score] > 0.0 }
                                .sort_by { |c| -c[:conflict_score] }
 
-                Legion::Logging.debug "[goal_management] detect_conflicts goal=#{goal_id} conflicts=#{conflicts.size}"
+                log.debug "[goal_management] detect_conflicts goal=#{goal_id} conflicts=#{conflicts.size}"
                 { success: true, goal_id: goal_id, conflicts: conflicts, count: conflicts.size }
               end
 
@@ -163,13 +175,67 @@ module Legion
                 active.sort_by { |g| -g.priority }.first(limit)
               end
 
+              URGENCY_BOOST = { critical: 0.3, high: 0.2, moderate: 0.1, low: 0.05 }.freeze
+
+              def reprioritize!(signal:)
+                domain = signal[:domain]&.to_sym
+                boost = URGENCY_BOOST[signal[:urgency]&.to_sym] || 0.05
+                adjusted = 0
+
+                @goals.each_value do |goal|
+                  next unless goal.domain == domain && goal.active?
+
+                  times = (boost / Constants::PRIORITY_BOOST).ceil
+                  times.times { goal.boost_priority! }
+                  persist_goal(goal)
+                  adjusted += 1
+                end
+
+                log.info "[goal_engine] reprioritize! domain=#{domain} boost=#{boost} adjusted=#{adjusted}"
+                { adjusted: adjusted, domain: domain, boost: boost }
+              end
+
+              def assign_task_to_goal(goal_id:, task_id:, runner_mapping:)
+                goal = @goals[goal_id]
+                return { success: false, error: "goal #{goal_id} not found" } unless goal
+
+                goal.assign_task!(task_id: task_id, runner_mapping: runner_mapping)
+                persist_goal(goal)
+                log.debug "[goal_management] assign_task goal=#{goal_id} task_id=#{task_id}"
+                { success: true, goal_id: goal_id, task_id: task_id }
+              end
+
               def decay_all_priorities!
                 inactive = @goals.values.reject { |g| g.status == :active }
                 inactive.each(&:decay_priority!)
-                Legion::Logging.debug "[goal_management] decay_all inactive=#{inactive.size}"
+                log.debug "[goal_management] decay_all inactive=#{inactive.size}"
                 { decayed: inactive.size }
               end
 
+              def update_from_task_event(task_id:, status:, result: nil)
+                @mutex.synchronize do
+                  goal = @goals.values.find { |g| g.task_id == task_id }
+                  return { found: false } unless goal
+
+                  case status
+                  when 'task.completed'
+                    goal.advance_progress!(1.0 - goal.progress)
+                    goal.complete! if goal.progress >= Constants::PROGRESS_THRESHOLD
+                    propagate_progress_to_parent(goal.id) if goal.parent_id
+                    persist_goal(goal)
+                    log.info "[goal_engine] goal status change goal=#{goal.id} transition=completed"
+                    { found: true, goal_id: goal.id, new_status: goal.status, progress: goal.progress }
+                  when 'task.exception', 'task.failed'
+                    goal.block!
+                    persist_goal(goal)
+                    log.info "[goal_engine] goal status change goal=#{goal.id} transition=blocked"
+                    { found: true, goal_id: goal.id, new_status: :blocked, error: result }
+                  else
+                    { found: true, goal_id: goal.id, unhandled_status: status }
+                  end
+                end
+              end
+
               def goal_report
                 statuses = GOAL_STATUSES.to_h { |s| [s, 0] }
                 @goals.each_value { |g| statuses[g.status] += 1 }
@@ -192,6 +258,28 @@ module Legion
 
               private
 
+              def log
+                Legion::Logging
+              end
+
+              def persist_goal(goal)
+                @persistence.save_goal(goal.to_h)
+              end
+
+              def rehydrate_from_cache
+                cached = @persistence.load_all
+                return if cached.empty?
+
+                cached.each do |id, goal_hash|
+                  goal = Goal.from_h(goal_hash)
+                  @goals[id] = goal
+                  @root_goal_ids << id if goal.root?
+                end
+                log.info "[goal_engine] rehydrated #{cached.size} goals from cache"
+              rescue StandardError => e
+                log.error "GoalEngine: rehydration failed: #{e.message}"
+              end
+
               def depth_of(goal_id, current_depth = 0)
                 goal = @goals[goal_id]
                 return current_depth unless goal&.parent_id
@@ -212,6 +300,7 @@ module Legion
                 avg = children.sum(&:progress).round(10) / children.size
                 parent.instance_variable_set(:@progress, avg.round(10))
                 parent.instance_variable_set(:@updated_at, Time.now)
+                persist_goal(parent)
                 propagate_progress_to_parent(goal.parent_id)
               end
 

data/lib/legion/extensions/agentic/executive/goal_management/helpers/goal_persistence.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module GoalManagement
+          module Helpers
+            class GoalPersistence
+              include Legion::Cache::Helper if defined?(Legion::Cache::Helper)
+              include Legion::JSON::Helper if defined?(Legion::JSON::Helper)
+
+              GOAL_TTL = 86_400
+              INDEX_KEY_SUFFIX = ':index'
+              BRIDGE_KEY_SUFFIX = ':bridge'
+
+              def initialize(namespace: 'legion_goals')
+                @namespace = namespace
+              end
+
+              def save_goal(goal_hash)
+                return false unless persistence_available?
+
+                cache_set(goal_key(goal_hash[:id]), json_dump(goal_hash), ttl: GOAL_TTL)
+                update_index(goal_hash[:id], :add)
+                true
+              rescue StandardError => e
+                log.error "[goal_persistence] save_goal failed: #{e.message}"
+                false
+              end
+
+              def load_goal(id)
+                return nil unless persistence_available?
+
+                raw = cache_get(goal_key(id))
+                return nil unless raw
+
+                json_load(raw)
+              rescue StandardError => e
+                log.error "[goal_persistence] load_goal failed: #{e.message}"
+                nil
+              end
+
+              def delete_goal(id)
+                return false unless persistence_available?
+
+                cache_delete(goal_key(id))
+                update_index(id, :remove)
+                true
+              rescue StandardError => e
+                log.error "[goal_persistence] delete_goal failed: #{e.message}"
+                false
+              end
+
+              def save_all(goals_hash)
+                return false unless persistence_available?
+
+                goals_hash.each_value { |g| save_goal(g.is_a?(Hash) ? g : g.to_h) }
+                true
+              rescue StandardError => e
+                log.error "[goal_persistence] save_all failed: #{e.message}"
+                false
+              end
+
+              def load_all
+                return {} unless persistence_available?
+
+                ids = load_index
+                return {} if ids.empty?
+
+                goals = ids.each_with_object({}) do |id, result|
+                  goal = load_goal(id)
+                  result[id] = goal if goal
+                end
+                log.info "[goal_persistence] rehydrated #{goals.size} goals from cache"
+                goals
+              rescue StandardError => e
+                log.error "[goal_persistence] load_all failed: #{e.message}"
+                {}
+              end
+
+              def save_bridge_state(bridge_hash)
+                return false unless persistence_available?
+
+                cache_set(bridge_key, json_dump(bridge_hash), ttl: GOAL_TTL)
+                true
+              rescue StandardError => e
+                log.error "[goal_persistence] save_bridge_state failed: #{e.message}"
+                false
+              end
+
+              def load_bridge_state
+                return {} unless persistence_available?
+
+                raw = cache_get(bridge_key)
+                return {} unless raw
+
+                json_load(raw)
+              rescue StandardError => e
+                log.error "[goal_persistence] load_bridge_state failed: #{e.message}"
+                {}
+              end
+
+              private
+
+              def log
+                Legion::Logging
+              end
+
+              def persistence_available?
+                respond_to?(:cache_connected?) && cache_connected?
+              rescue StandardError => e
+                log.debug "[goal_persistence] cache not available: #{e.message}"
+                false
+              end
+
+              def goal_key(id) = "#{@namespace}:goal:#{id}"
+              def index_key = "#{@namespace}#{INDEX_KEY_SUFFIX}"
+              def bridge_key = "#{@namespace}#{BRIDGE_KEY_SUFFIX}"
+
+              def update_index(id, operation)
+                ids = load_index
+                case operation
+                when :add    then ids << id unless ids.include?(id)
+                when :remove then ids.delete(id)
+                end
+                cache_set(index_key, json_dump(ids), ttl: GOAL_TTL)
+              end
+
+              def load_index
+                raw = cache_get(index_key)
+                return [] unless raw
+
+                json_load(raw)
+              rescue StandardError => e
+                log.error "[goal_persistence] load_index failed: #{e.message}"
+                []
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end