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. **Memory: SOLO pgvector, niente registry.** Le memory vivono esclusivamente nella tabella `vectors.memory` (vectordb condiviso). Il `registry.jsonl` di ChironeWp3 è **eliminato** (vestigiale: una volta che il metadata del vectordb contiene subject/detail/rationale, il registry non serve più). La promotion (F5) = upsert diretto a vectordb (`save-one` per una memoria, batch per molte). Le decisioni restano nel ledger di sessione (`review_decisions.jsonl`, per-sessione, separato dalle memory). Multi-workstation OK per costruzione: niente file locale da sincronizzare.
   - **Listare memory** → scan del vectordb.
   - **"Cancellare"** → il writer REST è upsert-only; non si cancella fisicamente, si marca `metadata.status="superseded"` (audit trail).
   - **Re-index (modello embedding cambia)** → operazione server-side che rilegge dal vectordb stesso.
   - **Conseguenza nel codice:** `tht/memory.py` NON porta `load_registry`/`save_registry`/`update_record`/`delete_record`/`registry_path`/`promote(registry_path)` (6 funzioni droppate). Restano `MemoryRecord`, `memory_vector_records`, `save_one_memory`. La promotion (F5) si riscrive come upsert batch al vectordb (Onda 3).
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. Reso **necessario** dalla decisione 5 (senza registry, il vectordb è l'unica fonte).
7. **Evidence: repository separato per-cliente, NON dentro ThothII.** Il contenuto evidence è specifico del dominio cliente (es. aritmologia @ policlinico). Struttura: ThothII è generico (zero contenuto cliente); un **repo workspace separato per-cliente** (es. `tht-workspace-psd/`) contiene `evidence/`, il workspace YAML cliente, e gli indici LSH (vedi punto 8). Deploy = `checkout ThothII + checkout tht-workspace-<cliente>`, con `.env` che punta `THT_DOCS_ROOT` al repo cliente. Niente "copia in harness/".
8. **LSH: scarica TUTTI i valori distinti, non "campiona".** `tht lsh build` scarica tutti i valori distinti scaricabili delle colonne di testo dal DWH (parametrico, dipende dal workspace), costruisce i MinHash+LSH dentro harness come attività di preprocessing. L'indice risultante è **per-cliente**: vive nel repo workspace separato (decisione 7), non in `harness/indexes/` generico.
9. **`language` come parametro del workspace.** Il workspace dichiara la lingua in cui sono scritte le descrizioni di tabelle/colonne e le evidence (es. `language: it` per PSD). La skill lo legge e lo usa per: (a) interpretare i match LSH/evidence nel linguaggio giusto, (b) indirizzare il reviewer in quella lingua. Le **istruzioni della skill restano in inglese** (più affidabili per i modelli, meno ambigue); solo contenuto e output seguono il `language`. Default `en`. Rende Thoth non legato all'italiano (generalizzazione per altri clienti/domini).
10. **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 (repo workspace per-cliente + LSH build)

Perché la sessione L2 validi davvero D14 (value-grounding) e F4 evidence-based (come claims la Sezione 4), servono due setup che oggi mancano. Entrambi sono **per-cliente** (decisioni 7+8), NON dentro ThothII.

**Repo workspace per-cliente (decisione 7):**
- ThothII è generico. Il contenuto evidence è specifico del dominio cliente (aritmologia @ PSD nel caso di test). Struttura di deploy:
  ```
  checkout ThothII          # generico, niente contenuto cliente
  checkout tht-workspace-psd # repo separato: evidence/ + workspace YAML + indici LSH
  ```
  Con `.env` che punta `THT_DOCS_ROOT=<repo-workspace>/evidence` e `THT_WORKSPACE=<repo-workspace>/psd.yaml`.
- **Non si copia evidence in harness/.** Ogni cliente ha il suo repo workspace.
- Per il test L2 locale: il repo workspace PSD è `/Users/mp/Chirone/chirone/etl/docs` (la cartella esiste). Si crea un repo `tht-workspace-psd/` che la referenzia/conteiene, separato da ThothII. Operazione one-shot del deploy, documentata in README, non nel codice ThothII.
- Verifica: `tht search --kind evidence "<termine>"` ritorna risultati non vuoti su un termine noto.

**LSH index (value-grounding D14a, decisione 8):**
- Dipende da `tht.lshindex` (portato in Onda 0) + `tht lsh build` (lsh_cmd, portato in Onda 4).
- Build sul workspace cliente (UNA volta, prima della sessione):
  ```bash
  tht lsh build --workspace <repo-workspace>/psd.yaml
  ```
  **Scarica TUTTI i valori distinti scaricabili delle colonne di testo** dal DWH (parametrico, via REST `db.sampling.unique_values_for_lsh_rest`), costruisce i MinHash + LSH, li serializza nel path `indexes/` del **repo workspace cliente** (NON in `harness/indexes/`).
- 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). Operazione one-shot per cliente, 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 (crea repo workspace + 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→tht`:

| Modulo | Righe | Dipendenze | Note |
|---|---|---|---|
| `vendor/thoth_lsh.py` + `VENDORED.md` | ~85 | datasketch, tqdm (leaf puro) | copia in `tht/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:

```python
# phase_cmd.py — aggiunta a quanto già portato (meta)
def require_phase_or_exit(cfg, session: str, min_phase: int) -> None:
    from tht.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)

```python
# 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 tht.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 `tht/workflow.py`:

```python
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).** Originale: `memory promote` (scriveva il registry) poi `memory index` (full resync vectordb dal registry). ThothII **droppa il registry** (decisione 5): le memory vivono SOLO nel vectordb. La promozione di una singola memoria usa `tht memory save-one` (upsert mirato via writer key, implementato in B2). La skill F5 (promozione batch) si riscrive come upsert batch diretto a vectordb (niente registry intermedio). La F2 (applicazione) legge dal vectordb; grazie all'arricchimento metadata (decisione 6), l'hit basta per ricostruire la decisione. Onesta sul limite: il writer REST è upsert-only, la "cancellazione" è logica (`metadata.status="superseded"`).

   **Arricchimento metadata vectordb (correzione del gap + reso necessario dal drop del registry).** La tabella `vectors.memory` aveva `metadata = {type, session_id, tables, concepts}` — mancavano `subject`/`detail`/`rationale` strutturati. ThothII arricchisce: in `memory_vector_records` (`tht/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 registry, questo arricchimento è obbligatorio** (non opzionale): il vectordb è l'unica fonte. **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, `tht/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 `tht <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.