docs: scaffolding decision memo + technical report Phase 1

Aggiunge i template per gate decision memo (sez. 4.4 spec) e technical report (sez. 4.5 spec). Da popolare con numeri reali a chiusura del run phase1-real-001 (in corso). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-10 11:21:26 +02:00
parent 370acb4893
commit 6a201c7e49
2 changed files with 391 additions and 0 deletions
@@ -0,0 +1,169 @@
+# Gate Phase 1 — Decision Memo
+
+**Data**: 10 maggio 2026
+**Run analizzati**: phase1-real-001 (in attesa di completamento; eventuali run successivi listati qui)
+**Spesa totale Phase 1**: $TBD di $700 cap (=TBD%)
+**Tempo speso Phase 1**: TBD settimane (calendar)
+**Status**: TEMPLATE — completare con numeri reali a fine run.
+
+---
+
+## 1. Premessa
+
+Questo memo formalizza la valutazione dei 5 hard gate definiti nello spec strategico (`docs/superpowers/specs/2026-05-09-decisione-strategica-design.md`, sez. 4.4) sulla base dei risultati della/e run reale/i. Segue la regola "mai self-approve": **author pass** seguito da **review pass adversarial** prima della decisione formale.
+
+I gate sono numerici per costruzione: PASS o FAIL è meccanico, non discrezionale. Discrezionale è solo l'azione successiva quando uno o più gate falliscono.
+
+---
+
+## 2. Author pass — valutazione hard gate
+
+### Gate 1 — Loop converge
+
+**Soglia**: la fitness mediana della popolazione cresce per ≥3 generazioni consecutive prima di plateau.
+
+**Misura osservata**:
+
+| Generazione | Median fitness | Variazione |
+|---|---|---|
+| 0 | TBD | — |
+| 1 | TBD | TBD |
+| 2 | TBD | TBD |
+| 3 | TBD | TBD |
+| 4 | TBD | TBD |
+| 5 | TBD | TBD |
+| 6 | TBD | TBD |
+| 7 | TBD | TBD |
+| 8 | TBD | TBD |
+| 9 | TBD | TBD |
+
+Numero di generazioni consecutive con crescita: **TBD**.
+
+**Esito**: PASS / FAIL
+
+**Razionale**: TBD.
+
+---
+
+### Gate 2 — Output formalizzabile
+
+**Soglia**: ≥80% delle proposte LLM passano il parser S-expression senza intervento manuale.
+
+**Misura osservata**:
+- Evaluations totali: TBD
+- Parse success: TBD (= TBD%)
+- Parse error: TBD
+
+Distribuzione errori più frequenti:
+- TBD
+
+**Esito**: PASS / FAIL
+
+**Razionale**: TBD.
+
+---
+
+### Gate 3 — Tail superiore
+
+**Soglia**: i top-5 genomi hanno DSR in-sample ≥ 1.5x la mediana di popolazione.
+
+**Misura osservata**:
+- Median DSR popolazione: TBD
+- Top-5 DSR: TBD, TBD, TBD, TBD, TBD
+- Top-5 mediano: TBD
+- Ratio (top-5 mediano / pop median): TBD
+
+**Esito**: PASS / FAIL
+
+**Razionale**: TBD.
+
+---
+
+### Gate 4 — Diversità non collassa
+
+**Soglia**: entropia della distribuzione di fitness in popolazione > 0.5 a fine run.
+
+**Misura osservata**:
+- Entropy generazione finale: TBD
+- Entropy iniziale (gen 0): TBD
+- Trend entropy: TBD
+
+**Esito**: PASS / FAIL
+
+**Razionale**: TBD.
+
+---
+
+### Gate 5 — Cost predictability
+
+**Soglia**: spesa effettiva entro ±30% della stima preventivata ($500-700 per Phase 1).
+
+**Misura osservata**:
+- Stima preventivo: $500-700 (mid $600)
+- Spesa reale: $TBD (somma `total_cost_usd` su tutti i run Phase 1)
+- Deviazione: TBD%
+
+**Esito**: PASS / FAIL
+
+**Razionale**: TBD.
+
+---
+
+## 3. Soft observations (informative, non vincolanti)
+
+- **Diversità cognitiva**: cognitive_style sopravvissuti a fine run: TBD su 6 originali.
+- **Top-5 ispezione qualitativa**: i top genomi propongono strategie strutturalmente diverse o sono cloni? TBD.
+- **Failure mode parser**: tassonomia degli errori parse dominanti (TBD).
+- **Cerbero/Deribit data quality**: gap nei dati storici, anomalie. TBD.
+
+---
+
+## 4. Author pass — conclusione
+
+**Esito complessivo author pass**: PASS / FAIL / PARTIAL
+
+Hard gate falliti (se presenti): TBD.
+
+**Decisione raccomandata dall'autore**:
+- [ ] GO Phase 2 (specificare aggiustamenti)
+- [ ] ITERATE Phase 1 (specificare cosa cambiare prima di un nuovo run)
+- [ ] PIVOT (specificare dominio o approach alternativo)
+- [ ] STOP (specificare razionale + learnings)
+
+**Razionale autore**: TBD.
+
+---
+
+## 5. Review pass — red team adversarial
+
+**Modalità review pass**: subagent Claude red-team / collega umano / fresh-eyes 48h. *(Selezionare e documentare).*
+
+**Critiche strutturate ricevute**:
+
+1. **Cherry-picking**: i numeri sopra sono stati cherry-picked? Quali run sono stati esclusi e perché? TBD.
+2. **Statistical robustness**: i gate basati su DSR usano `n_trials` corretto? Bonferroni applicato? TBD.
+3. **Overfitting al training**: c'è hold-out genuino o tutta la valutazione è in-sample? TBD.
+4. **Diversità apparente vs reale**: signal correlation fra top-5 misurata? Possono essere cloni che hanno solo prompt diversi? TBD.
+5. **Cost trap**: la spesa è entro budget ma vicina al cap? Estrapolando linearmente, Phase 2 sfora? TBD.
+
+**Contro-evidenze raccolte / fix applicati**:
+- TBD.
+
+---
+
+## 6. Decisione finale
+
+**Decisione**: [GO Phase 2 | ITERATE Phase 1 | PIVOT | STOP]
+
+**Razionale finale (post-review)**: TBD.
+
+**Aggiustamenti per la fase successiva**:
+- TBD.
+
+**Documenti correlati prodotti**:
+- `docs/reports/2026-05-10-phase1-technical-report.md` (report tecnico ~5 pagine)
+- `docs/runs/2026-05-10-phase1-real-001.md` (per ogni run, da creare se serve)
+
+---
+
+*Memo da committare insieme al report tecnico Phase 1. Versione 1.0 del template — popolare con dati reali a chiusura run.*
@@ -0,0 +1,222 @@
+# Phase 1 Lean Spike — Rapporto Tecnico
+
+**Autore**: Adriano Dal Pastro
+**Data**: 10 maggio 2026
+**Versione**: 1.0 (TEMPLATE — popolare con dati a chiusura run)
+**Status**: in attesa risultati run reale (`phase1-real-001` in corso)
+
+**Documenti correlati**:
+- `docs/superpowers/specs/2026-05-09-decisione-strategica-design.md` (decisione strategica)
+- `docs/superpowers/plans/2026-05-09-phase1-lean-spike.md` (piano implementativo)
+- `docs/decisions/2026-05-10-gate-phase1.md` (decision memo gate)
+
+---
+
+## 1. Setup sperimentale
+
+**Obiettivo della Phase 1 lean spike**: dimostrare che il loop tecnico funziona end-to-end. Non è una valutazione dell'edge alpha, è una validazione di fattibilità. I cinque hard gate dello spec sez. 4.4 misurano se il sistema gira come progettato e se l'output LLM è formalizzabile, non se le strategie generate sarebbero profittevoli.
+
+### 1.1 Configurazione del run
+
+| Parametro | Valore |
+|---|---|
+| Population size (K) | 20 |
+| Generazioni | 10 |
+| Elite k | 2 |
+| Tournament k | 3 |
+| Crossover probability | 0.5 |
+| Random seed | 42 |
+| Symbol | BTC-PERPETUAL (Deribit) |
+| Timeframe | 1h |
+| Range storico | 2024-01-01 → 2026-01-01 (2 anni) |
+| Fees backtest | 5 basis points |
+| n_trials_dsr | 50 |
+| Tier LLM dominante | C (qwen3-235b-a22b-2507 via OpenRouter) |
+| Cerbero MCP endpoint | http://localhost:9001 (locale) |
+
+### 1.2 Stack tecnologico
+
+Python 3.13, uv, pytest+pytest-mock+responses, sqlmodel/sqlite per persistence, sexpdata per parsing, pandas+numpy+scipy per analytics, openai SDK con base URL OpenRouter, tenacity per retry transient, streamlit+plotly per dashboard.
+
+### 1.3 Architettura del run
+
+L'orchestrator (`src/multi_swarm/orchestrator/run.py`) coordina la pipeline end-to-end: caricamento OHLCV via `CerberoOHLCVLoader` (cache parquet), costruzione market summary, popolazione iniziale di K=20 genomi diversificati per cognitive_style (6 stili: physicist, biologist, historian, meteorologist, ecologist, engineer), e per ogni generazione il loop hypothesis (LLM call, parse S-expression) → falsification (compile, backtest, DSR) → adversarial (heuristic checks) → fitness (DSR − dd_penalty * max_dd, kill su HIGH adversarial finding) → next_generation (elitism + tournament + crossover/mutation). Tutti gli stati sono persistiti su SQLite (`runs.db`) con indici su fitness desc per query rapide della dashboard.
+
+### 1.4 Caveat metodologici
+
+- **In-sample**: il backtest in Phase 1 lean spike non usa walk-forward; tutto il range 2024-2026 viene usato sia per la generazione delle ipotesi sia per la loro valutazione. La sopravvivenza out-of-sample è esplicitamente fuori scope di Phase 1 (gate Phase 2 #2).
+- **Compiler con indicatori built-in**: il compiler S-expression (`src/multi_swarm/protocol/compiler.py`) calcola RSI, SMA, ATR, MACD, realized_vol localmente con pandas. `CerberoTools` è plumbed ma non chiamato durante l'esecuzione delle strategie — è disponibile come tool per agenti future-tense ma il fitness in Phase 1 dipende solo dagli indicatori locali.
+- **Mock RSI epsilon**: il compiler ha un epsilon-floor su `roll_down` per evitare RSI = 100 esatto su serie monotonicamente crescenti (artefatto matematico irrilevante su dati reali ma documentato).
+
+---
+
+## 2. Loop convergence
+
+**Domanda gate 1**: la popolazione converge nel tempo?
+
+### 2.1 Fitness per generazione
+
+| Gen | Median | Max | P90 | Entropy |
+|---|---|---|---|---|
+| 0 | TBD | TBD | TBD | TBD |
+| 1 | TBD | TBD | TBD | TBD |
+| 2 | TBD | TBD | TBD | TBD |
+| 3 | TBD | TBD | TBD | TBD |
+| 4 | TBD | TBD | TBD | TBD |
+| 5 | TBD | TBD | TBD | TBD |
+| 6 | TBD | TBD | TBD | TBD |
+| 7 | TBD | TBD | TBD | TBD |
+| 8 | TBD | TBD | TBD | TBD |
+| 9 | TBD | TBD | TBD | TBD |
+
+### 2.2 Plot
+
+*(Inserire screenshot dashboard — pagina GA Convergence — `docs/reports/figures/phase1/ga-convergence.png`)*
+
+### 2.3 Osservazioni
+
+- Generazioni di crescita consecutiva mediana: TBD.
+- Plateau osservato a partire dalla generazione: TBD.
+- Entropy a fine run: TBD (gate threshold 0.5).
+
+---
+
+## 3. Top-5 genomi: ispezione qualitativa
+
+**Domanda gate 3**: il tail superiore della popolazione esiste e separa segnale da rumore?
+
+| Rank | Genome ID (short) | Fitness | DSR | Sharpe | Max DD | Trades | Cognitive style | Tier |
+|---|---|---|---|---|---|---|---|---|
+| 1 | TBD | TBD | TBD | TBD | TBD | TBD | TBD | TBD |
+| 2 | TBD | TBD | TBD | TBD | TBD | TBD | TBD | TBD |
+| 3 | TBD | TBD | TBD | TBD | TBD | TBD | TBD | TBD |
+| 4 | TBD | TBD | TBD | TBD | TBD | TBD | TBD | TBD |
+| 5 | TBD | TBD | TBD | TBD | TBD | TBD | TBD | TBD |
+
+### 3.1 Strategie selezionate
+
+Per ognuno dei top-5, riportare la S-expression generata e una lettura qualitativa: il pattern catturato è economicamente plausibile (es. mean reversion, momentum di breakout, condizione di stress) o è un'iperparametrizzazione casuale del backtest?
+
+**Top-1**: TBD.
+**Top-2**: TBD.
+**Top-3**: TBD.
+**Top-4**: TBD.
+**Top-5**: TBD.
+
+### 3.2 Ratio top-5 / median
+
+Median DSR popolazione: TBD. Mediana DSR top-5: TBD. Ratio: TBD (gate 1.5x).
+
+---
+
+## 4. Parser failure modes
+
+**Domanda gate 2**: l'output LLM è strutturalmente affidabile?
+
+### 4.1 Statistiche aggregate
+
+- Evaluations totali: TBD
+- Parse success: TBD (TBD%)
+- Parse failure: TBD (TBD%)
+
+### 4.2 Tassonomia degli errori
+
+Per ognuna delle classi sotto, riportare frequenza assoluta e relativa:
+
+- **No s-expression found in output**: TBD. Causa tipica: l'LLM ha restituito prosa senza fence o senza `(strategy ...)` esplicito.
+- **sexp parse error**: TBD. Causa tipica: parentesi sbilanciate, syntax non valida.
+- **Unknown verb**: TBD. Causa tipica: LLM ha inventato verbi non in `VERBS`.
+- **Validation error (unknown indicator/feature)**: TBD. Causa tipica: LLM ha usato indicatori non presenti in `KNOWN_INDICATORS`.
+- **Validation error (wrong arity)**: TBD. Causa tipica: numero argomenti errato per verbi specifici.
+
+### 4.3 Failure mode più frequente — analisi qualitativa
+
+Esempio di output LLM che ha causato il failure dominante: TBD.
+
+Suggerimenti per Phase 2 (es. arricchire il prompt con esempi negativi, validare con DSPy o restrict to JSON instead of S-expression): TBD.
+
+---
+
+## 5. Costi reali vs preventivo
+
+**Domanda gate 5**: la spesa è prevedibile?
+
+### 5.1 Breakdown costi LLM
+
+| Tier | Calls | Input tokens | Output tokens | Cost USD |
+|---|---|---|---|---|
+| C | TBD | TBD | TBD | TBD |
+| Altri | TBD | TBD | TBD | TBD |
+| **Totale** | TBD | TBD | TBD | **TBD** |
+
+### 5.2 Ablation tier (se eseguito)
+
+Phase 1 lean spike usa solo tier C. Ablation B vs C rinviata a Phase 2 (spec sez. 5.1).
+
+### 5.3 Confronto con preventivo
+
+- Preventivo: $500-700 (mid $600).
+- Spesa reale: $TBD.
+- Deviazione: TBD%.
+- Tokens medi per call: TBD input, TBD output.
+
+### 5.4 Estrapolazione costi Phase 2
+
+Phase 2 prevede K=40 (× 2x), 15 generazioni (× 1.5x) e tier mix (~30% B, 10x più caro). Estrapolazione lineare: TBD × 2 × 1.5 × ~3 = $TBD. Confronto con cap Phase 2 ($700-1100): rientrano.
+
+---
+
+## 6. Diversity metrics
+
+**Domanda gate 4**: la diversità cognitiva sopravvive alla pressione selettiva?
+
+### 6.1 Entropy fitness per generazione
+
+(Vedi tabella sez. 2.1 colonna entropy.)
+
+### 6.2 Cognitive style sopravvissuti
+
+| Stile | Gen 0 (count) | Gen finale (count) |
+|---|---|---|
+| physicist | TBD | TBD |
+| biologist | TBD | TBD |
+| historian | TBD | TBD |
+| meteorologist | TBD | TBD |
+| ecologist | TBD | TBD |
+| engineer | TBD | TBD |
+
+### 6.3 Signal correlation fra top-5
+
+Phase 1 non implementa speciation né novelty bonus, quindi è plausibile vedere alta correlazione fra i top performer. Misura indicativa (Pearson correlation fra signal series dei top-5 sull'OOS): TBD. Se ρ > 0.7, top-5 sono cloni leggeri — implicazione architetturale per Phase 2 (necessità di novelty bonus o speciation).
+
+---
+
+## 7. Threats to validity
+
+Lista esplicita dei limiti metodologici e dei rischi di sovra-interpretare i risultati:
+
+1. **In-sample fitting**: tutto il backtest è sullo stesso range usato per generare le ipotesi. Phase 2 introduce walk-forward + hold-out finale per misurare overfitting.
+2. **Mock LLM-driven exploration con tier C unico**: nessun confronto contro tier B / S. Possibile underperformance vs Sonnet/Opus che potrebbero generare strategie qualitativamente diverse.
+3. **Adversarial layer hand-crafted**: i 4 check (no_trades, degenerate, overtrading, undertrading) sono euristici. Phase 2 introduce 5 prompt LLM-driven dedicati (data snooping, lookahead, regime fragility, crowding, transaction cost erosion).
+4. **Fitness function v0**: lineare in DSR + drawdown penalty. Non multi-livello (per-team, anti-collusion). Phase 2 introduce.
+5. **No speciation, no novelty bonus**: convergenza prematura plausibile. Documentata nello spec sez. 8.4.
+6. **Cerbero/Deribit data quality**: nessuna detection di gap, outlier, exchange downtime. Da affrontare prima di forward-test (Phase 3).
+7. **Costi LLM volatili**: pricing OpenRouter per qwen3 può variare. Stima Phase 2 può cambiare significativamente.
+
+---
+
+## 8. Conclusioni e implicazioni per Phase 2
+
+**Hard gate sintesi**: TBD su 5 passati.
+
+**Decisione preliminare**: rimandato al `docs/decisions/2026-05-10-gate-phase1.md` (decision memo).
+
+**Apprendimenti chiave per Phase 2** (popolare a chiusura):
+
+- TBD.
+
+**Riusabilità del codebase Phase 1**: il design modulare (data, backtest, metrics, cerbero, protocol, genome, llm, agents, ga, persistence, orchestrator, dashboard) è riutilizzabile direttamente in Phase 2. Estensioni richieste: speciation in `ga/`, novelty bonus in `ga/fitness.py`, walk-forward integration in `orchestrator/run.py`, Adversarial LLM-driven in `agents/adversarial.py`, Random Forest baseline in nuovo modulo `baseline/`.
+
+---
+
+*Documento da finalizzare a fine Phase 1. Versione 1.0 — template; popolare con i numeri reali da `runs.db` e screenshot della dashboard.*