# 🎯 Icarus Phase 7 — 'Cognition' Sprint

**Status:** Planned — Entry after Phase 6 UAT completion  
**Director:** Matt  
**Theme:** Cognitive layer, predictive intelligence, household optimization

---

## Pre-Entry Requirements

Before entering Phase 7, the following must be validated:

| Requirement | Owner | Criteria | Status |
|-------------|-------|----------|--------|
| Event Graph maturity | Socrates | 30 days stable operation, <1% data loss | ⏳ Phase 6 |
| Multi-user state sync | Socrates | Aundrea + Matt concurrent use, conflict-free | ⏳ Phase 6 |
| Phase 6 UAT complete | Matt | >90% document routing accuracy | ⏳ In Progress |
| LLM token efficiency review | Wadsworth | Local vs cloud cost analysis | ⏳ Phase 7 entry |

---

## Pillar 1: Hierarchical Briefing Model (HBM)

**Source:** `shared/project-docs/hbm-spec-v0.1.md` (deferred from Phase 6)  
**Owner:** Daedalus (UX), Socrates (backend), Wadsworth (scheduler)  

### Scope
Four-level household briefing system based on cognitive psychology research:
- **Month:** Pattern density heatmap (aggregation only)
- **Week:** Anchor events + commitment cards (aggregation only)
- **Day:** When/Then chains + forgetting budget (**Briefing Agent**)
- **Hour:** Full action scripts (**Briefing Agent**)

### Phase 7 Approach: Incremental
| Sprint | Deliverable | Risk |
|--------|-------------|------|
| 7.1 | Month + Week briefs (aggregation, no Agent) | Low |
| 7.2 | Day brief — When/Then chains | Medium (LLM cost) |
| 7.3 | Hour detail + Morning/evening notifications | Medium |
| 7.4 | Forgetting budget optimization | Low |

### LLM Cost Mitigation
- **Cache strategy:** DayBrief cached until Event Graph changes
- **Target:** >80% cache hit rate (most days = no LLM call)
- **Fallback:** Simplified extraction if Briefing Agent fails

### Sovereign Constraint
Daily Briefing Agent must support local execution (Gaming PC 3080 Ti):
- Primary: `phi4:14b` or `qwen2.5-coder:7b` for chain generation
- Fallback: Cloud (GLM-5.1) only if local fails
- Cost target: <$0.50/month via aggressive caching

---

## Pillar 2: LLM Token Efficiency Review

**Trigger:** HBM cost analysis requirement  
**Owner:** Wadsworth (analysis), Socrates (implementation)  
**Goal:** Minimize cloud LLM costs via local model optimization

### Analysis Scope

| System | Current | Target | Strategy |
|--------|---------|--------|----------|
| Document briefing (Icarus) | Cloud (qwen3-vl:8b) | Local (qwen3-vl:8b) | Gaming PC via Tailscale |
| Recipe extraction | Cloud (jina + LLM) | Local | Ollama phi4:14b |
| Newsletter parsing | Cloud (qwen2.5:7b) | Local | Gaming PC |
| HBM Day Brief | Cloud (GLM-5.1) | Local first | phi4:14b chain generation |
| Payment alerts | Cloud (LLM classify) | Local | Keyword + light LLM |

### Cost Modeling

```
Scenario A: All Cloud (Current)
- Document briefing: ~$0.01 × 30 docs = $0.30/day
- Newsletter parsing: ~$0.02 × 2 newsletters = $0.04/day
- HBM Day Brief: ~$0.04 × 1 = $0.04/day
- Monthly total: ~$11.40

Scenario B: Local-First (Target)
- Document briefing: Local (Tailscale to Gaming PC) = $0
- Newsletter parsing: Local = $0
- HBM Day Brief: Local (80% cache hit) = $0.01/day
- Monthly total: ~$0.30 (99% reduction)
```

