ralph_workflow/phases/
mod.rs

1//! Pipeline Phase Orchestration Module
2//!
3//! This module contains the execution logic for each phase of the Ralph pipeline.
4//! Phases are invoked by the reducer architecture via effects, keeping business
5//! logic (when to transition) separate from execution logic (how to execute).
6//!
7//! # Pipeline Phases
8//!
9//! Ralph runs four sequential phases:
10//!
11//! ```text
12//! ┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
13//! │   Planning   │ ──▶ │ Development  │ ──▶ │    Review    │ ──▶ │    Commit    │
14//! │              │     │              │     │              │     │              │
15//! │ Creates PLAN │     │ Implements   │     │ Reviews code │     │ Generates    │
16//! │ from PROMPT  │     │ iterations   │     │ and fixes    │     │ commit msg   │
17//! └──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘
18//! ```
19//!
20//! ## Planning Phase
21//!
22//! Reads `PROMPT.md` and generates `.agent/PLAN.md` via AI agent.
23//! The plan guides subsequent development iterations.
24//!
25//! ## Development Phase
26//!
27//! Executes N iterations (configurable via `-D`) where the agent:
28//! 1. Reads `PROMPT.md` and `PLAN.md`
29//! 2. Implements changes
30//! 3. Commits after each iteration (if changes detected)
31//!
32//! ## Review Phase
33//!
34//! Runs M review cycles (configurable via `-R`) where:
35//! 1. Reviewer agent analyzes cumulative diff since pipeline start
36//! 2. Creates `.agent/ISSUES.md` with findings
37//! 3. Developer agent fixes issues
38//! 4. Repeats until no issues or max cycles reached
39//!
40//! ## Commit Phase
41//!
42//! Generates a final commit message via AI, analyzing the full diff.
43//! Falls back to intelligent heuristic-based message if AI fails.
44//!
45//! # Module Structure
46//!
47//! - [`context`] - Shared [`PhaseContext`] for passing state between phases
48//! - [`development`] - Iterative development cycle execution
49//! - [`review`] - Code review and fix cycle execution
50//! - [`commit`] - Automated commit message generation
51//! - [`integrity`] - File integrity verification
52//!
53//! # Integration with Reducer
54//!
55//! The reducer (see [`crate::reducer`]) determines which phase to execute via
56//! [`crate::reducer::determine_next_effect`]. Phase modules are invoked by
57//! effect handlers, returning events that update pipeline state.
58//!
59//! **Important**: Phase modules do NOT make control-flow decisions. They execute
60//! their assigned task and return events. All decisions about phase transitions,
61//! agent fallback, and retry behavior are made by the reducer based on events.
62//!
63//! # Phase Module Responsibilities
64//!
65//! Phase modules execute tasks and emit events. They do NOT:
66//! - Make control flow decisions (no "if condition then skip phase")
67//! - Read legacy artifact files to recover missing results
68//! - Skip or advance phases based on file existence checks
69//! - Perform implicit agent selection or fallback logic
70//! - Trigger agent fallback directly (only the reducer does this)
71//!
72//! All phase transitions are made by the reducer based on events emitted by effects.
73//!
74//! # Note on Re-exports
75//!
76//! The functions below are public for use by the reducer architecture.
77//! They were previously private module internals.
78
79pub mod commit;
80pub mod commit_logging;
81pub mod context;
82pub mod development;
83pub mod integrity;
84pub mod review;
85
86pub use commit::{
87    effective_model_budget_bytes, generate_commit_message, truncate_diff_to_model_budget,
88};
89pub use context::{get_primary_commit_agent, PhaseContext};
ralph_workflow/phases/mod.rs

ralph_workflow/phases/
mod.rs
