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

Revisione di semplicità: Memory ed Evidence

Data: 2026-09-08. Stato: archivio locale Markdown, editor esterni e consolidamento manuale con seguito Git scelti per la release 0; conseguenze esplicitate, restanti semplificazioni confermate, chiariti impatto core e controllo Git. Nessuna modifica applicativa.

Condizioni che guidano la revisione

Chi amministra il sistema è competente e deve vedere chiaramente cosa produce ogni azione. Durante il CRUD amministrativo di Memory ed Evidence si può assumere che non ci siano attività core in corso; la loro eventuale contemporaneità non è un caso da supportare con meccanismi dedicati.

Lo specialista di contesto può essere una persona diversa da chi gestisce l'installazione. Scrive le draft delle Evidence senza dover accedere a PostgreSQL, amministrarlo o disporre della stessa installazione. Il flusso fondamentale resta:

1. Lo specialista scrive e consegna le draft in documenti accessibili al sistema.
2. Il sistema le acquisisce e le raffina in Evidence strutturate.
3. Il sistema conserva localmente le Evidence per consultazione e manutenzione.

La proposta avanzata durante la revisione di usare PostgreSQL come archivio autorevole anche delle Evidence è ritirata. Confrontava il costo del solo CRUD interno, senza rappresentare adeguatamente l'autonomia di chi produce le fonti. Un database dietro un'interfaccia non richiederebbe di per sé accesso SQL agli autori, né un database condiviso; questo però non risolve da solo il flusso di redazione e consegna esterno. Non propongo di introdurre tale dipendenza.

Archivio locale delle Evidence accettato dopo il chiarimento

Il proprietario ha accettato i file locali e richiede una gestione facile da trovare e usare anche per uno specialista non tecnico. Il formato di lavoro è Markdown; JSONL non è una superficie di gestione delle Evidence. Il proprietario ha scelto editor esterni per la release 0, chiedendo di indicare chiaramente dove sono i file.

Contenuto	Responsabile	Conservazione e uso
Draft originali	Specialista di contesto	File o repository delle fonti, redigibili e consegnabili indipendentemente dall'installazione
Evidence raffinate e correzioni locali	Sistema e persone autorizzate alla manutenzione del contenuto	File Markdown in un archivio locale persistente dell'installazione, consultabili dall'applicazione e modificabili con editor esterni
Indice di ricerca	Sistema	Qdrant, ricostruibile dalle Evidence locali correnti

Questa è una revisione della parte tecnica di Q11: distingue l'autorità delle draft esterne dall'archivio delle Evidence raffinate usate dalla singola installazione. Il repository delle fonti rimane utilizzabile; il consolidamento delle Evidence locali non esegue commit o push e non richiede un PostgreSQL condiviso. Il seguito manuale ora richiesto comprende controllo del diff, commit e push nel repository che contiene i file curati. L'archivio è una working tree persistente; draft e unità curate possono stare nello stesso repository, mantenendo distinta la loro funzione.

Le conseguenze devono essere esplicite. Una correzione locale cambia ciò che usa quell'installazione e non viene rispedita automaticamente allo specialista o ad altre installazioni. I file restano trasferibili per un passaggio esplicito; non si costruisce una sincronizzazione bidirezionale. L'archivio locale va conservato e incluso nelle copie di sicurezza: dopo una correzione non è più un semplice output eliminabile e rigenerabile dalle draft senza perdita di lavoro.

Memory mantiene PostgreSQL locale come archivio già concordato. Le due pagine restano separate e riusano controlli comuni; la scelta della persistenza segue il flusso di produzione dei rispettivi contenuti.

Gestione della release 0: editor esterni scelti

Il proprietario sceglie il proprio editor sul Mac o PC, oppure vim, nano o equivalenti sul server. La proposta di editor applicativo è ritirata; non si integra una libreria di editing né si sviluppano form di contenuto Evidence.

Evidence management conserva lista, ricerca, filtri e dettaglio. Mostra la cartella del workspace e il percorso assoluto di ogni file, copiabile e risolto dalla configurazione effettiva. Indica l'host su cui si trova; con Docker mostra il percorso persistente accessibile sull'host. Le istruzioni distinguono draft originali e Evidence raffinate da manutenere e includono un esempio Markdown per crearne una.