### Implementation
1. **Benchmark local models** on Gaming PC (tokens/sec, quality)
2. **Hybrid pipeline** — try local first, fallback to cloud
3. **Token budgeting** — per-request limits, max daily spend
4. **Cache everything** — embeddings, generations, summaries

### Deliverables
- [ ] `shared/project-docs/llm-efficiency-analysis.md` — benchmark results
- [ ] `shared/api-specs/local-llm-routing.yaml` — hybrid pipeline spec
- [ ] Socrates: Gaming PC Ollama integration
- [ ] Wadsworth: Cost tracking dashboard

---

## Pillar 3: Multi-User State Synchronization

**Prerequisite for HBM**  
**Owner:** Socrates  

### Problem
Aundrea marks permission slip signed at 21:45. Matt's 22:00 brief must reflect this.

### Solution
Event Graph state versioning:
```yaml
Event:
  state_version: int           # increment on change
  state_last_updated: ISO8601
  state_updated_by: person_id   # aundrea | matt
  state_history: [StateChange]  # audit trail

StateChange:
  timestamp: ISO8601
  person: person_id
  field: string                 # e.g., "permission_slip"
  old_value: any
  new_value: any
```

### Sync Strategy
- **Optimistic updates** — local change immediately, sync to Event Graph async
- **Conflict resolution** — last-write-wins with notification of conflict
- **Offline support** — queue changes, sync when reconnected

### Deliverables
- [ ] State version tracking in Event Graph
- [ ] Conflict detection UI (Daedalus)
- [ ] Sync status indicator ("Synced 2 min ago")

---

## Pillar 4: Predictive Household Optimization

**Beyond HBM — intelligent suggestions**  
**Owner:** Socrates (ML), Wadsworth (routing), Daedalus (UX)  

### Features

| Feature | Input | Output | Example |
|---------|-------|--------|---------|
| Carpool suggestion | Event Graph + locations | Optimized pickup schedule | "Harper and neighbor both have OT Tuesday — carpool?" |
| Prep task bundling | Week's prep_tasks | Bundled errands | "3 permission slips need signing — batch tonight" |
| Conflict prediction | Pattern history | Likely double-bookings | "Friday 6pm historically overbooked" |
| Energy forecasting | FamilyState patterns | Cognitive load prediction | "Tuesday looks heavy — front-load Monday prep" |

### Technical Approach
- **No new ML infrastructure** — pattern matching on Event Graph
- **Heuristics first** — only add ML if heuristics insufficient
- **Local computation** — Gaming PC for any model inference

---

## Phase 7 Success Criteria

| Metric | Target | Measurement |
|--------|--------|-------------|
| HBM Week Brief | Ship 7.1 | Month + Week views live |
| HBM Day Brief | Ship 7.2 | When/Then chains working |
| LLM cost reduction | 90% vs Phase 6 | Monthly cloud spend |
| Cache hit rate | >80% | Briefing Agent invocations |
| Multi-user sync | Zero conflicts | State change log |
| Local LLM coverage | >80% of calls | Cloud fallback ratio |

---

## Dependencies from Phase 6

| Phase 6 Deliverable | Phase 7 Dependency |
|---------------------|-------------------|
| Event Graph (Icarus) | Required for HBM |
| IMAP IDLE ingress | Required for email-based state updates |
| Drop Zone share sheet | Nice-to-have for document → Event Graph |
| Finance Intelligence | Optional — expense tracking in HBM |
| Brain Query | Optional — natural language → Event Graph queries |

---

## Timeline Estimate

**Phase 7 Duration:** 4-6 weeks
- Week 1-2: Month + Week briefs (Sprint 7.1)
- Week 3-4: LLM efficiency review + local model integration
- Week 5-6: Day Brief with When/Then chains (Sprint 7.2)
- Week 7+: Hour detail, notifications, optimization

**Entry Criteria:** Phase 6 UAT complete + Event Graph 30-day stability

---

_The cognitive layer transforms data into actionable household intelligence._