Enum PipelineEvent 

pub enum PipelineEvent {
    Lifecycle(LifecycleEvent),
    Planning(PlanningEvent),
    Development(DevelopmentEvent),
    Review(ReviewEvent),
    PromptInput(PromptInputEvent),
    Agent(AgentEvent),
    Rebase(RebaseEvent),
    Commit(CommitEvent),
    AwaitingDevFix(AwaitingDevFixEvent),
    ContextCleaned,
    CheckpointSaved {
        trigger: CheckpointTrigger,
    },
    FinalizingStarted,
    PromptPermissionsRestored,
    LoopRecoveryTriggered {
        detected_loop: String,
        loop_count: u32,
    },
}

Pipeline events representing all state transitions.

Events are organized into logical categories for type-safe routing to category-specific reducers. Each category has a dedicated inner enum.

Event Categories

• Lifecycle - Pipeline start/stop/resume
• Planning - Plan generation events
• Development - Development iteration and continuation events
• Review - Review pass and fix attempt events
• Agent - Agent invocation and chain management events
• Rebase - Git rebase operation events
• Commit - Commit generation events
• Miscellaneous events (context cleanup, checkpoints, finalization)

Example

// Type-safe event construction
let event = PipelineEvent::Agent(AgentEvent::InvocationStarted {
    role: AgentRole::Developer,
    agent: "claude".to_string(),
    model: Some("opus".to_string()),
});

// Pattern matching routes to category handlers
match event {
    PipelineEvent::Agent(agent_event) => reduce_agent_event(state, agent_event),
    // ...
}

⚠️ FROZEN - DO NOT ADD VARIANTS ⚠️

This enum is FROZEN. Adding new top-level variants is PROHIBITED.

Why is this frozen?

PipelineEvent provides category-based event routing to the reducer. The existing categories (Lifecycle, Planning, Development, Review, etc.) cover all pipeline phases. Adding new top-level variants would indicate a missing architectural abstraction or an attempt to bypass phase-specific event handling.

What to do instead

1. Express events through existing categories - Use the category enums:

   • PlanningEvent for planning phase observations
   • DevelopmentEvent for development phase observations
   • ReviewEvent for review phase observations
   • CommitEvent for commit generation observations
   • AgentEvent for agent invocation observations
   • RebaseEvent for rebase state machine transitions

2. Return errors for unrecoverable failures - Don’t create events for conditions that should terminate the pipeline. Return Err from the effect handler instead.

3. Extend category enums if needed - If you truly need a new event within an existing phase, add it to that phase’s category enum (e.g., add a new variant to ReviewEvent rather than creating a new top-level category).

Enforcement

The freeze policy is enforced by the pipeline_event_is_frozen test in this module, which will fail to compile if new variants are added. This is intentional.

See LifecycleEvent documentation for additional context on the freeze policy rationale.

Variants

Lifecycle(LifecycleEvent)

Pipeline lifecycle events (start, stop, resume).

Planning(PlanningEvent)

Planning phase events.

Development(DevelopmentEvent)

Development phase events.

Review(ReviewEvent)

Review phase events.

PromptInput(PromptInputEvent)

Prompt input materialization events.

Agent(AgentEvent)

Agent invocation and chain events.

Rebase(RebaseEvent)

Rebase operation events.

Commit(CommitEvent)

Commit generation events.

AwaitingDevFix(AwaitingDevFixEvent)

AwaitingDevFix phase events.

ContextCleaned

Context cleanup completed.

CheckpointSaved

Checkpoint saved.

Fields

trigger: CheckpointTrigger

What triggered the checkpoint save.

FinalizingStarted

Finalization phase started.

PromptPermissionsRestored

PROMPT.md permissions restored.

LoopRecoveryTriggered

Loop recovery triggered (tight loop detected and broken).

Fields

detected_loop: String

String representation of the detected loop.

loop_count: u32

Number of times the loop was repeated.

Implementations

impl PipelineEvent

pub const fn pipeline_started() -> Self

