Adriano
da88e7f746
* docs/11-gui-streamlit.md — replaces the original spec with what was actually built: implementation status table, real page filenames (1_Status, 2_Audit, 3_Equity, 4_History, 5_Position), per-page inventory of implemented vs deferred sections, GUI ↔ engine table showing arm_kill/disarm_kill via manual_actions and the not_supported markers for force_close + approve/reject_proposal, consumer signature with cron */1, lock model clarified (no GUI lockfile), DoD updated with current state. * docs/05-data-model.md — manual_actions is no longer "pianificata": populated by gui/data_layer.py, drained by the manual_actions job; per-kind status table (arm/disarm OK, others not_supported). * docs/09-development-roadmap.md — Phase 4.5 marked implemented with per-task ✅/⏳ markers for the deferred items (auto-refresh, AppTest, force-close hook). * docs/06-operational-flow.md — adds Flusso 5b describing the manual_actions consumer pattern (enqueue → KillSwitch transition → audit log linkage). 360/360 tests still pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
279 lines
8.9 KiB
Markdown
279 lines
8.9 KiB
Markdown
# 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.**
|