ThothII/docs/reports/2026-08-15-tht-command-audit.md

Audit critico dei comandi tht

Data: 2026-08-15

Scopo

Questo audit valuta tutti i comandi terminali registrati dall'attuale CLI Python tht prima di unificare la CLI di ThothII sotto un solo eseguibile pubblico. La valutazione incrocia:

• il contratto del workflow Pi in harness/.pi/skills/tht-sessione/SKILL.md;
• le invocazioni reali del gate in harness/.pi/extensions/tht-gate.js;
• le invocazioni del backend in backend/src/tht/tht-runner.ts;
• i job operatore in backend/src/workspaces/preprocessing-service.ts;
• il migratore in docker/session-migrate.sh;
• test e documentazione esistenti.

L'inventario autorevole contiene 76 comandi Typer più il comando callback doctor: 77 comandi terminali complessivi.

Legenda

• WF — intoccabile workflow: chiamato da Pi, dal gate o dal contratto delle otto fasi. Va conservato con semantica, output JSON ed exit code compatibili. Non deve necessariamente apparire nell'help ordinario dell'utente.
• PL — intoccabile piattaforma: chiamato dal backend, dai job workspace o dal deployment. Anche questo è un contratto interno, non necessariamente un comando da mostrare all'utente.
• ADV — mantenere avanzato: non è nel flusso automatico, ma offre una capacità amministrativa o di recupero che sarebbe imprudente perdere. Va nascosto dall'help base.
• ACCORPA: la capacità serve, ma non merita un comando autonomo.
• RIMUOVI: il comando non ha chiamanti reali ed è duplicato, superato, pericoloso o incompleto. L'eventuale logica riutilizzata da altri flussi resta una libreria interna.

Risultato sintetico

Esito	Numero	Conseguenza
WF o PL, intoccabili	55	Conservare il contratto; nascondere i primitivi tecnici dall'help base
ADV o ACCORPA	8	Conservare la capacità riducendo la superficie UX
RIMUOVI	14	Eliminare il comando dalla nuova CLI
Totale	77	Una sola CLI pubblica molto più semplice, senza riscrivere il workflow vivo

Matrice completa

Diagnostica, configurazione e dipendenze

Comando	Valutazione
config check	ACCORPA in tht doctor: la validazione della configurazione serve, ma due preflight distinti confondono l'utente.
doctor	ACCORPA/MANTIENI pubblico come unico tht doctor, includendo controlli host, Compose, storage e configurazione runtime.
db ping	PL: il backend lo usa per rifiutare correttamente una nuova sessione quando il DWH non è raggiungibile o non è read-only. Interno.
db fetch-ca	ACCORPA in tht setup o nella configurazione workspace: utile per TLS, ma non giustifica un comando isolato.
ollama ensure	PL: preflight automatico dell'embedder usato dal backend. Interno.

Fasi e decision ledger

Comando	Valutazione
phase advance	WF: il gate lo usa per avanzare solo dopo la decisione umana. Primitivo anti-bypass, quindi interno.
phase meta	WF: fornisce al gate la definizione data-driven delle fasi e dei tipi di decisione. Interno.
phase reopen	WF: è il percorso canonico per tornare a una fase precedente e invalidare deterministicamente gli artefatti successivi.
phase show	WF: il gate lo usa per calcolare la fase corrente. Interno.
decision add	WF: persistenza fondamentale delle decisioni del reviewer. Solo gate, non shell utente.
decision add-batch	WF: scrittura atomica delle decisioni multiple. Evita ledger parziali.
decision add-join-set	WF: sostituzione atomica dell'intero insieme di join.
decision list	RIMUOVI: nessun chiamante; session show --json contiene già il ledger necessario.
decision retract	RIMUOVI dalla CLI: nessun flusso vivo lo invoca e phase reopen è il percorso di correzione supportato. La semantica tombstone può restare nel dominio finché utile.

Sessioni

Comando	Valutazione
session archive	PL: usato dalla gestione sessioni del backend.
session check	WF: gate oggettivo della fase 5; verifica decisioni e schema linking.
session close	PL: usato dal backend.
session delete	PL: usato dal backend con i relativi controlli applicativi.
session documents	WF/PL: ricostruisce il contesto persistito e alimenta sia Pi sia la GUI.
session fail	PL: usato dal backend per rappresentare il fallimento terminale.
session finalize	WF: chiusura deterministica della fase finale e indicizzazione della domanda risolta.
session list	PL: alimenta la lista sessioni della GUI.
session migrate	PL: eseguito dal servizio one-shot di migrazione server; resta interno dietro tht sessions migrate.
session new	WF/PL: crea la persistenza iniziale della domanda; il backend dipende dal JSON restituito.
session preferences get	PL: lettura delle preferenze applicative. Interno.
session preferences set	PL: scrittura delle preferenze applicative. Interno.
session reopen	PL: riapertura dello stato terminale esposta dalla gestione sessioni.
session retrieval-pack	WF: legge il retrieval pack già persistito per il kickoff di Pi. Distinto da search pack, che lo costruisce.
session set-group	PL: rinomina il raggruppamento dalla GUI.
session set-name	PL: rinomina la sessione dalla GUI.
session set-question	WF: persiste deterministicamente domanda riscritta e assunzioni. Solo gate.
session set-schema-linking	WF: valida e scrive schema_linking.json. Solo gate.
session show	WF/PL: fonte compatta dello stato persistito per resume, gate e backend.
session sync-schema-linking	WF: riproietta deterministicamente il ledger nello schema linking.
session unarchive	PL: usato dalla gestione sessioni del backend.

