Enum Effect 

pub enum Effect {
    AgentInvocation {
        role: AgentRole,
        agent: String,
        model: Option<String>,
        prompt: String,
    },
    InitializeAgentChain {
        role: AgentRole,
    },
    PreparePlanningPrompt {
        iteration: u32,
        prompt_mode: PromptMode,
    },
    MaterializePlanningInputs {
        iteration: u32,
    },
    CleanupPlanningXml {
        iteration: u32,
    },
    InvokePlanningAgent {
        iteration: u32,
    },
    ExtractPlanningXml {
        iteration: u32,
    },
    ValidatePlanningXml {
        iteration: u32,
    },
    WritePlanningMarkdown {
        iteration: u32,
    },
    ArchivePlanningXml {
        iteration: u32,
    },
    ApplyPlanningOutcome {
        iteration: u32,
        valid: bool,
    },
    PrepareDevelopmentContext {
        iteration: u32,
    },
    MaterializeDevelopmentInputs {
        iteration: u32,
    },
    PrepareDevelopmentPrompt {
        iteration: u32,
        prompt_mode: PromptMode,
    },
    CleanupDevelopmentXml {
        iteration: u32,
    },
    InvokeDevelopmentAgent {
        iteration: u32,
    },
    InvokeAnalysisAgent {
        iteration: u32,
    },
    ExtractDevelopmentXml {
        iteration: u32,
    },
    ValidateDevelopmentXml {
        iteration: u32,
    },
    ApplyDevelopmentOutcome {
        iteration: u32,
    },
    ArchiveDevelopmentXml {
        iteration: u32,
    },
    PrepareReviewContext {
        pass: u32,
    },
    MaterializeReviewInputs {
        pass: u32,
    },
    PrepareReviewPrompt {
        pass: u32,
        prompt_mode: PromptMode,
    },
    CleanupReviewIssuesXml {
        pass: u32,
    },
    InvokeReviewAgent {
        pass: u32,
    },
    ExtractReviewIssuesXml {
        pass: u32,
    },
    ValidateReviewIssuesXml {
        pass: u32,
    },
    WriteIssuesMarkdown {
        pass: u32,
    },
    ExtractReviewIssueSnippets {
        pass: u32,
    },
    ArchiveReviewIssuesXml {
        pass: u32,
    },
    ApplyReviewOutcome {
        pass: u32,
        issues_found: bool,
        clean_no_issues: bool,
    },
    PrepareFixPrompt {
        pass: u32,
        prompt_mode: PromptMode,
    },
    CleanupFixResultXml {
        pass: u32,
    },
    InvokeFixAgent {
        pass: u32,
    },
    ExtractFixResultXml {
        pass: u32,
    },
    ValidateFixResultXml {
        pass: u32,
    },
    ApplyFixOutcome {
        pass: u32,
    },
    ArchiveFixResultXml {
        pass: u32,
    },
    RunRebase {
        phase: RebasePhase,
        target_branch: String,
    },
    ResolveRebaseConflicts {
        strategy: ConflictStrategy,
    },
    CheckCommitDiff,
    PrepareCommitPrompt {
        prompt_mode: PromptMode,
    },
    MaterializeCommitInputs {
        attempt: u32,
    },
    InvokeCommitAgent,
    CleanupCommitXml,
    ExtractCommitXml,
    ValidateCommitXml,
    ApplyCommitMessageOutcome,
    ArchiveCommitXml,
    CreateCommit {
        message: String,
    },
    SkipCommit {
        reason: String,
    },
    BackoffWait {
        role: AgentRole,
        cycle: u32,
        duration_ms: u64,
    },
    ReportAgentChainExhausted {
        role: AgentRole,
        phase: PipelinePhase,
        cycle: u32,
    },
    ValidateFinalState,
    SaveCheckpoint {
        trigger: CheckpointTrigger,
    },
    CleanupContext,
    RestorePromptPermissions,
    WriteContinuationContext(ContinuationContextData),
    CleanupContinuationContext,
    TriggerDevFixFlow {
        failed_phase: PipelinePhase,
        failed_role: AgentRole,
        retry_cycle: u32,
    },
    EmitCompletionMarkerAndTerminate {
        is_failure: bool,
        reason: Option<String>,
    },
    TriggerLoopRecovery {
        detected_loop: String,
        loop_count: u32,
    },
}

