ThothII/docs/prd/2026-08-21-modularizzazione-disambiguazione-evidence-memory-prd.md

# PRD — Modularizzazione a moduli incapsulati: disambiguazione, evidence, memory

**Status:** riflessione architetturale di plausibilità — nessuna decisione implementativa presa qui; il
documento fissa confini, contratti condivisi e precondizioni da cui potranno nascere ticket e piani separati
**Data:** 2026-08-21
**Autore:** analisi del codice su main (`5f05754`), su richiesta del proprietario; incrocia e non sostituisce
i documenti evidence-canonica già esistenti (sez. 9)
**Uso:** riferimento per il programma di sviluppo parallelo dei tre sottosistemi (disambiguazione, gestione
evidence, gestione memory); definisce cosa deve essere vero *prima* che i tre flussi possano girare in
parallelo senza impatti incrociati

---

## 1. L'obiettivo del proprietario

Avviare uno sviluppo che cambi **in parallelo** tre aree del sistema:

1. **disambiguazione** (estratta e separata dal workflow);
2. **gestione delle evidence** — nuovo componente che espone un'API verso il resto del workflow ma resta
   ben incapsulato al suo interno;
3. **gestione della memory** — con lo stesso grado di forte incapsulamento.

Vincolo accettato: le modifiche fatte su un modulo **non devono impattare gli altri moduli** se non per
eventuali ridefinizioni dei contratti (API) esposti.

## 2. Verdetto sintetico

**Plausibile, e il codebase è insolitamente ben predisposto per farlo.** Ma con tre precisazioni oneste:

1. i tre componenti sono oggi a **tre livelli di maturità diversi**: evidence è quasi un modulo, memory è
   già incapsulata meglio di quanto sembri, la disambiguazione **non è un componente di codice** e
   "estrarla" è un lavoro di natura diversa (sez. 4);
2. esistono **due "quinti moduli" nascosti** — il ledger dei tipi di decisione con `workflow.yaml`, e il
   gate `tht-gate.js` con il vector store — che il piano a tre vie deve contemplare, altrimenti il
   parallelismo si rompe dove non si sta guardando (ledger e gate sono spiegati in sez. 3; le implicazioni
   in sez. 5);
3. gli accoppiamenti reali **non sono negli import Python**: sono nei decision type del ledger, nelle
   proiezioni `search pack`/`search find`, nel modello di contenuto della memory e negli id evidence
   citabili. Sono quelli i contratti da definire e versionare **prima** del parallelismo (sez. 6–7).

## 3. Ledger e gate: i due elementi cardine del workflow

Il resto del documento usa di continuo due concetti che conviene fissare qui, perché sono
i punti dove i tre moduli si incontrano davvero: il **ledger** (dove lo stato viene
registrato) e il **gate** (chi decide e chi scrive).

### 3.1 Il ledger — il registro delle decisioni (`review_decisions.jsonl`)

Una sessione è una directory: manifest + artefatti per fase (`question.md`,
`schema_linking.json`, `sql_final.sql`, …) + un file `review_decisions.jsonl`. Il ledger
è **append-only**: una riga JSON per ogni decisione del reviewer, con numero progressivo
`seq`, timestamp, `type`, `subject`, `detail`, `rationale` (più i campi di rollback
`retracts`/`phase`). I `DecisionType` definiti in `tht/decisions.py` sono esattamente 30.

Esempio concreto: a F1 il reviewer sceglie "per 'ablazione' intendo la colonna
`flag_ablazione` della fact delle procedure" → nel ledger viene accodata una riga come
`{"seq": 3, "ts": "…", "type": "concept_clarified", "subject": "ablazione", "detail": "…",
"rationale": "…"}`.

Due proprietà lo rendono cardine:

1. **la fase corrente non è memorizzata: è calcolata** rileggendo (fold) il ledger
   (`tht/phase.py`). Il ledger è la fonte di verità — "ciò che non è registrato non è
   accaduto". Il rollback non cancella nulla: aggiunge `decision_retracted`/
   `phase_reopened` e la vista *effettiva* (`effective_decisions`) esclude le righe
   ritirate e quelle rimaste stale oltre il punto di rollback;
