PythagorasGoal/CLAUDE.md

# PythagorasGoal — Istruzioni per agenti

## Stato del progetto — v2.0.0 RESET (2026-06-19)

**LEGGERE PRIMA DI TUTTO.** Il progetto è stato resettato dopo aver scoperto che l'intera
libreria di strategie "validata OOS" (FADE, PAIRS, DIP01, TR01, ROT02, TSM01, XS01, SH01) era
**artefatto di uno storico contaminato** — print fantasma del feed Cerbero **testnet** + storico
**Binance/USDT**. Ri-testate sul feed reale, tutte perdono ogni anno (vedi
`docs/diary/2026-06-19-deribit-history.md`, il documento di fondazione).

Cosa è cambiato:
- Lo storico è stato **ricostruito da Deribit mainnet** e **certificato**. Universo affidabile =
  **solo BTC/ETH** (tutti i TF). Gli alt sono esclusi (illiquidi/divergenti/non certificabili).
- Tutto il codice vecchio (strategie, stack live, ~100 script di ricerca/gate, dati non
  certificati, 60+ diari) è **archiviato in `Old/`** (preservato in git, non cancellato).
- ~~L'esecuzione è DISABILITATA, il conto mainnet è flat. Non c'è trading live attivo.~~
  **AGGIORNATO 2026-06-20: l'esecuzione di TP01 è ARMATA e LIVE su Deribit mainnet** —
  `config/live.json` `execution_enabled=true` + cron giornaliero `live_execute.py --execute`
  (cablato in `scripts/cron_daily.sh`). Guardrail: cap **$300 notional/asset**, min order $5,
  **disaster-SL on-book −30%**, alert Telegram su esecuzione/errori. **Capitale reale ≈ $600**
  (NON i €2000 nominali del paper trader). Stato corrente: **flat** (target TSMOM risk-off →
  BTC/ETH 0.0x, nessun ordine). Solo TP01 è eseguito; XS01/VRP01 restano paper/STAT-MODE.
- Si riparte dalla ricerca di strategie NUOVE, su dati certi, con la metodologia qui sotto.

### Ricerca post-reset (2026-06-19) — esito

Prima ondata di ricerca onesta su BTC/ETH certificati (5 track, harness condiviso
`src/backtest/harness.py`). Sintesi in `docs/diary/2026-06-19-research-synthesis.md`.

- **TP01 Trend Portfolio — strategia DIFENSIVA robusta (non alpha)** —
  `src/strategies/trend_portfolio.py`. TSMOM multi-orizzonte (1-3-6 mesi) vol-targeted, long-flat,
  50/50 BTC+ETH. Config canonica **PORT LF1d** (**>=12h, 1d raccomandato**, vol-target 20%, leva cap 2x):
  **FULL Sharpe ~1.30, maxDD ~14%; HOLD-OUT 2025-26 Sharpe ~0.31 / +3.5%** mentre il buy&hold 50/50
  faceva −39%/DD60%. Verificata indipendentemente col gauntlet onesto (hold-out + cross-asset +
  plateau + deflated-Sharpe 0.999): **regge**. **Valore = taglio del drawdown ~6× vs buy&hold**, NON
  generazione di ritorno (CAGR ~16% vs ~48% del buy&hold sul toro).
  ⚠️ **LOOK-AHEAD (2026-06-19):** un ffill MIXED-TIMEFRAME su barre open-labeled gonfiava il 4h
  (~1.60 → reale ~1.1). Il calcolo per-singolo-TF è leak-free, ma **NON scendere sotto le 12h**:
  costi+overfitting dominano senza vantaggio (FULL Sh piatto ~1.3 da 12h a 4h; hold-out migliore a 1d).
  Deploy/paper a **1d**. Diari `2026-06-19-tp01-verification.md` / `-tp01-lookahead-fix-lf.md`.
  Paper trader: `scripts/live/paper_trend.py` (1d). Test: `tests/test_trend_portfolio.py`.
  Ri-verifica: `scripts/analysis/{verify_tp01,stress_tp01,tp01_lowfreq}.py`.
