# Uni-Wizard v2 — The Three-House Architecture

> *"Ezra reads and orders the pattern. Bezalel builds and unfolds the pattern. Timmy judges and preserves sovereignty."*

## Overview

The Uni-Wizard v2 is a refined architecture that integrates:

- **Timmy's** sovereignty metrics, conscience, and local-first telemetry
- **Ezra's** archivist pattern: read before write, evidence over vibes, citation discipline
- **Bezalel's** artificer pattern: build from plans, proof over speculation, forge discipline

## Core Principles

### 1. Three Distinct Houses

| House | Role | Primary Capability | Motto |
|-------|------|-------------------|-------|
| **Timmy** | Sovereign | Judgment, review, final authority | *Sovereignty and service always* |
| **Ezra** | Archivist | Reading, analysis, synthesis | *Read the pattern. Name the truth.* |
| **Bezalel** | Artificer | Building, testing, proving | *Build the pattern. Prove the result.* |

### 2. Non-Merging Rule

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│    EZRA     │     │   BEZALEL   │     │    TIMMY    │
│  (Archivist)│     │ (Artificer) │     │  (Sovereign)│
│   Reads →   │────→│  Builds →   │────→│  Judges     │
│   Shapes    │     │   Proves    │     │  Approves   │
└─────────────┘     └─────────────┘     └─────────────┘
       ↑                                        │
       └────────────────────────────────────────┘
              Artifacts flow one direction
```

No house blends into another. Each maintains distinct identity, telemetry, and provenance.

### 3. Provenance-First Execution

Every tool execution produces a `Provenance` record:

```python
@dataclass
class Provenance:
    house: str              # Which house executed
    tool: str               # Tool name
    started_at: str         # ISO timestamp
    completed_at: str       # ISO timestamp
    input_hash: str         # Content hash of inputs
    output_hash: str        # Content hash of outputs
    sources_read: List[str] # Ezra: what was read
    evidence_level: str     # none, partial, full
    confidence: float       # 0.0 to 1.0
```

## Architecture

### Harness (harness.py)

The `UniWizardHarness` is the core execution engine with house-aware policies:

```python
# Ezra mode — enforces reading before writing
ezra = UniWizardHarness(house="ezra")
result = ezra.execute("git_commit", message="Update")
# → Fails if git_status wasn't called first

# Bezalel mode — enforces proof verification
bezalel = UniWizardHarness(house="bezalel")
result = bezalel.execute("deploy", target="production")
# → Verifies tests passed before deploying

# Timmy mode — full telemetry, sovereign judgment
timmy = UniWizardHarness(house="timmy")
review = timmy.review_for_timmy(results)
# → Generates structured review with recommendation
```

### Router (router.py)

The `HouseRouter` automatically routes tasks to the appropriate house:

```python
router = HouseRouter()

# Auto-routed to Ezra (read operation)
result = router.route("git_status", repo_path="/path")

# Auto-routed to Bezalel (build operation)  
result = router.route("git_commit", repo_path="/path", message="Update")

