Phase 0: project skeleton

- pyproject.toml with uv, deps for runtime + gui + backtest + dev - ruff/mypy strict config, pre-commit hooks for ruff/mypy/pytest - src/cerbero_bite/ layout with empty modules ready for Phase 1+ - structlog JSONL logger with daily rotation - click CLI with placeholder subcommands (status, start, kill-switch, gui, replay, config hash, audit verify) - 6 smoke tests passing, mypy --strict clean, ruff clean Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-26 23:10:30 +02:00
commit 881bc8a1bf
40 changed files with 6018 additions and 0 deletions
@@ -0,0 +1,269 @@
+# 09 — Development Roadmap
+
+Sviluppo per fasi, ognuna con obiettivo chiaro, criteri di completamento
+e dipendenze. La sequenza è stretta: ogni fase aggiunge valore e si
+costruisce sulla precedente.
+
+## Fase 0 — Setup (3-5 giorni)
+
+**Obiettivo:** scheletro di progetto eseguibile, niente logica di
+business.
+
+Tasks:
+
+1. `git init` + branch `main` + `.gitignore` (esclude `data/`, `.lockfile`,
+   `*.local.yaml`).
+2. `pyproject.toml` con `uv`, deps base: pydantic, sqlalchemy, apscheduler,
+   mcp, rich (CLI), pytest, mypy, ruff.
+3. Layout cartelle come da `02-architecture.md`.
+4. Logger strutturato con `structlog`, output JSONL su file.
+5. `__main__.py` con CLI Click: comandi `start`, `stop`, `status`,
+   `dry-run`, `kill-switch`, `replay`.
+6. Pre-commit hooks installati.
+7. `tests/conftest.py` con fixtures di base.
+8. Hello-world test che valida l'avvio dell'engine senza nessun
+   tool MCP reale (tutti fake).
+
+Definition of Done:
+
+- `uv run cerbero-bite status` stampa "engine idle, kill_switch=0"
+- `uv run pytest` passa con almeno 5 test triviali
+- `mypy --strict src/` passa
+- Repository committato
+
+## Fase 1 — Core algorithms (7-10 giorni)
+
+**Obiettivo:** i 7 algoritmi puri implementati, con test al 100%.
+
+Tasks (ordine TDD):
+
+1. `entry_validator.validate_entry` + `compute_bias`
+2. `liquidity_gate.check`
+3. `sizing_engine.compute_contracts`
+4. `combo_builder.select_strikes` + `build`
+5. `greeks_aggregator.aggregate`
+6. `exit_decision.evaluate` (questo è il più complesso, due giornate dedicate)
+7. `kelly_recalibration.recalibrate`
+
+Per ogni modulo:
+- scrivere test che falliscono
+- implementare la versione minima che li passa
+- aggiungere property test con hypothesis
+- code review (skill `superpowers:requesting-code-review`)
+
+Definition of Done:
+
+- 100% statement+branch coverage su `core/`
+- Property test per ogni invariante documentata
+- 0 errori `mypy --strict`
+- Tutti i test obbligatori in `08-testing-validation.md` presenti
+
+## Fase 2 — Persistenza e safety (5-7 giorni)
+
+**Obiettivo:** state machine + risk control implementati.
+
+Tasks:
+
+1. Schema SQLite + migration 0001
+2. `state/repository.py` con CRUD typed
+3. Audit log con hash chain
+4. `safety/kill_switch.py` con tutti i trigger automatici
+5. `safety/dead_man.sh` script shell separato
+6. Backup utility + retention policy
+7. CLI `audit verify`, `kill-switch arm/disarm`, `state inspect`
+
+Definition of Done:
+
+- Coverage `state/` ≥ 90%, `safety/` 100%
+- Test di corruzione SQLite e hash chain passano
+- Recovery test: kill engine mid-write, restart, stato consistente
+
+## Fase 3 — MCP clients (4-6 giorni)
+
+**Obiettivo:** wrapper tipizzati per tutti i server MCP usati.
+
+Tasks (parallelizzabili tra collaboratori se ci fossero):
+
+1. `clients/_base.py`: McpClient abstract + retry/timeout
+2. `clients/deribit.py` con tutti i metodi documentati
+3. `clients/hyperliquid.py`
+4. `clients/macro.py`
+5. `clients/sentiment.py`
+6. `clients/portfolio.py`
+7. `clients/memory.py`
+8. `clients/telegram.py` (anche listener webhook per conferme)
+9. `clients/brain_bridge.py`
+
+Per ogni client: fake corrispondente in `tests/fixtures/fakes/`.
+
+Definition of Done:
+
+- Coverage `clients/` ≥ 80%
+- Fake test scenari happy/timeout/anomaly per ognuno
+- `cerbero-bite ping` lista lo stato di ogni MCP
+
+## Fase 4 — Orchestrator e flussi (5-7 giorni)
+
+**Obiettivo:** i flussi di `06-operational-flow.md` cablati.
+
+Tasks:
+
+1. `runtime/orchestrator.py` — composizione core + clients + state
+2. `runtime/scheduler.py` — APScheduler con i cron documentati
+3. `runtime/monitoring.py` — loop ogni 12h
+4. `runtime/alert_manager.py` — escalation policy
+
+Test integration su scenari completi (vedi `08-testing-validation.md`):
+- weekly open happy path
+- monitor profit take
+- monitor vol stop
+- recovery dopo crash
+- kill switch blocca entry
+
+Definition of Done:
+
+- Tutti gli integration test passano
+- Engine può girare in `--dry-run` per 24h senza errori
+- I log sono leggibili e completi
+
+## Fase 4.5 — GUI Streamlit (4 giorni)
+
+**Obiettivo:** dashboard locale per osservazione e azioni manuali. Spec
+dettagliata in `11-gui-streamlit.md`.
+
+Tasks:
+
+1. Setup `gui/main.py` + sidebar nav + auto-refresh
+2. Pagina Status (engine, capitale, MCP health, kill switch panel)
+3. Pagina Equity (curve, drawdown, monthly stats)
+4. Pagina Position (legs, payoff plotly, decision history, force-close)
+5. Pagina History (filtri, KPI, export CSV)
+6. Pagina Audit (log live, verify chain, search)
+7. Tabella `manual_actions` + consumer job APScheduler nell'engine
+8. Test integration con `streamlit.testing.v1.AppTest`
+
+Definition of Done:
+
+- `cerbero-bite gui` lancia la dashboard su `127.0.0.1:8765`
+- Tutte le 5 pagine raggiungibili e popolate
+- Disarm da GUI loggato in audit chain ed effettivo entro 30 sec
+- Force-close da GUI consumato dall'engine entro 30 sec
+- Test integration su ogni pagina passing
+
+## Fase 5 — Reporting e UX (3-5 giorni)
+
+**Obiettivo:** report Telegram puliti, daily digest, replay command.
+
+Tasks:
+
+1. `reporting/pre_trade.py` — testo Markdown con sezioni
+2. `reporting/exit_proposal.py`
+3. `reporting/daily_digest.py`
+4. `reporting/monthly_report.py`
+5. CLI `cerbero-bite replay` per backtest
+6. CLI `cerbero-bite recalibrate-kelly --dry-run`
+
+Definition of Done:
+
+- Tre messaggi Telegram esempio committati come fixtures
+- Replay command funziona su 30 giorni di dati storici simulati
+
+## Fase 6 — Golden tests e backtest (3-4 giorni)
+
+**Obiettivo:** suite di scenari golden + replay storico.
+
+Tasks:
+
+1. Almeno 10 scenari golden coprenti tutti i path principali
+2. Storia ETH spot + DVOL caricata da CSV in `tests/data/historical/`
+3. Confronto P&L replay vs simulazione Monte Carlo del documento
+
+Definition of Done:
+
+- Replay 2024-01 → 2026-04 senza errori
+- Equity curve riprodotta con stesso seed numerico
+- Differenza con MC entro intervalli attesi
+
+## Fase 7 — Paper trading (90 giorni)
+
+**Obiettivo:** validazione su segnali reali ma niente capitale.
+
+Setup:
+
+- Engine live in `--dry-run`
+- Telegram alert reali
+- Adriano replica trade su **testnet Deribit** o paper book per misurare
+  slippage reale
+
+Metriche da raccogliere:
+
+- Numero proposte settimanali emesse
+- Quante passano i filtri
+- Win rate, avg P&L paper
+- Discrepanze tra mid stimato e fill reale (slippage)
+- Errori di sistema, kill switch armati
+
+Definition of Done:
+
+- ≥ 30 trade paper concluso
+- 0 errori critici
+- Win rate ≥ 70% (paper ETH credit spread baseline atteso)
+- Sign-off Adriano via audit chain
+
+## Fase 8 — Soft launch (30 giorni live, cap dimezzato)
+
+**Obiettivo:** primi trade reali con capitale ridotto.
+
+Setup:
+
+- Cap 100 EUR per trade, 500 EUR engagement totale
+- Solo Bull Put Spread (no IC) per ridurre superficie di rischio
+- Daily digest manuale ogni mattina con Adriano
+
+Metriche di passaggio a full:
+
+- ≥ 10 trade reali conclusi
+- P&L coerente con Monte Carlo (entro 1 sigma)
+- 0 incidenti operativi
+- Spread fill mediano ≤ 5% slippage rispetto al mid stimato
+
+## Fase 9 — Full launch
+
+**Obiettivo:** operatività regime.
+
+- Cap pieno: 200 EUR per trade, 1.000 EUR engagement
+- Iron Condor abilitato (regime laterale)
+- Mensile review Kelly + report Brain-Bridge
+- Ogni 6 mesi review completa con Milito
+
+## Roadmap futura (post-launch, idee)
+
+- **Sottostante BTC**: stessa strategia, parametri ricalibrati. Richiede
+  fase di paper-trading dedicata.
+- **Multi-exchange execution**: alternativa a Deribit (Bybit options,
+  Binance options) per ridurre counterparty risk.
+- **Dashboard locale**: pagina HTML statica generata dai log per
+  visualizzare equity curve e trade list senza tool esterni.
+- **Auto Kelly update**: dopo 100 trade reali, valutare l'auto-update
+  con sand-box di review Milito.
+- **Promozione MCP options-engine**: estrarre `core/` come server MCP
+  dedicato, riusabile da Cerbero core stesso e da Milito.
+
+## Stima cumulativa
+
+| Fase | Giorni di lavoro | Calendar (con review) |
+|---|---:|---:|
+| 0 — Setup | 3-5 | 1 settimana |
+| 1 — Core | 7-10 | 2 settimane |
+| 2 — State & Safety | 5-7 | 1.5 settimane |
+| 3 — Clients | 4-6 | 1 settimana |
+| 4 — Orchestrator | 5-7 | 1.5 settimane |
+| 4.5 — GUI Streamlit | 4 | 1 settimana |
+| 5 — Reporting | 3-5 | 1 settimana |
+| 6 — Golden + Backtest | 3-4 | 1 settimana |
+| **Totale fino a paper-ready** | **34-48** | **~10 settimane** |
+| 7 — Paper trading | — | 12-13 settimane |
+| 8 — Soft launch | — | 4-5 settimane |
+| 9 — Full launch | — | ongoing |
+
+**Tempo a regime: ~6 mesi dal kickoff.**