- **XS01 Cross-Sectional Momentum (Hyperliquid) — DIVERSIFICATORE che migliora il portafoglio** —
  `src/portfolio/sleeves.py:_xsec_returns`. Market-neutral su **19 alt liquidi major** Hyperliquid (1d,
  dal 2024): ogni 10g long i 5 più forti / short i 5 più deboli, vol-target 20%. **Scorrelato a TP01
  (~−0.12).** Affinato (2026-06-19): **(a) blend di lookback [30,90]** (z-score cross-sectional mediato,
  come il multi-orizzonte di TP01); **(b) gate di dispersione p30** (entra solo se la dispersione
  cross-section del momentum supera il percentile espandente causale, altrimenti flat — XS è rumore in
  regime compatto). Standalone FULL Sh **1.50** / HOLD 1.71 / DD 11%, plateau robusto (lookback, gate
  p15-35). **Caveat:** storia ~2.5 anni; STAT-MODE (book a 19 gambe non eseguibile a 2k, serve ~20k) →
  monitor forward. NB il gate concentra XS nei regimi dispersi (2025-26 = hold-out alta-dispersione).
  Ricerca `scripts/portfolio/{xsec_research,xsec_blend,xsec_dispgate}.py`. Diari `2026-06-19-hyperliquid-xsec`
  / `-xsec-blend` / `-xsec-dispgate` / `-xsec-universe-expansion` / `-trend-multiasset`.
- **PORTAFOGLIO ATTIVO = TP01 (41.25%) + XS01 (18.75%) + VRP01 (15%) + SKH01 (25%)** (`src/portfolio/sleeves.active_sleeves`):
  TP01+XS01 combinato **FULL Sharpe 1.55, HOLD-OUT 1.55, DD 4.4%**. Aggiunto **VRP01** (options
  short-vol, sotto): TP01+VRP01 da solo fa FULL Sh 1.30→1.44 / HOLD 0.31→0.40 a peso 20% (3-way da
  validare locale con dati HL). **Aggiunto SKH01-V2-DD @25% effettivo (2026-06-23, sotto):** i tre
  preesistenti scalati nel restante 0.75 (rapporto 55:25:20). Il portafoglio a **4 sleeve** fa
  **FULL Sharpe 1.68→2.13, HOLD-OUT 1.63→2.30, DD full 14.3%→7.8%** (Skyhook è quasi-ortogonale,
  corr ~0.09). Report `scripts/portfolio/run_portfolio.py`. Sleeve a date d'inizio
  diverse → outer-join con pesi rinormalizzati (TP01/SKH01 dal 2019, VRP dal 2021, XS dal 2024).
- **SKH01-V2-DD "Skyhook" — DIVERSIFICATORE quasi-ortogonale (research)** — `src/strategies/skyhook.SKH01_V2_DD`,
  sleeve `src/portfolio/sleeves._skyhook_returns`. Sistema dual-TF (segnale 690m / exec 230m) regime
  (BuzVola/BuzVolume tipo-Chande) AND pattern (Donchian breakout), NON trend-follower, L/S. Vincitrice
  di 2 onde multi-agente (la 2ª = DD-reduction): exit a **percentuale fissa ASIMMETRICA** (long sl4%/tp10%,
  short sl2%/tp8% più stretto) → standalone **maxDD BTC 21% / ETH 27% (<30%)**, minFull +0.99, minHold
  +1.26, causale (0/400), fee-surviving 0.40%RT. Marginal vs TP01 **ADDS** (corr 0.09, has_insample_edge,
  robust_oos multicut 7/7, is_hedge=False); blend 0.75·TP01+0.25·SKH **hold-out 0.31→1.17**. Verificato
  leak-free + 2 scettici. **CAVEAT:** equity daily-step (Sharpe lens), ETH DD margine sottile, book 230m
  (costi ribilanciamento da verificare a deploy) → research win, forward-monitor. Diario `2026-06-23-skyhook.md`.
