ouroboros-ai 0.40.2.dev8__tar.gz → 0.40.2.dev10__tar.gz

{ouroboros_ai-0.40.2.dev8 → ouroboros_ai-0.40.2.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.40.2.dev8
+Version: 0.40.2.dev10
 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.40.2.dev8 → ouroboros_ai-0.40.2.dev10}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.40.2.dev8'
-__version_tuple__ = version_tuple = (0, 40, 2, 'dev8')
+__version__ = version = '0.40.2.dev10'
+__version_tuple__ = version_tuple = (0, 40, 2, 'dev10')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.40.2.dev8 → ouroboros_ai-0.40.2.dev10}/src/ouroboros/auto/adapters.py

@@ -788,6 +788,65 @@ class HandlerEvaluator:
         )
 
 
+class HandlerSeedQAEvaluator:
+    """Callable Seed QA evaluator backed by ``ouroboros_qa``."""
+
+    def __init__(self, qa_handler: QAHandler) -> None:
+        self.qa_handler = qa_handler
+
+    async def __call__(self, seed: Seed, ledger: Any) -> EvaluateResult:
+        seed_yaml = yaml.dump(
+            seed.to_dict(), default_flow_style=False, allow_unicode=True, sort_keys=False
+        )
+        ledger_reference = yaml.dump(
+            ledger.to_dict() if hasattr(ledger, "to_dict") else ledger,
+            default_flow_style=False,
+            allow_unicode=True,
+            sort_keys=False,
+        )
+        quality_bar = (
+            "The Seed must be ready for autonomous execution before run starts. "
+            "It must preserve the interview/ledger intent, have ambiguity_score <= 0.20, "
+            "contain concrete acceptance criteria, include constraints/non-goals/runtime "
+            "context, and avoid unsupported assumptions or missing requirements."
+        )
+        result = await self.qa_handler.handle(
+            {
+                "artifact": seed_yaml,
+                "artifact_type": "document",
+                "quality_bar": quality_bar,
+                "reference": ledger_reference,
+                "seed_content": seed_yaml,
+                "pass_threshold": 0.80,
+            }
+        )
+        if result.is_err:
+            return EvaluateResult(
+                passed=False,
+                score=0.0,
+                verdict="fail",
+                error=str(result.error),
+            )
+        meta = result.value.meta or {}
+        if str(meta.get("status", "")) == "delegated_to_subagent":
+            return EvaluateResult(
+                passed=False,
+                score=0.0,
+                verdict="fail",
+                error=(
+                    "QAHandler returned a plugin-delegation envelope; the auto pipeline "
+                    "cannot grade Seed QA via out-of-band subagent dispatch"
+                ),
+            )
+        return EvaluateResult(
+            passed=bool(meta.get("passed", False)),
+            score=float(meta.get("score", 0.0)),
+            verdict=str(meta.get("verdict", "fail")),
+            differences=tuple(meta.get("differences", ()) or ()),
+            suggestions=tuple(meta.get("suggestions", ()) or ()),
+        )
+
+
 @dataclass(frozen=True, slots=True)
 class LateralResult:
     """Structured result returned by :class:`HandlerLateralThinker`.

{ouroboros_ai-0.40.2.dev8 → ouroboros_ai-0.40.2.dev10}/src/ouroboros/auto/interview_driver.py

@@ -166,6 +166,20 @@ def _lateral_response_authorizes_demotion(text: str | None) -> bool:
     return bool(_LATERAL_CLEARANCE_MARKER_RE.search(text))
 
 
+def _backend_confirmed_seed_ready(turn: InterviewTurn) -> bool:
+    """Return True when the backend closed the interview within the ambiguity gate.
+
+    Backends that do not yet report ``ambiguity_score`` remain compatible:
+    ``seed_ready`` / ``completed`` without a score is accepted as a backend
+    confirmation.
+    """
+    if not (turn.seed_ready or turn.completed):
+        return False
+    if turn.ambiguity_score is None:
+        return True
+    return float(turn.ambiguity_score) <= BACKEND_READY_AMBIGUITY_THRESHOLD
+
+
 # Structural alias for the production lateral-thinker callable. Mirrors the
 # alias declared on ``ouroboros.auto.pipeline``; duplicated locally because
 # ``adapters.LateralResult`` cannot be imported at module load time without
@@ -183,10 +197,10 @@ class InterviewTurn:
     session_id: str
     seed_ready: bool = False
     completed: bool = False
-    # Optional diagnostic surface — backend's own ambiguity reading for the
-    # current turn. The driver never gates on this; it is only used to build
-    # informative blocker messages when the mutual-agreement closure gate
-    # exhausts its budget without both parties converging.
+    # Optional backend ambiguity reading for the current turn. When present,
+    # the driver uses it for the low-ambiguity backend closure gate and for
+    # blocker/status messages; when absent, legacy ``seed_ready`` /
+    # ``completed`` confirmations remain accepted.
     ambiguity_score: float | None = None
 
 
@@ -617,37 +631,22 @@ class AutoInterviewDriver:
                 "blocked", state.interview_session_id, ledger, state.current_round, blocker
             )
 
-        # Closure gate (ledger-primary, backend-advisory per SSOT #1157
-        # *Closure Policy* section, 2026-05-27): an interview closes the
-        # moment ``ledger.is_seed_ready()`` returns True, regardless of
-        # backend ``seed_ready`` state. Backend signals remain useful as
-        # advisory metadata but no longer gate closure on their own.
-        # Disagreement is reframed as the next answer instead of a terminal
-        # block:
+        # Closure gate: the ledger must be structurally complete and the
+        # backend must acknowledge Seed readiness at or below the ambiguity
+        # threshold. Disagreement is reframed as the next answer until the
+        # bounded interview budget is exhausted:
         #
         # * backend signals completion but the ledger has open gaps → answer
         #   the first open gap so the backend re-scores against substantive
         #   new content; the loop refuses backend-only closure (the
         #   premature-closure invariant preserved below).
-        # * backend keeps asking but the ledger is structurally full → close
-        #   immediately as ``ledger_only``; do NOT let the backend extend the
-        #   dialogue past structural completeness, because an LLM evaluator
-        #   never saturates and waiting for its agreement stalls indefinitely
-        #   (the #1170 R2-diag failure mode).
+        # * backend keeps asking, or reports completion with ambiguity > 0.20,
+        #   while the ledger is structurally full → keep answering until the
+        #   backend score converges or max_rounds blocks the session.
         #
-        # ``max_rounds`` is the budget for ledger-filling rounds. The interview
-        # closes the moment ``ledger.is_seed_ready()`` returns True
-        # (ledger-primary closure policy per SSOT #1157 "Closure Policy"
-        # section, formalized 2026-05-27 after #1170 R2-diag confirmed the
-        # legacy AND-gate stalls the simplest canonical case). Backend
-        # ``seed_ready`` / ``completed`` / ``ambiguity_score`` is recorded as
-        # advisory signal on ``state.interview_closure_mode`` but no longer
-        # gates closure — an LLM evaluator never saturates, so requiring its
-        # agreement makes every populated ledger wait indefinitely for an
-        # acknowledgement that never comes. PR-B1 (#1148) shipped a
-        # ``ledger_only`` escape hatch at ``max_rounds`` but kept the AND-gate
-        # as the primary path; this PR promotes ``ledger_only`` to the
-        # primary in-loop closure mode (see SSOT freshness sync 2026-05-27).
+        # ``max_rounds`` is the budget for ledger-filling and backend
+        # convergence rounds. This intentionally prevents a high-ambiguity
+        # backend result from moving directly into Seed generation.
         #
         # Premature-closure invariant preserved below: when the backend
         # reports ``seed_ready`` / ``completed`` but the ledger has open
@@ -655,23 +654,10 @@ class AutoInterviewDriver:
         # the next answer toward filling the next detected gap.
         for round_number in range(state.current_round + 1, self.max_rounds + 1):
             backend_done = turn.seed_ready or turn.completed
+            backend_confirmed = _backend_confirmed_seed_ready(turn)
             ledger_done = ledger.is_seed_ready()
-            if ledger_done:
-                closure_mode = "mutual_agreement" if backend_done else "ledger_only"
-                # Observability parity with the previous max_rounds-only
-                # ledger_only path: emit the same ``auto.interview.ledger_only_closure``
-                # event so existing log-grep consumers and #1170 R2 evidence
-                # captures continue to work. ``mutual_agreement`` is not given
-                # a dedicated event because it was not previously emitted in
-                # the in-loop close path.
-                if not backend_done:
-                    log.info(
-                        "auto.interview.ledger_only_closure",
-                        auto_session_id=state.auto_session_id,
-                        round_number=round_number,
-                        ambiguity_score=turn.ambiguity_score,
-                        interview_session_id=state.interview_session_id,
-                    )
+            if ledger_done and backend_confirmed:
+                closure_mode = "mutual_agreement"
                 state.pending_question = None
                 state.interview_completed = True
                 state.interview_closure_mode = closure_mode
@@ -851,7 +837,7 @@ class AutoInterviewDriver:
                     round_number=round_number + 1,
                 )
 
-        # max_rounds exhausted — one final ledger-primary closure check, then
+        # max_rounds exhausted — one final backend-confirmed closure check, then
         # safe-default finalization for autonomous ``ooo auto``.  The manual
         # ``ooo interview`` path remains strict/fail-closed in its own driver;
         # this auto driver is allowed to close missing/weak required sections
@@ -860,21 +846,13 @@ class AutoInterviewDriver:
         # interview loop: explicit/backend-provided answers always win first,
         # and defaults are only the final escape from a benign stalled dialog.
         #
-        # The final ledger-primary check catches the case where the last
-        # round's apply / backend exchange filled the ledger after the
-        # top-of-loop ledger check fired False for round ``max_rounds``.
+        # The final check catches the case where the last round's apply /
+        # backend exchange both filled the ledger and lowered ambiguity.
         backend_done = turn.seed_ready or turn.completed
+        backend_confirmed = _backend_confirmed_seed_ready(turn)
         ledger_done = ledger.is_seed_ready()
-        if ledger_done:
-            closure_mode = "mutual_agreement" if backend_done else "ledger_only"
-            if not backend_done:
-                log.info(
-                    "auto.interview.ledger_only_closure",
-                    auto_session_id=state.auto_session_id,
-                    round_number=self.max_rounds,
-                    ambiguity_score=turn.ambiguity_score,
-                    interview_session_id=state.interview_session_id,
-                )
+        if ledger_done and backend_confirmed:
+            closure_mode = "mutual_agreement"
             state.pending_question = None
             state.interview_completed = True
             state.interview_closure_mode = closure_mode
@@ -992,11 +970,18 @@ class AutoInterviewDriver:
                     )
                 state.interview_session_id = synthesis_turn.session_id
                 state.pending_question = synthesis_turn.question
-                if not (synthesis_turn.seed_ready or synthesis_turn.completed):
+                if not _backend_confirmed_seed_ready(synthesis_turn):
                     _revert_safe_default_entries(ledger, finalization.defaulted_sections)
+                    ambiguity_part = (
+                        f"ambiguity_score={synthesis_turn.ambiguity_score:.2f}"
+                        if synthesis_turn.ambiguity_score is not None
+                        else "ambiguity_score=unknown"
+                    )
                     blocker = (
-                        "safe-default synthesis did not close the persisted interview: "
-                        "backend_done=False, ledger defaults rolled back"
+                        "safe-default synthesis did not close the persisted interview "
+                        "within the backend ambiguity gate: "
+                        f"backend_done={bool(synthesis_turn.seed_ready or synthesis_turn.completed)}, "
+                        f"{ambiguity_part}, ledger defaults rolled back"
                     )
                     log.warning(
                         "auto.interview.safe_default_synthesis_nonclosure",
@@ -1005,6 +990,7 @@ class AutoInterviewDriver:
                         defaulted_sections=finalization.defaulted_sections,
                         backend_seed_ready=bool(synthesis_turn.seed_ready),
                         backend_completed=bool(synthesis_turn.completed),
+                        backend_ambiguity=synthesis_turn.ambiguity_score,
                         synthesis_pushed=synthesis_pushed,
                     )
                     state.ledger = ledger.to_dict()
@@ -1047,13 +1033,8 @@ class AutoInterviewDriver:
             ambiguity_part = "ambiguity_score=unknown"
         open_gaps = ledger.open_gaps()
         gaps_part = f"open_gaps={open_gaps}" if open_gaps else "open_gaps=[]"
-        # NOTE: PR-B1 (#1148) previously placed a ``ledger_only`` fallback
-        # here for the ``ledger_done and not backend_done`` case at
-        # max_rounds. That fallback is now unreachable — the ledger-primary
-        # check at the top of this max_rounds block (and at the top of each
-        # in-loop iteration) closes any ``ledger_done`` case before we get
-        # here, regardless of backend state. See SSOT #1157 "Closure Policy"
-        # section (formalized 2026-05-27) for the design rationale.
+        # A complete ledger without a low-ambiguity backend close lands here
+        # and blocks instead of forcing Seed generation from stale ambiguity.
         # PR-B2 / #821: partial safe-default closure — some required gaps were
         # safely defaultable, but at least one remained unsafe at max_rounds.
         # Distinguish from the generic "nothing was defaultable" path with a
@@ -1107,13 +1088,12 @@ class AutoInterviewDriver:
                 "blocked", state.interview_session_id, ledger, self.max_rounds, blocker
             )
 
-        # Defensive last resort: ledger is not done, safe-default could not
-        # close, no unsafe-gap partial-rollback fired. Under the ledger-primary
-        # policy this means every required section was probed and the
-        # ``finalize_safe_defaultable_gaps`` policy found nothing safe to fill.
+        # Defensive last resort: the interview did not reach a low-ambiguity
+        # backend-confirmed close, safe-default could not close, and no
+        # unsafe-gap partial-rollback fired.
         # Surface as a typed BLOCKED so callers can resume / sharpen the goal.
-        # ``ledger_done`` is guaranteed False here (otherwise the top
-        # max_rounds check above would have returned ``seed_ready``).
+        # ``ledger_done`` may be true here; that means backend ambiguity never
+        # fell below the closure threshold.
         blocker = (
             f"auto interview reached max_rounds={self.max_rounds} without closure: "
             f"backend_done={backend_done} ({ambiguity_part}), "
@@ -1585,11 +1565,18 @@ class AutoInterviewDriver:
                 )
             state.interview_session_id = synthesis_turn.session_id
             state.pending_question = synthesis_turn.question
-            if not (synthesis_turn.seed_ready or synthesis_turn.completed):
+            if not _backend_confirmed_seed_ready(synthesis_turn):
                 _revert_safe_default_entries(ledger, finalization.defaulted_sections)
+                ambiguity_part = (
+                    f"ambiguity_score={synthesis_turn.ambiguity_score:.2f}"
+                    if synthesis_turn.ambiguity_score is not None
+                    else "ambiguity_score=unknown"
+                )
                 blocker = (
-                    "backend-ready safe-default synthesis did not close the persisted interview: "
-                    "ledger defaults rolled back"
+                    "backend-ready safe-default synthesis did not close the persisted interview "
+                    "within the backend ambiguity gate: "
+                    f"backend_done={bool(synthesis_turn.seed_ready or synthesis_turn.completed)}, "
+                    f"{ambiguity_part}, ledger defaults rolled back"
                 )
                 state.ledger = ledger.to_dict()
                 state.mark_blocked(

{ouroboros_ai-0.40.2.dev8 → ouroboros_ai-0.40.2.dev10}/src/ouroboros/auto/ledger_seed.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import re
+from typing import Any
 from uuid import uuid4
 
 from ouroboros.auto.grading import deterministic_floor
@@ -33,6 +34,18 @@ grade/run gates that suppress high-ambiguity-only blockers for degraded seeds
 (#1257 PR-C).
 """
 
