docs/phases/PHASE7_EXECUTIVE_CONTROL.md

# Phase 7: Executive Control Architecture

**Status**: MVP Implementation Complete ✅
**Date**: 2026-03-20
**Author**: Jonathan Harrison (Codette Framework)

## Overview

Phase 7 solves the "powerful brain without executive function" problem by adding intelligent routing of queries to optimal Phase 1-6 component combinations.

**Core Problem**: All queries activated the full machinery (debate, semantic tension, pre-flight prediction, etc.), wasting compute on simple factual questions and slowing down latency unnecessarily.

**Solution**: An Executive Controller that makes per-query routing decisions:
- **SIMPLE** queries (factual): Skip heavy machinery, direct answer (~150ms, 3 compute units)
- **MEDIUM** queries (conceptual): 1-round debate with selective components (~900ms, 25 units)
- **COMPLEX** queries (philosophical/multi-domain): Full 3-round debate with all Phase 1-6 components (~2500ms, 50+ units)

## Architecture

### Executive Controller (`reasoning_forge/executive_controller.py`)

**Core Class**: `ExecutiveController`

```python
decision = controller.route_query(query, complexity)
# Returns ComponentDecision with:
# - component_activation: dict of which Phase 1-6 components to enable
# - component_config: configuration for each component (e.g., debate_rounds: 1)
# - reasoning: explanation of why this routing was chosen
# - estimated_latency_ms, compute_cost: performance expectations
```

**Three Routing Paths**:

1. **SIMPLE Route** (QueryComplexity.SIMPLE)
   ```
   Components activated: None (direct answer)
   Debate: False
   Semantic Tension: False
   Pre-flight Prediction: False
   Expected latency: 150ms
   Expected correctness: 0.95
   Compute cost: 3 units
   ```

2. **MEDIUM Route** (QueryComplexity.MEDIUM)
   ```
   Components activated: Selective
   Debate: True (1 round)
   Semantic Tension: True
   Specialization Tracking: True
   Pre-flight Prediction: False (skipped)
   Memory Weighting: True
   Expected latency: 900ms
   Expected correctness: 0.80
   Compute cost: 25 units
   ```

3. **COMPLEX Route** (QueryComplexity.COMPLEX)
   ```
   Components activated: All Phase 1-6
   Debate: True (3 rounds)
   Semantic Tension: True
   Specialization Tracking: True
   Pre-flight Prediction: True
   Memory Weighting: True
   Gamma Monitoring: True
   Expected latency: 2500ms
   Expected correctness: 0.85
   Compute cost: 50+ units
   ```

### Integration Points

1. **CodetteForgeBridge** (`inference/codette_forge_bridge.py`)
   - Modified to import and initialize ExecutiveController
   - `_generate_with_phase6()` now calls `executive_controller.route_query()` before activation
   - SIMPLE queries now bypass ForgeEngine entirely, use direct orchestrator
   - Response metadata includes Phase 7 routing transparency

2. **Response Transparency**
   ```python
   response['phase7_routing'] = {
       'query_complexity': 'simple',
       'components_activated': {
           'debate': False,
           'semantic_tension': False,
           ...
       },
       'reasoning': "SIMPLE factual query - avoided heavy machinery for speed",
       'latency_analysis': {
           'estimated_ms': 150,
           'actual_ms': 148,
           'savings_ms': 2
       },
       'metrics': {
           'conflicts_detected': 0,
           'gamma_coherence': 0.95
       }
   }
   ```

## Key Features

### 1. Rule-Based Routing (MVP)
- Simple complexity heuristics determine optimal component combination
- No learning required; works immediately after Phase 6
- Predictable and transparent

### 2. Transparency Metadata
- Every response includes Phase 7 routing information
- Users/developers see WHAT ran and WHY
- Estimated vs actual latency comparison
- Compute cost accounting

### 3. Learning-Ready Architecture
- `ExecutiveControllerWithLearning` class for future adaptive routing
- Framework for weekly route optimization from historical data
- ε-greedy exploration vs exploitation strategy (optional)

### 4. Performance Estimates
- SIMPLE: ~2-3x faster than full machinery
- MEDIUM: ~50% of full machinery cost
- COMPLEX: Full capability when needed

## Test Coverage

**File**: `test_phase7_executive_controller.py`

All 10 tests passing:
- [OK] SIMPLE routing correct
- [OK] MEDIUM routing correct
- [OK] COMPLEX routing correct
- [OK] Transparency metadata correct
- [OK] Routing statistics tracked
- [OK] Component activation counts correct
- [OK] Learning router works
- [OK] Compute cost ranking correct
- [OK] Latency ranking correct
- [OK] ComponentDecision serializable

