ThothII/docs/reports/2026-08-15-tht-command-maintain-erase-enhance.md

# Proposta maintain-erase-enhance per i comandi `tht`

Data: 2026-08-15

## Criterio

- **MAINTAIN**: il comando resta disponibile senza modifiche sostanziali. Come richiesto, non viene
  aggiunta una motivazione.
- **ERASE**: il comando viene eliminato dalla nuova CLI; la motivazione indica la duplicazione, il
  superamento o l'assenza di un utilizzo reale.
- **ENHANCE**: la capacità viene mantenuta, ma il comando viene migliorato, accorpato o reso più
  sicuro. La proposta indica l'intervento.

La proposta copre tutti i 77 comandi terminali dell'attuale CLI Python.

## Sintesi

| Proposta | Numero |
|---|---:|
| MAINTAIN | 55 |
| ENHANCE | 8 |
| ERASE | 14 |
| **Totale** | **77** |

## Lista completa

### Diagnostica, configurazione e dipendenze

| Comando | Proposta |
|---|---|
| `config check` | **ENHANCE** — incorporare la validazione nel comando pubblico `tht doctor`, mantenendo una funzione interna riutilizzabile e l'output strutturato. Evita due preflight sovrapposti. |
| `doctor` | **ENHANCE** — farne l'unica diagnostica multilivello: installazione, descriptor, Compose, storage, configurazione runtime, DWH, Pi, Qdrant ed embedder. Deve offrire output umano e `--json`, senza mutare lo stato. |
| `db ping` | **MAINTAIN** |
| `db fetch-ca` | **ENHANCE** — integrarlo nel setup guidato del workspace, mostrando endpoint e fingerprint prima della conferma. Può restare disponibile come operazione TLS avanzata, ma non come passaggio manuale obbligatorio. |
| `ollama ensure` | **MAINTAIN** |

### Fasi e decision ledger

| Comando | Proposta |
|---|---|
| `phase advance` | **MAINTAIN** |
| `phase meta` | **MAINTAIN** |
| `phase reopen` | **MAINTAIN** |
| `phase show` | **MAINTAIN** |
| `decision add` | **MAINTAIN** |
| `decision add-batch` | **MAINTAIN** |
| `decision add-join-set` | **MAINTAIN** |
| `decision list` | **ERASE** — non ha chiamanti reali e duplica il ledger già restituito da `session show --json`. |
| `decision retract` | **ERASE** — non è invocato dal workflow corrente; `phase reopen` è il percorso supportato per correggere e invalidare deterministicamente le decisioni. La semantica tombstone può restare nel dominio. |

### Sessioni

| Comando | Proposta |
|---|---|
| `session archive` | **MAINTAIN** |
| `session check` | **MAINTAIN** |
| `session close` | **MAINTAIN** |
| `session delete` | **MAINTAIN** |
| `session documents` | **MAINTAIN** |
| `session fail` | **MAINTAIN** |
| `session finalize` | **MAINTAIN** |
| `session list` | **MAINTAIN** |
| `session migrate` | **MAINTAIN** |
| `session new` | **MAINTAIN** |
| `session preferences get` | **MAINTAIN** |
| `session preferences set` | **MAINTAIN** |
| `session reopen` | **MAINTAIN** |
| `session retrieval-pack` | **MAINTAIN** |
| `session set-group` | **MAINTAIN** |
| `session set-name` | **MAINTAIN** |
| `session set-question` | **MAINTAIN** |
| `session set-schema-linking` | **MAINTAIN** |
| `session show` | **MAINTAIN** |
| `session sync-schema-linking` | **MAINTAIN** |
| `session unarchive` | **MAINTAIN** |

### Schema e retrieval

| Comando | Proposta |
|---|---|
| `schema check` | **MAINTAIN** |
| `schema columns` | **MAINTAIN** |
| `schema introspect` | **MAINTAIN** |
| `schema render` | **MAINTAIN** |
| `schema suggest-fks` | **MAINTAIN** |
| `search find` | **MAINTAIN** |
| `search pack` | **MAINTAIN** |

### CTE, SQL e datamart