Si modificano direttamente i file nell'archivio locale dell'installazione. Chi lavora su una copia sul proprio computer la riporta lì con i propri strumenti. Non sono richiesti upload/download web, nuove cartelle condivise o sincronizzazione.

Dopo aver salvato, aggiunto o rimosso file, l'operatore controlla lo stato Git, poi esegue un comando manuale di consolidamento: controlla la struttura attesa, segnala file e correzioni necessarie e, solo se i controlli passano, aggiorna metadati, corpus e indice. Il comando è rieseguibile dopo correzioni o errori tecnici. Seguono commit e push manuali, con le istruzioni della pagina e della documentazione operativa. Il core consulta solo l'ultimo corpus consolidato valido; i file in lavorazione e gli aggiornamenti falliti non devono introdurre contenuto parziale nella ricerca. La richiesta più recente sostituisce la proposta intermedia del pulsante Apply file changes; non servono un'esecuzione dalla UI, watcher o operazioni Git automatiche. Il salvataggio nell'editor da solo non aggiorna il recall. Il controllo dei file usa git status --short nel terminale; il normale git diff è disponibile per approfondire le righe cambiate, senza visualizzatore web o doppia revisione obbligatoria. Il comando riporta un breve riepilogo testuale delle modifiche.

Il Markdown locale deve essere realmente editabile: il testo visibile è autorevole, i campi richiesti sono documentati e i metadati derivati sono gestiti dal sistema. Il formato v3 attuale, che verifica il rendering contro una copia codificata del testo, va quindi adattato. Non basta indicare i percorsi dei file attuali e non si introduce un secondo archivio di scambio da sincronizzare. Questo comporta una modifica effettiva dei componenti core Evidence: parser, renderer, preparazione, validazione, normalizzazione e collegamento a indicizzazione/recall. E1 comprende nuova versione del contratto, conversione dei file esistenti e verifica del percorso completo; il formato interno tipizzato viene conservato dove possibile.

Creazione, modifica e cancellazione delle unità raffinate passano dai file e dallo stesso consolidamento. Un errore di accesso all'archivio non è una prova di cancellazione. Le correzioni approvate dal core continuano a chiamare direttamente il servizio di scrittura. Il proprietario ha confermato le restanti semplificazioni chiedendo di esplicitare impatto core e semplicità del controllo Git. Il piano Evidence specifica controlli, comando previsto e sequenza Git. Dopo il consolidamento il contenuto è disponibile localmente; finché commit/push non sono completati, non è versionato/trasferito al remoto. Il sistema si affida alla disciplina dell'operatore e non tenta di completare o riparare automaticamente la sequenza Git.

Conseguenze rispetto al piano precedente alla revisione

Il confronto riguarda il piano concordato prima del riesame: form strutturate per le unità, repository Git autorevole con scritture applicative e supporto alle modifiche amministrative durante sessioni aperte. Le funzionalità non erano ancora implementate: si confrontano due progetti, non una regressione già introdotta.

