ouroboros-ai 0.3.0__tar.gz → 0.4.0__tar.gz

ouroboros_ai-0.4.0/HANDOFF.md

@@ -0,0 +1,111 @@
+# Handoff Document
+
+> Last Updated: 2026-02-03
+> Session: Ontological Framework Implementation - Phase 6 Complete
+
+---
+
+## Goal
+
+Ouroboros v0.4.0에 **Ontological Framework** 추가:
+1. **AOP 기반 분석 프레임워크** - 횡단 관심사를 모듈화하여 재사용 가능한 분석 전략 구현
+2. **Deliberative Consensus** - Advocate/Devil/Judge 역할 기반 2라운드 토론 시스템
+3. **Devil's Advocate Strategy** - 온톨로지 질문으로 "근본 해결책인가?" 검증
+
+---
+
+## Current Progress
+
+### ✅ Phase 6: Quality Review - COMPLETE
+
+**Code Review 이슈 수정 완료:**
+
+| 이슈 | 위치 | 해결 |
+|------|------|------|
+| Exception Handling (ProviderError 중복 래핑) | `consensus.py:731-737` | try/except 제거 - Strategy가 내부에서 에러 처리 |
+| Unused import | `consensus.py:26` | `build_devil_advocate_prompt` 제거 |
+| Import ordering | 3개 파일 | `ruff --fix`로 자동 정렬 |
+| Missing `__all__` | `ontology_aspect.py` | 이미 존재 (line 443-454) |
+
+**테스트 결과:** 73개 테스트 통과 (consensus + ontology 관련)
+
+### ✅ 완료된 구현
+
+| 파일 | 설명 | 테스트 |
+|------|------|--------|
+| `src/ouroboros/core/ontology_questions.py` | 온톨로지 질문 정의 | ✅ |
+| `src/ouroboros/core/ontology_aspect.py` | AOP 분석 프레임워크 | ✅ |
+| `src/ouroboros/evaluation/models.py` | VoterRole, FinalVerdict, DeliberationResult | ✅ |
+| `src/ouroboros/evaluation/consensus.py` | DeliberativeConsensus 클래스 | ✅ |
+| `src/ouroboros/strategies/devil_advocate.py` | DevilAdvocateStrategy | ✅ |
+| `tests/unit/evaluation/test_consensus.py` | Deliberative 테스트 | ✅ |
+| `tests/unit/core/test_ontology_aspect.py` | AOP 테스트 | ✅ |
+| `tests/unit/core/test_ontology_questions.py` | 온톨로지 질문 테스트 | ✅ |
+
+---
+
+## Next Steps
+
+### Phase 7: Summary
+
+1. **전체 테스트 실행**
+   ```bash
+   uv run pytest tests/unit/evaluation/ tests/unit/core/ -v
+   ```
+
+2. **변경 사항 커밋** (선택적)
+   ```bash
+   git add -p  # 변경 검토
+   git commit -m "feat(evaluation): add deliberative consensus with AOP-based devil's advocate"
+   ```
+
+### 대기 중 (낮은 우선순위)
+
+| 파일 | 설명 |
+|------|------|
+| `src/ouroboros/bigbang/ontology.py` | Interview Phase 통합 |
+| `src/ouroboros/bigbang/ambiguity.py` | Ontology Score 가중치 추가 |
+
+---
+
+## Important Files
+
+### 핵심 구현
+```
+src/ouroboros/core/ontology_questions.py    # 온톨로지 질문 정의
+src/ouroboros/core/ontology_aspect.py       # AOP 프레임워크 (BaseAnalyzer, AnalysisResult)
+src/ouroboros/evaluation/consensus.py       # DeliberativeConsensus (lines 500-830)
+src/ouroboros/strategies/devil_advocate.py  # Strategy 패턴 구현
+```
+
+### 테스트
+```
+tests/unit/evaluation/test_consensus.py     # 32개 테스트
+tests/unit/core/test_ontology_aspect.py     # 18개 테스트
+tests/unit/core/test_ontology_questions.py  # 23개 테스트
+```
+
+---
+
+## Notes
+
+### 아키텍처 결정
+
+1. **Devil's Advocate는 Strategy 객체**: LLM 호출 대신 `DevilAdvocateStrategy.analyze()` 사용
+2. **Strategy가 에러 처리**: `analyze()` 메서드가 LLM 에러를 내부에서 처리하여 `AnalysisResult.invalid()` 반환
+3. **AnalysisResult.is_valid**: `True` = 근본 해결책, `False` = 증상 치료
+
+### 검증 명령어
+
+```bash
+# 테스트
+uv run pytest tests/unit/evaluation/test_consensus.py -v
+uv run pytest tests/unit/core/ -v
+
+# 린트
+uv run ruff check src/ouroboros/evaluation/ src/ouroboros/core/ src/ouroboros/strategies/
+```
+
+---
+
+*Phase 6 완료. Phase 7 (Summary)로 진행 가능.*

