docs(spec): aggiungi Onda 0b — setup pre-sessione evidence + LSH build

Buco trovato prima della user review: lo spec claims D14 value-grounding ed
evidence-based F4, ma non setup né evidence né l'indice LSH. Senza, la sessione
L2 girerebbe degradata (solo segnali vettoriali) e i claim sarebbero falsi.

Onda 0b (dopo Onda 0 + 4, prima della sessione L2):
- Evidence: cablare THOTH_DOCS_ROOT=/Users/mp/Chirone/chirone/etl/docs nel .env +
  blocco evidence nel chirone-test.yaml. La cartella esiste già.
- LSH: nsp lsh build sul workspace chirone-test (one-shot, richiede VPN + Ollama).
  Verifica: nsp search ritorna match multi-colonna + test_value_grounding_real
  smette di skip-piare.

Ordine esecuzione aggiornato (6 step), D14a value-grounding marcato 'sì (se Onda 0b)',
nsp lsh build tolto dal fuori-scope (ora dentro).
This commit is contained in:
2026-06-27 09:38:38 +02:00
parent 96499e70d6
commit 9f14a13594
@@ -34,12 +34,43 @@ Onda 3 — cmd foglia (usano radici + vector)
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 chirone-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 (`nsp <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 esiste già sul Mac: `/Users/mp/Chirone/chirone/etl/docs/evidence/` (curata a mano, fonte unica delle evidence).
- Cablare: aggiungere `THOTH_DOCS_ROOT=/Users/mp/Chirone/chirone/etl/docs` al `.env` (oggi vuoto) + blocco `evidence` nel `chirone-test.yaml`:
```yaml
evidence:
source_root: ${THOTH_DOCS_ROOT}
evidence_dir: evidence
```
- Verifica: `nsp search --kind evidence "<termine>"` ritorna risultati non vuoti su un termine noto.
**LSH index (value-grounding D14a):**
- Dipende da `nsp.lshindex` (portato in Onda 0) + `nsp lsh build` (lsh_cmd, portato in Onda 4).
- Build sul workspace chirone-test (UNA volta, prima della sessione):
```bash
nsp lsh build --workspace workspaces/chirone-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: `nsp 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`:
@@ -191,7 +222,7 @@ Verifica sullo schema reale: entrambi i concetti hanno fact table dedicate (`fac
|---|---|---|
| F1/F3/F5 (base) | sì | chiarimento, riscrittura, sintesi |
| F4 complesso | sì | 2 fact + ~15 dim, join multipli |
| D14a value-grounding | sì | "ablazione"/"cardioversione" matchano tabella + campi |
| 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) |
@@ -211,7 +242,8 @@ Verifica sullo schema reale: entrambi i concetti hanno fact table dedicate (`fac
2. Onda 1 (radici CLI + require_phase_or_exit + phase advance/reopen/show) → `pytest` verde + `nsp phase advance --help` esce 0
3. Onda 2-4 (cmd foglia + SQL/CTE) → `pytest` verde + `nsp --help` mostra tutti i sottocomandi
4. Skill riscritta → script di coerenza (no PsdWp3, cmd citati = cmd registrati)
5. Sessione L2 (manuale, con l'operatore) → criteri 1-6 sopra
5. Onda 0b (setup pre-sessione) → cablare evidence + `nsp lsh build` su chirone-test; verifica `nsp search` ritorna LSH + evidence
6. 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.
@@ -219,5 +251,4 @@ Verifica sullo schema reale: entrambi i concetti hanno fact table dedicate (`fac
- **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.
- **`nsp lsh build` completo** (port dell'indice LSH da schema reale): il test L2 value-grounding (`test_value_grounding_real`) richiede un indice buildato; `nsp lsh build` si porta qui (lsh_cmd in Onda 4), ma la build dell'indice sul workspace chirone-test è un'operazione pre-sessione separata.
- **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.