# Suite21 — Committee-Anchored Guarded Temporal Residual

Suite21 is the final experiment in the current semester-Transformer framework. It keeps the strongest existing tabular Committee as an exact identity anchor and asks whether explicit ordered-semester history can add **complementary** predictive evidence without recreating Suite20's calibration and false-negative problems.

## Install location

Extract this folder to:

```text
/root/disk_3tb/earlywarning/30072026/suite21_guarded_temporal_residual
```

The default inputs are the same existing caches used by Suites 13–20:

```text
/root/disk_3tb/earlywarning/30072026/results/cross_faculty_residual_moe/cache
/root/disk_3tb/earlywarning/30072026/results/suite12_structured_cache
```

No new raw-database preprocessing is required.

## Run

```bash
cd /root/disk_3tb/earlywarning/30072026/suite21_guarded_temporal_residual
chmod +x run_suite21.sh
./run_suite21.sh
```

Results:

```text
/root/disk_3tb/earlywarning/30072026/results/suite21_guarded_temporal_residual
```

Log:

```text
/root/disk_3tb/earlywarning/30072026/log/suite21_guarded_temporal_residual.log
```

`run_suite21.sh` first validates the canonical and structured cache contract, then runs F1–F7.

## Models trained per fold

- `suite21_flat_residual`
- `suite21_temporal_residual`
- `suite21_guarded_temporal_residual` — primary

All three are anchored to the same Committee. The primary model cannot silently replace the Committee: chronological validation explicitly selects residual authority from a grid that includes exact identity (`alpha=0`).

## Key defaults

```text
d_model                 96
Transformer layers      2
heads                    4
ensemble residual heads 8
max epochs              10
minimum selection epochs 5
patience                 3
batch size              1024
samples / epoch          250000
learning rate            5e-4
pairwise ranking weight  0.05
alpha grid               0,.25,.50,.75,1
positive logit cap       1.50
negative logit cap       1.00
guard power              1.50
```

Training is faculty-balanced but **not class-balanced**. This is intentional to avoid Suite20's probability-prior distortion.

## Main outputs

### Core ranking results

```text
all_metrics.csv
all_fold_macro_summary.csv
holdout_macro_summary.csv
holdout_mean_by_faculty.csv
primary_holdout_head_to_head.csv
reference_coverage.csv
```

These compare Suite21 to Committee and every available previous suite with aligned score files, including Suite20, Suite18, Suite17, V2, and Council when present.

### Operational robustness / confusion matrices

```text
operational_policies_from_dev_f1_f5.csv
operational_holdout_metrics.csv
operational_holdout_decisions.csv
operational_holdout_macro_summary.csv
operational_pooled_confusions_by_faculty.csv
operational_overall_confusions.csv
```

F1–F5 select thresholds and warning ratios. F6/F7 are evaluation-only.

The package also contains `reference_council_13_faculties.csv`, parsed from the Council archive supplied for this project. It is used only as a clearly labeled historical 13-faculty reference (English is missing), separate from the row-aligned leaderboard.

The console prints pooled F6/F7 confusion matrices for IT for:

- Suite21 primary,
- Committee,
- Suite18,
- Suite20 Transformer,
- V2,
- Council,

whenever corresponding aligned scores exist.

### Mechanism diagnostics

```text
all_committee_retention_diagnostics.csv
all_residual_authority_diagnostics.csv
all_attention_diagnostics.csv
all_uncertainty_diagnostics.csv
all_history_perturbation_diagnostics.csv
selected_epochs_and_authority.csv
```

These answer:

- how closely Suite21 preserves Committee ranking;
- how much residual authority was selected;
- whether corrections increase or decrease failure risk;
- whether failures are still suppressed by historical evidence;
- whether reverse/zero history damages performance;
- which semesters receive target-conditioned attention;
- whether ensemble disagreement concentrates difficult rows.

## Important interpretation rule

The Committee is not just another baseline here. It is the **identity model** inside Suite21. If validation does not support temporal corrections, `alpha=0` returns exactly the Committee.

Therefore a Suite21 result close to Committee with many `alpha=0` selections means the temporal residual failed to generalize sufficiently. A result above Committee means the longitudinal evidence genuinely earned authority on historical future blocks and transferred to F6/F7.

See `DESIGN.md` for the frozen hypothesis and acceptance criteria.
