ouroboros-ai 0.43.3.dev6__tar.gz → 0.43.3.dev8__tar.gz

{ouroboros_ai-0.43.3.dev6 → ouroboros_ai-0.43.3.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.43.3.dev6
+Version: 0.43.3.dev8
 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.dev8/docs/rfc/context-first-inverted-interview.md

@@ -0,0 +1,176 @@
+# RFC: Context-First Inverted Interview
+
+## Status
+
+Draft proposal.
+
+## Problem
+
+Some Seed interviews are hard for the wrong reason.
+
+The user is not starting from a blank slate. They may have already supplied:
+
+- a long prior discussion;
+- raw files;
+- recordings or transcripts;
+- handoff notes;
+- failed previous Seeds;
+- generated artifacts that are useful as leads but not trustworthy;
+- domain constraints that have already been corrected multiple times.
+
+In those cases, a normal open-ended interview can create three failures:
+
+1. **Context loss** — the system asks for requirements that are already present
+   in the pre-work.
+2. **Fast shallow convergence** — the interview reaches `seed_ready` with a safe
+   but under-scoped interpretation.
+3. **User fatigue** — the user has to restate the same intent instead of only
+   correcting the system's current understanding.
+
+This is different from an underspecified new idea. The missing behavior is not
+"ask more questions." The missing behavior is "synthesize the existing context
+first, then ask the user to correct the synthesis."
+
+## Proposal
+
+Add a **context-first inverted interview** mode before Seed generation.
+
+Instead of beginning with broad questions, the interviewer first performs a
+pre-work synthesis pass:
+
+1. inspect supplied context and raw artifacts;
+2. reconstruct the current requirement model;
+3. separate confirmed facts, inferred assumptions, unresolved ambiguities, and
+   human-only decisions;
+4. present that model back as short falsifiable statements;
+5. ask the user to correct only the wrong or incomplete lines;
+6. repeat until material ambiguity is gone;
+7. then proceed to normal Seed generation and review.
+
+## Example interaction
+
+```text
+Interviewer:
+
+Based on the prior context and files, my current understanding is:
+
+1. The final product is a reusable CLI plus a local web surface.
+2. Static handoff docs are supporting outputs, not the product.
+3. The legacy workflow should be treated as a reference source, not discarded.
+4. New reviewer checks should be added only as candidate alerts, not final
+   judgments.
+5. Missing required input data must become `insufficient_data` / `unchecked`, not
+   `OK`.
+
+Which line is wrong or incomplete?
+```
+
+The user can answer:
+
+```text
+Line 4 is right, but add that reviewer checks must include the items from the
+recording. Line 1 must say CLI is the batch/reproducibility surface and web is the
+human review surface.
+```
+
+The next turn updates the requirement model instead of starting over.
+
+## Output model
+
+The pre-work synthesis should produce an auditable ledger before the Seed:
+
+```yaml
+confirmed_facts:
+  - value: "Final product includes CLI and web surface"
+    source: user_prior_context
+
+inferred_assumptions:
+  - value: "Static handoff documents are generated outputs"
+    source: prework_synthesis
+    confidence: 0.8
+
+unresolved_ambiguities:
+  - question: "Which reviewer checks are mandatory for MVP?"
+    reason: "Named in prior discussion but not mapped to acceptance criteria"
+
+human_only_decisions:
+  - question: "May the system change the final artifact class?"
+    reason: "Changes product scope and must not be defaulted"
+```
+
+## Relationship to existing Socratic interview
+
+This does not replace the Socratic interview.
+
+Normal Socratic interview is best when the user has a vague goal and needs the
+system to expose hidden assumptions.
+
+Context-first inverted interview is best when there is already substantial
+pre-work and the risk is losing it.
+
+The two modes can compose:
+
+```text
+prework synthesis -> inverted correction loop -> Socratic follow-up for only the
+remaining ambiguities -> Seed
+```
+
+## Activation candidates
+
+The mode may be explicit:
+
+```bash
+ooo interview --mode inverted
+ooo auto --interview-mode inverted
+```
+
+It may also be suggested when signals appear:
+
+- the prompt references prior discussion, recordings, raw files, or pre-work;
+- the user says the interview is too hard or keeps losing context;
+- previous auto/Seed attempts produced a safe but wrong artifact class;
+- the user corrects the same scope assumption more than once;
+- the driver detects many raw artifacts but few confirmed ledger entries.
+
+## Contract
+
+When inverted mode is active:
+
+- the system should not ask broad blank-slate questions until it has presented a
+  pre-work synthesis;
+- each synthesized statement must be source-tagged as confirmed, inferred,
+  ambiguous, or human-only;
+- inferred assumptions must be falsifiable and easy for the user to correct;
+- user corrections outrank generated synthesis;
+- Seed generation must not proceed while a human-only decision is unresolved;
+- generated safe defaults may fill local reversible gaps, but must not replace
+  a user-stated artifact class or domain constraint.
+
+## Non-goals
+
+- This RFC does not require a new Seed schema immediately.
+- This RFC does not remove current interview behavior.
+- This RFC does not require full raw-file analysis in the first implementation
+  slice.
+- This RFC does not make generated synthesis authoritative without user review.
+
+## Initial implementation slices
+
+Small follow-up PRs could land independently:
+
+1. Add a pre-work synthesis ledger type.
+2. Add an `--interview-mode inverted` flag that prints the synthesized ledger
+   before the first question.
+3. Add a diagnostic that detects high-context prompts with no synthesis pass.
+4. Add regression tests for safe-but-wrong Seed outputs after rich pre-work.
+5. Add examples showing context-first inverted interview transcripts.
+
+## Acceptance criteria
+
+- A high-context prompt can produce an assumption-led first interview turn.
+- Confirmed user facts, inferred assumptions, ambiguities, and human-only
+  decisions are distinguishable in output.
+- The user can correct a numbered line without restating the whole requirement.
+- Seed generation waits for unresolved human-only decisions.
+- Tests cover a case where pre-work contains the intended final artifact, but a
+  blank-slate interview would otherwise converge to a narrower safe output.

ouroboros_ai-0.43.3.dev8/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.dev6 → ouroboros_ai-0.43.3.dev8}/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.dev6'
-__version_tuple__ = version_tuple = (0, 43, 3, 'dev6')
+__version__ = version = '0.43.3.dev8'
+__version_tuple__ = version_tuple = (0, 43, 3, 'dev8')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.43.3.dev6 → ouroboros_ai-0.43.3.dev8}/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.dev6 → ouroboros_ai-0.43.3.dev8}/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