Effects represent side-effect operations.

The reducer determines which effect to execute next based on state. Effect handlers execute effects and emit events.

Variants

AgentInvocation

Fields

role: AgentRole

agent: String

model: Option<String>

prompt: String

InitializeAgentChain

Fields

role: AgentRole

PreparePlanningPrompt

Prepare the planning prompt for an iteration (single-task).

This effect must only render/write the prompt that will be used for the subsequent planning agent invocation.

Fields

iteration: u32

prompt_mode: PromptMode

MaterializePlanningInputs

Materialize planning inputs (single-task).

This effect must perform any oversize handling for planning prompt inputs (inline vs file references) and emit explicit reducer events recording the final representation. It must not render/write the planning prompt.

Fields

iteration: u32

CleanupPlanningXml

Clean up stale planning XML before invoking the planning agent (single-task).

Fields

iteration: u32

InvokePlanningAgent

Invoke the planning agent for an iteration (single-task).

This effect must only perform agent execution using the prepared planning prompt (written by PreparePlanningPrompt) and must not parse/validate outputs.

Fields

iteration: u32

ExtractPlanningXml

Extract the planning XML from the canonical workspace path (single-task).

This effect must only verify that .agent/tmp/plan.xml exists and is readable. It must not validate XML, write PLAN.md, or change phase.

Fields

iteration: u32

ValidatePlanningXml

Validate the extracted planning XML (single-task).

This effect must only validate/parse the XML at .agent/tmp/plan.xml and emit a planning validation event. It must not write PLAN.md, archive files, or transition phases.

Fields

iteration: u32

WritePlanningMarkdown

Write .agent/PLAN.md from the validated planning XML (single-task).

This effect must only write markdown. It must not archive XML or transition phases.

Fields

iteration: u32

ArchivePlanningXml

Archive .agent/tmp/plan.xml after PLAN.md is written (single-task).

This effect must only archive the canonical plan XML (move to .processed).

Fields

iteration: u32

ApplyPlanningOutcome

Apply the already-validated planning outcome to advance the reducer state (single-task).

This effect must only emit the appropriate planning outcome event.

Fields

iteration: u32

valid: bool

PrepareDevelopmentContext

Prepare development context files for an iteration (single-task).

This effect must only write any context artifacts needed for the development prompt and must not render prompts or invoke agents.

Fields

iteration: u32

MaterializeDevelopmentInputs

Materialize development inputs (single-task).

This effect must perform any oversize handling for development prompt inputs (inline vs file references) and emit explicit reducer events recording the final representation. It must not render/write the development prompt.

Fields

iteration: u32

PrepareDevelopmentPrompt

Prepare the development prompt for an iteration (single-task).

This effect must only render/write the prompt that will be used for the subsequent developer agent invocation.

Fields

iteration: u32

prompt_mode: PromptMode

CleanupDevelopmentXml

Clean up stale development XML before invoking the developer agent (single-task).

Fields

iteration: u32

InvokeDevelopmentAgent

Invoke the developer agent for an iteration (single-task).

This effect must only perform agent execution using the prepared prompt and must not parse/validate outputs.

Fields

iteration: u32

InvokeAnalysisAgent

Invoke the analysis agent for an iteration (single-task).

This effect must only perform agent execution to analyze the git diff against PLAN.md and produce development_result.xml. It must not parse or validate outputs - those are handled by subsequent ExtractDevelopmentXml and ValidateDevelopmentXml effects.

The analysis agent has no context from development execution and produces an objective assessment based purely on observable code changes.

Fields

iteration: u32

ExtractDevelopmentXml

Extract the development result XML from the canonical workspace path (single-task).

This effect must only verify that .agent/tmp/development_result.xml exists and is readable. It must not validate XML, apply outcomes, or archive files.

Fields

iteration: u32

ValidateDevelopmentXml

Validate the extracted development result XML (single-task).

This effect must only validate/parse the XML at .agent/tmp/development_result.xml and emit a validation event. It must not apply outcomes or archive files.

Fields

iteration: u32

ApplyDevelopmentOutcome

Apply the already-validated development outcome to advance the reducer state (single-task).

This effect must only emit the appropriate development outcome event.

Fields

iteration: u32

