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

{ouroboros_ai-0.2.3 → ouroboros_ai-0.4.0}/CHANGELOG.md

@@ -5,6 +5,44 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-01-28
+
+### Added
+
+#### Documentation
+- **CLI Reference** (`docs/cli-reference.md`) - Complete command reference with examples
+- **Prerequisites section** in README with Python 3.14+ requirement
+- **Contributing section** with links to Issues and Discussions
+- **OSS badges** - PyPI version, Python version, License
+
+#### Interview System
+- **Tiered confirmation system** for interview rounds:
+  - Rounds 1-3: Auto-continue (minimum context gathering)
+  - Rounds 4-15: Ask "Continue?" after each round
+  - Rounds 16+: Ask "Continue?" with diminishing returns warning
+- **No hard round limit** - User controls when to stop
+- New constants: `MIN_ROUNDS_BEFORE_EARLY_EXIT`, `SOFT_LIMIT_WARNING_THRESHOLD`
+
+### Changed
+
+#### Interview Engine
+- Removed `MAX_INTERVIEW_ROUNDS` hard limit (was 10)
+- `is_complete` now only checks status (user-controlled completion)
+- `record_response()` no longer auto-completes at max rounds
+- System prompt simplified to show "Round N" instead of "Round N of 10"
+
+#### CLI Init Command
+- Extracted `_run_interview_loop()` helper to eliminate code duplication (~60 lines)
+- State saved immediately after status mutation for consistency
+- Updated welcome message to reflect no round limit
+
+### Removed
+- Korean-language requirement documents (`requirement/` folder)
+- Hard round limit enforcement in interview engine
+
+### Fixed
+- Code duplication in init.py interview continuation flow
+
 ## [0.2.0] - 2026-01-27
 
 ### Added

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.2.3 → ouroboros_ai-0.4.0}/PKG-INFO

@@ -1,14 +1,16 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.2.3
+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
@@ -41,18 +43,26 @@ Description-Content-Type: text/markdown
   <em>The serpent that devours itself to be reborn anew.</em>
 </p>
 
+<p align="center">
+  <a href="https://pypi.org/project/ouroboros-ai/"><img src="https://img.shields.io/pypi/v/ouroboros-ai?color=blue" alt="PyPI"></a>
+  <a href="https://python.org"><img src="https://img.shields.io/badge/python-3.14+-blue" alt="Python"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+</p>
+
 <p align="center">
   <a href="#-philosophy">Philosophy</a> •
   <a href="#-the-six-phases">Phases</a> •
   <a href="#-architecture">Architecture</a> •
+  <a href="#-prerequisites">Prerequisites</a> •
   <a href="#-quick-start">Start</a> •
-  <a href="#-the-personas-lateral-thinking-agents">Personas</a>
+  <a href="#-roadmap">Roadmap</a> •
+  <a href="#-contributing">Contributing</a>
 </p>
 
 <br/>
 
 <p align="center">
-  <code>74 modules</code> · <code>1,341 tests</code> · <code>97%+ coverage</code>
+  <code>75 modules</code> · <code>1,341 tests</code> · <code>97%+ coverage</code>
 </p>
 
 <br/>
@@ -236,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                                  ┃
@@ -304,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
 │
@@ -349,10 +359,11 @@ 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/>
 
-**작동 방식**: Stagnation Detection (4 patterns) → Persona Rotation → 새로운 관점으로 재시도
+**How it works**: Stagnation Detection (4 patterns) → Persona Rotation → Retry with fresh perspective
 
 <br/>
 
@@ -415,6 +426,22 @@ not to restart, but to **re-crystallize** with new understanding.
 
 <br/>
 
+## ◈ Prerequisites
+
+<br/>
+
+| Requirement | Description |
+|-------------|-------------|
+| **Python 3.14+** | Required (uses latest language features) |
+| **Claude Code Max Plan** | For orchestrator mode (no API key needed) |
+| **OR API Key** | OpenRouter, Anthropic, or OpenAI for LiteLLM mode |
+
+<br/>
+
+---
+
+<br/>
+
 ## ◈ Installation
 
 <br/>