{ouroboros_ai-0.3.0 → ouroboros_ai-0.4.0}/PKG-INFO

@@ -1,14 +1,16 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.3.0
+Version: 0.4.0
 Summary: Self-Improving AI Workflow System
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE
 Requires-Python: >=3.14
 Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: cachetools>=5.0.0
 Requires-Dist: claude-agent-sdk>=0.1.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: litellm>=1.80.0
+Requires-Dist: mcp>=1.26.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: rich>=13.0.0
@@ -60,7 +62,7 @@ Description-Content-Type: text/markdown
 <br/>
 
 <p align="center">
-  <code>75 modules</code> · <code>1,341 tests</code> · <code>97%+ coverage</code> · <code>v0.2.x</code>
+  <code>75 modules</code> · <code>1,341 tests</code> · <code>97%+ coverage</code>
 </p>
 
 <br/>
@@ -244,7 +246,7 @@ These iterate until a **Seed** crystallizes—a specification with `Ambiguity
 ┃      └────┬────┘                                                               ┃
 ┃           │      Stage 1: Mechanical ($0) — lint, build, test                  ┃
 ┃           │      Stage 2: Semantic ($$) — AC compliance, drift                 ┃
-┃           │      Stage 3: Consensus ($$$$) — multi-model vote                  ┃
+┃           │      Stage 3: Consensus ($$$$) — Advocate/Devil/Judge debate       ┃
 ┃           ▼                                                                    ┃
 ┃      ┌─────────┐                                                               ┃
 ┃      │ PHASE 5 │  S E C O N D A R Y   L O O P                                  ┃
@@ -312,9 +314,9 @@ def select_approach(task):
 ```
 src/ouroboros/
 │
-├── core/           ◆ The essence: types, errors, seed, context
+├── core/           ◆ The essence: types, errors, seed, ontology
 │
-├── bigbang/        ◇ Phase 0: Interview → Ambiguity → Seed
+├── bigbang/        ◇ Phase 0: Interview → Ontology → Ambiguity → Seed
 │
 ├── routing/        ◇ Phase 1: PAL router, complexity, tiers
 │
@@ -357,6 +359,7 @@ src/ouroboros/
 | **THE RESEARCHER** | *"Stop coding. Read the docs."* | Knowledge gap detected | Search, read documentation, find examples |
 | **THE SIMPLIFIER** | *"Cut scope in half. Return to MVP."* | Overengineering detected | Remove features, reduce complexity |
 | **THE ARCHITECT** | *"Question the foundation. Rebuild if needed."* | Structural issues | Redesign, refactor core assumptions |
+| **THE CONTRARIAN** | *"What if we're solving the wrong problem?"* | Root cause unclear | Challenge assumptions using ontological questions |
 
 <br/>
 
@@ -618,6 +621,8 @@ Contributions are welcome! Please see:
 [■■■■■■■■■■] Epic 6  Drift Control       ✓
 [■■■■■■■■■■] Epic 7  Secondary Loop      ✓
 [■■■■■■■■■■] Epic 8  Orchestrator        ✓
+[■■■■■■■■■■] Epic 9  MCP Integration     ✓
+[■■■■■■■■■■] Epic 10 TUI Mode            ✓
 ```
 
 ### Upcoming

{ouroboros_ai-0.3.0 → ouroboros_ai-0.4.0}/README.md

@@ -40,7 +40,7 @@
 <br/>
 
 <p align="center">
-  <code>75 modules</code> · <code>1,341 tests</code> · <code>97%+ coverage</code> · <code>v0.2.x</code>
+  <code>75 modules</code> · <code>1,341 tests</code> · <code>97%+ coverage</code>
 </p>
 
 <br/>
@@ -224,7 +224,7 @@ These iterate until a **Seed** crystallizes—a specification with `Ambiguity
 ┃      └────┬────┘                                                               ┃
 ┃           │      Stage 1: Mechanical ($0) — lint, build, test                  ┃
 ┃           │      Stage 2: Semantic ($$) — AC compliance, drift                 ┃