- **VRP01 Options Short-Vol — DIVERSIFICATORE da FinanceOld/OptionsAgent** — `src/portfolio/sleeves._vrp_combo_returns`.
  Put credit spread settimanale (vendi put -0.28, compra put -0.10) gated su IV-rank. Idee portate da
  `../FinanceOld/OptionsAgent` (Bear Call Spread + gate d'ingresso). Migliora il lead VRP nudo
  (options_vrp_lab): **(a) defined-risk** taglia la coda (worst-week -16.6%→-7.4%, DD 33%→14%);
  **(b) gate IV-rank>0.30** = vendi vol solo ricca → ribalta HOLD-OUT da -0.25 a +0.28 (l'alpha è il
  filtro di regime). Standalone **FULL Sh 1.10, HOLD 0.60, DD 12%**, positivo/piatto ogni anno (2022
  crash incluso). Scorrelato a TP01 (~+0.01-0.07). **CAVEAT:** premio MODELLATO su DVOL ATM (skew non
  esplicito), book a 1d, f di stress reale non catturato → LEAD robusto, non deploy pieno. Ricerca
  `scripts/research/options_vrp_v2.py` (vs baseline `options_vrp_lab.py`). Test `tests/test_vrp_sleeve.py`.
  Diario `2026-06-20-financeold-analysis-vrp-v2.md`.
- **Universo Hyperliquid: ESPANDERLO NON aiuta XS01** (provato): 52-asset / top-liquidità dinamico /
  trend-multi-asset → tutti peggiori (small-cap/memecoin diluiscono il momentum relativo; il trend
  multi-asset è ridondante con TP01, corr 0.74). I margini su XS sono nella STRUTTURA DEL SEGNALE
  (blend + gate), non nel numero di asset. I **51** parquet certificati restano per ricerca futura.
  ⚠️ Il test "52-asset = negativo" era in parte inquinato dal backfill sintetico (AXS 83%, ALGO/SAND
  37% di barre vol=0) poi rimosso — vedi correzione estrazione 2026-06-20 sotto; resta comunque vero
  che il long-tail diluisce XS01, ma il numero netto post-fix è 51.
- **Lead OPZIONI VRP (income short-vol) — quantificato, NON deploy** — `scripts/research/options_vrp_*.py`.
  Vendita put settimanali che incassa il volatility risk premium (IV>RV), scorrelato al trend (~0.07).
  Premio prezzato BS su DVOL reale (`fetch_dvol.py`) + calibrato su quote REALI cerbero-bite mainnet
  (`options_vrp_calibrate.py`): **f reale ≈ 1.0** (non 1.29) → Sharpe ~0.71, DD 33%, coda severa
  (settimane −15..−26% su LUNA/FTX). Diversificatore DEBOLE a premio reale, e short-vol da modello.
  **Regola: niente short-vol da modello in deploy.** Rivalutare quando cerbero-bite cattura un crash
  (per il f di stress reale). Diari `2026-06-19-options-vrp-lab` / `-eval-crypto-backtest-options`.
- **Edge deboli/scartati:** ML walk-forward BTC (Sh ~0.57), trend 1h L/S (~1.0), RV ETH/BTC (Sh 0.27,
  regime-luck), calendar/seasonality (buy&hold travestito), volume/vol e momentum-reversal (negativi).
- **MORTO/confermato artefatto:** mean-reversion / fade (negativo anche a fee zero — la vecchia
  libreria +201%/+1238% era contaminazione); trend 5m/15m (fee).
- **Soffitto strutturale BTC/ETH-direzionale ~1.3** superato SOLO espandendo a un meccanismo diverso:
  cross-sectional su universo Hyperliquid certificato (XS01) → portafoglio Sharpe ~1.55.
- **Sweep "strategie alternative" (2026-06-20) — 104 ipotesi / 153 agenti / NIENTE di nuovo regge.**
  Ricerca onesta a largo spettro su BTC/ETH+DVOL (harness condiviso vettoriale leak-free
  `scripts/research/alt/altlib.py`, 104 script in `scripts/research/alt/runs/`): 11 famiglie
  (breakout, trend non-TSMOM, mean-rev gated, DVOL/vol, cross-asset pairs, stagionalità, overlay
  rischio, opzioni modellate, microstruttura, ML walk-forward, combo). 16 promettenti, **1 sola**
  sopravvissuta alla verifica avversariale (3 scettici) e comunque NON deployabile. Conferma forte
  del soffitto ~1.3: ogni PASS era hold-out-fitting o **TP01/TSMOM travestito** (trend-beta del
  toro). Unico LEAD: **STA05** (EWMA-cross ensemble, **long-short**) — leak-free, plateau, corr
  hold-out **0.53** a TP01, il blend 0.75·TP01+0.25·STA05 alza l'hold-out 0.31→0.59 (full 1.30→1.24,
  DD 14→16%); MA hold-out corto (536g) → **forward-monitor, non sleeve.** Lezione harness: valutare
  lo Sharpe **MARGINALE vs baseline TP01** (non assoluto) + esigere plateau e jackknife
  drop-one-month sull'hold-out prima di PASS (hanno ucciso 13/14 falsi positivi). Diario
  `2026-06-20-alt-strategies-100agent-sweep.md`.