Create a PipelineStarted event.

pub const fn pipeline_resumed(from_checkpoint: bool) -> Self

Create a PipelineResumed event.

pub const fn pipeline_completed() -> Self

Create a PipelineCompleted event.

pub const fn planning_phase_started() -> Self

Create a PlanningPhaseStarted event.

pub const fn planning_phase_completed() -> Self

Create a PlanningPhaseCompleted event.

pub const fn planning_prompt_prepared(iteration: u32) -> Self

Create a PlanningPromptPrepared event.

pub const fn planning_agent_invoked(iteration: u32) -> Self

Create a PlanningAgentInvoked event.

pub const fn planning_xml_cleaned(iteration: u32) -> Self

Create a PlanningXmlCleaned event.

pub const fn planning_xml_extracted(iteration: u32) -> Self

Create a PlanningXmlExtracted event.

pub const fn planning_xml_missing(iteration: u32, attempt: u32) -> Self

Create a PlanningXmlMissing event.

pub const fn planning_xml_validated( iteration: u32, valid: bool, markdown: Option<String>, ) -> Self

Create a PlanningXmlValidated event.

pub const fn planning_markdown_written(iteration: u32) -> Self

Create a PlanningMarkdownWritten event.

pub const fn planning_xml_archived(iteration: u32) -> Self

Create a PlanningXmlArchived event.

pub const fn plan_generation_completed(iteration: u32, valid: bool) -> Self

Create a PlanGenerationCompleted event.

pub const fn planning_output_validation_failed( iteration: u32, attempt: u32, ) -> Self

Create a PlanningOutputValidationFailed event.

impl PipelineEvent

pub const fn prompt_input_oversize_detected( phase: PipelinePhase, kind: PromptInputKind, content_id_sha256: String, size_bytes: u64, limit_bytes: u64, policy: String, ) -> Self

pub const fn planning_inputs_materialized( iteration: u32, prompt: MaterializedPromptInput, ) -> Self

pub const fn development_inputs_materialized( iteration: u32, prompt: MaterializedPromptInput, plan: MaterializedPromptInput, ) -> Self

pub const fn review_inputs_materialized( pass: u32, plan: MaterializedPromptInput, diff: MaterializedPromptInput, ) -> Self

pub const fn commit_inputs_materialized( attempt: u32, diff: MaterializedPromptInput, ) -> Self

pub const fn xsd_retry_last_output_materialized( phase: PipelinePhase, scope_id: u32, last_output: MaterializedPromptInput, ) -> Self

pub const fn prompt_permissions_locked(warning: Option<String>) -> Self

Create a PromptPermissionsLocked event.

pub const fn prompt_permissions_restore_warning(warning: String) -> Self

Create a PromptPermissionsRestoreWarning event.

pub const fn template_rendered( phase: PipelinePhase, template_name: String, log: SubstitutionLog, ) -> Self

Create a TemplateRendered event.

Emitted by prompt preparation handlers after template rendering. The substitution log enables validation based on tracked substitutions.

impl PipelineEvent

pub const fn development_phase_started() -> Self

Create a DevelopmentPhaseStarted event.

pub const fn development_iteration_started(iteration: u32) -> Self

Create a DevelopmentIterationStarted event.

pub const fn development_context_prepared(iteration: u32) -> Self

Create a DevelopmentContextPrepared event.

pub const fn development_prompt_prepared(iteration: u32) -> Self

Create a DevelopmentPromptPrepared event.

pub const fn development_agent_invoked(iteration: u32) -> Self

Create a DevelopmentAgentInvoked event.

pub const fn development_xml_extracted(iteration: u32) -> Self

Create a DevelopmentXmlExtracted event.

pub const fn development_xml_cleaned(iteration: u32) -> Self

Create a DevelopmentXmlCleaned event.

pub const fn development_xml_missing(iteration: u32, attempt: u32) -> Self

Create a DevelopmentXmlMissing event.

