ouroboros-ai 0.43.3.dev5__tar.gz → 0.43.3.dev7__tar.gz

{ouroboros_ai-0.43.3.dev5 → ouroboros_ai-0.43.3.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.43.3.dev5
+Version: 0.43.3.dev7
 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.43.3.dev7/docs/rfc/inverted-interview-intent-preservation.md

@@ -0,0 +1,149 @@
+# RFC: Inverted Interview Intent Preservation
+
+## Status
+
+Draft proposal. Tracking issue: #1504.
+
+## Problem
+
+Some interviews fail not because the user has not stated intent, but because the
+system drifts away from intent the user already stated.
+
+A recurring failure shape:
+
+1. The user states a strong artifact contract, for example `CLI + web app`.
+2. The interview or auto-answer path introduces a safer narrower option, for
+   example `docs-only handoff`.
+3. The pipeline converges on the narrower option because it is conservative and
+   easy to verify.
+4. The output is safe, but wrong: the final artifact class changed without an
+   explicit user decision.
+
+This is different from ordinary ambiguity. The missing behavior is not “ask more
+open-ended questions.” The missing behavior is “reconstruct and preserve the
+user's already-stated contract before asking the next question.”
+
+## Proposal
+
+Add an **inverted interview** mode or guardrail for interviews that begin with
+strong user intent or prior context.
+
+Instead of starting only with open-ended Socratic questions, the interviewer first
+reconstructs the current requirement as explicit, falsifiable assumptions:
+
+- final artifact class;
+- outputs that are products versus outputs that are supporting artifacts;
+- non-goals;
+- locked user facts;
+- unsafe interpretation changes;
+- unresolved decisions that still need human authority.
+
+Then it asks the user to correct mismatches.
+
+Example:
+
+```text
+My current understanding:
+
+1. Final artifact is a CLI plus web app.
+2. Docs-only handoff is not the final artifact.
+3. Checklist files are generated outputs of the CLI/web system, not the product.
+4. Existing legacy workflow behavior must be inherited where relevant.
+5. Missing source data must be represented as insufficient/unchecked, not OK.
+
+Which line is wrong or incomplete?
+```
+
+The user can answer with a small correction instead of restating the whole task.
+The interview repeats this assumption-led loop until no material mismatch
+remains, then continues through the existing Seed readiness and Restate gates.
+
+## Relationship to Socratic interview
+
+This does not replace the existing Socratic interview. It is a front-loaded
+intent-preservation pass for cases where the user has already supplied material
+requirements.
+
+Normal Socratic interview asks:
+
+```text
+What do you want to build?
+```
+
+Inverted interview asks:
+
+```text
+Here is what I think you already asked for. Which part is wrong?
+```
+
+Both are dialectic. The difference is that inverted interview treats prior user
+intent as the first object of examination.
+
+## Contract
+
+When a user-stated artifact class is locked by goal text, preference, or a
+confirmed ledger entry:
+
+- generated answers must not replace it with a narrower artifact class;
+- docs-only, review-only, handoff-only, or checklist-only options must be treated
+  as scope-reduction candidates;
+- scope reductions require an explicit user answer or a blocked state;
+- if a human chooses the narrower artifact, record a warning and require
+  confirmation before Seed generation;
+- supporting artifacts may still be generated, but they must not be represented
+  as the final product unless the user says so.
+
+## Example failure this guards
+
+A user requests a reusable local tool with both CLI and web surfaces. During
+interview, a conservative default chooses a docs-only handoff package. The handoff
+contains useful material, but the final artifact class changed from executable
+software to static documentation.
+
+In inverted mode, the first interview turn should lock:
+
+```yaml
+final_artifact: CLI + web app
+supporting_artifacts:
+  - checklist files
+  - handoff documents
+  - review summaries
+not_final_artifact:
+  - docs-only handoff
+```
+
+A later generated `docs-only handoff` answer conflicts with this contract and must
+be blocked unless the user explicitly changes the contract.
+
+## Implementation slice in this PR
+
+This PR adds a small IntentGuard extension for narrowed-output artifact drift:
+
+- output-contract detection recognizes CLI/web/tool/app artifacts with token-aware matching;
+- generated `docs-only` / `handoff-only` / `checkpack` / `checklist package`
+  answers are treated like existing review-only reductions when they are offered
+  as narrowed alternatives;
+- diagnostics warn when a pending question offers a docs-only narrowing next to a
+  user-locked output contract;
+- supporting artifacts such as checklist packages may remain in the user goal
+  without disabling the goal-derived contract;
+- tests cover CLI/web intent drifting toward docs-only handoff, supporting
+  checklist outputs, and short-term false positives such as `app` in
+  `approach`.
+
+## Non-goals
+
+- No new interview command flag yet.
+- No full assumption-led UI yet.
+- No replacement of the current Socratic interview.
+- No Seed schema change in this slice.
+
+## Future work
+
+Possible follow-ups:
+
+1. `ooo interview --mode inverted` or `ooo auto --interview-mode inverted`.
+2. A first-turn assumption ledger rendered to the user for correction.
+3. A Seed Draft Ledger field for locked artifact class versus supporting outputs.
+4. Auto-activation when the user corrects artifact scope or when generated options
+   offer docs-only/review-only alternatives to a user-locked executable artifact.

{ouroboros_ai-0.43.3.dev5 → ouroboros_ai-0.43.3.dev7}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.43.3.dev5'
-__version_tuple__ = version_tuple = (0, 43, 3, 'dev5')
+__version__ = version = '0.43.3.dev7'
+__version_tuple__ = version_tuple = (0, 43, 3, 'dev7')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.43.3.dev5 → ouroboros_ai-0.43.3.dev7}/src/ouroboros/auto/intent_guard.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
 from enum import StrEnum
