ouroboros-ai 0.25.3.dev91__tar.gz → 0.25.3.dev93__tar.gz

{ouroboros_ai-0.25.3.dev91 → ouroboros_ai-0.25.3.dev93}/CONTRIBUTING.md

@@ -452,7 +452,7 @@ Any change to a file under `src/ouroboros/cli/commands/` requires reviewing and
 
 #### `init.py` — `ouroboros init` / `ouroboros init start`
 
-Flags covered: `--resume`, `--state-dir`, `--runtime`, `--llm-backend`, `--debug` (`--orchestrator` is deprecated/hidden)
+Flags covered: `--resume`, `--state-dir`, `--orchestrator`, `--runtime`, `--llm-backend`, `--debug`
 
 **Must update:**
 - `docs/cli-reference.md` — `init` command section (flags, examples)
@@ -461,7 +461,7 @@ Flags covered: `--resume`, `--state-dir`, `--runtime`, `--llm-backend`, `--debug
 - `docs/getting-started.md` — onboarding flow
 
 **Also check:**
-- `docs/runtime-guides/claude-code.md` and `docs/runtime-guides/codex.md` — if `--runtime` or `--llm-backend` behavior changes
+- `docs/runtime-guides/claude-code.md` and `docs/runtime-guides/codex.md` — if `--orchestrator` or `--runtime` behavior changes
 
 #### `run.py` — `ouroboros run workflow`
 

{ouroboros_ai-0.25.3.dev91 → ouroboros_ai-0.25.3.dev93}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.25.3.dev91
+Version: 0.25.3.dev93
 Summary: Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE
@@ -105,6 +105,11 @@ Description-Content-Type: text/markdown
 
 Ouroboros sits between you and your AI runtime (Claude Code, Codex CLI, or others). It replaces ad-hoc prompting with a structured specification-first workflow: interview, crystallize, execute, evaluate, evolve.
 
+<!-- TODO: Replace with demo GIF or asciicast -->
+<p align="center">
+  <em>[Demo: 2-minute walkthrough from vague idea to verified code -- coming soon]</em>
+</p>
+
 ---
 
 ## Why Ouroboros?
@@ -170,6 +175,24 @@ After one loop of the Ouroboros cycle, a vague idea becomes a verified codebase:
 | **Seed** | No spec | Immutable specification with acceptance criteria, ontology, constraints |
 | **Evaluate** | Manual review | 3-stage gate: Mechanical (free) -> Semantic -> Multi-Model Consensus |
 
+<!-- Screenshots: replace placeholder paths with actual images after recording -->
+<p align="center">
+  <strong>Interview Transcript</strong><br/>
+  <img src="./docs/images/demo-interview.png" width="720" alt="Ouroboros Socratic interview exposing hidden assumptions from a vague prompt"/><br/>
+  <sub>The Socratic Interviewer turns "build me a task CLI" into 12 clarified decisions.</sub>
+</p>
+
+<p align="center">
+  <strong>Seed Artifact</strong><br/>
+  <img src="./docs/images/demo-seed.png" width="720" alt="Ouroboros seed specification with acceptance criteria, ontology, and constraints"/><br/>
+  <sub>Immutable seed spec locks intent -- acceptance criteria, ontology, and constraints -- before a line of code is written.</sub>
+</p>
+
+<p align="center">
+  <strong>Evaluation Verdict</strong><br/>
+  <img src="./docs/images/demo-evaluation.png" width="720" alt="Ouroboros 3-stage evaluation gate showing mechanical, semantic, and consensus results"/><br/>
+  <sub>3-stage verification gate: Mechanical (free) -> Semantic -> Multi-Model Consensus.</sub>
+</p>
 
 <details>
 <summary><strong>What just happened?</strong></summary>

{ouroboros_ai-0.25.3.dev91 → ouroboros_ai-0.25.3.dev93}/README.md

@@ -65,6 +65,11 @@
 
 Ouroboros sits between you and your AI runtime (Claude Code, Codex CLI, or others). It replaces ad-hoc prompting with a structured specification-first workflow: interview, crystallize, execute, evaluate, evolve.
 
+<!-- TODO: Replace with demo GIF or asciicast -->
+<p align="center">
+  <em>[Demo: 2-minute walkthrough from vague idea to verified code -- coming soon]</em>
+</p>
+
 ---
 
 ## Why Ouroboros?
@@ -130,6 +135,24 @@ After one loop of the Ouroboros cycle, a vague idea becomes a verified codebase:
 | **Seed** | No spec | Immutable specification with acceptance criteria, ontology, constraints |
 | **Evaluate** | Manual review | 3-stage gate: Mechanical (free) -> Semantic -> Multi-Model Consensus |
 
+<!-- Screenshots: replace placeholder paths with actual images after recording -->
+<p align="center">
+  <strong>Interview Transcript</strong><br/>
+  <img src="./docs/images/demo-interview.png" width="720" alt="Ouroboros Socratic interview exposing hidden assumptions from a vague prompt"/><br/>
+  <sub>The Socratic Interviewer turns "build me a task CLI" into 12 clarified decisions.</sub>
+</p>
+
+<p align="center">
+  <strong>Seed Artifact</strong><br/>
+  <img src="./docs/images/demo-seed.png" width="720" alt="Ouroboros seed specification with acceptance criteria, ontology, and constraints"/><br/>
+  <sub>Immutable seed spec locks intent -- acceptance criteria, ontology, and constraints -- before a line of code is written.</sub>
+</p>
+
+<p align="center">
+  <strong>Evaluation Verdict</strong><br/>
+  <img src="./docs/images/demo-evaluation.png" width="720" alt="Ouroboros 3-stage evaluation gate showing mechanical, semantic, and consensus results"/><br/>
+  <sub>3-stage verification gate: Mechanical (free) -> Semantic -> Multi-Model Consensus.</sub>
+</p>
 
 <details>
 <summary><strong>What just happened?</strong></summary>

{ouroboros_ai-0.25.3.dev91 → ouroboros_ai-0.25.3.dev93}/docs/cli-reference.md

@@ -130,8 +130,9 @@ ouroboros init [start] [OPTIONS] [CONTEXT]
 |--------|-------------|
 | `-r, --resume TEXT` | Resume an existing interview by ID |
 | `--state-dir DIRECTORY` | Custom directory for interview state files |
-| `--runtime TEXT` | Agent runtime backend for the workflow execution step after seed generation (`claude`, `codex`). |
-| `--llm-backend TEXT` | LLM backend override for interview, ambiguity scoring, and seed generation (`claude_code`, `litellm`, `codex`). Resolved from config (`llm.backend`) by default. |
+| `-o, --orchestrator` | Use Claude Code for the interview/seed flow; combine with `--runtime` to choose the workflow handoff backend |
+| `--runtime TEXT` | Agent runtime backend for the workflow execution step after seed generation. Shipped values: `claude`, `codex`. `opencode` appears in the CLI enum but is out of scope. Custom adapters registered in `runtime_factory.py` are also accepted. |
+| `--llm-backend TEXT` | LLM backend for interview, ambiguity scoring, and seed generation (`claude_code`, `litellm`, `codex`). `opencode` appears in the CLI enum but is out of scope |
 | `-d, --debug` | Show verbose logs including debug messages |
 
 **Examples:**
@@ -143,10 +144,13 @@ ouroboros init "I want to build a task management CLI tool"
 # Explicit subcommand (equivalent)
 ouroboros init start "I want to build a task management CLI tool"
 
+# Start with Claude Code (no API key needed)
+ouroboros init --orchestrator "Build a REST API"
+
 # Specify runtime backend for the workflow step
-ouroboros init --runtime codex "Build a REST API"
+ouroboros init --orchestrator --runtime codex "Build a REST API"
 
-# Override LLM backend for interview and seed generation
+# Use Codex as the LLM backend for interview and seed generation
 ouroboros init --llm-backend codex "Build a REST API"
 
 # Resume an interrupted interview
@@ -199,7 +203,7 @@ ouroboros run [workflow] [OPTIONS] SEED_FILE
 
 | Option | Description |
 |--------|-------------|
-| `-o/-O, --orchestrator/--no-orchestrator` | Orchestrator mode (default: enabled). `--no-orchestrator` falls back to legacy placeholder mode. |
+| `-o/-O, --orchestrator/--no-orchestrator` | Use the agent-runtime orchestrator for execution (default: enabled) |
 | `--runtime TEXT` | Agent runtime backend override (`claude`, `codex`). Uses configured default if omitted. (`opencode` is in the CLI enum but out of scope) |
 | `-r, --resume TEXT` | Resume a previous orchestrator session by ID |
 | `--mcp-config PATH` | Path to MCP client configuration YAML file |

{ouroboros_ai-0.25.3.dev91 → ouroboros_ai-0.25.3.dev93}/docs/guides/seed-authoring.md

@@ -335,7 +335,7 @@ acceptance_criteria:
 
 ## Validation
 
-> **Note — `--dry-run` is not functional in the current implementation.** In the default orchestrator mode, the `--dry-run` flag is silently ignored and execution proceeds normally. In legacy non-orchestrator mode (`--no-orchestrator`), `--dry-run` prints a placeholder message without performing any YAML or schema checks. This limitation is tracked for a future release.
+> **Note — `--dry-run` is not functional in the current implementation.** In the default orchestrator mode (`--orchestrator` is `True` by default), the `--dry-run` flag is silently ignored and execution proceeds normally. In non-orchestrator mode (`--no-orchestrator`), `--dry-run` prints a placeholder message without performing any YAML or schema checks. This limitation is tracked for a future release.
 
 **Current approach to pre-run validation:** Run the workflow normally. Schema validation errors surface *before* any agent sessions start, so an invalid seed will print an error and exit without executing:
 
@@ -394,10 +394,10 @@ export ANTHROPIC_API_KEY="sk-ant-..."
 # or
 export OPENAI_API_KEY="sk-..."
 
-# To avoid needing an API key, use Claude Code or Codex CLI (configured in llm.backend):
+# To avoid needing an API key, use Claude Code (Max Plan):
 ooo interview "Build a REST API"
 # or standalone:
-ouroboros init start "Build a REST API"
+ouroboros init start --orchestrator "Build a REST API"
 ```
 
 #### LLM rate-limit or transient API error during questioning
