lex-goal-management

Hierarchical goal lifecycle management for LegionIO agents. Part of the LegionIO cognitive architecture extension ecosystem (LEX).

What It Does

lex-goal-management gives an agent a structured goal system: goals can be decomposed into sub-goal trees, tracked through a lifecycle (proposed -> active -> completed/abandoned/blocked), assigned priorities and deadlines, and monitored for conflicts with competing goals in the same domain.

Key capabilities:

Goal tree: unlimited nesting up to depth 10, progress propagates automatically from children to parents
State machine: proposed, active, blocked, completed, abandoned transitions with guards
Priority system: floating-point 0..1 priority with labels (trivial, low, moderate, high, critical), boost/decay operations
Deadline tracking: flag overdue goals based on wall-clock time
Conflict detection: identify same-domain goals competing for priority
Auto-pruning: oldest completed/abandoned goals are removed when the 500-goal cap is reached

Installation

Add to your Gemfile:

gem 'lex-goal-management'

Or install directly:

gem install lex-goal-management

Usage

require 'legion/extensions/goal_management'

client = Legion::Extensions::GoalManagement::Client.new

# Add a top-level goal
result = client.add_goal(content: 'Improve response latency', domain: :performance, priority: 0.7)
goal_id = result[:goal][:id]

# Decompose into sub-goals
client.decompose_goal(goal_id: goal_id, sub_goals: [
  { content: 'Profile hot paths', domain: :performance },
  { content: 'Cache frequent queries', domain: :performance }
])

# Move through lifecycle
client.activate_goal(goal_id: goal_id)
client.advance_goal_progress(goal_id: goal_id, amount: 0.5)

# Inspect state
client.list_active_goals
client.highest_priority_goals(limit: 3)
client.goal_status

# Detect conflicts
client.detect_goal_conflicts(goal_id: goal_id)

# Complete or abandon
client.complete_goal(goal_id: goal_id)

Runner Methods

Method	Description
`add_goal`	Create a new goal, optionally under a parent
`decompose_goal`	Batch-create sub-goals under a parent
`activate_goal`	Move from proposed/blocked to active
`complete_goal`	Mark a goal completed
`abandon_goal`	Mark a goal abandoned
`block_goal`	Mark an active goal blocked
`unblock_goal`	Resume a blocked goal
`advance_goal_progress`	Increment progress (0..1), propagates to parent
`detect_goal_conflicts`	Find competing goals in the same domain
`list_active_goals`	Return all active goals
`list_blocked_goals`	Return all blocked goals
`list_overdue_goals`	Return goals past their deadline
`list_completed_goals`	Return completed goals
`get_goal_tree`	Return full recursive tree from a root goal
`highest_priority_goals`	Top N non-terminal goals by priority
`decay_priorities`	Apply priority decay to inactive goals
`goal_status`	Summary report (counts by status, overdue, high-priority)

Development

bundle install
bundle exec rspec
bundle exec rubocop

License

MIT