ouroboros-ai 0.26.5.dev1__tar.gz → 0.26.5.dev3__tar.gz

{ouroboros_ai-0.26.5.dev1 → ouroboros_ai-0.26.5.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.26.5.dev1
+Version: 0.26.5.dev3
 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.5.dev1 → ouroboros_ai-0.26.5.dev3}/skills/pm/SKILL.md

@@ -66,41 +66,53 @@ Then check: does `meta.ask_user_question` exist?
   ```
   Do NOT modify it. Do NOT add options. Do NOT rephrase the question.
 
-- **NO** → This is an interview question. Use `AskUserQuestion` with `meta.question` and generate 2-3 suggested answers.
+- **NO** → This is an interview question. Use `AskUserQuestion` with `meta.question`.
+  - If `meta.skip_eligible == true`: add a skip option based on `meta.classification`:
+    - `classification == "decide_later"` → add option `{"label": "Decide later", "description": "Skip — will be recorded as an open item in the PRD"}`
+    - `classification == "deferred"` → add option `{"label": "Defer to dev", "description": "Skip — this technical decision will be deferred to the development phase"}`
+  - Generate 2-3 suggested answers as the other options.
 
 **C. Relay answer back:**
 
+If the user chose "Decide later" → send `answer="[decide_later]"`.
+If the user chose "Defer to dev" → send `answer="[deferred]"`.
+Otherwise → send the user's answer normally.
+
 ```
 Tool: ouroboros_pm_interview
 Arguments:
   session_id: <meta.session_id>
