timmy-home/uni-wizard/v2/README.md

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:

@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:

# 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:

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)

{
    "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)

{
    "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)

{
    "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:

{
  "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:

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

Usage Examples

Basic Tool Execution

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

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

# 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.