+import re
 from typing import Any
 
 from ouroboros.auto.ledger import (
@@ -114,9 +115,62 @@ _ARTIFACT_OUTPUT_TERMS = (
     "html",
     "report",
     "reports",
+    "cli",
+    "command",
+    "commands",
+    "web",
+    "webapp",
+    "web app",
+    "app",
+    "application",
+    "tool",
+    "tools",
 )
 
+_BROAD_ARTIFACT_OUTPUT_TERMS = (
+    "video",
+    "videos",
+    "mp4",
+    "clip",
+    "clips",
+    "short",
+    "shorts",
+    "long-form",
+    "long form",
+    "json",
+    "csv",
+    "pdf",
+    "html",
+    "cli",
+    "command",
+    "commands",
+    "web",
+    "webapp",
+    "web app",
+    "app",
+    "application",
+    "tool",
+    "tools",
+)
+
+_NARROWED_OUTPUT_COMPETING_ARTIFACT_TERMS = tuple(
+    term for term in _BROAD_ARTIFACT_OUTPUT_TERMS if term not in {"json", "csv", "pdf", "html"}
+)
+
+_NARROWED_OUTPUT_CONTEXT_FOLLOWERS = {
+    "audience",
+    "audiences",
+    "group",
+    "groups",
+    "stakeholder",
+    "stakeholders",
+    "team",
+    "teams",
+}
+
 _ARTIFACT_GENERATION_TERMS = (
+    "build",
+    "builds",
     "make",
     "makes",
     "create",
@@ -144,6 +198,44 @@ _REVIEW_ONLY_TERMS = (
     "no export",
 )
 
+_SCOPE_REDUCTION_TERMS = (
+    "docs-only",
+    "docs only",
+    "documentation-only",
+    "documentation only",
+    "document-only",
+    "document only",
+    "handoff-only",
+    "handoff only",
+    "handoff package",
+    "checkpack",
+    "check pack",
+    "checklist-only",
+    "checklist only",
+    "checklist package",
+)
+
+_NARROWED_OUTPUT_EXCLUSION_TERMS = (
+    "not the final artifact",
+    "not final artifact",
+    "not the final output",
+    "not final output",
+    "not the final deliverable",
+    "not final deliverable",
+    "not the deliverable",
+    "not deliverable",
+    "not the artifact",
+    "not artifact",
+    "only generated output",
+    "only generated outputs",
+    "only supporting output",
+    "only supporting outputs",
+    "supporting output",
+    "supporting outputs",
+    "supporting artifact",
+    "supporting artifacts",
+)
+
 _DIAGNOSTIC_MARKERS = (
     "[seed qa repair attempt",
     "[seed qa lateral repair attempt",
@@ -210,7 +302,7 @@ def guard_auto_answer(
             IntentGuardCheck(
                 code="generated_option_conflict",
                 status=IntentGuardStatus.FAIL,
-                message="generated review-only framing conflicts with the user output contract",
+                message="generated narrowed-output framing conflicts with the user output contract",
                 action="discard the generated option and answer from USER_GOAL/USER_PREFERENCE; block if retry still conflicts",
             )
         )
@@ -252,16 +344,17 @@ def guard_interview_turn(
             message="initial interview context contains an artifact-output contract",
         )
     )
-    question_has_generated_choice = _contains_review_only_option(question) or (
+    question_has_generated_choice = _contains_scope_reduction_option(question) or (
         "--mode auto" in question.casefold() and "--mode review" in question.casefold()
     )
-    answer_has_review_only = _contains_review_only_option(answer_text) or (
-        "review" in answer_text.casefold()
-        and not _has_artifact_output_terms(answer_text)
-        and question_has_generated_choice
+    answer_has_review_only = _contains_scope_reduction_option(answer_text) or (
+        "review" in answer_text.casefold() and not _has_artifact_output_terms(answer_text)
     )
+
     if not question_has_generated_choice or not answer_has_review_only:
         return IntentGuardReport(tuple(checks))
+    if _is_explicit_narrowed_output_contract(contract):
+        return IntentGuardReport(tuple(checks))
 
     source = answer_source.strip().casefold()
     if source in _HUMAN_ANSWER_SOURCES:
@@ -269,7 +362,7 @@ def guard_interview_turn(
             IntentGuardCheck(
                 code="user_contract_change",
                 status=IntentGuardStatus.WARN,
-                message="human answer appears to change the initial output contract toward review-only behavior",
+                message="human answer appears to change the initial output contract toward a narrower output class",
                 action="record it, but ask/confirm whether this is an intentional scope change before Seed generation",
             )
         )
@@ -324,12 +417,16 @@ def diagnose_auto_state(
                 message="output contract is anchored in user/repo evidence",
             )
         )
-        if pending_question and _contains_review_only_option(pending_question):
+        if (
+            pending_question
+            and _contains_scope_reduction_option(pending_question)
+            and not _is_explicit_narrowed_output_contract(contract)
+        ):
             checks.append(
                 IntentGuardCheck(
                     code="generated_option_present",
                     status=IntentGuardStatus.WARN,
-                    message="pending question contains a generated review-only option next to a user output contract",
+                    message="pending question contains a generated narrowed-output option next to a user output contract",
                     action="prefer USER_GOAL/USER_PREFERENCE when answering; do not let the generated option win",
                 )
             )
@@ -347,7 +444,7 @@ def diagnose_auto_state(
                     IntentGuardCheck(
                         code="generated_option_conflict",
                         status=IntentGuardStatus.FAIL,
-                        message="recent auto answer appears to have accepted review-only framing over user output intent",
+                        message="recent auto answer appears to have accepted narrowed-output framing over user output intent",
                         action="discard that answer, reopen the round, and re-answer from USER_GOAL/USER_PREFERENCE",
                     )
                 )
@@ -429,35 +526,96 @@ def _generated_review_option_conflicts(
     source = answer_source.strip().casefold()
     if source in {"user_goal", "user_preference", "repo_fact", "existing_convention"}:
         return False
-    question_has_generated_choice = _contains_review_only_option(question) or (
+    question_has_generated_choice = _contains_scope_reduction_option(question) or (
         "--mode auto" in question.casefold() and "--mode review" in question.casefold()
     )
     if not question_has_generated_choice:
         return False
+    if _is_explicit_narrowed_output_contract(contract_text):
+        return False
     answer_lower = answer_text.casefold()
-    if _contains_review_only_option(answer_lower):
+    if _contains_scope_reduction_option(answer_lower):
         return True
     return "review" in answer_lower and not _has_artifact_output_terms(answer_lower)
 
 
-def _contains_review_only_option(text: str) -> bool:
+def _is_explicit_narrowed_output_contract(text: str) -> bool:
+    """Return true when the user contract itself is the narrowed output.
+
+    Scope-reduction phrases are only failures when a generated answer narrows a
+    broader user artifact class. If the user's locked contract is already a
+    docs-only/review-only/checklist-only handoff, a generated answer that
+    repeats that contract should pass instead of being treated as drift. Narrow
+    artifact terms that are explicitly excluded from the final deliverable do
+    not make the user contract a narrowed-output contract.
+    """
+    return (
+        _contains_scope_reduction_option(text)
+        and not _contains_competing_artifact_contract(text)
+        and not _contains_any_phrase(text, _NARROWED_OUTPUT_EXCLUSION_TERMS)
+    )
+
+
+def _contains_competing_artifact_contract(text: str) -> bool:
+    """Return true when text names a competing final artifact class.
+
+    Broad tokens such as ``web`` and ``app`` are also used as audience/context
+    descriptors (``web team``, ``app team``). Those should not prevent an
+    explicitly narrowed user contract (for example, docs-only handoff files for
+    that team) from passing the guard.
+    """
     lowered = text.casefold()
-    return any(term in lowered for term in _REVIEW_ONLY_TERMS)
+    for term in _NARROWED_OUTPUT_COMPETING_ARTIFACT_TERMS:
+        escaped = re.escape(term.casefold())
+        prefix = r"(?<!\w)" if term[:1].isalnum() else ""
+        suffix = r"(?!\w)" if term[-1:].isalnum() else ""
+        for match in re.finditer(f"{prefix}{escaped}{suffix}", lowered):
+            after = lowered[match.end() :]
+            next_word = re.match(r"(?:\s+|-)+(\w+)", after)
+            if next_word and next_word.group(1) in _NARROWED_OUTPUT_CONTEXT_FOLLOWERS:
+                continue
+            return True
+    return False
+
+
+def _contains_review_only_option(text: str) -> bool:
+    return _contains_any_phrase(text, _REVIEW_ONLY_TERMS)
+
+
+def _contains_scope_reduction_option(text: str) -> bool:
+    return _contains_any_phrase(text, (*_REVIEW_ONLY_TERMS, *_SCOPE_REDUCTION_TERMS))
 
 
 def _looks_like_artifact_generation(text: str) -> bool:
-    lowered = text.casefold()
     return (
         bool(text.strip())
-        and any(term in lowered for term in _ARTIFACT_GENERATION_TERMS)
-        and _has_artifact_output_terms(lowered)
-        and not _contains_review_only_option(lowered)
+        and _contains_any_phrase(text, _ARTIFACT_GENERATION_TERMS)
+        and _has_artifact_output_terms(text)
     )
 
 
 def _has_artifact_output_terms(text: str) -> bool:
+    return _contains_any_phrase(text, _ARTIFACT_OUTPUT_TERMS)
+
+
+def _contains_any_phrase(text: str, phrases: Sequence[str]) -> bool:
     lowered = text.casefold()
-    return any(term in lowered for term in _ARTIFACT_OUTPUT_TERMS)
+    return any(_contains_phrase(lowered, phrase.casefold()) for phrase in phrases)
+
+
+def _contains_phrase(lowered_text: str, phrase: str) -> bool:
+    """Return true when ``phrase`` appears as a token/phrase, not a substring.
+
+    IntentGuard uses short artifact terms such as ``app`` and ``web``. Raw
+    substring matching would treat prose like ``approach`` or ``webbing`` as an
+    artifact contract, so alphanumeric phrase edges must align to non-word
+    boundaries. Phrases that start or end with punctuation keep substring
+    semantics for CLI flags such as ``--mode review``.
+    """
+    escaped = re.escape(phrase)
+    prefix = r"(?<!\w)" if phrase[:1].isalnum() else ""
+    suffix = r"(?!\w)" if phrase[-1:].isalnum() else ""
+    return re.search(f"{prefix}{escaped}{suffix}", lowered_text) is not None
 
 
 def _seed_artifact_has_diagnostic_constraints(seed_artifact: Mapping[str, Any]) -> bool:

{ouroboros_ai-0.43.3.dev5 → ouroboros_ai-0.43.3.dev7}/src/ouroboros/auto/pipeline.py

@@ -385,6 +385,11 @@ class AutoPipelineResult:
     partial_product: bool = False
     partial_product_reason: str | None = None
     partial_unresolved_slots: tuple[str, ...] = ()
+    # #1509: final-status surfaces must distinguish orchestration state
+    # from artifact state so BLOCKED/FAILED sessions with generated files are
+    # not mistaken for verified completion. Values are intentionally stringly
+    # typed for stable CLI/MCP wire compatibility.
+    artifact_state: str | None = None
 
 
 @dataclass(slots=True)
@@ -4099,8 +4104,20 @@ class AutoPipeline:
         # (e.g. on a safety blocker) keeps ``partial_product=False`` so the
         # field cannot be misread as "deadline recovery succeeded".
         partial_product = seed_degraded and state.phase == AutoPhase.COMPLETE
+        result_status = status_override or state.phase.value
+        artifact_state = _artifact_state_for_result(
+            status=result_status,
+            phase=state.phase,
+            seed_path=state.seed_path,
+            execution_id=state.execution_id,
+            job_id=state.job_id,
+            run_session_id=state.run_session_id,
+            run_handoff_status=state.run_handoff_status,
+            partial_product=partial_product,
+            product_verified=_has_verified_product_completion(state),
+        )
         return AutoPipelineResult(
-            status=status_override or state.phase.value,
+            status=result_status,
             auto_session_id=state.auto_session_id,
             phase=state.phase.value,
             grade=review.grade_result.grade.value if review else state.last_grade,
@@ -4157,6 +4174,7 @@ class AutoPipeline:
             partial_product=partial_product,
             partial_product_reason=partial_product_reason,
             partial_unresolved_slots=partial_unresolved_slots,
+            artifact_state=artifact_state,
         )
 
     def _checkpoint_final_commit(self, state: AutoPipelineState) -> None:
@@ -4339,6 +4357,61 @@ class AutoPipeline:
             pass
 
 
+def _artifact_state_for_result(
+    *,
+    status: str,
+    phase: AutoPhase,
+    seed_path: str | None,
+    execution_id: str | None,
+    job_id: str | None,
+    run_session_id: str | None,
+    partial_product: bool,
+    run_handoff_status: str | None = None,
+    product_verified: bool = False,
+) -> str:
+    """Classify the generated-artifact outcome separately from orchestration.
+
+    ``status`` remains the authoritative orchestration state. This companion
+    value prevents final renderers from implying completion when a BLOCKED or
+    FAILED run still left useful generated files behind.
+    """
+
+    has_generated_artifact = bool(seed_path or execution_id or job_id or run_session_id)
+    if status in {AutoPhase.BLOCKED.value, AutoPhase.FAILED.value}:
+        return "partial_artifact_generated" if has_generated_artifact else status
+    if status == AutoPhase.COMPLETE.value:
+        if partial_product:
+            return "complete_unverified"
+        if product_verified:
+            return "complete_verified"
+        if run_handoff_status == RUN_HANDOFF_STARTED_STATUS:
+            return "complete_unverified"
+        return "complete_verified"
+    if phase in {AutoPhase.BLOCKED, AutoPhase.FAILED}:
+        return "partial_artifact_generated" if has_generated_artifact else phase.value
+    return "artifact_in_progress" if has_generated_artifact else "not_generated"
+
+
+def _has_verified_product_completion(state: AutoPipelineState) -> bool:
+    """Return True when COMPLETE represents a verified product terminal.
+
+    ``run_handoff_status=started`` can persist after a complete-product run moves
+    through Ralph/EVALUATE success. Treat those terminal success signals as
+    stronger evidence than the stale handoff marker so final surfaces do not
+    downgrade verified product completion to handoff-only completion.
+    """
+
+    if state.phase is not AutoPhase.COMPLETE:
+        return False
+    if state.ralph_job_status == "completed":
+        return True
+    if state.last_qa_passed is True:
+        return True
+    if state.complete_product and state.ralph_stop_reason is not None:
+        return True
+    return state.run_handoff_status == "completed"
+
+
 def _mark_invalid_seed_artifact(state: AutoPipelineState, message: str) -> None:
     state.seed_artifact = {}
     # Keep seed_origin consistent with the now-empty seed_artifact: the

{ouroboros_ai-0.43.3.dev5 → ouroboros_ai-0.43.3.dev7}/src/ouroboros/cli/commands/auto.py

@@ -871,6 +871,8 @@ def _print_result(result: AutoPipelineResult, *, show_ledger: bool) -> None:
     console.print(f"Auto session: [cyan]{result.auto_session_id}[/]")
     displayed_status = "run_handoff_started" if handoff_only else result.status
     console.print(f"Status: [bold]{displayed_status}[/]")
+    if result.artifact_state:
+        console.print(f"Artifact state: [bold]{result.artifact_state}[/]")
     if handoff_only:
         console.print(
             "Product status: [yellow]not verified complete; execution is still external/pending[/]"

{ouroboros_ai-0.43.3.dev5 → ouroboros_ai-0.43.3.dev7}/src/ouroboros/mcp/tools/auto_handler.py

@@ -1376,6 +1376,8 @@ def _result_meta(result: AutoPipelineResult) -> dict[str, Any]:
         "job_id": result.job_id,
         "run_session_id": result.run_session_id,
     }
+    if result.artifact_state is not None:
+        meta["artifact_state"] = result.artifact_state
     if handoff_only:
         meta["presentation_status"] = _presentation_status(result)
         meta["product_status"] = "not_verified_complete"
@@ -2171,6 +2173,8 @@ def _format_result(result: AutoPipelineResult) -> str:
         f"Status: {_presentation_status(result)}",
         f"Phase: {result.phase}",
     ]
+    if result.artifact_state:
+        lines.append(f"Artifact state: {result.artifact_state}")
     if handoff_only:
         lines.append("Product status: not verified complete; execution is still external/pending")
     elif result.status == "detached":

{ouroboros_ai-0.43.3.dev5 → ouroboros_ai-0.43.3.dev7}/tests/integration/auto/test_status_unified.py

@@ -640,7 +640,7 @@ def test_cli_status_auto_snapshot(tmp_path) -> None:
         "  current_generation: 3\n"
         "  stop_reason: qa passed\n"
         "IntentGuard: pass\n"
-        "  PASS intent_contract_not_applicable: goal does not look like an artifact-output request\n"
+        "  PASS intent_lock_present: output contract is anchored in user/repo evidence\n"
         "  PASS spec_pollution: Seed constraints do not contain known diagnostic markers\n"
     )
     assert rendered == expected