ouroboros-ai 0.26.7.dev7__tar.gz → 0.27.1.dev1__tar.gz

{ouroboros_ai-0.26.7.dev7 → ouroboros_ai-0.27.1.dev1}/.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.26.6",
+      "version": "0.27.0",
       "author": {
         "name": "Q00",
         "email": "jqyu.lee@gmail.com"

{ouroboros_ai-0.26.7.dev7 → ouroboros_ai-0.27.1.dev1}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ouroboros",
-  "version": "0.26.6",
+  "version": "0.27.0",
   "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.26.7.dev7 → ouroboros_ai-0.27.1.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.26.7.dev7
+Version: 0.27.1.dev1
 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.26.7.dev7 → ouroboros_ai-0.27.1.dev1}/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.26.6 -->
+<!-- ooo:VERSION:0.27.0 -->
 # Ouroboros — Specification-First AI Development
 
 > Before telling AI what to build, define what should be built.

{ouroboros_ai-0.26.7.dev7 → ouroboros_ai-0.27.1.dev1}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.26.7.dev7'
-__version_tuple__ = version_tuple = (0, 26, 7, 'dev7')
+__version__ = version = '0.27.1.dev1'
+__version_tuple__ = version_tuple = (0, 27, 1, 'dev1')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.26.7.dev7 → ouroboros_ai-0.27.1.dev1}/src/ouroboros/mcp/tools/authoring_handlers.py

@@ -706,7 +706,11 @@ class InterviewHandler:
 
                 state = result.value
                 _interview_id = state.interview_id
-                live_score = await self._score_interview_state(llm_adapter, state)
+                # No answers exist yet — scoring cannot trigger completion
+                # and would waste an LLM call (~3-8s). The PM handler
+                # already skips scoring before MIN_ROUNDS_BEFORE_EARLY_EXIT
+                # (pm_interview.py:889); apply the same optimisation here.
+                live_score = None
                 question_result = await engine.ask_next_question(state)
                 if question_result.is_err:
                     error_msg = str(question_result.error)
@@ -919,18 +923,23 @@ class InterviewHandler:
                     # question generation failures downstream
                     await engine.save_state(state)
 
-                    live_score = await self._score_interview_state(llm_adapter, state)
-                    if (
-                        live_score is not None
-                        and live_score.is_ready_for_seed
-                        and _count_answered_rounds(state) >= MIN_ROUNDS_BEFORE_EARLY_EXIT
-                    ):
-                        return await self._complete_interview_response(
-                            engine,
-                            state,
-                            session_id,
-                            live_score,
-                        )
+                    # Only score ambiguity when completion is actually
+                    # possible.  Before MIN_ROUNDS_BEFORE_EARLY_EXIT the
+                    # result cannot trigger early exit, so the LLM call
+                    # (~3-8 s) is pure waste.  The PM handler already
+                    # applies this guard (pm_interview.py:889).
+                    answered = _count_answered_rounds(state)
+                    if answered >= MIN_ROUNDS_BEFORE_EARLY_EXIT:
+                        live_score = await self._score_interview_state(llm_adapter, state)
+                        if live_score is not None and live_score.is_ready_for_seed:
+                            return await self._complete_interview_response(
+                                engine,
+                                state,
+                                session_id,
+                                live_score,
+                            )
+                    else:
+                        live_score = None
                 else:
                     live_score = _load_state_ambiguity_score(state)
 

{ouroboros_ai-0.26.7.dev7 → ouroboros_ai-0.27.1.dev1}/tests/unit/mcp/tools/test_definitions.py

@@ -1494,7 +1494,10 @@ class TestInterviewHandlerCwd:
         mock_engine.start_interview.assert_awaited_once()
         call_kwargs = mock_engine.start_interview.call_args
         assert call_kwargs[1]["cwd"] == str(tmp_path)
-        assert "(ambiguity: 0.67) First question?" in result.value.content[0].text
+        # Scoring is now skipped on interview start (0 answered rounds cannot
+        # trigger early completion), so the question appears without an
+        # ambiguity prefix.  See https://github.com/Q00/ouroboros/issues/283
+        assert "First question?" in result.value.content[0].text
 
     async def test_interview_handle_resolves_pm_seed_paths(self, tmp_path) -> None:
         """initial_context paths should load PMSeed content before starting the interview."""
@@ -1543,18 +1546,26 @@ class TestInterviewHandlerCwd:
         assert str(seed_path) not in resolved_context
 
     async def test_interview_handle_clears_stored_ambiguity_after_new_answer(self) -> None:
-        """Interview answers should refresh the ambiguity snapshot after rescoring."""
+        """Interview answers should refresh the ambiguity snapshot after rescoring.
+
+        Scoring only runs when answered rounds >= MIN_ROUNDS_BEFORE_EARLY_EXIT
+        (currently 3), so this test creates enough answered rounds to cross
+        the threshold.  See https://github.com/Q00/ouroboros/issues/283
+        """
         handler = InterviewHandler(llm_adapter=MagicMock())
         state = InterviewState(
             interview_id="sess-123",
             ambiguity_score=0.14,
             ambiguity_breakdown={"goal_clarity": {"name": "goal_clarity"}},
             rounds=[
+                InterviewRound(round_number=1, question="Q1?", user_response="A1"),
+                InterviewRound(round_number=2, question="Q2?", user_response="A2"),
+                InterviewRound(round_number=3, question="Q3?", user_response="A3"),
                 InterviewRound(
-                    round_number=1,
+                    round_number=4,
                     question="What should it do?",
                     user_response=None,
-                )
+                ),
             ],
         )
         mock_engine = MagicMock()

ouroboros_ai-0.27.1.dev1/tests/unit/mcp/tools/test_interview_scoring_guard.py

@@ -0,0 +1,246 @@
+"""Tests for InterviewHandler — ambiguity scoring guard.
+
+Regression coverage for the performance issue where ambiguity scoring
+was invoked on every interview step, even when early completion was
+impossible (rounds < MIN_ROUNDS_BEFORE_EARLY_EXIT).
+
+See: https://github.com/Q00/ouroboros/issues/283
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from ouroboros.bigbang.ambiguity import AmbiguityScore, ComponentScore, ScoreBreakdown
+from ouroboros.bigbang.interview import (
+    MIN_ROUNDS_BEFORE_EARLY_EXIT,
+    InterviewRound,
+    InterviewState,
+    InterviewStatus,
+)
+from ouroboros.mcp.tools.authoring_handlers import InterviewHandler
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+
+def _make_state(
+    interview_id: str = "test-001",
+    answered_rounds: int = 0,
+) -> InterviewState:
+    """Create an InterviewState with the given number of answered rounds."""
+    rounds = [
+        InterviewRound(
+            round_number=i + 1,
+            question=f"Q{i + 1}",
+            user_response=f"A{i + 1}",
+        )
+        for i in range(answered_rounds)
+    ]
+    # Append one unanswered round (the pending question) if rounds exist
+    if answered_rounds > 0:
+        rounds.append(
+            InterviewRound(
+                round_number=answered_rounds + 1,
+                question=f"Q{answered_rounds + 1}",
+                user_response=None,
+            )
+        )
+    return InterviewState(
+        interview_id=interview_id,
+        initial_context="Build a test app",
+        rounds=rounds,
+        status=InterviewStatus.IN_PROGRESS,
+    )
+
+
+def _make_component(name: str = "test") -> ComponentScore:
+    """Create a minimal ComponentScore."""
+    return ComponentScore(name=name, clarity_score=0.9, weight=1.0, justification="clear")
+
+
+def _make_ready_score() -> AmbiguityScore:
+    """Create an AmbiguityScore that would trigger early completion."""
+    breakdown = ScoreBreakdown(
+        goal_clarity=_make_component("goal"),
+        constraint_clarity=_make_component("constraints"),
+        success_criteria_clarity=_make_component("success_criteria"),
+    )
+    # overall_score=0.1 → is_ready_for_seed property returns True (≤ 0.2)
+    return AmbiguityScore(overall_score=0.1, breakdown=breakdown)
+
+
+def _build_handler() -> InterviewHandler:
+    """Build an InterviewHandler with mocked dependencies."""
+    return InterviewHandler(
+        llm_backend="claude",
+        event_store=None,
+    )
+
+
+# ── Tests ────────────────────────────────────────────────────────────────────
+
+
+class TestScoringSkippedOnInterviewStart:
+    """Ambiguity scoring must NOT run when starting a new interview."""
+
+    @pytest.mark.asyncio
+    async def test_start_does_not_call_score(self) -> None:
+        """On interview start (0 answered rounds), scoring is skipped."""
+        handler = _build_handler()
+
+        mock_engine = MagicMock()
+        mock_engine.start_interview = AsyncMock(
+            return_value=MagicMock(
+                is_err=False,
+                value=_make_state(answered_rounds=0),
+            )
+        )
+        mock_engine.ask_next_question = AsyncMock(
+            return_value=MagicMock(is_err=False, value="What framework?")
+        )
+        mock_engine.save_state = AsyncMock(return_value=MagicMock(is_err=False))
+
+        with (
+            patch.object(handler, "_score_interview_state", new_callable=AsyncMock) as mock_score,
+            patch(
+                "ouroboros.mcp.tools.authoring_handlers.create_llm_adapter",
+                return_value=MagicMock(),
+            ),
+            patch(
+                "ouroboros.mcp.tools.authoring_handlers.InterviewEngine",
+                return_value=mock_engine,
+            ),
+            patch(
+                "ouroboros.mcp.tools.authoring_handlers.resolve_initial_context_input",
+                return_value=MagicMock(is_err=False, value="Build a test app"),
+            ),
+        ):
+            await handler.handle({"initial_context": "Build a test app", "cwd": "/tmp"})
+
+            # Scoring should NOT have been called
+            mock_score.assert_not_called()
+
+            # But question generation should still proceed
+            mock_engine.ask_next_question.assert_called_once()
+
+
+class TestScoringSkippedOnEarlyRounds:
+    """Ambiguity scoring must NOT run when answered rounds < MIN_ROUNDS."""
+
+    @pytest.mark.asyncio
+    async def test_round_1_answer_skips_scoring(self) -> None:
+        """Answering round 1 (1 answered round) does not trigger scoring."""
+        handler = _build_handler()
+
+        state = _make_state(answered_rounds=1)
+
+        mock_engine = MagicMock()
+        mock_engine.load_state = AsyncMock(return_value=MagicMock(is_err=False, value=state))
+        mock_engine.record_response = AsyncMock(return_value=MagicMock(is_err=False, value=state))
+        mock_engine.ask_next_question = AsyncMock(
+            return_value=MagicMock(is_err=False, value="Next question?")
+        )
+        mock_engine.save_state = AsyncMock(return_value=MagicMock(is_err=False))
+
+        with (
+            patch.object(handler, "_score_interview_state", new_callable=AsyncMock) as mock_score,
+            patch.object(handler, "_emit_event", new_callable=AsyncMock),
+            patch(
+                "ouroboros.mcp.tools.authoring_handlers.create_llm_adapter",
+                return_value=MagicMock(),
+            ),
+            patch(
+                "ouroboros.mcp.tools.authoring_handlers.InterviewEngine",
+                return_value=mock_engine,
+            ),
+        ):
+            await handler.handle({"session_id": "test-001", "answer": "React with TypeScript"})
+
+            mock_score.assert_not_called()
+            mock_engine.ask_next_question.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_round_2_answer_skips_scoring(self) -> None:
+        """Answering round 2 (2 answered rounds) does not trigger scoring."""
+        handler = _build_handler()
+
+        state = _make_state(answered_rounds=2)
+
+        mock_engine = MagicMock()
+        mock_engine.load_state = AsyncMock(return_value=MagicMock(is_err=False, value=state))
+        mock_engine.record_response = AsyncMock(return_value=MagicMock(is_err=False, value=state))
+        mock_engine.ask_next_question = AsyncMock(
+            return_value=MagicMock(is_err=False, value="Next question?")
+        )
+        mock_engine.save_state = AsyncMock(return_value=MagicMock(is_err=False))
+
+        with (
+            patch.object(handler, "_score_interview_state", new_callable=AsyncMock) as mock_score,
+            patch.object(handler, "_emit_event", new_callable=AsyncMock),
+            patch(
+                "ouroboros.mcp.tools.authoring_handlers.create_llm_adapter",
+                return_value=MagicMock(),
+            ),
+            patch(
+                "ouroboros.mcp.tools.authoring_handlers.InterviewEngine",
+                return_value=mock_engine,
+            ),
+        ):
+            await handler.handle({"session_id": "test-001", "answer": "PostgreSQL"})
+
+            mock_score.assert_not_called()
+
+
+class TestScoringRunsWhenCompletionPossible:
+    """Ambiguity scoring MUST run when answered rounds >= MIN_ROUNDS."""
+
+    @pytest.mark.asyncio
+    async def test_round_at_threshold_triggers_scoring(self) -> None:
+        """Answering at MIN_ROUNDS_BEFORE_EARLY_EXIT triggers scoring."""
+        handler = _build_handler()
+
+        state = _make_state(answered_rounds=MIN_ROUNDS_BEFORE_EARLY_EXIT)
+
+        mock_engine = MagicMock()
+        mock_engine.load_state = AsyncMock(return_value=MagicMock(is_err=False, value=state))
+        mock_engine.record_response = AsyncMock(return_value=MagicMock(is_err=False, value=state))
+        mock_engine.ask_next_question = AsyncMock(
+            return_value=MagicMock(is_err=False, value="Another question?")
+        )
+        mock_engine.save_state = AsyncMock(return_value=MagicMock(is_err=False))
+
+        # overall_score=0.5 → is_ready_for_seed returns False (> 0.2)
+        not_ready_score = AmbiguityScore(
+            overall_score=0.5,
+            breakdown=ScoreBreakdown(
+                goal_clarity=_make_component("goal"),
+                constraint_clarity=_make_component("constraints"),
+                success_criteria_clarity=_make_component("success_criteria"),
+            ),
+        )
+        assert not not_ready_score.is_ready_for_seed
+
+        with (
+            patch.object(
+                handler,
+                "_score_interview_state",
+                new_callable=AsyncMock,
+                return_value=not_ready_score,
+            ) as mock_score,
+            patch.object(handler, "_emit_event", new_callable=AsyncMock),
+            patch(
+                "ouroboros.mcp.tools.authoring_handlers.create_llm_adapter",
+                return_value=MagicMock(),
+            ),
+            patch(
+                "ouroboros.mcp.tools.authoring_handlers.InterviewEngine",
+                return_value=mock_engine,
+            ),
+        ):
+            await handler.handle({"session_id": "test-001", "answer": "Yes, that's the plan"})
+
+            # Scoring SHOULD be called at threshold
+            mock_score.assert_called_once()
+            mock_engine.ask_next_question.assert_called_once()