2. **è il canale di comunicazione tra i moduli**: la disambiguazione *scrive*
   `concept_clarified`/`ambiguity_open`/`value_grounded`; l'evidence *scrive*
   `evidence_accepted`/`evidence_rejected`/`concept_formula_approved|rejected`; la memory
   *legge* `concept_clarified` (per costruire le promozioni) e *scrive* `memory_promoted`/
   `memory_promotion_declined`. Per questo l'insieme dei decision type **è** un contratto:
   ridefinirlo (sez. 6.1) è l'equivalente di cambiare una API tra moduli.

### 3.2 Il gate — l'estensione che impone il human-in-the-loop (`tht-gate.js`)

ThothII non esegue il workflow con codice: lo esegue **un agente LLM (Pi)** che segue
SKILL.md. Il modello propone, ma non decide e non persiste direttamente. Il gate è
l'estensione JavaScript di Pi (~2000 righe, `harness/.pi/extensions/tht-gate.js`) che
svolge tre lavori:

1. **traduce le proposte del modello in widget per l'umano**: il modello chiama un tool
   del gate — `reviewer_select` (scelta singola), `reviewer_decide` (multiselect),
   `reviewer_confirm` (gate su artefatto/fase) più i specializzati `rewrite_question`,
   `reviewer_schema_linking`, `reviewer_datamart`, `reviewer_memory_promote`,
   `write_schema_linking`, `write_cte_sql`, `write_final_sql`; il gate costruisce il
   descriptor del widget → RPC → backend → SSE → browser, dove il frontend lo renderizza
   dal registry `src/widgets/`;
2. **persiste attraverso un unico canale**: alla risposta del reviewer, è il gate (non il
   modello) a invocare la CLI `tht` (es. `tht memory promote --preview --json`,
   `tht session sync-schema-linking`) e ad accodare la riga nel ledger;
3. **fa rispettare le regole (enforcement)**: l'hook anti-bypass blocca `tht phase
   advance`, `tht decision add`, `tht memory promote|save-one` se il modello prova a
   eseguirli direttamente dalla shell; i payload vengono validati (TypeBox) e gli
   artefatti mostrati al reviewer sono ricostruiti in modo deterministico (es. il widget
   CTE mostra il SQL persistito via `tht cte info`, non il testo del modello); le
   chiusure di fase deterministiche sono automatiche.

Esempio concreto (F8): il modello chiama `reviewer_memory_promote`; il gate esegue
`tht memory promote --preview --json`, costruisce la checklist pre-selezionata; il
reviewer conferma; il gate salva le memory scelte (`memory save-one`), registra
`memory_promoted`/`memory_promotion_declined` nel ledger e finalizza la sessione. Il
modello non ha mai scritto nulla di propria mano.

Perché è cardine per la modularizzazione: il gate è **l'unico punto** in cui i tre moduli
appaiono all'utente e in cui le loro regole vengono imposte — ogni cambiamento a
disambiguazione/evidence/memory ha quasi sempre una controparte nel gate (sez. 5.2).

## 4. Stato attuale dei tre componenti

### 4.1 Evidence — il più vicino a essere un modulo

Fatti verificati nel codice:

- esiste già un **port vero** (`harness/tht/ports/evidence.py`: `discover`/`acquire`, credential-free,
  contratti Pydantic congelati) con **tre adapter** dietro il port (`adapters/evidence/{filesystem,http,s3}.py`);
- la pipeline di canonizzazione/indicizzazione vive in `harness/tht/corpus/` (sorgente → normalize →
  chunk → embed → vector store, generazioni isolate stage→publish);
- la **superficie di consumo del workflow è già quasi tutta incanalata in due comandi con JSON pulito**:
  `tht search pack` (sezione evidence: top 5, proiezione `{title, status, excerpt[:400]}`) e
  `tht search find [--kind evidence|formula]`. Quella proiezione è già di fatto un'API: evidence-canonica
  può rifare tutto dietro di essa (card, involucro tipizzato, retrieval duale) senza che F1 se ne accorga,
  finché il contratto di proiezione regge;
- l'**inventario dei punti di consumo è già fatto**: `verifica-workflow.md` elenca i 12 touchpoint (T1–T12)
  con meccanismo e requisito. Quel documento **è** la bozza del contratto esterno del modulo.

Ciò che manca all'incapsulamento sono esattamente i tre GAP lì identificati:

- **GAP 1 — identità citabile**: il processo tratta l'id evidence come documento (F3 lo cita, F4 lo attacca
  ai candidati, il report di sessione lo risolve in file via `resolve_evidence_file`/`rglob`). La decisione
  già presa (id citabile `doc#card`) richiede l'estensione del resolver: è l'ultimo passo di contratto da
  chiudere;