Schema e retrieval

Comando	Valutazione
schema check	PL: validazione delle annotazioni curate nel workflow workspace.
schema columns	WF: il gate usa il catalogo colonne per validare e correggere il linking.
schema introspect	WF: fallback previsto dal contratto quando manca lo schema fisico; la modalità refresh resta manutenzione.
schema render	WF: produce il contesto mschema usato dal modello.
schema suggest-fks	PL: comando del flusso operatore per le annotazioni FK curate.
search find	WF: ricerca mirata di evidence, valori e formule durante le fasi.
search pack	WF/PL: costruisce e persiste il contesto iniziale F1; usato anche dal backend.

CTE, SQL e datamart

Comando	Valutazione
cte info	WF: restituisce SQL persistito, posizione nel piano e ultimo test.
cte list	RIMUOVI: nessun chiamante o test; cte plan, cte info e session documents coprono il bisogno.
cte next	WF: il gate determina il prossimo CTE da revisionare.
cte plan	WF: persiste l'ordine completo dei CTE.
cte save	WF: tool deterministico di scrittura usato dal gate.
cte test	WF: verifica read-only dei CTE prevista esplicitamente dal contratto.
sql validate	WF: validazione strutturale e read-only prima dell'esecuzione.
sql preview	WF/PL: preview controllata usata dal modello e dalla GUI.
sql set-final	WF: unica scrittura canonica di sql_final.sql attraverso il repository di sessione.
sql export	PL: esportazione richiesta dalla GUI.
sql explain	RIMUOVI: nessun chiamante, test o requisito nel workflow corrente. Si reintroduce solo con un vero passo di analisi del piano.
sql save	RIMUOVI: duplica set-final ed export e permette un percorso di scrittura non usato.
datamart generate	WF: fase 8 del workflow.

Memory

Comando	Valutazione
memory promote	WF: preview dei candidati di promozione usata dal gate.
memory save-one	WF: persistenza atomica della singola memory approvata.
memory search	WF: recupero delle memory riutilizzabili nella fase 2.
memory solved-index	WF: recupero manuale previsto se l'indicizzazione al finalize fallisce.
memory solved-search	WF: recupero di domande risolte simili nelle fasi successive.
memory list	ADV: mantenere per amministrare record errati, ma fuori dall'help base.
memory show	ADV: mantenere insieme a list per ispezione puntuale.
memory update	ADV: mantenere per correggere il merito di una memory senza alterarne la provenienza.
memory delete	ADV: mantenere come rimedio selettivo; richiede conferma esplicita nella nuova CLI.
memory index	ADV: utile come riparazione/full-resync, ma va presentato come manutenzione e non come uso normale.
memory clear	RIMUOVI: distruzione globale non usata; confligge con una UX sicura di backup/ripristino.
memory migrate	RIMUOVI: migrazione legacy una tantum senza dati di produzione da preservare.

Preprocessing, evidence e indici

Comando	Valutazione
preprocess dwh	PL: pipeline canonica usata da tht workspace preprocess dwh/run.
preprocess evidence	PL: pipeline canonica usata da tht workspace preprocess evidence/run.
vector index-schema	PL: indicizzazione schema usata dal workflow workspace.
evidence extract	RIMUOVI: primitivo superato dalla pipeline versionata preprocess evidence. Conservare soltanto la logica riusata.
evidence index	RIMUOVI: primitivo superato dalla stessa pipeline versionata.
lsh build	RIMUOVI come comando: è già uno step di preprocess dwh; il builder resta interno.
lsh query	RIMUOVI: probe visuale senza chiamanti, test o documentazione operativa. La ricerca applicativa passa da search find.
vector init	RIMUOVI: il controllo di Qdrant/embedder è ormai coperto dal reconciler di collezione, da ollama ensure e dal nuovo tht doctor.

Formule di concetto

Comando	Valutazione
formula save	RIMUOVI dalla CLI corrente: nessun chiamante, test o flusso di approvazione lo usa. Conservare il formato/store e la lettura tramite search find --kind formula.
formula list	RIMUOVI: stesso sottosistema incompleto. Un futuro flusso di curation dovrà progettare insieme creazione, approvazione, elenco e modifica.

Conseguenza per la nuova CLI unica

La semplificazione migliore non consiste nel rinominare tutti i 55 contratti vivi o nel mostrarli all'utente. Consiste nel mantenere un unico eseguibile tht con due livelli di visibilità:

1. l'help ordinario mostra soltanto setup, lifecycle, backup/restore, Pi e workspace;
2. i contratti WF/PL restano invocabili dallo stesso eseguibile, ma sono interni/nascosti e usati da backend, gate e job one-shot.

In questo modo l'utente vede una CLI piccola, mentre il workflow non subisce una riscrittura inutile e rischiosa. Non serve un secondo eseguibile né un alias thothctl.