@@ -476,7 +503,7 @@ uv run ouroboros init start "I want to build a task management CLI"
 uv run ouroboros status health
 ```
 
-> 📖 **[Full Guide: Running with Claude Code](docs/running-with-claude-code.md)**
+> 📖 **[Full Guide: Running with Claude Code](docs/running-with-claude-code.md)** | **[CLI Reference](docs/cli-reference.md)**
 
 <br/>
 
@@ -563,22 +590,51 @@ uv run ruff format src/
 
 <br/>
 
+## ◈ Contributing
+
+<br/>
+
+Contributions are welcome! Please see:
+
+- **Issues**: [GitHub Issues](https://github.com/Q00/ouroboros/issues) for bugs and feature requests
+- **Discussions**: [GitHub Discussions](https://github.com/Q00/ouroboros/discussions) for questions and ideas
+
+<br/>
+
+---
+
+<br/>
+
 ## ◈ Roadmap
 
 <br/>
 
+### Completed
+
 ```
-[■■■■■■■■■■] Epic 0  Foundation
-[■■■■■■■■■■] Epic 1  Big Bang
-[■■■■■■■■■■] Epic 2  PAL Router
-[■■■■■■■■■■] Epic 3  Double Diamond
-[■■■■■■■■■■] Epic 4  Resilience
-[■■■■■■■■■■] Epic 5  Evaluation
-[■■■■■■■■■■] Epic 6  Drift Control
-[■■■■■■■■■■] Epic 7  Secondary Loop
-[■■■■■■■■■■] Epic 8  Orchestrator      ✓ Complete
+[■■■■■■■■■■] Epic 0  Foundation          ✓
+[■■■■■■■■■■] Epic 1  Big Bang            ✓
+[■■■■■■■■■■] Epic 2  PAL Router          ✓
+[■■■■■■■■■■] Epic 3  Double Diamond      ✓
+[■■■■■■■■■■] Epic 4  Resilience          ✓
+[■■■■■■■■■■] Epic 5  Evaluation          ✓
+[■■■■■■■■■■] Epic 6  Drift Control       ✓
+[■■■■■■■■■■] Epic 7  Secondary Loop      ✓
+[■■■■■■■■■■] Epic 8  Orchestrator        ✓
+[■■■■■■■■■■] Epic 9  MCP Integration     ✓
+[■■■■■■■■■■] Epic 10 TUI Mode            ✓
 ```
 
+### Upcoming
+
+| Feature | Description | Status |
+|---------|-------------|--------|
+| **Worker MCP** | MCP server for distributed task execution | Planned |
+| **TUI Enhancement** | Rich terminal UI with real-time progress | Planned |
+| **AC Tree Visualization** | Interactive acceptance criteria graph | Planned |
+| **Plugin System** | Custom evaluators and personas | Planned |
+| **Web Dashboard** | Execution monitoring and analytics | Planned |
+
 <br/>
 
 ---

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

@@ -21,18 +21,26 @@
   <em>The serpent that devours itself to be reborn anew.</em>
 </p>
 
+<p align="center">
+  <a href="https://pypi.org/project/ouroboros-ai/"><img src="https://img.shields.io/pypi/v/ouroboros-ai?color=blue" alt="PyPI"></a>
+  <a href="https://python.org"><img src="https://img.shields.io/badge/python-3.14+-blue" alt="Python"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+</p>
+
 <p align="center">
   <a href="#-philosophy">Philosophy</a> •
   <a href="#-the-six-phases">Phases</a> •
   <a href="#-architecture">Architecture</a> •
+  <a href="#-prerequisites">Prerequisites</a> •
   <a href="#-quick-start">Start</a> •
-  <a href="#-the-personas-lateral-thinking-agents">Personas</a>
+  <a href="#-roadmap">Roadmap</a> •
+  <a href="#-contributing">Contributing</a>
 </p>
 
 <br/>
 
 <p align="center">
-  <code>74 modules</code> · <code>1,341 tests</code> · <code>97%+ coverage</code>
+  <code>75 modules</code> · <code>1,341 tests</code> · <code>97%+ coverage</code>
 </p>
 
 <br/>
@@ -216,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                                  ┃
@@ -284,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
 │
@@ -329,10 +337,11 @@ 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/>
 
-**작동 방식**: Stagnation Detection (4 patterns) → Persona Rotation → 새로운 관점으로 재시도
+**How it works**: Stagnation Detection (4 patterns) → Persona Rotation → Retry with fresh perspective
 
 <br/>
 
@@ -395,6 +404,22 @@ not to restart, but to **re-crystallize** with new understanding.
 
 <br/>
 
+## ◈ Prerequisites
+
+<br/>
+
+| Requirement | Description |
+|-------------|-------------|
+| **Python 3.14+** | Required (uses latest language features) |
+| **Claude Code Max Plan** | For orchestrator mode (no API key needed) |
+| **OR API Key** | OpenRouter, Anthropic, or OpenAI for LiteLLM mode |
+
+<br/>
+
+---
+
+<br/>
+
 ## ◈ Installation
 
 <br/>
@@ -456,7 +481,7 @@ uv run ouroboros init start "I want to build a task management CLI"
 uv run ouroboros status health
 ```
 