Aspetto	Cosa cambia	Conseguenza pratica
Gestione R0 delle Evidence	Editor esterno scelto al posto di editor e form nell'applicazione	Si usano strumenti già disponibili. La pagina indica i file; servono un Markdown realmente editabile, esempi e validazione in acquisizione. Si rinuncia alla guida e ai controlli durante la digitazione.
Applicazione delle modifiche esterne	Salvare i file nell'archivio ed eseguire il consolidamento manuale	Una copia sul Mac o PC va riportata nell'archivio con gli strumenti dell'operatore. Fino al consolidamento riuscito la modifica non è disponibile al core. Gli errori strutturali indicano il seguito necessario. Non si sviluppano trasferimenti file web o watcher.
Autorità delle Evidence raffinate	Archivio locale, distinto dalle draft esterne	Una correzione agisce su quell'installazione. Lo specialista che lavora alle draft e altre installazioni non la ricevono automaticamente.
Cronologia e distribuzione Git	Controllo del diff, commit e push manuali dopo il consolidamento	Git conserva e trasferisce quanto l'operatore committa e pubblica. La sequenza non è imposta né completata dal sistema: se il push manca o fallisce, il core locale può già usare modifiche non trasferite. Non c'è rollback applicativo o gestione automatica dei conflitti Git.
Ripristino dei dati	Le Evidence locali curate sono dati primari	Il backup deve comprenderle. Ricostruire tutto dalle sole draft recupererebbe la base, ma potrebbe perdere correzioni e cancellazioni locali; Clear deve preservare l'archivio.
Attività core contemporanee	Non vengono più gestite le modifiche amministrative durante il lavoro core	Se avvengono comunque, non è garantita la coerenza della sessione in corso. Non si aggiornano contesti o SQL già prodotti. Le successive elaborazioni usano il contenuto aggiornato dopo il completamento dell'operazione.
Salvataggio e indice	Operazione sequenziale con recupero minimo persistente	L'utente attende l'esito dell'indicizzazione. Un problema può richiedere Retry; il contenuto già salvato viene conservato e un esito incompleto non viene presentato come pieno successo. Il piano precedente già prevedeva questi esiti, non garantiva retry automatici.
Pulizia Memory dopo sync	Chiamata diretta nel flusso esistente	Stesso effetto funzionale, con meno coordinamento interno. Rimangono il recupero dopo interruzione, i limiti dell'ambito controllato e l'esclusione di errori di connessione o cleanup del solo Catalog.
Verifica semantica	Nessuna nuova valutazione generale o revisione obbligatoria a ogni Save	La responsabilità del significato resta allo specialista; i test verificano contratti e casi mirati. La validazione strutturale non garantiva la correttezza del dominio neppure nel piano precedente.

Sono invariati il riepilogo Memory, le categorie ammesse, i gate esistenti, la ricerca ibrida e i collegamenti, le correzioni persistenti dei conflitti e la protezione delle modifiche manuali. Le fonti vengono aggiornate su richiesta come già concordato. Le scritture deliberate dal core stesso restano supportate tramite lo stesso servizio: l'assenza di amministrazione concomitante non le elimina.

Non è prevista una rinuncia alle capacità di ricerca o al contenuto delle Evidence. Conservare gli stessi contenuti tipizzati, ambiti e indicizzazione evita una perdita di qualità dovuta a un taglio di funzionalità, ma l'equivalenza del nuovo percorso deve essere verificata. Il formato Markdown e un editor più semplice non sono, da soli, una garanzia di qualità o di assenza di errori.

Riesame di tutte le decisioni Q1–Q15