- **GAP 2 — formula store**: lettura cablata e funzionante, scrittura senza proprietario di produzione.
  La decisione già presa (le card famiglia 3 del corpus canonico sono fonte di verità; i `.sql.md` sono
  derivati della pipeline) assegna il proprietario senza toccare il contratto di lettura D14b;
- **GAP 3 — conoscenza di dominio nei testi istruzionali**: dialetto, ricette temporali PSD, esempi clinici
  dentro SKILL.md e reference doc. È contenuto evidence sparso nel workflow: la migrazione verso il corpus
  canonico **è parte del lavoro di confine**, non un'attività cosmetica successiva.

Nota trasversale: il ciclo di vita evidence attraversa **due linguaggi** — materializzazione e ciclo di vita
della collection stanno nel backend TypeScript (P4/P6), corpus e ricerca nello harness Python. L'API del
modulo deve quindi essere il contratto CLI/JSON (che è già lo stile di casa: `--json` pristine), non
un'interfaccia Python.

### 4.2 Memory — già incapsulata, con un accoppiamento semantico da esplicitare

Fatti verificati:

- il modulo vive in `harness/tht/memory.py` + `tht/solved.py` + `cli/memory_cmd.py`, con registro JSONL
  a scrittura atomica e dedup del contenuto reviewer-visibile;
- i punti di contatto col workflow sono **esattamente tre**: F2 (ricerca + applicazione via gate), F8
  (gate di promozione), finalize (indicizzazione `solved_question`, best-effort);
- il gate consuma la memory **solo tramite CLI**: `tht memory promote --preview --json` e
  `memory save-one`; la logica di calcolo dei candidati (dedup, decisioni storie post-rollback, seq
  rifiutate, esclusione delle già decise nella sessione) è tutta dentro memory.py. È incapsulamento vero,
  già operativo.