ArchiveDevelopmentXml

Archive .agent/tmp/development_result.xml after validation (single-task).

This effect must only archive the canonical development result XML.

Fields

iteration: u32

PrepareReviewContext

Prepare review context files (single-task).

This effect must only write the review inputs (prompt backups, diffs, etc.) needed for a subsequent AgentInvocation and must not invoke agents.

Fields

pass: u32

MaterializeReviewInputs

Materialize review inputs (single-task).

This effect must perform any oversize handling for review prompt inputs (inline vs file references) and emit explicit reducer events recording the final representation. It must not render/write the review prompt.

Fields

pass: u32

PrepareReviewPrompt

Prepare the review prompt for a pass (single-task).

This effect must only render/write the prompt that will be used for the subsequent reviewer agent invocation.

Fields

pass: u32

prompt_mode: PromptMode

CleanupReviewIssuesXml

Clean up stale review issues XML before invoking the reviewer agent (single-task).

Fields

pass: u32

InvokeReviewAgent

Invoke the reviewer agent for a review pass (single-task).

This effect must only perform agent execution using the prepared review prompt (written by PrepareReviewPrompt) and must not parse/validate outputs.

Fields

pass: u32

ExtractReviewIssuesXml

Extract the review issues XML from the canonical workspace path (single-task).

This effect must only verify that .agent/tmp/issues.xml exists and is readable. It must not validate XML, write ISSUES.md, or change phase.

Fields

pass: u32

ValidateReviewIssuesXml

Validate the extracted review issues XML (single-task).

This effect must only validate/parses the XML at .agent/tmp/issues.xml and emit a review validation event. It must not write ISSUES.md, archive files, or transition phases.

Fields

pass: u32

WriteIssuesMarkdown

Write .agent/ISSUES.md from the validated issues XML (single-task).

This effect must only write markdown. It must not archive XML or transition phases.

Fields

pass: u32

ExtractReviewIssueSnippets

Extract review issue snippets for a pass (single-task).

This effect must only extract snippets and emit UI output.

Fields

pass: u32

ArchiveReviewIssuesXml

Archive .agent/tmp/issues.xml after ISSUES.md is written (single-task).

This effect must only archive the canonical issues XML (move to .processed).

Fields

pass: u32

ApplyReviewOutcome

Apply the already-validated review outcome to advance the reducer state (single-task).

This effect must only emit the appropriate review outcome event.

Fields

pass: u32

issues_found: bool

clean_no_issues: bool

PrepareFixPrompt

Prepare the fix prompt for a review pass (single-task).

This effect must only render/write the prompt that will be used for the subsequent fix agent invocation.

Fields

pass: u32

prompt_mode: PromptMode

CleanupFixResultXml

Clean up stale fix result XML before invoking the fix agent (single-task).

Fields

pass: u32

InvokeFixAgent

Invoke the fix agent for a review pass (single-task).

This effect must only perform agent execution using the prepared fix prompt (written by PrepareFixPrompt) and must not parse/validate outputs.

Fields

pass: u32

ExtractFixResultXml

Extract the fix result XML from the canonical workspace path (single-task).

This effect must only verify that .agent/tmp/fix_result.xml exists and is readable. It must not validate XML, apply outcomes, or archive files.

Fields

pass: u32

ValidateFixResultXml

Validate the extracted fix result XML (single-task).

This effect must only validate/parses the XML at .agent/tmp/fix_result.xml and emit a fix validation event. It must not apply outcomes or archive files.

Fields

pass: u32

ApplyFixOutcome

Apply the already-validated fix outcome to advance the reducer state (single-task).

This effect must only emit the appropriate fix outcome event.

Fields

pass: u32

ArchiveFixResultXml

Archive .agent/tmp/fix_result.xml after validation (single-task).

This is intentionally sequenced before ApplyFixOutcome so the reducer can archive artifacts while still in the fix chain (before state transitions reset per-pass tracking).

Fields

pass: u32

RunRebase

Fields

phase: RebasePhase

target_branch: String

ResolveRebaseConflicts

Fields

strategy: ConflictStrategy

CheckCommitDiff

Compute the commit diff for the current attempt (single-task).

This effect must only compute/write the diff and emit whether it is empty.

PrepareCommitPrompt

Prepare the commit prompt (single-task).