-┃           │      Stage 3: Consensus ($$$$) — multi-model vote                  ┃
+┃           │      Stage 3: Consensus ($$$$) — Advocate/Devil/Judge debate       ┃
 ┃           ▼                                                                    ┃
 ┃      ┌─────────┐                                                               ┃
 ┃      │ PHASE 5 │  S E C O N D A R Y   L O O P                                  ┃
@@ -292,9 +292,9 @@ def select_approach(task):
 ```
 src/ouroboros/
 │
-├── core/           ◆ The essence: types, errors, seed, context
+├── core/           ◆ The essence: types, errors, seed, ontology
 │
-├── bigbang/        ◇ Phase 0: Interview → Ambiguity → Seed
+├── bigbang/        ◇ Phase 0: Interview → Ontology → Ambiguity → Seed
 │
 ├── routing/        ◇ Phase 1: PAL router, complexity, tiers
 │
@@ -337,6 +337,7 @@ src/ouroboros/
 | **THE RESEARCHER** | *"Stop coding. Read the docs."* | Knowledge gap detected | Search, read documentation, find examples |
 | **THE SIMPLIFIER** | *"Cut scope in half. Return to MVP."* | Overengineering detected | Remove features, reduce complexity |
 | **THE ARCHITECT** | *"Question the foundation. Rebuild if needed."* | Structural issues | Redesign, refactor core assumptions |
+| **THE CONTRARIAN** | *"What if we're solving the wrong problem?"* | Root cause unclear | Challenge assumptions using ontological questions |
 
 <br/>
 
@@ -598,6 +599,8 @@ Contributions are welcome! Please see:
 [■■■■■■■■■■] Epic 6  Drift Control       ✓
 [■■■■■■■■■■] Epic 7  Secondary Loop      ✓
 [■■■■■■■■■■] Epic 8  Orchestrator        ✓
+[■■■■■■■■■■] Epic 9  MCP Integration     ✓
+[■■■■■■■■■■] Epic 10 TUI Mode            ✓
 ```
 
 ### Upcoming

{ouroboros_ai-0.3.0 → ouroboros_ai-0.4.0}/_bmad-output/planning-artifacts/architecture.md

@@ -149,6 +149,33 @@ class FilteredContext:
 - Fallback to sequential retry on partial failure
 - Minimum valid responses required before aggregation
 
+#### 6. Deliberative Consensus Pattern (v0.4.0)
+
+For high-stakes decisions requiring ontological validation:
+
+```python
+class DeliberativeConsensus:
+    """Two-round adversarial evaluation with philosophical grounding"""
+
+    async def evaluate(self, proposal: Proposal) -> DeliberativeResult:
+        # Round 1: Concurrent positions
+        advocate_task = self._run_advocate(proposal)
+        devil_task = self._run_devil(proposal)  # Uses ontology_questions
+        advocate, devil = await asyncio.gather(advocate_task, devil_task)
+
+        # Round 2: Judge renders verdict
+        verdict = await self._run_judge(advocate, devil)
+        return DeliberativeResult(
+            verdict=verdict,  # APPROVED | REJECTED | CONDITIONAL
+            is_root_solution=devil.confirmed_root_cause,
+        )
+```
+
+**Roles:**
+- **ADVOCATE**: Argues for the proposal's merits
+- **DEVIL'S ADVOCATE**: Challenges using four ontological questions (ESSENCE, ROOT_CAUSE, PREREQUISITES, HIDDEN_ASSUMPTIONS)
+- **JUDGE**: Synthesizes positions, renders final verdict
+
 ### Testing Strategy
 
 **Priority**: Observability Layer First (E0 Epic)
