mptyl/ThothII
1
0
Fork 0
Code Issues 25 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

feat: complete evidence restructuring worktree

Browse Source
This commit is contained in:
Codex
2026-08-26 11:39:02 +02:00
parent a54d4769dd
commit 38f02cfd08
56 changed files with 1981 additions and 1801 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/evidence.md
+118 -97
View File
@@ -1,36 +1,36 @@
# Evidence: sorgenti, preparazione e revisione
# Evidence: sources, preparation, and review
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.
This page describes the complete workspace Evidence lifecycle: where original material lives, how curated units are produced, when they become available at runtime, and what the author and reviewer are responsible for.
## Regola di pubblicazione
## Publication rule
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.
The workspace repository is the versioned source. ThothII reads it, validates it, and publishes an atomic generation. It does not modify, commit, or push the author's repository.
Una Evidence diventa utilizzabile dal workflow solo quando:
Evidence becomes available to the workflow only when:
1. il materiale originale è presente in `source/`;
2. l'unità derivata è presente in `curated/`;
3. il manifest collega unità, sorgente e hash;
4. la validazione non produce errori o review item irrisolti;
5. la pipeline di preprocessing costruisce una generazione indicizzata e la attiva.
1. the original material is in `source/`;
2. the derived unit is in `curated/`;
3. the manifest links the unit, source, and hash;
4. validation finds no errors or unresolved review items;
5. preprocessing builds and activates an indexed generation.
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.
A proposal generated during a session is not automatically published Evidence. The model may propose a formula or explanation, but a curator must import, review, and publish it in the repository before another session can retrieve it.
## Dove deve stare il primo sorgente
## Where the original source belongs
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.
For filesystem Evidence v2, the authoritative original source must be in the `source/` directory of the workspace repository. `curated/` contains the reviewed and indexed result, not the original material.
```text
<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
│ └── <domain>/<file>.md
├── curated/ # reviewed Evidence Units
│ └── <domain>/<unit>.md
├── manifest.yaml # preparation links, hashes, and metadata
└── example/ # examples and supporting material
```
Il descriptor del workspace deve dichiarare `evidence.schema_version: 2` e, per una sorgente filesystem, usare esattamente:
The workspace descriptor must declare `evidence.schema_version: 2` and use exactly this configuration for a filesystem source:
```yaml
evidence:
@@ -42,141 +42,162 @@ evidence:
- "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.
The legacy configuration may expose `source_root`, such as `${THT_DOCS_ROOT}` or `/data`. For the v2 structure, the runtime pattern must select only `curated/**/*.md`. Do not index `source/` directly, mix `source/` and `curated/`, use broader globs, or include non-Markdown files.
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.
HTTP and S3 are separate adapters. They do not use the filesystem structure `source/` and `curated/`, but they must still provide stable provenance, without credentials in URIs, under the adapter-specific contract.
## Come deve essere fatta un'unità curata
## What a curated unit must contain
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à.
Canonical Curated Evidence v2 keeps short machine metadata in YAML frontmatter and renders the
reviewable content as real Markdown. The body layout is deterministic for each Evidence kind:
prose uses sections and paragraphs, identifiers use code lists, enum values use tables, formulas
use fenced SQL, supporting excerpts use blockquotes, and unresolved review items use dedicated
blocks.
```markdown
---
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
schema_version: 2
id: evidence:fascia-pediatrica
title: Fascia pediatrica
kind: domain
purposes:
- disambiguation
language: it
provenance:
source_file: source/domain/paziente.md
source_sha256: sha256:0000000000000000000000000000000000000000000000000000000000000000
---
Definizione verificata dell'autonomia nominale per modello di bicicletta elettrica.
# Fascia pediatrica
La regola deve essere abbastanza atomica da poter essere citata senza ricostruire
un intero capitolo. Il testo deve distinguere definizione, condizioni e limiti.
## Regola
La fascia pediatrica comprende i pazienti con età inferiore a 18 anni.
## Estratti di supporto
> I pazienti sotto i 18 anni sono pediatrici.
```
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.
The actual files also contain invisible `tht:` comments delimiting typed fields. Curators edit the
visible Markdown between those markers; removing or duplicating markers makes validation fail
closed instead of silently ignoring content. V1 files containing only frontmatter remain readable
for compatibility, but newly prepared units use v2.
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à.
Curated units must be atomic, readable by a second reviewer, and supported by the source.
Provenance references must lead back to the original file and the passage that supports the claim.
Do not put secrets, tokens, passwords, or credentials in metadata or URIs.
## Preparazione: dal sorgente alla generazione attiva
The modern canonical form also stores the Evidence kind, provenance, supporting excerpts, `source_file`, and `source_sha256`. The canonical contract rejects unknown fields, mutable metadata, and URIs containing credentials. Identifiers must remain stable even when a unit's kind changes.
## Preparation: from source to active generation
```mermaid
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"]
SRC["source/DOMAIN/*.md\noriginal material"] --> PREP["tht evidence prepare\ncandidate preparation"]
PREP --> CAND["curated/DOMAIN/*.md\nproposed or updated units"]
CAND --> VAL["tht evidence validate\nstructure and link checks"]
VAL -->|errors or review items| FIX["Author corrections\nand review"]
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"]
COMMIT --> ING["tht preprocess evidence\nnormalization and chunking"]
ING --> BM25["BM25 index"]
ING --> VEC["Embeddings and vector store"]
BM25 --> GEN["Candidate generation"]
VEC --> GEN
GEN --> ACT["Generazione attiva"]
ACT --> RUNTIME["Ricerca Evidence nel workflow"]
GEN --> ACT["Active generation"]
ACT --> RUNTIME["Evidence retrieval in the 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.
Preparation can restructure changed sources, but it does not publish by itself. `prepare` produces a proposal and can identify the document involved in an error. `validate` does not write or publish. The curator publishes the revision. The runtime reads a complete, validated revision, then the pipeline creates a versioned generation. Activation is atomic, and a previous generation remains available under the retention policy.
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.
Runtime retrieval is hybrid. The dense branch uses embeddings, the BM25 branch uses lexical search, and deterministic fusion orders the results. The published unit keeps its provenance, which the model must cite when it uses the Evidence.
## Responsabilità del creatore
## Author responsibilities
Il creatore prepara il materiale e rende verificabile ogni unità. In pratica deve:
The author prepares the material and makes every unit verifiable. The author must:
- 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.
- put the original material in `source/` without changing its meaning during curation;
- split the content into atomic units, with one rule or definition per unit when possible;
- assign a stable identifier and a clear title;
- provide provenance, tables, and related concepts when known;
- keep the text in the workspace language;
- separate facts, rules, examples, formulas, and limits;
- include excerpts that support the unit without extending the conclusion beyond the source;
- run `tht evidence prepare` and `tht evidence validate`;
- resolve every error and review item before proposing a commit;
- give the reviewer the necessary context, including source changes and the reason for any rename or retirement.
Il creatore non deve:
The author must not:
- 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.
- write directly to the active production corpus;
- treat a model proposal as a verified fact;
- delete an unsupported unit without recording its retirement or relink;
- put credentials in metadata, files, or provenance URLs;
- manually change manifests, hashes, or generations to make validation pass.
## Responsabilità del revisore
## Reviewer responsibilities
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:
The reviewer does not approve text merely because it is clear. The reviewer checks the relationship between source, unit, and intended use. For each unit, the reviewer must check:
1. che il sorgente indicato esista nella revisione esaminata;
2. che l'estratto sostenga davvero l'affermazione;
3. che l'unità non unisca regole incompatibili o concetti indipendenti;
4. che tabelle, colonne e concetti siano identificati correttamente;
5. che l'identificatore sia stabile e non duplichi un'altra unità;
6. che il testo distingua definizione, condizione, eccezione ed esempio;
7. che non contenga informazioni sensibili o dettagli non presenti nel sorgente;
8. che la valutazione del retrieval copra le query rilevanti e non nasconda risultati vuoti.
1. the cited source exists in the reviewed revision;
2. the excerpt actually supports the claim;
3. the unit does not combine incompatible rules or independent concepts;
4. tables, columns, and concepts are identified correctly;
5. the identifier is stable and does not duplicate another unit;
6. the text distinguishes the definition, condition, exception, and example;
7. it contains no sensitive information or details absent from the source;
8. retrieval evaluation covers relevant queries and does not hide empty results.
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.
The reviewer can approve, request changes, reject, retire, or relink a unit to a new source. Retirement must be explicit. A relink must name the new file and leave a verifiable record of the decision. Approval does not publish immediately: the repository must pass validation and the generation must pass evaluation before activation.
## Comandi disponibili
## Available commands
I comandi di authoring operano sul repository di workspace e non pubblicano direttamente.
Authoring commands operate on the workspace repository and do not publish directly.
```bash
# Prepara le sorgenti cambiate. Non committa e non pubblica.
# Prepare changed sources. Does not commit or publish.
tht evidence prepare <workspace-root>
# Rielabora tutte le sorgenti con la pipeline installata.
# Reprocess all sources with the installed pipeline.
tht evidence prepare <workspace-root> --upgrade
# Valida struttura, manifest, legami e review item.
# Rewrite legacy v1 units as readable v2 Markdown without model calls.
tht evidence migrate <workspace-root>
# Validate structure, manifest, links, and review items.
tht evidence validate <workspace-root>
# Restituisce JSON per CI o strumenti automatici.
# Return JSON for CI or automated tools.
tht evidence validate <workspace-root> --json
# Valuta il retrieval su una generazione o sulla generazione attiva.
# Evaluate retrieval on a generation or the active generation.
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.
# Resolve a unit without publishing: retire it or link it to a new source.
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.
# Materialize and index a versioned generation.
tht preprocess evidence --config <workspace-config>
# Esecuzione a secco e ripresa di un job, quando supportate dalla configurazione.
# Dry run and resume a job when supported by the configuration.
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.
`evidence prepare`, `evidence migrate`, `evidence validate`, and `evidence resolve` require the
repository path. `preprocess evidence` uses the workspace configuration because it needs the
embedding, vector store, retention policy, and 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.
Exit codes are part of the operating contract: `evidence validate` returns `0` when the corpus is publishable, `1` for validation errors, and `3` when only review items or orphaned units remain. With `--json`, stdout must contain valid JSON only.
## Formule e proposte di sessione
## Formulas and session proposals
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à.
Formulas use a format distinct from document Evidence. A formula proposed during a session may be cited in the current proposal, but it does not enter the runtime corpus, receive a usable `evidence:` ID, or write to the repository. To become published, it must follow the same import, review, and preprocessing path as other units.
## Riferimenti contrattuali
## Contract references
- [Contratto Workspace Evidence v3](contracts/workspace-evidence-v3.md)
- [Contratto della CLI di preprocessing](contracts/workspace-preprocessing-cli.md)
- [Workspace Evidence v3 contract](contracts/workspace-evidence-v3.md)
- [Preprocessing CLI contract](contracts/workspace-preprocessing-cli.md)