ThothII/docs/plans/2026-09-08-memory-evidence-administration.md

Amministrazione di Memory ed Evidence

Data del piano: 2026-09-08. Aggiornamento 2026-09-09: M1–M3, E1–E3 e X1 implementati. Risultati e limiti della verifica finale sono raccolti nel rapporto X1.

La revisione di semplicità riesamina tutte le decisioni Q1–Q15 alla luce degli ultimi chiarimenti del proprietario e confronta le conseguenze con il piano precedente. Per Evidence R0 sono scelti file Markdown locali, editor esterni e consolidamento manuale con controllo della struttura, seguito da diff, commit e push dell'operatore. La pagina deve indicare chiaramente percorsi e comandi. Le restanti semplificazioni sono confermate. Il cambio del formato richiede adeguare il sottosistema core Evidence, convertire i file e reindicizzare; E1 precede la pagina. Il controllo umano usa lo stato Git nel terminale, con diff delle righe quando serve, senza una UI dedicata. Si ignora la contemporaneità fra amministrazione e core. Lo specialista scrive draft indipendentemente dall'installazione; il sistema le raffina e le conserva localmente. La proposta aggiornata usa file canonici locali per le Evidence e toglie commit/push automatici dal CRUD; questa revisione tecnica di Q11 sostituisce la raccomandazione precedente ed è stata attuata negli incrementi E1–E3.

Obiettivo e decisioni del proprietario

L'amministratore deve poter accedere in qualsiasi momento alle Memory e alle Evidence registrate, cercarle, filtrarle, aprirle, crearle, modificarle e cancellarle. L'accesso non richiede una sessione del core o una fase del workflow.

Il lavoro è diviso in due progetti autonomi:

• Memory management;
• Evidence management.

I progetti condividono l'esperienza di gestione e i componenti appropriati, mantenendo distinti i contenuti, le regole di validazione e i percorsi di persistenza.

Collocazione dei due accessi

L'ordine previsto nell'accordion Administration è:

Administration
  Database management
  Memory management
  Evidence management
  ────────────────────
  Workspace management
  Pi management

Memory management ed Evidence management sono due voci autonome, allo stesso livello di Database management. «Sotto» indica soltanto la posizione fisica nella navigazione. Non sono sottopagine, tab o funzionalità di Database management. Ciascuna apre la propria pagina e possiede il proprio stato di navigazione.

Decisioni già acquisite sulla Memory

