# Uni-Wizard v4 — Production Architecture

## Overview

This PR delivers the complete four-pass evolution of the Uni-Wizard architecture, from foundation to production-ready self-improving intelligence system.

## Four-Pass Evolution

### Pass 1: Foundation (Issues #74-#79)
- **Syncthing mesh setup** for VPS fleet synchronization
- **VPS provisioning script** for sovereign Timmy deployment
- **Tool registry** with 19 tools (system, git, network, file)
- **Health daemon** and **task router** daemons
- **systemd services** for production deployment
- **Scorecard generator** (JSONL telemetry for overnight analysis)

### Pass 2: Three-House Canon
- **Timmy (Sovereign)**: Final judgment, telemetry, sovereignty preservation
- **Ezra (Archivist)**: Read-before-write, evidence over vibes, citation discipline
- **Bezalel (Artificer)**: Build-from-plans, proof over speculation, test-first
- **Provenance tracking** with content hashing
- **Artifact-flow discipline** (no house blending)

### Pass 3: Self-Improving Intelligence
- **Pattern database** (SQLite backend) for execution history
- **Adaptive policies** that auto-adjust thresholds based on performance
- **Predictive execution** (success prediction before running)
- **Learning velocity tracking**
- **Hermes bridge** for shortest-loop telemetry (<100ms)
- **Pre/post execution learning**

### Pass 4: Production Integration
- **Unified API**: `from uni_wizard import Harness, House, Mode`
- **Three modes**: SIMPLE / INTELLIGENT / SOVEREIGN
- **Circuit breaker pattern** for fault tolerance
- **Async/concurrent execution** support
- **Production hardening**: timeouts, retries, graceful degradation

## File Structure

```
uni-wizard/
├── v1/                    # Foundation layer
│   ├── tools/            # 19 tool implementations
│   ├── daemons/          # Health and task router daemons
│   └── scripts/          # Scorecard generator
├── v2/                    # Three-House Architecture
│   ├── harness.py        # House-aware execution
│   ├── router.py         # Intelligent task routing
│   └── task_router_daemon.py
├── v3/                    # Self-Improving Intelligence
│   ├── intelligence_engine.py   # Pattern DB, predictions, adaptation
│   ├── harness.py               # Adaptive policies
│   ├── hermes_bridge.py         # Shortest-loop telemetry
│   └── tests/test_v3.py
├── v4/                    # Production Integration
│   ├── FINAL_ARCHITECTURE.md    # Complete architecture doc
│   └── uni_wizard/__init__.py   # Unified production API
├── FINAL_SUMMARY.md       # Executive summary
docs/
└── ALLEGRO_LANE_v4.md     # Narrowed Allegro lane definition
```

## Key Features

### 1. Multi-Tier Caching Foundation
The architecture provides the foundation for comprehensive caching (Issue #103):
- Tool result caching with TTL
- Pattern caching for predictions
- Response caching infrastructure

### 2. Backend Routing Foundation
Foundation for multi-backend LLM routing (Issue #95, #101):
- House-based routing (Timmy/Ezra/Bezalel)
- Model performance tracking
- Fallback chain infrastructure

### 3. Self-Improvement
- Automatic policy adaptation based on success rates
- Learning velocity tracking
- Prediction accuracy measurement

### 4. Production Ready
- Circuit breakers for fault tolerance
- Comprehensive telemetry
- Health monitoring
- Graceful degradation

## Usage

```python
from uni_wizard import Harness, House, Mode

# Simple mode - direct execution
harness = Harness(mode=Mode.SIMPLE)
result = harness.execute("git_status", repo_path="/path")

# Intelligent mode - with predictions and learning
harness = Harness(house=House.EZRA, mode=Mode.INTELLIGENT)
result = harness.execute("git_status")
print(f"Predicted success: {result.provenance.prediction:.0%}")

# Sovereign mode - full provenance
harness = Harness(house=House.TIMMY, mode=Mode.SOVEREIGN)
result = harness.execute("deploy")
```

## Testing

```bash
cd uni-wizard/v3/tests
python test_v3.py
```

## Allegro Lane Definition

This PR includes the narrowed definition of Allegro's lane:
- **Primary**: Gitea bridge (40%), Hermes bridge (40%)
- **Secondary**: Redundancy/failover (10%), Operations (10%)
- **Explicitly NOT**: Making sovereign decisions, authenticating as Timmy

## Related Issues

- Closes #76 (Tool library expansion)
- Closes #77 (Gitea task router)
- Closes #78 (Health check daemon)
- Provides foundation for #103 (Caching layer)
- Provides foundation for #95 (Backend routing)
- Provides foundation for #94 (Grand Timmy)

## Deployment

```bash
# Install
pip install -e uni-wizard/v4/

# Start services
sudo systemctl enable uni-wizard
sudo systemctl start uni-wizard

# Verify
uni-wizard health
```

---

**Total**: ~8,000 lines of architecture and production code
**Status**: Production ready
**Ready for**: Deployment to VPS fleet