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`.