# Repo Alignment Plan

## Current State

The repository is the `neurotwin` Python research package and CLI. It already contains the leakage-controlled Neural Translation infrastructure, prepared-manifest training and evaluation, claim gates, model cards, A100 handoff packaging, the legacy `NeuralStateSpaceTranslator`, the historical `NeuroTwinPairOperator`, and the experimental NFC implementation under `src/neurotwin/models/nfc/`.

The current branch is `ptlnextdoor/kahlus-v2-prs` at `cdc3ee9`, with a clean worktree at the start of this pass. The graph report identifies the core abstractions as the old translator, Pair-Operator, split/leakage machinery, prepared tasks, baseline runners, architecture registry, and the new NFC synthetic suite.

## Trusted

- Split manifests, event manifests, leakage audits, prepared-task generation, and claim gates are trusted infrastructure lanes.
- Synthetic and MOABB smoke paths are trusted as plumbing checks, not scientific evidence.
- A100 packaging and handoff scripts are trusted only when built from a clean committed HEAD and verified by checksums.
- The current claim boundary is trusted: no model-superiority, clinical, first-foundation-model, exact TRIBE, exact BrainVista, or fNIRS support claim is allowed.

## Not Trusted Yet

- NFC synthetic results are not scientific evidence.
- The NFC synthetic falsification gate is the immediate trust boundary before Algonauts/CNeuroMod or 6x A100 runs.
- The benchmark layer still needs scrutiny for over-broad labels, ablation thresholds, uncertainty calibration semantics, and whether the gate proves more than plumbing.
- Old short-step synthetic signals are invalidated as evidence after the corrected gate.
- fNIRS and TurboQuant/TurboVec are research notes or optional future infrastructure, not implemented model claims.

## Planned Changes

- Add/update the top-level NFC pivot project-state document.
- Add/update the NFC mathematical constitution and no-loss equation ledger.
- Add/update a code architecture map tying research concepts to files and claim boundaries.
- Add/update a master research-state dossier.
- Add fNIRS observation-operator notes as docs only.
- Add TurboQuant/TurboVec retrieval/audit notes as docs only.
- Tighten claim hygiene docs.
- Verify and, only if necessary, harden the NFC synthetic gate and A100 handoff strictness.

## Out of Scope

- No A100 jobs.
- No raw public neural data.
- No clinical, MDD, diagnostic, or treatment claims.
- No full fNIRS implementation.
- No TurboVec dependency or vendored retrieval stack.
- No deletion of old translator, Pair-Operator, MOABB, leakage, reporting, model-card, or packaging systems.
- No claim that NFC beats baselines unless the strict evidence gate actually passes.

## Validation Plan

- `git diff --check`
- `PYTHONPATH=src python3 -m unittest discover -s tests -v`
- `PYTHONPATH=src python3 -m neurotwin.cli doctor`
- `PYTHONPATH=src python3 -m neurotwin.cli eval --suite nfc_synthetic --out-dir /tmp/neurotwin_nfc_alignment_smoke --train-steps 1 --seed 0`
- `PYTHONPATH=src python3 -m neurotwin.cli eval --suite nfc_synthetic --out-dir /tmp/neurotwin_nfc_alignment_strict --train-steps 5 --seed 0 --require-pass || true`
- `bash scripts/run_smoke.sh /tmp/neurotwin_alignment_smoke`
- `graphify update .`
- Package only after validation and only from a clean committed HEAD if a commit is made.