• La Memory serve a migliorare schema linking e generazione SQL di domande future.
• Il perimetro comprende chiarimenti di dominio riutilizzabili, regole corrette per join, filtri e aggregazioni, domande risolte consultabili ed errori da evitare quando il motivo è stato compreso e approvato. Le scelte occasionali non diventano regole generali; possono restare nel contesto di un exemplar.
• Il formato della memory card è allineato per analogia a quello delle Evidence; origine e dominio restano separati. Le Memory non entrano nel canone Evidence.
• La gestione avviene tramite CRUD e form interni a ThothII.
• L'evoluzione del modulo Memory è interna a ThothII, riusando l'infrastruttura dell'installazione e senza adottare un framework esterno per governarne il comportamento.
• Il progetto comprende ricerca semantica e lessicale ibrida in Qdrant, filtri sull'ambito e collegamenti espliciti fra card percorsi dal core. Non introduce un database a grafi dedicato e non rinvia il grafo a una successiva sperimentazione.
• PostgreSQL, già presente nell'installazione, è l'archivio autorevole di card, collegamenti e dipendenze, in tabelle proprie del modulo Memory. Sostituisce il registro JSONL; Qdrant è una proiezione rigenerabile, con sincronizzazione esplicita.
• I collegamenti sono proposti e approvati insieme alle card nel riepilogo finale e gestibili manualmente da Administration. Cancellare una card elimina anche i collegamenti che la coinvolgono, conservando le altre card.
• Gli exemplar solved_question usano il formato card con consumo consultativo.
• Il core prepara durante il lavoro un riepilogo finale modificabile delle nuove Memory e degli aggiornamenti proposti. Il reviewer seleziona cosa salvare; la cancellazione resta nel CRUD amministrativo.
• Le Memory vengono proposte nei gate pertinenti: chiarimenti all'inizio, regole di collegamento nello schema linking e regole di calcolo durante la costruzione SQL. Le approvazioni sono integrate nei gate, senza una domanda separata per ogni card.
• Una modifica sostituisce il contenuto corrente: non è richiesta una cronologia aggiuntiva delle revisioni delle Memory o una ricostruibilità storica dedicata.
• Se un riferimento allo schema rende una Memory inutilizzabile, il proprietario sceglie la cancellazione anziché lo stato «Needs review». Dopo una sincronizzazione riuscita dello schema fisico, il backend comunica gli elementi rimossi al modulo Memory, che cancella le card dipendenti e le proiezioni. La relazione fra card ed elementi dello schema deve essere strutturata; cleanup del Catalog ed errori di connessione non sono prove di rimozione fisica.
• I conflitti fra Memory ed Evidence si risolvono con azioni chiuse, specifiche e accompagnate dal contenuto risultante. La scelta alimenta una correzione degli archivi attraverso i rispettivi percorsi, con stato di pubblicazione esplicito; è sempre possibile dichiarare inadeguate le proposte e richiederne la riformulazione.
• La verifica usa test funzionali automatici e regressioni per casi concreti; non promette un miglioramento qualitativo generale o un benchmark con/senza Memory.
• Le sessioni esistenti non vincolano il design. Il loro azzeramento durante lo sviluppo, se necessario, è autorizzato; non è un'operazione eseguita da questi documenti.

La decisione di non conservare uno storico riguarda le Memory. Non modifica automaticamente il contratto di authoring e pubblicazione delle Evidence.

Salvataggio delle Evidence

In Q12 il proprietario rifiuta la separazione fra Save draft e Publish. La scelta successiva dell'editor esterno sostituisce il Save della form con il salvataggio dei file e un comando manuale di consolidamento: verifica la struttura, indica le correzioni necessarie e, se valido, aggiorna metadati, corpus e indice. Acquisisce anche aggiunte e cancellazioni. Segue il controllo del diff con commit e push manuali dell'operatore; non sono previsti watcher, Git automatico o un editor in Evidence management. La pagina mostra cartella, percorsi sull'host e comandi; il piano Evidence specifica la sequenza. Il consolidamento attiva localmente il contenuto; un push mancante o fallito lascia il trasferimento al remoto da completare manualmente. L'ultimo chiarimento elimina il requisito di aggiornare sessioni aperte a seguito di modifiche amministrative: durante tali modifiche il core è fermo o la contemporaneità può essere ignorata. Rimangono le correzioni deliberate dalla sessione stessa. La review di Q11 distingue le draft dello specialista dalle Evidence raffinate locali; raccomanda di preservare le prime e gestire le seconde su file persistenti, senza PostgreSQL condiviso o scritture automatiche nel repository delle fonti. In Q13 è approvata la precedenza della correzione manuale quando una fonte aggiornata la contraddice: resta attiva fino alla risoluzione esplicita del confronto in Evidence management. Le Evidence cancellate non ricompaiono automaticamente durante la rigenerazione. Q14 consente di crearle senza documento esterno, in R0 tramite un nuovo Markdown: una dichiarazione manuale sostiene il testo corrente, con l'eventuale documento originario conservato come provenienza distinta. Q15 limita la riacquisizione delle fonti esterne a una richiesta esplicita dell'amministratore; il normale salvataggio e il recall usano il contenuto già acquisito. L'ADR 0019 registra l'evoluzione del contratto, ancora da implementare.

Stato verificato nel repository

frontend/src/shell/AppShell.tsx contiene Administration con Database management, Workspace management e Pi management. Non contiene le due pagine richieste.

