un flag sconosciuto non e' l'azione di default: guardia su 18 script, indice USDE orario, pulizia

MISURATO oggi durante la revisione: `trades_db.py --help` non stampava l'uso, cadeva in sync()
e riscriveva meta.ultimo_sync. Nessuno dei 18 script di scripts/live/ usava argparse: un flag
sbagliato era il ramo else. Su journal.py avrebbe scritto pagina e riga di DB, su analista.py
avrebbe speso una chiamata al modello e mandato un Telegram.

- src/live/cli.valida: prima istruzione di ogni __main__, prima di connect()/sync/rete.
  --help -> 0 con l'uso; flag ignoto, valore mancante o posizionale -> 2 con l'elenco dei
  previsti (P4). NIENTE argparse: cambierebbe messaggi, codici d'uscita e --help di script
  che il cron gia' chiama.
- 18 script cablati (i 3 che scrivono + 14 + cc01), flag invariati.
- tests/test_cli_flag.py (30): elenco DERIVATO dalla cartella (P1), valida come prima
  istruzione, uso che documenta i flag, e i flag che il CRON usa davvero restano accettati
  (P15/P16); end-to-end su --help e flag ignoto con trades.db non toccato (M15).
  Verificato a mano: monitor_health --quiet, trades_db --sync --quiet, book_execute dry-run.

Debito §5.15, primo passo: balance_watch (orario) registra `usde_usdc` a ogni campione — None
con la ragione se illeggibile, mai 1,0. Il cablaggio nel bound quando la serie ha storia.

Pulizia dalla revisione: tests/helpers.carica_script al posto della 15a copia del loader
importlib (5 file del libro live); il fill di prova via upsert_fills invece di un INSERT che
lasciava verified NULL; asserzioni non ancorate al padding; movimenti_capitale accetta le
righe gia' lette (una SELECT invece di due ai due lati di una scrittura del cron).

Test 910 verdi (+52). Diario 2026-09-02c.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XDJsH3iDSaBns3ccpPBwiu

scripts/live/analista.py