- **MARGINAL SCORER (implementato 2026-06-20)** — la lezione "Sharpe marginale, non assoluto" è
  ora codice in `scripts/research/alt/altlib.py`: `study_marginal(name, target_fn)` valuta un
  candidato direzionale BTC/ETH **sia** in assoluto **sia** rispetto al baseline `tp01_baseline_daily()`
  (corr, uplift del blend OOS, beta+alpha residua) e ritorna `earns_slot = (abs!=FAIL) AND
  (marginal==ADDS)`. **Regola: una nuova strategia direzionale si giudica su `earns_slot`, non sullo
  Sharpe assoluto** (gli overlay-su-TSMOM ereditano lo Sharpe di trend e prendono PASS fasulli —
  es. CMB04 PASS assoluto → NEUTRAL marginale). Demo `marginal_demo.py`, test `tests/test_marginal_scorer.py`.
  ⚠️ **INDURITO 2026-06-21 (onda ortho):** la versione fisso-HOLDOUT + jackknife-mese era
  ingannabile — 17/18 book relative-value "ADDS" su una sola finestra 2025 (ETH-bleed dove TP01 è
  debole). Tre gate nuovi in `marginal_vs_tp01`: **(1) persistenza multi-cut** (uplift positivo a più
  date di taglio, non solo 2025); **(2) edge in-sample** (`has_insample_edge`: lo Sharpe standalone
  PRE-holdout dev'essere ≥0.5 — un low-corr a Sharpe ~0.3 "aggiunge" solo matematica di
  diversificazione, riportata via `null_pctl_*` vs un asset-rumore a corr-zero); **(3) hedge vs
  alpha** (`is_hedge`: un low-corr che paga SOLO quando TP01 è debole — `corr(Sharpe-TP01, uplift
  annuo)` molto negativa — è un hedge, non alpha). Verdetti nuovi: HEDGE, NOISE. Sull'onda ortho lo
  scorer indurito collassa 17/18 → **1** (`dvol_spread`, unico con edge in-sample reale; comunque
  forward-monitor per multiple-testing/storia DVOL corta). Lezione: un nuovo sleeve si giudica su
  edge-in-sample + persistenza multi-cut + non-hedge, non sull'uplift di una finestra fortunata.
- **HARNESS REALISM (codificato 2026-06-21, onda intraday)** — due gate nuovi in `altlib.py`,
  test `tests/test_harness_realism.py`:
  - **`day_boundary_robust(target_fn, tf)`** — un effetto ora/sessione/giorno il cui uplift
    marginale **si inverte** spostando il confine del giorno UTC di poche ore è un **artefatto di
    etichettatura calendario** (ha ucciso `open_drive`: +0.23 a 00:00 → −0.33 a +8h → ARTIFACT-RISK).
    Un segnale di prezzo è INVARIANT (spread 0); un effetto calendario vero è ROBUST (resta positivo;
    es. `prevday_range_breakout`). **Regola: ogni segnale calendar/session/hour passa questo test
    prima di crederci.**
  - **`eval_weights_smallcap(df, target, capital=600, min_order=5)`** — a ~$600 un ribilanciamento
    di nozionale < min_order **non si esegue**; la fee proporzionale che `eval_weights` applica a
    migliaia di micro-trade sub-dollaro (tipici di un overlay vol-target) è **finzione**. Salta i
    sub-min_order e riporta lo **Sharpe haircut** reale vs modellato. **Vale per OGNI sleeve a questo
    capitale, TP01 incluso** — lo Sharpe netto onesto a $600 è quello small-cap, non quello modellato.