Il modulo Memory espone già comandi CLI per elenco, dettaglio, aggiornamento, cancellazione e ricerca, ma manca una superficie CRUD amministrativa web. Il riepilogo di una sessione mostra soltanto le Memory collegate alla sessione. Il contratto attuale della Memory descrive registro JSONL canonico e indice Qdrant derivato.

Le Evidence hanno già un percorso di consultazione e modifica dei documenti nel repository di authoring, descritto in Evidence: sources, preparation, and review. Manca una pagina amministrativa per queste operazioni dentro ThothII. Il contratto attuale prevede che ThothII legga e pubblichi il repository, senza modificarlo, creare commit o eseguire push: l'editing amministrativo richiede evolvere questo confine, come esplicitato nel progetto Evidence.

Esperienza comune

L'amministratore lavora nell'interfaccia operativa esistente, con una lista densa e leggibile e un'area di dettaglio. Si riusano tema, controlli, focus e navigazione già definiti in PRODUCT.md e DESIGN.md.

• Selettore di workspace, ricerca testuale, filtri combinabili, ordinamento e paginazione.
• Elenco completo dei record persistiti, indipendente dalla disponibilità della ricerca semantica. Una ricerca per similarità può affiancarlo, senza limitarlo ai pochi risultati del recall del core.
• Apertura del contenuto completo, dell'ambito di applicazione e della provenienza.
• Creazione e modifica Memory mediante form; per Evidence R0, percorsi ed esempi Markdown per editor esterni, consolidamento e seguito Git manuali.
• Cancellazione con indicazione precisa dell'oggetto e del suo effetto; per Evidence R0 la rimozione del file è acquisita dal consolidamento.
• Stato esplicito di salvataggio e disponibilità per il core, con recupero dagli errori.
• Filtri e posizione nell'elenco conservati quando si apre e si chiude un record.
• Controlli utilizzabili da tastiera; stato vuoto, nessun risultato e indisponibilità del servizio distinguibili. Chrome in inglese, contenuti nella lingua del workspace.

Le due pagine non dipendono dalla selezione di un database in Database management. Eventuali filtri su tabelle e colonne usano riferimenti al catalogo quando disponibili; la loro assenza non impedisce di consultare i contenuti registrati.

Componenti condivisibili: barra di ricerca e filtri, lista, paginazione, struttura del dettaglio, campi comuni della card, provenienza e feedback delle operazioni. Form Memory, istruzioni di manutenzione Evidence, autorizzazione, validazione, pubblicazione e persistenza rimangono responsabilità dei rispettivi moduli. Il riuso del frontend non introduce un archivio canonico unico per Memory ed Evidence.

Confini e integrazione

Entrambe le pagine appartengono ad Administration e devono applicare il controllo amministrativo anche nelle API. La collocazione visiva non assegna automaticamente le autorizzazioni di Database management ai nuovi moduli.

Il progetto Memory può essere consegnato senza attendere il progetto Evidence. I componenti comuni si estraggono quando servono ai flussi reali di entrambi. La verifica finale congiunta copre ordine della navigazione, accesso indipendente, filtri, percorsi di manutenzione e feedback coerenti, isolamento fra workspace e assenza di effetti incrociati fra i due domini.

La separazione fra Reference Vector Collection e Memory Vector Collection rimane quella dell'ADR 0017. Un'operazione amministrativa sulle Evidence non cancella le Memory; una cancellazione di Memory non elimina Evidence, Schema o metadati del database.

Piano esecutivo dei due progetti

Il riesame mantiene i requisiti funzionali Q1–Q15 e semplifica le scelte tecniche secondo le condizioni descritte sopra. L'ordine di lavoro parte dalla Memory e riusa poi i componenti effettivamente comuni per Evidence management. Le API e il coordinamento delle scritture attuano questi vincoli; la distinzione fra draft esterne e archivio locale sostituisce l'ipotesi di un unico archivio Git da modificare.