This effect must only render/write the commit prompt that will be used for the subsequent commit agent invocation. It must not invoke agents or validate outputs.

Fields

prompt_mode: PromptMode

MaterializeCommitInputs

Materialize commit inputs (single-task).

This effect must perform any model-budget truncation and inline-vs-reference handling for commit prompt inputs (notably the diff), and emit explicit reducer events recording the final representation. It must not render/write the commit prompt.

Fields

attempt: u32

InvokeCommitAgent

Invoke the commit agent (single-task).

This effect must only perform agent execution using the prepared commit prompt and must not parse/validate outputs.

CleanupCommitXml

Clean up stale commit XML before invoking the commit agent (single-task).

ExtractCommitXml

Extract the commit XML from the canonical workspace path (single-task).

This effect must only verify that .agent/tmp/commit_message.xml exists and is readable. It must not validate XML or archive files.

ValidateCommitXml

Validate the extracted commit XML (single-task).

This effect must only validate/parse the XML at .agent/tmp/commit_message.xml and emit a commit validation event. It must not create commits or archive files.

ApplyCommitMessageOutcome

Apply the already-validated commit message outcome (single-task).

This effect must only emit the appropriate commit outcome event.

ArchiveCommitXml

Archive .agent/tmp/commit_message.xml after validation (single-task).

This effect must only archive the canonical commit XML (move to .processed).

CreateCommit

Fields

message: String

SkipCommit

Fields

reason: String

BackoffWait

Wait for a retry-cycle backoff delay.

This effect is emitted when the reducer determines the agent chain has entered a new retry cycle and a backoff delay must be applied before attempting more work.

Fields

role: AgentRole

cycle: u32

duration_ms: u64

ReportAgentChainExhausted

Report agent chain exhaustion.

This effect is emitted when the agent chain has exhausted all retry attempts. The handler converts this to an ErrorEvent::AgentChainExhausted which the reducer processes to transition to Interrupted phase.

Fields

role: AgentRole

phase: PipelinePhase

cycle: u32

ValidateFinalState

SaveCheckpoint

Fields

trigger: CheckpointTrigger

CleanupContext

RestorePromptPermissions

Restore PROMPT.md write permissions after pipeline completion.

This effect is emitted during the Finalizing phase to restore write permissions on PROMPT.md so users can edit it normally after Ralph exits.

WriteContinuationContext(ContinuationContextData)

Write continuation context file for next development attempt.

This effect is emitted when a development iteration returns partial/failed status and needs to continue. The context file provides the next attempt with information about what was done.

The effect handler executes this as part of the development iteration flow when the reducer determines continuation is needed.

CleanupContinuationContext

Clean up continuation context file.

Emitted when an iteration completes successfully or when starting a fresh iteration (to remove stale context).

The effect handler executes this as part of the development iteration flow when the reducer determines cleanup is needed.

TriggerDevFixFlow

Trigger development agent to fix pipeline failure.

Invoked when the pipeline reaches AwaitingDevFix phase after agent chain exhaustion. The dev agent is given the full failure context (logs, error messages, last state) and asked to diagnose and fix the root cause.

After completion (success or failure), the pipeline emits a completion marker and transitions to Interrupted.

Fields

failed_phase: PipelinePhase

The phase where the failure occurred.

failed_role: AgentRole

The role of the exhausted agent chain.

retry_cycle: u32

Retry cycle count when exhaustion occurred.

EmitCompletionMarkerAndTerminate

Emit completion marker and transition to Interrupted.

This effect is emitted after dev-fix flow completes (or skips) to ensure a completion marker is always written before pipeline termination.

Fields

is_failure: bool

Whether the pipeline is terminating due to failure.

reason: Option<String>

Optional reason for termination.

TriggerLoopRecovery

Trigger mandatory loop recovery.

This effect is emitted when the orchestrator detects that the same effect has been executed too many times consecutively without state progression. The handler will reset XSD retry state, clear session IDs, and reset loop detection counters to break the loop.

Fields

detected_loop: String

String representation of the detected loop (for diagnostics).

loop_count: u32

Number of times the loop was repeated.

Trait Implementations

impl Clone for Effect

fn clone(&self) -> Effect

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Effect

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Effect

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Effect

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

where __S: Serializer,

Serialize this value into the given Serde serializer.