@@ -708,18 +708,22 @@ ouroboros run minimal_seed.yaml
 
 ---
 
-### CLI Flag Notes
+### CLI Flag Warnings
 
-#### `--orchestrator` (init command)
+#### `--runtime` without `--orchestrator` (init command)
 
-The `--orchestrator` flag on `ouroboros init` is **deprecated** and no longer needed. The LLM backend is resolved from config (`llm.backend`) automatically. The flag is accepted for backward compatibility but has no effect.
+**Symptom:**
+```
+Warning: --runtime only affects the workflow execution step when --orchestrator is enabled.
+```
 
-```bash
-# Just use:
-ouroboros init start "Build a REST API"
+**Cause:** `--runtime` (e.g., `--runtime codex`) was passed to `ouroboros init` without `--orchestrator`. The `--runtime` flag only controls which agent runtime backend is used when the generated seed is immediately handed off to workflow execution. Without `--orchestrator`, the workflow handoff step uses a placeholder.
+
+**Behavior:** This is a **warning only** — the interview and seed generation proceed normally. The runtime flag has no effect.
 
-# Override backend explicitly if needed:
-ouroboros init start --llm-backend codex "Build a REST API"
+**Fix:** Add `--orchestrator` if you want to use the specified runtime backend for the post-generation workflow step:
+```bash
+ouroboros init start --orchestrator --runtime codex "Build a REST API"
 ```
 
 ---

{ouroboros_ai-0.25.3.dev91 → ouroboros_ai-0.25.3.dev93}/docs/runtime-guides/claude-code.md

@@ -32,7 +32,7 @@ orchestrator:
   runtime_backend: claude
 ```
 
