chore: preserve root worktree documents

CONTEXT.md

@@ -1,95 +1,42 @@
 # Contesto di dominio di ThothII
 
-## Architettura del workflow
+## Workflow
 
-**Workflow Kernel** — Il coordinatore deterministico che possiede lo stato del workflow,
-le transizioni, il rollback, la finalizzazione e l'applicazione atomica degli esiti dei
-moduli.
+**Workflow core** — La parte condivisa del workflow NL→SQL che governa la sequenza
+delle fasi, il ciclo di vita delle sessioni, la revisione umana e la persistenza. Non è
+un processo distinto né un sistema estensibile di plugin.
 
-**Workflow Module** — Una capacità incapsulata che espone un contratto versionato. Un
-modulo può partecipare a più stage e non modifica direttamente lo stato del workflow.
+**Internal workflow module** — Un insieme coeso di comportamento e conoscenza di
+dominio sviluppato e rilasciato insieme a ThothII. È isolato per rendere locali le
+modifiche, non per essere caricato dinamicamente o sostituito da implementazioni esterne.
 
-**Stage** — Un punto del workflow, identificato semanticamente, nel quale viene invocato
-un modulo. L'identità dello stage è indipendente dalla sua posizione visiva.
+**Pi** — Il runtime agentico concreto usato da ThothII per le elaborazioni che
+richiedono un modello. Segue le istruzioni del workflow e usa gli strumenti messi a
+disposizione dai moduli interni.
 
-**Display code** — L'etichetta di presentazione associata a uno stage, per esempio da
-`F1` a `F8`. I display code alimentano gli indicatori di avanzamento nel frontend, ma non
-sono usati come identità del workflow o chiavi di dipendenza.
+**Admission** — Il controllo che stabilisce se una domanda può entrare nel workflow
+NL→SQL oppure deve essere riformulata o rifiutata.
 
-**Module outcome** — Il risultato proposto da un modulo: eventi tipizzati, modifiche agli
-artifact, un'eventuale richiesta di revisione umana e uno stato di esecuzione. Il
-Workflow Kernel valida e applica l'esito.
+**Disambiguation** — La responsabilità di rendere esplicita e sottoporre a revisione
+l’interpretazione di una domanda ambigua prima della generazione SQL.
 
-**Revision request** — La proposta tipizzata con cui un modulo segnala che lo stage
-corrente non può concludersi validamente senza rieseguire lo stesso stage o uno stage
-precedente. Non produce direttamente una transizione: il Workflow Kernel valida la
-richiesta, sospende l'avanzamento e, per riaprire uno stage già completato, attende una
-decisione umana tipizzata. Il Kernel, non il modulo, determina gli eventi e gli artifact
-causalmente da rendere stale.
+**Evidence** — La conoscenza di dominio curata e citabile usata per fondare
+l’interpretazione della domanda e le scelte effettuate durante il workflow.
 
-**Question Admission** — Il controllo preliminare eseguito prima delle fasi da `F1` a
-`F8`. Nella prima release distingue una domanda utilizzabile da input garbage e verifica
-che la domanda appartenga allo scope dichiarato dal workspace. Il suo stato è mostrato
-separatamente dagli otto indicatori di fase.
+**Memory** — La conoscenza riutilizzabile derivata da decisioni o sessioni precedenti e
+resa disponibile alle elaborazioni successive.
 
-**Workspace scope** — La dichiarazione gestita e versionata di ciò che il database di un
-workspace rappresenta e delle domande alle quali è destinato a rispondere. Question
-Admission la usa come riferimento per valutare la pertinenza di una domanda.
+**Datamart** — L’attività finale già esistente che gestisce l’eventuale produzione del
+datamart dopo la generazione del SQL.
 
