# Suite29 v3 — launcher and reporting refinement

Audited against actual `run_suite24.sh`, `run_suite25.sh`, `run_suite26.sh`,
`run_suite28.sh` in the supplied source archives.

## Changes

1. **Persistent logs:** `run_suite29.sh` logs under `$AQ_ROOT/log/` using a stable
   `suite29_enrollment_set.log` and a timestamped per-run log, with `tee`,
   `pipefail`, run metadata, and explicit success/failure markers.
2. **Canonical results:** full outputs default to
   `$AQ_ROOT/results/suite29_enrollment_set/`. Smoke runs should override
   `--output-dir .../results/suite29_smoke`.
3. **Runnable defaults:** plain `bash run_suite29.sh` runs all seven folds,
   all faculties, self-only + set, seeds 29/129/229, 18 epochs, and saves checkpoints.
   Explicit CLI flags can override the defaults.
4. **Preflight:** validates Python dependencies, device availability, input cache
   directories, expected fold/faculty joblib filenames, and output write access.
   Actual `.joblib` content is validated during model training.
5. **Run diagnostics:** adds per-fold observed enrollment-set profiles, multiple
   failure-group share, expanded per-faculty AP/AUC/precision/recall/F2/Brier/ECE
   printing, student-semester expected/observed count comparison, and faculty/size
   attention allocation in the console.
6. **Final research summary:** new `suite29_report.py` prints and saves
   macro-by-fold, retrospective F6/F7, matched AP delta, win/loss, faculty
   stability, attention, group errors, historical completeness, and bootstrap.
7. **Regression tests:** adds preflight and offline-reporting tests.
8. **Performance:** CPU thread count defaults to four (override OMP_NUM_THREADS
   and MKL_NUM_THREADS), avoiding pathological oversubscription on tiny batches.

## Unchanged

- Same course encoder, one masked attention block, individual per-course sigmoid.
- Same self-only, cross-course set, and no-peer intervention definitions.
- Same chronological fold selection, training/refit and loss functions.
- No new data-derived feature and no target-semester label ever enters attention.

## Validation scope

The package has locally executed structural tests and a complete **synthetic**
canonical/structured cache run, including launcher, two models, reports and
checkpoints. No full AQ server cache was supplied for a real 14-faculty run.
