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

feat(evidence): add table-free v3 and design guidance

Browse Source
This commit is contained in:
Codex
2026-08-26 12:15:40 +02:00
parent 38f02cfd08
commit 9d4f994d3e
11 changed files with 983 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/contracts/workspace-evidence-v3.md
+10 -8
View File
@@ -50,15 +50,17 @@ traceability but never acquired by v2 runtime preprocessing.
### Curated unit representation
The `schema_version` inside each `curated/**/*.md` file is distinct from the workspace descriptor
version above. Unit schema v1 stores the complete typed unit in YAML frontmatter and remains
readable for compatibility. Unit schema v2 keeps short metadata in frontmatter and stores the
typed payload, supporting excerpts, and review items in a deterministic Markdown body.
version above. Unit schema v1 stores the complete typed unit in YAML frontmatter. Unit schema v2
keeps short metadata in frontmatter and stores the typed payload in the body. Both remain readable
for compatibility.
V2 bodies use headings, paragraphs, code lists, enum tables, fenced SQL, and blockquotes according
to the Evidence kind. Invisible `tht:` comments delimit typed fields. Parsers must reject missing,
duplicate, unknown, or unstructured body content; they must never silently ignore it. Newly
prepared units use v2. `tht evidence migrate <workspace-root>` upgrades existing v1 units locally
without a model call, commit, publication, or semantic change.
Unit schema v3 stores canonical machine metadata in an invisible `tht:metadata` comment and renders
the complete review surface as deterministic Markdown. It uses headings, paragraphs, wrapping
lists, fenced SQL, blockquotes, and a collapsed technical-details block. It never emits YAML
frontmatter or Markdown tables. Invisible `tht:` comments delimit typed fields. Parsers must reject
missing, duplicate, unknown, desynchronized, or unstructured body content; they must never silently
ignore it. Newly prepared units use v3. `tht evidence migrate <workspace-root>` upgrades existing
v1 and v2 units locally without a model call, commit, publication, or semantic change.
### Example: filesystem
docs/evidence.md
+29 -23
View File
@@ -48,28 +48,26 @@ HTTP and S3 are separate adapters. They do not use the filesystem structure `sou
## What a curated unit must contain
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.
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.
```markdown
---
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
---
<!-- 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.
@@ -77,12 +75,20 @@ 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 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.
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.
@@ -162,7 +168,7 @@ tht evidence prepare <workspace-root>
# Reprocess all sources with the installed pipeline.
tht evidence prepare <workspace-root> --upgrade
# Rewrite legacy v1 units as readable v2 Markdown without model calls.
# 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.