# 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`):
- daily 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 giornaliere 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.**