From a2414cf4c98f5d7365c525f1daed7532b5913497 Mon Sep 17 00:00:00 2001
From: mathias <mathias.bergqvist@gmail.com>
Date: Wed, 27 May 2026 21:56:28 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20write=20PROJECT.md=20=E2=80=94=20resear?=
 =?UTF-8?q?ch=20conventions,=20hypothesis,=20agent=20instructions?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .context/PROJECT.md | 77 ++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 72 insertions(+), 5 deletions(-)

diff --git a/.context/PROJECT.md b/.context/PROJECT.md
index 7779a58..c713104 100644
--- a/.context/PROJECT.md
+++ b/.context/PROJECT.md
@@ -1,13 +1,80 @@
-# hostexecutor
+# jepa-fx-risk
 
 ## Identity
 
-- **Name**: hostexecutor
+- **Name**: jepa-fx-risk
 - **Owner**: Mathias
-- **Client**: personal
-- **Repo**: gitea.d-ma.be/mathias/hostexecutor
+- **Client**: personal / research
+- **Repo**: gitea.d-ma.be/mathias/jepa-fx-risk
 - **Status**: active
+- **Brain wing**: `jepa-fx` (`wiki/jepa-fx/`)
+
+## Purpose
+
+Research project. Not a product. The "user" is future-self and research readers. Success is a reproducible, publishable result — not deployment.
 
 ## Stack
 
-Go + Templ + HTMX + CDN Tailwind. See `~/dev/.context/AGENT.md` for cross-project conventions.
+- **Primary language**: Go 1.24+ (pipeline, eval harness, CLI, experiment runner)
+- **ML layer**: Python 3.12 + PyTorch (TS-JEPA training loop only — isolated in `model/`)
+- **Build**: Task (Taskfile.yml)
+- **Target infra**: koala (Arch + Blackwell GPU, training), iguana (Mac Studio M2, dev)
+- **MCP**: brain (knowledge), gitea (version control)
+
+## Research context
+
+**Primary hypothesis:**
+> JEPA embeddings trained on FX time-series will produce latent market-state representations structurally separable by regime without explicit labels, measurable by silhouette score > 0.35 on k-means clusters vs. realised-volatility regime labels, on held-out data including at least one structural break.
+
+**Current phase:** Phase 0 — SSL Feasibility Gate
+
+**Training cutoff:** 2023-01-01 (hard — never look at post-2023 data during development)
+
+**Out of scope:** options pricing, directional alpha, live/paper trading, exotic pairs (Phases 1–3)
+
+**Brain wing for prior decisions and failure modes:** `brain_query wing=jepa-fx`
+
+## Conventions
+
+### Scientific discipline
+- Every experiment has a spec in `specs/` before any code runs
+- Hypotheses are falsifiable and have quantitative acceptance criteria
+- Null results are recorded and published — not discarded
+- Training cutoff is sacred — post-2023 data never informs any design decision
+- Results reported with baselines; no cherry-picking
+
+### Code style
+- Go: `gofumpt`, `golangci-lint` with project config; table-driven tests; `testify`
+- Errors: `fmt.Errorf("context: %w", err)` — no naked returns
+- Python: `ruff` for lint; type hints throughout; `pytest` for tests
+- No Jupyter notebooks for anything reproducible — notebooks are EDA scratch only
+
+### Git
+- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `experiment:`, `result:`
+- Branch: `feat/`, `experiment/phase-N-description`, `fix/`
+- Every experiment run gets a git tag: `exp/YYYYMMDD-short-description`
+- PRs: one concern per PR; description explains *why* not *what*
+
+### Experiment discipline
+- One spec per phase in `specs/` — written before any implementation
+- Each run recorded in `experiments/YYYYMMDD-HHMMSS-description/`
+- Metric summaries committed to `results/summaries/` — large outputs gitignored
+- `task check` must pass before any commit
+
+### Security / data
+- No raw FX data committed (gitignored) — see `data/README.md` for reproducible download
+- No API keys or tokens in code — env vars only
+- Training data and results stay local — nothing to cloud unless explicitly decided
+
+## Agent instructions
+
+When acting as a coding agent on this project:
+
+1. Read this file and all `SKILL.md` files in `.skills/` before starting work
+2. Run `brain_query wing=jepa-fx` to load current decisions and failure modes
+3. Run `task check` before every commit (lint + vet + test)
+4. Check `DECISIONS.md` before making any architecture or methodology choice
+5. Every experiment needs a spec in `specs/` — no specless experiments
+6. Never touch post-2023 data during development; it is sealed
+7. Record null results honestly — do not iterate until metrics pass without noting it
+8. When adding a Python dependency, justify it; prefer pure Go alternatives