pub const fn development_xml_validated( iteration: u32, status: DevelopmentStatus, summary: String, files_changed: Option<Vec<String>>, next_steps: Option<String>, ) -> Self

Create a DevelopmentXmlValidated event.

pub const fn development_outcome_applied(iteration: u32) -> Self

Create a DevelopmentOutcomeApplied event.

pub const fn development_xml_archived(iteration: u32) -> Self

Create a DevelopmentXmlArchived event.

pub const fn development_iteration_completed( iteration: u32, output_valid: bool, ) -> Self

Create a DevelopmentIterationCompleted event.

pub const fn development_phase_completed() -> Self

Create a DevelopmentPhaseCompleted event.

pub const fn development_iteration_continuation_triggered( iteration: u32, status: DevelopmentStatus, summary: String, files_changed: Option<Vec<String>>, next_steps: Option<String>, ) -> Self

Create a DevelopmentIterationContinuationTriggered event.

pub const fn development_iteration_continuation_succeeded( iteration: u32, total_continuation_attempts: u32, ) -> Self

Create a DevelopmentIterationContinuationSucceeded event.

pub const fn development_output_validation_failed( iteration: u32, attempt: u32, ) -> Self

Create a DevelopmentOutputValidationFailed event.

pub const fn development_continuation_budget_exhausted( iteration: u32, total_attempts: u32, last_status: DevelopmentStatus, ) -> Self

Create a DevelopmentContinuationBudgetExhausted event.

pub const fn development_continuation_context_written( iteration: u32, attempt: u32, ) -> Self

Create a DevelopmentContinuationContextWritten event.

pub const fn development_continuation_context_cleaned() -> Self

Create a DevelopmentContinuationContextCleaned event.

impl PipelineEvent

pub const fn review_phase_started() -> Self

Create a ReviewPhaseStarted event.

pub const fn review_pass_started(pass: u32) -> Self

Create a ReviewPassStarted event.

pub const fn review_context_prepared(pass: u32) -> Self

Create a ReviewContextPrepared event.

pub const fn review_prompt_prepared(pass: u32) -> Self

Create a ReviewPromptPrepared event.

pub const fn review_agent_invoked(pass: u32) -> Self

Create a ReviewAgentInvoked event.

pub const fn review_issues_xml_extracted(pass: u32) -> Self

Create a ReviewIssuesXmlExtracted event.

pub const fn review_issues_xml_cleaned(pass: u32) -> Self

Create a ReviewIssuesXmlCleaned event.

pub const fn review_issues_xml_missing( pass: u32, attempt: u32, error_detail: Option<String>, ) -> Self

Create a ReviewIssuesXmlMissing event.

pub const fn review_issues_xml_validated( pass: u32, issues_found: bool, clean_no_issues: bool, issues: Vec<String>, no_issues_found: Option<String>, ) -> Self

Create a ReviewIssuesXmlValidated event.

pub const fn review_issues_markdown_written(pass: u32) -> Self

pub const fn review_issue_snippets_extracted(pass: u32) -> Self

pub const fn review_issues_xml_archived(pass: u32) -> Self

pub const fn fix_prompt_prepared(pass: u32) -> Self

pub const fn fix_agent_invoked(pass: u32) -> Self

pub const fn fix_result_xml_extracted(pass: u32) -> Self

pub const fn fix_result_xml_missing( pass: u32, attempt: u32, error_detail: Option<String>, ) -> Self

pub const fn fix_result_xml_validated( pass: u32, status: FixStatus, summary: Option<String>, ) -> Self

pub const fn fix_result_xml_cleaned(pass: u32) -> Self

pub const fn fix_outcome_applied(pass: u32) -> Self

pub const fn fix_result_xml_archived(pass: u32) -> Self

pub const fn review_completed(pass: u32, issues_found: bool) -> Self

Create a ReviewCompleted event.

pub const fn fix_attempt_started(pass: u32) -> Self

Create a FixAttemptStarted event.

pub const fn fix_attempt_completed(pass: u32, changes_made: bool) -> Self

