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](../reports/knowledge-archives-release.md).

La [revisione di semplicità](2026-09-08-memory-evidence-simplification-review.md)
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](2026-09-08-memory-management.md);
- [Evidence management](2026-09-08-evidence-management.md).

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 è:

```text
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](2026-09-08-evidence-management.md) 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](../adr/0019-author-evidence-in-app-with-automatic-activation.md) 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](../gestione-memory.md) 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](../evidence.md).
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](../adr/0017-separate-reference-vectors-from-runtime-memory.md).
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.