- **Onestà sul target €50/giorno:** NON raggiungibile su 2000 in 1-2 anni (servono ~130k di
  capitale o un DD da rovina). La leva non è la scorciatoia; la via è target-vol + capitale +
  tempo. La strategia che *guadagna* esiste, ma a ~+€1.5/giorno su 2000.

Script ricerca: `scripts/research/track{A,B,C,D,E}_*.py` + `trackD_timing.py`.

## Obiettivo

Ricerca: riconoscimento pattern frattali per trading algoritmico su crypto. Target dichiarato
€50/giorno partendo da €1.000. **Onestà prima di tutto**: nessun numero va creduto finché non è
netto fee, out-of-sample, robusto su griglia, e su dati certificati + liquidi + eseguibili.

## Stack

- **Linguaggio:** Python 3.11+ — **Package manager:** uv (`pyproject.toml`, `uv.lock`)
- **Dati:** Parquet in `data/raw/` (gitignored). Solo BTC/ETH (5m/15m/1h).
- **Analisi/ML:** numpy, pandas, scipy, scikit-learn
- **Fonte dati storici:** Deribit mainnet via `ccxt` (pubblico, tokenless)

## Struttura (post-reset)

```
src/data/downloader.py     → load_data(asset, tf): legge i parquet certificati da data/raw/
src/strategies/base.py     → Strategy (ABC), Signal, BacktestResult, YearlyStats
src/strategies/indicators.py → indicatori condivisi (ema, atr, keltner, ...)
src/strategies/trend_portfolio.py → TP01: strategia DIFENSIVA robusta (PORT LF1d, >=12h), causale
src/portfolio/             → PORTAFOGLIO DI STRATEGIE estensibile (Sleeve + StrategyPortfolio)
  portfolio.py             → combina N sleeve per peso su griglia giornaliera; metriche FULL/hold-out/anno
  sleeves.py               → REGISTRY sleeve attivi: TP01 (55%) + XS01 (25%) + VRP01 (20%). Aggiungere = una riga
src/fractal/               → indicatori frattali (patterns.py, indicators.py, similarity.py)
src/backtest/engine.py     → engine di backtesting riusabile
src/backtest/harness.py    → harness ONESTO (load BTC/ETH, backtest_signals no-leakage, OOS)
src/version.py             → APP_VERSION (legge il file VERSION)
scripts/research/          → ricerca: track{A-I}_*.py + options_vrp_*.py + fetch_dvol.py
scripts/portfolio/         → run_portfolio.py (report) + xsec_*.py (ricerca/affinamento XS01)
scripts/live/paper_trend.py → paper trader forward-only di TP01 (1d) (no esecuzione reale)
scripts/analysis/          → SOLO i tool dati certificati:
  rebuild_history.py        → (ri)costruisce lo storico da Deribit mainnet (base 5m + resample)
  certify_feed.py           → certifica il feed (integrità, coerenza resample, spike, cross-venue)
  audit_feed.py             → audit per-barra vs riferimento esterno
  multi_source_check.py     → cross-check multi-venue (quale venue è "vero")
data/raw/                  → btc/eth × {5m,15m,1h} (gitignored). UNICO dato attivo.
data/instruments_registry.json → registry strumenti (reference)
docs/diary/                → diario di ricerca (1 voce: il reset; aggiungere dopo ogni esperimento)
Old/                       → ARCHIVIO: tutto il vecchio (strategie, live, ricerca, dati, diari)
VERSION                    → semver (2.0.0)
```

## Comandi

