docs(evidence): finalize restructuring design

2026-08-24 14:57:53 +02:00
parent 6062cb010e
commit d970e10264
8 changed files with 2133 additions and 0 deletions
@@ -1,5 +1,11 @@
 # Evidence canonica — struttura tipizzata per disambiguazione, schema linking e SQL

+> **Superseded (2026-08-24).** Questo documento conserva la storia della prima
+> proposta. Il disegno approvato è
+> [`2026-08-24-evidence-restructuring-design.md`](2026-08-24-evidence-restructuring-design.md)
+> e il relativo piano esecutivo è
+> [`2026-08-24-evidence-restructuring.md`](2026-08-24-evidence-restructuring.md).
+
 ## Contesto e decisioni prese

 ThothII ha già due livelli separati che non si parlano:
@@ -0,0 +1,659 @@
+# Ristrutturazione delle Evidence — disegno approvato
+
+**Stato:** approvato il 24 agosto 2026
+**Sostituisce:** `docs/plans/2026-08-18-evidence-canonica-design.md`
+**Ambito:** authoring, revisione, pubblicazione, indicizzazione e uso runtime delle Evidence
+
+## 1. Obiettivo
+
+Questo disegno introduce un processo semplice e verificabile per trasformare documenti
+di partenza non necessariamente ben organizzati in Evidence strutturate, revisionabili
+da una persona e ricercabili in modo efficace da ThothII.
+
+La soluzione deve:
+
+1. partire dai testi oggi presenti nel repository del workspace;
+2. riorganizzarli senza inventare informazioni;
+3. conservare sorgenti e risultato nello stesso repository Git;
+4. affidare a Git la revisione e l'approvazione umana;
+5. indicizzare soltanto le versioni approvate;
+6. sfruttare Qdrant senza moltiplicare collezioni e componenti;
+7. inserirsi nel workflow modulare attuale, nel quale Evidence è un modulo autonomo.
+
+La fonte di verità rimane sempre il repository Git. Qdrant è un indice derivato che può
+essere ricostruito.
+
+## 2. Principio guida
+
+Il processo è diviso in due percorsi distinti.
+
+- Il **percorso di authoring** prepara e revisiona le Evidence fuori dalle sessioni
+  domanda→SQL.
+- Il **percorso runtime** è in sola lettura e consulta esclusivamente Evidence già
+  pubblicate.
+
+```mermaid
+flowchart LR
+    S["Testi sorgente"] --> P["Pre-processing"]
+    P --> C["Evidence curate"]
+    C --> R["Revisione Git umana"]
+    R --> M["Merge e attivazione revisione"]
+    M --> I["Indicizzazione atomica"]
+    I --> Q["Qdrant: indice attivo"]
+    Q --> E["Evidence Module"]
+    E --> W["Workflow F1-F8"]
+```
+
+Una sessione può proporre una nuova formula o segnalare una lacuna, ma non modifica il
+repository e non pubblica autonomamente conoscenza.
+
+## 3. Struttura nel repository del workspace
+
+Ogni workspace adotta questa struttura sotto la propria directory `evidence/`:
+
+```text
+evidence/
+├── README.md
+├── source/
+│   └── ... documenti originali ...
+├── curated/
+│   ├── glossary/
+│   ├── domain/
+│   ├── enum/
+│   ├── example/
+│   ├── mapping/
+│   ├── normalization/
+│   ├── formula/
+│   └── reference/
+├── manifest.yaml
+└── evaluation.yaml
+```
+
+### 3.1 `source/`
+
+Contiene i documenti originali. La prima versione accetta file Markdown, testo UTF-8 e
+file `.sql.md`. Un URL può essere descritto in un documento, ma non viene scaricato né
+interpretato automaticamente.
+
+I sorgenti vengono preservati: il pre-processing non li riscrive.
+
+### 3.2 `curated/`
+
+Contiene una Evidence Unit per file. Le sottodirectory rendono immediatamente visibile
+il tipo anche a un lettore umano. Il campo `kind` nel documento resta comunque
+obbligatorio: la directory aiuta la navigazione, il campo è il contratto macchina.
+
+### 3.3 `manifest.yaml`
+
+È gestito dal comando di preparazione e registra:
+
+- hash di ciascun sorgente;
+- Evidence Unit derivate da quel sorgente;
+- identificatori stabili;
+- versione del processo di preparazione;
+- unità orfane da controllare.
+
+Il manifest permette di elaborare soltanto ciò che è cambiato. Non sostituisce Git e
+non contiene lo stato di approvazione.
+
+### 3.4 `evaluation.yaml`
+
+Contiene inizialmente circa venti domande rappresentative e gli identificatori delle
+Evidence che ci aspettiamo di recuperare. È il controllo minimo per evitare di
+considerare “migliore” una ricerca soltanto perché sembra sofisticata.
+
+## 4. Una struttura comune, otto tipi distinti
+
+La separazione tra tipi non viene eliminata. Ogni documento ha un involucro comune e
+una parte specializzata determinata da `kind`.
+
+### 4.1 Campi comuni
+
+```yaml
+schema_version: 1
+id: formula:fascia-pediatrica
+title: Fascia pediatrica
+kind: formula
+purposes:
+  - sql_generation
+  - schema_linking
+applies_to:
+  concepts:
+    - fascia pediatrica
+  tables:
+    - clinical.patient
+  columns:
+    - clinical.patient.birth_date
+language: it
+provenance:
+  source_file: source/10-domini-clinici/paziente.md
+  source_sha256: sha256:0123456789abcdef...
+review_items: []
+```
+
+I campi hanno ruoli diversi:
+
+- `kind` dice **che cosa contiene** il documento;
+- `purposes` dice **in quali attività può essere utile**;
+- `applies_to` dice **a quali concetti o elementi del database si riferisce**;
+- `provenance` permette di risalire al testo di origine;
+- `review_items` rende visibili i dubbi ancora da risolvere.
+
+### 4.2 Tipi iniziali
+
+| `kind` | Contenuto | Esempio d'uso |
+| --- | --- | --- |
+| `glossary` | Definizione, sinonimi e varianti linguistiche | Capire che “ricovero” e “degenza” possono indicare lo stesso concetto |
+| `domain` | Regole e vincoli del dominio | Interpretare correttamente un episodio clinico |
+| `enum` | Valori ammessi e loro significato | Tradurre “dimesso” nel codice memorizzato nel DWH |
+| `example` | Domanda esemplificativa e interpretazione attesa | Riconoscere una formulazione già documentata |
+| `mapping` | Collegamento fra concetto e schema fisico | Individuare tabella e colonne pertinenti |
+| `normalization` | Regole di normalizzazione | Uniformare codici, date o varianti testuali |
+| `formula` | Espressione SQL riutilizzabile e relativi input | Calcolare la fascia pediatrica dalla data di nascita |
+| `reference` | Un riferimento esterno che è esso stesso contenuto recuperabile | Proporre all'utente il link a una specifica linea guida |
+
+Un URL che documenta un'altra Evidence appartiene alla sua `provenance`. Un URL che
+deve essere recuperato come risposta autonoma è invece una Evidence `reference`.
+
+### 4.3 Dati specifici per tipo
+
+La parte specializzata è una unione discriminata: ogni `kind` ammette e richiede campi
+diversi. Alcuni esempi:
+
+```yaml
+# formula
+formula:
+  concept: fascia pediatrica
+  columns:
+    - clinical.patient.birth_date
+  sql: |
+    CASE WHEN age < 18 THEN 'pediatrica' ELSE 'adulta' END
+```
+
+```yaml
+# reference
+reference:
+  url: https://example.org/linea-guida
+  label: Linea guida clinica
+  description: Criteri usati per classificare gli episodi.
+```
+
+```yaml
+# enum
+enum:
+  column: clinical.episode.discharge_status
+  values:
+    D: dimesso
+    T: trasferito
+```
+
+I tipi restano quindi sfruttabili sia in validazione sia in ricerca. Una formula non è
+un semplice testo etichettato: possiede obbligatoriamente un concetto, le colonne di
+input e SQL valido come contenuto strutturato.
+
+## 5. Pre-processing dei testi sorgente
+
+Il comando concettuale è:
+
+```text
+tht evidence prepare <workspace-root>
+```
+
+Per l'utente è una sola operazione. Internamente esegue quattro passaggi.
+
+### 5.1 Estrazione deterministica
+
+Il sistema:
+
+- individua i file ammessi in `evidence/source/`;
+- verifica dimensione, codifica UTF-8 e percorso sicuro;
+- calcola l'hash del contenuto;
+- confronta il risultato con `manifest.yaml`;
+- carica, quando esiste, la precedente versione curata collegata al sorgente.
+
+Un sorgente invariato non viene nuovamente elaborato.
+
+### 5.2 Normalizzazione deterministica
+
+Prima del modello vengono normalizzati soltanto aspetti meccanici:
+
+- terminatori di riga e Unicode;
+- spaziatura e intestazioni palesemente riconoscibili;
+- elenchi, tabelle, blocchi SQL e URL;
+- metadati già esplicitamente presenti;
+- riferimenti a tabelle e colonne riconoscibili.
+
+Questa fase non interpreta il significato e non inventa strutture semantiche.
+
+### 5.3 Una sola ristrutturazione assistita dal modello
+
+Per ogni sorgente cambiato il modello riceve:
+
+- il testo normalizzato;
+- gli otto schemi ammessi;
+- le regole “non inventare” e “segnala il dubbio”;
+- le precedenti Evidence curate derivate da quel sorgente;
+- gli identificatori già assegnati.
+
+Può:
+
+- assegnare titoli;
+- classificare il tipo;
+- separare un sorgente in più Evidence Unit;
+- riordinare e riscrivere per chiarezza;
+- compilare campi strutturati con fatti presenti nel sorgente.
+
+Non può:
+
+- fondere automaticamente sorgenti diversi;
+- aggiungere fatti non documentati;
+- risolvere silenziosamente un'ambiguità;
+- cancellare un'unità precedentemente revisionata.
+
+Pi viene usato in modalità non interattiva e senza strumenti di scrittura. È un
+dettaglio interno del comando, non una nuova tipologia di sessione ThothII.
+
+### 5.4 Validazione deterministica
+
+L'output del modello non viene scritto direttamente. Viene prima controllato:
+
+- schema comune e schema specifico del `kind`;
+- unicità e stabilità degli identificatori;
+- appartenenza alle enumerazioni ammesse;
+- esistenza e hash del sorgente;
+- correttezza sintattica di URL, tabelle, colonne e SQL dove applicabile;
+- assenza di credenziali;
+- coerenza tra directory e `kind`;
+- assenza di collegamenti a sorgenti diversi nella stessa unità.
+
+Esistono tre esiti.
+
+| Esito | Comportamento |
+| --- | --- |
+| Valido | Il documento è pronto per la revisione Git |
+| Valido con dubbi | Il documento viene scritto con `review_items`; non è indicizzabile |
+| Non valido | Il documento non è pubblicabile e il rapporto spiega l'errore |
+
+Un dubbio reale può essere mantenuto soltanto se il revisore lo trasforma in una
+limitazione esplicita del contenuto e svuota `review_items`.
+
+## 6. Aggiornamenti incrementali e protezione delle correzioni umane
+
+La precedente versione curata è un input, non un file usa-e-getta. In questo modo il
+modello può proporre una modifica minima senza ricominciare da zero.
+
+Il comando:
+
+- si rifiuta di operare se `evidence/curated/` o `evidence/manifest.yaml` contengono
+  modifiche Git non salvate;
+- mantiene gli ID associati a contenuti che rappresentano ancora la stessa unità;
+- mostra come diff le variazioni proposte;
+- non modifica i file derivati da sorgenti invariati;
+- segnala come orfana un'unità il cui sorgente è stato rimosso;
+- non elimina mai automaticamente un'unità orfana.
+
+Git fornisce confronto, revisione, cronologia e recupero. Non viene introdotto un
+database di authoring parallelo.
+
+## 7. Revisione e pubblicazione
+
+Il flusso di pubblicazione è:
+
+```text
+prepare → revisione Git → validate → merge → attivazione workspace
+        → preprocess evidence → nuova generazione Qdrant attiva
+```
+
+### 7.1 Approvazione umana
+
+L'approvazione coincide con il normale processo Git del repository del workspace:
+
+1. il curatore esegue `prepare` in un clone di authoring;
+2. legge i documenti e il diff;
+3. corregge i contenuti;
+4. esegue `tht evidence validate`;
+5. apre o approva la pull request;
+6. esegue il merge.
+
+La prima versione non crea automaticamente branch, commit o pull request.
+
+### 7.2 Quando un documento diventa Published Evidence
+
+Una Curated Evidence diventa Published Evidence soltanto quando:
+
+- appartiene a una revisione Git approvata e pulita;
+- la revisione è stata attivata dal registry di ThothII;
+- non contiene `review_items` irrisolti;
+- l'intero corpus supera la validazione;
+- la generazione Qdrant viene pubblicata atomicamente.
+
+Il descriptor filesystem deve indicizzare solo `curated/**/*.md`. I sorgenti e i file
+di supporto restano materializzati per tracciabilità, ma non entrano nell'indice.
+
+## 8. Indicizzazione e generazioni
+
+L'indicizzazione continua a usare il meccanismo già implementato dal modulo Evidence:
+
+1. legge la radice materializzata della revisione Git attiva;
+2. valida nuovamente tutte le Evidence;
+3. costruisce Evidence Fragment secondo sezioni semantiche;
+4. genera le rappresentazioni dense;
+5. chiede a Qdrant di generare la rappresentazione lessicale BM25;
+6. carica i punti con la nuova `vector_generation`;
+7. verifica manifest, conteggi e leggibilità;
+8. rende attiva la nuova generazione;
+9. conserva le generazioni precedenti previste dalla policy.
+
+Se uno dei passaggi fallisce, la generazione precedente rimane attiva. I punti caricati
+parzialmente vengono compensati secondo il meccanismo transazionale già esistente.
+
+## 9. Qdrant spiegato senza presupporre conoscenze vettoriali
+
+### 9.1 L'analogia della biblioteca
+
+Si può immaginare Qdrant come il catalogo di una biblioteca.
+
+- Le **Evidence Unit** sono i documenti completi conservati negli scaffali Git.
+- Gli **Evidence Fragment** sono le schede del catalogo relative alle singole sezioni.
+- I **vettori** sono rappresentazioni numeriche usate per confrontare una domanda con
+  quelle schede.
+- Il **payload** è l'insieme delle etichette leggibili: tipo, scopo, tabelle, colonne,
+  revisione e documento di origine.
+
+Qdrant non decide se una Evidence è vera e non sostituisce il documento. Aiuta soltanto
+a trovare rapidamente le schede più promettenti.
+
+### 9.2 Ricerca per significato: vettore dense
+
+La rappresentazione dense descrive il significato generale di una frase. Permette, per
+esempio, di avvicinare “pazienti minorenni” a “fascia pediatrica” anche quando le parole
+non coincidono.
+
+È utile per il linguaggio naturale, ma può essere meno precisa con codici, acronimi,
+nomi di colonne e formule.
+
+### 9.3 Ricerca per parole e identificatori: BM25 sparse
+
+La rappresentazione sparse conserva il peso delle parole presenti. È adatta a termini
+come `ICD-10`, `discharge_status`, `ADT`, un valore enum o un nome esatto di colonna.
+
+Qdrant 1.18.2 può generare questa rappresentazione direttamente sul server usando
+`qdrant/bm25`; per il corpus italiano si passa `language: italian` sia durante il
+caricamento sia durante la ricerca. Non serve aggiungere FastEmbed o un nuovo servizio.
+
+Il nome “sparse” significa soltanto che, tra moltissime parole possibili, ogni testo ne
+usa poche. Qdrant mantiene anche l'IDF: una parola rara pesa più di una parola presente
+quasi ovunque.
+
+### 9.4 Perché combinarle
+
+Una domanda può richiedere contemporaneamente comprensione e precisione lessicale:
+
+> “Qual è la formula per distinguere la fascia pediatrica usando
+> `patient.birth_date`?”
+
+La ricerca dense riconosce il concetto; BM25 riconosce con forza “formula” e il nome
+della colonna. Qdrant esegue entrambe e produce due graduatorie.
+
+### 9.5 Reciprocal Rank Fusion
+
+Reciprocal Rank Fusion, o RRF, combina le due graduatorie usando la posizione dei
+risultati invece di confrontare direttamente punteggi di natura diversa.
+
+In termini pratici:
+
+- un documento alto in entrambe le liste sale;
+- un documento molto forte in una sola lista può comunque emergere;
+- non occorre inventare una conversione fragile fra “similarità semantica” e “punteggio
+  delle parole”.
+
+Si parte con i pesi predefiniti. Pesi diversi saranno introdotti soltanto se
+`evaluation.yaml` dimostrerà un miglioramento.
+
+### 9.6 Il ruolo dei metadati
+
+Ogni punto Qdrant conserva almeno:
+
+```text
+workspace_id
+workspace_revision
+vector_generation
+record_kind
+evidence_id
+evidence_kind
+purposes
+concepts
+tables
+columns
+language
+source_file
+source_sha256
+fragment_ordinal
+```
+
+I metadati hanno due usi:
+
+- workspace, revisione e generazione sono filtri obbligatori di sicurezza;
+- tipo, scopo e ambito orientano la ricerca oppure diventano filtri quando il chiamante
+  formula una richiesta esplicita.
+
+Durante la generazione SQL, per esempio, `formula` e `mapping` ricevono priorità, ma una
+regola `domain` molto pertinente può ancora apparire. Se il workflow chiede
+esplicitamente soltanto formule, `evidence_kind=formula` diventa invece un filtro
+vincolante.
+
+### 9.7 Perché non creare una collezione per tipo
+
+Una domanda spesso attraversa più tipi: una formula può dipendere da un mapping, da un
+enum e da una regola di dominio. Collezioni separate richiederebbero più interrogazioni,
+fusione applicativa e più operazioni di manutenzione.
+
+La soluzione usa la collezione semantica già posseduta dal workspace e aggiunge vettori
+denominati `dense` e `bm25`. I payload indicizzati distinguono i tipi. È più semplice e
+permette a Qdrant di eseguire ricerca ibrida e filtri nella stessa Query API.
+
+### 9.8 Perché indicizzare frammenti ma restituire unità
+
+Un documento lungo può contenere sezioni diverse. Un unico vettore ne diluirebbe il
+significato; frammenti arbitrari di lunghezza fissa spezzerebbero invece formule o
+regole.
+
+La divisione segue intestazioni e campi tipizzati. Qdrant trova i frammenti, poi
+l'Evidence Module li raggruppa per `evidence_id` e restituisce l'unità completa con
+provenienza e citazione.
+
+### 9.9 Cosa non introduciamo nella prima versione
+
+- una collezione per ogni tipo;
+- ColBERT o multivettori late-interaction;
+- un reranker basato su un altro modello;
+- pesi RRF regolati a mano senza misurazioni;
+- un servizio separato per BM25;
+- ricerca automatica sul web.
+
+Queste possibilità rimangono future ottimizzazioni, non prerequisiti.
+
+Riferimenti tecnici ufficiali:
+
+- [Qdrant: Text Search](https://qdrant.tech/documentation/search/text-search/)
+- [Qdrant: server-side BM25](https://qdrant.tech/documentation/inference/inference-bm25/)
+- [Qdrant: Hybrid Queries e RRF](https://qdrant.tech/documentation/search/hybrid-queries/)
+- [Qdrant: payload indexing](https://qdrant.tech/documentation/manage-data/indexing/)
+- [Qdrant: multitenancy](https://qdrant.tech/documentation/manage-data/multitenancy/)
+
+## 10. Contratto di ricerca del modulo Evidence
+
+Il workflow non costruisce query Qdrant. Usa una sola interfaccia concettuale:
+
+```python
+search(
+    query: str,
+    purpose: EvidencePurpose,
+    context: EvidenceSearchContext,
+) -> list[EvidenceResult]
+```
+
+`EvidenceSearchContext` può specificare tabelle, colonne, concetti e, solo quando
+necessario, tipi obbligatori.
+
+Il modulo Evidence possiede interamente:
+
+- generazione della query dense;
+- query BM25 con lingua coerente;
+- filtri su revisione e generazione;
+- RRF;
+- preferenze per `kind`, `purpose` e `applies_to`;
+- raggruppamento dei frammenti;
+- risoluzione di provenienza e citazioni;
+- controllo della revisione attiva.
+
+Il workflow riceve candidati spiegabili, mai verità automatiche.
+
+## 11. Inserimento nel workflow modulare ThothII
+
+Evidence rimane un modulo autonomo con due responsabilità pubbliche.
+
+### 11.1 Authoring
+
+```text
+prepare → validate → evaluate
+```
+
+Questa superficie è usata dal curatore e non dalle sessioni.
+
+### 11.2 Runtime
+
+```text
+search → resolve citation → project into session
+```
+
+F1, F3 e F4 passano `purpose` e contesto al modulo. Non conoscono collezioni, nomi di
+vettori, generazioni o sintassi Qdrant.
+
+Le istruzioni Pi relative alla consultazione delle Evidence vengono spostate in
+frammenti del modulo Evidence e poi proiettate nel `SKILL.md` generato, seguendo il
+meccanismo modulare già usato da Disambiguation e Memory.
+
+## 12. Formule
+
+Le formule approvate oggi presenti nello store `formulas/*.sql.md` vengono convertite in
+Evidence `kind: formula`. Dopo la migrazione non esistono due archivi runtime.
+
+Una nuova formula scoperta in F4 segue invece questo percorso:
+
+```text
+sessione → Formula proposal nell'artefatto di sessione
+         → importazione di manutenzione
+         → Curated Evidence formula
+         → revisione Git
+         → Published Evidence
+```
+
+Le decisioni `concept_formula_approved` e `concept_formula_rejected` continuano a
+descrivere la scelta fatta nella singola sessione. Non equivalgono alla pubblicazione
+globale nel workspace.
+
+## 13. Comportamento in caso di errore
+
+### 13.1 Durante l'authoring
+
+- un file non UTF-8, troppo grande o strutturalmente invalido produce un errore chiaro;
+- un dubbio semantico produce un `review_item`;
+- un albero Git sporco impedisce la sovrascrittura delle modifiche umane;
+- un sorgente rimosso produce un'unità orfana, non una cancellazione.
+
+### 13.2 Durante l'indicizzazione
+
+- la nuova generazione viene preparata senza toccare quella attiva;
+- un caricamento o una verifica falliti non cambiano il puntatore attivo;
+- i dati parziali vengono rimossi quando possibile e comunque non sono leggibili dal
+  runtime perché manca l'attivazione.
+
+### 13.3 Durante una sessione
+
+Se Qdrant, il corpus attivo o la revisione attesa non sono disponibili:
+
+- il risultato Evidence è vuoto;
+- viene emesso un avviso esplicito;
+- non vengono usate revisioni precedenti;
+- la sessione può continuare con gli altri meccanismi e con i normali gate umani.
+
+Questo è il comportamento fail-closed già presente e viene preservato.
+
+## 14. Valutazione minima
+
+`tht evidence evaluate` esegue le domande in `evaluation.yaml` contro l'indice attivo e
+riporta almeno:
+
+- quante domande hanno trovato una Evidence attesa nei primi 5 e nei primi 10 risultati;
+- quali tipi attesi sono mancati;
+- quali query non hanno prodotto risultati;
+- revisione Git, generazione e configurazione di ricerca usate.
+
+La prima baseline deve essere salvata prima di regolare pesi o introdurre altri modelli.
+Il comando non modifica l'indice.
+
+## 15. Comandi e responsabilità
+
+| Comando | Dove opera | Scrive |
+| --- | --- | --- |
+| `tht evidence prepare <workspace-root>` | clone Git di authoring | `curated/`, `manifest.yaml` |
+| `tht evidence validate <workspace-root>` | clone Git o CI | nulla |
+| `tht evidence evaluate ...` | indice attivo | solo rapporto su stdout/JSON |
+| `tht ... workspace preprocess evidence` | installazione/runtime | nuova generazione corpus e Qdrant |
+
+`prepare` non crea commit. `preprocess evidence` non modifica il repository Git.
+
+## 16. Migrazione iniziale del workspace PSD
+
+Il corpus attuale comprende 36 file Markdown organizzati in glossario, domini clinici,
+enum, esempi NLQ, mapping e normalizzazione. La migrazione avviene così:
+
+1. spostare gli originali sotto `evidence/source/`, conservandone la gerarchia;
+2. eseguire `prepare` e generare `curated/`;
+3. revisionare tutte le unità e risolvere i `review_items`;
+4. importare eventuali formule approvate come `kind: formula`;
+5. compilare circa venti query in `evaluation.yaml`;
+6. configurare il descriptor con `patterns: ["curated/**/*.md"]`;
+7. validare, fare merge e attivare la revisione;
+8. ricostruire in modo controllato la collezione per il nuovo contratto dense+BM25;
+9. eseguire `preprocess evidence`;
+10. salvare la baseline di valutazione e svolgere una verifica umana F1/F3/F4.
+
+Non serve mantenere v1 e v2 attivi contemporaneamente nel runtime: Git conserva la
+vecchia revisione e il meccanismo delle generazioni conserva il rollback dell'indice.
+
+## 17. Criteri di accettazione
+
+La prima versione è completa quando:
+
+1. un sorgente poco strutturato produce una o più unità tipizzate senza perdere la
+   provenienza;
+2. sorgenti invariati sono un no-op;
+3. modifiche umane non vengono sovrascritte;
+4. un `review_item` impedisce l'indicizzazione;
+5. tutte le otto varianti hanno validazione specifica;
+6. le formule approvate sono ricercate tramite lo stesso modulo delle altre Evidence;
+7. soltanto `curated/**/*.md` entra nel corpus runtime;
+8. la collezione Qdrant espone `dense` e `bm25` e gli indici payload richiesti;
+9. la Query API esegue i due prefetch e la fusione RRF;
+10. risultati di frammenti della stessa unità vengono raggruppati;
+11. una revisione o generazione non corrispondente restituisce zero Evidence e un
+    avviso;
+12. il set di valutazione produce un rapporto ripetibile;
+13. una sessione completa continua a funzionare anche con Evidence non disponibili;
+14. documentazione e comandi descrivono lo stesso contratto.
+
+## 18. Decisioni rinviate
+
+Saranno considerate soltanto dopo la baseline:
+
+- pesi RRF diversi da quelli predefiniti;
+- reranking;
+- ColBERT o multivettori;
+- acquisizione automatica di PDF, Word, HTML o pagine web;
+- creazione automatica di branch e pull request;
+- fusione assistita di Evidence provenienti da sorgenti diversi.
+
+Queste esclusioni mantengono la prima implementazione comprensibile, realizzabile,
+manutenibile e documentabile.