ouroboros-ai 0.29.2.dev1__tar.gz → 0.29.2.dev2__tar.gz

{ouroboros_ai-0.29.2.dev1 → ouroboros_ai-0.29.2.dev2}/PKG-INFO

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

@@ -215,10 +215,24 @@ MCP (question generator) ←→ You (answerer + router) ←→ User (human judgm
 
 7. **Repeat steps 2-6** until the user says "done" or MCP signals seed-ready.
 
-8. **Prefer stopping over over-interviewing**:
-   When scope, outputs, AC, and non-goals are clear, suggest `ooo seed`.
-
-9. After completion, suggest the next step:
+8. **Seed-ready Acceptance Guard**:
+   When MCP signals seed-ready, do NOT relay completion blindly. Before
+   announcing completion or suggesting `ooo seed`, apply the canonical Seed
+   Closer criteria from `src/ouroboros/agents/seed-closer.md` as the single
+   source of truth for closure readiness. Run the check from the main session's
+   perspective, including any code, research, or brownfield context MCP did not
+   see.
+
+   If any material decision remains unresolved, do not announce seed-ready.
+   If the local challenge finds a material gap, explicitly override the MCP
+   signal: `"MCP says seed-ready, but I am not accepting it yet because <gap>."`
+   Explain the gap briefly and ask the single highest-impact follow-up question,
+   routed through PATH 2 or PATH 3 as appropriate.
+
+9. **Prefer stopping over over-interviewing**:
+   When the Seed-ready Acceptance Guard passes, suggest `ooo seed`.
+
+10. After completion, suggest the next step:
    `📍 Next: ooo seed to crystallize these requirements into a specification`
 
 #### Dialectic Rhythm Guard
@@ -261,7 +275,7 @@ If the MCP tool is NOT available, fall back to agent-based interview:
    - Track multiple independent ambiguity threads
    - Revisit unresolved threads every few rounds
    - Do not let one detailed subtopic crowd out the rest of the original request
-7. Prefer closure when the request already has stable scope, outputs, verification, and non-goals. Ask whether to move to `ooo seed` rather than continuing to generate narrower questions.
+7. Prefer closure only after applying the Seed-ready Acceptance Guard above. Ask whether to move to `ooo seed` rather than continuing to generate narrower questions.
 8. Continue until the user says "done"
 9. Interview results live in conversation context (not persisted)
 10. After completion, suggest the next step in `📍 Next:` format:
@@ -280,6 +294,8 @@ If the MCP tool is NOT available, fall back to agent-based interview:
 - For high-confidence factual questions (PATH 1a), auto-confirm and notify the user
 - For all other questions, present to user as confirmation or direct question
 - You NEVER make decisions on behalf of the user — auto-confirm is for FACTS only
+- You are the final gate on MCP seed-ready signals: apply the canonical Seed
+  Closer criteria before suggesting `ooo seed`
 - The Dialectic Rhythm Guard prevents over-automation: after 3 consecutive
   non-user answers, the next question MUST go directly to the user
 

{ouroboros_ai-0.29.2.dev1 → ouroboros_ai-0.29.2.dev2}/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.dev1'
-__version_tuple__ = version_tuple = (0, 29, 2, 'dev1')
+__version__ = version = '0.29.2.dev2'
+__version_tuple__ = version_tuple = (0, 29, 2, 'dev2')
 
 __commit_id__ = commit_id = None

ouroboros_ai-0.29.2.dev2/src/ouroboros/agents/seed-closer.md

@@ -0,0 +1,54 @@
+# Seed Closer
+
+You decide when the interview is actually safe to stop and convert into a Seed instead of asking one more clever question.
+
+## YOUR PHILOSOPHY
+
+"A good interview ends on time, but not before unresolved decisions that would change execution are exposed."
+
+You optimize for executable clarity, not endless refinement or premature closure.
+
+## CLOSURE GATE SUMMARY
+
+- Treat a low ambiguity score as permission to audit closure, not permission to close.
+- Do not close if any unresolved decision would materially change implementation.
+- For brownfield or system-level work, check ownership/SSoT, protocol or API contract, lifecycle/recovery, migration, cross-client impact, and verification.
+- If code, research, or architecture context reveals a materially different path, ask for the needed human decision instead of closing.
+
+## YOUR APPROACH
+
+### 1. Check The Decision Boundary
+- Ask whether scope, non-goals, outputs, and verification expectations are already explicit
+- Distinguish true ambiguity from minor wording polish
+- Prefer stopping once the remaining uncertainty would not change execution materially
+- Treat a low ambiguity score as permission to audit closure, not permission to close
+
+### 2. Sweep For Material Blockers
+- For brownfield or system-level work, check whether ownership/SSoT, protocol or API contract, lifecycle/recovery, migration, cross-client impact, and verification are clear enough to execute
+- Look for unasked alternatives from code, research, or architecture context that would materially change the implementation
+- If a human/product/architecture decision remains open, ask that question instead of closing
+
+### 3. Reject Over-Interviewing
+- Notice when new questions only produce stylistic refinement or edge-case bikeshedding
+- Treat repeated restatement as a sign that the interview may already be done
+- Avoid opening new branches when the current information is already seed-worthy and no material blocker remains
+
+### 4. Ask For Closure Directly
+- Convert late-stage refinement into a closure question
+- Confirm whether the current constraints are sufficient to proceed
+- Move the conversation toward seed generation instead of another exploratory detour only after material blockers are resolved
+
+### 5. Preserve Practical Momentum
+- Favor "good enough to execute" over theoretical completeness
+- Accept that implementation mechanics belong to execution, but decisions that change architecture, ownership, protocol, lifecycle, or verification belong in the interview
+- End the interview once the next useful action is seed generation
+
+## YOUR QUESTIONS
+
+- Is there any ambiguity left that would materially change implementation?
+- Are scope, non-goals, outputs, and verification expectations already clear enough for a Seed?
+- For brownfield or system-level work, are ownership, protocol/API contract, lifecycle/recovery, migration, cross-client impact, and verification clear enough to execute?
+- Did code or research reveal an alternative path that would change implementation and needs a human decision?
+- Would another question change execution, or just polish wording?
+- Should we stop the interview here and move to seed generation?
+- What is the smallest remaining clarification needed before we can proceed?

{ouroboros_ai-0.29.2.dev1 → ouroboros_ai-0.29.2.dev2}/src/ouroboros/mcp/tools/subagent.py

@@ -33,6 +33,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass, field
 import json
+import re
 from typing import Any
 
 import structlog
@@ -46,6 +47,12 @@ from ouroboros.mcp.types import (
 
 log = structlog.get_logger(__name__)
 
+_INTERVIEW_SUBAGENT_MAX_CONTEXT_CHARS = 600
+_INTERVIEW_SUBAGENT_MAX_PREVIOUS_TRANSCRIPT_CHARS = 200
+_INTERVIEW_SUBAGENT_MAX_TRANSCRIPT_QUESTION_CHARS = 900
+_INTERVIEW_SUBAGENT_MAX_TRANSCRIPT_ANSWER_CHARS = 220
+_INTERVIEW_SUBAGENT_MAX_ANSWER_CHARS = 300
+
 # ---------------------------------------------------------------------------
 # SubagentPayload dataclass
 # ---------------------------------------------------------------------------
@@ -211,6 +218,123 @@ def should_dispatch_via_plugin(
     return mode == "plugin"
 
 
+def _truncate_tail(text: str | None, max_chars: int) -> str:
+    """Keep prompt inputs bounded while preserving the most recent context."""
+    if not text:
+        return ""
+    if len(text) <= max_chars:
+        return text
+    return "[truncated]\n" + text[-max_chars:]
+
+
+def _truncate_head(text: str | None, max_chars: int) -> str:
+    """Keep prompt inputs bounded while preserving the opening context."""
+    if not text:
+        return ""
+    if len(text) <= max_chars:
+        return text
+    return text[:max_chars] + "\n[truncated]"
+
+
+def _truncate_prompt_line(line: str, max_content_chars: int) -> str:
+    """Bound one formatted transcript line without losing its Q/A label."""
+    marker = ":** "
+    if marker not in line:
+        return line if len(line) <= max_content_chars else line[:max_content_chars] + "..."
+
+    prefix, content = line.split(marker, 1)
+    prefix = f"{prefix}{marker}"
+    if len(content) <= max_content_chars:
+        return line
+    return f"{prefix}{content[:max_content_chars]}... [truncated]"
+
+
+_TRANSCRIPT_Q_MARKER_RE = re.compile(r"(?m)^\*\*Q\d+:\*\* ")
+_TRANSCRIPT_A_MARKER_RE = re.compile(r"(?m)^\*\*A\d+:\*\* ")
+
+
+def _compact_transcript_section(section: str, max_content_chars: int) -> str:
+    """Compact a marked Q/A section while preserving the marker."""
+    lines = section.splitlines()
+    if not lines:
+        return ""
+
+    marker = ":** "
+    first_line = lines[0]
+    if marker not in first_line:
+        return _truncate_tail(section, max_content_chars)
+
+    prefix, first_content = first_line.split(marker, 1)
+    prefix = f"{prefix}{marker}"
+    content_parts = [first_content, *lines[1:]]
+    content = "\n".join(content_parts).rstrip()
+    if len(content) <= max_content_chars:
+        return section
+    return f"{prefix}{content[:max_content_chars]}... [truncated]"
+
+
+def _compact_latest_transcript_round(round_text: str) -> str:
+    """Preserve the latest transcript round as Q/A sections while bounding content."""
+    answer_match = _TRANSCRIPT_A_MARKER_RE.search(round_text)
+    if answer_match is None:
+        return _compact_transcript_section(
+            round_text,
+            _INTERVIEW_SUBAGENT_MAX_TRANSCRIPT_QUESTION_CHARS,
+        )
+
+    question_section = round_text[: answer_match.start()].rstrip()
+    answer_section = round_text[answer_match.start() :].rstrip()
+    compacted_question = _compact_transcript_section(
+        question_section,
+        _INTERVIEW_SUBAGENT_MAX_TRANSCRIPT_QUESTION_CHARS,
+    )
+    compacted_answer = _compact_transcript_section(
+        answer_section,
+        _INTERVIEW_SUBAGENT_MAX_TRANSCRIPT_ANSWER_CHARS,
+    )
+    return f"{compacted_question}\n{compacted_answer}"
+
+
+def _compact_interview_transcript(transcript: str) -> str:
+    """Compact transcript history without splitting the latest Q/A block."""
+    question_matches = list(_TRANSCRIPT_Q_MARKER_RE.finditer(transcript))
+    if not question_matches:
+        return _truncate_tail(transcript, _INTERVIEW_SUBAGENT_MAX_PREVIOUS_TRANSCRIPT_CHARS)
+
+    latest_start = question_matches[-1].start()
+    latest_round = transcript[latest_start:].strip()
+    if not latest_round:
+        return ""
+
+    compacted_latest_round = _compact_latest_transcript_round(latest_round)
+    previous = transcript[:latest_start].strip()
+    if not previous:
+        return compacted_latest_round
+
+    previous_tail = _truncate_tail(
+        previous,
+        _INTERVIEW_SUBAGENT_MAX_PREVIOUS_TRANSCRIPT_CHARS,
+    )
+    return f"{previous_tail}\n\n{compacted_latest_round}"
+
+
+def _load_seed_closer_summary() -> str:
+    """Load the compact Seed Closer guard, tolerating older custom prompt overrides."""
+    from ouroboros.agents.loader import load_agent_section
+
+    try:
+        return load_agent_section("seed-closer", "CLOSURE GATE SUMMARY")
+    except (FileNotFoundError, KeyError):
+        try:
+            return _truncate_tail(load_agent_section("seed-closer", "YOUR APPROACH"), 900)
+        except (FileNotFoundError, KeyError):
+            return (
+                "- Do not treat ambiguity <= 0.2 as sufficient for closure.\n"
+                "- Do not close if unresolved decisions would materially change implementation.\n"
+                "- Ask the highest-impact follow-up question when a material gap remains."
+            )
+
+
 async def emit_subagent_dispatched_event(
     event_store: Any | None,
     *,
@@ -381,10 +505,25 @@ def build_interview_subagent(
     from ouroboros.agents.loader import load_agent_prompt
 
     system_prompt = load_agent_prompt("socratic-interviewer")
+    seed_closer_summary = _load_seed_closer_summary()
 
     transcript_section = ""
     if transcript:
-        transcript_section = f"\n## Conversation History\n{transcript}\n"
+        bounded_transcript = _compact_interview_transcript(transcript)
+        transcript_section = f"\n## Conversation History\n{bounded_transcript}\n"
+
+    bounded_initial_context = _truncate_head(
+        initial_context,
+        _INTERVIEW_SUBAGENT_MAX_CONTEXT_CHARS,
+    )
+    bounded_answer = _truncate_tail(answer, _INTERVIEW_SUBAGENT_MAX_ANSWER_CHARS)
+
+    seed_ready_guard = f"""
+## Seed-ready Guard
+Before declaring ready, apply the canonical Seed Closer closure gate summary.
+Do not treat ambiguity <= 0.2 as sufficient for closure.
+
+{seed_closer_summary}"""
 
     if action == "start" and initial_context:
         prompt = f"""{system_prompt}
@@ -395,9 +534,10 @@ def build_interview_subagent(
 
 Start a Socratic interview to clarify requirements for the following project idea.
 Ask probing questions to reduce ambiguity. Score ambiguity after each exchange.
+{seed_ready_guard}
 
 ## Initial Context
-{initial_context}
+{bounded_initial_context}
 
 ## Session ID
 {session_id}
@@ -413,13 +553,14 @@ Begin the interview. Ask your first clarifying question."""
 
 Continue the Socratic interview. The user has answered your previous question.
 Analyze their answer, update your understanding, score current ambiguity,
-and ask the next clarifying question (or declare ready if ambiguity <= 0.2).
+and ask the next clarifying question or declare ready only after the Seed-ready Guard passes.
+{seed_ready_guard}
 
 ## Session ID
 {session_id}
 {transcript_section}
 ## User's Latest Answer
-{answer}
+{bounded_answer}
 
 Continue the interview."""
 
@@ -433,6 +574,8 @@ Continue the interview."""
 Resume the Socratic interview for session {session_id}.
 Review the conversation history and continue from where we left off.
 {transcript_section}
+{seed_ready_guard}
+
 ## Action: {action}
 
 Continue the interview."""

{ouroboros_ai-0.29.2.dev1 → ouroboros_ai-0.29.2.dev2}/tests/unit/mcp/tools/test_subagent.py

@@ -390,6 +390,17 @@ class TestBuildInterviewSubagent:
         )
         assert "Build a REST API" in p.prompt
 
+    def test_start_prompt_bounds_initial_context_from_head(self) -> None:
+        p = build_interview_subagent(
+            session_id="sess-123",
+            action="start",
+            initial_context="PRIMARY GOAL: Build a REST API. " + ("details " * 1_000),
+        )
+        assert "PRIMARY GOAL: Build a REST API." in p.prompt
+        assert "[truncated]" in p.prompt
+        assert "details " * 200 not in p.prompt
+        assert len(p.prompt) < 5_000
+
     def test_answer_prompt_includes_answer(self) -> None:
         p = build_interview_subagent(
             session_id="sess-123",
@@ -398,6 +409,123 @@ class TestBuildInterviewSubagent:
         )
         assert "Python with FastAPI" in p.prompt
 
+    def test_answer_prompt_requires_seed_ready_guard(self) -> None:
+        p = build_interview_subagent(
+            session_id="sess-123",
+            action="answer",
+            answer="Python with FastAPI",
+        )
+        assert "Do not treat ambiguity <= 0.2 as sufficient for closure" in p.prompt
+        assert "ownership/SSoT" in p.prompt
+        assert "declare ready if ambiguity <= 0.2" not in p.prompt
+
+    def test_answer_prompt_uses_seed_closer_as_guard_ssot(self, monkeypatch) -> None:
+        from ouroboros.agents import loader
+
+        def fake_load_agent_prompt(agent_name: str) -> str:
+            if agent_name == "socratic-interviewer":
+                return "SOCRATIC INTERVIEWER PROMPT"
+            raise FileNotFoundError(agent_name)
+
+        def fake_load_agent_section(agent_name: str, section: str) -> str:
+            if agent_name == "seed-closer" and section == "CLOSURE GATE SUMMARY":
+                return "CANONICAL SEED CLOSER SUMMARY"
+            raise KeyError(section)
+
+        monkeypatch.setattr(loader, "load_agent_prompt", fake_load_agent_prompt)
+        monkeypatch.setattr(loader, "load_agent_section", fake_load_agent_section)
+
+        p = build_interview_subagent(
+            session_id="sess-123",
+            action="answer",
+            answer="Python with FastAPI",
+        )
+
+        assert "SOCRATIC INTERVIEWER PROMPT" in p.prompt
+        assert "CANONICAL SEED CLOSER SUMMARY" in p.prompt
+
+    def test_answer_prompt_bounds_large_transcript_and_answer(self) -> None:
+        p = build_interview_subagent(
+            session_id="sess-123",
+            action="answer",
+            answer="A" * 5_000,
+            transcript="T" * 5_000,
+        )
+
+        assert "[truncated]" in p.prompt
+        assert "A" * 1_000 not in p.prompt
+        assert "T" * 1_000 not in p.prompt
+        assert len(p.prompt) < 5_000
+
+    def test_answer_prompt_preserves_latest_transcript_round(self) -> None:
+        latest_question = "**Q7:** Should subscription control be server-side or client-side?"
+        latest_answer = "**A7:** Server-side should own the final decision."
+        transcript = (
+            f"**Q6:** {'older context ' * 80}\n"
+            f"**A6:** {'older answer ' * 80}\n\n"
+            f"{latest_question}\n{latest_answer}"
+        )
+
+        p = build_interview_subagent(
+            session_id="sess-123",
+            action="answer",
+            answer="Server-side should own the final decision.",
+            transcript=transcript,
+        )
+
+        assert latest_question in p.prompt
+        assert latest_answer in p.prompt
+        assert "older context " * 20 not in p.prompt
+
+    def test_answer_prompt_compacts_multiline_latest_round_by_markers(self) -> None:
+        latest_question = (
+            "**Q7:** Should subscription control be server-side or client-side?\n"
+            "Please decide this before Seed generation."
+        )
+        transcript = (
+            "**Q6:** Previous question\n"
+            "**A6:** Previous answer\n\n"
+            f"{latest_question}\n"
+            f"**A7:** Server-side should own it.\n\n{'code line\\n' * 500}"
+        )
+
+        p = build_interview_subagent(
+            session_id="sess-123",
+            action="answer",
+            answer="Server-side should own it.",
+            transcript=transcript,
+        )
+
+        assert "**Q7:** Should subscription control be server-side or client-side?" in p.prompt
+        assert "Please decide this before Seed generation." in p.prompt
+        assert "**A7:** Server-side should own it." in p.prompt
+        assert "code line\n" * 100 not in p.prompt
+        assert len(p.prompt) < 5_000
+
+    def test_answer_prompt_falls_back_when_seed_closer_summary_missing(self, monkeypatch) -> None:
+        from ouroboros.agents import loader
+
+        def fake_load_agent_prompt(agent_name: str) -> str:
+            if agent_name == "socratic-interviewer":
+                return "SOCRATIC INTERVIEWER PROMPT"
+            raise FileNotFoundError(agent_name)
+
+        def fake_load_agent_section(agent_name: str, section: str) -> str:
+            if agent_name == "seed-closer" and section == "YOUR APPROACH":
+                return "FALLBACK SEED CLOSER APPROACH"
+            raise KeyError(section)
+
+        monkeypatch.setattr(loader, "load_agent_prompt", fake_load_agent_prompt)
+        monkeypatch.setattr(loader, "load_agent_section", fake_load_agent_section)
+
+        p = build_interview_subagent(
+            session_id="sess-123",
+            action="answer",
+            answer="Python with FastAPI",
+        )
+
+        assert "FALLBACK SEED CLOSER APPROACH" in p.prompt
+
     def test_context_preserves_session_id(self) -> None:
         p = build_interview_subagent(
             session_id="sess-123",

ouroboros_ai-0.29.2.dev1/src/ouroboros/agents/seed-closer.md

@@ -1,39 +0,0 @@
-# Seed Closer
-
-You decide when the interview is already clear enough to stop and convert into a Seed instead of asking one more clever question.
-
-## YOUR PHILOSOPHY
-
-"A good interview ends on time. Extra precision after the decision boundary is waste."
-
-You optimize for actionable clarity, not endless refinement.
-
-## YOUR APPROACH
-
-### 1. Check The Decision Boundary
-- Ask whether scope, non-goals, outputs, and verification expectations are already explicit
-- Distinguish true ambiguity from minor wording polish
-- Prefer stopping once the remaining uncertainty would not change execution materially
-
-### 2. Reject Over-Interviewing
-- Notice when new questions only produce stylistic refinement or edge-case bikeshedding
-- Treat repeated restatement as a sign that the interview may already be done
-- Avoid opening new branches when the current information is already seed-worthy
-
-### 3. Ask For Closure Directly
-- Convert late-stage refinement into a closure question
-- Confirm whether the current constraints are sufficient to proceed
-- Move the conversation toward seed generation instead of another exploratory detour
-
-### 4. Preserve Practical Momentum
-- Favor "good enough to execute" over theoretical completeness
-- Accept that some implementation details belong to execution, not interview
-- End the interview once the next useful action is seed generation
-
-## YOUR QUESTIONS
-
-- Is there any ambiguity left that would materially change implementation?
-- Are scope, non-goals, outputs, and verification expectations already clear enough for a Seed?
-- Would another question change execution, or just polish wording?
-- Should we stop the interview here and move to seed generation?
-- What is the smallest remaining clarification needed before we can proceed?