Create a FixAttemptCompleted event.

pub const fn review_phase_completed(early_exit: bool) -> Self

Create a ReviewPhaseCompleted event.

pub const fn review_pass_completed_clean(pass: u32) -> Self

Create a ReviewPassCompletedClean event.

pub const fn review_output_validation_failed( pass: u32, attempt: u32, error_detail: Option<String>, ) -> Self

Create a ReviewOutputValidationFailed event.

pub const fn fix_continuation_triggered( pass: u32, status: FixStatus, summary: Option<String>, ) -> Self

Create a FixContinuationTriggered event.

pub const fn fix_continuation_succeeded(pass: u32, total_attempts: u32) -> Self

Create a FixContinuationSucceeded event.

pub const fn fix_continuation_budget_exhausted( pass: u32, total_attempts: u32, last_status: FixStatus, ) -> Self

Create a FixContinuationBudgetExhausted event.

pub const fn fix_output_validation_failed( pass: u32, attempt: u32, error_detail: Option<String>, ) -> Self

Create a FixOutputValidationFailed event.

impl PipelineEvent

pub const fn agent_invocation_started( role: AgentRole, agent: String, model: Option<String>, ) -> Self

Create an AgentInvocationStarted event.

pub const fn agent_invocation_succeeded(role: AgentRole, agent: String) -> Self

Create an AgentInvocationSucceeded event.

pub const fn agent_invocation_failed( role: AgentRole, agent: String, exit_code: i32, error_kind: AgentErrorKind, retriable: bool, ) -> Self

Create an AgentInvocationFailed event.

pub const fn agent_fallback_triggered( role: AgentRole, from_agent: String, to_agent: String, ) -> Self

Create an AgentFallbackTriggered event.

pub const fn agent_model_fallback_triggered( role: AgentRole, agent: String, from_model: String, to_model: String, ) -> Self

Create an AgentModelFallbackTriggered event.

pub const fn agent_retry_cycle_started(role: AgentRole, cycle: u32) -> Self

Create an AgentRetryCycleStarted event.

pub const fn agent_chain_exhausted(role: AgentRole) -> Self

Create an AgentChainExhausted event.

pub const fn agent_chain_initialized( drain: AgentDrain, agents: Vec<String>, max_cycles: u32, retry_delay_ms: u64, backoff_multiplier: f64, max_backoff_ms: u64, ) -> Self

Create an AgentChainInitialized event.

pub const fn agent_rate_limited( role: AgentRole, agent: String, prompt_context: Option<String>, ) -> Self

Create an AgentRateLimited event.

pub const fn agent_auth_failed(role: AgentRole, agent: String) -> Self

Create an AgentAuthFailed event.

pub const fn agent_timed_out( role: AgentRole, agent: String, output_kind: TimeoutOutputKind, logfile_path: Option<String>, child_status_at_timeout: Option<ChildProcessInfo>, ) -> Self

Create an AgentTimedOut event.

pub const fn agent_session_established( role: AgentRole, agent: String, session_id: String, ) -> Self

Create an AgentSessionEstablished event.

pub const fn agent_xsd_validation_failed( role: AgentRole, artifact: ArtifactType, error: String, retry_count: u32, ) -> Self

Create an AgentXsdValidationFailed event.

pub const fn agent_template_variables_invalid( role: AgentRole, template_name: String, missing_variables: Vec<String>, unresolved_placeholders: Vec<String>, ) -> Self

Create an AgentTemplateVariablesInvalid event.

pub const fn agent_timeout_context_written( role: AgentRole, logfile_path: String, context_path: String, ) -> Self

Create an AgentTimeoutContextWritten event.

impl PipelineEvent

pub const fn rebase_started(phase: RebasePhase, target_branch: String) -> Self

Create a RebaseStarted event.

pub const fn rebase_conflict_detected(files: Vec<PathBuf>) -> Self

Create a RebaseConflictDetected event.

