Module files 

File management utilities for Ralph’s agent files.

This module manages the .agent/ directory structure and files:

• PLAN.md, ISSUES.md, STATUS.md, NOTES.md lifecycle
• commit-message.txt management
• PROMPT.md validation
• Isolation mode file cleanup
• Result extraction from agent JSON logs
• File integrity verification and checksums
• Error recovery and state repair
• Real-time file system monitoring for PROMPT.md protection

Module Organization

The files module is organized by domain concern:

• io - File I/O operations (agent files, recovery, backup, context)
• protection - File protection and integrity (validation, integrity, monitoring)
• llm_output_extraction - LLM output extraction (commit message, JSON extraction)
• result_extraction - Plan and issue extraction from logs

Isolation Mode

By default, Ralph operates in isolation mode where STATUS.md, NOTES.md, and ISSUES.md are not persisted between runs. This prevents context contamination from previous runs.

Orchestrator-Controlled File I/O

The orchestrator is the sole entity responsible for writing output files. Agent JSON output is extracted and written by the orchestrator, ensuring consistent file handling regardless of agent behavior.

Re-exports

pub use io::clean_context_for_reviewer;

pub use io::clean_context_for_reviewer_with_workspace;

pub use io::cleanup_generated_files;

pub use io::cleanup_generated_files_with_workspace;

pub use io::create_prompt_backup;

pub use io::create_prompt_backup_with_workspace;

pub use io::delete_commit_message_file;

pub use io::delete_commit_message_file_with_workspace;

pub use io::delete_issues_file_for_isolation;

pub use io::delete_issues_file_for_isolation_with_workspace;

pub use io::delete_plan_file;

pub use io::delete_plan_file_with_workspace;

pub use io::ensure_files;

pub use io::file_contains_marker;

pub use io::file_contains_marker_with_workspace;

pub use io::make_prompt_read_only;

pub use io::make_prompt_read_only_with_workspace;

pub use io::make_prompt_writable;

pub use io::make_prompt_writable_with_workspace;

pub use io::read_commit_message_file;

pub use io::read_commit_message_file_with_workspace;

pub use io::reset_context_for_isolation;

pub use io::setup_xsd_schemas_with_workspace;

pub use io::update_status;

pub use io::update_status_with_workspace;

pub use io::verify_file_not_corrupted_with_workspace;

pub use io::write_commit_message_file;

pub use io::write_commit_message_file_with_workspace;

pub use io::write_diff_backup_with_workspace;

pub use io::write_file_atomic_with_workspace;

pub use protection::validate_prompt_md;

pub use protection::validate_prompt_md_with_workspace;

pub use result_extraction::extract_issues;

Modules

io

File I/O operations for Ralph’s agent files.

llm_output_extraction

LLM Output Extraction Module

protection

File protection and integrity for Ralph’s agent files.

result_extraction

Result extraction from agent JSON logs.