ThothII/docs/superpowers/specs/2026-06-27-cli-port-completo-skill-riscritta-design.md

Design: porting CLI completo + riscrittura skill nsp-sessione

Data: 2026-06-27 Stato: bozza, in attesa di approvazione Contesto: il piano harness (A8–D6) ha portato nsp phase meta (1/12 comandi CLI) e i modelli dati/backend core, ma il loop skill→LLM→gate resta non esercitato perché mancano gli altri 11 comandi CLI + la skill nsp-sessione. Questo design porta il resto per rendere il loop testabile end-to-end.

Decisioni (approvate in brainstorming)

1. Scope: F1→F8 completo. Tutti gli 11 cmd CLI mancanti + i 3 cluster backend mancanti + skill riscritta.
2. Drift phase.py: riscrittura diretta sui 12 siti cmd che usano le vecchie costanti (MAX_PHASE/PHASE_NAMES/SCHEMA_LINKING_PHASE/DECISION_MIN_PHASE) → load_workflow() + metodi su Workflow. Niente strato wrapper.
3. Skill: riscrittura completa ex-novo che riflette l'architettura ThothII (widget-descriptor, D11 save-one, D13 free-text, D14 value-grounding/formula, D15 rollback), prendendo spunto dalla struttura ChironeWp3 ma non copiandola.
4. Indipendenza da ChironeWp3 (proprietà architetturale): quando ThothII è pronto, il server non deve avere ChironeWp3 installato — solo Supabase (DWH + pgvector con le RPC SECURITY DEFINER, indipendenti dal codice app) e la cartella evidence (dentro ThothII). Nessuna dipendenza dal repo chirone. Verificato: il codice ThothII non ha riferimenti a ChironeWp3/psdwp3 (rename completo); le RPC vivono nel DB.
5. Registro memory: locale per-workstation. registry.jsonl vive in harness/artifacts/memory/ su ciascuna workstation (NON condiviso). La F2 (applicazione) legge dal vectordb condiviso e, grazie all'arricchimento metadata (decisione 6), ricostruisce la decisione senza lookup nel registro. Il registro resta necessario solo per la F5 (promozione: scrive localmente + indicizza sul vectordb condiviso). Multi-workstation OK: le memorie si condividono via vectordb.
6. Arricchimento metadata memory vectordb: subject/detail/rationale nel jsonb (vedi Sezione 3 punto 2). Correzione del gap ereditato da ChironeWp3. Reso possibile dal fatto che la tabella memory è vuota al momento del porting.
7. Evidence: dentro ThothII. La cartella evidence (contenuto statico curato, 229 markdown) si sposta in harness/evidence/. ThothII diventa self-contained (vedi Onda 0b).
8. Renaming prodotto tht (Thoth = prodotto, PSD = cliente). Il codice non porta traccia del contesto clinico. Rinomine: comando nsp→tht, package nsp/→tht/ (46 file import), skill nsp-sessione→tht-sessione, gate nsp-gate.js→tht-gate.js, workspace chirone.*→tht.example.yaml/tht-test.yaml (generici-prodotto; un deploy cliente crea il suo psd.yaml non-committato). Variabili env THOTH_*→THT_* (uniformate al comando).
9. Neutralizzazione riferimenti cliente nel codice. Commenti/docstring che menzionano "ChironeWp3", "PsdWp3", "DWH Chirone", "policlinico", "sandonato" vengono resi generici ("the reference implementation", "the DWH") o rimossi. Il contesto cliente (endpoint supabase-...policlinicosandonato.it, nomi schema datawarehouse) vive SOLO nei file di configurazione reali (.env gitignored, workspace cliente non-committato) — mai nel codice versionato né nei template.
10. Renaming come Onda -1 (isolata, prima del porting CLI). Si fa come passo separato e verificato: dopo il rename, pytest deve restare 109 passed (verifica che il renaming non ha rotto nulla). Poi il porting CLI (Onde 0-4) avviene già col nome nuovo tht — niente doppio lavoro. Isolare il renaming dal porting permette di debuggare l'uno indipendentemente dall'altro.

Sezione 1 — Architettura e strategia di porting

Porting fedele con riscritture chirurgiche del drift, in ordine topologico (dipendenze radice prima), così ogni passo ha un'app che carica. Sei onde:

Onda -1 — renaming prodotto tht (ISOLATA, prima di tutto)
  nsp->tht (comando+package+46 import), nsp-sessione->tht-sessione,
  nsp-gate.js->tht-gate.js, chirone.*->tht.* workspace, THOTH_*->THT_* env.
  Neutralizzazione riferimenti chirone/psd/policlinico nei commenti/docstring.
  Verification: pytest resta 109 passed (rename non rompe nulla).

Onda 0 — backend mancanti (foglie)
  vendor/thoth_lsh, lshindex/, sqlcheck/, execute/, rest/execute.py,
  rest/explain.py, ctetest.py, report.py, datamart.py(stub)

Onda 1 — radici intra-CLI (espongono helper importati da tutti)
  config_cmd (CONFIG_OPT), schema_cmd (_load_config_or_exit, physical_path,
            annotations_path), session_cmd (session_dir, load_session_or_exit)
  + require_phase_or_exit riscritta ex-novo in phase_cmd
  + comandi advance/reopen/show di phase_cmd (oggi c'è solo meta)

Onda 2 — vector layer
  vector_cmd (make_embedder, open_store, open_searcher, require_vector_cfg)

Onda 3 — cmd foglia (usano radici + vector)
  memory_cmd, search_cmd, evidence_cmd, db_cmd, decision_cmd
  + arricchimento metadata memory (subject/detail/rationale in tht/memory.py:
    memory_vector_records) — correzione gap ereditato, vedi Sezione 3 punto 2

Onda 4 — cmd SQL/CTE (cluster sql_cmd)
  sql_cmd (do_run, do_explain, promoted_tables_for, _load_physical_or_exit)
  cte_cmd, datamart_cmd(stub), lsh_cmd (usa lshindex Onda 0)

Onda 0b — setup pre-sessione (dopo Onda 0 + Onda 4, prima della sessione L2)
  Cabla evidence nel workspace + .env, builda indice LSH sul workspace tht-test.
  NECESSARIO: senza di questo i claim D14/evidence della sessione L2 sono falsi
  (la F4 gira degradata, solo segnali vettoriali).

Dopo ogni onda: pytest verde (109, nessuna regressione) + import smoke (tht <sub> --help esce 0 per ogni nuovo sottocomando).

Sezione 2 — Porting CLI e drift (dettaglio)

Onda 0b — Setup pre-sessione (evidence + LSH)

Perché la sessione L2 validi davvero D14 (value-grounding) e F4 evidence-based (come claims la Sezione 4), servono due setup che oggi mancano:

Evidence:

• La cartella evidence è contenuto statico curato a mano (229 markdown, 11M, nessuno script generatore ETL). Verificato: è documentazione clinica/db, non output di un processo. Per il deploy multi-workstation self-contained, si sposta dentro ThothII in harness/evidence/ (non più dipendenza dal path esterno /Users/mp/Chirone/chirone/etl/docs).
• Operazione: cp -r /Users/mp/Chirone/chirone/etl/docs harness/evidence (path sorgente — l'unico riferimento al repo chirone, puro one-shot di copia) + aggiornare il default di THT_DOCS_ROOT a harness/evidence + blocco evidence nel tht-test.yaml:

  evidence:
    source_root: ${THOTH_DOCS_ROOT}
    evidence_dir: evidence
  

• Nota sicurezza: la cartella va revisionata per contenuto sensibile (dati paziente?) prima di committare nel repo. Se contiene PII, va nel .gitignore e distribuita fuori banda, non nel repo pubblico. Da verificare prima del commit.
• Verifica: tht search --kind evidence "<termine>" ritorna risultati non vuoti su un termine noto.

LSH index (value-grounding D14a):

• Dipende da tht.lshindex (portato in Onda 0) + tht lsh build (lsh_cmd, portato in Onda 4).
• Build sul workspace tht-test (UNA volta, prima della sessione):

  tht lsh build --workspace workspaces/tht-test.yaml
  

  Questo campiona i valori distinti delle colonne di testo dal DWH via REST (db.sampling.unique_values_for_lsh_rest), costruisce i MinHash + LSH, e li serializza in indexes/ (path del workspace).
• Verifica: tht search "<valore noto>" ritorna match multi-colonna (es. "ablazione" su più colonne) e test_value_grounding_real (L2) smette di skip-piare.
• Prerequisito: la build richiede il DWH raggiungibile (VPN) + embeddings (Ollama attivo). È un'operazione one-shot, non a ogni sessione.

Ordine: Onda 0b si esegue DOPO Onda 0 (lshindex) e Onda 4 (lsh_cmd), e PRIMA della sessione L2. È un'operazione dell'operatore (build indice), non codice nuovo — ma va nel piano come step esplicito con la sua verifica.

Onda 0 — backend mancanti

Tutti piccoli, nessun drift (non toccano phase/workflow). Port verbatim con rename psdwp3→nsp:

Modulo	Righe	Dipendenze	Note
vendor/thoth_lsh.py + VENDORED.md	~85	datasketch, tqdm (leaf puro)	copia in nsp/vendor/
lshindex/__init__.py	~85	vendor + LshConfig (portato)	sed rename
sqlcheck/__init__.py	~125	ExecutionConfig + mschema.models (portati)	leaf
execute/__init__.py + execute/warnings.py	~150	ExecutionConfig (portato)	leaf
rest/execute.py + rest/explain.py	~60	execute + rest.client (portato)
ctetest.py	~110	sqlglot, pydantic	leaf
report.py	~80	execute + sqlcheck (stessa onda)
datamart.py	~30	—	stub raise NotImplementedError

Onda 1 — radici intra-CLI + require_phase_or_exit

I 3 cmd radice si portano verbatim (rename), eccetto gli import di session.phase → phase. Poi require_phase_or_exit riscritta ex-novo:

# phase_cmd.py — aggiunta a quanto già portato (meta)
def require_phase_or_exit(cfg, session: str, min_phase: int) -> None:
    from nsp.workflow import load_workflow
    cur = current_phase(session_dir(cfg, session))
    if cur < min_phase:
        wf = load_workflow()
        nome = wf.phase_name(min_phase)
        typer.secho(
            f"Impossibile: serve la Fase {min_phase} ({nome}), sessione '{session}' è alla Fase {cur}.",
            fg=typer.colors.RED, err=True,
        )
        raise typer.Exit(1)

In questa onda si portano anche i comandi advance/reopen/show di phase_cmd con lo stesso fix dei 2 drift (const → load_workflow(), import path).

Drift: i 12 siti di costanti phase (meccanici, stesso pattern)

# PRIMA (ChironeWp3)
from psdwp3.session.phase import MAX_PHASE, PHASE_NAMES, SCHEMA_LINKING_PHASE, DECISION_MIN_PHASE
... MAX_PHASE ... PHASE_NAMES.get(n) ... DECISION_MIN_PHASE.get(type, 1) ... cur < SCHEMA_LINKING_PHASE

# DOPO (ThothII)
from nsp.workflow import load_workflow
wf = load_workflow()
... wf.max_phase ... wf.phase_name(n) ... wf.decision_min_phase(type) ... cur < wf.schema_linking_phase()

Siti: 5 file cmd (phase_cmd, session_cmd, decision_cmd, cte_cmd, datamart_cmd).

Gap da colmare in Workflow: manca il metodo schema_linking_phase(). Da aggiungere a nsp/workflow.py:

def schema_linking_phase(self) -> int:
    """La fase che produce schema_linking.json (artifacts_out). Default 5."""
    for p in self.phases:
        if "schema_linking.json" in p.artifacts_out:
            return p.num
    return 5

Onde 2-4 — cmd foglia e SQL/CTE

Port verbatim (rename + fix import path session.phase→phase). Nessun altro drift: DecisionType è generico via get_args (i 4 nuovi tipi ThothII si pickano automaticamente), i modelli si costruiscono da JSON (model_validate), i campi ThothII-added (grounded_values, concept_formulas, author/summary) sono opzionali con default.

Registrazione nell'app: alla fine di ogni onda, app.add_typer(<sub>_app, name="<sub>") in cli/__init__.py. Smoke verification: nsp <sub> --help esce 0.

Cross-cutting: ordine intra-CLI obbligato

• _load_config_or_exit, physical_path, annotations_path, session_dir, load_session_or_exit, CONFIG_OPT sono definiti nei cmd radice (config_cmd/schema_cmd/session_cmd) e importati dalla maggior parte degli altri → portati per primi (Onda 1).
• vector_cmd exports (make_embedder, open_store, open_searcher, require_vector_cfg) consumati da memory_cmd/search_cmd/evidence_cmd → vector_cmd in Onda 2, prima di quei tre (Onda 3).
• sql_cmd exports (do_run, do_explain, promoted_tables_for, _load_physical_or_exit) consumati da cte_cmd + session_cmd → sql_cmd (Onda 4) prima di cte_cmd. (session_cmd è radice in Onda 1 ma i suoi path SQL dipendono da sql_cmd; verificare in implementazione se session_cmd va spostato dopo sql_cmd, o se i due path si disaccoppiano.)

Sezione 3 — Riscrittura skill nsp-sessione

Riscrittura ex-novo che prende spunto dalla struttura ChironeWp3 ma riflette ThothII. Posizionamento: harness/.pi/skills/nsp-sessione/ con SKILL.md + 4 sottomoduli (cte.md, memoria.md, rewriting.md, sql-generation.md).

Cosa si conserva dall'originale (valido, non reinventare)

• Struttura a 8 fasi F1→F8 con prerequisito/postcondizione di ciascuna
• Discipline trasversali (un fatto per comando nsp, una domanda alla volta, accetta-la-proposta sempre fra le opzioni, nessuno step in limbo, artefatto = output di prima classe)
• Modello decisionale: reviewer_decide per decisioni descrittive (la scelta È la conferma), reviewer_confirm solo per i gate F1/F5/F7
• Semantica dei comandi nsp (quando chiamarli, in che ordine) — ogni vincolo preciso (es. "max 5 memorie candidate, solo 3 tipi riusabili: concept_clarified/table_promoted/table_excluded") va trasferito fedelmente leggendo l'originale riga per riga, non parafrasato

Cosa si riscrive per riflettere ThothII

1. Modello gate → widget-descriptor. La prosa originale dice "dialog native / checklist a caselle". Riscritta in termini di widget: reviewer_select (single-pick), reviewer_decide (multiselect con payload decisione), reviewer_confirm (artifact-gate). Le invarianti (Altro sempre presente, no-limbo, recommended marker) sono garantite dai builder (C1). La disciplina resta identica, il vocabolario cambia.

2. Fase 2 — save-one (D11) invece di full resync. Originale: memory promote poi memory index (full resync, solo-server). ThothII: in profile=workstation, la promozione di una singola memoria usa nsp memory save-one (upsert mirato via writer key, implementato in B2); memory promote + memory index (full resync) resta per profile=server. La skill guida il modello al comando corretto: presenta memory save-one quando il contesto è una singola memoria promossa in workstation, memory promote + memory index quando si fa promozione batch lato server. La discriminante è il comando invocato (la CLI legge il profilo da .env); la skill non deve far dedurre il profilo al modello, ma scegliere il comando in base al numero di memorie da promuovere (una → save-one, molte → promote). Onesta sul limite: save-one ha cleanup distruttivo assente (resta server-side).

   Arricchimento metadata vectordb (correzione del gap ereditato da ChironeWp3). La tabella vectors.memory aveva metadata = {type, session_id, tables, concepts} — mancavano subject/detail/rationale strutturati, quindi l'hit vettoriale non bastava per applicare la memoria (ChironeWp3 faceva lookup nel registro canonico). ThothII arricchisce: in memory_vector_records (nsp/memory.py) si aggiungono subject/detail/rationale al dict metadata del VectorRecord. pack_metadata (rest_writer.py:26) li serializza automaticamente nel jsonb via **record.metadata. Nessuna modifica al writer RPC, nessuna modifica allo schema DB. search_similar proietta già metadata completo → la F2 ricostruisce la decisione direttamente dall'hit, senza lookup nel registro. Il registro globale resta come source-of-truth per la promozione (F5), ma la F2 legge solo dal vectordb. Momento ideale: la tabella memory è vuota, niente re-indicizzazione di dati esistenti.

3. Fase 3 — riscrittura (invariata nel modello, solo vocabolario gate). Prerequisito "devi essere già in Fase 3" (exit 5, nsp/phase.py:171), question_rewritten come decisione, sequenza ordinata (decisione → rewrite_question tool → nsp session set-question scrive question.md deterministicamente, session/store.py:set_question). Allineamento widget-descriptor. Gestione modifica/rifiuto invariata ("Altro" itera, "Torna indietro" riapre F1).

4. Fase 4 — value grounding (D14a) + formula (D14b). Originale F4 menziona solo table_promoted/excluded/column_corrected. ThothII aggiunge:

   • value_grounded: quando un valore citato (es. "ablazione") matcha più colonne (flag + testo), il modello presenta reviewer_decide con opzioni value_grounded per ogni colonna candidata (usando aggregate_lsh_multi che non collassa al miglior match). Il reviewer sceglie l'ancora.
   • concept_formula_approved/rejected: quando un concetto (es. "fascia pediatrica", "stesso anno") ha una formula SQL candidata (retrieve_formula), il modello la presenta e il reviewer approva/rifiuta. Per la domanda di test, candidati naturali: estrazione anno da data, calcolo età nell'anno dell'ablazione, predicato same-year fra due eventi.

5. Discipline — free-text (D13). Aggiunta: quando il reviewer usa "Altro" con testo libero, il modello valuta il testo in contesto, agisce, ri-chiede se ambiguo (non defaulta). Il testo registrato nel rationale della decisione (contratto testato in B5).

6. Discipline — rollback (D15). Aggiunta: dopo /torna N o "Torna indietro", il modello riprende dalla fase N rivedendo gli artefatti esistenti; teardown_to_phase cancella gli artefatti oltre il target. Il modello NON ri-esegue comandi nsp per artefatti ancora validi.

7. Fase 8 — datamart resta stub. datamart.py è raise NotImplementedError. La skill lo guida come nell'originale (decisione sì/no + hook stub), onesta sul fatto che non genera nulla.

Sottomoduli

cte.md, memoria.md, rewriting.md, sql-generation.md portati adattandone la prosa gate (stessa logica del punto 1 sopra), mantenendo la sostanza tecnica.

Frontmatter

name: nsp-sessione, description riscritta per ThothII (NL→SQL su Chirone, fasi 1-8, widget-descriptor gate, evoluzioni D11/D13/D14/D15).

Metodo di scrittura (per preservare l'intento originale)

L'intento preciso di ogni fase (vincoli come "max 5 memorie candidate", "solo 3 tipi riusabili", "checklist pre-selezionata con la proposta", sequenze ordinate) si trasferisce leggendo l'originale riga per riga durante l'implementazione, non parafrasando. Se durante la scrittura un vincolo risulta poco chiaro, si chiede invece di indovinare.

Sezione 4 — Testing e criteri di successo

Test automatici (CI-runnabile, a ogni onda)

Porting CLI + backend (Onde 0-4):

• Dopo ogni onda, pytest (L0+L1) deve restare 109 passed — nessuna regressione.
• Import smoke per onda: python -c "from nsp.<modulo> import ..." per ogni nuovo backend; nsp <sub> --help esce 0 per ogni nuovo sottocomando.
• Drift L1 (nuovo test): esercita require_phase_or_exit su fasi sintetiche — conferma che la riscrittura contro Workflow funziona. Pure logic, tmp_path, no DB.

Skill:

• Non unit-testable in L1 (prosa per il modello).
• Verifica automatica: grep -c "PsdWp3\|psdwp3" in harness/.pi/skills/nsp-sessione/ = 0; ogni nsp <cmd> citato corrisponde a un sottocomando registrato in cli/__init__.py (script di coerenza).

Test L2 — la sessione di test (manuale, pre-rilascio)

Domanda di test (complessa, massima copertura):

Crea una lista con i pazienti che negli ultimi 20 anni hanno avuto una cardioversione elettrica ed una ablazione lo stesso anno. Per ogni paziente incluso nella lista esponi il sesso, l'età che aveva il paziente nell'anno in cui ha fatto l'ablazione, tutti i dati rilevanti dell'ablazione e tutti i dati rilevanti della cardioversione.

Verifica sullo schema reale: entrambi i concetti hanno fact table dedicate (fact_cardioversione_elettrica_transtoracica, fact_studio_elettrofisiologico_endocavitario_ablazione + ~13 fact_see_ablazione_* di dettaglio). La domanda esercita F4 complesso (2 fact + ~15 dim/detail, join multipli), D14 (value-grounding: "ablazione"/"cardioversione elettrica" matchano nomi-tabella e campi/patologie; formula: "stesso anno", "età nell'anno dell'ablazione"), F6 (decomposizione CTE naturale), F7 (SQL finale complesso).

Criteri di successo della sessione:

1. Avvio: /nuova-domanda "<la domanda>" → il modello chiama nsp session new, legge la skill, inizia F1.
2. Gate funziona: il modello chiama i tool reviewer_* e il gate presenta widget-descriptor (non prosa grezza). Il reviewer può rispondere.
3. Persistenza: ogni decisione del reviewer produce una riga in review_decisions.jsonl (verificabile leggendo il file dopo).
4. Avanzamento fasi: il workflow avanza F1→... secondo le decisioni, usando i comandi nsp corretti (non phase advance manuale, non decision add diretto).
5. Anti-bypass: se il modello prova nsp phase advance da shell, il gate lo blocca (hook tool_call).
6. Artefatti: per una domanda che arriva in fondo, schema_linking.json + cte_plan.json/ctes/*.sql + sql_final.sql prodotti e coerenti col ledger.

Copertura per evoluzione:

Evoluzione	Esercitata?	Come
F1/F3/F5 (base)	sì	chiarimento, riscrittura, sintesi
F4 complesso	sì	2 fact + ~15 dim, join multipli
D14a value-grounding	sì (se Onda 0b fatta)	"ablazione"/"cardioversione" matchano tabella + campi; richiede indice LSH buildato (Onda 0b)
D14b formula	sì	"stesso anno", "età nell'anno ablazione"
D13 free-text	se innesca	se il reviewer corregge via "Altro"
D11 save-one (F2)	solo se memorie trovate	se nsp memory search in F2 trova match (NOTA: tabella memory azzerata di recente — la prima sessione probabilmente salta F2 senza match, quindi D11 va validato con una seconda sessione dopo aver popolato le memorie). L'arricchimento metadata (Onda 3) fa sì che quando F2 trova match, l'hit basta per applicare la memoria senza lookup registro.
F6 CTE	sì	decomposizione naturale
D15 rollback	se innesca	se il reviewer torna indietro

Onestà

• Più copertura = più punti di rottura. Una domanda complessa ha più probabilità di fallire a metà in punti che una semplice non tocca. Un fallimento a metà non è un fallimento del porting — è il segnale che L2 è designed a cogliere. Va letto come tale.
• Durata: sessione lunga (più decisioni, CTE uno a uno). Va bene per test pre-rilascio, non per ripeterlo spesso.
• Gate glue in CI: resta verificato solo nella sessione L2 manuale senza un fake-Pi mock (follow-up cross-cutting noto).
• Comportamento non deterministico di GLM 5.2: la sessione può andare diversamente a ogni run. L2 è safety-net pre-rilascio, non regression gate.

Ordine di esecuzione e definition of done

1. Onda -1 (renaming tht) → pytest verde 109 passed + tht --help funziona + grep -rw nsp = 0 nel codice
2. Onda 0 (backend) → pytest verde + import smoke
3. Onda 1 (radici CLI + require_phase_or_exit + phase advance/reopen/show) → pytest verde + tht phase advance --help esce 0
4. Onda 2-4 (cmd foglia + SQL/CTE) → pytest verde + tht --help mostra tutti i sottocomandi
5. Skill riscritta (tht-sessione) → script di coerenza (no PsdWp3/chirone, cmd citati = cmd registrati)
6. Onda 0b (setup pre-sessione) → copiare evidence in harness/evidence/ + tht lsh build su tht-test; verifica tht search ritorna LSH + evidence
7. Sessione L2 (manuale, con l'operatore) → criteri 1-6 sopra

Definition of done: Onde 0-4 + skill completate con pytest verde + sessione L2 che soddisfa i criteri 1-4 (avvio, gate, persistenza, avanzamento). I criteri 5-6 (anti-bypass, artefatti finali) sono verification aggiuntiva nella stessa sessione.

Fuori scope (rimane aperto)

• Gate glue in CI (fake-Pi mock): follow-up cross-cutting. Il glue nsp-gate.js resta verificato solo in L2 manuale.
• L2 come regression gate: resta pre-rilascio, non CI.
• RPC mancanti lato server (validate_select, current_user): rilevate 404 nei test. Non bloccano il loop base, ma vanno (ri)installate lato Supabase per i path pre-SQL.