ouroboros-ai 0.29.2.dev2__tar.gz → 0.29.3.dev5__tar.gz

{ouroboros_ai-0.29.2.dev2 → ouroboros_ai-0.29.3.dev5}/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "ouroboros",
       "description": "Transform vague ideas into validated seed specifications through Socratic questioning and ontological analysis",
-      "version": "0.29.1",
+      "version": "0.29.2",
       "author": {
         "name": "Q00",
         "email": "jqyu.lee@gmail.com"

{ouroboros_ai-0.29.2.dev2 → ouroboros_ai-0.29.3.dev5}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ouroboros",
-  "version": "0.29.1",
+  "version": "0.29.2",
   "description": "Self-improving AI workflow system. Crystallize requirements before execution with Socratic interview, ambiguity scoring, and 3-stage evaluation.",
   "author": {
     "name": "Q00",

{ouroboros_ai-0.29.2.dev2 → ouroboros_ai-0.29.3.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.29.2.dev2
+Version: 0.29.3.dev5
 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

{ouroboros_ai-0.29.2.dev2 → ouroboros_ai-0.29.3.dev5}/skills/setup/SKILL.md

@@ -246,7 +246,7 @@ A backup will be created: CLAUDE.md.bak
 **If "Preview first", show:**
 ````markdown
 <!-- ooo:START -->
-<!-- ooo:VERSION:0.29.1 -->
+<!-- ooo:VERSION:0.29.2 -->
 # Ouroboros — Specification-First AI Development
 
 > Before telling AI what to build, define what should be built.

{ouroboros_ai-0.29.2.dev2 → ouroboros_ai-0.29.3.dev5}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.29.2.dev2'
-__version_tuple__ = version_tuple = (0, 29, 2, 'dev2')
+__version__ = version = '0.29.3.dev5'
+__version_tuple__ = version_tuple = (0, 29, 3, 'dev5')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.29.2.dev2 → ouroboros_ai-0.29.3.dev5}/src/ouroboros/cli/commands/mcp.py

@@ -131,7 +131,13 @@ def _ensure_shell_env(*, timeout: float = 10.0) -> None:
         cmd = [shell, "-l", "-c", dump_cmd]
 
     try:
-        result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            stdin=subprocess.DEVNULL,
+            text=True,
+            timeout=timeout,
+        )
     except (FileNotFoundError, subprocess.TimeoutExpired, OSError) as e:
         _stderr_console.print(f"[yellow]Warning: shell env load failed: {e}[/yellow]")
         return

{ouroboros_ai-0.29.2.dev2 → ouroboros_ai-0.29.3.dev5}/src/ouroboros/mcp/tools/evaluation_handlers.py

@@ -1252,6 +1252,21 @@ class LateralThinkHandler:
                         "all",
                     ),
                 ),