```bash
uv sync                                                       # installa dipendenze
uv run python scripts/analysis/rebuild_history.py --asset BTC ETH   # (ri)costruisci storico da Deribit mainnet
uv run python scripts/analysis/certify_feed.py                # certifica i feed (locale + cross-venue)
uv run python scripts/analysis/certify_feed.py --local        # solo check locali (veloce)
uv run python scripts/research/trackD_trendport.py            # backtest strategia vincente (full report)
uv run python scripts/research/trackD_timing.py               # vincitrice su 15m/1h/4h/1d + PnL/DD/trade per anno
uv run python scripts/analysis/fetch_hyperliquid.py          # fetch+certify universo Hyperliquid (Cerbero mainnet) -> data/raw/hl_*
uv run python scripts/portfolio/xsec_research.py             # ricerca cross-sectional su Hyperliquid (XS01)
uv run python scripts/portfolio/run_portfolio.py             # report del PORTAFOGLIO attivo (TP01+XS01)
uv run python scripts/live/paper_trend.py                    # avanza il paper trader TP01 (forward-only, 1d)
uv run pytest                                                 # test
```

```python
from src.data.downloader import load_data
df = load_data("BTC", "1h")   # OK. load_data("SOL", ...) -> FileNotFoundError (guardrail: solo dati certi)
```

## IL DATO — fonte di verità (regola di prim'ordine)

- **La verità è Deribit mainnet**, perché è dove (in futuro) eseguiamo. Cross-check multi-venue:
  Deribit mainnet è a 0-1 bps dal consenso. **Binance NON è la verità** (è USDT, ~10 bps fuori, e
  sotto depeg USDT fino al 3% off) → usare Binance/Coinbase SOLO come audit indipendente, mai come
  ancora per "ripulire" i dati.
- **Aggiornare lo storico SOLO con `rebuild_history.py`** (ccxt Deribit mainnet, base 5m unica +
  resample → coerenza interna garantita). **MAI** il vecchio downloader Cerbero (token testnet =
  feed farlocco: è la causa della contaminazione).
- **Certificare sempre** dopo un rebuild con `certify_feed.py` (integrità OHLC, zero gap, coerenza
  resample maxΔ≈0, spike = solo crash reali, accordo cross-venue per-anno vs Coinbase USD).

### Universo ricercabile certificato
- **BTC / ETH**: puliti (2-6 bps vs Coinbase USD su tutta la storia), liquidi (~0% barre flat a 1h),
  storia lunga (2018/2019→oggi) → **ogni timeframe (5m/15m/1h)**. È l'unico dato in `data/raw`.
- **Alt Deribit (SOL/XRP/ADA/LTC/DOGE/BNB): FUORI.** Illiquidi (LTC 5m 82% barre flat, run ~3 giorni),
  divergenti, o non certificabili. Archiviati in `Old/data/raw`.
- **Universo Hyperliquid (Cerbero MCP MAINNET): 19 alt liquidi a 1d, dal 2024** — BTC/ETH/SOL/BNB/XRP/
  DOGE/AVAX/LINK/LTC/ADA/ARB/OP/SUI/APT/INJ/TIA/SEI/NEAR/AAVE. Certificati (`fetch_hyperliquid.py`):
  flat 0%, cross-venue 4-9 bps vs Binance, >1% ≈0% → `data/raw/hl_*_1d.parquet`. **Caveat:** storia
  nativa solo **~2.5 anni** (2024-2026; pre-2024 = backfill, vol 0). Abilita le strategie
  CROSS-SECTIONAL (impossibili a 2 asset). NB: Cerbero col token TESTNET = farlocco; col token
  **mainnet** (`.env.mainnet`) = reale, ma SEMPRE da certificare (cross-venue + liquidità).
  ⚠️ **CORREZIONE estrazione (2026-06-20):** il backfill NON è solo pre-2024 — cerbero MCP padda con
  barre SINTETICHE (volume 0, prezzi copiati da Binance → matchano cross-venue e non sono flat) ogni
  asset listato su HL **dopo** lo START. Il `flat`+cross-venue da soli non lo vedono: il rivelatore è
  il **VOLUME**. `fetch_hyperliquid.py` ora (1) taglia il run iniziale a volume 0, (2) scarta chi resta
  < 365g reali (es. **AXS 83% sintetico → fuori**), (3) gata i gap vol=0 interni. Universo certificato
  = **51** (era 52). I **19 major di XS01 hanno 0 backfill → invariati** (strategia live non toccata).
  Verificato direttamente su cerbero MCP. Diario `2026-06-20-cerbero-backfill-fix.md`.

