Enhance Type Definitions and Error Handling Documentation

- Added descriptive comments for constants in enums.go to clarify their purpose and improve code readability.
- Updated error definitions in errors.go with comments to specify the meaning of each error, enhancing understanding of error handling in the codebase.

agent/robot/types/enums.go

@@ -3,6 +3,7 @@ package types
 // Phase - execution phase
 type Phase string
 
+// Phase constants define the execution phases for robot agent
 const (
 	PhaseInspiration Phase = "inspiration" // P0: Clock only
 	PhaseGoals       Phase = "goals"       // P1
@@ -21,6 +22,7 @@ var AllPhases = []Phase{
 // ClockMode - clock trigger mode
 type ClockMode string
 
+// ClockMode constants define the clock trigger modes
 const (
 	ClockTimes    ClockMode = "times"    // run at specific times
 	ClockInterval ClockMode = "interval" // run every X duration
@@ -30,6 +32,7 @@ const (
 // TriggerType - trigger source
 type TriggerType string
 
+// TriggerType constants define the trigger sources
 const (
 	TriggerClock TriggerType = "clock"
 	TriggerHuman TriggerType = "human"
@@ -39,6 +42,7 @@ const (
 // ExecStatus - execution status
 type ExecStatus string
 
+// ExecStatus constants define the execution status values
 const (
 	ExecPending   ExecStatus = "pending"
 	ExecRunning   ExecStatus = "running"
@@ -50,6 +54,7 @@ const (
 // RobotStatus - matches __yao.member.robot_status
 type RobotStatus string
 
+// RobotStatus constants define the robot status values
 const (
 	RobotIdle        RobotStatus = "idle"
 	RobotWorking     RobotStatus = "working"
@@ -62,30 +67,39 @@ const (
 // Format: category.action (e.g., "task.add", "goal.adjust")
 type InterventionAction string
 
+// InterventionAction constants define the human intervention actions
 const (
-	// Task operations
-	ActionTaskAdd    InterventionAction = "task.add"    // add a new task
-	ActionTaskCancel InterventionAction = "task.cancel" // cancel a task
-	ActionTaskUpdate InterventionAction = "task.update" // update task details
+	// ActionTaskAdd adds a new task
+	ActionTaskAdd InterventionAction = "task.add"
+	// ActionTaskCancel cancels a task
+	ActionTaskCancel InterventionAction = "task.cancel"
+	// ActionTaskUpdate updates task details
+	ActionTaskUpdate InterventionAction = "task.update"
 
-	// Goal operations
-	ActionGoalAdjust   InterventionAction = "goal.adjust"   // modify current goal
-	ActionGoalAdd      InterventionAction = "goal.add"      // add a new goal
-	ActionGoalComplete InterventionAction = "goal.complete" // mark goal as complete
-	ActionGoalCancel   InterventionAction = "goal.cancel"   // cancel a goal
+	// ActionGoalAdjust modifies current goal
+	ActionGoalAdjust InterventionAction = "goal.adjust"
+	// ActionGoalAdd adds a new goal
+	ActionGoalAdd InterventionAction = "goal.add"
+	// ActionGoalComplete marks goal as complete
+	ActionGoalComplete InterventionAction = "goal.complete"
+	// ActionGoalCancel cancels a goal
+	ActionGoalCancel InterventionAction = "goal.cancel"
 
-	// Plan operations (schedule for later)
-	ActionPlanAdd    InterventionAction = "plan.add"    // add to plan queue
-	ActionPlanRemove InterventionAction = "plan.remove" // remove from plan queue
-	ActionPlanUpdate InterventionAction = "plan.update" // update planned item
+	// ActionPlanAdd adds to plan queue
+	ActionPlanAdd InterventionAction = "plan.add"
+	// ActionPlanRemove removes from plan queue
+	ActionPlanRemove InterventionAction = "plan.remove"
+	// ActionPlanUpdate updates planned item
+	ActionPlanUpdate InterventionAction = "plan.update"
 
-	// Instruction (direct command)
-	ActionInstruct InterventionAction = "instruct" // direct instruction to robot
+	// ActionInstruct is a direct instruction to robot
+	ActionInstruct InterventionAction = "instruct"
 )
 
 // Priority - task/goal priority
 type Priority string
 
+// Priority constants define the priority levels
 const (
 	PriorityHigh   Priority = "high"
 	PriorityNormal Priority = "normal"
@@ -95,6 +109,7 @@ const (
 // DeliveryType - output delivery type
 type DeliveryType string
 
+// DeliveryType constants define the output delivery types
 const (
 	DeliveryEmail   DeliveryType = "email"
 	DeliveryFile    DeliveryType = "file"
@@ -105,6 +120,7 @@ const (
 // DedupResult - deduplication result
 type DedupResult string
 
+// DedupResult constants define the deduplication results
 const (
 	DedupSkip    DedupResult = "skip"    // skip execution
 	DedupMerge   DedupResult = "merge"   // merge with existing
@@ -114,6 +130,7 @@ const (
 // EventSource - event trigger source
 type EventSource string
 
+// EventSource constants define the event trigger sources
 const (
 	EventWebhook  EventSource = "webhook"  // HTTP webhook
 	EventDatabase EventSource = "database" // DB change trigger
@@ -122,6 +139,7 @@ const (
 // LearningType - learning entry type
 type LearningType string
 
+// LearningType constants define the learning entry types
 const (
 	LearnExecution LearningType = "execution" // execution record
 	LearnFeedback  LearningType = "feedback"  // error/fix feedback
@@ -131,6 +149,7 @@ const (
 // TaskSource - how task was created
 type TaskSource string
 
+// TaskSource constants define how a task was created
 const (
 	TaskSourceAuto  TaskSource = "auto"  // generated by P2 (task planning)
 	TaskSourceHuman TaskSource = "human" // added via human intervention
@@ -140,6 +159,7 @@ const (
 // ExecutorType - task executor type
 type ExecutorType string
 
+// ExecutorType constants define the task executor types
 const (
 	ExecutorAssistant ExecutorType = "assistant"
 	ExecutorMCP       ExecutorType = "mcp"
@@ -149,6 +169,7 @@ const (
 // TaskStatus - task execution status
 type TaskStatus string
 
+// TaskStatus constants define the task execution status values
 const (
 	TaskPending   TaskStatus = "pending"
 	TaskRunning   TaskStatus = "running"
@@ -161,6 +182,7 @@ const (
 // InsertPosition - where to insert task in queue
 type InsertPosition string
 
+// InsertPosition constants define where to insert task in queue
 const (
 	InsertFirst InsertPosition = "first" // insert at beginning (highest priority)
 	InsertLast  InsertPosition = "last"  // append at end (default)

agent/robot/types/errors.go

@@ -2,24 +2,44 @@ package types
 
 import "errors"
 
-var (
-	// Config errors
-	ErrMissingIdentity    = errors.New("identity.role is required")
-	ErrClockTimesEmpty    = errors.New("clock.times is required for times mode")
-	ErrClockIntervalEmpty = errors.New("clock.every is required for interval mode")
-	ErrClockModeInvalid   = errors.New("clock.mode must be times, interval, or daemon")
+// ErrMissingIdentity indicates identity.role is required
+var ErrMissingIdentity = errors.New("identity.role is required")
 
-	// Runtime errors
-	ErrRobotNotFound      = errors.New("robot not found")
-	ErrRobotPaused        = errors.New("robot is paused")
-	ErrRobotBusy          = errors.New("robot has reached max concurrent executions")
-	ErrTriggerDisabled    = errors.New("trigger type is disabled for this robot")
-	ErrExecutionCancelled = errors.New("execution was cancelled")
-	ErrExecutionTimeout   = errors.New("execution timed out")
+// ErrClockTimesEmpty indicates clock.times is required for times mode
+var ErrClockTimesEmpty = errors.New("clock.times is required for times mode")
 
-	// Phase errors
-	ErrPhaseAgentNotFound = errors.New("phase agent not found")
-	ErrGoalGenFailed      = errors.New("goal generation failed")
-	ErrTaskPlanFailed     = errors.New("task planning failed")
-	ErrDeliveryFailed     = errors.New("delivery failed")
-)
+// ErrClockIntervalEmpty indicates clock.every is required for interval mode
+var ErrClockIntervalEmpty = errors.New("clock.every is required for interval mode")
+
+// ErrClockModeInvalid indicates clock.mode must be times, interval, or daemon
+var ErrClockModeInvalid = errors.New("clock.mode must be times, interval, or daemon")
+
+// ErrRobotNotFound indicates robot not found
+var ErrRobotNotFound = errors.New("robot not found")
+
+// ErrRobotPaused indicates robot is paused
+var ErrRobotPaused = errors.New("robot is paused")
+
+// ErrRobotBusy indicates robot has reached max concurrent executions
+var ErrRobotBusy = errors.New("robot has reached max concurrent executions")
+
+// ErrTriggerDisabled indicates trigger type is disabled for this robot
+var ErrTriggerDisabled = errors.New("trigger type is disabled for this robot")
+
+// ErrExecutionCancelled indicates execution was cancelled
+var ErrExecutionCancelled = errors.New("execution was cancelled")
+
+// ErrExecutionTimeout indicates execution timed out
+var ErrExecutionTimeout = errors.New("execution timed out")
+
+// ErrPhaseAgentNotFound indicates phase agent not found
+var ErrPhaseAgentNotFound = errors.New("phase agent not found")
+
+// ErrGoalGenFailed indicates goal generation failed
+var ErrGoalGenFailed = errors.New("goal generation failed")
+
+// ErrTaskPlanFailed indicates task planning failed
+var ErrTaskPlanFailed = errors.New("task planning failed")
+
+// ErrDeliveryFailed indicates delivery failed
+var ErrDeliveryFailed = errors.New("delivery failed")