---
name: oral-microbiome-transfer-auditor
description: Execute the locked, offline oral microbiome transfer-readiness auditor for saliva-based periodontitis, including public-recovery freeze building, cross-cohort evaluation, cohort-shift diagnostics, baseline recommendation, and supporting benchmark artifacts.
allowed-tools: Bash(uv *, python *, python3 *, curl *, ls *, test *, shasum *, unzip *)
requires_python: "3.12.x"
package_manager: uv
repo_root: .
canonical_output_dir: outputs/canonical
---

# Oral Microbiome Transfer Auditor

This skill executes the audit-first transfer-readiness workflow exactly as frozen by the repository contract. It does not invent cohorts, corrected inputs, unverifiable benchmark rows, or fake sample labels.

## Runtime Expectations

- Platform: CPU-only
- Python: `3.12.x`
- Package manager: `uv`
- Offline after the freeze bundle exists locally
- Canonical freeze directory: `data/benchmark/freeze`
- Paper PDF build requires `tectonic`

## Scope Rules

- Saliva only in v1
- Adult samples only when age is available
- `periodontitis` vs `control` only
- `EPheClass` `PD_s` is the canonical abundance backbone
- Canonical v1 is ASV-first
- No corrected or batch-effect-removed table in the scored path
- Blind cohorts are excluded from thresholding, feature selection, hyperparameter selection, confounder-margin tuning, and durable feature-core distillation

## Step 1: Build Or Confirm The Public-Recovery Raw Bundle

The freeze builder will create these raw assets from the public `PD_s` backbone if they are absent:

- `data/benchmark/raw/epheclass_pd_s_abundance.tsv`
- `data/benchmark/raw/recovered_metadata.tsv`
- `data/benchmark/raw/recovered_taxonomy.tsv`

The source provenance and reconstruction rules are documented in `data/refs/source_provenance.md`.

## Step 2: Install The Locked Environment

```bash
uv sync --frozen
```

## Step 3: Build The Frozen Benchmark

```bash
uv run --frozen --no-sync oral-microbiome-benchmark build-freeze --config config/canonical_periodontitis.yaml --out data/benchmark/freeze
```

## Step 4: Run The Canonical Auditor

```bash
uv run --frozen --no-sync oral-microbiome-benchmark run --config config/canonical_periodontitis.yaml --out outputs/canonical
```

The primary outputs are now the audit verdict, model recommendation, and cohort-shift diagnostics. Legacy benchmark metrics remain as supporting evidence.

## Step 5: Verify The Canonical Run

```bash
uv run --frozen --no-sync oral-microbiome-benchmark verify --config config/canonical_periodontitis.yaml --run-dir outputs/canonical
```

## Step 6: Optional Triage

Triage v1 is evaluative only and requires a labeled external cohort:

```bash
uv run --frozen --no-sync oral-microbiome-benchmark triage --config config/canonical_periodontitis.yaml --input inputs/new_cohort.tsv --metadata inputs/new_metadata.tsv --out outputs/triage
```

## Step 7: Freeze The Submission Bundle

```bash
uv run --frozen --no-sync python scripts/prepare_submission_bundle.py --config config/canonical_periodontitis.yaml --run-dir outputs/canonical
```

This snapshots the verified run into `submission/freeze/source_canonical/`, writes paper-facing tables and figures into `submission/results/`, and regenerates `paper/generated/`.

## Step 8: Build The Paper PDF

```bash
uv run --frozen --no-sync python scripts/build_paper_pdf.py --config config/canonical_periodontitis.yaml
```

If `tectonic` is missing, install it with your local package manager first and then rerun Step 8.

## Optional Step 9: Clean-Room Replication

```bash
uv run --frozen --no-sync python scripts/create_mini_venv.py --force
uv run --frozen --no-sync python scripts/run_replication_check.py --profile smoke --venv-dir .venv-mini
uv run --frozen --no-sync python scripts/run_replication_check.py --profile full --venv-dir .venv-mini
```

The smoke profile uses fixture data and checks the end-to-end contract quickly. The full profile reproduces the canonical freeze, run, verify, submission bundle, paper build, and snapshot comparison from local assets only.

## How To Interpret Verdicts

- `transfer_ready`: the retained panel supports a non-baseline transfer claim.
- `baseline_only_recommended`: the panel is usable, but the safer recommendation is the abundance baseline.
- `sparse_transfer_unreliable`: the panel does not support trustworthy sparse tuning.
- `insufficient_mixed_cohorts`: too few mixed cohorts remain for canonical transfer scoring.
- `unrecoverable_labels`: label provenance fails.
- `shifted_candidate`: one or more retained primary cohorts are materially shifted.

## Canonical Success Criteria

The canonical scored path is successful only if:

- the freeze builder completes without dropping below the blind-panel requirement
- the canonical run completes successfully
- the verifier exits `0`
- all required outputs are present and nonempty
- the verifier reports `passed`
- the audit bundle contains a top-level verdict and recommended model
- if taxonomy is absent, the run still passes honestly with `signature_only` marked `unavailable_missing_taxonomy`
- the submission bundle and paper can be rebuilt from the frozen canonical snapshot without manual edits