Enum PipelinePhase 

pub enum PipelinePhase {
    Planning,
    Development,
    Review,
    CommitMessage,
    FinalValidation,
    Finalizing,
    Complete,
    AwaitingDevFix,
    Interrupted,
}

Pipeline phases for checkpoint tracking.

These phases represent the major stages of the Ralph pipeline. Reducers transition between phases based on events.

Phase Transitions

Planning → Development → Review → CommitMessage → FinalValidation → Finalizing → Complete
             ↓             ↓            ↓
        AwaitingDevFix → Interrupted

Phase Descriptions

• Planning: Generate implementation plan for the iteration
• Development: Execute plan, write code
• Review: Review code changes, identify issues
• CommitMessage: Generate commit message
• FinalValidation: Final checks before completion
• Finalizing: Cleanup operations (restore permissions, etc.)
• Complete: Pipeline completed successfully
• AwaitingDevFix: Terminal failure occurred, dev agent diagnosing
• Interrupted: Pipeline terminated (success or failure)

Variants

Planning

Development

Review

CommitMessage

FinalValidation

Finalizing

Finalizing phase for cleanup operations before completion.

This phase handles:

• Restoring PROMPT.md write permissions
• Any other cleanup that must go through the effect system

Complete

AwaitingDevFix

Awaiting development agent to fix pipeline failure.

This phase occurs when the pipeline encounters a terminal failure condition (e.g., agent chain exhausted) but before transitioning to Interrupted. It signals that the development agent should be invoked to diagnose and fix the failure root cause.

Failure Handling Flow

1. ErrorEvent::AgentChainExhausted occurs in any phase
2. Reducer transitions state to AwaitingDevFix
3. Orchestration determines Effect::TriggerDevFixFlow
4. Handler executes TriggerDevFixFlow: a. Writes completion marker to .agent/tmp/completion_marker (failure status) b. Emits DevFixTriggered event c. Dispatches dev-fix agent d. Emits DevFixCompleted event e. Emits CompletionMarkerEmitted event
5. DevFixTriggered/DevFixCompleted events: no state change (stays in AwaitingDevFix)
6. CompletionMarkerEmitted event: transitions to Interrupted
7. Orchestration determines Effect::SaveCheckpoint for Interrupted
8. Handler saves checkpoint, increments checkpoint_saved_count
9. Event loop recognizes is_complete() == true and exits successfully

Event Loop Termination Guarantees

The event loop MUST NOT exit with completed=false when in AwaitingDevFix phase. The failure handling flow is designed to always complete with:

• Completion marker written to filesystem
• State transitioned to Interrupted
• Checkpoint saved (checkpoint_saved_count > 0)
• Event loop returning completed=true

If the event loop exits with completed=false from AwaitingDevFix, this indicates a critical bug (e.g., max iterations reached before checkpoint saved).

Completion Marker Requirement

The completion marker MUST be written before transitioning to Interrupted. This ensures external orchestration systems (CI, monitoring) can detect pipeline termination even if the event loop exits unexpectedly.

Agent Chain Exhaustion Handling

When in AwaitingDevFix phase with an exhausted agent chain, orchestration falls through to phase-specific logic (TriggerDevFixFlow) instead of reporting exhaustion again. This prevents infinite loops where exhaustion is reported repeatedly.

Transitions:

• From: Any phase where AgentChainExhausted error occurs
• To: Interrupted (after dev-fix attempt completes or fails)

Interrupted

Trait Implementations

impl Clone for PipelinePhase

fn clone(&self) -> PipelinePhase

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PipelinePhase

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for PipelinePhase

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for PipelinePhase

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for PipelinePhase

fn eq(&self, other: &PipelinePhase) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for PipelinePhase

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Copy for PipelinePhase

impl Eq for PipelinePhase

impl StructuralPartialEq for PipelinePhase