pub const fn rebase_conflict_resolved(files: Vec<PathBuf>) -> Self

Create a RebaseConflictResolved event.

pub const fn rebase_succeeded(phase: RebasePhase, new_head: String) -> Self

Create a RebaseSucceeded event.

pub const fn rebase_failed(phase: RebasePhase, reason: String) -> Self

Create a RebaseFailed event.

pub const fn rebase_aborted(phase: RebasePhase, restored_to: String) -> Self

Create a RebaseAborted event.

pub const fn rebase_skipped(phase: RebasePhase, reason: String) -> Self

Create a RebaseSkipped event.

pub const fn commit_generation_started() -> Self

Create a CommitGenerationStarted event.

pub const fn commit_diff_prepared( empty: bool, content_id_sha256: String, ) -> Self

Create a CommitDiffPrepared event.

pub const fn commit_diff_failed(error: String) -> Self

Create a CommitDiffFailed event.

pub const fn commit_diff_invalidated(reason: String) -> Self

pub const fn commit_prompt_prepared(attempt: u32) -> Self

Create a CommitPromptPrepared event.

pub const fn commit_agent_invoked(attempt: u32) -> Self

Create a CommitAgentInvoked event.

pub const fn commit_xml_extracted(attempt: u32) -> Self

Create a CommitXmlExtracted event.

pub const fn commit_xml_missing(attempt: u32) -> Self

Create a CommitXmlMissing event.

pub const fn commit_xml_validated( message: String, files: Vec<String>, excluded_files: Vec<ExcludedFile>, attempt: u32, ) -> Self

Create a CommitXmlValidated event.

pub const fn commit_xml_validation_failed(reason: String, attempt: u32) -> Self

Create a CommitXmlValidationFailed event.

pub const fn commit_xml_archived(attempt: u32) -> Self

Create a CommitXmlArchived event.

pub const fn commit_required_files_cleaned(attempt: u32) -> Self

pub const fn commit_message_generated(message: String, attempt: u32) -> Self

Create a CommitMessageGenerated event.

pub const fn commit_message_validation_failed( reason: String, attempt: u32, ) -> Self

Create a CommitMessageValidationFailed event.

pub const fn commit_created(hash: String, message: String) -> Self

Create a CommitCreated event.

pub const fn commit_generation_failed(reason: String) -> Self

Create a CommitGenerationFailed event.

pub const fn commit_skipped(reason: String) -> Self

Create a CommitSkipped event.

pub const fn pre_termination_safety_check_passed() -> Self

Create a PreTerminationSafetyCheckPassed event.

pub const fn pre_termination_uncommitted_changes_detected( file_count: usize, ) -> Self

Create a PreTerminationUncommittedChangesDetected event.

pub const fn residual_files_found(files: Vec<String>, pass: u8) -> Self

Create a ResidualFilesFound event.

Emitted after a selective commit pass when uncommitted files remain.

pub const fn residual_files_none() -> Self

Create a ResidualFilesNone event.

Emitted after a commit pass when the working tree is clean.

pub const fn context_cleaned() -> Self

Create a ContextCleaned event.

pub const fn checkpoint_saved(trigger: CheckpointTrigger) -> Self

Create a CheckpointSaved event.

pub const fn finalizing_started() -> Self

Create a FinalizingStarted event.

pub const fn prompt_permissions_restored() -> Self

Create a PromptPermissionsRestored event.

impl PipelineEvent

pub const fn loop_recovery_triggered( detected_loop: String, loop_count: u32, ) -> Self

Construct a LoopRecoveryTriggered event.

pub const fn gitignore_entries_ensured( entries_added: Vec<String>, already_present: Vec<String>, file_created: bool, ) -> Self

Create a GitignoreEntriesEnsured event.

Trait Implementations

impl Clone for PipelineEvent

fn clone(&self) -> PipelineEvent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for PipelineEvent

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for PipelineEvent

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for PipelineEvent

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

where __S: Serializer,

Serialize this value into the given Serde serializer.