L'accoppiamento che conta non è di codice ma **semantico**: `REUSABLE_TYPES = {"concept_clarified"}` —
il modello di contenuto della memory è definito dal tipo di output della disambiguazione. Se il ridisegno
F1 cambia cosa sia un chiarimento (target group, tassonomia dell'ambiguità, caso unanswerable), cambia
anche cosa la memory può promuovere e come. **Il contratto disambiguazione→memory va definito prima di
far girare i due flussi in parallelo**, o si scontreranno esattamente lì.

### 4.3 Disambiguazione — non è un componente di codice

Il punto onesto: **non c'è niente da "estrarre" nel senso classico**. Oggi la disambiguazione è il
comportamento dell'LLM in F1/F3/F4, governato da (ledger e gate: sez. 3):

- **prosa** (SKILL.md + `rewriting.md`): una sola ambiguità per volta, opzioni informate, "lascia aperta
  l'ambiguità" esplicita;
- **retrieval**: pack iniettato (`retrieval_pack.md`), `tht search find`, `tht schema render`, LSH con
  `aggregate_lsh_multi` che espone *tutte* le colonne dove un valore appare (es. "ablazione" su flag
  booleano + campo patologia testuale);
- **ledger**: `concept_clarified`, `ambiguity_open`, `value_grounded`, `question_rewritten`;
- **gate**: i widget che presentano le interpretazioni candidate.

"Extractorla" significa quindi, in ordine:

1. **definire il suo contratto input/output** — in: domanda + contesto di retrieval; out: ambiguità con
   target group, opzioni candidate, segnale unanswerable distinto dall'ambiguo. È ciò che
   `impact-ridisegno-disambiguazione.md` §3 già elenca (retrieval duale lessicale+semantico, target group,
   unanswerable);
2. **darle una superficie** che l'orchestratore consuma (sezione del pack, comando, sezione skill dedicata)
   invece di comportamento libero del modello;
3. **spostare la conoscenza che usa** fuori da SKILL.md e dentro le evidence (GAP 3).

Rischio specifico e strutturale: l'LLM è colla che **può bypassare qualunque contratto su carta**. In
questo codebase l'unico enforcement che funziona è a livello gate/CLI — il pattern è già dimostrato
dall'hook anti-bypass che blocca `tht phase advance`/`decision add` da shell e `tht memory promote`/
`save-one` fuori dal gate. Finché il contratto di disambiguazione non è enforcement (hook + CLI + skill
come contratto completo), la proprietà "le modifiche non impattano altri moduli" è una speranza, non una
proprietà verificabile.

## 5. I due quinti moduli nascosti

### 5.1 Il ledger + `workflow.yaml` — la colonna vertebrale condivisa

Tutti e tre i moduli leggono/scrivono il decision ledger (`review_decisions.jsonl`, sez. 3.1): la
disambiguazione
emette `concept_clarified`/`value_grounded`; l'evidence emette `evidence_accepted`/`evidence_rejected`/
`concept_formula_approved|rejected`; la memory legge `concept_clarified` ed emette `memory_*`. Il campo
`emits` di `workflow.yaml` accoppia fasi e decision type; `phase.py` piega il ledger per calcolare la
fase corrente.

Questo è un **bene**: il ledger è già un contratto a eventi tra i moduli. Ma è superficie condivisa —
tutti e tre i flussi vorranno toccarla. Va trattata come contratto a sé (quarto), con controllo dei
cambiamenti, non come territorio libero.

### 5.2 Il gate (`tht-gate.js`) e il vector store — i punti caldi di merge

- **Il gate** (sez. 3; ~2000 righe + builders/enrich/artifact-contracts) renderizza candidati evidence, dedup
  opzioni memory, costruisce il widget schema-linking con id evidence, guida F2/F8 memory e fa enforcement
  anti-bypass. **Tutti e tre i flussi avranno bisogno di modifiche al gate**: se non viene spaccato lungo
  gli stessi confini dei moduli, diventa il punto caldo di merge del programma parallelo.
- **Il vector store**: una collection Qdrant per workspace, kind-separata (`schema_table`, `schema_column`,
  `evidence`, `memory`, `solved_question`); il contratto di collection e payload-index è di proprietà del
  backend TS (P4), lettura/scrittura sono Python. I record schema/evidence sono revision-scoped (P3),
  memory/solved workspace-wide. Se evidence-canonica cambia la forma dei record/payload (il frontmatter
  già fluisce libero nei metadata), gli assunti di indicizzazione della memory ne risentono. Il vector
  store va designato come **infrastruttura condivisa con contratto proprio**, non come territorio
  implicito di uno dei tre.

## 6. I contratti che sono le vere API

Il parallelismo è protetto da quattro contratti, nessuno dei quali è un'interfaccia Python:

1. **Decision type del ledger** (`workflow.yaml` `emits` + `decisions.py`): l'interfaccia a eventi tra i
   tre moduli e il workflow. Ogni ridefinizione è una modifica di contratto, va versionata e comunicata;
2. **Proiezioni di consumo evidence** (`search pack` / `search find --kind evidence|formula`): la forma di
   ciò che F1/F3/F4 vedono. È il cuore del ticket "Consumo per fase", che già porta i requisiti della F1
   ridisegnata e **non va congelato prima** che il disegno F1 abbia almeno uno schizzo;
3. **Modello di contenuto memory** (`REUSABLE_TYPES` + campi del record + proiezione `promote --preview
   --json`): dipende semanticamente dal contratto di output della disambiguazione (sez. 4.2);
4. **Id evidence citabile** (`doc#card` + estensione del resolver id→file): il contratto che tiene insieme
   F3 (citazioni), F4 (candidati), decisions (subject) e report di sessione.

## 7. Ordine di sviluppo consigliato

Coerente con quanto già deciso in `map.md` e nell'impact doc:

1. **schizzo del disegno F1** della disambiguazione (anche non finale): target group, retrieval duale,
   unanswerable — perché il contratto di consumo va progettato *contro la F1 ridisegnata*;
2. **chiusura del contratto "Consumo per fase"** (cerniera tra evidence-canonica e F1): proiezioni,
   filtri, id citabili `doc#card` con resolver esteso;
3. **definizione del contratto disambiguazione→memory** (cosa è riusabile, con quali campi);
4. **solo allora** i tre flussi girano in parallelo, ciascuno nel suo worktree.

Strumento di protezione del parallelismo già disponibile in casa: il **pattern dei port-contract test**
(`test_evidence_port_contract.py`, `test_vector_port_contract.py`, `test_dwh_port_contract.py`).
Estenderlo ai nuovi confini (proiezioni evidence, contratto memory, enforcement di disambiguazione) è il
modo più economico per rendere l'indipendenza dei moduli **verificabile** invece che sperata: un flusso
rompe l'altro se e solo se rompe un test di contratto, non per effetti nascosti.

## 8. Rischi e mitigazioni

| Rischio | Natura | Mitigazione |
|---|---|---|
| L'LLM orchestratore bypassa il contratto di disambiguazione | strutturale (il workflow è LLM-driven) | enforcement gate/CLI sul modello dell'anti-bypass esistente; SKILL come contratto completo, non consiglio |
| Collisione disambiguazione↔memory su `concept_clarified` | semantica | contratto esplicito (sez. 6.3) definito prima del parallelismo |
| `tht-gate.js` punto caldo di merge | organizzativa | spaccare il gate lungo gli stessi confini dei moduli (builders per modulo) |
| Deriva del contratto vector store tra TS e Python | infrastrutturale | contratto di collection/payload/kind di proprietà unica, test di contratto su entrambi i lati |
| modifiche contagiose a `workflow.yaml`/ledger | processo | change control sul ledger come quarto contratto; `emits` data-driven già aiuta |
| contratti congelati troppo presto (Consumo per fase) | sequenza | ordine sez. 7: prima schizzo F1, poi chiusura contratto |

## 9. Riferimenti

- `docs/wayfinder/evidence-canonica/map.md` — mappa del sottoprogetto evidence-canonica (destinazione,
  decisioni chiuse, nebbie);
- `docs/wayfinder/evidence-canonica/prototypes/verifica-workflow.md` — i 12 touchpoint evidence (T1–T12) e
  i GAP 1–3: l'inventario dell'interfaccia esterna del futuro modulo evidence;
- `docs/wayfinder/evidence-canonica/prototypes/impact-ridisegno-disambiguazione.md` — valutazione d'impatto
  del ridisegno F1 (requisiti: retrieval duale, target group, unanswerable; coordinamento dei due progetti);
- `docs/wayfinder/evidence-canonica/prototypes/PROTOTIPO-formato-unita-canonica.md` e `tipologia-evidence.md`
  — formato card+involucro chiuso il 2026-08-21 e casistica a 7 famiglie;
- `docs/disambiguazione-iniziale.md` — stato attuale della disambiguazione;
- `docs/gestione-memory.md` — disegno della gestione memory;
- `harness/workflow.yaml`, `harness/.pi/skills/tht-sessione/SKILL.md`, `harness/.pi/extensions/tht-gate.js`
  — le fonti di codice citate (fasi, discipline, gate);
- `docs/prd/2026-08-09-workspace-preprocessing-prd.md` — il PRD da cui nasce l'attuale catena
  preprocessing/registry (contesto P2–P6 citato in sez. 4.1 e 5.2).