/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>

<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 any compatible canonical Session. Ralph does not own a CLI driver, private Session type or second state store; it calls only `maestro run ...` and follows the shared Run loop. Primary path: locate and drive an existing Session. Session creation is a fallback when no compatible Session 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 live compatible Session; paused state enters audited recovery.
• `--amend` — amend the live Session goal; 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 the policy loop** — locate → allocate → brief → dispatch → check → drift/proposal evaluation → done/decide → next → seal. 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 completes it. 4. **Sessions are topic grouping/indexes** — execution, handoff, anchor and immutable outputs belong to Runs. 5. **canonical upstream map** — same-Session sealed outputs enter only through birth/brief; no manual context reconstruction. 6. **Runtime mutation authority** — session.json/run.json are never written directly; normal flow uses only `maestro run ...`. 7. **Proposal governance** — Skill proposes, Ralph evaluates budget/confidence/intent, Runtime applies atomically with the producing Run. 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 `session decide`, never direct append. 10. **Auto is bounded** — `-y` cannot bypass high risk, confidence <60, ambiguity, escalation, failed gates or reground halt. 11. **Compatibility commands are out of band** — no Ralph/Session CLI is called or recommended. 12. **Terminal means terminal** — sealed/archived returns `CHAIN_COMPLETE`, never resume. 13. **Decision is mandatory** — every Ralph-created chain contains at least one formal decision node before Session seal; Run completion never substitutes for `session decide`. 14. **Completion and decision both continue** — after successful `session done --json` or `session decide --json`, immediately execute any satisfiable `continuation.authority=automatic` action in the same turn. </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 — `session create --chain-file` S_CONFIRM — confirm unless `-y` S_RUN_LOOP — shared Run lifecycle S_EVALUATE — quality/goal/scope/reground decision S_AMEND — audited goal amendment S_RECOVER — audited paused recovery S_FAIL — retry or pause; retry budget exhausted implies Session auto-paused. (Distinct from maestro's S_FALLBACK, which requests missing intent/disambiguation before any Session exists; S_FAIL operates on an already-created Session.) S_DONE — seal 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 compatible Session is paused and `-c` → S_RUN_LOOP WHEN: exact compatible Session is running with a chain → S_INFER WHEN: only paused Session exists and no `-c` (treat as new intent; paused Session remains untouched) → S_INFER WHEN: no live Session and intent present → S_FAIL WHEN: multiple candidates or incompatible terminal Session

S_INFER → S_DECOMPOSE → S_ASSESS → S_BUILD → S_CREATE S_CREATE → S_RUN_LOOP WHEN: `-y` AND risk ≠ high AND confidence_score ≥ 60 S_CREATE → S_CONFIRM WHEN: `-y` AND (risk == high OR confidence_score < 60) S_CREATE → S_CONFIRM OTHERWISE S_CREATE → S_FAIL WHEN: creation fails (delete temp file, report error) S_CONFIRM → S_RUN_LOOP WHEN: confirmed S_CONFIRM → S_BUILD WHEN: revised S_CONFIRM → END WHEN: cancelled

S_RUN_LOOP: → S_EVALUATE WHEN: next node is a decision → S_FAIL WHEN: executor/check/drift reports retry or blocker → S_DONE WHEN: `CHAIN_COMPLETE` → S_DONE WHEN: no pending steps and no `CHAIN_COMPLETE` (implicit completion) → S_RUN_LOOP WHEN: Run sealed and another pending step exists

S_EVALUATE: → S_RUN_LOOP WHEN: proceed or accepted fix proposal → S_RECOVER WHEN: escalate pauses Session → S_FAIL WHEN: escalate but Session not paused (user declined pause) → S_RUN_LOOP WHEN: post-goal-audit AND has_unmet (fix loop; insert repair step at `target_stage`) → S_DONE WHEN: post-goal-audit AND all_met AND INTENT_ALIGNED → END WHEN: post-goal-audit AND all_met AND NOT INTENT_ALIGNED (REGROUND_HALT) →