## Expected Impact

### Immediate (MVP Deployment)
- **Latency improvement**: 50-70% reduction on SIMPLE queries
- **Compute savings**: Estimated 40-50% for typical mixed workload
- **Quality preservation**: No degradation on COMPLEX queries
- **User experience**: Fast answers feel snappier; transparent routing builds trust

### Short-term (1-2 weeks)
- Real latency benchmarking against baseline
- Correctness evaluation to confirm no quality loss
- User feedback on response transparency

### Medium-term (Learning Version)
- Historical data analysis to refine routes further
- Per-domain routing optimization
- Meta-learning on component combinations

## Phase 7 vs. Phase 6

| Aspect | Phase 6 | Phase 7 |
|--------|---------|---------|
| **Scope** | Semantic tension, specialization, pre-flight | Component routing, executive control |
| **Problem Solved** | Over-activation on simple queries | System overhead, lack of decision intelligence |
| **Key Innovation** | Continuous conflict strength (ξ) | Intelligent component gating |
| **Complexity** | SIMPLE, MEDIUM, COMPLEX classification | Adaptive routing based on classification |
| **User Impact** | Better reasoning quality | Better latency + transparency |
| **Testing** | Phase 6 architectural validation | Phase 7 routing validation |

## Implementation Notes

### Current Status
- ✅ `executive_controller.py` created (357 lines)
- ✅ `codette_forge_bridge.py` modified for Phase 7 integration
- ✅ 10/10 tests passing
- ✅ Response metadata includes phase7_routing
- ⏳ Not yet tested against actual ForgeEngine (Phase 6 dependency)

### What's Different from Phase 6
Phase 6 enhanced *how we reason* (semantic tension, specialization).
Phase 7 enhances *whether we reason* (selective component activation).

This is governance of capabilities, not new capabilities.

### Design Principle: "Right-sized Reasoning"
- A factual question shouldn't trigger a 3-round philosophical debate
- A philosophical question shouldn't settle for direct lookup
- The system chooses the right tool for the right problem

## Future Directions

### Phase 7B: Learning Router
- Integrate with `living_memory` for historical analysis
- Weekly route optimization from correctness data
- Per-domain routing specialization

### Phase 8: Meta-Learning
- Learn which Phase 1-6 component combinations work best
- Automatic discovery of optimal component sets
- Federated learning across multiple Codette instances

### Phase 9+: Adaptive Governance
- Real-time adjustment of routing based on success/failure
- User preference learning ("I prefer fast over deep")
- Domain-specific routing strategies

## Files Modified/Created

### NEW
- `reasoning_forge/executive_controller.py` (357 lines)
- `test_phase7_executive_controller.py` (268 lines)

### MODIFIED
- `inference/codette_forge_bridge.py` (added Phase 7 integration, routing logic)

### UNCHANGED (but ready for Phase 7)
- All Phase 1-6 components (backward compatible)
- Query Classifier (used in routing decisions)
- ForgeEngine (components conditionally activated)

## Running Phase 7

### Automatic (Production)
Phase 7 auto-initializes in `codette_forge_bridge.py`:
```python
self.executive_controller = ExecutiveController(verbose=verbose)
# Automatically routes all queries through Phase 7
```

### Manual Testing
```bash
python test_phase7_executive_controller.py
# All 10 tests should pass
```

### Integration Validation
Phase 7 will be tested in conjunction with Phase 6:
1. Run existing Phase 6 benchmarks with Phase 7 enabled
2. Measure latency improvement (50-70% on SIMPLE expected)
3. Verify correctness preserved on MEDIUM/COMPLEX
4. Collect transparency metadata for analysis

## Next Steps

**Immediate (Next Session)**:
1. Test Phase 7 integration with actual ForgeEngine
2. Run Phase 6 evaluation suite with Phase 7 enabled
3. Measure real-world latency improvements
4. Deploy MVP to production (codette_web.bat)

**Short-term (1-2 weeks)**:
5. Create comprehensive latency benchmarks
6. Evaluate correctness preservation
7. Gather user feedback on transparency
8. Consider Phase 7B (learning router)

**Decision Point**:
- If MVP shows 50%+ compute savings with no quality loss → green light for learning version
- If users value transparency → expand Phase 7 metadata
- If domain-specific patterns emerge → build specialized routers

---

**Codette Principle**: "Be like water—individuality with responsibility"

Phase 7 brings discipline to Codette's awesome power. Powerful systems need governors.