# Multi-phase workflow
results = router.execute_multi_house_plan([
    {"tool": "git_status", "params": {}, "house": "ezra"},
    {"tool": "git_commit", "params": {"message": "Update"}, "house": "bezalel"}
], require_timmy_approval=True)
```

### Task Router Daemon (task_router_daemon.py)

Polls Gitea and executes the full three-house workflow:

1. **Ezra reads** the issue, analyzes, shapes approach
2. **Bezalel implements** based on Ezra's analysis, generates proof
3. **Timmy reviews** both phases, renders sovereign judgment
4. **Comment posted** to issue with full provenance

## House Policies

### Ezra (Archivist)

```python
{
    "requires_provenance": True,
    "evidence_threshold": 0.8,
    "must_read_before_write": True,
    "citation_required": True
}
```

- Must read git status before git commit
- Must cite sources in outputs
- Evidence level must be "full" for archives
- Confidence threshold: 80%

### Bezalel (Artificer)

```python
{
    "requires_provenance": True,
    "evidence_threshold": 0.6,
    "requires_proof": True,
    "test_before_ship": True
}
```

- Must verify proof before marking complete
- Tests must pass before "shipping"
- Fail-fast on verification failures
- Confidence threshold: 60%

### Timmy (Sovereign)

```python
{
    "requires_provenance": True,
    "evidence_threshold": 0.7,
    "can_override": True,
    "telemetry": True
}
```

- Records all telemetry
- Can override other houses
- Final judgment authority
- Confidence threshold: 70%

## Telemetry & Sovereignty Metrics

Every execution is logged to `~/timmy/logs/uni_wizard_telemetry.jsonl`:

```json
{
  "session_id": "abc123...",
  "timestamp": "2026-03-30T20:00:00Z",
  "house": "ezra",
  "tool": "git_status",
  "success": true,
  "execution_time_ms": 145,
  "evidence_level": "full",
  "confidence": 0.95,
  "sources_count": 3
}
```

Generate sovereignty report:

```python
harness = UniWizardHarness("timmy")
print(harness.get_telemetry_report())
```

## Usage Examples

### Basic Tool Execution

```python
from harness import get_harness

# Ezra analyzes repository
ezra = get_harness("ezra")
result = ezra.execute("git_log", repo_path="/path", max_count=10)
print(f"Evidence: {result.provenance.evidence_level}")
print(f"Confidence: {result.provenance.confidence}")
```

### Cross-House Workflow

```python
from router import HouseRouter

router = HouseRouter()

# Ezra reads issue → Bezalel implements → Timmy reviews
results = router.execute_multi_house_plan([
    {"tool": "gitea_get_issue", "params": {"number": 42}, "house": "ezra"},
    {"tool": "file_write", "params": {"path": "/tmp/fix.py"}, "house": "bezalel"},
    {"tool": "run_tests", "params": {}, "house": "bezalel"}
], require_timmy_approval=True)

# Timmy's judgment available in results["timmy_judgment"]
```

### Running the Daemon

```bash
# Three-house task router
python task_router_daemon.py --repo Timmy_Foundation/timmy-home

# Skip Timmy approval (testing)
python task_router_daemon.py --no-timmy-approval
```

## File Structure

```
uni-wizard/v2/
├── README.md                 # This document
├── harness.py               # Core harness with house policies
├── router.py                # Intelligent task routing
├── task_router_daemon.py    # Gitea polling daemon
└── tests/
    └── test_v2.py          # Test suite
```

## Integration with Canon

This implementation respects the canon from `specs/timmy-ezra-bezalel-canon-sheet.md`:

1. ✅ **Distinct houses** — Each has unique identity, policy, telemetry
2. ✅ **No blending** — Houses communicate via artifacts, not shared state
3. ✅ **Timmy sovereign** — Final review authority, can override
4. ✅ **Ezra reads first** — Must_read_before_write enforced
5. ✅ **Bezalel proves** — Proof verification required
6. ✅ **Provenance** — Every action logged with full traceability
7. ✅ **Telemetry** — Timmy's sovereignty metrics tracked

## Comparison with v1

| Aspect | v1 | v2 |
|--------|-----|-----|
| Houses | Single harness | Three distinct houses |
| Provenance | Basic | Full with hashes, sources |
| Policies | None | House-specific enforcement |
| Telemetry | Limited | Full sovereignty metrics |
| Routing | Manual | Intelligent auto-routing |
| Ezra pattern | Not enforced | Read-before-write enforced |
| Bezalel pattern | Not enforced | Proof-required enforced |

## Future Work

- [ ] LLM integration for Ezra analysis phase
- [ ] Automated implementation in Bezalel phase
- [ ] Multi-issue batch processing
- [ ] Web dashboard for sovereignty metrics
- [ ] Cross-house learning (Ezra learns from Timmy reviews)

---

*Sovereignty and service always.*