@@ -1000,6 +1027,46 @@ async def execute_phase(phase: Phase, uow: UnitOfWork):
     )
 ```
 
+#### Ontological Questioning Pattern (v0.4.0)
+
+```python
+from enum import Enum
+
+class OntologyQuestionType(str, Enum):
+    """Four fundamental questions for deep analysis"""
+    ESSENCE = "essence"              # "What IS this, really?"
+    ROOT_CAUSE = "root_cause"        # "Is this the root cause or a symptom?"
+    PREREQUISITES = "prerequisites"  # "What must exist first?"
+    HIDDEN_ASSUMPTIONS = "hidden_assumptions"  # "What are we assuming?"
+
+@dataclass
+class OntologyQuestion:
+    type: OntologyQuestionType
+    question: str
+    context: str
+
+    def format_prompt(self) -> str:
+        """Format for LLM consumption"""
+        return f"[{self.type.value.upper()}] {self.question}\nContext: {self.context}"
+
+# Usage in Contrarian Persona
+class ContrarianPersona:
+    def challenge(self, proposal: str) -> list[OntologyQuestion]:
+        return [
+            OntologyQuestion(
+                type=OntologyQuestionType.ROOT_CAUSE,
+                question="Is this addressing the root cause or treating a symptom?",
+                context=proposal,
+            ),
+            # ... other questions
+        ]
+```
+
+**Application Points:**
+- `resilience/personas.py`: Contrarian uses ontological questions
+- `evaluation/consensus.py`: Devil's Advocate role
+- `bigbang/ontology.py`: Interview framework discovery
+
 ### Anti-Patterns (MUST AVOID)
 
 #### 1. Zombie Objects (Detached ORM State)
@@ -1112,7 +1179,8 @@ ouroboros/
 │       │   │   ├── validate.py  # ouroboros validate <seed.yaml>
 │       │   │   ├── status.py    # ouroboros status [--seed-id]
 │       │   │   ├── resume.py    # ouroboros resume <checkpoint-id>
-│       │   │   └── config.py    # ouroboros config [show|set|init]
+│       │   │   ├── config.py    # ouroboros config [show|set|init]
+│       │   │   └── story.py     # v0.4.0: ouroboros story - narrative generation from universe
 │       │   └── formatters/
 │       │       ├── __init__.py
 │       │       ├── tables.py    # Rich table formatters
@@ -1126,6 +1194,7 @@ ouroboros/
 │       │   ├── protocols.py     # Protocol definitions (LLMAdapter, etc.)
 │       │   ├── seed.py          # Seed, OntologySchema, Constraints
 │       │   ├── ontology.py      # EffectiveOntology, OntologyEvent
+│       │   ├── ontology_questions.py  # v0.4.0: Four ontological probes (ESSENCE, ROOT_CAUSE, PREREQUISITES, HIDDEN_ASSUMPTIONS)
 │       │   ├── ac.py            # AcceptanceCriteria, ACNode, ACTree
 │       │   └── context.py       # ExecutionContext, contextvars
 │       │
@@ -1143,6 +1212,7 @@ ouroboros/
 │       │   ├── clarifier.py     # Clarification engine
 │       │   ├── ambiguity.py     # Ambiguity Gate (≤0.2 threshold)
 │       │   ├── interview.py     # Interview protocol
+│       │   ├── ontology.py      # v0.4.0: Ontological framework discovery during interview
 │       │   └── seed_generator.py # Generate Seed from interview
 │       │
 │       ├── routing/             # Phase 1: PAL Router
@@ -1169,10 +1239,12 @@ ouroboros/
 │       │
 │       ├── evaluation/          # Phase 4: Evaluation
 │       │   ├── __init__.py
+│       │   ├── models.py        # v0.4.0: EvaluationResult, ConsensusResult, Verdict
 │       │   ├── pipeline.py      # EvaluationPipeline orchestrator
 │       │   ├── mechanical.py    # Stage 1: MechanicalEvaluator ($0)
 │       │   ├── semantic.py      # Stage 2: SemanticEvaluator ($$)
-│       │   └── stage_result.py  # StageResult, EvaluationResult
+│       │   ├── consensus.py     # v0.4.0: DeliberativeConsensus (Advocate/Devil/Judge)
+│       │   └── stage_result.py  # StageResult (legacy, see models.py)
 │       │
 │       ├── consensus/           # Phase 5: Consensus
 │       │   ├── __init__.py
@@ -1749,3 +1821,7 @@ The Python 3.14 + uv + Typer stack with Event Sourcing and Domain-Driven Design
 
 **Document Maintenance:** Update this architecture when major technical decisions are made during implementation.
 
+---
+
+_Last Updated: 2026-02-02 (v0.4.0 additions)_
+

{ouroboros_ai-0.3.0 → ouroboros_ai-0.4.0}/_bmad-output/planning-artifacts/epics.md

@@ -369,6 +369,22 @@ So that I have a clear, immutable specification for execution.
 
 ---
 
+### Story 1.4: Story Generation Command
+
+As a developer,
+I want a CLI command to generate stories from my universe,
+So that I can create narrative elements based on the ontological framework.
+
+**Acceptance Criteria:**
+
+**Given** an existing universe with bigbang session
+**When** running `ouroboros story`
+**Then** the story generation wizard launches
+**And** user can select from discovered story types
+**And** narrative elements are generated based on universe ontology
+
+---
+
 ## Epic 2: Intelligent Task Routing (PAL)
 
 **Goal:** Developers benefit from cost-optimized LLM routing that automatically selects the right model tier based on task complexity, with intelligent escalation and downgrade.
@@ -547,7 +563,18 @@ So that stagnation is broken through creative approaches.
 **And** Researcher persona seeks additional information
 **And** Simplifier persona reduces complexity
 **And** Architect persona restructures the approach
-**And** Contrarian persona challenges assumptions
+**And** Contrarian persona challenges assumptions using ontological questions
+
+**Contrarian Ontological Analysis (v0.4.0):**
+
+**Given** the Contrarian persona is activated
+**When** challenging assumptions
+**Then** it uses the four ontological questions:
+  - ESSENCE: "What IS this, really?"
+  - ROOT_CAUSE: "Is this the root cause or a symptom?"
+  - PREREQUISITES: "What must exist first?"
+  - HIDDEN_ASSUMPTIONS: "What are we assuming?"
+**And** challenges are grounded in philosophical inquiry, not just contrarianism
 
 ---
 
@@ -589,6 +616,14 @@ So that obvious issues are caught before expensive LLM evaluation.
 **And** static analysis runs
 **And** coverage threshold ≥ 0.7 is verified
 
+**Unified Evaluation Protocol (v0.4.0):**
+
+**Given** any evaluation stage
+**When** `EvaluationProtocol.evaluate()` is called
+**Then** the unified interface dispatches to appropriate stage handler
+**And** `EvaluationResult` contains: passed, score, feedback, metadata
+**And** `ConsensusResult` extends with: verdicts list, majority_reached, dissenting_opinions
+
 ---
 
 ### Story 5.2: Stage 2 - Semantic Evaluation
@@ -621,6 +656,15 @@ So that important outputs have diverse verification.
 **And** 2/3 majority agreement is required
 **And** disagreements are logged with reasoning
 
+**Deliberative Mode (v0.4.0):**
+
+**Given** a high-stakes decision requiring ontological analysis
+**When** DeliberativeConsensus is triggered
+**Then** Round 1 runs ADVOCATE and DEVIL'S ADVOCATE positions concurrently
+**And** Devil's Advocate uses ontological questions to challenge root cause vs symptom
+**And** Round 2 has JUDGE review both positions and render verdict (APPROVED/REJECTED/CONDITIONAL)
+**And** `is_root_solution` indicates whether Devil confirmed the solution addresses root cause
+
 ---
 
 ### Story 5.4: Consensus Trigger Matrix
@@ -682,6 +726,29 @@ So that accumulated drift is caught and corrected.
 
 ---
 
+### Story 6.3: Ontological Framework Discovery
+
+As a developer using the interview system,
+I want the bigbang interview to capture fundamental ontological insights,
+So that the generated universe has coherent philosophical foundations.
+
+**Acceptance Criteria:**
+
+**Given** a bigbang interview session
+**When** exploring the problem domain
+**Then** the system probes for:
+  - ESSENCE: The fundamental nature of concepts
+  - ROOT_CAUSE: Distinguishing symptoms from causes
+  - PREREQUISITES: Identifying foundational dependencies
+  - HIDDEN_ASSUMPTIONS: Surfacing implicit beliefs
+
+**Given** ontological insights are captured
+**When** the interview completes
+**Then** findings are stored in structured format for universe generation
+**And** can inform the Contrarian persona and Devil's Advocate evaluations
+
+---
+
 ## Epic 7: Secondary Loop & TODO Processing
 
 **Goal:** Developers can defer non-critical improvements discovered during execution and process them efficiently in batches after primary goals are met.
@@ -793,20 +860,210 @@ So that I can run orchestrator mode from the command line.
 
 ---
 
+## Epic 9: MCP Protocol Integration
+
+**Value Proposition:** Enable Ouroboros to be controlled via Model Context Protocol, allowing Claude Desktop and other MCP clients to execute workflows.
+
+**Dependencies:** Epic 0 (Foundation), Epic 8 (Orchestrator)
+
+**Stories:** 4
+
+---
+
+### Story 9.1: MCP Type Definitions
+
+As a developer,
+I want well-typed MCP protocol types,
+So that I can implement type-safe MCP communication.
+
+**Acceptance Criteria:**
+
+**Given** the mcp/types.py module
+**When** I import MCP types
+**Then** MCPToolDefinition, MCPToolResult, MCPResourceDefinition are available
+**And** MCPCapabilities, MCPServerInfo describe server capabilities
+**And** all types are immutable dataclasses with validation
+
+---
+
+### Story 9.2: MCP Server Adapter
+
+As a developer,
+I want an MCP server that exposes Ouroboros tools,
+So that MCP clients can interact with Ouroboros.
+
+**Acceptance Criteria:**
+
+**Given** the mcp/server/adapter.py module
+**When** I create and start an MCPServerAdapter
+**Then** tools are registered via register_tool()
+**And** resources are registered via register_resource()
+**And** server supports stdio and SSE transports
+**And** FastMCP SDK is used for protocol handling
+
+---
+
+### Story 9.3: MCP Tools Implementation
+
+As a developer,
+I want Ouroboros functionality exposed as MCP tools,
+So that Claude Desktop can execute seeds and query status.
+
+**Acceptance Criteria:**
+
+**Given** the mcp/tools/definitions.py module
+**When** OUROBOROS_TOOLS are registered
+**Then** ouroboros_execute_seed executes a seed specification
+**And** ouroboros_session_status returns session state
+**And** ouroboros_query_events queries event history
+**And** all tools return Result types for error handling
+
+---
+
+### Story 9.4: MCP CLI Integration
+
+As a developer,
+I want CLI commands for MCP server management,
+So that I can start and inspect MCP servers from the command line.
+
+**Acceptance Criteria:**
+
+**Given** the cli/commands/mcp.py module
+**When** I run `ouroboros mcp serve`
+**Then** MCP server starts with configured transport
+**And** `ouroboros mcp info` shows server information and tools
+**And** `--transport`, `--host`, `--port` options are available
+
+---
+
+## Epic 10: Interactive TUI Mode
+
+**Value Proposition:** Provide real-time visual monitoring of workflow execution through an interactive terminal interface.
+
+**Dependencies:** Epic 0 (Foundation), Epic 8 (Orchestrator)
+
+**Stories:** 6
+
+---
+
+### Story 10.1: TUI Application Framework
+
+As a developer,
+I want a Textual-based TUI application,
+So that I can monitor workflows in real-time.
+
+**Acceptance Criteria:**
+
+**Given** the tui/app.py module
+**When** I launch OuroborosTUI
+**Then** application initializes with TUIState
+**And** screens are registered and switchable via number keys
+**And** events from EventStore update the UI reactively
+**And** keyboard shortcuts are documented in help screen
+
+---
+
+### Story 10.2: Dashboard Screen
+
+As a developer,
+I want a dashboard showing execution overview,
+So that I can see phase progress, drift, and costs at a glance.
+
+**Acceptance Criteria:**
+
+**Given** the tui/screens/dashboard.py module
+**When** Dashboard screen is displayed
+**Then** PhaseProgressWidget shows Double Diamond phases
+**And** DriftMeterWidget shows weighted drift score
+**And** CostTrackerWidget shows token usage and cost
+**And** ACTreeWidget shows acceptance criteria hierarchy
+
+---
+
+### Story 10.3: Logs Screen
+
+As a developer,
+I want a filterable log viewer,
+So that I can inspect execution logs by level.
+
+**Acceptance Criteria:**
+
+**Given** the tui/screens/logs.py module
+**When** Logs screen is displayed
+**Then** logs are displayed with timestamps and levels
+**And** LogFilterBar allows filtering by level (DEBUG/INFO/WARNING/ERROR)
+**And** logs auto-scroll and can be paused
+**And** filter changes refresh the log display
+
+---
+
+### Story 10.4: Execution Screen
+
+As a developer,
+I want detailed execution information,
+So that I can inspect phase outputs and event timeline.
+
+**Acceptance Criteria:**
+
+**Given** the tui/screens/execution.py module
+**When** Execution screen is displayed
+**Then** current phase and status are shown
+**And** event timeline shows chronological events
+**And** phase outputs are displayed per phase
+**And** events update reactively from EventStore
+
+---
+
+### Story 10.5: Debug Screen
+
+As a developer,
+I want debug tools for inspecting state,
+So that I can troubleshoot issues during development.
+
+**Acceptance Criteria:**
+
+**Given** the tui/screens/debug.py module
+**When** Debug screen is displayed
+**Then** StateInspector shows TUIState fields
+**And** raw events tab shows unprocessed events
+**And** config tab shows current configuration
+**And** state can be refreshed manually
+
+---
+
+### Story 10.6: TUI CLI Integration
+
+As a developer,
+I want CLI commands for launching TUI,
+So that I can monitor executions from the command line.
+
+**Acceptance Criteria:**
+
+**Given** the cli/commands/tui.py module
+**When** I run `ouroboros tui monitor`
+**Then** TUI application launches
+**And** `--execution-id` monitors specific execution
+**And** `--session-id` monitors specific session
+**And** keyboard navigation works (1-5 for screens, q to quit)
+
+---
+
 ## Epic Summary
 
 | Epic | Title | Stories | FRs | Key Value |
 |------|-------|---------|-----|-----------|
 | 0 | Project Foundation & Infrastructure | 9 | 3 | Installable, configurable CLI |
-| 1 | Seed Creation via Big Bang | 3 | 3 | Clear requirement specification |
+| 1 | Seed Creation via Big Bang | 4 | 3 | Clear requirement specification |
 | 2 | Intelligent Task Routing (PAL) | 4 | 4 | Cost-optimized LLM usage |
 | 3 | Double Diamond Execution | 4 | 3 | Recursive task decomposition |
 | 4 | Resilience & Stagnation Recovery | 3 | 2 | Zero-stop operation |
 | 5 | Three-Stage Evaluation Pipeline | 4 | 4 | Rigorous verification |
-| 6 | Drift Control & Retrospective | 2 | 2 | Goal alignment |
+| 6 | Drift Control & Retrospective | 3 | 2 | Goal alignment |
 | 7 | Secondary Loop & TODO Processing | 2 | 2 | Deferred improvements |
 | 8 | Orchestrator (Claude Agent SDK) | 4 | - | Real code execution via SDK |
-| **Total** | | **35** | **23** | |
+| 9 | MCP Protocol Integration | 4 | - | External client integration |
+| 10 | Interactive TUI Mode | 6 | - | Real-time visual monitoring |
+| **Total** | | **45** | **23** | |
 
 ---
 
@@ -824,6 +1081,10 @@ Epic 1 (Seed) ──→ Epic 2 (Routing) ──→ Epic 3 (Execution)
                                       Epic 6 (Drift) ──→ Epic 7 (Secondary)
                                                               ↓
                                                         Epic 8 (Orchestrator)
+                                                              ↓
+                                              ┌───────────────┴───────────────┐
+                                              ↓                               ↓
+                                        Epic 9 (MCP)                   Epic 10 (TUI)
 ```
 
 Each Epic provides **complete, standalone functionality** while building upon previous Epics. No Epic requires a future Epic to function.
@@ -831,5 +1092,5 @@ Each Epic provides **complete, standalone functionality** while building upon pr
 ---
 
 _Generated: 2026-01-14_
-_Updated: 2026-01-23_
-_Status: Complete_
+_Updated: 2026-02-03_
+_Status: Complete (v0.4.0 additions)_