Decisione	Esito della revisione	Approccio più semplice e conseguenza
Q1 — Riepilogo Memory	Mantengo	Un riepilogo finale editabile, con selezione di cosa salvare. Nessuna approvazione ripetuta per ogni card durante la sessione.
Q2 — Aggiunte e aggiornamenti	Mantengo	Mostrare contenuto risultante e record sostituito. La somiglianza non avvia fusioni automatiche; la cancellazione semantica resta esplicita nel CRUD.
Q3 — Consumo nei gate	Mantengo	Usare i gate già previsti. Nessun nuovo percorso di approvazione per la sola consultazione di una Memory; exemplar consultativi.
Q4 — Conflitti Memory/Evidence	Semplifico l'esecuzione	La scelta mostra quale archivio cambia e con quale testo. Chiamare lo stesso servizio di salvataggio del CRUD, con un esito unico; niente secondo sistema di pubblicazione. Le correzioni deliberate dal core restano un caso da supportare.
Q5 — Dipendenze fisiche eliminate	Mantengo, con chiamata diretta	Alla fine della sincronizzazione fisica riuscita, chiamare la pulizia Memory nello stesso flusso. Mostrare le conseguenze nella conferma della sincronizzazione già esistente e il conteggio finale. Non introdurre bus di eventi o un nuovo controllo continuo del DWH.
Q6 — Verifiche	Mantengo il perimetro limitato	CRUD, filtri, persistenza, cancellazioni, recupero dall'errore e casi mirati di ricerca. Nessuna valutazione qualitativa generale a ogni salvataggio, nessun secondo modello giudice obbligatorio.
Q7 — Evoluzione interna	Mantengo	Riutilizzare componenti e servizi dell'installazione. Nessun framework esterno o ulteriore servizio per governare Memory.
Q8 — Ibrido e collegamenti	Mantengo entrambe le capacità	Riutilizzare la ricerca ibrida; collegamenti in una lista modificabile ed espansione limitata nel core. Nessun database a grafi, editor visuale di grafi o deduzione automatica di una rete di relazioni. Le capacità restano nel progetto attuale.
Q9 — PostgreSQL per Memory	Mantengo	Il database è già locale all'installazione; card, collegamenti e dipendenze restano coordinati. Qdrant è ricostruibile. Il flusso Memory non richiede un autore esterno indipendente.
Q10 — Cura dei collegamenti	Mantengo	Gestirli nello stesso riepilogo e dettaglio della card. Cancellare una card elimina i collegamenti incidenti e conserva le altre card.
Q11 — Archivio Evidence	Rivedo la soluzione tecnica	Draft esterne indipendenti e Evidence raffinate in file locali persistenti. Togliere commit/push dal CRUD. La modifica locale non aggiorna automaticamente la fonte dello specialista. La proposta PostgreSQL autorevole per Evidence è ritirata.
Q12 — Save e sessioni aperte	Adatto agli editor esterni	Dopo il salvataggio dei file, un comando manuale consolida e attiva le modifiche; l'operatore completa poi commit/push. Nessun workflow editoriale aggiuntivo, watcher, aggiornamento delle sessioni aperte o modalità manutenzione.
Q13 — Fonte cambiata e cura manuale	Mantengo, con confronto semplice	La correzione manuale prevale finché una persona decide altrimenti. Un cambiamento della fonte collegata rende disponibile il confronto; non serve dimostrare automaticamente una contraddizione semantica. Le cancellazioni non vengono annullate dalla rigenerazione.
Q14 — Creazione manuale	Mantengo tramite file	Un nuovo Markdown secondo l'esempio documentato consente una Evidence manuale con provenienza dichiarata e senza documento esterno obbligatorio. Il flusso principale draft dello specialista → raffinamento locale rimane disponibile e indipendente.
Q15 — Refresh delle fonti	Mantengo	Acquisizione e raffinamento delle fonti aggiornate su richiesta esplicita. Consolidamento e recall usano il contenuto locale; non cercano nuove versioni remote.

Restano confermati due link autonomi sotto Database management, CRUD completo con filtri, assenza di storico aggiuntivo delle Memory e assenza di vincoli sulle sessioni di sviluppo già esistenti.

Riduzioni trasversali del piano

Un'operazione alla volta, con esito comprensibile. Save per Memory e consolidamento manuale per Evidence validano e aggiornano l'indice in sequenza. L'interfaccia mostra operazione in corso, completata oppure errore con azione di recupero. Non espone un workflow editoriale di stati draft, approved, published per il normale CRUD. La draft dello specialista è il documento di ingresso della preparazione, non un secondo pulsante di salvataggio dell'editor delle unità locali.

Recupero minimo dopo errore. Se l'archivio è stato aggiornato ma Qdrant no, va detto e deve essere possibile riprovare, per Evidence rieseguendo il comando. Serve un'indicazione persistente del lavoro incompleto, sufficiente anche per ripulire una card già cancellata dopo un riavvio. La ricerca non deve usare contenuti rimossi o superati alla domanda successiva. Il piano non imponeva già una outbox o nuovi worker: la revisione rende esplicito che non sono richiesti né code generiche né sincronizzazioni continue.

Pulizia schema diretta e ripetibile. Il flusso esistente del Catalog può richiamare Memory dopo l'applicazione dello schema. Occorre coprire il crash fra le due scritture: conservare la pulizia pendente sul run oppure verificare di nuovo le dipendenze contro lo snapshot fisico riuscito e il suo ambito. Ricalcolare solo il nuovo diff perderebbe le rimozioni già applicate. La rimozione manuale di metadati Catalog o un errore di connessione non autorizzano a cancellare Memory.

Nessuna gestione delle sessioni amministrate contemporaneamente. Non progettare aggiornamenti a caldo, ripristino dei contesti già letti, invalidazione dello SQL, notifiche alle sessioni o generazioni aggiuntive per lettori paralleli. Rimangono le scritture esplicitamente richieste dalla sessione stessa: il riepilogo Memory e una correzione Evidence approvata chiamano il medesimo servizio e ne gestiscono l'esito prima di proseguire. Questo caso non richiede coordinare tutte le altre sessioni.

