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.

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.