omh-ralph

OMH Ralph — Verified Execution (v2)

Requires the OMH plugin. Install plugins/omh/ from this repo to ~/.hermes/plugins/omh/.

When to Use

• You have a plan (from omh-ralplan or manual) and need verified execution
• The user says: "ralph", "don't stop", "until done", "must complete", "keep going"
• You need guaranteed verification — not just "looks done" but evidence-backed completion
• Multi-step implementation where each task must be independently verified

When NOT to Use

• No plan or spec exists (use omh-deep-interview and/or omh-ralplan first)
• Trivial single-file changes (just do them directly)
• The user explicitly wants to skip verification

Architecture: One Task Per Invocation

Each ralph invocation does ONE unit of work and exits. The caller re-invokes for the next task. This eliminates context window exhaustion and makes every invocation a clean checkpoint.

Invocation N:  read state → pick task → execute → verify → update state → EXIT
Invocation N+1: read state → pick next task → execute → verify → update state → EXIT
...
Final invocation: all tasks pass → architect review → mark complete → EXIT

Procedure

Step 0: Resolve Instance and Acquire Lock

Ralph and autopilot mutate a shared .omh/plans/ plan. Two sessions running ralph against the same plan would race on ralph-tasks state and produce non-deterministic outcomes. Use per-instance state + advisory lock to make concurrent plans safe.

1. Resolve instance_id from the plan path:
   • Default plan source: .omh/plans/ralplan-*.md or .omh/plans/ralph-plan.md.
   • instance_id = basename(plan_path) without ".md" (engine slugifies).
   • If no plan exists yet (Step 2 will choose), use instance_id="default".
2. Acquire the lock before reading/writing state:

   lock = omh_state(action="lock", mode="ralph",
                    lock_key="{instance_id}",
                    session_id="{HERMES_SESSION_ID or uuid}",
                    holder_note="ralph executing {plan_path}")
   

   • acquired=true: continue.
   • acquired=false: report held_by to the user (pid + session_id + started_at). Offer: wait / cancel the holder (omh_state(action="cancel", mode="ralph", instance_id="{instance_id}"), then on next invocation the dead holder's lock will be released automatically by stale-pid detection) / pick a different plan.
3. Pass instance_id to every subsequent omh_state call in this invocation — both the ralph mode and the ralph-tasks mode.
4. Release the lock at every exit point (success, blocked, cancel, max-iterations, exception):

   omh_state(action="unlock", mode="ralph",
             lock_key="{instance_id}",
             session_id="{HERMES_SESSION_ID or uuid}")
   

   Wrap the body of the procedure so the unlock fires even on error.