-**Datamart Plugin** — Il modulo sostituibile che implementa lo stage semantico
-`datamart`, presentato con display code `F8`. La promozione della memory e la
-finalizzazione della sessione non appartengono al Datamart Plugin.
-
-**Ordered workflow** — La pipeline deterministica composta dal preflight Admission,
-dagli otto stage principali ordinati da `F1` a `F8` e dalla finalizzazione. L'ordine
-degli stage è esplicito; il workflow non è un DAG generale.
-
-**Extension point** — Una posizione semantica nel lifecycle dell'Ordered workflow alla
-quale possono contribuire uno o più moduli senza diventare nuovi stage visibili. Un
-extension point non possiede un display code.
-
-**Stage state** — La proiezione deterministica degli eventi del workflow che descrive
-uno stage come `pending`, `ready`, `running`, `awaiting_human`, `completed`, `skipped` o
-`failed`. Non è un valore corrente memorizzato separatamente dal ledger.
-
-**Required contribution** — Il contributo di un modulo a un extension point che deve
-concludersi o essere esplicitamente saltato secondo policy prima che il workflow possa
-avanzare.
-
-**Best-effort contribution** — Il contributo di un modulo il cui fallimento viene
-registrato e mostrato come warning, ma non impedisce al workflow di avanzare.
-
-**Blocked workflow** — La proiezione complessiva di un workflow che non può avanzare a
-causa di uno stage o di un contributo required fallito o non disponibile. `Blocked` non
-è uno Stage state autonomo.
-
-**Module invocation** — Una singola richiesta del Workflow Kernel a un modulo in uno
-stage o extension point. Conserva la stessa identità attraverso eventuali retry, che
-sono tentativi distinti della medesima invocation.
-
-**Stage skip** — La conclusione esplicita di uno stage senza eseguirne il comportamento.
-È ammessa soltanto dalla policy dello stage e registra motivo e attore; un fallimento non
-equivale mai implicitamente a uno skip.
-
-**Stage reopen** — La riapertura di uno stage non finalizzato che rende stale gli esiti
-causalmente successivi. Gli effetti esterni già prodotti richiedono una marcatura o una
-compensazione esplicita e non sono presentati come automaticamente annullati. Può essere
-applicata dal Workflow Kernel in seguito all'approvazione di una Revision request, ma
-non può essere eseguita direttamente da Pi o da un Workflow Module.
-
-**Completion policy** — La regola con cui uno stage si conclude: `automatic` quando il
-kernel può verificarne deterministicamente l'esito, oppure `review_required` quando è
-necessaria un'approvazione umana tipizzata.
-
-**Paused session** — Una sessione interrotta intenzionalmente ma resumibile. L'azione
+**Paused session** — Una sessione interrotta intenzionalmente ma resumibile. L’azione
 “Stop and save” mette la sessione in pausa; non la completa e non la marca come fallita.
 
-**Finalized session** — Una sessione completata con esito canonico e immutabile. Una
-correzione successiva crea una nuova sessione derivata, collegata a quella precedente.
+**Finalized session** — Una sessione completata che non accetta ulteriori modifiche al
+proprio risultato.
 
-**After-finalize hook** — Una notifica o attività best-effort eseguita tramite outbox
-dopo la finalizzazione. Non può modificare il ledger, gli artifact canonici o lo stato
-terminale della sessione.
+**Workspace scope** — La dichiarazione di ciò che il database di un workspace
+rappresenta e delle domande alle quali è destinato a rispondere.
 
 ## Catalogo dei metadati
 
@@ -103,8 +50,12 @@ Workspace Database. Non definisce quali elementi partecipano al workflow SQL.
 **Database Profile** — L'insieme curato di scope, descrizioni e metadati semantici
 associato a un Workspace Database.
 
-**AI Proposal** — Un contenuto generato con l'ausilio dell'AI che non è ancora stato
-approvato come contenuto canonico.
+**Generated comment** — Il testo descrittivo prodotto dall'AI per una tabella o una
+colonna. Rimane distinto dalla descrizione finché l'utente non ne richiede la copia.
+
+**Core Schema Selection** — Il sottoinsieme di tabelle, colonne e relazioni di un
+Workspace Database reso disponibile al processo core di ThothII. È distinto dal
+Workspace scope, che descrive il dominio e le domande ammesse.
 
 **Publication** — Una versione approvata e immutabile dei contenuti del Metadata
 Catalog resa disponibile ai suoi consumatori.