chore: preserve root worktree documents

2026-08-31 15:34:55 +02:00
parent b5db0cd3c1
commit fa7380b3a3
8 changed files with 1021 additions and 80 deletions
@@ -0,0 +1,141 @@
+# 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.