@@ -115,7 +115,21 @@ def scrivi(con, g: date, modello: str, secco: bool = False, verbose: bool = True
     return stato
 
 
+USO = """uso: analista.py [--giorno AAAA-MM-GG] [--modello NOME] [--secco] [--no-telegram] [--quiet]
+
+  (nessun flag)  scrive l'analisi di OGGI nel campo `analisi` e manda la notifica
+  --giorno G     analizza il giorno G
+  --modello M    modello da usare (default: src.live.analista.MODELLO_DEFAULT)
+  --secco        stampa e NON salva, niente Telegram
+  --no-telegram  salva ma non manda la notifica
+  --quiet        non stampa
+
+⚠️ SPENDE una chiamata al modello e MANDA un messaggio Telegram, salvo --secco/--no-telegram."""
+
 if __name__ == "__main__":
+    from src.live.cli import valida
+    valida("analista.py", USO, flag=("--secco", "--no-telegram", "--quiet"),
+           con_valore=("--giorno", "--modello"))
     con = T.connect()
     g = date.fromisoformat(_arg("--giorno", datetime.now(timezone.utc).date().isoformat()))
     st = scrivi(con, g, modello=_arg("--modello", A.MODELLO_DEFAULT),

scripts/live/balance_watch.py

@@ -85,6 +85,17 @@ def campiona(c: DeribitRead) -> dict:
         rec["n_posizioni"] = sum(1 for p in pos if abs(float(p.get("size") or 0)) > 1)
     except Exception:
         rec["nozionale_lordo"], rec["n_posizioni"] = None, None
+    # INDICE usde_usdc, ORARIO (aggiunto 2026-09-02, debito §5.15). `usde_watch` lo registra una
+    # volta al giorno (12:35Z): troppo rado per il classificatore dei movimenti di capitale, che
+    # confronta due letture di equity a un'ora di distanza e oggi guarda solo BTC/ETH — con il
+    # 31% dell'equity in USDE, un depeg sarebbe scorporato come un PRELIEVO. Questa e' la serie
+    # che manca; il cablaggio nel bound viene dopo, quando ci sara' storia. None se non leggibile
+    # (P5: "non vedo" non e' "il peg tiene").
+    try:
+        from src.live.usde import prezzo_indice
+        rec["usde_usdc"] = prezzo_indice()
+    except Exception as e:
+        rec["usde_usdc"], rec["usde_usdc_errore"] = None, f"{type(e).__name__}"
     return rec
 
 

scripts/live/book_execute.py

@@ -355,5 +355,14 @@ def main():
         raise
 
 
+USO = """uso: book_execute.py [--execute]
+
+  uv run python scripts/live/book_execute.py   # DRY-RUN (piano, nessun ordine)
+  uv run python scripts/live/book_execute.py --execute   # esegue SOLO se execution_enabled=true
+
+Dettaglio nel docstring in testa al file."""
+
 if __name__ == "__main__":
+    from src.live.cli import valida
+    valida("book_execute.py", USO, flag=("--execute",), con_valore=())
     main()

scripts/live/cc01_regime_watch.py

@@ -93,5 +93,13 @@ def main() -> None:
         print("  regime QUIET: carry non raccoglibile (coerente con luglio 2026).")
 
 
+USO = """uso: cc01_regime_watch.py
+
+  (nessun flag) sorveglia il regime di CC01 e stampa lo stato.
+
+Dettaglio nel docstring in testa al file."""
+
 if __name__ == "__main__":
+    from src.live.cli import valida
+    valida("cc01_regime_watch.py", USO)
     main()

scripts/live/edge_watch.py

@@ -144,5 +144,15 @@ def main() -> int:
     return 0
 
 
+USO = """uso: edge_watch.py [--quiet]
+
+  edge_watch.py — sorveglianza dell'EDGE del book live. Riporta e allerta; non tocca nulla.
+  uv run python scripts/live/edge_watch.py   # report
+  uv run python scripts/live/edge_watch.py --quiet   # solo se qualcosa scatta (cron)
+
+Dettaglio nel docstring in testa al file."""
+
 if __name__ == "__main__":
+    from src.live.cli import valida
+    valida("edge_watch.py", USO, flag=("--quiet",), con_valore=())
     raise SystemExit(main())

scripts/live/fee_watch.py

@@ -252,5 +252,15 @@ def main() -> int:
     return 2 if r["level"] == "AZIONE" else 0
 
 
+USO = """uso: fee_watch.py [--quiet]
+
+  fee_watch.py — sorveglia lo schema fee di Deribit e applica la regola DECISA IN ANTICIPO.
+  uv run python scripts/live/fee_watch.py   # report
+  uv run python scripts/live/fee_watch.py --quiet   # stampa/allerta solo se qualcosa cambia
+
+Dettaglio nel docstring in testa al file."""
+
 if __name__ == "__main__":
+    from src.live.cli import valida
+    valida("fee_watch.py", USO, flag=("--quiet",), con_valore=())
     raise SystemExit(main())

scripts/live/journal.py

@@ -41,7 +41,19 @@ def una(con, g: date, nota: str | None = None, verbose: bool = True) -> Path:
     return f
 
 
+USO = """uso: journal.py [--giorno AAAA-MM-GG] [--backfill N] [--nota "testo"] [--quiet]
+
+  (nessun flag)  scrive la voce di OGGI (pagina marcata PARZIALE: il giorno non e' chiuso)
+  --giorno G     scrive la voce del giorno G
+  --backfill N   ricostruisce gli ultimi N giorni, dal piu' vecchio
+  --nota "..."   annota il giorno (campo dell'operatore, mai riscritto da un ricalcolo)
+  --quiet        non stampa la riga di riepilogo
+
+⚠️ SCRIVE: una riga nel DB e una pagina in docs/journal/. Sola lettura su feed, log e venue."""
+
 if __name__ == "__main__":
+    from src.live.cli import valida
+    valida("journal.py", USO, flag=("--quiet",), con_valore=("--giorno", "--backfill", "--nota"))
     # sincronizzare PRIMA: altrimenti la sezione 'Libro' (letta dal log) e la sezione 'P&L'
     # (letta dal DB) descrivono due istanti diversi e la pagina si contraddice da sola.
     sys.path.insert(0, str(ROOT / "scripts" / "live"))

scripts/live/live_execute.py

@@ -137,5 +137,14 @@ def main():
         raise
 
 
+USO = """uso: live_execute.py [--execute]
+
+  uv run python scripts/live/live_execute.py   # DRY-RUN (piano, nessun ordine)
+  uv run python scripts/live/live_execute.py --execute   # esegue SOLO se execution_enabled=true
+
+Dettaglio nel docstring in testa al file."""
+
 if __name__ == "__main__":
+    from src.live.cli import valida
+    valida("live_execute.py", USO, flag=("--execute",), con_valore=())
     main()

scripts/live/live_trend.py

@@ -74,5 +74,15 @@ def main():
           (f"{len(r['orders'])} ordine/i costruito/i sopra." if r["orders"] else "Target flat: 0 ordini."))
 
 
+USO = """uso: live_trend.py [--equity V] [--no-net]
+
+  uv run python scripts/live/live_trend.py   # shadow su mainnet reale
+  uv run python scripts/live/live_trend.py --equity 2000   # forza la base di sizing
+  uv run python scripts/live/live_trend.py --no-net   # offline: solo matematica + parita'
+
+Dettaglio nel docstring in testa al file."""
+
 if __name__ == "__main__":
+    from src.live.cli import valida
+    valida("live_trend.py", USO, flag=("--no-net",), con_valore=("--equity",))
     main()

scripts/live/microtest.py

@@ -88,5 +88,14 @@ def main():
     print("  Validato: invio ordine reale, fill, fee reali, reconciliation, ritorno a flat.")
 
 
+USO = """uso: microtest.py [--live]
+
+  uv run python scripts/live/microtest.py   # DRY-RUN: nessun ordine inviato
+  uv run python scripts/live/microtest.py --live   # invia il round-trip REALE
+
+Dettaglio nel docstring in testa al file."""
+
 if __name__ == "__main__":
+    from src.live.cli import valida
+    valida("microtest.py", USO, flag=("--live",), con_valore=())
     main()

scripts/live/monitor_health.py

@@ -55,5 +55,15 @@ def main() -> int:
     return 0
 
 
+USO = """uso: monitor_health.py [--quiet]
+
+  monitor_health.py — i forward-monitor stanno registrando? Riporta e allerta, non tocca nulla.
+  uv run python scripts/live/monitor_health.py   # report
+  uv run python scripts/live/monitor_health.py --quiet   # stampa/allerta solo se scatta
+
+Dettaglio nel docstring in testa al file."""
+
 if __name__ == "__main__":
+    from src.live.cli import valida
+    valida("monitor_health.py", USO, flag=("--quiet",), con_valore=())
     raise SystemExit(main())

scripts/live/paper_combo.py

@@ -118,5 +118,13 @@ def main():
     print(f"  GTAA (IB, asof {asof}): " + ", ".join(f"{k} {v:.0%}" for k, v in gw.items() if v) + f"  | cash {cash:.0%}")
 
 
+USO = """uso: paper_combo.py [--reset] [--status]
+
+  uv run python scripts/live/paper_combo.py [--status|--reset]
+
+Dettaglio nel docstring in testa al file."""
+
 if __name__ == "__main__":
+    from src.live.cli import valida
+    valida("paper_combo.py", USO, flag=("--status", "--reset"), con_valore=())
     main()

scripts/live/paper_portfolio.py

@@ -87,5 +87,15 @@ def main():
     print(f"  posizioni correnti: {pf.current_positions()}")
 
 
+USO = """uso: paper_portfolio.py [--reset] [--status]
+
+  uv run python scripts/live/paper_portfolio.py   # avanza (init al 1o run)
+  uv run python scripts/live/paper_portfolio.py --status   # solo stato
+  uv run python scripts/live/paper_portfolio.py --reset   # azzera (riparte da ora)
+
+Dettaglio nel docstring in testa al file."""
+
 if __name__ == "__main__":
+    from src.live.cli import valida
+    valida("paper_portfolio.py", USO, flag=("--status", "--reset"), con_valore=())
     main()

scripts/live/paper_regen.py

@@ -224,5 +224,15 @@ def main() -> None:
     print("\n  fatto. I file *.%s.* sono l'evidenza del difetto e restano nel backup." % SUFFISSO)
 
 
+USO = """uso: paper_regen.py [--solo V]
+
+  paper_regen.py — RIGENERA le serie dei forward-monitor rotti da `advance()` (§5.1).
+  uv run python scripts/live/paper_regen.py   # tutti e 4
+  uv run python scripts/live/paper_regen.py --solo paper_statarb
+
+Dettaglio nel docstring in testa al file."""
+
 if __name__ == "__main__":
+    from src.live.cli import valida
+    valida("paper_regen.py", USO, flag=(), con_valore=("--solo",))
     main()

scripts/live/scale_watch.py

@@ -58,5 +58,15 @@ def main() -> None:
     print(f"\n  invio: {rep['invio']}")
 
 
+USO = """uso: scale_watch.py [--quiet] [--secco]
+
+  uv run python scripts/live/scale_watch.py   # osserva e stampa, invia se ALLARME
+  uv run python scripts/live/scale_watch.py --secco   # osserva e stampa, NON invia nulla
+  uv run python scripts/live/scale_watch.py --quiet   # una riga sola (per il cron)
+
+Dettaglio nel docstring in testa al file."""
+
 if __name__ == "__main__":
+    from src.live.cli import valida
+    valida("scale_watch.py", USO, flag=("--quiet", "--secco"), con_valore=())
     main()

scripts/live/telegram_daily.py

@@ -146,5 +146,14 @@ def main() -> None:
     print("inviato" if send(txt) else "NON inviato (config Telegram assente o rete KO)")
 
 
+USO = """uso: telegram_daily.py [--dry-run]
+
+  uv run python scripts/live/telegram_daily.py   # calcola e invia
+  uv run python scripts/live/telegram_daily.py --dry-run   # stampa e basta, non invia
+
+Dettaglio nel docstring in testa al file."""
+
 if __name__ == "__main__":
+    from src.live.cli import valida
+    valida("telegram_daily.py", USO, flag=("--dry-run",), con_valore=())
     main()

scripts/live/trades_db.py

@@ -125,8 +125,16 @@ def report() -> None:
     con.close()
 
 
+USO = """uso: trades_db.py [--sync] [--report] [--reconcile] [--quiet]
+
+  --sync       (default) legge log e jsonl e aggiorna data/live/trades.db — idempotente
+  --report     stato del libro di bordo + P&L (TWR, non e1/e0)
+  --reconcile  incrocio delle tre fonti sui fill (log x jsonl x venue)
+  --quiet      con --sync: non stampa il riepilogo"""
+
 if __name__ == "__main__":
-    args = sys.argv[1:]
+    from src.live.cli import valida
+    args = valida("trades_db.py", USO, flag=("--sync", "--report", "--reconcile", "--quiet"))
     if "--reconcile" in args:
         reconcile()
     elif "--report" in args:

scripts/live/usde_watch.py

@@ -330,5 +330,15 @@ def main() -> int:
     return 0
 
 
+USO = """uso: usde_watch.py [--quiet]
+
+  usde_watch.py — sorveglianza giornaliera del collaterale USDE: reward, depeg, quota. SOLA LETTURA.
+  uv run python scripts/live/usde_watch.py   # report completo
+  uv run python scripts/live/usde_watch.py --quiet   # stampa/allerta solo transizioni
+
+Dettaglio nel docstring in testa al file."""
+
 if __name__ == "__main__":
+    from src.live.cli import valida
+    valida("usde_watch.py", USO, flag=("--quiet",), con_valore=())
     sys.exit(main())

scripts/live/venue_watch.py

@@ -98,5 +98,15 @@ def main() -> int:
     return 0
 
 
+USO = """uso: venue_watch.py [--quiet]
+
+  venue_watch.py — runner ORARIO del tripwire di venue. Allerta su Telegram, NON blocca nulla.
+  uv run python scripts/live/venue_watch.py   # un giro, stampa il report
+  uv run python scripts/live/venue_watch.py --quiet   # solo in caso di allarme (per il cron)
+
+Dettaglio nel docstring in testa al file."""
+
 if __name__ == "__main__":
+    from src.live.cli import valida
+    valida("venue_watch.py", USO, flag=("--quiet",), con_valore=())
     raise SystemExit(main())