# Cross-Faculty Residual 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:** Implement the approved Committee-Anchored Cross-Faculty Joint Residual MoE, its chronology-safe all-faculty cache workflow, target-only ablation, operational evaluation, diagnostics, reference comparison, tests, launcher, and README inside `suite5/`.

**Architecture:** Reuse canonical per-faculty Suite5 caches as immutable Committee sources. Build fold-specific shared representations from common raw features, Committee meta features, support features, and faculty embeddings; jointly train bounded residual experts and a NULL-aware router; select epochs by macro-faculty forward validation; refit on all historical OOF rows; evaluate each target faculty independently and aggregate macro results.

**Tech Stack:** Python 3, NumPy, pandas, scikit-learn, PyTorch, joblib, pytest, Bash.

**Spec:** `docs/superpowers/specs/2026-08-23-cross-faculty-residual-moe-design.md`

## Global Constraints
- Keep the canonical RF/ET/HGB Committee read-only.
- Failure label is `target_grade10 < 5` as already encoded in canonical caches.
- Never use any target-fold label from any faculty during model fitting or epoch selection.
- Shared feature schema is the exact raw-feature-name intersection across participating faculties.
- Target-only ablations must use the same common raw-feature schema as the shared model.
- Production evaluation uses development folds 1-5 and holdout folds 6-7 by default.
- Print and save AP/AUC, F2@10/15/20/25, fixed-threshold metrics, drift-aware metrics, and confusion matrices.

---

### Task 1: Cross-faculty data and preprocessing utilities

**Files:**
- Create: `cross_faculty_common.py`
- Test: `tests/test_cross_faculty_residual_moe.py`

**Interfaces:**
- Produces faculty discovery, common-feature alignment, historical/target bundle construction, standardization, effective faculty/class sampling weights, metric helpers, and reference normalization.

- [ ] Write tests for common feature intersection/alignment, no-target-label historical construction, faculty-balanced class-aware weights, and macro metric aggregation.
- [ ] Run focused tests and verify failure before implementation.
- [ ] Implement the minimal utilities.
- [ ] Re-run focused tests.

### Task 2: Residual MoE model and losses

**Files:**
- Create: `cross_faculty_residual_moe.py`
- Test: `tests/test_cross_faculty_residual_moe.py`

**Interfaces:**
- Produces `ResidualMoE`, zero-residual Committee initialization, capability targets, joint loss, router diagnostics, and deterministic device/seed helpers.

- [ ] Write tests proving zero initialization reproduces q exactly, weights sum to one, residual bounds hold, and positive utility shifts router targets toward the useful expert.
- [ ] Run focused tests and verify failure.
- [ ] Implement model/loss functions.
- [ ] Re-run focused tests.

### Task 3: Chronological shared training and target prediction

**Files:**
- Create: `train_cross_faculty_residual_moe.py`
- Modify: `cross_faculty_common.py`
- Test: `tests/test_cross_faculty_residual_moe.py`

**Interfaces:**
- Consumes canonical cache directory and faculty list.
- Produces per-fold shared/optional target-only predictions, router/residual diagnostics, saved model state, fold metrics, and training history.

- [ ] Add synthetic-cache tests for temporal split, macro validation selection, target predictions, and target-only same-schema behavior.
- [ ] Verify tests fail.
- [ ] Implement training loop, early epoch selection, refit, prediction, and artifact writing.
- [ ] Run focused tests.

### Task 4: Operational and cross-faculty benchmark evaluation

**Files:**
- Create: `cross_faculty_eval.py`
- Test: `tests/test_cross_faculty_residual_moe.py`

**Interfaces:**
- Consumes fold prediction records.
- Produces per-faculty development-selected fixed/drift policies, V2-style confusion matrices, macro summaries, and standardized CSVs.

- [ ] Write tests for frozen development thresholding, prior-fold drift-rate logic, confusion matrices, and macro win-rate aggregation.
- [ ] Verify tests fail.
- [ ] Implement evaluation/reporting.
- [ ] Re-run tests.

### Task 5: Cache orchestration and launchers

**Files:**
- Create: `prepare_cross_faculty_cache.py`
- Create: `run_cross_faculty_residual_moe.sh`
- Modify: `README_suite5.txt`

**Interfaces:**
- Discovers all faculty split files, builds/reuses canonical caches for all requested folds, launches shared training/evaluation, supports optional faculty subset and target-only ablations.

- [ ] Add CLI smoke tests for `--help` and faculty discovery.
- [ ] Implement cache orchestration and launcher.
- [ ] Run shell syntax check and CLI help checks.

### Task 6: External V2/Council reference collection

**Files:**
- Create: `collect_reference_metrics.py`
- Modify: `cross_faculty_eval.py`
- Modify: `README_suite5.txt`
- Test: `tests/test_cross_faculty_residual_moe.py`

**Interfaces:**
- Parses V2-style and Council logs into standardized `faculty/model/split` metrics and merges optional references into the final comparison table.

- [ ] Write parser tests for original V2 and Council pooled HOLDOUT lines.
- [ ] Verify failure.
- [ ] Implement parser/merge.
- [ ] Re-run tests.

### Task 7: Full verification and bundle

**Files:**
- Create: `README_cross_faculty_residual_moe.txt`
- Create: `cross_faculty_residual_moe_bundle.zip`

- [ ] Run `python -m compileall` over new Python files.
- [ ] Run full `pytest -q` for Suite5 tests.
- [ ] Run synthetic end-to-end shared training smoke test on CPU.
- [ ] Run `bash -n run_cross_faculty_residual_moe.sh`.
- [ ] Build a self-contained ZIP including dependencies required by the launcher.
- [ ] Inspect archive contents and final file tree.