## Metodologia obbligatoria per ogni nuova strategia

1. **Ingresso eseguibile**: direzione e prezzo decisi con dati **fino a `close[i]`**, mai
   `close[i-1]` con direzione presa da `i`; mai entry sull'estremo (high/low) di una candela.
2. **Backtest NETTO** dopo fee realistiche Deribit (**0.10% RT** taker; maker ~0%) + leva.
3. **Out-of-sample** held-out + robustezza su **griglia parametri** (entrambi gli asset, tutte le
   celle positive) + **sweep fee** (0.00-0.20% RT, margine ampio).
4. **Liquidità & plausibilità** (lezione v2.0.0): incrociare ogni edge con la liquidità reale del
   book (quota di barre flat) e con la plausibilità del prezzo (cross-venue). Un edge full+OOS
   robusto su un book fermo o su wick fantasma NON è un edge.
5. Strategia in `scripts/strategies/` (codice univoco), test in `tests/`, diario aggiornato.

## Lezioni critiche (da NON ripetere — la storia di questo progetto)

- **Feed contaminato → libreria fasulla (v2.0.0).** Print fantasma testnet + Binance/USDT hanno
  prodotto edge inesistenti (+201%/+1238%/+16492% "OOS"). Tutti spariti sul feed reale. Lezione: il
  dato viene prima della strategia; certificare sempre.
- **Look-ahead squeeze (storico).** L'intera famiglia squeeze-breakout aveva accuratezze 76-82% che
  erano artefatto: decideva la direzione con la candela di breakout `i` ma entrava a `close[i-1]`.
  Con ingresso onesto: lancio di moneta. (Dettagli nei diari in `Old/`.)
- **Entry sugli estremi di candela.** Strategie che entrano a `close` quando `close` è all'estremo
  del range (≤0.1% o ≥99.9%) gonfiano i ritorni in modo irrealistico (ETH 2024: +30.848% → +2.725%
  rimuovendoli). Spesso è un artefatto di dato o di entry non eseguibile.
- **Mean-reversion vs breakout.** Sui dati storici l'unica direzione che mostrava edge era la
  mean-reversion (i breakout rientrano) — MA anche quegli edge erano per lo più artefatto del feed:
  da riverificare da zero su dati certi.
- **Fee** = vincolo di prim'ordine. 0.10% RT baseline. Molte operazioni = morte per fee.
- **Leva**: testare 3x; 5x raddoppia il drawdown. I numeri a leva alta NON sono il caso base.
- **Data leakage** con rendimenti log: `returns[k] = log(close[k+1]/close[k])` usa `close[k+1]`. I
  feature devono fermarsi a `returns[i-2]` se il prezzo corrente è `close[i-1]`. Verificare SEMPRE.

## Convenzioni

- Strategie in `scripts/strategies/` con codice univoco; scartate documentate nel diario.
- Diario in `docs/diary/YYYY-MM-DD.md`, aggiornato dopo ogni esperimento significativo.
- **Nessun segreto nei commit** (token/chiavi). `.env` e `.env.mainnet` sono gitignored.
- Versionamento: `VERSION` (semver) + `scripts/bump_version.py`. `src/version.py` lo legge.

## Archivio `Old/`

Tutto il lavoro pre-reset (preservato in git per consultazione storica): strategie
(`Old/scripts/strategies`), stack live e portafogli (`Old/src/live`, `Old/src/portfolio`,
`Old/scripts/portfolios`), ricerca/gate (`Old/scripts/analysis`), dati non certificati
(`Old/data`), 60+ diari (`Old/docs/diary`), test (`Old/tests`). Consultabile come riferimento
("come facevamo X"), ma **nessun edge lì dentro è fidato** finché non è ri-validato su dati certi.
```