# Suite34 IP-MVCL Implementation Plan

> **For agentic workers:** Use superpowers:executing-plans; implement each task
> with contract tests, then perform one independent whole-package review.

**Goal:** Deliver the complete runnable DL experiment and sufficient single-log evidence.
**Architecture:** Canonical cache adapter → training-only preprocessing → full-input
MLP plus semantic views → matched fusion → chronological selection/refit → frozen
operating policies and comprehensive reporting.
**Tech stack:** Python 3.10+, NumPy, pandas, SciPy, scikit-learn, joblib, PyTorch.
**Spec:** ../../../DESIGN_FINAL.md and ../../../DESIGN_ORIGINAL.md.

## Global constraints

- Principal arms A0,A0M,A1,A2,P1; optional A3; defaults 29,129,229.
- Exact covered/finite historical sidecar alignment; full target support retained.
- F1–F5 development; F6/F7 retrospective; one final trained scoring model per cell.
- All tables printed in one log; no real-result claims from synthetic tests.
- No source-cache mutation. No external Git repository exists for this artifact.

## Review focus

- Missing rows/features and shuffled same-size sidecars fail loudly.
- Constant/all-missing features and small class support preserve fixed shapes.
- Partial resumes and changed source/configuration never silently mix runs.
- Retrospective labels cannot change development decision or F7 thresholds.
- Restricted runs remain pilots, with no full-population promotion.

### Task 1: Source, preprocessing and semantic views

Files: s34_data.py, s34_preprocessing.py, s34_views.py, s34_synthetic.py,
config/feature_views.json; tests/test_data.py, test_views.py, test_chronology.py.
Interfaces: Part(X,y,frame,row_index,reference), Cell(history,target,audit);
discover_population, inspect_population, load_cell, chronological_split;
Preprocessor.fit/transform with names and bundles; bind_manifest/randomize_manifest.
- [x] Write source alignment, chronology and information-bundle tests.
- [x] Run unittest, observe missing implementation failure.
- [x] Implement exact inspected source contract and explicit manifest catalog.
- [x] Run task tests: all pass, including invalid-mask/row-order cases.

### Task 2: Neural training, metrics and checkpoints

Files: s34_model.py, s34_metrics.py, s34_training.py, s34_checkpoint.py;
tests/test_model.py, test_metrics.py, test_training.py, test_checkpoint.py.
Interfaces: Model(input_dim,views,arm,config), forward(logit,details);
fit_predict(history,target,manifest,config,seed,emit);
cell_metrics, select_threshold, apply_policy, save/load/replay checkpoint.
- [x] Write matched-parameter, gradient, metric/tie, target-label-invariance tests.
- [x] Run tests RED; implement selection/refit and portable checkpoints.
- [x] Run tests GREEN; replay exact saved scores and deterministic seed.

### Task 3: Diagnostics, evaluation and reporting

Files: s34_diagnostics.py, s34_comparisons.py, s34_reporting.py;
tests/test_reporting.py.
Interfaces: diagnostics(model,preprocessor,part), summarize_metrics,
operational_tables, paired_contrasts, promotion_decision, render_report.
- [x] Write tests for macro averaging, frozen F6/F7 policies, no retro decision
  influence, cluster bootstrap and complete table printing.
- [x] Run RED, implement report tables and descriptive hypothesis conclusions.
- [x] Run GREEN; verify no identifiers in aggregate log.

### Task 4: Orchestration, packaging and acceptance

Files: train_suite34.py, run_suite34.sh, check_environment.py, requirements.txt,
README.md, PROTOCOL.md, config/default.json, tests/test_synthetic_e2e.py.
- [x] Write subprocess E2E tests for 2 faculties×7 folds×all principal arms,
  checkpoint replay, resume, mismatched signature and failure exit codes.
- [x] Run RED; implement preflight, atomic fragments, dev freeze, retro reporting.
- [x] Run entire unittest suite, syntax/import checks and launcher smoke.
- [x] Obtain independent code review; fix important findings with regressions.
- [x] Save sample complete synthetic report and validation evidence.
- [x] Build single-directory ZIP, validate integrity, save final deliverable.
