# Suite3 Composite 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 a self-contained Suite3 composite academic-warning experiment that combines stable committee probabilities, full-feature HGB meta learning, recent temporal HGBs, history-rich relational signal, and unsupervised rank-preserving score alignment.

**Architecture:** `suite3_common.py` owns calibration/fusion/evaluation utilities. `train_suite3.py` generates chronology-safe prequential component predictions, selects robust convex weights from historical transitions only, refits components on all allowed history, aligns target scores to committee scale without labels, and evaluates dev/holdout with frozen threshold and drift-aware warning budget. Existing `train_v3.py`, `breakthrough_common.py`, `exp_relational_fm.py`, and the relational helpers are copied unchanged into `suite3`.

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

## Global Constraints
- Target remains grade < 5.
- Base experts/hyperparameters remain unchanged.
- Dev folds 1-5, holdout folds 6-7 by default.
- No target labels may tune components, alignment, fusion weights, threshold, or warning budget.
- Alignment may use unlabeled target scores from the whole target temporal block.
- Relational contribution is restricted to `history_semesters >= 3`.
- History support is computed from strictly prior semesters.

---

### Task 1: Alignment and Fusion Utilities

**Files:**
- Create: `suite3/suite3_common.py`
- Test: `suite3/test_suite3.py`

**Interfaces:**
- Produces `quantile_align_to_reference(source, reference) -> np.ndarray`
- Produces `blockwise_quantile_align(source, reference, blocks) -> np.ndarray`
- Produces `apply_composite(q, a1, recent, relational, rich_mask, w_a1, w_recent, rel_alpha) -> np.ndarray`
- Produces `select_robust_weights(...) -> (dict, list[dict])`

- [ ] Write failing tests that verify monotonic/rank preservation, reference-distribution matching, block isolation, rich-only relational changes, convexity, and committee fallback.
- [ ] Run `pytest -q suite3/test_suite3.py` and confirm RED because `suite3_common` does not exist.
- [ ] Implement the minimal utilities.
- [ ] Re-run tests and confirm GREEN.

### Task 2: Chronological Component Generation

**Files:**
- Create: `suite3/train_suite3.py`
- Test: `suite3/test_suite3.py`

**Interfaces:**
- Produces prequential predictions for committee, all-history HGB, last6 HGB, last4 HGB, and hybrid relational expert.
- Produces aligned versions for each historical transition block.

- [ ] Add failing tests for temporal window index selection and candidate weight grid constraints.
- [ ] Run focused tests and confirm RED.
- [ ] Implement component feature construction and prequential prediction helpers.
- [ ] Re-run focused tests and confirm GREEN.

### Task 3: Fold Training, Selection, Diagnostics

**Files:**
- Modify: `suite3/train_suite3.py`

**Interfaces:**
- `run_fold(args, fold, outdir)` returns actual labels and all counterfactual score variants.
- Writes per-fold scores, transition diagnostics, fusion grid, calibration diagnostics, correlations, history-regime metrics, and feature importance.

- [ ] Add a synthetic chronological CLI test that requires unseen students/courses and three history-depth regimes.
- [ ] Verify the CLI test fails before fold orchestration exists.
- [ ] Implement production refits, target block alignment, fusion selection, relational gating, and all diagnostics.
- [ ] Verify the synthetic CLI run succeeds and all expected CSVs exist.

### Task 4: Frozen Development Decision Policy

**Files:**
- Modify: `suite3/train_suite3.py`

**Interfaces:**
- Tune F2 threshold/warning ratio on pooled development final predictions only.
- Print/save fixed-threshold and drift-aware metrics/confusion matrices for every fold and pooled holdout.

- [ ] Add a test that holdout evaluation reuses the supplied frozen threshold and warning ratio without recalibration.
- [ ] Confirm RED.
- [ ] Implement decision-policy evaluation using canonical `train_v3.py` helpers.
- [ ] Confirm GREEN.

### Task 5: Packaging and Verification

**Files:**
- Create: `suite3/run_suite3.sh`
- Create: `suite3/README_suite3.txt`
- Create: `suite3/make_synthetic_suite3_data.py`

- [ ] Compile every Python file.
- [ ] Run full pytest suite.
- [ ] Run a chronological synthetic dev→holdout smoke test through `train_suite3.py`.
- [ ] Verify base-expert parameter parity against canonical `train_v3.py`.
- [ ] Verify launcher shell syntax.
- [ ] Verify expected output artifacts and ZIP integrity.
- [ ] Package `/mnt/data/suite3_bundle.zip`.