Ordine	Incremento	Risultato verificabile	Dipendenze
1	M1 — Archivio e CRUD Memory	PostgreSQL autorevole, API e pagina con elenco completo, filtri, form e cancellazione; collegamenti e dipendenze persistiti, proiezioni aggiornate o invalidate	Nessuna dipendenza dal progetto Evidence
2	M2 — Ricerca Memory	Ricerca ibrida con filtri ed espansione limitata dei collegamenti; risultati coerenti con il contenuto corrente	M1
3	M3 — Memory nel workflow	Riepilogo finale, uso delle categorie nei gate e cancellazione dopo sincronizzazione fisica riuscita	M1 e M2
4	E1 — Preparazione e archivio Evidence	Draft esterne, raffinamento del sistema, file canonici locali persistenti e protezione delle correzioni/cancellazioni	Q11–Q15 riesaminate; non richiede il runtime Memory
5	E2 — Manutenzione e consolidamento Evidence	Pagina con percorsi dei Markdown; comando manuale di verifica e attivazione; istruzioni per diff, commit e push	E1
6	E3 — Fonti e conflitti di aggiornamento	Importazione delle origini supportate, refresh esplicito, confronto con le correzioni manuali	E1 ed E2
7	X1 — Integrazione finale	Correzioni persistenti dei conflitti Memory/Evidence e verifica congiunta delle due pagine	M3 ed E3

E1–E3 sono un progetto separato: la sequenza è l'ordine operativo scelto per questa consegna, non una dipendenza tecnica dal modulo Memory. Il CRUD Memory è utilizzabile come primo incremento; M2 e M3 restano obbligatori nel progetto attuale. La correzione completa dei conflitti fra i due archivi si considera consegnata soltanto con X1.

Responsabilità di implementazione

• Il harness possiede contratti, persistenza e operazioni dei moduli Memory ed Evidence. Il backend applica autorizzazioni, espone le API e orchestra le operazioni; non introduce una seconda implementazione delle stesse scritture.
• Il Metadata Catalog rimane responsabilità del backend. Una sincronizzazione fisica riuscita chiama la pulizia Memory nello stesso flusso, con gli elementi effettivamente rimossi nell'ambito controllato e un recupero dopo interruzione. La pulizia non dipende dalla UI e non richiede un bus di eventi.
• Le pagine condividono controlli di consultazione e feedback; logica dei kind, fonte autorevole e attivazione rimangono nei rispettivi moduli. L'AppShell ospita le due voci autonome nell'ordine concordato.
• Le modifiche coordinate hanno gestione esplicita di errori e retry. I controlli sulla versione corrente impediscono sovrascritture inconsapevoli senza richiedere uno storico delle Memory. I retry non duplicano card o collegamenti. Il normale salvataggio è sequenziale, con un esito persistente da recuperare se incompleto; non richiede nuovi worker, code generiche o coordinamento delle sessioni aperte.

Verifiche e chiusura della consegna

Ogni incremento esegue i test delle operazioni che cambia e i controlli dei layer coinvolti: pytest/ruff per il harness, vitest e typecheck per backend/frontend. Le pagine sono verificate anche nel browser per navigazione, filtri, form, errori e uso da tastiera. I contratti e i test specifici sono nei due piani di progetto.

X1 verifica sia i conflitti che correggono Memory sia quelli che correggono Evidence, inclusi utente privo dell'autorizzazione necessaria, proposta rifiutata, errore di attivazione e retry. Il gate deve mostrare lo stato reale dell'archivio: la sola risoluzione della domanda corrente non dimostra che la correzione sia persistita. La verifica congiunta copre inoltre isolamento dei workspace, ordine dei link e assenza di cancellazioni incrociate.

I contratti correnti vengono aggiornati insieme al relativo codice. Alla fine si aggiornano PROJECT_STATE.md e documentazione operativa e si esegue la build strict. La verifica della generazione con un modello reale rimane distinta dai test deterministici; non si promette un benchmark generale di miglioramento qualitativo.

Gli incrementi approvati sono implementati e disponibili nel Docker locale. I rapporti di validazione distinguono i test deterministici, i servizi reali e le prove con il modello configurato. Le verifiche sintetiche non modificano la conoscenza PSD; la valutazione dei contenuti reali rimane una decisione del reviewer.