Evidence: sorgenti, preparazione e revisione

Questa pagina descrive il ciclo completo delle Evidence di workspace: dove si trova il materiale originale, come si producono le unità curate, quando diventano disponibili al runtime e quali responsabilità hanno autore e revisore.

Regola di pubblicazione

Il workspace repository è la sorgente versionata. ThothII lo legge, lo valida e pubblica una generazione atomica. Non modifica, committa o pusha il repository dell'autore.

Una Evidence diventa utilizzabile dal workflow solo quando:

il materiale originale è presente in source/;
l'unità derivata è presente in curated/;
il manifest collega unità, sorgente e hash;
la validazione non produce errori o review item irrisolti;
la pipeline di preprocessing costruisce una generazione indicizzata e la attiva.

Una proposta generata durante una sessione non è automaticamente Evidence pubblicata. Il modello può proporre una formula o una spiegazione, ma un curatore deve importarla, revisionarla e pubblicarla nel repository prima che un'altra sessione possa recuperarla.

Dove deve stare il primo sorgente

Per il filesystem Evidence v2, il primo sorgente autorevole deve stare nella directory source/ del repository di workspace. curated/ contiene il risultato revisionato e indicizzato, non il materiale originale.

<workspace-repository>/
├── source/                 # materiale originale, preservato
│   └── <dominio>/<file>.md
├── curated/                # Evidence Units revisionate
│   └── <dominio>/<unit>.md
├── manifest.yaml           # legami, hash e metadati della preparazione
└── example/                # esempi e materiale di supporto

Il descriptor del workspace deve dichiarare evidence.schema_version: 2 e, per una sorgente filesystem, usare esattamente:

evidence:
  schema_version: 2
  source:
    type: filesystem
    uri: "<workspace.id>/evidence"
    patterns:
      - "curated/**/*.md"

La configurazione storica può esporre source_root, per esempio ${THT_DOCS_ROOT} o /data. Per la struttura v2 il pattern runtime deve selezionare solo curated/**/*.md. Non bisogna indicizzare direttamente source/, mescolare source/ e curated/, usare glob più ampi o includere file non Markdown.

HTTP e S3 sono adapter distinti. Non usano la struttura filesystem source/ e curated/, ma devono comunque fornire una provenienza stabile, senza credenziali negli URI e con il contratto specifico dell'adapter.

Come deve essere fatta un'unità curata

Le unità Markdown lette dal loader storico della CLI hanno frontmatter YAML. I campi minimi sono id e title; tier, status, sources, tables, concepts descrivono il contesto dell'unità.

---
id: evidence:autonomia-batteria
title: Autonomia nominale della batteria
tier: structural
status: reviewed
sources:
  - source/domain/bicycle.md
tables:
  - bicycle_model
concepts:
  - concept:battery-range
---

Definizione verificata dell'autonomia nominale per modello di bicicletta elettrica.

La regola deve essere abbastanza atomica da poter essere citata senza ricostruire
un intero capitolo. Il testo deve distinguere definizione, condizioni e limiti.

Le unità curate devono essere atomiche, leggibili da un secondo revisore e sostenute dal sorgente. I riferimenti di provenienza devono permettere di risalire al file originale e alla porzione che supporta l'affermazione. Non inserire segreti, token, password o credenziali nei metadati o negli URI.

La forma canonica moderna conserva anche il tipo di Evidence, la provenienza, gli estratti di supporto, source_file e source_sha256. Il contratto canonico rifiuta campi sconosciuti, metadati mutabili e URI con credenziali. Gli identificatori devono restare stabili anche quando cambia il tipo di unità.

Preparazione: dal sorgente alla generazione attiva

flowchart TD
    SRC["source/DOMINIO/*.md\nmateriale originale"] --> PREP["tht evidence prepare\npreparazione candidata"]
    PREP --> CAND["curated/DOMINIO/*.md\nunità proposte o aggiornate"]
    CAND --> VAL["tht evidence validate\ncontrolli di struttura e legami"]
    VAL -->|errori o review item| FIX["Correzioni dell'autore\ne revisione"]
    FIX --> PREP
    VAL -->|publishable| COMMIT["Commit del repository\nauthoring clone"]
    COMMIT --> ING["tht preprocess evidence\nnormalizzazione e chunking"]
    ING --> BM25["Indice BM25"]
    ING --> VEC["Embedding e vector store"]
    BM25 --> GEN["Generazione candidata"]
    VEC --> GEN
    GEN --> ACT["Generazione attiva"]
    ACT --> RUNTIME["Ricerca Evidence nel workflow"]

La preparazione può ristrutturare sorgenti cambiate, ma non pubblica da sola. prepare produce una proposta e può indicare il documento coinvolto in caso di errore. validate non scrive né pubblica. La pubblicazione della revisione è un'azione del curatore. Il runtime legge una revisione completa e validata, poi la pipeline crea una generazione versionata. L'attivazione è atomica: una generazione precedente resta disponibile secondo la policy di retention.

