# Suite13 Committee-Preserving Collaborative Evidence MoE Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Build Suite13 by preserving Suite12's heterogeneous collaboration while implementing the five approved corrections identified by the Suite12 postmortem.

**Architecture:** Reuse Suite12 structured evidence/cache and E1-E4 encoders. Replace the lossy E0 with direct Committee evidence plus a zero-initialized bounded global correction, change epoch selection to faculty-robust Committee-relative metrics, protect E0 with low-LR parameter groups and preservation losses, add mechanism-specific auxiliary heads/targets, and provide faculty/semester context only to the gate.

**Tech Stack:** Python 3, PyTorch, numpy, pandas, scikit-learn, joblib.

**Spec:** `docs/superpowers/specs/2026-08-28-suite13-committee-preserving-collaborative-moe-design.md`

## Global Constraints
- Canonical expanding-fold/Suite5 cache remains authoritative for rows, labels and RF/ET/HGB OOF/target probabilities.
- Reuse Suite12 structured-cache schema v4; do not require raw-cache rebuild when compatible.
- Strict chronology: only structured evidence prior to target semester.
- No target labels in model inputs or gate context.
- Final prediction is direct collaborative fusion, never Committee + final residual and never score-mixing fallback.
- Same fair evaluator and holdout protocol as Suites7-12.

---

### Task 1: Committee-preserving E0 and gate context
**Files:** Create `suite13_models.py`, `suite13_data.py`, `suite13_pipeline.py`; Test `tests/test_suite13_core.py`.
**Interfaces:** Model forward consumes canonical `committee_probs` and separate `gate_context`; returns E0 correction and teacher reconstruction diagnostics.
- [ ] Write failing tests for exact initial E0=Committee, teacher-evidence availability, gate-only faculty/semester context, and final-head isolation.
- [ ] Run focused tests and verify RED.
- [ ] Implement minimal model/data/pipeline behavior.
- [ ] Run focused tests and verify GREEN.

### Task 2: Mechanism targets and objectives
**Files:** Modify `suite13_pipeline.py`, create `suite13_training.py`; Test `tests/test_suite13_core.py`.
**Interfaces:** `Suite13Bundle.mechanism_targets` has E1 prior-history risk summary, E2 historical course fail propensity, E3 y, and E4 mastery deficiency; E1/E2/E4 are evidence-derived and peer-label-free.
- [ ] Write failing tests for smoothing/grouping and chronology-safe E4 target.
- [ ] Verify RED.
- [ ] Implement targets, mechanism heads and phase losses with expert-specific direct weights.
- [ ] Verify GREEN.

### Task 3: Robust selection and protected joint optimizer
**Files:** Modify `suite13_training.py`, create `train_suite13_collaborative_evidence_moe.py`; Test `tests/test_suite13_core.py`.
**Interfaces:** `robust_committee_selection_stats()` returns score, med/mean AP delta, median F2 delta, win counts; Phase3 optimizer uses E0 LR scaling.
- [ ] Write failing tests for faculty-balanced score and phase3 LR parameter groups.
- [ ] Verify RED.
- [ ] Implement robust selection and optimizer groups.
- [ ] Verify GREEN.

### Task 4: Reporting and comparison
**Files:** Create `suite13_reporting.py`, modify train entrypoint.
**Interfaces:** Reads Suite12 score files plus prior references; writes fold/holdout/operational/diagnostic CSVs and prints E0 retention/mechanism/gate/ablation/attention audits.
- [ ] Add focused tests for Suite12 reference alignment and retention diagnostics.
- [ ] Verify RED.
- [ ] Implement reporting.
- [ ] Verify GREEN.

### Task 5: End-to-end smoke and package
**Files:** Create `run_suite13.sh`, `README.md`, update docs/tests.
**Interfaces:** Reuses `$RESULTS/suite12_structured_cache` by default and writes `$RESULTS/suite13_committee_preserving_collaborative_moe`.
- [ ] Run full unit tests.
- [ ] Run Python compile and shell syntax checks.
- [ ] Run synthetic expanding-fold four-phase CLI smoke including reporting.
- [ ] Run a real-schema structured-cache compatibility/materialization check.
- [ ] Package ZIP and verify `unzip -t`.
