# Suite26 MINT Implementation Plan

> For agentic workers: use the execution and review workflows task by task. Independent data and reporting modules can be implemented in parallel under the dispatching-parallel-agents skill. User has explicitly requested design and full implementation in this turn.

Goal: deliver a complete runnable tree–memory framework with history inside the trainable tree routing.

Architecture: a differentiable binary forest reads student history at internal nodes and predicts from its leaves. Conventional trees initialize trainable splits and leaves; a single objective jointly updates all components.

Tech stack: Python 3.10+, PyTorch 2.1+, NumPy, pandas, scikit-learn, joblib, standard unittest.

Spec: DESIGN.md in this package.

## Global constraints

- Separate output directory `suite26_joint_tree_memory`; primary column `suite26_mint`.
- No tree-score residual/calibration/blending in the forward model.
- Strict global temporal partitioning and earlier-semester history.
- All saved results identify initialization, configuration, data coverage, and reference alignment.
- Existing caches and original Suite26 package are read-only.

## Review focus

- Unequal faculty calendar coverage cannot leak future training labels into validation.
- Cold students/courses and entirely missing historical grades must predict finite values.
- Memory must affect internal routes and receive gradient from the final forest loss.
- Serialization must reproduce predictions including vocabulary/preprocessing.
- Missing or reordered legacy references must never silently align by label equality.

## Task 1: chronological data module

Files: mint_data.py, tests/test_data.py. Interfaces: exactly the Table/Prepared/Preprocessor/HistoryIndex/MemoryDataset APIs in DESIGN.md.
- [x] Write and run failing data-contract tests.
- [x] Implement canonical cache loading, full history, reconstruction audit, preprocessing, global split, and outcome-independent memory.
- [x] Verify positive and negative chronology tests and unseen-course behavior.

## Task 2: metrics and matched comparison module

Files: mint_metrics.py, tests/test_metrics.py. Interfaces: metrics/macro_ap/add_references/write_report in DESIGN.md.
- [x] Write and run failing keyed alignment, known confusion, threshold-selection, and paired macro-bootstrap tests.
- [x] Implement metrics, reference joins, paired reports and dev-only operational thresholds.
- [x] Verify single-model/partial-fold reports and absent references do not crash.

## Task 3: trainable forest and memory

Files: mint_seed.py, mint_model.py, tests/test_model.py.
- [x] Write and run failing hard seed equivalence, path mass, empty history, route sensitivity, and main-loss gradient tests.
- [x] Implement ExtraTrees-to-complete-tree initialization and forward routing.
- [x] Implement course/state memory encoders, node-conditioned attention, readiness deficits, conditional thresholds and trainable leaves.
- [x] Verify all tests plus state roundtrip, using real PyTorch CPU execution.

## Task 4: experiment orchestration

Files: train_suite26.py, run_suite26.sh, predict_suite26.py, make_synthetic_cache.py, tests/test_pipeline.py.
- [x] Write a failing end-to-end test using a small canonical-cache fixture.
- [x] Implement per-fold selection/refit, matched variants, interventions, gradient/routing diagnostics, atomic checkpoints, manifests and resume validation.
- [x] Implement preflight, CPU smoke entrypoint and checkpoint reload predictions.
- [x] Verify reports and checkpoint predictions; verify resume and configuration mismatch behavior.

## Task 5: review and delivery

Files: README.md, VALIDATION.md, requirements.txt, package ZIP.
- [x] Independently review architecture and temporal contracts against source.
- [x] Run the full unittest suite and an end-to-end synthetic run with all variants.
- [x] Check shell syntax, Python compilation, ZIP integrity and real-data path overrides.
- [x] Write honest validation evidence and run instructions; save final ZIP.

## Reviewed amendments

Default selection uses one latest historical semester, with explicit mixed-origin provenance for optional longer windows. Refit preserves selection examples per epoch below the cap. Reference names map explicitly to source score aliases. Balanced split discovery is followed by unweighted leaf counts. Downward float32 threshold conversion preserves branch decisions. The common feature schema spans all requested faculties/folds. See VALIDATION.md for executed evidence and limits.