| Comando | Proposta |
|---|---|
| `cte info` | **MAINTAIN** |
| `cte list` | **ERASE** — non ha chiamanti o test e sovrappone informazioni già disponibili con `cte plan`, `cte info` e `session documents`. |
| `cte next` | **MAINTAIN** |
| `cte plan` | **MAINTAIN** |
| `cte save` | **MAINTAIN** |
| `cte test` | **MAINTAIN** |
| `sql validate` | **MAINTAIN** |
| `sql preview` | **MAINTAIN** |
| `sql set-final` | **MAINTAIN** |
| `sql export` | **MAINTAIN** |
| `sql explain` | **ERASE** — non è usato né testato dal workflow attuale. Va reintrodotto soltanto se l'analisi del piano diventa un passo esplicito del processo. |
| `sql save` | **ERASE** — duplica `sql set-final` e `sql export` e introduce un percorso di scrittura non utilizzato. |
| `datamart generate` | **MAINTAIN** |

### Memory

| Comando | Proposta |
|---|---|
| `memory promote` | **MAINTAIN** |
| `memory save-one` | **MAINTAIN** |
| `memory search` | **MAINTAIN** |
| `memory solved-index` | **MAINTAIN** |
| `memory solved-search` | **MAINTAIN** |
| `memory list` | **ENHANCE** — trasformarlo in una vista amministrativa paginata, con filtri, provenienza, stato e output `--json`; non mostrarlo nell'help base. |
| `memory show` | **ENHANCE** — mostrare provenienza immutabile, decisione sorgente, stato dell'indice e riferimenti necessari a una correzione consapevole. |
| `memory update` | **ENHANCE** — limitare l'aggiornamento ai campi modificabili, mostrare un diff prima della conferma e impedire modifiche alla provenienza. |
| `memory delete` | **ENHANCE** — richiedere identificatore esatto e conferma esplicita, mostrare l'impatto e verificare la rimozione coerente da registro e indice. |
| `memory index` | **ENHANCE** — riposizionarlo come comando di repair: prima rileva il drift, poi ricostruisce soltanto con conferma e verifica finale. Non deve sembrare un'operazione ordinaria. |
| `memory clear` | **ERASE** — cancellazione globale non usata e troppo facile da eseguire per errore; backup/ripristino e cancellazione selettiva sono percorsi più sicuri. |
| `memory migrate` | **ERASE** — migrazione legacy una tantum; non esistono dati di produzione da preservare e la nuova architettura può partire direttamente dal formato corrente. |

### Preprocessing, evidence e indici

| Comando | Proposta |
|---|---|
| `preprocess dwh` | **MAINTAIN** |
| `preprocess evidence` | **MAINTAIN** |
| `vector index-schema` | **MAINTAIN** |
| `evidence extract` | **ERASE** — è un primitivo superato dalla pipeline versionata `preprocess evidence`; l'eventuale logica condivisa resta interna. |
| `evidence index` | **ERASE** — è un secondo primitivo superato dalla stessa pipeline, che già gestisce materializzazione, indicizzazione, versionamento e resume. |
| `lsh build` | **ERASE** — la costruzione LSH è già uno step di `preprocess dwh`; mantenere due ingressi permette esecuzioni parziali incoerenti. |
| `lsh query` | **ERASE** — probe visuale senza chiamanti, test o documentazione operativa; il workflow usa `search find`. |
| `vector init` | **ERASE** — il controllo di Qdrant ed embedder è già coperto dal reconciler della collezione, da `ollama ensure` e dal nuovo `tht doctor`. |

### Formule di concetto

| Comando | Proposta |
|---|---|
| `formula save` | **ERASE** — non ha chiamanti, test o un flusso di approvazione completo. Il formato e lo store possono restare disponibili alla ricerca finché non viene progettata una vera curation. |
| `formula list` | **ERASE** — appartiene allo stesso sottosistema incompleto; un futuro flusso deve progettare insieme creazione, approvazione, elenco, modifica e cancellazione. |

## Impatto sulla UX

I 55 comandi `MAINTAIN` comprendono molti contratti macchina intoccabili. Mantenerli non implica
mostrarli tutti nell'help principale. La futura CLI unica può conservare gli stessi percorsi per
backend, gate e job, mostrando all'utente soltanto i gruppi operativi di primo livello.