# Suite7 Shared Backbone + Faculty Adapter 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 a controlled cross-faculty Residual-MoE ablation that inserts zero-output-initialized faculty-specific bottleneck adapters between the Suite5 shared encoder and shared experts/router, then compares it fairly against Committee and Suite5.

**Architecture:** Preserve Suite5 shared initialization and training protocol. Add `h_f = h + A_f(h)` with one 128→16→128 adapter per faculty, normal down-projection initialization and zero up-projection initialization. Reuse Suite5 caches and exact feature schemas.

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

**Spec:** `docs/2026-08-25-suite7-shared-private-adapter-design.md`

## Global Constraints
- Reuse Suite5 canonical cache; do not retrain Committee models.
- Use exact Suite5 `common_raw_features` for each fold.
- Keep all Suite5 losses and operational evaluation unchanged.
- Instantiate Suite5-equivalent shared modules before adapters to preserve RNG-equivalent initialization.
- Default adapter bottleneck = 16, adapter scale = 1.0, zero-initialize only the up projection.
- No target holdout labels may influence model selection or threshold tuning.

---

### Task 1: Shared-private model and initialization invariants
**Files:**
- Create: `suite7_shared_private_moe.py`
- Test: `tests/test_suite7_model.py`

**Interfaces:**
- Produces: `FacultyAdapter`, `SharedPrivateResidualMoE`, `adapter_diagnostics`, `adapter_parameter_rows`.

- [ ] Write tests proving zero adapter output, exact Committee output at initialization, faculty-specific behavior, and Suite5 shared-parameter initialization equivalence.
- [ ] Run tests and confirm they fail because Suite7 model does not exist.
- [ ] Implement the minimal model and diagnostics.
- [ ] Run tests and confirm they pass.

### Task 2: Data/evaluation/reporting reuse
**Files:**
- Create: `suite7_common.py`, `suite7_eval.py`, `suite7_reporting.py`
- Test: `tests/test_suite7_reporting.py`

**Interfaces:**
- Consumes Suite5-compatible canonical cache files and Suite5 score/schema files.
- Produces aligned Suite5 shared scores and three-way comparison tables.

- [ ] Write tests for exact shared-frame alignment and Committee/Shared/Adapter comparison.
- [ ] Verify failure before implementation.
- [ ] Implement helpers by preserving Suite5 semantics.
- [ ] Verify tests pass.

### Task 3: Chronological all-faculty trainer
**Files:**
- Create: `train_suite7_shared_private_adapter.py`
- Test: `tests/test_suite7_smoke.py`

**Interfaces:**
- Consumes `--cache_dir`, `--shared_results_dir`, all-faculty fold caches.
- Produces per-fold checkpoints, scores, training history, adapter/router diagnostics, pooled/operational comparisons.

- [ ] Write a small synthetic smoke test that creates compatible canonical caches and Suite5 score/schema references.
- [ ] Verify it fails before trainer implementation.
- [ ] Implement training, validation, refit, prediction, metrics, diagnostics, and optional external reference merge.
- [ ] Verify smoke test and complete pytest suite pass.

### Task 4: Documentation and packaging
**Files:**
- Create: `README_suite7.txt`, `collect_reference_metrics.py`
- Copy compatibility dependencies: `train_v3.py`, `suite2_common.py`, `breakthrough_common.py`.

- [ ] Document the exact run command using existing Suite5 cache/results.
- [ ] Run Python compilation, CLI help, full pytest suite, and ZIP integrity verification.
- [ ] Package `/mnt/data/suite7` as `/mnt/data/suite7_shared_private_adapter.zip`.