+DEADLINE_LEDGER_SEED_GENERATION_MODE = "interview_deadline_complete_ledger"
+"""``SeedMetadata.generation_mode`` for a *complete* ledger that reached closure
+via the interview-phase deadline recovery path (#1302).
+
+Distinct from :data:`PARTIAL_SEED_GENERATION_MODE`: the ledger is fully resolved
+(no ``unresolved_slots``), but the per-phase interview deadline cut the Socratic
+loop short before the backend could confirm low ambiguity (``<= 0.20``). The
+Seed therefore carries the full ledger content yet is flagged ``degraded`` so
+the grade/run gates surface it as a typed partial-product terminal instead of
+auto-running a Seed whose low ambiguity was never backend-confirmed.
+"""
+
 _PARTIAL_DEFAULT_ACCEPTANCE = (
     "Synthesized Seed runs without raising and the recorded goal is "
     "surfaced in execution output (conservative smoke).",
@@ -55,6 +68,7 @@ def synthesize_seed_from_ledger(
     ledger: SeedDraftLedger,
     *,
     interview_id: str | None = None,
+    recovery_reason: str | None = None,
 ) -> Seed:
     """Build a valid Seed directly from a complete auto ledger.
 
@@ -62,6 +76,18 @@ def synthesize_seed_from_ledger(
     unavailable after the deterministic ledger has enough evidence to proceed.
     The ledger remains the source of truth; this function performs no model or
     external IO.
+
+    Args:
+        ledger: The complete ledger to synthesize from.
+        interview_id: Reference to the source interview, mirrored on
+            :attr:`~ouroboros.core.seed.SeedMetadata.interview_id`.
+        recovery_reason: When set (e.g. ``"interview_phase_deadline"``), the
+            ledger is complete but closure was reached via a recovery path that
+            never obtained backend-confirmed low ambiguity (#1302). The Seed
+            keeps its full ledger content but is stamped ``degraded`` with
+            :data:`DEADLINE_LEDGER_SEED_GENERATION_MODE` so the grade/run gates
+            route it to the typed partial-product terminal instead of auto-RUN.
+            ``None`` (default) yields the legacy fully-runnable ``"normal"`` Seed.
     """
     if not ledger.is_seed_ready():
         msg = f"cannot synthesize Seed from incomplete ledger: {', '.join(ledger.open_gaps())}"
@@ -132,13 +158,35 @@ def synthesize_seed_from_ledger(
             ),
         ),
         metadata=SeedMetadata(
-            seed_id=f"seed_{uuid4().hex[:12]}",
-            ambiguity_score=max(0.05, deterministic_floor(ledger)),
-            interview_id=interview_id,
+            **_synthesized_metadata_kwargs(ledger, interview_id, recovery_reason)
         ),
     )
 
 
+def _synthesized_metadata_kwargs(
+    ledger: SeedDraftLedger,
+    interview_id: str | None,
+    recovery_reason: str | None,
+) -> dict[str, Any]:
+    """Build the ``SeedMetadata`` kwargs for :func:`synthesize_seed_from_ledger`.
+
+    A plain ``recovery_reason is None`` keeps the legacy ``"normal"`` provenance.
+    When a recovery reason is supplied the complete-ledger Seed is flagged
+    ``degraded`` (with no ``unresolved_slots`` — the ledger is fully resolved)
+    so the deadline-recovery contract (#1302) routes it away from auto-RUN.
+    """
+    kwargs: dict[str, Any] = {
+        "seed_id": f"seed_{uuid4().hex[:12]}",
+        "ambiguity_score": max(0.05, deterministic_floor(ledger)),
+        "interview_id": interview_id,
+    }
+    if recovery_reason is not None:
+        kwargs["generation_mode"] = DEADLINE_LEDGER_SEED_GENERATION_MODE
+        kwargs["degraded"] = True
+        kwargs["recovery_reason"] = recovery_reason
+    return kwargs
+
+
 def partial_seed_from_evidence(
     ledger: SeedDraftLedger,
     *,