Pagine essenziali. Ricerca testuale, filtri e lista completa permettono di trovare i contenuti; la ricerca semantica appartiene anzitutto al core. Memory conserva le form; Evidence espone dettaglio, percorsi e istruzioni per la modifica esterna. Hash e manifest restano gestiti dal sistema. Si riusano i controlli di accesso esistenti; chi modifica i file necessita dei permessi sul relativo filesystem, senza accesso a PostgreSQL o un nuovo sistema generale di ruoli.

Conseguenze delle azioni da rendere visibili

Azione	Conseguenza da comunicare
Save riuscito	Il contenuto corrente è conservato ed è disponibile per le successive elaborazioni.
Save con errore dell'indice	Il contenuto è conservato; la disponibilità alla ricerca non è completata. Retry completa il lavoro senza richiedere di riscrivere la modifica.
Salvataggio nell'editor esterno	Cambia il file, ma non aggiorna il recall. Una copia esterna va prima riportata nell'archivio dell'installazione.
Consolidamento Evidence	Acquisisce aggiunte, modifiche e cancellazioni locali; verifica la struttura e, se valida, aggiorna metadati e indice. Un errore indica cosa correggere; si riesegue il comando dopo la correzione o un errore tecnico.
Commit e push manuali	Versionano e trasferiscono al repository remoto i file consolidati. Un errore Git si risolve manualmente; il consolidamento locale già riuscito non viene annullato.
Delete di una Memory	La card e i collegamenti che la coinvolgono vengono rimossi; le altre card restano.
Delete di una Evidence	L'unità locale non viene più usata né ricreata automaticamente; la draft originale e le altre unità derivate restano.
Refresh sources	Si acquisiscono nuove versioni delle fonti e si preparano le Evidence interessate; le correzioni locali protette non vengono sovrascritte.
Sincronizzazione fisica	Le Memory dipendenti da elementi effettivamente eliminati vengono cancellate; l'ambito e il conteggio dell'effetto sono visibili.
Preprocessing Clear	Si eliminano i dati derivati previsti dal comando; le Evidence canoniche locali e le Memory rimangono.

Non sono necessarie conferme ripetute su Save. Per le cancellazioni si usa una conferma concreta sull'oggetto e sulle conseguenze, integrando gli effetti nella conferma già presente quando l'azione è una sincronizzazione distruttiva.

Cosa va comunque implementato

Il raffinamento locale e la scrittura di Markdown canonico/manifest esistono in harness/tht/evidence/authoring.py. Preparano e validano gli output prima della sostituzione con staging e rollback; non eseguono commit/push. Va separato il requisito di Git worktree dalla preparazione del contenuto e va integrata l'acquisizione delle draft esterne.

La materializzazione corrente in backend/src/workspaces/evidence/materialization.ts è invece ricostruita da una revisione Git: non è già l'archivio locale scrivibile proposto. Il renderer e il preprocessing devono consumare il nuovo archivio persistente. Una modifica locale non deve richiedere un nuovo commit della fonte.

Si riusa l'attivazione Evidence esistente dove serve a verificare un candidato e a recuperare da errori; l'assenza di lettori contemporanei non rende atomici file e Qdrant. La mutazione resta circoscritta alle Evidence e preserva Schema, relazioni, LSH e Memory. Il suo successo non cancella blocchi di readiness del Catalog.

Le verifiche prioritarie coprono il percorso draft → raffinamento → elenco/CRUD locale → ricerca, persistenza dopo riavvio, retry dopo errore, mancata ricomparsa delle unità eliminate, refresh con correzioni locali, isolamento dei workspace e conservazione dell'archivio locale dopo Clear. Le prove di aggiornamento live da amministrazione vengono eliminate; resta la verifica delle correzioni deliberate dal core stesso.

L'ordine resta Memory, Evidence e integrazione finale. I dettagli degli incrementi nei due piani sono lavoro interno; per l'utente rimangono due gestioni autonome.