La ricerca runtime usa il recupero ibrido. Il ramo denso usa gli embedding, il ramo BM25 usa la ricerca lessicale e la fusione deterministica ordina i risultati. L'unità pubblicata conserva la provenienza, che il modello deve citare quando usa l'evidence.

Responsabilità del creatore

Il creatore prepara il materiale e rende verificabile ogni unità. In pratica deve:

mettere il materiale originale in source/, senza sovrascriverne il significato durante la curatela;
suddividere il contenuto in unità atomiche, una regola o definizione per unità quando possibile;
assegnare un identificatore stabile e un titolo comprensibile;
indicare la provenienza, le tabelle e i concetti coinvolti quando sono noti;
mantenere il testo nella lingua del workspace;
separare fatti, regole, esempi, formule e limiti;
riportare gli estratti che sostengono l'unità, senza estendere la conclusione oltre il sorgente;
eseguire tht evidence prepare e tht evidence validate;
risolvere ogni errore e ogni review item prima di proporre il commit;
fornire al revisore il contesto necessario, inclusi i cambiamenti nel sorgente e il motivo di eventuali rinomini o ritiri.

Il creatore non deve:

scrivere direttamente nel corpus attivo di produzione;
trattare una proposta del modello come fatto verificato;
eliminare un'unità solo perché non è più supportata senza registrare il ritiro o il relink;
inserire credenziali nei metadati, nei file o negli URL di provenienza;
modificare manualmente manifest, hash o generazioni per far passare la validazione.

Responsabilità del revisore

Il revisore non approva la forma del testo soltanto perché è chiara. Verifica il rapporto tra sorgente, unità e uso previsto. Per ogni unità deve controllare:

che il sorgente indicato esista nella revisione esaminata;
che l'estratto sostenga davvero l'affermazione;
che l'unità non unisca regole incompatibili o concetti indipendenti;
che tabelle, colonne e concetti siano identificati correttamente;
che l'identificatore sia stabile e non duplichi un'altra unità;
che il testo distingua definizione, condizione, eccezione ed esempio;
che non contenga informazioni sensibili o dettagli non presenti nel sorgente;
che la valutazione del retrieval copra le query rilevanti e non nasconda risultati vuoti.

Il revisore può approvare, chiedere modifiche, rigettare, ritirare o riallacciare un'unità a un nuovo sorgente. Un ritiro deve essere esplicito. Un relink deve indicare il nuovo file e deve lasciare una traccia verificabile della decisione. L'approvazione non comporta la pubblicazione immediata: il repository deve passare la validazione e la generazione deve superare la valutazione prima dell'attivazione.

Comandi disponibili

I comandi di authoring operano sul repository di workspace e non pubblicano direttamente.

# Prepara le sorgenti cambiate. Non committa e non pubblica.
tht evidence prepare <workspace-root>

# Rielabora tutte le sorgenti con la pipeline installata.
tht evidence prepare <workspace-root> --upgrade

# Valida struttura, manifest, legami e review item.
tht evidence validate <workspace-root>

# Restituisce JSON per CI o strumenti automatici.
tht evidence validate <workspace-root> --json

# Valuta il retrieval su una generazione o sulla generazione attiva.
tht evidence evaluate <workspace-root> --config <workspace-config>
tht evidence evaluate <workspace-root> --config <workspace-config> --generation <id> --json

# Risolve una unità senza pubblicare: ritiro oppure nuovo collegamento al sorgente.
tht evidence resolve <workspace-root> evidence:<id> --retire
tht evidence resolve <workspace-root> evidence:<id> --source source/domain/nuovo.md

# Materializza e indicizza una generazione versionata.
tht preprocess evidence --config <workspace-config>

# Esecuzione a secco e ripresa di un job, quando supportate dalla configurazione.
tht preprocess evidence --config <workspace-config> --dry-run
tht preprocess evidence --config <workspace-config> --resume <run-id>

evidence prepare, evidence validate e evidence resolve richiedono il path del repository. preprocess evidence usa invece la configurazione del workspace, perché deve conoscere embedding, vector store, policy di retention e artifact directory.

I codici di uscita sono parte del contratto operativo: evidence validate usa 0 quando il corpus è pubblicabile, 1 per errori di validazione e 3 quando restano solo elementi da revisionare o unità orfane. Con --json, stdout deve contenere solo JSON valido.

Formule e proposte di sessione

Le formule hanno un formato distinto dalle Evidence documentali. Una formula proposta durante una sessione può essere citata nella proposta corrente, ma non entra nel corpus runtime, non riceve un ID evidence: utilizzabile e non scrive nel repository. Per diventare pubblicata deve seguire lo stesso percorso di importazione, revisione e preprocessing delle altre unità.

10 KiB Raw Blame History