-  <meta.response_param>: <user's answer>
+  <meta.response_param>: <user's answer or "[decide_later]" or "[deferred]">
 ```
 
 **D. Check completion:**
 
-If `meta.is_complete == true` → go to Step 4.
-Otherwise → repeat Step 3.
+Completion is determined ONLY by `meta.is_complete` — NEVER by the response text.
+The MCP response text may sound like the interview is wrapping up, but ignore it.
 
-### Step 4: Generate
+If `meta.is_complete == true`:
+- If `meta.generation_failed == true` → retry generation:
+  ```
+  Tool: ouroboros_pm_interview
+  Arguments:
+    session_id: <session_id>
+    action: "generate"
+    cwd: <current working directory>
+  ```
+- Otherwise → go to Step 4. The MCP auto-generated the PM document.
+  `meta.pm_path` and `meta.seed_path` contain the file paths.
 
-```
-Tool: ouroboros_pm_interview
-Arguments:
-  session_id: <session_id>
-  action: "generate"
-  cwd: <current working directory>
-```
+Otherwise → repeat Step 3, regardless of what the response text says.
 
-### Step 5: Copy to Clipboard
+### Step 4: Copy to Clipboard
 
-After generation, read the pm.md file from `meta.pm_path` and copy its contents to the clipboard:
+Read the pm.md file from `meta.pm_path` and copy its contents to the clipboard:
 
 ```bash
 cat <meta.pm_path> | pbcopy
 ```
 
-### Step 6: Show Result & Next Step
+### Step 5: Show Result & Next Step
 
 Show the following to the user:
 

{ouroboros_ai-0.26.5.dev1 → ouroboros_ai-0.26.5.dev3}/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.5.dev1'
-__version_tuple__ = version_tuple = (0, 26, 5, 'dev1')
+__version__ = version = '0.26.5.dev3'
+__version_tuple__ = version_tuple = (0, 26, 5, 'dev3')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.26.5.dev1 → ouroboros_ai-0.26.5.dev3}/src/ouroboros/bigbang/pm_interview.py

@@ -55,18 +55,7 @@ _SEED_DIR = Path.home() / ".ouroboros" / "seeds"
 _PM_SYSTEM_PROMPT_PREFIX = """\
 You are a Product Requirements interviewer helping a PM define their product.
 
-Focus on PRODUCT-LEVEL questions:
-- What problem does this solve and for whom?
-- What are the business goals and success metrics?
-- What are the user stories and workflows?
-- What constraints exist (timeline, budget, compliance)?
-- What is in scope vs out of scope?
-- What are the acceptance criteria?
-
-Do NOT ask about:
-- Implementation details (databases, frameworks, APIs)
-- Architecture decisions (microservices, deployment)
-- Code-level patterns or testing strategies
+Focus on: goal, user stories, constraints, success criteria, assumptions.
 
 """
 
@@ -158,7 +147,8 @@ class PMInterviewEngine:
     """Original question text for questions classified as DECIDE_LATER.
 
     These are questions that are premature or unknowable at the PM stage.
-    They are auto-answered with a placeholder and stored here so the PMSeed
+    The main session presents the question to the user with a "decide later"
+    option; when chosen, the caller records the item here so the PMSeed
     and PM document can surface them as explicit "decide later" decisions.
     """
     classifications: list[ClassificationResult] = field(default_factory=list)
@@ -484,47 +474,39 @@ class PMInterviewEngine:
         output_type = classification.output_type
 
         if output_type == ClassifierOutputType.DEFERRED:
-            # Track as deferred item and generate a new question
-            self.deferred_items.append(classification.original_question)
+            # Return the question to the caller (main session) so the user
+            # can choose to defer it themselves.  The main session detects
+            # classification == "deferred" via response_meta and offers
+            # a "skip / defer to dev" option.  If the user picks it, the
+            # caller calls skip_as_deferred() which records the deferral
+            # and appends to deferred_items.
+            #
+            # Previously this branch auto-answered and recursed, which could
+            # trigger MCP 120s timeouts on consecutive DEFERRED runs.
             log.info(
-                "pm.question_deferred",
+                "pm.question_deferred_candidate",
                 question=classification.original_question[:100],
                 reasoning=classification.reasoning,
                 output_type=output_type,
             )
-            # Feed an automatic response back to the inner InterviewEngine
-            # so the round is properly recorded and the engine advances.
-            # This prevents the inner engine from re-generating similar
-            # technical questions it doesn't know were already handled.
-            await self.record_response(
-                state,
-                user_response="[Deferred to development phase] "
-                "This technical decision will be addressed during the "
-                "development interview.",
-                question=classification.original_question,
-            )
-            # Recursively ask for the next real question
-            return await self.ask_next_question(state)
+            return Result.ok(classification.original_question)
 
         if output_type == ClassifierOutputType.DECIDE_LATER:
-            # Auto-answer with placeholder — no PM interaction needed
-            placeholder = classification.placeholder_response
-            self.decide_later_items.append(classification.original_question)
+            # Return the question to the caller (main session) so the user
+            # can choose "decide later" themselves.  The main session detects
+            # classification == "decide_later" via response_meta and offers
+            # the option.  If the user picks it, the caller calls
+            # skip_as_decide_later() which records the placeholder and
+            # appends to decide_later_items.
+            #
+            # Previously this branch auto-answered and recursed, which could
+            # trigger MCP 120s timeouts on consecutive DECIDE_LATER runs.
             log.info(
                 "pm.question_decide_later",
                 question=classification.original_question[:100],
-                placeholder=placeholder[:100],
                 reasoning=classification.reasoning,
             )
-            # Record the placeholder as the response so the interview
-            # engine advances its round count
-            await self.record_response(
-                state,
-                user_response=f"[Decide later] {placeholder}",
-                question=classification.original_question,
-            )
-            # Recursively ask for the next real question
-            return await self.ask_next_question(state)
+            return Result.ok(classification.original_question)
 
         if output_type == ClassifierOutputType.REFRAMED:
             # Use the reframed version and track the mapping
@@ -595,6 +577,76 @@ class PMInterviewEngine:
 
         return await self.inner.record_response(state, user_response, question)
 
+    async def skip_as_decide_later(
+        self,
+        state: InterviewState,
+        question: str,
+    ) -> Result[InterviewState, ValidationError]:
+        """Skip a question as "decide later" at the user's explicit request.
+
+        Records the question in ``decide_later_items`` and feeds a placeholder
+        response to the inner InterviewEngine so the round is properly recorded
+        and the engine advances.
+
+        This is called when the main session detects that the user chose the
+        "decide later" option for a DECIDE_LATER-classified question, instead
+        of the old auto-skip behavior inside ``ask_next_question``.
+
+        Args:
+            state: Current interview state.
+            question: The question the user chose to decide later.
+
+        Returns:
+            Result containing updated state or ValidationError.
+        """
+        if question not in self.decide_later_items:
+            self.decide_later_items.append(question)
+
+        log.info(
+            "pm.question_decide_later_by_user",
+            question=question[:100],
+        )
+
+        return await self.record_response(
+            state,
+            user_response="[Decide later] To be determined — user chose to decide later.",
+            question=question,
+        )
+
+    async def skip_as_deferred(
+        self,
+        state: InterviewState,
+        question: str,
+    ) -> Result[InterviewState, ValidationError]:
+        """Skip a question as "deferred to dev" at the user's explicit request.
+
+        Records the question in ``deferred_items`` and feeds a deferral
+        response to the inner InterviewEngine so the round is properly recorded
+        and the engine advances.
+
+        Args:
+            state: Current interview state.
+            question: The question the user chose to defer.
+
+        Returns:
+            Result containing updated state or ValidationError.
+        """
+        if question not in self.deferred_items:
+            self.deferred_items.append(question)
+
+        log.info(
+            "pm.question_deferred_by_user",
+            question=question[:100],
+        )
+
+        return await self.record_response(
+            state,
+            user_response="[Deferred to development phase] "
+            "This technical decision will be addressed during the "
+            "development interview.",
+            question=question,
+        )
+
     async def complete_interview(
         self,
         state: InterviewState,
@@ -1129,13 +1181,14 @@ Include them as original question text in "decide_later_items":
             for s in data.get("user_stories", [])
         )
 
-        # Merge deferred items from classifier with extraction
+        # Merge LLM-extracted items with engine-tracked items, deduplicating.
+        # The extraction prompt includes raw items as context so the LLM may
+        # already emit them, but engine-tracked items are authoritative and
+        # must survive even if the extractor omits them.
         all_deferred = list(data.get("deferred_items", []))
         for item in self.deferred_items:
             if item not in all_deferred:
                 all_deferred.append(item)
-
-        # Merge decide-later items — stored as original question text
         all_decide_later = list(data.get("decide_later_items", []))
         for item in self.decide_later_items:
             if item not in all_decide_later:

{ouroboros_ai-0.26.5.dev1 → ouroboros_ai-0.26.5.dev3}/src/ouroboros/bigbang/question_classifier.py

@@ -3,9 +3,10 @@
 Classifies generated questions as PM-answerable (planning), DEV-only
 (development/technical), or decide-later (premature/unknowable).
 
-DEV-only questions are reframed into PM-friendly language or deferred to
-the development interview phase. Decide-later questions get an automatic
-placeholder response without PM interaction.
+DEV-only questions are reframed into PM-friendly language or returned to
+the user with the option to defer to the development interview phase.
+Decide-later questions are returned to the user with the option to defer
+rather than being automatically skipped.
 
 Uses a Sonnet-grade model for accurate judgment and reframing.
 """
@@ -51,8 +52,8 @@ class ClassifierOutputType(StrEnum):
 
     PASSTHROUGH: Planning question forwarded unchanged to the PM.
     REFRAMED: Development question rewritten in PM-friendly language.
-    DEFERRED: Deeply technical question deferred to the dev interview phase.
-    DECIDE_LATER: Premature question auto-answered with a placeholder.
+    DEFERRED: Deeply technical question returned to user with defer option.
+    DECIDE_LATER: Premature question returned to user with decide-later option.
     """
 
     PASSTHROUGH = "passthrough"
@@ -73,8 +74,9 @@ class ClassificationResult:
         reasoning: Why the classifier chose this category.
         defer_to_dev: Whether this question should be deferred entirely.
         decide_later: Whether this question is premature and should be
-            auto-answered with a placeholder.
-        placeholder_response: Automatic response for decide-later questions.
+            returned to the user with the option to defer.
+        placeholder_response: Placeholder response for decide-later questions
+            (used if the user chooses to defer).
     """
 
     original_question: str
@@ -90,8 +92,10 @@ class ClassificationResult:
         """Determine the classifier output type for this result.
 
         Returns:
-            DECIDE_LATER if premature/unknowable question (auto-answered),
-            DEFERRED if deeply technical (skipped entirely),
+            DECIDE_LATER if premature/unknowable question (returned to user
+                with option to defer),
+            DEFERRED if deeply technical (returned to user with option to
+                defer to dev phase),
             PASSTHROUGH if planning question (forwarded unchanged),
             REFRAMED if development question rewritten for PM.
         """
@@ -109,13 +113,20 @@ class ClassificationResult:
 
         For PASSTHROUGH: returns original_question unchanged.
         For REFRAMED: returns the reframed_question.
-        For DEFERRED: returns empty string (should not be shown).
-        For DECIDE_LATER: returns empty string (auto-answered).
+        For DEFERRED: returns original_question (shown to user
+            so they can choose to answer or defer to dev).
+        For DECIDE_LATER: returns original_question (shown to user
+            so they can choose to answer or defer).
         """
         if self.output_type == ClassifierOutputType.PASSTHROUGH:
             return self.original_question
         if self.output_type == ClassifierOutputType.REFRAMED:
             return self.reframed_question
+        if self.output_type in (
+            ClassifierOutputType.DECIDE_LATER,
+            ClassifierOutputType.DEFERRED,
+        ):
+            return self.original_question
         return ""
 
 
@@ -181,7 +192,8 @@ class QuestionClassifier:
 
     Uses a Sonnet-grade LLM to judge whether questions are appropriate
     for a PM audience, reframes technical questions when possible, and
-    identifies premature questions that should be auto-answered.
+    identifies premature questions that should be returned to the user
+    with the option to defer.
 
     Attributes:
         llm_adapter: LLM adapter for classification calls.

{ouroboros_ai-0.26.5.dev1 → ouroboros_ai-0.26.5.dev3}/src/ouroboros/cli/commands/init.py

@@ -10,8 +10,6 @@ from pathlib import Path
 from typing import Annotated
 
 import click
-from prompt_toolkit import PromptSession
-from prompt_toolkit.key_binding import KeyBindings, KeyPressEvent
 from rich.prompt import Confirm, Prompt
 import typer
 import yaml
@@ -26,6 +24,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.cli.formatters.prompting import multiline_prompt_async
 from ouroboros.config import get_clarification_model
 from ouroboros.observability import LoggingConfig, configure_logging
 from ouroboros.providers import create_llm_adapter
@@ -104,46 +103,6 @@ def _make_message_callback(debug: bool):
     return callback
 
 
-async def _multiline_prompt_async(prompt_text: str) -> str:
-    """Get multiline input with proper paste handling.
-
-    Behavior:
-    - Enter: Submit input
-    - Ctrl+J: Insert newline
-    - Paste: Multiline text is preserved (via bracketed paste mode)
-
-    Args:
-        prompt_text: The prompt to display.
-
-    Returns:
-        The user's input (may contain newlines from paste).
-
-    Raises:
-        EOFError: If end-of-file is reached (e.g., stdin closed).
-        KeyboardInterrupt: If user presses Ctrl+C.
-    """
-    bindings = KeyBindings()
-
-    @bindings.add("c-j")
-    def insert_newline(event: KeyPressEvent) -> None:
-        event.current_buffer.insert_text("\n")
-
-    @bindings.add("c-m")
-    def submit(event: KeyPressEvent) -> None:
-        event.current_buffer.validate_and_handle()
-
-    console.print(f"[bold green]{prompt_text}[/] [dim](Enter: submit, Ctrl+J: newline)[/]")
-
-    session: PromptSession[str] = PromptSession(
-        message="> ",
-        multiline=True,
-        prompt_continuation="  ",
-        key_bindings=bindings,
-    )
-
-    return await session.prompt_async()
-
-
 def _get_adapter(
     use_orchestrator: bool,
     backend: str | None = None,
@@ -219,7 +178,7 @@ async def _run_interview_loop(
         console.print()
 
         # Get user response (multiline-safe for paste)
-        response = await _multiline_prompt_async("Your response")
+        response = await multiline_prompt_async("Your response")
 
         if not response.strip():
             print_error("Response cannot be empty. Please try again.")
@@ -791,7 +750,7 @@ def start(
             )
             console.print()
 
-            context = asyncio.run(_multiline_prompt_async("What would you like to build?"))
+            context = asyncio.run(multiline_prompt_async("What would you like to build?"))
 
     if not resume and not context:
         print_error("Initial context is required when not resuming.")

{ouroboros_ai-0.26.5.dev1 → ouroboros_ai-0.26.5.dev3}/src/ouroboros/cli/commands/pm.py

@@ -19,8 +19,10 @@ import typer
 from ouroboros.bigbang.interview import InterviewRound
 from ouroboros.cli.formatters import console
 from ouroboros.cli.formatters.panels import print_error, print_info, print_success, print_warning
+from ouroboros.cli.formatters.prompting import multiline_prompt_async
 from ouroboros.config import get_clarification_model
 from ouroboros.core.types import Result
+from ouroboros.observability import LoggingConfig, configure_logging
 
 app = typer.Typer(
     name="pm",
@@ -108,6 +110,10 @@ def pm_command(
     if model is None:
         model = get_clarification_model()
 
+    if debug:
+        configure_logging(LoggingConfig(log_level="DEBUG"))
+        print_info("Debug mode enabled - showing verbose logs")
+
     console.print("\n[bold cyan]Ouroboros PM Generator[/] - Product Requirements Document\n")
 
     if resume:
@@ -392,12 +398,13 @@ async def _run_pm_interview(
         opening = engine.get_opening_question()
         console.print(f"\n[bold yellow]?[/] {opening}\n")
 
-        user_answer = console.input("[bold green]> [/]")
+        user_answer = await multiline_prompt_async("Your response")
 
         if not user_answer.strip():
             print_error("No response provided. Exiting.")
             raise typer.Exit(code=1)
 
+        print_info("Starting interview...")
         state_result = await engine.ask_opening_and_start(
             user_response=user_answer,
             brownfield_repos=brownfield_repos if brownfield_repos else None,
@@ -417,6 +424,7 @@ async def _run_pm_interview(
         if state.rounds and state.rounds[-1].user_response is None:
             question = state.rounds[-1].question
         else:
+            print_info("Generating next question...")
             q_result = await engine.ask_next_question(state)
             if q_result.is_err:
                 print_error(f"Question generation failed: {q_result.error}")
@@ -439,6 +447,20 @@ async def _run_pm_interview(
 
         console.print(f"\n[bold yellow]?[/] {question}\n")
 
+        # Check if this question was classified as skippable —
+        # if so, show a hint that the user can defer it.
+        classification = engine.get_last_classification()
+        if classification == "decide_later":
+            console.print(
+                "[dim]  💡 This question can be deferred. "
+                'Type "decide later" or "skip" to defer it.[/]\n'
+            )
+        elif classification == "deferred":
+            console.print(
+                "[dim]  💡 This is a technical question that can be deferred to the dev phase. "
+                'Type "defer" or "skip" to defer it.[/]\n'
+            )
+
         # Persist state + meta AFTER displaying the question but BEFORE
         # waiting for input so that an interruption preserves the pending
         # question and --resume shows the same question.
@@ -448,7 +470,7 @@ async def _run_pm_interview(
             break
         _save_cli_pm_meta(state.interview_id, engine)
 
-        user_response = console.input("[bold green]> [/]")
+        user_response = await multiline_prompt_async("Your response")
 
         # Allow early exit
         if user_response.strip().lower() in ("done", "exit", "quit", "/done"):
@@ -460,6 +482,8 @@ async def _run_pm_interview(
             complete_result = await engine.complete_interview(state)
             if isinstance(complete_result, Result) and complete_result.is_err:
                 print_error(f"Failed to complete interview: {complete_result.error}")
+            elif isinstance(complete_result, Result):
+                state = complete_result.value
             save_result = await engine.save_state(state)
             if isinstance(save_result, Result) and save_result.is_err:
                 print_error(f"Failed to save completed state: {save_result.error}")
@@ -471,10 +495,45 @@ async def _run_pm_interview(
         if state.rounds and state.rounds[-1].user_response is None:
             state.rounds.pop()
 
+        # Handle user-initiated skip (decide later / defer to dev)
+        _lower = user_response.strip().lower()
+        if classification == "decide_later" and _lower in (
+            "decide later",
+            "skip",
+            "[decide_later]",
+        ):
+            record_result = await engine.skip_as_decide_later(state, question)
+            if isinstance(record_result, Result) and record_result.is_err:
+                print_error(f"Failed to skip question: {record_result.error}")
+                break
+            save_result = await engine.save_state(state)
+            if isinstance(save_result, Result) and save_result.is_err:
+                print_error(f"Failed to save state: {save_result.error}")
+                break
+            _save_cli_pm_meta(state.interview_id, engine)
+            continue
+        if classification == "deferred" and _lower in (
+            "defer",
+            "skip",
+            "[deferred]",
+        ):
+            record_result = await engine.skip_as_deferred(state, question)
+            if isinstance(record_result, Result) and record_result.is_err:
+                print_error(f"Failed to defer question: {record_result.error}")
+                break
+            save_result = await engine.save_state(state)
+            if isinstance(save_result, Result) and save_result.is_err:
+                print_error(f"Failed to save state: {save_result.error}")
+                break
+            _save_cli_pm_meta(state.interview_id, engine)
+            continue
+
         record_result = await engine.record_response(state, user_response, question)
         if isinstance(record_result, Result) and record_result.is_err:
             print_error(f"Failed to record response: {record_result.error}")
             break
+        if isinstance(record_result, Result):
+            state = record_result.value
         save_result = await engine.save_state(state)
         if isinstance(save_result, Result) and save_result.is_err:
             print_error(f"Failed to save state: {save_result.error}")

ouroboros_ai-0.26.5.dev3/src/ouroboros/cli/formatters/prompting.py

@@ -0,0 +1,38 @@
+"""Prompt helpers for interactive CLI input."""
+
+from __future__ import annotations
+
+from prompt_toolkit import PromptSession
+from prompt_toolkit.key_binding import KeyBindings, KeyPressEvent
+from prompt_toolkit.patch_stdout import patch_stdout
+
+from ouroboros.cli.formatters import console
+
+
+async def multiline_prompt_async(prompt_text: str) -> str:
+    """Get multiline-safe input while allowing logs above the active prompt."""
+    bindings = KeyBindings()
+
+    @bindings.add("c-j")
+    def insert_newline(event: KeyPressEvent) -> None:
+        event.current_buffer.insert_text("\n")
+
+    @bindings.add("c-m")
+    def submit(event: KeyPressEvent) -> None:
+        event.current_buffer.validate_and_handle()
+
+    console.print(f"[bold green]{prompt_text}[/] [dim](Enter: submit, Ctrl+J: newline)[/]")
+
+    session: PromptSession[str] = PromptSession(
+        message="> ",
+        multiline=True,
+        prompt_continuation="  ",
+        key_bindings=bindings,
+    )
+
+    # prompt_toolkit proxies both stdout and stderr above the prompt.
+    with patch_stdout(raw=True):
+        return await session.prompt_async()
+
+
+__all__ = ["multiline_prompt_async"]