+                MCPToolParameter(
+                    name="stagnation_pattern",
+                    type=ToolInputType.STRING,
+                    description=(
+                        "Detected stagnation pattern used to suggest a persona when "
+                        "persona is omitted."
+                    ),
+                    required=False,
+                    enum=(
+                        "spinning",
+                        "oscillation",
+                        "no_drift",
+                        "diminishing_returns",
+                    ),
+                ),
                 MCPToolParameter(
                     name="personas",
                     type=ToolInputType.ARRAY,
@@ -1292,6 +1307,7 @@ class LateralThinkHandler:
             Result containing lateral thinking prompt(s) or error.
         """
         from ouroboros.resilience.lateral import LateralThinker, ThinkingPersona
+        from ouroboros.resilience.stagnation import StagnationPattern
 
         problem_context = arguments.get("problem_context")
         if not problem_context:
@@ -1316,7 +1332,18 @@ class LateralThinkHandler:
 
         # --- Parallel multi-persona dispatch path ---
         explicit_list = arguments.get("personas")
-        persona_arg = arguments.get("persona", "contrarian")
+        raw_persona_arg = arguments.get("persona")
+        if explicit_list or raw_persona_arg is None:
+            persona_arg = ""
+        else:
+            persona_arg = str(raw_persona_arg).strip()
+            if not persona_arg:
+                return Result.err(
+                    MCPToolError(
+                        "persona cannot be blank",
+                        tool_name="ouroboros_lateral_think",
+                    )
+                )
         dispatch_all = persona_arg == "all"
 
         if explicit_list or dispatch_all:
@@ -1435,6 +1462,43 @@ class LateralThinkHandler:
             )
 
         # --- Single-persona path ---
+        if not persona_arg:
+            stagnation_pattern_arg = arguments.get("stagnation_pattern")
+            if stagnation_pattern_arg:
+                try:
+                    stagnation_pattern = StagnationPattern(str(stagnation_pattern_arg))
+                except ValueError:
+                    return Result.err(
+                        MCPToolError(
+                            (
+                                f"Invalid stagnation_pattern: {stagnation_pattern_arg}. "
+                                "Must be one of: spinning, oscillation, no_drift, "
+                                "diminishing_returns"
+                            ),
+                            tool_name="ouroboros_lateral_think",
+                        )
+                    )
+
+                from ouroboros.resilience.recovery import suggest_lateral_persona_for_pattern
+
+                suggested = suggest_lateral_persona_for_pattern(
+                    stagnation_pattern,
+                    failed_attempts=failed_attempts,
+                )
+                if suggested is None:
+                    return Result.err(
+                        MCPToolError(
+                            (
+                                "No available lateral thinking persona remains after "
+                                "applying failed_attempts exclusions"
+                            ),
+                            tool_name="ouroboros_lateral_think",
+                        )
+                    )
+                persona_arg = suggested.value
+            else:
+                persona_arg = ThinkingPersona.CONTRARIAN.value
+
         try:
             persona = ThinkingPersona(persona_arg)
         except ValueError:

{ouroboros_ai-0.29.2.dev2 → ouroboros_ai-0.29.3.dev5}/src/ouroboros/orchestrator/runner.py

@@ -87,6 +87,14 @@ from ouroboros.orchestrator.session import SessionRepository, SessionStatus, Ses
 from ouroboros.orchestrator.workflow_state import coerce_ac_marker_update
 from ouroboros.persistence.checkpoint import CheckpointStore
 from ouroboros.providers import create_llm_adapter
+from ouroboros.resilience.lateral import ThinkingPersona
+from ouroboros.resilience.recovery import (
+    RecoveryActionKind,
+    RecoveryPlanner,
+    RecoverySnapshot,
+    create_recovery_applied_event,
+    get_run_recovery_protocol_prompt,
+)
 
 if TYPE_CHECKING:
     from ouroboros.core.seed import Seed
@@ -277,6 +285,7 @@ IMPORTANT: You are extending existing code, NOT creating a new project.
 
     ac_tracking = get_ac_tracking_prompt()
     strategy_fragment = strategy.get_system_prompt_fragment()
+    recovery_protocol = get_run_recovery_protocol_prompt()
 
     return f"""{strategy_fragment}
 
@@ -289,7 +298,9 @@ IMPORTANT: You are extending existing code, NOT creating a new project.
 ## Evaluation Principles
 {principles_text}
 
-{ac_tracking}"""
+{ac_tracking}
+
+{recovery_protocol}"""
 
 
 def build_task_prompt(
@@ -1599,23 +1610,32 @@ class OrchestratorRunner:
             last_tool: str | None = None
             last_completed_count = 0
             runtime_handle: RuntimeHandle | None = None
+            recovery_interventions_used = 0
+            recovery_personas: list[str] = []
 
             cancelled_result: Result[OrchestratorResult, OrchestratorError] | None = None
 
-            with Status(
-                f"[bold cyan]Executing: {seed.goal[:50]}...[/]",
-                console=self._console,
-                spinner="dots",
-            ) as status:
-                runtime_handle = self._seed_runtime_handle(
-                    self._inherited_runtime_handle, tool_catalog=tool_catalog
-                )
+            async def _consume_task_stream(
+                *,
+                prompt: str,
+                resume_handle: RuntimeHandle | None,
+                status: Any,
+            ) -> RuntimeHandle | None:
+                nonlocal cancelled_result
+                nonlocal final_message
+                nonlocal last_completed_count
+                nonlocal last_tool
+                nonlocal messages_processed
+                nonlocal success
+                nonlocal tracker
+
+                active_runtime_handle = resume_handle
                 async with aclosing(
                     self._adapter.execute_task(  # type: ignore[type-var]
-                        prompt=task_prompt,
+                        prompt=prompt,
                         tools=merged_tools,
                         system_prompt=system_prompt,
-                        resume_handle=runtime_handle,
+                        resume_handle=active_runtime_handle,
                     )
                 ) as message_stream:
                     async for message in message_stream:
@@ -1640,7 +1660,7 @@ class OrchestratorRunner:
                             tracker.session_id,
                         )
                         if message.resume_handle is not None:
-                            runtime_handle = message.resume_handle
+                            active_runtime_handle = message.resume_handle
 
                         # Update workflow state tracker
                         state_tracker.process_runtime_message(message)
@@ -1741,6 +1761,84 @@ class OrchestratorRunner:
                             final_message = message.content
                             success = not message.is_error
 
+                return active_runtime_handle
+
+            def _build_recovery_snapshot() -> RecoverySnapshot:
+                unfinished = [
+                    f"{ac.index}. {ac.content}"
+                    for ac in state_tracker.state.acceptance_criteria
+                    if ac.status.value != "completed"
+                ]
+                unfinished_text = "\n".join(unfinished[:5]) or "None"
+                problem_context = (
+                    f"Goal: {seed.goal}\n"
+                    f"Unfinished acceptance criteria:\n{unfinished_text}\n\n"
+                    f"Previous final message:\n{final_message[:1000]}"
+                )
+                current_approach = (
+                    "The first run attempted the seed normally and ended without "
+                    "satisfying the workflow. Continue from the current repository "
+                    "state, but avoid repeating the same failed path."
+                )
+                return RecoverySnapshot(
+                    problem_context=problem_context,
+                    current_approach=current_approach,
+                    messages_processed=messages_processed,
+                    completed_count=state_tracker.state.completed_count,
+                    total_count=state_tracker.state.total_count,
+                    final_error=final_message,
+                    used_personas=tuple(ThinkingPersona(persona) for persona in recovery_personas),
+                    interventions_used=recovery_interventions_used,
+                )
+
+            with Status(
+                f"[bold cyan]Executing: {seed.goal[:50]}...[/]",
+                console=self._console,
+                spinner="dots",
+            ) as status:
+                runtime_handle = self._seed_runtime_handle(
+                    self._inherited_runtime_handle, tool_catalog=tool_catalog
+                )
+                runtime_handle = await _consume_task_stream(
+                    prompt=task_prompt,
+                    resume_handle=runtime_handle,
+                    status=status,
+                )
+
+                if cancelled_result is None and not success and runtime_handle is not None:
+                    planner = RecoveryPlanner()
+                    recovery_action = planner.plan(_build_recovery_snapshot())
+                    if (
+                        recovery_action.kind == RecoveryActionKind.INJECT_LATERAL_DIRECTIVE
+                        and recovery_action.directive
+                        and recovery_action.persona is not None
+                    ):
+                        recovery_interventions_used += 1
+                        recovery_personas.append(recovery_action.persona.value)
+                        await self._event_store.append(
+                            create_recovery_applied_event(
+                                execution_id=exec_id,
+                                session_id=tracker.session_id,
+                                seed_id=seed.metadata.seed_id,
+                                action=recovery_action,
+                                messages_processed=messages_processed,
+                                completed_count=state_tracker.state.completed_count,
+                                total_count=state_tracker.state.total_count,
+                            )
+                        )
+                        status.stop()
+                        self._console.print(
+                            "[yellow]Recovery: "
+                            f"{recovery_action.pattern.value if recovery_action.pattern else 'unknown'} "
+                            f"-> {recovery_action.persona.value}[/yellow]"
+                        )
+                        status.start()
+                        runtime_handle = await _consume_task_stream(
+                            prompt=recovery_action.directive,
+                            resume_handle=runtime_handle,
+                            status=status,
+                        )
+
             # If cancelled, return the cancellation result now that the
             # generator has been properly closed via aclosing.
             if cancelled_result is not None:

{ouroboros_ai-0.29.2.dev2 → ouroboros_ai-0.29.3.dev5}/src/ouroboros/resilience/__init__.py

@@ -8,6 +8,7 @@ Components:
 - ExecutionHistory: Tracks execution state for detection
 - LateralThinker: Generates alternative approaches via personas
 - ThinkingPersona: 5 personas for lateral thinking
+- RecoveryPlanner: Chooses bounded in-run recovery directives
 - Events: Stagnation and lateral thinking event types
 
 Story 4.1: Stagnation Detection (4 Patterns)
@@ -34,6 +35,16 @@ from ouroboros.resilience.lateral import (
     PersonaStrategy,
     ThinkingPersona,
 )
+from ouroboros.resilience.recovery import (
+    RecoveryAction,
+    RecoveryActionKind,
+    RecoveryPlanner,
+    RecoverySnapshot,
+    coerce_failed_attempt_personas,
+    create_recovery_applied_event,
+    get_run_recovery_protocol_prompt,
+    suggest_lateral_persona_for_pattern,
+)
 from ouroboros.resilience.stagnation import (
     DiminishingReturnsDetectedEvent,
     ExecutionHistory,
@@ -64,4 +75,13 @@ __all__ = [
     "LateralThinkingSucceededEvent",
     "LateralThinkingFailedEvent",
     "AllPersonasExhaustedEvent",
+    # Recovery planning
+    "RecoveryAction",
+    "RecoveryActionKind",
+    "RecoveryPlanner",
+    "RecoverySnapshot",
+    "coerce_failed_attempt_personas",
+    "create_recovery_applied_event",
+    "get_run_recovery_protocol_prompt",
+    "suggest_lateral_persona_for_pattern",
 ]

ouroboros_ai-0.29.3.dev5/src/ouroboros/resilience/recovery.py

@@ -0,0 +1,232 @@
+"""Recovery planning shared by run loops and lateral thinking tools."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from ouroboros.events.base import BaseEvent
+from ouroboros.resilience.lateral import LateralThinker, ThinkingPersona
+from ouroboros.resilience.stagnation import StagnationPattern
+
+
+class RecoveryActionKind(StrEnum):
+    """Planner actions for a stalled or failed execution."""
+
+    CONTINUE = "continue"
+    INJECT_LATERAL_DIRECTIVE = "inject_lateral_directive"
+    STAGNATED = "stagnated"
+
+
+@dataclass(frozen=True, slots=True)
+class RecoverySnapshot:
+    """Execution state used to decide whether to intervene."""
+
+    problem_context: str
+    current_approach: str
+    messages_processed: int = 0
+    completed_count: int = 0
+    total_count: int = 0
+    final_error: str = ""
+    stagnation_pattern: StagnationPattern | None = None
+    failed_attempts: tuple[str, ...] = ()
+    used_personas: tuple[ThinkingPersona, ...] = ()
+    interventions_used: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class RecoveryAction:
+    """A concrete recovery decision."""
+
+    kind: RecoveryActionKind
+    reason: str
+    pattern: StagnationPattern | None = None
+    persona: ThinkingPersona | None = None
+    directive: str = ""
+
+    @classmethod
+    def continue_(cls, reason: str) -> RecoveryAction:
+        """Return a no-op recovery action."""
+        return cls(kind=RecoveryActionKind.CONTINUE, reason=reason)
+
+    @classmethod
+    def stagnated(cls, reason: str, pattern: StagnationPattern | None = None) -> RecoveryAction:
+        """Return a terminal stagnation action."""
+        return cls(kind=RecoveryActionKind.STAGNATED, reason=reason, pattern=pattern)
+
+
+class RecoveryPlanner:
+    """Choose bounded lateral recovery actions for execution loops."""
+
+    def __init__(
+        self,
+        *,
+        lateral_thinker: LateralThinker | None = None,
+        max_interventions: int = 1,
+    ) -> None:
+        self._lateral_thinker = lateral_thinker or LateralThinker()
+        self._max_interventions = max_interventions
+
+    def plan(self, snapshot: RecoverySnapshot) -> RecoveryAction:
+        """Return the next recovery action for the supplied execution snapshot."""
+        if snapshot.interventions_used >= self._max_interventions:
+            return RecoveryAction.stagnated(
+                "Recovery intervention budget exhausted",
+                snapshot.stagnation_pattern,
+            )
+
+        pattern = snapshot.stagnation_pattern or self._infer_pattern(snapshot)
+        persona = suggest_lateral_persona_for_pattern(
+            pattern,
+            failed_attempts=snapshot.failed_attempts,
+            used_personas=snapshot.used_personas,
+            lateral_thinker=self._lateral_thinker,
+        )
+        if persona is None:
+            return RecoveryAction.stagnated(
+                "No available lateral thinking persona remains after exclusions",
+                pattern,
+            )
+
+        lateral_result = self._lateral_thinker.generate_alternative(
+            persona=persona,
+            problem_context=snapshot.problem_context,
+            current_approach=snapshot.current_approach,
+            failed_attempts=snapshot.failed_attempts,
+        )
+        if lateral_result.is_err:
+            return RecoveryAction.stagnated(str(lateral_result.error), pattern)
+
+        lateral = lateral_result.unwrap()
+        reason = self._reason_for(pattern, snapshot)
+        directive = (
+            "## Lateral Recovery Directive\n"
+            f"Detected pattern: {pattern.value}\n"
+            f"Selected persona: {persona.value}\n"
+            f"Reason: {reason}\n\n"
+            "Do not repeat the failed path. Continue the same task, but switch "
+            "strategy using the lateral prompt below. Produce a concrete patch "
+            "or verification step that advances the acceptance criteria.\n\n"
+            f"{lateral.prompt}"
+        )
+        return RecoveryAction(
+            kind=RecoveryActionKind.INJECT_LATERAL_DIRECTIVE,
+            reason=reason,
+            pattern=pattern,
+            persona=persona,
+            directive=directive,
+        )
+
+    @staticmethod
+    def _infer_pattern(snapshot: RecoverySnapshot) -> StagnationPattern:
+        if snapshot.final_error.strip():
+            return StagnationPattern.SPINNING
+        if (
+            snapshot.total_count
+            and snapshot.completed_count <= 0
+            and snapshot.messages_processed >= 10
+        ):
+            return StagnationPattern.NO_DRIFT
+        return StagnationPattern.DIMINISHING_RETURNS
+
+    @staticmethod
+    def _reason_for(pattern: StagnationPattern, snapshot: RecoverySnapshot) -> str:
+        if snapshot.final_error.strip():
+            return "The previous run ended in a final error without satisfying the seed."
+        if pattern == StagnationPattern.NO_DRIFT:
+            return "No acceptance criteria have completed after sustained execution."
+        if pattern == StagnationPattern.DIMINISHING_RETURNS:
+            return "Execution appears to be making weaker progress and needs a strategy shift."
+        if pattern == StagnationPattern.OSCILLATION:
+            return "Execution appears to be alternating between approaches."
+        return "Execution appears to be repeating an unproductive path."
+
+
+def coerce_failed_attempt_personas(
+    failed_attempts: tuple[str, ...],
+    *,
+    used_personas: tuple[ThinkingPersona, ...] = (),
+) -> tuple[ThinkingPersona, ...]:
+    """Convert failed attempt strings into persona exclusions."""
+    excluded: list[ThinkingPersona] = list(used_personas)
+    for attempt in failed_attempts:
+        try:
+            persona = ThinkingPersona(attempt.strip().lower())
+        except ValueError:
+            continue
+        if persona not in excluded:
+            excluded.append(persona)
+    return tuple(excluded)
+
+
+def suggest_lateral_persona_for_pattern(
+    pattern: StagnationPattern,
+    *,
+    failed_attempts: tuple[str, ...] = (),
+    used_personas: tuple[ThinkingPersona, ...] = (),
+    lateral_thinker: LateralThinker | None = None,
+) -> ThinkingPersona | None:
+    """Suggest a persona for a stagnation pattern with shared exclusion semantics."""
+    thinker = lateral_thinker or LateralThinker()
+    return thinker.suggest_persona_for_pattern(
+        pattern,
+        exclude_personas=coerce_failed_attempt_personas(
+            failed_attempts,
+            used_personas=used_personas,
+        ),
+    )
+
+
+def get_run_recovery_protocol_prompt() -> str:
+    """Return system prompt instructions for in-run self recovery."""
+    return """## Self-Recovery Protocol
+If you notice that the run is stalled, repeating the same failed edit, or making
+no acceptance-criterion progress, switch strategy before continuing:
+- spinning: stop retrying the same fix; isolate or bypass the blocker.
+- no_drift: gather the missing fact or inspect the source of truth.
+- diminishing_returns: simplify the task and remove unnecessary moving parts.
+- oscillation: choose one architecture and make the smallest coherent step.
+
+When you switch strategy, state the detected pattern and the new concrete next
+step briefly, then continue implementing and verifying the acceptance criteria."""
+
+
+def create_recovery_applied_event(
+    *,
+    execution_id: str,
+    session_id: str,
+    action: RecoveryAction,
+    seed_id: str | None = None,
+    messages_processed: int = 0,
+    completed_count: int = 0,
+    total_count: int = 0,
+) -> BaseEvent:
+    """Create an event recording an automatic recovery intervention."""
+    return BaseEvent(
+        type="resilience.recovery.applied",
+        aggregate_type="execution",
+        aggregate_id=execution_id,
+        data={
+            "session_id": session_id,
+            "seed_id": seed_id,
+            "kind": action.kind.value,
+            "pattern": action.pattern.value if action.pattern else None,
+            "persona": action.persona.value if action.persona else None,
+            "reason": action.reason,
+            "messages_processed": messages_processed,
+            "completed_count": completed_count,
+            "total_count": total_count,
+        },
+    )
+
+
+__all__ = [
+    "RecoveryAction",
+    "RecoveryActionKind",
+    "RecoveryPlanner",
+    "RecoverySnapshot",
+    "coerce_failed_attempt_personas",
+    "create_recovery_applied_event",
+    "get_run_recovery_protocol_prompt",
+    "suggest_lateral_persona_for_pattern",
+]

ouroboros_ai-0.29.3.dev5/tests/unit/cli/test_mcp_shell_env.py

@@ -0,0 +1,38 @@
+"""Tests for MCP shell environment loading."""
+
+from __future__ import annotations
+
+import io
+import json
+import os
+import subprocess
+import sys
+
+from ouroboros.cli.commands import mcp
+
+
+def test_shell_env_loader_preserves_mcp_stdin(monkeypatch) -> None:
+    monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
+    monkeypatch.setenv("PATH", "/usr/bin")
+    monkeypatch.setenv("SHELL", "/bin/zsh")
+
+    initialize_message = '{"jsonrpc":"2.0","id":1,"method":"initialize"}\n'
+    fake_stdin = io.StringIO(initialize_message)
+    monkeypatch.setattr(sys, "stdin", fake_stdin)
+
+    calls: list[dict[str, object]] = []
+
+    def fake_run(cmd: list[str], **kwargs: object) -> subprocess.CompletedProcess[str]:
+        calls.append(kwargs)
+        if kwargs.get("stdin") != subprocess.DEVNULL:
+            sys.stdin.read()
+        stdout = json.dumps({"PATH": os.environ["PATH"], "OUROBOROS_TEST_ENV": "loaded"})
+        return subprocess.CompletedProcess(cmd, 0, stdout=stdout, stderr="")
+
+    monkeypatch.setattr(mcp.subprocess, "run", fake_run)
+
+    mcp._ensure_shell_env(timeout=1.25)
+
+    assert fake_stdin.read() == initialize_message
+    assert calls[0]["stdin"] == subprocess.DEVNULL
+    assert os.environ["OUROBOROS_TEST_ENV"] == "loaded"