Module sanity 

Automatic startup health checks with auto-fix and migration prompts.

Responsibilities:

• Run lightweight health checks on Ralph startup for key commands.
• Auto-update README.md when embedded template is newer (no prompt).
• Detect and prompt for config migrations (deprecated keys, unknown keys).
• Support –auto-fix flag to auto-approve all migrations without prompting.
• Support –no-sanity-checks flag to skip sanity health checks.
• Support non-interactive mode to skip all prompts (for CI/piped runs).

Not handled here:

• Deep validation (git, runners, queue structure) - that’s ralph doctor.
• GUI app flows.
• Network connectivity checks.

Invariants/assumptions:

• Sanity checks are fast and lightweight.
• README auto-update is automatic (users shouldn’t edit this file manually).
• Config migrations require user confirmation unless –auto-fix is set.
• Unknown config keys prompt for remove/keep/rename action.
• Prompts require both stdin and stdout to be TTYs.
• If non_interactive is true, all prompts are skipped (use –auto-fix to apply changes).
• README sync may also be invoked directly by command routing for agent-facing commands.

Structs

SanityIssue

A single issue found during sanity checks.

SanityOptions

Options for controlling sanity check behavior.

SanityResult

Result of running sanity checks.

Enums

IssueSeverity

Severity level for sanity issues.

Functions

refresh_readme_if_needed

Refresh .ralph/README.md if missing/outdated.

report_sanity_results

Report sanity check results to the user.

run_sanity_checks

Run all sanity checks and apply fixes based on options.

should_refresh_readme_for_command

Whether a command should refresh .ralph/README.md before execution.

should_run_sanity_checks

Check if sanity checks should run for a given command.