# Suite4 Specialist Research 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 five chronology-safe specialist experiments with one shared canonical committee cache and a one-command concurrent launcher.

**Architecture:** `prepare_suite4_cache.py` materializes immutable fold data and canonical committee OOF/production predictions. `suite4_common.py` provides shared metrics, block handling, feature construction, and diagnostic helpers. Five independent experiment scripts consume the cache and write isolated artifacts.

**Tech Stack:** Python, NumPy, pandas, scikit-learn, PyTorch; existing project train_v3/relational utilities.

## Global Constraints
- Do not change the canonical RF/ET/HGB committee.
- Holdout labels cannot influence training, selection, teacher construction, retrieval memory, or competence learning.
- All historical specialist features/predictions used for selection must be temporal-forward or OOF.
- Every nontrivial model must preserve committee fallback.
- All experiments must emit fold-level scores and diagnostics plus pooled summary CSVs.

### Task 1: Shared cache and common invariants
- [ ] Write failing tests for rescue targets/pairs, monotonic severity projection, competence weights, oracle corrections, and retrieval evidence.
- [ ] Implement `suite4_common.py` and `prepare_suite4_cache.py`.
- [ ] Run focused tests and compilation.

### Task 2: Failure-rescue ranker
- [ ] Add pair-construction tests and RankNet scoring smoke test.
- [ ] Implement `exp_1_failure_rescue.py` with prequential authority selection and rescue diagnostics.
- [ ] Run synthetic chronological smoke.

### Task 3: Council competence model
- [ ] Test row-wise weights and committee anchor behavior.
- [ ] Implement forward expert generation, regret targets, competence regressors, and diagnostics in `exp_2_competence_council.py`.
- [ ] Run synthetic chronological smoke.

### Task 4: Oracle distillation
- [ ] Test teacher correction clipping and no-target-teacher path.
- [ ] Implement historical block oracle teachers and stable/recent student regressors in `exp_3_oracle_distillation.py`.
- [ ] Run synthetic chronological smoke.

### Task 5: Dense severity specialist
- [ ] Test monotonic cumulative probabilities and ordinal feature derivation.
- [ ] Implement chronological severity OOF, production severity models, and meta-specialist in `exp_4_dense_severity.py`.
- [ ] Run synthetic chronological smoke.

### Task 6: Retrieval memory specialist
- [ ] Test retrieval evidence dimensions and prior-block-only memory behavior.
- [ ] Implement local memory features and HGB specialist in `exp_5_retrieval_memory.py`.
- [ ] Run synthetic chronological smoke.

### Task 7: Launcher, README, verification
- [ ] Implement `run_suite4.sh` and documentation.
- [ ] Run complete test suite, Python compilation, base-committee hash/parity check, five CLI smokes, launcher syntax check, artifact checks, and ZIP integrity.
