/maestro-ralph

name: maestro-ralph
disable-model-invocation: false
description: "Closed-loop policy over the canonical Session/Run chain"
argument-hint: "<intent> [-y] [-c] [--amend]"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - AskUserQuestion
  - Agent
  - SendMessage
  - TaskCreate
  - TaskUpdate
session-mode: run
contract:
  discovery: self-described
  consumes: []
  produces: []

<required_reading> @~/.maestro/workflows/run-mode.md @~/.maestro/workflows/orchestrator-run-loop.md @~/.maestro/prepare/ralph.md </required_reading>

If any required file above was not expanded into context by the host, or its content is no longer in context, Read it explicitly before executing the state machine.

<deferred_reading>

• [ralph-amend-goal.md](~/.maestro/workflows/ralph-amend-goal.md) — read only for `--amend`

</deferred_reading>

<purpose> Apply retry, confidence, drift, goal-audit and stopping policy over the exact current Session chain of a durable topic Session. Ralph does not own a CLI driver, private Session type, host-only lease, or second state store; it follows the shared session/3.0 Run loop. Primary path: locate and drive an existing Session. Opening a Session is a fallback when no compatible identity exists. </purpose>

<interface> Only these user flags are accepted:

• `-y` — skip all confirmation/clarification interactions, use default choices. Does NOT change data semantics (no auto-deferred decisions). Never bypasses: high-risk classification, confidence <60, ambiguity requiring user input, failed gates, or drift escalation.
• `-c` — continue the unique compatible Session's exact current chain; a stuck Run enters `run check` / `run transition` / `run cancel` recovery.
• `--amend` — amend the exact current Session objective/definition-of-done; remaining text is the change request.

All remaining text is intent. No engine, roadmap, script, depth, role, tier, platform, resume or dry-run flags are parsed. Those choices belong to Skill contracts and Runtime. </interface>

<invariants> 1. **Ralph owns policy, not authority** — locate Session identity -> bind exact session_id + orchestration_revision -> dispatch -> check -> drift evaluation -> complete/decide -> next -> session complete. 2. **One executor per Run** — dispatch one unnamed `run-executor`; nested execution strategy belongs to the Skill. 3. **Thin executor** — executor executes and checks one Run but never receives the private claim or completes it. 4. **Session owns chain and lifecycle** — Session is a durable topic grouping/index that owns the chain, decisions, artifact registry, and the orchestration_revision CAS fence; Runs own immutable attempts and outputs. There is no Execution, no lease, no pause/resume/seal. 5. **Canonical upstream map** — same-Session sealed outputs enter only through birth/brief; no manual context reconstruction. 6. **Runtime mutation authority** — protocol JSON is never written directly; canonical mutation uses exact `maestro session ...` / `maestro run ...` commands and `run-response/1.2` envelopes. 7. **Proposal governance** — Skill proposes, Ralph evaluates budget/confidence/intent, Runtime applies atomically inside the Session chain (`session chain insert|replace|skip`). 8. **No prompt fix templates** — fix/review/goal gaps dispatch a Skill that may emit a proposal. 9. **Decision receipts are single-source** — decisions land through fenced `maestro run decide`, never direct append. 10. **Auto is bounded** — `-y` cannot bypass high risk, confidence <60, ambiguity, escalation, failed gates or reground halt. 11. **Legacy compatibility is out of band** — Session lifecycle aliases are allowed only by the labeled `session/1.x` branch in the shared loop. 12. **Session terminality** — a completed Session never hosts new Runs until unarchived; the Session identity may be unarchived and extended. 13. **Decision is mandatory** — every Ralph-created Session chain contains at least one formal decision node before `session complete`; Run completion never substitutes for `run decide`. 14. **Completion and decision both continue** — after successful `run complete --json` or `run decide --json`, consume the fresh `orchestration_revision` and immediately execute any satisfiable automatic continuation in the same turn. 15. **Capability negotiation is mandatory** — before mutation, call `maestro capabilities --json`; require the v3 six-key exact contract (`session_run_minimal_v3`/`entity_revision_cas`/`participant_identity`/`request_receipts_v2` true, `execution_lease`/`operation_registry` false, `session_schema_writes` containing `session/3.0`, `execution_schema_writes` empty, `run_response_writes` containing `run-response/1.2`), otherwise fail closed or enter the explicitly selected legacy branch. </invariants>

<state_machine>

<states> S_PARSE — parse intent and the three public flags S_RESOLVE — locate or create a compatible Session S_INFER — infer lifecycle position and roadmap need S_DECOMPOSE — derive boundary and observable goals for a new Session S_ASSESS — classify creation risk and evidence confidence S_BUILD — build initial Skill chain S_CREATE — open/resolve Session identity, bootstrap its chain S_CONFIRM — confirm unless `-y` S_RUN_LOOP — shared v3 Run lifecycle (`run next` → execute → check → complete/decide) S_EVALUATE — quality/goal/scope/reground decision S_AMEND — audited goal amendment S_RECOVER — audited recovery for an open decision gate or stuck Run S_FAIL — retry or stop; retry exhaustion leaves the chain step pending (no paused Execution) S_DONE — complete the current Session </states>

<transitions> S_PARSE: → S_AMEND WHEN: `--amend` → S_RESOLVE WHEN: `-c` or intent present → S_FAIL OTHERWISE

S_RESOLVE: -> S_RECOVER WHEN: exact current Session has an open decision gate or a stuck Run and `-c` -> S_RUN_LOOP WHEN: exact current Session is `open` with a chain and a valid orchestration_revision fence -> S_INFER WHEN: only a gated/stuck Session exists an