git:20261016.c16e9e3 to git:20261016.d3f01ba

139 added, 468 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: ouroboros-run
description: "Use when an Ouroboros Seed (a spec file with a goal and acceptance criteria, such as *.seed.yaml) already exists and the user wants it executed: 'run the seed', 'execute this spec', 'ooo run'. Executes it and verifies every acceptance criterion. Not for raw requests without a Seed (use interview or auto)."
aliases: [execute]
mcp_tool: ouroboros_execute_seed
mcp_args:
seed_path: "$1"
cwd: "$CWD"
---
# /ouroboros:ouroboros-run
- Execute a Seed specification through the Ouroboros workflow engine.
+ Execute a Seed specification through the Ouroboros workflow engine as a background job. A completed run enqueues formal evaluation by default, and a rejection continues through a bounded Ralph loop.
## Usage
```
/ouroboros:ouroboros-run [seed_file_or_content]
```
- **Trigger keywords:** "ouroboros run", "execute seed"
-
- ## How It Works
-
- 1. **Input**: Provide seed YAML content directly or a path to a `.yaml` file
- 2. **Validation**: Seed is parsed and validated (goal, constraints, acceptance criteria, ontology)
- 3. **Execution**: The orchestrator runs the workflow with PAL routing
- 4. **Progress**: Real-time progress updates via session tracking
- 5. **Result**: Execution summary with pass/fail status
- 6. **Convergence**: completed runs enqueue formal evaluation by default. An
- explicit rejection continues through a bounded Ralph loop until approved or
- the configured evolution budget/stop condition is reached.
-
## 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. **You MUST perform this step before proceeding.**
-
- 1. Use the active runtime's tool-discovery capability to find and load the execution MCP tools:
- ```
- tool discovery query: "+ouroboros execute"
- ```
- 2. The tools will typically be named with prefix `mcp__plugin_ouroboros_ouroboros__` (e.g., `ouroboros_execute_seed`, `ouroboros_session_status`). After runtime tool discovery returns, the tools become callable.
- 3. If the tools are callable — already exposed, or loaded by discovery — proceed with the steps below. An empty discovery result for already-exposed tools is expected, not a failure. Skip to the **Fallback** section only if they are genuinely absent (no Ouroboros MCP server).
-
- **IMPORTANT**: Do NOT skip this step. Do NOT assume MCP tools are unavailable just because they don't appear in your immediate tool list. They are almost always available as deferred tools that need to be loaded first.
+ ### Loading MCP tools (deferred-schema guard)
- **CRITICAL — deferred-schema guard (prevents "Invalid tool parameters"):**
- This skill makes execution MCP calls across multiple turns, and each turn runs
- in a fresh tool context. A deferred tool's schema loaded on one turn is NOT
- guaranteed to still be loaded on the next. If you call any execution `ouroboros_*`
- MCP tool while its schema is not loaded in the **current** turn, the runtime
- rejects the call with **"Invalid tool parameters"** before it reaches the server.
- Therefore: **immediately before EVERY execution MCP call in this skill, re-run
- `tool discovery query: "+ouroboros execute"`** to reload the execution tool family,
- including `ouroboros_start_execute_seed`, `ouroboros_job_wait`,
- `ouroboros_ac_tree_hud`, and `ouroboros_job_result` (idempotent — a no-op when
- already loaded). If the load returns no matching tool (and the tool is not already callable — an empty load for an already-exposed tool is an expected no-op, not absence), switch to the documented
- fallback instead of retrying the failing call.
+ 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 execute"` for `ouroboros_start_execute_seed`, `ouroboros_job_wait`, `ouroboros_job_result`, and `ouroboros_ac_tree_hud`; `"+ouroboros session signal"` for `ouroboros_session_signal_targets` and `ouroboros_session_signal`. 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. Use the **Fallback (No MCP Server)** section only when the tools are genuinely absent.
### Execution Steps
1. **Do not create or switch branches yourself.** For a background execution
job, `use_worktree` defaults to true: the server runs the task in its own
worktree and reports `worktree_path` / `worktree_branch` in the job result.
Tell the user the task was isolated only when those fields are present. A
`dispatch_mode="plugin"` response delegates to a child session and carries
no worktree.
- 2. Check if the user provided seed content or a file path:
- - If a file path: Read the file with the Read tool
- - If inline YAML: Use directly
- - If neither: Check conversation history for a recently generated seed
+ 2. **Get the Seed.** Read a given file path with the active runtime's `inspect_code` capability, use inline YAML directly, or otherwise take the most recently generated Seed in the conversation.
Before a fresh start, do not ask about an efficiency policy unless the user
raised it or `execution.default_policy` in `~/.ouroboros/config.yaml` is
explicitly `ask`. Otherwise omit both arguments: the server applies the
- configured default, which is quality-first when nothing is configured.
- After the start, tell the user once which policy is running, using the
- `Efficiency Mode` line of the handoff; when it names the default, include
- the change command it shows. If the user did choose, or the config says
- `ask`, map the choice in outcome language:
+ configured default (quality-first when nothing is configured), and its start
+ receipt names the running policy and the change command. If the user did
+ choose, or the config says `ask`, map the choice in outcome language:
- - **Efficient execution** — start parallel/decomposed work economically and
+ - **Efficient execution**: start parallel/decomposed work economically and
strengthen the route only when recovery requires it. Send
`efficiency_mode="adaptive"` and `frugality_assurance="observe"`.
- - **Quality-first execution** — keep child work at the parent starting tier.
+ - **Quality-first execution**: keep child work at the parent starting tier.
Send `efficiency_mode="quality_first"` and `frugality_assurance="off"`.
`frugality_assurance="strict"` is a separate explicit opt-in because it may
- spend extra work on proof. Never enable it merely because efficient execution
- was chosen. Do not ask again on resume; the server restores the persisted
- policy and rejects an attempted resume-time change.
+ spend extra work on proof; never infer it from the efficiency choice. Do not
+ ask again on resume: the server restores the persisted policy and rejects a
+ resume-time change.
- 3. **Start background execution** with `ouroboros_start_execute_seed`:
+ 3. **Start background execution:**
```
Tool: ouroboros_start_execute_seed
Arguments:
seed_content: <the seed YAML>
efficiency_mode: <only when chosen: adaptive or quality_first>
frugality_assurance: <only when chosen: observe, off, or explicit strict>
- max_iterations: 10 (or as specified by user)
+ session_id: <only when resuming an existing session>
```
Omit `model_tier` by default so the runtime selects automatically. Include
`model_tier: <user choice>` only when the user explicitly requested a tier.
- This returns immediately with a `job_id`, `session_id`, and `execution_id`.
-
- 4. If resuming an existing session, include `session_id`:
- ```
- Tool: ouroboros_start_execute_seed
- Arguments:
- seed_content: <the seed YAML>
- session_id: <existing session ID>
- ```
-
- 5. **Recommended monitoring stance: delegate observation to one child session.**
-
- **TUI surfacing at job start (RFC #1392):**
-
- After `job_id`, `session_id`, and `execution_id` are returned, surface a live
- view once without delaying execution or observer delegation:
-
- - If `response.meta.dashboard_url` exists, show it as the primary live view.
-
- - If `execution.tui_autolaunch: true` (or legacy top-level
- `tui_autolaunch: true`) is present in the loaded Ouroboros config, run
- `ouroboros tui open` unconditionally and mention the dashboard in one
- short line.
- - Otherwise mention once that the TUI can be opened in a new terminal with
- `ouroboros tui open`. Offer to open it, but do not block the run waiting for
- an answer. Remember the answer for this session and do not repeat the offer.
- - If the user accepts, run `ouroboros tui open`.
- - If `ouroboros tui open` reports a manual command because the environment
- is headless, SSH, or unsupported, relay that command once and continue.
- - The dashboard is an external observer. It does not change which chat
- session owns MCP polling.
-
- After IDs are returned, print only this short handoff:
-
- ```
- Execution started in background.
- Job ID: <job_id>
- Session ID: <session_id>
- Execution ID: <execution_id>
- Live view: <dashboard_url, or `ouroboros tui open`>
- Runtime/harness: <response.meta.runtime_backend>
- LLM backend: <response.meta.llm_backend>
- Efficiency: <response.meta.efficiency_mode>
- Frugality assurance: <response.meta.frugality_assurance>
-
- Observation: <confirmed read-only child observer, or durable catch-up mode>.
- With a confirmed observer, meaningful progress, attention, and completion
- events will be posted here. Without one, the run still survives this turn
- and I will catch up from durable events on your next message or status request.
- This conversation stays available while the run continues.
- We can refine requirements, inspect or review code, or work on an unrelated
- task in an isolated worktree. I will check for active-worker conflicts before
- editing this run's workspace.
- For full details later: `ouroboros_ac_tree_hud(session_id=<session_id>)`
- ```
-
- **Text-only host compatibility (OMP and similar bridges):**
-
- If `response.meta.job_observer` is unavailable, inspect the response content
- for the final sentinel block:
-
- ```text
- <!-- ouroboros-job-observer-v1 base64
- <payload>
- -->
- ```
-
- Base64-decode `<payload>`, then fail closed unless it passes the canonical v1
- validation implemented by `extract_job_observer_inline_handoff`: exactly one
- bounded terminal sentinel; fixed protocol, role, ownership, wait/result tools,
- restrictions, and follow-result keys; internally consistent IDs; and a
- `job_id` matching the visible start receipt. Use visible Job/Session/Execution
- IDs only as identity anchors, never to reconstruct the nested contract. If
- structured and inline surfaces differ or validation fails, do not spawn an
- observer; report a transport-integrity failure.
-
- When a structured or recovered `job_observer` is present and the host has an
- independent child/subagent session primitive, spawn exactly one observer
- session and pass that object unchanged. Codex uses `spawn_agent`, OMP uses
- one native Task child, and Claude Code uses one Task/Agent child. The observer must:
-
- - On Codex, call the native `spawn_agent` primitive exactly once with
- `task_name="run_observer"` and include the structured or recovered
- `job_observer` unchanged in the child message. A `wait` call is not a spawn.
- - Require the spawn result to return a live child ID/path before saying an
- observer is connected or before ending the start turn.
- - On OMP, submit exactly one Task item named `RunObserver` with the recovered
- or structured contract unchanged, require the returned live agent/job ID,
- and use the host wait/inbox relay until the observer returns terminal.
- A job-status poll in the parent is not an observer spawn.
-
- - remain read-only: no repository edits, execution control, or worker fan-out;
- - own the job cursor exclusively and reload deferred MCP schemas immediately
- before each observer tool call;
- - call the declared `wait.tool` with the declared arguments, update its local
- cursor from response meta, and repeat until terminal;
- - call the declared `result.tool` after terminal status;
- - follow any job IDs named by `follow_result_job_keys`, including chained
- formal evaluation, before returning one compact final summary;
- - send sparse progress notices only when the host supports child-to-parent
- messages and the state meaningfully changes.
-
- The main session must not poll the same job while the observer owns it. It may
- continue the user conversation, refine requirements, perform read-only
- inspection/review, handle explicit status/control requests, or work on an
- unrelated task in an isolated worktree. Before writing to the active run's
- workspace, check for overlap with worker files or isolate the work. If
- `job_id` is absent because plugin mode already delegated the whole execution,
- follow that plugin child lifecycle instead.
-
- On Codex, a confirmed observer also requires a parent relay loop. After
- `spawn_agent` returns a live child ID/path, keep the parent turn open with
- `wait_agent` calls of at most 60 seconds. A child `send_message` only queues a
- mailbox event and cannot wake a parent turn that has already ended. Relay
- meaningful observer updates, then wait again until the child returns its
- terminal summary. User input may interrupt the wait; handle it and resume the
- relay loop while the observer 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 wait loop must never call Ouroboros job tools or compete for the
- observer's cursor.
+ The call returns at once with `job_id`, `session_id`, and `execution_id`.
- Handle observer messages as events, not as a transcript:
+ 4. **Hand off.** Relay the server's start receipt (IDs, backends, `Efficiency Mode` with any change command, dashboard). Then add:
+ - Live view: if `execution.tui_autolaunch: true` (or legacy top-level `tui_autolaunch: true`) is set, run `ouroboros tui open`; otherwise offer it once without blocking. If it prints a manual command (headless, SSH), relay that once.
+ - Observation: a confirmed read-only observer (step 5), or durable catch-up mode.
+ - This conversation stays available: the user can refine requirements, review code, or work on an unrelated task in an isolated worktree; check for active-worker conflicts before editing this run's workspace.
- - `phase_changed` / `progress_advanced`: relay at most 1-2 concise lines.
- Interpret the structured subtype, not raw logs:
- - `run_configuration`: state the current runtime/harness, starting model or
- tier when known, efficiency mode, and frugality assurance. If the exact
- model is not known yet, say it will be reported by the first routing event.
- - `execution_plan`: state total ACs, total dependency/parallel levels,
- whether work can run in parallel, and the first scheduled AC summaries.
- - `discovery_summary`: say which bounded targets the AC is examining and
- the purpose; never expose search queries, raw commands, or reasoning.
- - `level_started` / `level_completed`: say which parallel level is active
- or finished and the meaningful success/failure counts.
- - `ac_routing` / `harness_changed`: say "currently running with" and report
- only initial routing or a real model/tier/harness change.
- - `ac_attempt_judged`: at most one line on the AC attempt outcome.
- - `ac_accepted` / `ac_rejected`: report the AC's final acceptance and its
- compact disposition evidence.
- - `attention_required`: surface the blocker or pending decision immediately
- and ask the user only when human judgment is required.
- - `terminal`: fetch/present the final result and any chained evaluation.
- - Synapse `.queued` / `.delivering`: say the exact AC has a pending or claimed
- intent signal and name
- the effective boundary; do not claim application yet.
- - Synapse `.applied` / `.completed`: confirm runtime-proven application and
- relay the bounded AC reply when present.
- - Synapse `.rejected` / `.delivery_uncertain`: surface immediately and never
- claim the AC changed course.
- - Suppress unchanged heartbeats and raw tool output.
+ 5. **Delegate observation to exactly one observer.** The start result carries
+ `response.meta.job_observer`, a read-only observer contract with its own wait
+ and result tools, `instructions`, `restrictions`, and fallback. If the
+ structured meta is missing, recover the contract from the final
+ `<!-- ouroboros-job-observer-v1 base64 ... -->` content sentinel and fail
+ closed: if there is more than one sentinel or it is not at the end of the
+ text, the bounded payload does not decode to an object whose only key is
+ `job_observer`, that contract fails canonical v1 validation (it must equal,
+ field for field, the v1 contract the server builds from its own `job_id`,
+ `cursor`, `session_id`, `execution_id`, and `follow_result_job_keys`, so a
+ changed tool, argument, or instruction, or an extra field, fails), its
+ `job_id` differs from the visible start receipt, or the structured and inline
+ contracts differ, do not spawn an observer and report a transport-integrity
+ failure. Never rebuild the contract from visible IDs.
- Render every relay in the user's current conversation language. Keep event
- codes and effective-mode values unchanged only when exact diagnostics help.
- These are English canonical host instructions. Phrase the facts naturally in
- the active conversation language.
+ With a valid contract and an independent child-session primitive, spawn
+ exactly one observer through the active runtime's `orchestrate_subagents`
+ capability and pass the contract unchanged. It owns the job cursor, follows
+ the contract (including `follow_result_job_keys` for chained evaluation and
+ Ralph), and stays read-only. Claim an observer only after the spawn returns
+ a live child ID/path. The main session must not poll the same job while the
+ observer owns it. If plugin mode already delegated the whole execution (no
+ `job_id`), follow that child's lifecycle instead.
- This ownership split is the default for SOL-class models: the main model
- performs one start handoff, while a small isolated context owns the repetitive
- wait/result state machine.
+ - On Codex, call `spawn_agent` exactly once with `task_name="run_observer"`
+ and the contract unchanged in the child message; a `wait` call is not a
+ spawn. After the live child ID returns, keep the parent turn open with
+ `wait_agent` calls of at most 60 seconds: a child `send_message` only
+ queues a mailbox event and cannot wake a parent turn that already ended.
+ Relay meaningful updates and wait again until the terminal summary. User
+ input may interrupt the wait; handle it and resume 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. If the observer child fails, is cancelled, or exits early, use
+ that same catch-up instead of waiting indefinitely. The relay loop must not
+ poll Ouroboros job tools or touch the observer's cursor.
+ - On OMP, submit exactly one native Task child named `RunObserver` with the
+ contract unchanged, require its live agent/job ID, and relay through the
+ host wait/inbox until terminal. A parent job-status poll is not a spawn.
- If child creation is unavailable, fails, or returns no live child, do not
- claim that an observer exists or promise live proactive messages. The
- detached worker survives the stdio MCP turn. Tell the user that progress is
- durable and will be caught up on the next parent turn or explicit status
+ If no child can be created, do not claim an observer or promise live
+ messages. The detached worker survives the stdio MCP turn: say progress is
+ durable and will be caught up on the next turn or an explicit status
request. Keep the turn open only when the user explicitly asked for live
- watching; then use the fallback below.
-
- 6. **Fallback: low-token relay loop in the main session.**
-
- Use this only when `response.meta.job_observer` is absent, the host has no
- independent child session primitive, and the user explicitly asked to keep
- watching in the current turn. Do not run it in parallel with a delegated
- observer. Otherwise end the turn safely and catch up from the same cursor on
- the next parent turn.
+ watching (step 6).
- Use `ouroboros_job_wait`, not repeated `ouroboros_ac_tree_hud`, for routine
- monitoring. Keep the latest cursor and previous progress counters from the
- tool meta payload.
+ **Relaying observer events.** Relay each meaningful event in 1-2 lines;
+ suppress unchanged heartbeats, raw tool output, commands, and reasoning.
+ - `run_configuration`: runtime/harness, starting model or tier when known,
+ efficiency mode, frugality assurance.
+ - `execution_plan`: total ACs, dependency/parallel levels, and the first
+ scheduled AC summaries.
+ - `discovery_summary`: bounded targets and purpose.
+ - `level_started` / `level_completed`, `ac_routing` / `harness_changed`
+ ("currently running with"), `ac_attempt_judged`: only real changes.
+ - `ac_accepted` / `ac_rejected`: the AC's final acceptance and compact
+ disposition evidence.
+ - `attention_required`: surface immediately (see Active Conductor below).
+ - Synapse `.queued` / `.delivering`: pending, not applied yet. `.applied` /
+ `.completed`: confirm and relay any bounded AC reply. `.rejected` /
+ `.delivery_uncertain`: surface immediately; never claim the AC changed
+ course.
- This loop is intentionally harness/model friendly:
- - Treat `response.meta` as the source of truth.
- - Do not parse `response.text` for counts, status, or cursor.
- - Use `response.text` only as a human-readable current-message hint.
- - Keep all local monitor state in simple scalar variables.
- - Emit at most one short relay message per changed response.
- - Always continue to final `ouroboros_job_result` after a terminal status.
+ These are English canonical host instructions: render every relay in the
+ user's current conversation language, keeping event codes and mode values
+ only when exact diagnostics help.
+ 6. **Fallback: live relay in the main session.** Only when there is no
+ observer contract or no child primitive, and the user explicitly asked to
+ keep watching this turn. Never run it beside a delegated observer;
+ otherwise end the turn and catch up from the same cursor next turn.
```
- cursor = <cursor from start/status response, or 0>
- prev_status = "running"
- prev_phase = null
- prev_ac_completed = 0
- prev_sub_ac_completed = 0
- prev_message = null
-
- loop:
- Tool: ouroboros_job_wait
- Arguments:
- job_id: <job_id from step 3>
- cursor: <cursor>
- timeout_seconds: 180
- view: "summary"
- stream: "linked"
- wait_for: "attention_or_ac_change"
-
- cursor = response.meta.cursor
-
- if response.meta.changed is false:
- # Do not narrate unless the user explicitly asked for heartbeat updates.
- continue
-
- status = response.meta.status
- phase = response.meta.current_phase
- ac_completed = response.meta.ac_completed
- ac_total = response.meta.ac_total
- sub_ac_completed = response.meta.sub_ac_completed
- sub_ac_total = response.meta.sub_ac_total
- # The metadata field names remain legacy-compatible; relay them to users as Task/Subtask progress.
- message_hint = first non-empty non-metadata line from response.text, or null
-
- # Build one short relay update from structured fields.
- if status in ["completed", "failed", "cancelled", "interrupted"]:
- print terminal_relay(status, phase, ac_completed, ac_total, sub_ac_completed, sub_ac_total)
- break
-
- if ac_completed > prev_ac_completed:
- print task_progress_relay(phase, ac_completed, ac_total, sub_ac_completed, sub_ac_total, message_hint)
- elif sub_ac_completed > prev_sub_ac_completed:
- print subtask_progress_relay(phase, ac_completed, ac_total, sub_ac_completed, sub_ac_total, message_hint)
- elif phase != prev_phase or status != prev_status:
- print phase_or_status_relay(status, phase, ac_completed, ac_total, sub_ac_completed, sub_ac_total)
- elif message_hint != prev_message:
- print current_work_relay(phase, ac_completed, ac_total, sub_ac_completed, sub_ac_total, message_hint)
-
- prev_status = status
- prev_phase = phase
- prev_ac_completed = ac_completed or prev_ac_completed
- prev_sub_ac_completed = sub_ac_completed or prev_sub_ac_completed
- prev_message = message_hint or prev_message
+ Tool: ouroboros_job_wait
+ Arguments:
+ job_id: <job_id>
+ cursor: <latest cursor, or 0>
+ timeout_seconds: 180
+ view: "summary"
+ stream: "linked"
+ wait_for: "attention_or_ac_change"
```
-
- Notes:
- - `timeout_seconds: 180` means the MCP call can block for up to 3 minutes.
- This keeps the main session available often enough for a live relay while
- still avoiding noisy polling.
- - Use `view: "compact"` for very long jobs or when the user only wants a
- heartbeat. The raw tool may still return legacy text such as
- `job_x | running | AC 3/17`; relay that to users as Task progress.
- - Use `view: "summary"` for normal monitoring. It includes the job message
- plus Task/Subtask counts derived from legacy `ac_completed`/`sub_ac_completed`
- metadata fields.
- - Use `view: "full"` only when the user asks for detailed job status.
-
- Relay style examples:
- - `In progress: Deliver is at Task 1/3 and Subtask 12/16. Current work is the Subtask 3 regression test.`
- - `Level update: parallel level 1/1 has finished, and Task progress advanced to 3/3.`
- - `Completed: execution finished. Fetching the final job result now.`
-
- Relay output contract for other harnesses/models:
- - One update should be 1-2 sentences or 1 compact line.
- - Include `phase`, Task completed/total and Subtask completed/total when present.
- - Include the current work hint only if it changes.
- - Never include the full task tree in routine relay output.
- - Never include raw JSON, raw meta dumps, or repeated unchanged cursor lines.
- - Terminal statuses must be explicit: completed, failed, cancelled, or interrupted.
-
- Do not paste the full raw tool output unless the user asks for raw status.
- Do not add speculative ETA unless the tool provides one.
-
- **Synapse intent refinement:** When the user gives additive implementation
- intent during an active run, the main session owns target selection; never ask
- the user for internal AC/session IDs.
-
- Immediately before each Synapse call, reload its deferred schemas with
- `tool discovery query: "+ouroboros session signal"`.
-
- 1. Take `execution_id` from the start result or observer contract and call
- `ouroboros_session_signal_targets(execution_id=...)`.
- 2. Match the user's meaning against each target's `ac_content`, display path,
- and current HUD activity when needed. One active target may be selected
- directly. With multiple targets, select only when one is materially more
- relevant; ask a short user-language clarification only for genuine ties.
- 3. For additive implementation refinement, call `ouroboros_session_signal`
- with the selected target's exact scope/attempt/execution guards,
- `contract_effect="additive"`, `source="user"`, `mode="redirect"`, and
- `fallback_mode="after_turn"`. Copy `expected_contract_version` when target
- discovery supplies it, and create one stable idempotency key for this exact
- user turn. If the target went stale, rediscover once instead of asking for
- IDs.
- 4. When the user asks the AC a read-only question or requests assurance rather
- than an implementation change, use `mode="inform"` and
- `contract_effect="additive"`, and omit `fallback_mode` entirely because it
- is valid only for redirect. Synapse runs a no-tools reply turn when the
- runtime supports it; relay the bounded reply from the completed event.
- 5. Tell the user which AC was selected and report the returned effective mode.
- Wait for observer `.applied` or `.completed` before saying it was reflected.
-
- Never use Synapse to change approved goals, ACs, constraints, or non-goals;
- those require an approved shared successor or replacement contract.
-
- **Active Conductor attention handling:** `recommended_host_actions` is the
- authoritative menu. Never invent a mutating tool call.
-
- 1. VERIFY with at most one short-lived read-only host child using the supplied
- evidence IDs. If the host has no verifier primitive, surface the attention
- and stop before mutation.
- 2. DECIDE among the ordered menu actions. Engine-owned retry/routing must be
- closed before any successor action is considered.
- 3. LOG `phase="selected"` through
- `ouroboros_record_conductor_decision` before ACT. For a specification
- change in run mode, obtain explicit user approval and bind its receipt.
- 4. ACT only when the menu names a currently registered MCP tool. A corrective
- successor must preserve the approved contract unless the user approved the
- shared specification change.
- 5. LOG exactly one terminal `completed`, `failed`, or `declined` outcome. Do
- not silently retry a failed conductor action.
-
- 7. **Use `ouroboros_ac_tree_hud` only for manual drill-down or anomaly checks.**
-
- Do not call full tree HUD in the normal polling loop.
-
- Use these targeted calls:
+ Replace the cursor from `response.meta.cursor` after every call. Treat
+ `response.meta` as the source of truth and `response.text` only as a hint.
+ If `response.meta.changed` is false, repeat silently; otherwise emit one
+ compact line (phase, AC/sub-AC counts, new current-work hint), never raw
+ JSON, the full tree, or an ETA. On `completed`, `failed`, `cancelled`, or
+ `interrupted`, say so explicitly and go to step 8.
+ 7. **Drill-down only.** Use `ouroboros_ac_tree_hud` when the user asks for
+ details or progress looks stuck, never in the routine loop. `view` is
+ `"compact"`, `"summary"`, or `"tree"` (add `max_nodes: 30`); treat
+ `unchanged cursor=<cursor>` as a silent no-op.
```
- # Explicit short HUD, useful for a one-off check
Tool: ouroboros_ac_tree_hud
Arguments:
session_id: <session_id>
cursor: <cursor>
view: "summary"
-
- # Lowest-token one-line HUD
- Tool: ouroboros_ac_tree_hud
- Arguments:
- session_id: <session_id>
- cursor: <cursor>
- view: "compact"
-
- # Full tree only when user asks "show details", progress looks stuck,
- # or debugging requires seeing the task/subtask structure.
- Tool: ouroboros_ac_tree_hud
- Arguments:
- session_id: <session_id>
- cursor: <cursor>
- view: "tree"
- max_nodes: 30
```
- Treat `unchanged cursor=<cursor>` from explicit compact/summary views as a
- no-op. Do not explain it to the user unless they explicitly asked for
- heartbeat messages.
-
- 8. **Fetch final result in the polling owner** with `ouroboros_job_result`.
-
- The delegated observer performs this call on the default path. The main
- session performs it only on the fallback path from step 6.
+ 8. **Fetch the final result in the polling owner** (the observer by default,
+ the main session only on the step 6 fallback):
```
Tool: ouroboros_job_result
Arguments:
job_id: <job_id>
```
-
- 9. Present the execution results to the user:
- - Show success/failure status
- - Show session ID (for later status checks)
- - Show execution summary
-
- 10. **Post-execution QA and formal evaluation** (automatic):
- `ouroboros_start_execute_seed` automatically runs QA after execution.
- The QA verdict is included in the final job result text. This QA check is
- **not** the formal 3-stage evaluator. On servers that return
- `chained_evaluate_job_id`, the run has already enqueued the formal
- evaluator as a separate bounded background job.
- To skip: pass `skip_qa: true` to the tool.
+ Present status, session ID, and summary. Its QA verdict (skippable with
+ `skip_qa: true` at start) is not the formal 3-stage evaluator.
- If the final run result meta contains `chained_evaluate_job_id`:
- - The current polling owner continues with that job ID
- - Fetch its verdict with `ouroboros_job_result` after terminal status
- - Render **APPROVED** when `final_approved: true`; otherwise render not approved and list failed ACs or the failure reason from the evaluation result
- - If the evaluate job failed or timed out, keep the run success intact and show `Next: ooo evaluate <session_id>` as the manual retry
- - If the evaluation result contains `chained_ralph_job_id`, continue observing
- that job before presenting the final outcome. Report approval/convergence or
- the bounded Ralph stop reason; do not call the run blocked merely because
- its first evaluation was rejected.
+ If the result meta has `chained_evaluate_job_id`, the polling owner follows
+ that job and fetches its result: render **APPROVED** when
+ `final_approved: true`, otherwise not approved with the failed ACs or
+ reason. If the evaluate job failed or timed out, keep the run success and
+ show `Next: ooo evaluate <session_id>` as the manual retry. If the
+ evaluation has `chained_ralph_job_id`, follow it too and report approval or
+ the bounded Ralph stop reason; a rejected first evaluation does not make
+ the run blocked.
- If `chained_evaluate_job_id` is absent, keep the legacy path verbatim:
+ Without `chained_evaluate_job_id`, show:
- **PASS**: `Next: ooo evaluate <session_id> for formal 3-stage verification`
- - **REVISE**: Show differences/suggestions, then `Next: Fix the issues above, then ooo run to retry -- or ooo unstuck if blocked`
+ - **REVISE**: the differences/suggestions, then `Next: Fix the issues above, then ooo run to retry -- or ooo unstuck if blocked`
- **FAIL/ESCALATE**: `Next: Review failures above, then ooo run to retry -- or ooo unstuck if blocked`
+ ### Synapse intent refinement
+
+ Synapse is the `ouroboros_session_signal` channel that delivers bounded user intent to one running AC. When the user adds implementation intent during an active run, the main session picks the target; never ask the user for internal AC or session IDs.
+
+ 1. Call `ouroboros_session_signal_targets(execution_id=...)` with the `execution_id` from the start result or observer contract.
+ 2. Match the user's meaning against each target's `ac_content`, display path, and current HUD activity. Select one active target directly; with several, select only a materially more relevant one, and ask a short clarification only for a genuine tie.
+ 3. Additive implementation refinement: call `ouroboros_session_signal` with the target's exact scope/attempt/execution guards, `contract_effect="additive"`, `source="user"`, `mode="redirect"`, `fallback_mode="after_turn"`, `expected_contract_version` when discovery supplies it, and one stable idempotency key for this user turn. If the target went stale, rediscover once instead of asking for IDs.
+ 4. Read-only question or assurance request: use `mode="inform"` and `contract_effect="additive"`, and omit `fallback_mode` (valid only for redirect). Relay the bounded reply from the completed event.
+ 5. Tell the user which AC was selected and the effective mode; say it was reflected only after `.applied` or `.completed`.
+
+ Never use Synapse to change approved goals, ACs, constraints, or non-goals; those need an approved shared successor or replacement contract.
+
+ ### Active Conductor attention handling
+
+ `recommended_host_actions` is the authoritative menu; never invent a mutating tool call.
+
+ 1. VERIFY with at most one short-lived read-only host child using the supplied evidence IDs. Without a verifier primitive, surface the attention and stop before mutation.
+ 2. DECIDE among the ordered menu actions only after engine-owned retry/routing is closed.
+ 3. LOG `phase="selected"` through `ouroboros_record_conductor_decision` before ACT. A specification change in run mode needs explicit user approval with its receipt bound.
+ 4. ACT only when the menu names a currently registered MCP tool. A corrective successor preserves the approved contract unless the user approved the shared specification change.
+ 5. LOG exactly one terminal `completed`, `failed`, or `declined` outcome. Never silently retry a failed conductor action.
+
## Fallback (No MCP Server)
- If the MCP server is not available, inform the user:
+ Tell the user:
```
Ouroboros MCP server is not configured.
To enable full execution mode, run: /ouroboros:setup
Without MCP, you can still:
- Use /ouroboros:interview for requirement clarification
- Use /ouroboros:seed to generate specifications
- Manually implement the seed specification
```
- ## Example
-
- ```
- User: /ouroboros:ouroboros-run seed.yaml
-
- [Reads seed.yaml, validates, starts background execution]
-
- Background execution started.
- Job ID: job_a1b2c3d4e5f6
- Session ID: orch_x1y2z3
- Execution ID: exec_m1n2o3
-
- [Relay]
- In progress: Deliver is at Task 1/3 and Subtask 12/16.
- Current work is finishing the workflow routing Subtask.
-
- [Relay]
- Level update: parallel level 1/1 has finished, and Task progress advanced to 3/3.
- Execution is complete. Fetching the final job result now.
-
- [Fetching final result...]
-
- Result:
- Seed Execution SUCCESS
- ========================
- Session ID: orch_x1y2z3
- Goal: Build a CLI task manager
- Duration: 45.2s
- Messages Processed: 12
- Verification Status: executed_unverified
- Formal Evaluation: NOT evaluated by the 3-stage evaluator
-
- Next: `ooo evaluate orch_x1y2z3` for formal 3-stage verification
-
- # Newer server path:
- Verification Status: evaluation_enqueued
- Chained Evaluation Job ID: job_eval987
- [Poll ouroboros_job_wait/job_status, then fetch ouroboros_job_result]
- Formal Evaluation Verdict: APPROVED
- ```
-
## 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.