ThothII/docs/prd/2026-08-23-refactoring-modulare-conservativo-brief.md

# Brief — Refactoring modulare conservativo del workflow

**Stato:** input autorevole per `grill-with-docs`; non è ancora una specifica
implementativa.

## Obiettivo

Riorganizzare l’attuale applicazione ThothII per rendere locali e manutenibili le
modifiche a Disambiguation, Evidence e Memory, preservando integralmente comportamento,
frontend e flusso operativo esistenti.

La prima milestone è esclusivamente un refactoring. Non introduce nuove funzionalità e
non generalizza ThothII come piattaforma di plugin.

## Vincoli già decisi

- Il progetto continuerà a essere sviluppato e mantenuto da un solo proprietario, in un
  unico repository e con un unico rilascio.
- I moduli sono package interni secondo normali criteri di programmazione a oggetti.
  Non devono essere distribuibili indipendentemente, caricati dinamicamente o scritti da
  terze parti.
- I moduli non devono condividere un contratto universale. Ogni modulo può presentare al
  workflow una piccola façade adatta alla propria responsabilità.
- Moduli e fasi non coincidono necessariamente: un modulo può contribuire a più fasi e
  una fase può coordinare più moduli senza introdurre un protocollo generale.
- Pi resta il runtime concreto per le elaborazioni assistite dal modello. Non viene
  introdotta un’astrazione `ModelRuntime`.
- Il workflow resta ordinato e continua a usare `harness/workflow.yaml`, il ledger delle
  decisioni, i documenti di sessione e gli attuali gate human-in-the-loop.
- Frontend, eventi SSE, widget, comandi `tht`, JSON, codici di uscita e formato delle
  sessioni devono rimanere compatibili.
- Non sono previste migrazioni dei dati delle sessioni esistenti.
- Il flusso SQL centrale, inclusi schema linking, sintesi, CTE e SQL finale, resta nel
  workflow core durante questa milestone.
- Un altro componente futuro, estraneo al workflow e al core, non appartiene a questo
  refactoring.

## Moduli interni desiderati

### Admission

Occupa l’inizio logico del workflow. Nella prima milestone è un pass-through e ammette
sempre la domanda, così il comportamento osservabile non cambia.

Per una fase futura è già stata scelta questa policy: una domanda non ammessa può essere
riformulata nella stessa sessione; dopo il terzo tentativo fallito la sessione fallisce.
La classificazione e l’esperienza utente non fanno parte del primo refactoring.

### Disambiguation

Raccoglie senza cambiarne il comportamento la logica attuale di chiarimento,
interpretazione revisionata e riscrittura della domanda, comprese istruzioni Pi,
validazioni e presentazione delle relative decisioni.

### Evidence

Consolida le superfici esistenti di acquisizione, canonizzazione, ricerca e citazione.
Mantiene i seam già reali verso filesystem, HTTP e S3 e il contratto CLI/JSON necessario
fra Python e TypeScript. Non introduce un contratto generale per gli altri moduli.

### Memory

Raccoglie senza variazioni funzionali ricerca, selezione, promozione e conoscenza delle
domande già risolte, insieme alle istruzioni e ai gate specifici oggi dispersi.

### Datamart

Incapsula senza modificarla la parte di gestione del datamart oggi svolta nella fase F8.
La fase F8 rimane visivamente e funzionalmente invariata, ma l’eventuale comportamento
Memory che contiene appartiene al modulo Memory. La futura integrazione intelligente del
SQL in un progetto dbt o in un flusso ETL è deliberatamente rinviata al momento in cui
questo modulo verrà sviluppato.

## Responsabilità che restano condivise

Il workflow core conserva soltanto ciò che appartiene realmente all’intero flusso:

- ordine e avanzamento delle fasi;
- ciclo di vita e resume delle sessioni;
- ledger e documenti di sessione esistenti;
- persistenza e locking comuni;
- processo Pi e trasporto backend/frontend;
- gate generici, sicurezza anti-bypass e finalizzazione;
- coordinamento esplicito dei moduli tramite import statici.

I moduli non si scoprono tramite registry e non comunicano tramite event bus. Le
dipendenze condivise vengono ricevute dal modulo oppure coordinate dal workflow core;
un modulo non importa direttamente l’implementazione di un altro.

## Architettura esplicitamente rifiutata

Questa iniziativa non deve introdurre:

- Kernel separato dall’attuale harness;
- manifest, registry, binding o composition resolver;
- negoziazione e versionamento di un contratto universale;
- adapter di esecuzione `in_process`, `process` o `job`;
- `WorkflowDefinition`, `WorkflowCommit`, nuovo event store o upcaster;
- artifact slot e revisioni universali;
- Review Port, Interaction Request/Result o Instruction Bundle generici;
- plugin dbt o automazioni ETL nella prima milestone.

## Fatti rilevanti sul codice attuale

- `harness/.pi/extensions/tht-gate.js` è il principale punto caldo condiviso, con circa
  2.000 righe e logica relativa a più domini.
- `harness/.pi/skills/tht-sessione/SKILL.md` contiene circa 450 righe di istruzioni che
  attraversano tutte le fasi.
- Evidence possiede già un port reale e tre adapter per filesystem, HTTP e S3.
- Memory possiede già codice dedicato, ma responsabilità e integrazione sono distribuite
  tra modulo Python, CLI, gate e istruzioni Pi.
- Disambiguation oggi è soprattutto comportamento distribuito fra istruzioni, decisioni
  e gate, non un package applicativo autonomo.
- `harness/workflow.yaml` è già la fonte condivisa dell’ordine e dei requisiti delle
  fasi e deve rimanere tale.

L’analisi più ampia del problema corrente resta disponibile in
[`2026-08-21-modularizzazione-disambiguazione-evidence-memory-prd.md`](2026-08-21-modularizzazione-disambiguazione-evidence-memory-prd.md).

## Criterio di riuscita

Dopo il refactoring, una modifica interna a Disambiguation, Evidence o Memory deve
richiedere normalmente interventi nella directory e nei test del relativo modulo. Il
workflow core cambia soltanto quando cambia davvero il flusso condiviso.

La suite esistente, i test di caratterizzazione e i test end-to-end devono dimostrare
che il frontend e ogni comportamento osservabile sono rimasti invariati.

## Questioni da affidare a `grill-with-docs`

L’intervista deve concentrarsi soltanto sulle decisioni necessarie al refactoring:

1. ownership esatta dei file e delle responsabilità attuali;
2. façade minima e specifica di ciascun modulo;
3. collocazione delle istruzioni Pi e degli helper del gate relativi a ciascun dominio;
4. dipendenze condivise che devono essere ricevute dai moduli;
5. ordine di estrazione incrementale e test di caratterizzazione per ogni passaggio;
6. criteri oggettivi che impediscano al refactoring di introdurre cambiamenti funzionali.

Le funzioni future di Admission e Datamart/dbt sono fuori dal frontier dell’intervista:
vanno discusse soltanto dopo il completamento del refactoring conservativo.