-When `orchestrator.runtime_backend` is set to `claude`, Claude Code is used as the runtime backend.
+When using the `--orchestrator` CLI flag, Claude Code is the default runtime backend.
 
 ## How It Works
 
@@ -72,8 +72,8 @@ All commands in this section run in your **regular terminal** (shell), not insid
 
 **Terminal:**
 ```bash
-# Start interactive interview
-uv run ouroboros init start "Your idea here"
+# Start interactive interview (Claude Code runtime)
+uv run ouroboros init start --orchestrator "Your idea here"
 
 # Resume an interrupted interview
 uv run ouroboros init start --resume interview_20260127_120000
@@ -86,24 +86,24 @@ uv run ouroboros init list
 
 **Terminal:**
 ```bash
-# Execute workflow
-uv run ouroboros run workflow seed.yaml
+# Execute workflow (Claude Code runtime)
+uv run ouroboros run workflow --orchestrator seed.yaml
 
 # Dry run (validate seed without executing)
 uv run ouroboros run workflow --dry-run seed.yaml
 
 # Debug output (show logs and agent thinking)
-uv run ouroboros run workflow --debug seed.yaml
+uv run ouroboros run workflow --orchestrator --debug seed.yaml
 
 # Resume a previous session
-uv run ouroboros run workflow --resume <session_id> seed.yaml
+uv run ouroboros run workflow --orchestrator --resume <session_id> seed.yaml
 ```
 
 ## Troubleshooting
 
 ### "Providers: warning" in health check
 
-This is normal when not using LiteLLM providers. The orchestrator mode uses the configured runtime backend directly.
+This is normal when not using LiteLLM providers. The orchestrator mode uses Claude Code directly.
 
 ### Session fails with empty error
 
@@ -112,7 +112,7 @@ Ensure you're running from the project directory:
 **Terminal:**
 ```bash
 cd /path/to/ouroboros
