.context/PROJECT.md

@@ -1,13 +1,104 @@
-# hostexecutor
+# jepa-fx-risk
 
 ## Identity
 
-- **Name**: hostexecutor
+- **Name**: jepa-fx-risk
 - **Owner**: Mathias
-- **Client**: personal
+- **Client**: personal research
-- **Repo**: gitea.d-ma.be/mathias/hostexecutor
+- **Repo**: gitea.d-ma.be/mathias/jepa-fx-risk
-- **Status**: active
+- **Status**: active — Phase 0
+
+## Purpose
+
+Research project: apply JEPA-based self-supervised representation learning to
+FX risk management for a corporate bank with an internal global FX trading desk.
+
+Primary tasks: FX volatility forecasting and VaR/CVaR estimation.
+Target output: internal PoC for the trading desk.
+
+## Architecture decision (see DECISIONS.md ADR-001)
+
+**TS-JEPA + SIGReg** — TS-JEPA temporal patchwise architecture (Ennadir et al.,
+arXiv:2509.25449) with EMA replaced by Sketched Isotropic Gaussian Regularization
+(SIGReg, Balestriero & LeCun, arXiv:2511.08544). Single search axis: λ ∈ [0.01, 1.0].
+
+Phase 2 hypothesis: MTS-JEPA multi-resolution objective (arXiv:2602.04643).
 
 ## Stack
 
-Go + Templ + HTMX + CDN Tailwind. See `~/dev/.context/AGENT.md` for cross-project conventions.
+**Go** (`src/`): data pipeline (DUKASCopy fetch + hourly processing), evaluation
+harness (silhouette, linear probe R², collapse diagnostic, Kupiec/Christoffersen),
+results dashboard (Templ + HTMX + CDN Tailwind).
+
+**Python** (`model/`): all training and embedding export only. PyTorch cu130
+(Blackwell sm_120 compatible). No evaluation logic in Python.
+
+**Infra**: koala (Arch Linux, Blackwell GPU 12 GB VRAM) for training.
+iguana (Mac Studio M2 Ultra) + LiteLLM on piguard for autoresearch agent LLM.
+
+## Repository layout
+
+```
+jepa-fx-risk/
+├── src/                    # Go — data pipeline + eval harness + dashboard
+│   ├── data/               # DUKASCopy fetch, hourly processing, validation
+│   └── eval/               # silhouette, linear probe, collapse, backtest
+├── model/                  # Python — training only
+│   ├── train.py            # TS-JEPA + SIGReg backbone (autoresearch edits this)
+│   ├── prepare.py          # LOCKED — data loading, tokenization, export
+│   └── requirements.txt
+├── specs/                  # Research specs (one per phase/experiment type)
+├── experiments/            # Per-run outputs: embeddings, metrics.json, git tag
+├── results/summaries/      # Human-readable outcome per experiment
+├── program.md              # Autoresearch agenda — researcher edits this
+├── DECISIONS.md            # Architecture Decision Records
+└── Taskfile.yml            # task data:fetch, task experiment:run, task eval:*
+```
+
+## Phase structure
+
+- **Phase 0** (current): MAE baseline on EUR/USD hourly 2008–2022.
+  Gate: silhouette > 0.20, MAE > PCA, ±10% over 3 reruns.
+- **Phase 1**: TS-JEPA + SIGReg autoresearch sweep, 50 experiments.
+  Gate: val_vol_r2 > GARCH baseline AND Kupiec p > 0.05.
+- **Phase 2**: MTS-JEPA multi-resolution hypothesis.
+- **Phase 3**: Internal bank tick/position data (future, out of current scope).
+
+## Data
+
+DUKASCopy hourly OHLCV, 10 G10 pairs, 2008–2022 train / 2023 val / 2024 test.
+Features: log-return, log rolling-20-period HV, VIX (daily interpolated).
+Weekend gaps handled explicitly. See ADR-002.
+
+## Key conventions
+
+- `prepare.py` is LOCKED — never modified by agents or autoresearch
+- Evaluation metrics are always computed by the Go harness, never in Python
+- Every experiment gets a git tag: `exp/YYYYMMDD-description`
+- Null results are recorded explicitly in `results/summaries/` — do not iterate silently
+- `program.md` is the only file the researcher edits to steer autoresearch
+- CI runs `task check` (lint + vet + test) only — no GPU, no training
+
+## Evaluation metrics
+
+Primary (autoresearch optimizes): `val_vol_r2` — linear probe R² on 1-day
+realized volatility from frozen embeddings, computed by Go harness.
+
+Secondary (logged, not optimized): Kupiec p-value (VaR 99% backtest on EUR/USD).
+Must co-move with val_vol_r2 — checked from experiment 1.
+
+Diagnostics: silhouette score (regime clustering), PC1/HV correlation (collapse check).
+
+## Benchmarks to beat (trading desk comparison)
+
+- GARCH(1,1) — volatility forecasting baseline
+- Historical Simulation VaR (250-day rolling) — Basel default
+- EWMA RiskMetrics (λ=0.94)
+
+## Agent guidance
+
+Read `DECISIONS.md` before making architecture suggestions.
+Do not modify `prepare.py` or `src/eval/`.
+Do not suggest changing the Python/Go separation.
+Training runs are always manual via `task experiment:run` — never triggered by CI.
+When implementing, follow Go conventions in `.skills/go-patterns/SKILL.md`.