PythagorasGoal/docs/diary/2026-09-02c-flag-e-pulizia.md

2026-09-02 — Un flag sconosciuto non è l'azione di default

Scritto fra le 15:45Z e le 16:05Z. Il difetto è stato misurato, non ipotizzato: la revisione del codice di questa sessione ha eseguito trades_db.py --help come sonda di tempi e lo ha visto sincronizzare il DB.

1. Il difetto

Nessuno dei 18 script di scripts/live/ usava argparse. Leggevano gli argomenti così:

if "--reconcile" in args: ...
elif "--report" in args: ...
else: sync()            # <- qui finiva QUALUNQUE cosa non riconosciuta

Un flag sbagliato non era un errore: era il ramo finale. Costo osservato e costi possibili:

script	--help faceva	gravità
trades_db.py	sync(): riscriveva meta.ultimo_sync	osservato oggi, danno nullo
journal.py	scriveva la pagina di oggi e una riga nel DB	non osservato, ma scrive
analista.py	spendeva una chiamata al modello e mandava un Telegram	non osservato, ma spende

2. La riparazione, e perché non è argparse

src/live/cli.valida(nome, uso, flag=..., con_valore=...), chiamata come prima istruzione di ogni blocco __main__ — prima di connect(), prima del sync, prima della rete.

• --help / -h → stampa l'uso, esce 0;
• flag non dichiarato, o valore mancante, o posizionale → stderr con cosa e cosa si poteva (P4), esce 2 (errore d'uso, distinto dall'1 con cui gli script segnalano un esito negativo);
• tutto il resto invariato.

Argparse no. Cambierebbe messaggi d'errore, codici d'uscita e il comportamento di --help su 18 script che il cron già invoca: romperebbe ciò che gira per riparare ciò che non gira mai. Qui serviva l'opposto — lasciare intatti i flag esistenti e rifiutare solo l'ignoto.

3. Il test guarda entrambe le metà del contratto

tests/test_cli_flag.py, 30 test:

• l'elenco degli script si deriva dalla cartella (P1): uno script nuovo che legge sys.argv a mano e non chiama valida fa fallire il test, non passa inosservato perché nessuno ha aggiornato una lista;
• valida dev'essere la prima istruzione di __main__ (uscire dopo l'effetto non è uscire);
• l'uso deve nominare i flag che lo script accetta;
• i flag che il cron usa davvero devono restare accettati (P15/P16, letti dai cron_*.sh): una guardia che ferma il libro di bordo la notte stessa sarebbe peggio del difetto;
• end-to-end sui tre script che scrivono: --help esce 0 e non tocca trades.db; un flag ignoto esce 2 e non lo tocca (M15: il caso che ha causato il difetto, non un caso vicino).

Verificato a mano anche il contrario: monitor_health.py --quiet, trades_db.py --sync --quiet e book_execute.py in dry-run escono 0 come prima.

4. Il resto della sessione

Indice USDE orario (debito §5.15, primo passo). Il classificatore dei movimenti di capitale confronta due letture di equity a un'ora di distanza e il suo bound guarda solo BTC/ETH, mentre il 31% dell'equity è USDE: un depeg sarebbe scorporato come un prelievo. usde_watch registra l'indice una volta al giorno — troppo rado. Ora balance_watch (orario, sola lettura) lo registra a ogni campione, None con la ragione se non leggibile, mai 1,0. Il cablaggio nel bound viene quando la serie ha storia: prima serve il dato, poi la regola.

Pulizia lasciata dalla revisione. tests/helpers.carica_script sostituisce la dodicesima copia del caricatore importlib (15 in giro, con nomi di modulo diversi per lo stesso file e differenze silenziose su sys.modules); il fill di prova si scrive con upsert_fills invece che con un INSERT a mano che lasciava verified NULL, una forma che la produzione non produce; le asserzioni sul testo del report non sono più ancorate al padding; movimenti_capitale accetta le righe già lette, così il report non fa due SELECT sulla stessa tabella a un'ora del cron — due letture ai due lati di una scrittura descriverebbero due istanti diversi.

5. Il README era fermo a quindici giorni prima del reset

Chiesto un aggiornamento della documentazione, ho aperto il README e ho trovato un documento del 2026-06-04. Il reset v2.0.0 è del 19 giugno. Per 75 giorni la prima pagina del repository ha descritto la libreria pre-reset come se fosse il presente:

cosa diceva	stato vero
famiglie FADE / HONEST / PAIRS / TSMOM / SHAPE, strategie MR01…SH01	archiviate in Old/, artefatto di feed contaminato
PORT06: Sharpe 7,84 / 10,06, DD 2,60%, CAGR ~79%	numeri che CLAUDE.md §2 elenca sotto «non citare»
paper trader su strategies.yml, portafogli in portfolios.yml	file inesistenti
scripts/waste/, scripts/portfolios/, src/live/multi_runner.py	inesistenti
esecuzione shadow su Deribit testnet	il testnet è la causa del reset; oggi si esegue su mainnet con soldi veri

Riscritto contro lo stato vero: cosa gira adesso, i numeri nella lente di §2 (TWR +10,6%, non la crescita del conto), il metodo e i sei requisiti, la struttura verificata file per file, i gate con le loro date, l'obiettivo con la sua onestà. Ogni percorso citato è stato controllato: esiste. Da 423 righe a 152.

La lezione che ho registrato non è «aggiornare il README». È che un reset invalida anche i documenti che nessuno rilegge, e l'inventario di cosa cita numeri morti va fatto il giorno del reset — non 75 giorni dopo, per caso, mentre si fa altro.

6. Cosa NON ho fatto

• I loader importlib dei test sulla ricerca (moduli in scripts/research/) restano come sono: sono a livello di modulo, con radici diverse, e toccarli non ripara niente.

• Il bound USDE nel classificatore: manca la storia, non il codice.

• Non ho cercato altri documenti fermi al pre-reset fuori da README.md e docs/: l'inventario completo (ogni file che cita un numero morto) resta da fare, ed è la vera coda di questa scoperta.