-uv run ouroboros run workflow seed.yaml
+uv run ouroboros run workflow --orchestrator seed.yaml
 ```
 
 ### "EventStore not initialized"

{ouroboros_ai-0.25.3.dev91 → ouroboros_ai-0.25.3.dev93}/src/ouroboros/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.25.3.dev91'
-__version_tuple__ = version_tuple = (0, 25, 3, 'dev91')
+__version__ = version = '0.25.3.dev93'
+__version_tuple__ = version_tuple = (0, 25, 3, 'dev93')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.25.3.dev91 → ouroboros_ai-0.25.3.dev93}/src/ouroboros/bigbang/ambiguity.py

@@ -448,17 +448,14 @@ Additional context (intentional deferrals — do not penalise):
         except json.JSONDecodeError as e:
             raise ValueError(f"Invalid JSON response: {e}") from e
 
-        # Validate all required fields are present
-        required_fields = [
+        # Numeric score fields must be present. Missing justifications are recoverable.
+        required_score_fields = [
             "goal_clarity_score",
-            "goal_clarity_justification",
             "constraint_clarity_score",
-            "constraint_clarity_justification",
             "success_criteria_clarity_score",
-            "success_criteria_clarity_justification",
         ]
 
-        for field_name in required_fields:
+        for field_name in required_score_fields:
             if field_name not in data:
                 raise ValueError(f"Missing required field: {field_name}")
 
@@ -467,6 +464,15 @@ Additional context (intentional deferrals — do not penalise):
             score = float(value)
             return max(0.0, min(1.0, score))
 
+        def justification_for(field_name: str, component_name: str) -> str:
+            value = data.get(field_name)
+            if value is None:
+                return f"{component_name} justification not provided by model."
+            text = str(value).strip()
+            if not text:
+                return f"{component_name} justification not provided by model."
+            return text
+
         # Select weights based on project type
         if is_brownfield:
             goal_weight = BROWNFIELD_GOAL_CLARITY_WEIGHT
@@ -484,7 +490,10 @@ Additional context (intentional deferrals — do not penalise):
                 name="Context Clarity",
                 clarity_score=clamp_score(data["context_clarity_score"]),
                 weight=BROWNFIELD_CONTEXT_CLARITY_WEIGHT,
-                justification=str(data.get("context_clarity_justification", "")),
+                justification=justification_for(
+                    "context_clarity_justification",
+                    "Context Clarity",
+                ),
             )
 
         return ScoreBreakdown(
@@ -492,19 +501,28 @@ Additional context (intentional deferrals — do not penalise):
                 name="Goal Clarity",
                 clarity_score=clamp_score(data["goal_clarity_score"]),
                 weight=goal_weight,
-                justification=str(data["goal_clarity_justification"]),
+                justification=justification_for(
+                    "goal_clarity_justification",
+                    "Goal Clarity",
+                ),
             ),
             constraint_clarity=ComponentScore(
                 name="Constraint Clarity",
                 clarity_score=clamp_score(data["constraint_clarity_score"]),
                 weight=constraint_weight,
-                justification=str(data["constraint_clarity_justification"]),
+                justification=justification_for(
+                    "constraint_clarity_justification",
+                    "Constraint Clarity",
+                ),
             ),
             success_criteria_clarity=ComponentScore(
                 name="Success Criteria Clarity",
                 clarity_score=clamp_score(data["success_criteria_clarity_score"]),
                 weight=criteria_weight,
-                justification=str(data["success_criteria_clarity_justification"]),
+                justification=justification_for(
+                    "success_criteria_clarity_justification",
+                    "Success Criteria Clarity",
+                ),
             ),
             context_clarity=context_clarity,
         )

{ouroboros_ai-0.25.3.dev91 → ouroboros_ai-0.25.3.dev93}/src/ouroboros/cli/commands/init.py

@@ -26,7 +26,7 @@ from ouroboros.bigbang.interview import (
 from ouroboros.bigbang.seed_generator import SeedGenerator
 from ouroboros.cli.formatters import console
 from ouroboros.cli.formatters.panels import print_error, print_info, print_success, print_warning
-from ouroboros.config import get_clarification_model, get_llm_backend
+from ouroboros.config import get_clarification_model
 from ouroboros.observability import LoggingConfig, configure_logging
 from ouroboros.providers import create_llm_adapter
 from ouroboros.providers.base import LLMAdapter
@@ -145,15 +145,15 @@ async def _multiline_prompt_async(prompt_text: str) -> str:
 
 
 def _get_adapter(
+    use_orchestrator: bool,
     backend: str | None = None,
     for_interview: bool = False,
     debug: bool = False,
 ) -> LLMAdapter:
     """Get the appropriate LLM adapter.
 
-    Resolution order: explicit backend arg > config llm.backend > "claude_code".
-
     Args:
+        use_orchestrator: If True, default to Claude Code for compatibility.
         backend: Optional explicit LLM backend override.
         for_interview: If True, enable Read/Glob/Grep tools for codebase exploration.
         debug: If True, show streaming messages (thinking, tool use).
@@ -161,7 +161,7 @@ def _get_adapter(
     Returns:
         LLM adapter instance.
     """
-    resolved_backend = backend or get_llm_backend()
+    resolved_backend = backend or ("claude_code" if use_orchestrator else "litellm")
 
     if for_interview:
         # Interview mode: request the interview-specific permission policy and
@@ -260,6 +260,7 @@ async def _run_interview(
     initial_context: str,
     resume_id: str | None = None,
     state_dir: Path | None = None,
+    use_orchestrator: bool = False,
     debug: bool = False,
     workflow_runtime_backend: str | None = None,
     llm_backend: str | None = None,
@@ -270,11 +271,13 @@ async def _run_interview(
         initial_context: Initial context or idea for the interview.
         resume_id: Optional interview ID to resume.
         state_dir: Optional custom state directory.
+        use_orchestrator: If True, use Claude Code (Max Plan) instead of LiteLLM.
         workflow_runtime_backend: Optional agent runtime backend for the workflow handoff.
         llm_backend: Optional LLM backend override for interview and seed generation.
     """
     # Initialize components
     llm_adapter = _get_adapter(
+        use_orchestrator,
         backend=llm_backend,
         for_interview=True,
         debug=debug,
@@ -367,6 +370,7 @@ async def _run_interview(
     if should_start_workflow:
         await _start_workflow(
             seed_path,
+            use_orchestrator,
             runtime_backend=workflow_runtime_backend,
         )
 
@@ -468,32 +472,40 @@ async def _generate_seed_from_interview(
 
 async def _start_workflow(
     seed_path: Path,
+    use_orchestrator: bool = False,
     parallel: bool = True,
     runtime_backend: str | None = None,
 ) -> None:
-    """Start workflow from generated seed (always orchestrator mode).
+    """Start workflow from generated seed.
 
     Args:
         seed_path: Path to the seed YAML file.
+        use_orchestrator: Whether to use Claude Code orchestrator.
         parallel: Execute independent ACs in parallel. Default: True.
         runtime_backend: Optional runtime backend for orchestrator execution.
     """
     console.print()
     console.print("[bold cyan]Starting workflow...[/]")
 
-    from ouroboros.cli.commands.run import _run_orchestrator
+    if use_orchestrator:
+        # Direct function call instead of subprocess
+        from ouroboros.cli.commands.run import _run_orchestrator
 
-    try:
-        await _run_orchestrator(
-            seed_path,
-            resume_session=None,
-            parallel=parallel,
-            runtime_backend=runtime_backend,
-        )
-    except typer.Exit:
-        pass  # Normal exit
-    except KeyboardInterrupt:
-        print_info("Workflow interrupted.")
+        try:
+            await _run_orchestrator(
+                seed_path,
+                resume_session=None,
+                parallel=parallel,
+                runtime_backend=runtime_backend,
+            )
+        except typer.Exit:
+            pass  # Normal exit
+        except KeyboardInterrupt:
+            print_info("Workflow interrupted.")
+    else:
+        # Standard workflow (placeholder for now)
+        print_info(f"Would execute workflow from: {seed_path}")
+        print_info("Standard workflow execution not yet implemented.")
 
 
 def _find_pm_seeds(seeds_dir: Path | None = None) -> list[Path]:
@@ -681,13 +693,12 @@ def start(
             dir_okay=True,
         ),
     ] = None,
-    orchestrator: Annotated[  # noqa: ARG001 — kept for backward compat
+    orchestrator: Annotated[
         bool,
         typer.Option(
             "--orchestrator",
             "-o",
-            help="Deprecated: no longer needed. Backend is resolved from config (llm.backend).",
-            hidden=True,
+            help="Use Claude Code (Max Plan) instead of LiteLLM. No API key required.",
         ),
     ] = False,
     runtime: Annotated[
@@ -726,13 +737,12 @@ def start(
     This command initiates the Big Bang phase, which transforms vague ideas
     into clear, executable requirements through iterative questioning.
 
-    The LLM backend is resolved from config (llm.backend) by default.
-    Override with --llm-backend if needed.
-
     Example:
         ouroboros init start "I want to build a task management CLI tool"
 
-        ouroboros init start --runtime codex "Build a REST API"
+        ouroboros init start --orchestrator "Build a REST API"
+
+        ouroboros init start --orchestrator --runtime codex "Build a REST API"
 
         ouroboros init start --llm-backend codex "Build a REST API"
 
@@ -792,16 +802,21 @@ def start(
         configure_logging(LoggingConfig(log_level="DEBUG"))
         print_info("Debug mode enabled - showing verbose logs")
 
-    # Show mode info — resolve actual backend used
-    resolved_display = llm_backend.value if llm_backend else get_llm_backend()
-    backend_labels = {
-        "claude_code": "Claude Code - no API key required",
-        "codex": "Codex CLI - no API key required",
-        "litellm": "LiteLLM - API key required",
-    }
-    print_info(f"Using {backend_labels.get(resolved_display, resolved_display)}")
-    if runtime:
-        print_info(f"Workflow runtime backend: {runtime.value}")
+    if runtime and not orchestrator:
+        print_warning(
+            "--runtime only affects the workflow execution step when --orchestrator is enabled."
+        )
+
+    # Show mode info
+    if orchestrator:
+        print_info("Using Claude Code (Max Plan) - no API key required")
+        if runtime:
+            print_info(f"Workflow runtime backend: {runtime.value}")
+    else:
+        print_info("Using LiteLLM - API key required")
+
+    if llm_backend:
+        print_info(f"Interview LLM backend: {llm_backend.value}")
 
     # Run interview
     try:
@@ -810,6 +825,7 @@ def start(
                 context or "",
                 resume,
                 state_dir,
+                orchestrator,
                 debug,
                 runtime.value if runtime else None,
                 llm_backend.value if llm_backend else None,
@@ -838,7 +854,7 @@ def list_interviews(
     ] = None,
 ) -> None:
     """List all interview sessions."""
-    llm_adapter = create_llm_adapter(backend=get_llm_backend())
+    llm_adapter = create_llm_adapter(backend="litellm")
     engine = InterviewEngine(
         llm_adapter=llm_adapter,
         state_dir=state_dir or Path.home() / ".ouroboros" / "data",

{ouroboros_ai-0.25.3.dev91 → ouroboros_ai-0.25.3.dev93}/src/ouroboros/cli/commands/run.py

@@ -58,6 +58,14 @@ def _derive_quality_bar(seed: "Seed") -> str:
     return "The execution must satisfy all acceptance criteria:\n" + "\n".join(ac_lines)
 
 
+def _get_verification_artifact(summary: dict[str, Any], final_message: str) -> str:
+    """Prefer the structured verification report when present."""
+    verification_report = summary.get("verification_report")
+    if isinstance(verification_report, str) and verification_report:
+        return verification_report
+    return final_message or ""
+
+
 def _load_seed_from_yaml(seed_file: Path) -> dict[str, Any]:
     """Load seed configuration from YAML file.
 
@@ -249,7 +257,7 @@ async def _run_orchestrator(
 
                     qa_result = await qa_handler.handle(
                         {
-                            "artifact": res.final_message or "",
+                            "artifact": _get_verification_artifact(res.summary, res.final_message),
                             "artifact_type": "test_output",
                             "quality_bar": quality_bar,
                             "seed_content": yaml.dump(seed_data, default_flow_style=False),

{ouroboros_ai-0.25.3.dev91 → ouroboros_ai-0.25.3.dev93}/src/ouroboros/evolution/loop.py

@@ -889,7 +889,15 @@ class EvolutionaryLoop:
                 exec_result = await self.executor(current_seed, parallel=parallel)
                 if hasattr(exec_result, "is_ok") and exec_result.is_ok:
                     orch_result = exec_result.value
-                    execution_output = getattr(orch_result, "final_message", str(orch_result))
+                    summary = getattr(orch_result, "summary", {})
+                    verification_report = (
+                        summary.get("verification_report") if isinstance(summary, dict) else None
+                    )
+                    execution_output = (
+                        verification_report
+                        if isinstance(verification_report, str) and verification_report
+                        else getattr(orch_result, "final_message", str(orch_result))
+                    )
                     # Log structured metadata for observability
                     logger.info(
                         "evolution.generation.executed",

{ouroboros_ai-0.25.3.dev91 → ouroboros_ai-0.25.3.dev93}/src/ouroboros/mcp/tools/execution_handlers.py

@@ -409,7 +409,10 @@ class ExecuteSeedHandler:
                         quality_bar = self._derive_quality_bar(_seed)
                         await qa_handler.handle(
                             {
-                                "artifact": result.value.final_message or "",
+                                "artifact": self._get_verification_artifact(
+                                    result.value.summary,
+                                    result.value.final_message,
+                                ),
                                 "artifact_type": "test_output",
                                 "quality_bar": quality_bar,
                                 "seed_content": _seed_content,
@@ -500,6 +503,14 @@ class ExecuteSeedHandler:
         ac_lines = [f"- {ac}" for ac in seed.acceptance_criteria]
         return "The execution must satisfy all acceptance criteria:\n" + "\n".join(ac_lines)
 
+    @staticmethod
+    def _get_verification_artifact(summary: dict[str, Any], final_message: str) -> str:
+        """Prefer the structured verification report when present."""
+        verification_report = summary.get("verification_report")
+        if isinstance(verification_report, str) and verification_report:
+            return verification_report
+        return final_message or ""
+
     @staticmethod
     def _format_execution_result(exec_result, seed: Seed) -> str:
         """Format execution result as human-readable text.

{ouroboros_ai-0.25.3.dev91 → ouroboros_ai-0.25.3.dev93}/src/ouroboros/orchestrator/__init__.py

@@ -25,10 +25,11 @@ Usage:
     runner = OrchestratorRunner(adapter, event_store, mcp_manager=mcp_manager)
 
 CLI Usage:
-    ouroboros run seed.yaml
-    ouroboros run seed.yaml --runtime codex
-    ouroboros run seed.yaml --resume <session_id>
-    ouroboros run seed.yaml --mcp-config mcp.yaml
+    ouroboros run --orchestrator seed.yaml
+    ouroboros run --orchestrator seed.yaml --parallel  # Parallel AC execution
+    ouroboros run --orchestrator seed.yaml --resume <session_id>
+    ouroboros run --orchestrator seed.yaml --runtime codex
+    ouroboros run --orchestrator seed.yaml --mcp-config mcp.yaml
 """
 
 from ouroboros.orchestrator.adapter import (