Cerbero-Bite/docs/09-development-roadmap.md

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) ✅ implementata

Obiettivo: dashboard locale per osservazione e azioni manuali. Spec dettagliata in 11-gui-streamlit.md.

Implementata in quattro round (A–D):

1. ✅ gui/main.py + sidebar nav (auto-refresh attivo non cablato; il re-render Streamlit è sufficiente per la frequenza tipica)
2. ✅ Pagina Status (engine state, kill switch panel con typed confirmation, audit anchor, open positions)
3. ✅ Pagina Equity (cumulative P&L, drawdown, P&L distribution per close reason, per-month stats)
4. ✅ Pagina Position (legs from entry snapshot, payoff plotly per bull_put/bear_call con annotazioni, decision history) — greche live e force-close differiti
5. ✅ Pagina History (filtri window/reason/winners-losers, KPI strip, CSV export)
6. ✅ Pagina Audit (live log stream, chain verify, event filter)
7. ✅ Consumer runtime/manual_actions_consumer.py con job APScheduler */1 per arm/disarm (force_close = not_supported per ora)
8. ⏳ Test integration con streamlit.testing.v1.AppTest

Definition of Done — stato:

• ✅ 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 (source="manual_gui") ed effettivo entro ~1 minuto
• ⏳ Force-close da GUI: l'enqueue funziona ma l'orchestrator deve ancora esporre handle_force_close
• ⏳ Test integration AppTest: non scritti

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.