-> 📖 **[Full Guide: Running with Claude Code](docs/running-with-claude-code.md)**
+> 📖 **[Full Guide: Running with Claude Code](docs/running-with-claude-code.md)** | **[CLI Reference](docs/cli-reference.md)**
 
 <br/>
 
@@ -543,22 +568,51 @@ uv run ruff format src/
 
 <br/>
 
+## ◈ Contributing
+
+<br/>
+
+Contributions are welcome! Please see:
+
+- **Issues**: [GitHub Issues](https://github.com/Q00/ouroboros/issues) for bugs and feature requests
+- **Discussions**: [GitHub Discussions](https://github.com/Q00/ouroboros/discussions) for questions and ideas
+
+<br/>
+
+---
+
+<br/>
+
 ## ◈ Roadmap
 
 <br/>
 
+### Completed
+
 ```
-[■■■■■■■■■■] Epic 0  Foundation
-[■■■■■■■■■■] Epic 1  Big Bang
-[■■■■■■■■■■] Epic 2  PAL Router
-[■■■■■■■■■■] Epic 3  Double Diamond
-[■■■■■■■■■■] Epic 4  Resilience
-[■■■■■■■■■■] Epic 5  Evaluation
-[■■■■■■■■■■] Epic 6  Drift Control
-[■■■■■■■■■■] Epic 7  Secondary Loop
-[■■■■■■■■■■] Epic 8  Orchestrator      ✓ Complete
+[■■■■■■■■■■] Epic 0  Foundation          ✓
+[■■■■■■■■■■] Epic 1  Big Bang            ✓
+[■■■■■■■■■■] Epic 2  PAL Router          ✓
+[■■■■■■■■■■] Epic 3  Double Diamond      ✓
+[■■■■■■■■■■] Epic 4  Resilience          ✓
+[■■■■■■■■■■] Epic 5  Evaluation          ✓
+[■■■■■■■■■■] Epic 6  Drift Control       ✓
+[■■■■■■■■■■] Epic 7  Secondary Loop      ✓
+[■■■■■■■■■■] Epic 8  Orchestrator        ✓
+[■■■■■■■■■■] Epic 9  MCP Integration     ✓
+[■■■■■■■■■■] Epic 10 TUI Mode            ✓
 ```
 
+### Upcoming
+
+| Feature | Description | Status |
+|---------|-------------|--------|
+| **Worker MCP** | MCP server for distributed task execution | Planned |
+| **TUI Enhancement** | Rich terminal UI with real-time progress | Planned |
+| **AC Tree Visualization** | Interactive acceptance criteria graph | Planned |
+| **Plugin System** | Custom evaluators and personas | Planned |
+| **Web Dashboard** | Execution monitoring and analytics | Planned |
+
 <br/>
 
 ---

{ouroboros_ai-0.2.3 → 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)_
+