ralph · diff
git:20260824.1812bc4 to git:20261016.266342a
41 added, 215 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: ralph
description: "MCP-owned Ralph loop around background evolve_step jobs"
mcp_tool: ouroboros_ralph
mcp_args:
lineage_id: "$lineage_id"
---
# /ouroboros:ralph
MCP-owned Ralph loop around background `evolve_step` jobs. "The boulder never stops."
## Usage
```
ooo ralph --lineage-id <lineage_id>
/ouroboros:ralph --lineage-id <lineage_id>
-
- # For a plain natural-language request, run `ooo interview` + `ooo seed` first,
- # then call the MCP tool with a fresh lineage_id and the validated Seed YAML.
```
- **Trigger keywords:** "ralph", "don't stop", "must complete", "until it works", "keep going"
-
- ## How It Works
-
- Ralph is owned by the `ouroboros_ralph` MCP tool. In non-plugin runtimes, the
- tool starts one background Ralph job, runs repeated `evolve_step` generations
- inside that job, and stops only when QA passes, convergence is reached, a
- terminal evolution action occurs, cancellation is requested, or
- `max_generations` is reached. In OpenCode plugin mode, the MCP tool returns a
- `delegated_to_plugin` envelope with `job_id=None`; the bridge plugin dispatches
- a child Task session that owns the loop instead of creating a local JobManager
- job.
-
- The client skill should not reimplement the loop. Deterministic frontmatter
- dispatch is limited to the router's named `--lineage-id` option so raw trailing
- text is never treated as lineage identity. Raw natural-language
- `ooo ralph "<request>"` input must flow through the validated Seed path before
- any mutating Ralph loop starts. Until a lineage id and optional Seed YAML are
- prepared, `ouroboros_ralph` returns structured input guidance instead of
- starting a job. Once the inputs are prepared, start the MCP-owned Ralph surface
- once, then follow either the returned job tools path or the OpenCode Task widget
- path.
+ The `ouroboros_ralph` tool owns the loop (do not reimplement it): one background job runs repeated `evolve_step` generations until QA pass, convergence, a terminal evolution action, cancellation, or `max_generations`. Router dispatch reads only the named `--lineage-id` option, never trailing text.
## Instructions
- When the user invokes this skill:
-
- ### Load MCP Tools (Required first)
-
- The Ouroboros MCP tools are often registered as deferred tools that must be
- explicitly loaded before use. Do this before preparing input or calling Ralph:
-
- 1. Use the active runtime's tool-discovery capability to find and load the Ralph/job MCP tools:
- ```
- tool discovery query: "+ouroboros ralph job"
- ```
- 2. The loaded tools may be exposed under plugin-prefixed names such as
- `mcp__plugin_ouroboros_ouroboros__ouroboros_ralph`. Use the actual tool
- names returned by runtime tool discovery; the bare names below are the canonical MCP
- tool names for documentation.
- 3. Confirm that `ouroboros_ralph` and the job tools (`ouroboros_job_wait`,
- `ouroboros_job_status`, `ouroboros_job_result`, and
- `ouroboros_cancel_job`) are callable. If the tools are unavailable, stop and
- tell the user that Ralph requires the Ouroboros MCP runtime.
+ ### Loading MCP tools (deferred-schema guard)
- ### Ralph Flow
+ Ouroboros tools may be deferred, and a schema loaded on one turn can unload by the next. Immediately before each `ouroboros_*` call, load it with the active runtime's tool-discovery capability: `"+ouroboros ralph job"` for `ouroboros_ralph`, `ouroboros_job_wait`, `ouroboros_job_status`, `ouroboros_job_result`, and `ouroboros_cancel_job`; `"+ouroboros session signal"` for `ouroboros_session_signal_targets` and `ouroboros_session_signal`; `"+ouroboros conductor decision"` for `ouroboros_record_conductor_decision`. A call whose schema is not loaded fails with "Invalid tool parameters". If the tool is already callable, discovery is a no-op and an empty result is expected. If the tools are genuinely absent, stop and tell the user that Ralph requires the Ouroboros MCP runtime.
- 1. **Prepare lineage input**:
- - If the user provides an existing `lineage_id` and explicitly wants to
- continue it, reuse that `lineage_id` and omit `seed_content` unless they
- explicitly provide an updated Seed.
- - If the user provides Seed YAML for a new Ralph run, use it as
- `seed_content` and generate a fresh `lineage_id` for this run. Keep
- `lineage_id` separate from Seed, interview, and session IDs so separate
- Ralph runs over the same Seed do not collide.
- - If the user provides only a plain natural-language request, do not treat
- it as a direct `ooo ralph "<request>"` command, do not freehand Seed YAML,
- and do not pass raw text as `seed_content`. Route through the authoritative
- Seed path first: `ooo interview` to capture requirements, then `ooo seed` /
- `ouroboros_generate_seed` to produce validated Seed YAML with the normal
- ambiguity gate. After Seed generation, call the MCP tool with a fresh
- `lineage_id` and that validated Seed YAML as `seed_content`; do not use the
- raw request text. If an interview/seed session already exists in context,
- reuse that validated Seed output instead of regenerating it.
+ ### 1. Prepare lineage input
- 2. **Start Ralph** by calling `ouroboros_ralph` with:
- - `lineage_id`: existing lineage id for an explicit continuation, otherwise a
- freshly generated stable id for this Ralph run, such as
- `ralph-<short-slug>-<uuid>`; do not use a Seed/interview id by itself
- - `seed_content`: valid Seed YAML for generation 1 when starting a new lineage
- - `execute`: default `true`
- - `parallel`: default `true`
- - `skip_qa`: default `false`
- - `project_dir`: explicit target project directory when known
- - `max_generations`: default `10` unless the user requests a tighter bound
+ - **Continue a lineage**: when the user gives an existing `lineage_id` and wants to continue it, reuse it and omit `seed_content` unless they supply an updated Seed.
+ - **New run from Seed YAML**: use it as `seed_content` with a fresh `lineage_id` such as `ralph-<short-slug>-<uuid>`. Never reuse a Seed, interview, or session id as the lineage id, so separate runs over one Seed do not collide.
+ - **Plain natural-language request**: never pass raw text as `seed_content` or freehand Seed YAML. Run `ooo interview` and `ooo seed` first (or reuse a validated Seed in context), then start with a fresh `lineage_id`. Without inputs the tool returns input guidance instead of a job.
- 3. **Handle the start response**:
- - If `response.meta.job_id` is present, report it concisely and retain the
- job cursor from `response.meta.cursor`:
+ ### 2. Start Ralph
- ```
- [Ralph] Started background loop: <job_id>
- Lineage: <lineage_id>
- Live view: <dashboard_url, or `ouroboros tui open`>
+ Call `ouroboros_ralph` with `lineage_id`, `seed_content` (generation 1 of a new lineage), `execute` (default `true`), `parallel` (default `true`), `skip_qa` (default `false`), `project_dir` when known, and `max_generations` (default `10`, also the hard max; lower it only on request).
- A read-only observer will post meaningful progress, attention, and terminal
- events here. This conversation remains available for other safe work.
- ```
+ ### 3. Handle the start response
- - If `response.meta.job_observer` is unavailable, recover it from the final
- `<!-- ouroboros-job-observer-v1 base64 ... -->` content sentinel. Fail
- closed unless the bounded payload passes canonical v1 validation and its
- job identity matches the visible start receipt. Use that ID only as an
- identity anchor, never to reconstruct tools or arguments. Reject validation
- failure or any mismatch between structured and inline surfaces.
+ - **Job started** (`response.meta.job_id` present): keep `response.meta.cursor` and report:
- - If the structured or recovered `job_observer` is present and the host
- supports an independent child session, spawn exactly one read-only
- observer and pass that contract unchanged. The observer exclusively owns
- job wait/result calls and the cursor. The main session retains only user
- conversation, explicit on-demand status, and cancellation when the user
- requests it. The main session must not poll the same job while the observer
- is active. It may refine requirements, perform read-only review, or work in
- an unrelated isolated worktree; check active-worker conflicts before
- writing to Ralph's workspace.
- On Codex, call `spawn_agent` exactly once with `task_name="run_observer"`;
- `wait` is not a spawn, and do not claim an observer until a live child
- ID/path is returned. Once acknowledged, keep the parent turn open with
- `wait_agent` calls of at most 60 seconds while the observer is active. Child
- `send_message` calls only enqueue mailbox events and cannot revive an ended
- parent turn. Relay meaningful updates and wait again until terminal.
- On OMP, submit exactly one native Task child named `RunObserver`, require
- its live agent/job ID, and use the host wait/inbox relay until terminal.
- User input may interrupt the wait; handle it and resume
- waiting while observation remains active unless the user asks to stop live
- observation or replaces the active request. Then end only the relay loop,
- keep the durable job running, and offer next-turn or explicit-status catch-
- up. If the observer child fails, is cancelled, or exits before a terminal
- summary, use that same fallback instead of waiting indefinitely. This relay
- loop must not poll the Ouroboros job or take cursor ownership. If spawn
- fails, do not promise live proactive relays: the detached worker continues
- after the stdio turn, and the main session catches up from durable events
- on the next interaction or explicit status request. Keep the main turn open
- in the fallback polling loop only when the user asked for live watching.
+ ```
+ [Ralph] Started background loop: <job_id>
+ Lineage: <lineage_id>
+ Live view: <dashboard_url, or `ouroboros tui open`>
- - If `response.meta.status == "delegated_to_plugin"` and
- `response.meta.job_id is None`, report that OpenCode plugin mode delegated
- the loop to a child Task session. Do not call `ouroboros_job_wait`,
- `ouroboros_job_result`, or `ouroboros_cancel_job` without a job id; follow
- the host Task widget/session lifecycle instead.
+ A read-only observer will post meaningful progress, attention, and terminal
+ events here. This conversation remains available for other safe work.
+ ```
- 4. **Monitor non-plugin job progress in the polling owner** when a `job_id` exists.
+ - **Observer handoff**: if `response.meta.job_observer` is missing, recover it from the final `<!-- ouroboros-job-observer-v1 base64 ... -->` content sentinel; fail closed unless it passes canonical v1 validation and its job identity matches the visible start receipt, and use it only as an identity anchor, never to reconstruct tools or arguments. When the host supports an independent child session, spawn exactly one read-only observer and pass the contract unchanged. The observer exclusively owns job wait/result calls and the cursor; the main session keeps user conversation, explicit on-demand status, and user-requested cancellation. The main session must not poll the same job while the observer is active. It may refine requirements, do read-only review, or work in an unrelated isolated worktree; check active-worker conflicts before writing to Ralph's workspace.
+ - **Codex**: call `spawn_agent` exactly once with `task_name="run_observer"`; `wait` is not a spawn, so claim no observer until a live child ID/path returns. Then keep the parent turn open with `wait_agent` calls of at most 60 seconds while the observer is active. Child `send_message` calls only enqueue mailbox events and cannot revive an ended parent turn. Relay meaningful updates and wait again until terminal.
+ - **OMP**: submit exactly one native Task child named `RunObserver`, require its live agent/job ID, and use the host wait/inbox relay until terminal.
+ - User input may interrupt the wait; handle it and resume waiting unless the user asks to stop live observation or replaces the request. Then end only the relay loop, keep the durable job running, and offer next-turn or explicit-status catch-up. Use the same fallback, instead of waiting indefinitely, if the observer child fails, is cancelled, or exits before a terminal summary. The relay loop must not poll the Ouroboros job or take cursor ownership.
+ - If spawn fails, promise no live relays: the detached worker continues after the stdio turn, and the main session catches up from durable events on the next interaction or explicit status request.
+ - **OpenCode plugin delegation** (`response.meta.status == "delegated_to_plugin"`, `job_id` is `None`): a child Task session owns the loop. Never call job tools without a job id; treat the child Task result as the terminal surface and summarize its completion/error state and lineage id.
- The delegated observer is the default owner. Use the main-session loop below
- only when no independent child session exists and the user explicitly asked
- for live watching; otherwise catch up on the next parent turn. Never run both
- loops:
+ ### 4. Monitor (polling owner only)
- - `ouroboros_job_wait(job_id, cursor, timeout_seconds=120, stream="linked", wait_for="attention_or_ac_change")` for long polling;
- after every wait/status response, update `cursor = response.meta.cursor`
- - `ouroboros_job_status(job_id)` for a quick status check
- - `ouroboros_job_result(job_id)` when the job is terminal
- - `ouroboros_cancel_job(job_id)` if the user says stop/cancel
+ The observer is the default owner. Run this loop in the main session only when no independent child session exists and the user explicitly asked for live watching; otherwise catch up on the next turn. Never run both:
- Observer events are concise: relay phase/progress changes in 1-2 lines,
- surface `attention_required` immediately, present `terminal` as the final
- result, distinguish Synapse `queued` from runtime-proven `applied`, surface
- rejected/uncertain delivery immediately, and suppress unchanged heartbeats or
- raw tool output. Render every relay in the user's current conversation
- language; preserve raw event codes only when exact diagnostics help.
- Interpret structured subtypes: report run configuration, total ACs and
- dependency/parallel levels, first scheduled ACs, bounded Discover targets,
- current model/harness changes, level transitions, and verified AC completion.
- Say "currently running with" because later generations may escalate or switch
- harnesses. Never forward raw commands or model reasoning.
+ - `ouroboros_job_wait(job_id, cursor, timeout_seconds=120, stream="linked", wait_for="attention_or_ac_change")` for long polling;
+ after every wait/status response, update `cursor = response.meta.cursor`
+ - `ouroboros_job_status(job_id)` for a quick status check
+ - `ouroboros_job_result(job_id)` when the job is terminal
+ - `ouroboros_cancel_job(job_id)` if the user says stop/cancel
- When a new generation starts, do not just report the generation number —
- `lineage.generation.started` carries an `ac_focus` block
- (`active_ac_indices`, `frozen_ac_indices`, `active_ac_descriptions`,
- `reason`). Report WHAT the generation is redoing, e.g.
- "Gen 7: 2/5 AC 재작업 — 'CSV export writes summary.csv', 'CLI exits 0 on
- --help' (3 AC는 이전 PASS 증거로 frozen)". When `ac_focus` is absent or
- every AC is active with reason "initial/full generation", say the full AC
- graph is being executed. Never quote verify commands or expected outputs —
- descriptions only.
+ Relay rules: 1-2 lines per change; surface `attention_required` and rejected or uncertain delivery immediately; distinguish Synapse `queued` from runtime-proven `applied`; never forward heartbeats, raw tool output, commands, or model reasoning. Report run configuration, AC count and parallel levels, first scheduled ACs, and verified AC completion; say "currently running with", since later generations may switch model or harness. When `lineage.generation.started` carries `ac_focus`, report what the generation is redoing from `active_ac_descriptions` and how many ACs stay frozen (for example "Gen 7: reworking 2/5 ACs, 3 frozen on prior PASS evidence"); if it is absent or every AC is active, say the full AC graph is running. Never quote verify commands or expected outputs.
- When the user asks a live AC a read-only question or provides additive intent,
- reload `+ouroboros session signal`, call
- `ouroboros_session_signal_targets` for the observed execution, and select the
- semantically relevant AC without asking for internal IDs. Use
- `mode="inform"` for assurance/questions and omit `fallback_mode` in that
- mode. For implementation refinement use
- `contract_effect="additive"`, `source="user"`, `mode="redirect"`, and explicit
- `fallback_mode="after_turn"` with the exact discovered guards. Shared goal/AC/
- constraint/non-goal changes require an approved shared successor.
+ When the user asks a live AC a read-only question or adds intent, call `ouroboros_session_signal_targets` for the observed execution and pick the relevant AC without asking for internal IDs. Use `mode="inform"` for questions and assurance, and omit `fallback_mode` in that mode. For implementation refinement use `contract_effect="additive"`, `source="user"`, `mode="redirect"`, and explicit `fallback_mode="after_turn"` with the exact discovered guards, sent via `ouroboros_session_signal`. Shared goal, AC, constraint, or non-goal changes require an approved shared successor.
- 5. **On non-plugin job termination**, the polling owner fetches
- `ouroboros_job_result(job_id)` and
- summarize the final job result and next step:
- - Success / convergence: summarize the final generation output, QA verdict,
- and any `worktree_path` / `worktree_branch` returned in job metadata. Do not
- present `ooo evaluate` as an automatic next step for Ralph results: the
- Ralph job contract preserves the evolution `lineage_id`, but it does not
- reliably preserve a separate execution `session_id` for the evaluate
- workflow. If a valid execution `session_id` is explicitly available from a
- separate run result, keep it distinct from the Ralph `lineage_id` and follow
- the `ooo evaluate <session_id>` contract; otherwise state that formal
- evaluation needs a real execution session and should not be invoked from the
- Ralph lineage id alone.
- - Max generations / failure: summarize the stop reason and suggest
- `ooo unstuck`, `ooo interview`, or a narrower Ralph retry
- - Cancelled: confirm cancellation and preserve the job id for later inspection
+ ### 5. On termination
- 6. **On OpenCode plugin delegation**, rely on the child Task result as the
- terminal surface. Summarize the Task completion/error state and lineage id; do
- not claim a local Ralph job can be polled or cancelled.
+ The polling owner fetches the job result, then:
+ - **Success / convergence**: summarize the final generation, QA verdict, and any `worktree_path` / `worktree_branch`. A Ralph `lineage_id` is not an execution `session_id`: offer `ooo evaluate <session_id>` only when a real execution session id is available from a separate run.
+ - **Max generations / failure**: summarize the stop reason and suggest `ooo unstuck`, `ooo interview`, or a narrower Ralph retry.
+ - **Cancelled**: confirm and keep the job id for later inspection.
### Active Conductor decision policy
- For `attention_required`, use at most one short-lived read-only verifier. If the
- host has no verifier primitive, surface the evidence and do not mutate.
- Otherwise VERIFY → DECIDE from `recommended_host_actions` → LOG `selected` with
- `ouroboros_record_conductor_decision` → ACT only a menu-listed registered tool →
- LOG exactly one `completed`, `failed`, or `declined` outcome. Ralph may apply a
- conductor directive only to the first and sole bounded successor generation
- (`max_generations=1`), and only when it is deterministic and non-relaxing. Never
- silently retry or weaken the approved shared contract.
-
- These are English canonical host instructions. Render them naturally in the
- user's conversation language.
-
- ## Tool Mapping
-
- | Skill action | MCP tool |
- | --- | --- |
- | Start Ralph loop | `ouroboros_ralph` |
- | Wait for progress | `ouroboros_job_wait` |
- | Fetch final result | `ouroboros_job_result` |
- | Cancel loop | `ouroboros_cancel_job` |
- | Inspect current status | `ouroboros_job_status` |
-
- ## The Boulder Never Stops
-
- This is the key phrase. Ralph does not give up:
+ For `attention_required`, use at most one short-lived read-only verifier. If the host has no verifier primitive, surface the evidence and do not mutate. Otherwise VERIFY → DECIDE from `recommended_host_actions` → LOG `selected` with `ouroboros_record_conductor_decision` → ACT only a menu-listed registered tool → LOG exactly one `completed`, `failed`, or `declined` outcome. Ralph may apply a conductor directive only to the first and sole bounded successor generation (`max_generations=1`), and only when it is deterministic and non-relaxing. Never silently retry or weaken the approved shared contract.
- - Each failure is data for the next attempt.
- - Verification drives the loop.
- - Only success, convergence, terminal failure, cancellation, or max-generation
- limits stop it.
+ These are English canonical host instructions. Render them, and every relay, naturally in the user's conversation language.
## RFC #1392 State Breadcrumb Footer
- Your final response MUST end with exactly one breadcrumb footer line:
-
- ```
- ◆ <current state> → next: <recommended action>
- ```
-
- Derive `<current state>` from live session state via `ouroboros_session_status` when that MCP projection is available; otherwise derive it from this skill's actual outcome. Never use a linear `Step N of M` footer because Ouroboros is an evolutionary loop. When the next action is genuinely a choice, list 2-3 honest options in the `next:` clause. The breadcrumb line must be the last line of the response.
+ End the final response with exactly one line `◆ <current state> → next: <recommended action>`. Derive the state from live session state via `ouroboros_session_status` when available, otherwise from this skill's actual outcome. Never use a linear `Step N of M` footer; when the next step is a real choice, list 2-3 options.