# Findings & Decisions

## Requirements
- User asked to thoroughly read the project and introduce its current state to make future work easier.
- Follow-up request: implement recommended items 1-4 (`.gitignore`/data tracking, dependency manifest, smoke verification, XNet2d shape test) and skip item 5 (SSL Trainer).

## Research Findings
- Repository root: `/home/kekezack/workspace/X_SSL_Net`.
- Git branch: `feat_ssl_us_skeleton`.
- Dirty files at start: `configs/segmentation/train_sup_us_template.yaml`, `configs/segmentation/us_exp_sup_busi.yaml`, `configs/segmentation/us_exp_sup_busi_ablation.yaml`, `lib/modules/xnet_2d.py`, `lib/trainers/supervised.py`, plus untracked `lib/modules/xnet_2d_zh.py`.
- Main top-level files/directories identified: `README.md`, `configs/segmentation`, `tools`, `lib/modules`, `lib/trainers`, `lib/tools`, vendored `lib/SwinTransformer`, vendored `lib/sam2`.
- No `AGENTS.md`, `CLAUDE.md`, or `GEMINI.md` found in parent tree during initial scan.
- `lib/data/` exists locally and implements dataset indexing/loading/splitting, but `git status --ignored lib/data` reports it as ignored (`!! lib/data/`) and `git ls-files lib/data` returns nothing.
- Supported dataset builders in local `lib/data`: `BUS-UCLM`, `TG3K`, `TN3K`, `OTU_2d`, `BUSI`, `BUS-BRA`, `BUS_UC`, `CCAUI`, `DDTI`.
- BUSI and several datasets require generated project split files under `<dataset_root>/splits/project/train.txt` and `val.txt`; script is `scripts/generate_project_split.py`.
- Main training command path: `tools/train.py --config configs/segmentation/optimized/*.yaml`, or `tools/run_optimized_supervised.sh` which prepares splits then invokes training.
- Main trainer registry currently has one trainer: `supervised_segmentation`.
- Main model is `XNet2d`: encoder with local/wavelet/VMamba global branches, plain U-Net decoder skip fusion, FFT frequency refinement, and segmentation head returning `seg_logits`.
- Loss and metrics depend on MONAI. Model depends on PyTorch, `ptwt`, `timm`, and VMamba-related code; image loading depends on Pillow.
- Current environment import check: `yaml` available, but `torch`, `monai`, `ptwt`, `timm`, `triton`, `PIL`, and `swanlab` are missing.
- No project root dependency manifest found (`requirements.txt`/`pyproject.toml` absent); dependency references only exist in vendored/reference directories.
- Project tests are effectively absent; only `ref/SAM2-UNet/test.py` found under ignored reference code.
- `python -m py_compile` passed for key local files including trainer, model, loss/metrics, and data loader.
- `.gitignore` currently ignores `ref/`, `tmp/`, `data/`, outputs/logs, `.codex`, and also `.gitignore`; local diff adds `docs/`.
- `.gitignore` was updated so root `/data/` remains ignored but `lib/data/` is no longer ignored and appears as `?? lib/data/`.
- Added root `requirements.txt` for the main training stack.
- Added `tests/test_xnet_2d.py` for XNet2d segmentation output shape.
- `xnet_mamba` conda environment has core training dependencies (`torch`, `monai`, `ptwt`, `timm`, `triton`, `PIL`) but lacks `pytest` and `swanlab`.
- BUSI project splits exist and load successfully: train 624, val 156.
- CPU full-model forward is currently blocked by VMamba/csm_triton CPU path: `cross_scan_fn` enters `torch.cuda.device(x.device)` even when `ssm_backend="torch"`.
- CUDA smoke training passed on BUSI with 64x64 images, small model, 1 epoch, no validation/checkpoint/SwanLab: 312 train steps, final average total/seg loss about 0.84585.

## Technical Decisions
| Decision | Rationale |
|----------|-----------|
| Do not modify project code during audit | User requested reading/status, not implementation |

## Issues Encountered
| Issue | Resolution |
|-------|------------|
| Cannot run model/training in current environment | Missing core ML dependencies; limited verification to static reading and `py_compile` |
| Training depends on ignored `lib/data/` package | Treat as repository state risk; mention in handoff |
| CPU full XNet2d/Trainer smoke fails due to VMamba global branch CUDA wrapper | Recorded as model backend limitation; verified full smoke on available CUDA GPU |

## Resources
- `README.md`
- `tools/train.py`
- `lib/trainers/supervised.py`
- `lib/modules/xnet_2d.py`
- `configs/segmentation/*.yaml`