Evidence: sources, preparation, and review

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.

Publication rule

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.

Evidence becomes available to the workflow only when:

the original material is in source/;
the derived unit is in curated/;
the manifest links the unit, source, and hash;
validation finds no errors or unresolved review items;
preprocessing builds and activates an indexed generation.

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.

Where the original source belongs

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.

<workspace-repository>/
├── source/                 # materiale originale, preservato
│   └── <domain>/<file>.md
├── curated/                # reviewed Evidence Units
│   └── <domain>/<unit>.md
├── manifest.yaml           # preparation links, hashes, and metadata
└── example/                # examples and supporting material

The workspace descriptor must declare evidence.schema_version: 2 and use exactly this configuration for a filesystem source:

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

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 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.

What a curated unit must contain

Canonical Curated Evidence v3 hides canonical machine metadata in an HTML comment and renders the whole review surface as real Markdown. GitHub therefore shows no frontmatter table. The body layout is deterministic for each Evidence kind: prose uses sections and paragraphs, scopes and enum values use wrapping lists, formulas use fenced SQL, supporting excerpts use blockquotes, and unresolved review items use dedicated blocks.

<!-- tht:metadata:<canonical metadata> -->
# Fascia pediatrica

> **Dominio** · Italiano
>
> **Scopi:** Disambiguazione

## Ambito di applicazione

### Concetti

- fascia pediatrica

## Regola

La fascia pediatrica comprende i pazienti con età inferiore a 18 anni.

## Estratti di supporto

> I pazienti sotto i 18 anni sono pediatrici.

<details>
<summary>Dettagli tecnici e provenienza</summary>

- **ID:** `evidence:fascia-pediatrica`
- **File sorgente:** `source/domain/paziente.md`

</details>

The actual files contain invisible tht: comments for canonical metadata and typed-field boundaries. Removing, duplicating, or desynchronizing them makes validation fail closed instead of silently ignoring content. Unit schemas v1 and v2 remain readable for compatibility, but newly prepared units use v3.

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.

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

flowchart TD
    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\nnormalization and chunking"]
    ING --> BM25["BM25 index"]
    ING --> VEC["Embeddings and vector store"]
    BM25 --> GEN["Candidate generation"]
    VEC --> GEN
    GEN --> ACT["Active generation"]
    ACT --> RUNTIME["Evidence retrieval in the workflow"]

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.

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.

Author responsibilities

The author prepares the material and makes every unit verifiable. The author must:

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.

The author must not:

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.

Reviewer responsibilities

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:

the cited source exists in the reviewed revision;
the excerpt actually supports the claim;
the unit does not combine incompatible rules or independent concepts;
tables, columns, and concepts are identified correctly;
the identifier is stable and does not duplicate another unit;
the text distinguishes the definition, condition, exception, and example;
it contains no sensitive information or details absent from the source;
retrieval evaluation covers relevant queries and does not hide empty results.

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.

Available commands

Authoring commands operate on the workspace repository and do not publish directly.

# Prepare changed sources. Does not commit or publish.
tht evidence prepare <workspace-root>

# Reprocess all sources with the installed pipeline.
tht evidence prepare <workspace-root> --upgrade

# Rewrite legacy v1/v2 units as table-free v3 Markdown without model calls.
tht evidence migrate <workspace-root>

# Validate structure, manifest, links, and review items.
tht evidence validate <workspace-root>

# Return JSON for CI or automated tools.
tht evidence validate <workspace-root> --json

# 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

# 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

# Materialize and index a versioned generation.
tht preprocess evidence --config <workspace-config>

# 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 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.

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.

Formulas and session proposals

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.

10 KiB Raw Blame History