Panoramica

L'Analista geopolitico strutturale è uno strumento per condurre analisi geopolitiche rigorose seguendo il metodo strutturale, fase per fase. Ogni fase compone un aspetto dell'analisi (ammissibilità, parametri, classificazione, proprietà dello spazio, relazioni/attori, scenari, ecc.).

Che cosa fa l'applicazione

Dato un tema, ANGST sviluppa un'analisi geopolitica per fasi: ne verifica l'ammissibilità, fissa i parametri dell'analisi e costruisce passo dopo passo il quadro dello spazio, delle relazioni e degli attori, fino alle conclusioni, agli scenari e a un report finale. Ogni fase si appoggia sui risultati delle precedenti.

L'utente può intervenire durante l'analisi, modificando alcuni dei parametri che l'applicazione propone, per orientare lo sviluppo e i risultati. I dettagli di ogni fase e dei parametri modificabili sono nelle sezioni dedicate; l'architettura è nella sezione «Architettura del sistema».

📖 Base metodologica: l'approccio all'analisi condotta da questo strumento si basa sul testo metodologico «L'analisi geopolitica» di E. Boria (Carocci Editore). Lo stesso testo è il riferimento fisso della bibliografia del report finale, sempre con il numero 1 (Bibliografia::RIFERIMENTO_METODOLOGIA, api/Bibliografia.php).

Quando l'app si ferma dopo una fase, sei tu a decidere se proseguire, ottenere informazioni sullo stato corrente, o ricalibrare elementi precedenti.

In breve

  • Scrivi qualcosa per proseguire alla fase successiva
  • Usa slash-comandi (/stato, /compara, ecc.) per azioni specifiche
  • Leggi le correzioni di P10 se suggerite, ma sono informative, non obbligatorie
  • Il report finale (P13) può essere generato con /concludi report dopo P12, oppure subito con /concludi da qualunque fase
💡 Tip: Usa /stato in qualsiasi momento per verificare dove sei nella pipeline e quanti token hai consumato fino a quel punto.

Architettura del sistema

Riferimento tecnico per chi amministra o modifica ANGST: container Docker e strumenti di infrastruttura (Caddy, Adminer, code-server, backup-console), architettura del backend PHP, pipeline delle fasi P00–P14, e struttura completa delle cartelle del progetto — con diagrammi Mermaid.js e la spiegazione di ogni modulo.

📐 Architettura del sistema — apri la pagina di riferimento tecnico (si apre in una nuova scheda, riservata all'utenza admin).

Comandi disponibili

Fai click su questi comandi slash (/comando) in qualsiasi momento durante l'analisi per eseguire azioni specifiche.

Comando Quando usarlo Effetto
/stato In qualsiasi momento Mostra fase corrente, fasi completate, lacune dichiarate e totale token consumati
/tipo Dopo P04 Visualizza la classificazione corrente (tipo A, B, C.1, C.2, SOSPESO)
/riclassifica [tipo] [motivazione] Dopo P04, massimo 1 volta Impone una nuova classificazione: tipo (A, B, C.1 o C.2, in maiuscolo) e motivazione sono obbligatori. Il sistema non può rifiutarla; la motivazione guida tutte le fasi successive e il report finale dichiara che è stata imposta dall'utente — vedi "Riclassificazione imposta" nella sezione P04 qui sotto
/concludi report Dopo P12 Produci il report finale: genera il report narrativo assemblato (P13). È il comando che compare in azzurro nelle azioni di P12; funziona ancora anche il vecchio /report
/concludi Da P01 a P12 "Vai direttamente al report finale": esegue tutte le fasi successive una dopo l'altra, senza fermarsi tra l'una e l'altra, fino al report (P13). Compare in azzurro tra le azioni di ogni fase. Usa lo stesso ciclo della modalità automatica (Orchestrator::avanzaPipelineAutomatica(), risposta in streaming con la barra di avanzamento) ma parte da dove si è arrivati, e l'analisi resta semi-automatica. Una volta avviato non si può intervenire a metà (per esempio con /riclassifica); se una fase non riesce o la quota finisce, si ferma lì e un nuovo /concludi riparte da quel punto. Prima di partire compare un popup di conferma («Concludere l'analisi?») che avvisa che, se confermato, ANGST eseguirà in automatico tutte le fasi successive senza che l'utente possa intervenire sull'analisi, e che le fasi eseguite in una volta consumano token della quota. Se si interrompe dopo aver completato alcune fasi, la chat viene ricostruita dallo stato salvato sul server (come «Riprendi l'analisi») perché le fasi completate compaiano anche nel report esportato
/compara [caso] Dopo P11 Confronta l'analisi con un altro caso (es: /compara geopolitica del Pacifico). Attualmente disattivato: risponde «Comando non disponibile» (il pulsante non compare più nei pannelli «Azioni disponibili»; ricompare con la costante accesa). Si riattiva con define('COMPARA_ABILITATO', true); in config-work.php.
/abbandona In qualsiasi momento Azzera l'analisi corrente e ne inizia una nuova — stesso effetto del bottone "Nuova analisi", ma senza dover uscire dalla chat. Prima compare un popup di conferma («Abbandonare l'analisi?»): se confermi, l'analisi in corso è chiusa e non si può più proseguire (la chat salvata automaticamente per gli utenti resta in «I miei report»).

Avanzamento automatico

Se non usi un comando slash, scrivi un testo libero per proseguire alla fase successiva:

  • Una frase, una domanda, un'osservazione
  • Anche solo continua o ok
  • Fa avanzare la pipeline alla fase successiva — ma il suo contenuto viene letto nel merito dal modello solo subito dopo P01 (il messaggio che fa scattare P02, trattato come preferenze dell'utente: vedi la sezione P02 (Parametri)). Da P03 in poi è solo un segnale di "prosegui": il suo contenuto non viene più passato ai prompt delle fasi successive, qualunque cosa tu scriva
✓ Consiglio: Se vuoi passare al passo successivo senza aggiungere contesto, digita o fai click su continua o premi invio dopo aver letto l'output.

L'interfaccia: cosa vedi e cosa succede mentre l'app lavora

A sinistra c'è la barra laterale, a destra la chat in cui si svolge l'analisi. Questa sezione spiega che cosa mostra ogni blocco, come leggere i messaggi che compaiono mentre l'app aspetta il modello e che cosa trovi alla fine.

La barra laterale

DoveCosa mostra
Intestazione, pallino con numeroSi accende per qualche secondo ogni volta che Gemini esegue una vera ricerca sul web (grounding); il numero conta le ricerche viste dalla pagina da quando è stata aperta (dopo un ricaricamento riparte da zero, mentre la riga «Ricerche web» del pannello Token / Costo ricostruisce il totale dallo stato). Se resta a zero, finora non è stata eseguita nessuna ricerca web (per esempio in modalità Certificata, che le esclude)
ModalitàInterruttore semi-automatica / automatica. In semi-automatica l'app si ferma dopo ogni fase e aspetta te; in automatica esegue tutto il percorso e mostra solo il risultato finale. Si sceglie prima del primo messaggio e non si cambia a metà analisi
ConoscenzaCompare solo se EIL_ABILITATO è true in config-work.php: vedi la sezione Modalità di conoscenza
Ricerca approfonditaInterruttore, attivo all'avvio di ogni analisi (valore iniziale in RICERCA_APPROFONDITA_DEFAULT; si può spegnere prima del primo messaggio) (se RICERCA_APPROFONDITA_ABILITATA e la modalità di conoscenza non è Certificata): prima di passare alla fase successiva prova a colmare con una ricerca web reale le lacune dichiarate (solo se LACUNE_MAX_RICERCHE_PER_ANALISI è maggiore di 0: oggi in test e produzione è 0, quindi non lo fa); con FATTI_RIFERIMENTO_ABILITATI acceso governa anche la ricerca dei «fatti di riferimento» prima di P03 (vedi la tabella delle costanti di configurazione). Vedi Lacune dichiarate
PercorsoLe fasi dell'analisi: grigie quelle non ancora raggiunte, in verde lampeggiante quella attuale, in verde fisso e più tenue quelle completate. P05 compare solo per i temi di tipo C; P0X raggruppa il ramo scelto (relazioni e attori per il tipo A, attore dominante per il tipo B)
ClassificazioneIl tipo assegnato in P04 (A, B, C.1, C.2 o SOSPESO); «non ancora determinata» finché non è stato deciso
Lacune dichiarateL'elenco accumulato lungo l'analisi, con le più gravi in cima. Su smartphone il numero compare sulla scheda «Lacune»
Token / CostoToken di input e di output consumati dalla sessione (più pensiero, ricerche web ed EIL quando ci sono), il totale e il costo stimato. Aggiornati a ogni fase. La configurazione di sistema (prezzi dei token e del grounding: vedi Token e costi) non si apre più da qui: sta nella pagina Amministrazione, sezione «Configurazione di sistema», visibile solo all'utenza admin
AccountQuanti token e quanto budget hai consumato rispetto alla tua quota (o «illimitato»), con due barre
In fondo? Guida (questa, per gli amministratori), 📋 I miei report e 🗂 Tutti i report (vedi Salvataggio e gestione dei report) e Nuova analisi; sotto, staccato da quest'ultimo, il pulsante rosso Amministrazione (utenti, quote, file di log; si apre in una nuova scheda), poi la versione dell'applicazione. In alto trovi il tuo nome seguito da «· admin» e il pulsante Esci

Su computer puoi allargare o restringere la barra laterale trascinando il bordo verticale tra la barra e la chat: con una barra più larga le etichette delle fasi si leggono per intero. Su smartphone la barra diventa una fila di schede in basso (Percorso, Lacune, Token, Account, Altro) che aprono ciascuna il proprio pannello.

Mentre l'app aspetta: cosa significano i messaggi

Ogni fase richiede almeno una chiamata al modello e alcune ne richiedono molte: una fase può durare da pochi secondi a qualche minuto, e mentre l'app aspetta la casella di scrittura e i comandi sono disattivati. Per capire che sta lavorando, e su cosa, compaiono questi indicatori.

In modalità semi-automatica sotto l'ultimo messaggio appare una riga grigia con tre puntini che pulsano, il testo della fase in corso e un cronometro che parte da zero, per esempio:

  • Sto elaborando la fase P10 – Autoverifica… · 42 s
  • Sto verificando la richiesta: fase P01 – Ammissibilità… — il primo messaggio, quando l'app capisce se è un tema e se è ammissibile
  • Sto elaborando la fase P08 – Attori geopolitici (2/2)… — nel gruppo P07-P08 o P09a/b/c indica anche il passo (qui il secondo di due)
  • Sto elaborando la fase P04 – Classificazione (riclassificazione indicata da te)… — dopo /riclassifica

Anche i comandi che producono una fase hanno il loro messaggio: /compara (P14), /riformula (di nuovo P01) e il vecchio /report (P13). I comandi che non chiamano il modello, come /stato o /tipo, rispondono subito con il semplice «elaborazione in corso». /concludi e /concludi report usano invece la barra di avanzamento descritta qui sotto, perché eseguono più fasi in una sola richiesta.

Il blocco «Caratteri dello spazio» (P06) è il più lungo perché non è una sola chiamata ma tredici in sequenza: le dodici proprietà e poi la sintesi. L'app le esegue una dopo l'altra senza chiederti nulla e la riga cambia a ogni passo, con lo stesso cronometro che conta il tempo dell'intero blocco:

  • Sto elaborando la fase P06 – Caratteri dello spazio · proprietà 6/12: Mobilità…
  • Sto elaborando la fase P06 – Caratteri dello spazio · sintesi trasversale delle 12 proprietà… — l'ultimo passo, che rilegge tutte le proprietà

In modalità automatica, e dopo /concludi, l'analisi gira in un'unica richiesta: al posto della riga compare una barra di avanzamento con le tappe del percorso (le stesse del blocco «Percorso», da P01 a P14), che si colorano man mano. Durante il blocco P06 sotto la barra compare la stessa riga del passo in corso («proprietà 6/12: Mobilità…»). Il titolo della barra dice cosa sta succedendo: Analisi automatica in corso… oppure Completamento dell'analisi fino al report finale…. Alla fine i risultati compaiono tutti insieme.

ℹ️ Se la barra è ferma da minuti può essere un'attesa in coda per il limite di richieste del servizio di intelligenza artificiale: sotto la barra compare un avviso con i secondi di attesa e la fase interessata, e l'analisi riprende da sola. Trovi la spiegazione completa nelle Domande frequenti.

Quota e limiti

  • Il pannello Account confronta i consumi dell'utente con la quota assegnata dall'amministratore (default DEFAULT_QUOTA_TOKEN_TOTALE e DEFAULT_QUOTA_BUDGET_TOTALE, modificabili per ogni utente da Amministrazione). Oltre la soglia SOGLIA_AVVISO_QUOTA_PERCENTUALE (90) compare l'avviso «Stai per esaurire la quota disponibile. Contatta l'amministratore per una ricarica»; a quota esaurita l'app non accetta altri messaggi finché la quota non viene ricaricata da Amministrazione.
  • Se è impostato un tetto per singola analisi (LIMITE_TOKEN_SESSIONE e LIMITE_COSTO_SESSIONE, uguale per tutti gli account), sotto i totali compare un avviso quando ti avvicini («Stai per raggiungere il limite di sessione…») e, al 100%, «Limite di sessione raggiunto. Avvia una nuova analisi per continuare».

Alla fine dell'analisi

Dopo il report (P13) trovi, oltre alla bibliografia:

  • il Grafo attori e relazioni, un diagramma ricavato automaticamente dai dati già raccolti (attori, ruoli, presa dello spazio, concorrenti citati) — non da un'ulteriore elaborazione del modello, quindi più povero della descrizione in prosa; passando il mouse su un attore si evidenziano i suoi collegamenti. È incluso nel report finale che puoi salvare;
  • l'elenco Siti Web visitati, cioè le pagine trovate dalle ricerche web svolte durante l'analisi, senza duplicati. Compare solo in chat e non entra mai nei report salvati (lo scrive StateManager::appendSitiVisitati() da ogni ricerca web);
  • in modalità automatica e dopo /concludi, un avviso «Prima di concludere» che rimanda alla sezione Autoverifica per i limiti e i problemi rilevati.

Dietro le quinte: streaming, battito e fase successiva

Le due modalità hanno protocolli diversi (api/index.php):

RichiestaRispostaCosa vede l'utente
Semi-automatica, una faseJSON singolo (Content-Type: application/json)La riga con puntini, testo della fase e cronometro; per P06 il frontend concatena da solo le 13 richieste (una per proprietà, poi la sintesi) e aggiorna lo stesso indicatore
Automatica, oppure /concludi (Orchestrator::eComandoConcludi())NDJSON in streaming (application/x-ndjson): una riga JSON per evento, l'ultima è la risposta veraLa barra di avanzamento; la risposta finale è il bundle analisi_automatica_completata con tutte le fasi, riprodotte in chat saltando quelle già mostrate

Il frontend riconosce lo streaming dall'intestazione Content-Type della risposta, non dalla modalità scelta: per questo /concludi funziona anche in un'analisi semi-automatica. Gli eventi sono:

{"tipo":"progresso","fase":"P04","prossima":"P06_posizione_assoluta","grounding_richieste":1}
{"tipo":"attesa","motivo":"coda","stato":"in_corso","secondi":12,"fase":"P06_accessibilita"}
(riga vuota: battito ogni 10 s, tiene viva la connessione)
{"tipo":"analisi_automatica_completata", ...}
  • progresso: una fase è completata. prossima è la fase che sta per girare, ricavata da Orchestrator::prossimaFase() — l'unica definizione dell'ordine delle fasi, usata anche da avanzaPipeline() — con lo stato già aggiornato (quindi sa se P04 ha assegnato un tipo C e porta a P05, o A/B e porta a P06). La barra la usa per scrivere il passo in corso di P06. grounding_richieste c'è solo se la fase ha fatto ricerche web.
  • attesa: una chiamata a Gemini aspetta a lungo (coda del limitatore, o nuovo tentativo dopo un 429). Mostrato sotto la barra e nascosto al prossimo evento; vedi Quanti utenti insieme?.
  • Righe vuote: il battito di GeminiClient e delle attese EIL, ignorate dal parser.

Se un /concludi si interrompe (errore di validazione, quota, limite di sessione) lo stato resta alla fase raggiunta; il frontend, se la richiesta aveva già completato qualche fase, ricostruisce la chat dallo stato del server con lo stesso meccanismo di «Riprendi l'analisi» (?riprendi=1), così le fasi eseguite senza essere state mostrate compaiono, e finiscono nel report esportato. Un secondo /concludi riparte da lì.

Modalità di conoscenza (EIL)

Con EIL_ABILITATO = true (config.php / config-work.php) e le credenziali configurate, in sidebar compare un selettore Conoscenza a quattro opzioni. Come la Modalità, la scelta si fissa al primo messaggio (fase P00) e non cambia a metà analisi. Con la costante a false il selettore è nascosto e nessuna query a EIL parte, nemmeno chiamando l'endpoint a mano (controllo autoritativo lato server).

ModalitàGrounding GeminiQuery a EILRicerca approfondita
Web (default)autonomo, come oggimaidisponibile se abilitata
Certificataforzato spento1 per macro-sezione, obbligatoriadisattivata (userebbe il web)
Mistaautonomo1 per macro-sezione, come fonte primaria nel promptdisponibile, colma le lacune dopo EIL
Mista integrataautonomo1 per macro-sezione + 1 chiamata Gemini di arricchimento per sezionedisponibile

Macro-sezioni

EIL è interrogato una volta per macro-sezione, non per fase: S1 inquadramento (P03–P04), S2 caratteri dello spazio (P05–P06), S3 relazioni/attori o attore dominante (P07–P08 oppure P09a-c). La risposta è memorizzata in eil_sezioni nello stato dell'analisi e riusata da tutte le fasi della sezione, con lo stesso eil_session_id (follow-up per EIL).

Se EIL non risponde

  • Certificata: l'analisi si sospende con tipo: 'eil_non_disponibile', prima di segnare la sezione come interrogata — così un semplice reinvio del messaggio ritenta EIL. Nessun'altra fonte è ammessa in questa modalità.
  • Mista / Mista integrata: non blocca. La fase prosegue: la sezione è segnata come "vista" senza contesto EIL, e grounding + ricerca approfondita restano il fallback.
  • EIL risponde ma senza fonti pertinenti (citations e sources_consulted vuoti): non è un errore. In tutte le modalità l'analisi prosegue; in Certificata ciò che manca resta lacuna.

Provenienza nel report

Nelle modalità EIL, il report P13 marca le citazioni di documenti certificati con [EIL] dopo la parentesi — es. (limes-13062026.pdf, n.d.) [EIL] — e in bibliografia mostra il chip 📚 documento certificato (EIL). Le fonti web restano (Autore, Anno) senza marcatore. Gli "elementi aggiuntivi da ricerca Gemini" della modalità integrata vanno etichettati con la loro provenienza reale (ricerca_web_attiva / inferenza_propria), mai come EIL.

Vedi anche Token e costi per come il consumo EIL entra nei totali, e Fonti e bibliografia per la tabella completa delle provenienze.

Flusso della pipeline

Ecco il percorso completo dell'analisi, con i due rami principali (A/B) che si diramano dopo la classificazione (P04):

P01 Ammissibilità ↓ P02 Parametri ↓ P03 Introduzione ↓ P04 Classificazione (tipo A, B, C.1, C.2, SOSPESO) ↓ ├─ Tipo C? → P05 Spazializzazione └─ Tipo A/B/SOSPESO? → (salta P05) ↓ P06 Caratteri dello spazio (12 proprietà + sintesi) ↓ ├─ Tipo A → P07 Relazioni tra gruppi │ ↓ │ P08 Attori geopolitici │ └─ Tipo B → P09a Coesione interna (attore) ↓ P09b Presa di controllo ↓ P09c Fattori di forza ↓ P10 Autoverifica (⚠️ leggi bene i problemi qui) ↓ P11 Conclusioni ↓ P12 Scenari ↓ /concludi report → P13 Report narrativo ↓ /compara → P14 Comparazione (opzionale; DISATTIVATO: risponde «Comando non disponibile»)

Rami paralleli (A vs B)

Tipo A: Analisi di uno spazio geopolitico e le relazioni tra gruppi di attori

  • P07 analizza le conflittualità e le relazioni
  • P08 mappa i singoli attori e il loro peso

Tipo B: Analisi di uno spazio sottoposto al controllo di un attore dominante

  • P09a esamina la coesione interna dell'attore
  • P09b valuta l'intensità della presa di controllo
  • P09c identifica i fattori di forza e proiezione
ℹ️ Nota: Il tipo viene assegnato in P04 e confermato in P06. Se il tipo rimane indeterminato, si utilizza A come default.

Quando la pipeline attende una tua scelta

L'app si ferma dopo ogni fase e attende il tuo input. Ecco cosa succede in ciascun punto:

P01 — Ammissibilità

Il tema proposto viene valutato. Se ammesso in quanto ritenuto suscettibile di essere affrontato in una prospettiva geopolitica (e quindi non di diverso approccio disciplinare), la pipeline ti chiede di continuare. Se rifiutato o riformulabile, suggerisce un'alternativa. L'analisi non prosegue: il testo scritto dopo il rifiuto (o la riformulazione accettata con il pulsante) è un nuovo tema e riparte da P01 (Orchestrator::ripartiDaP01(), come /riformula), con modalità e ricerca approfondita dell'avvio conservate. Una semplice parola di continuazione («ok», «continua») non fa nulla: risponde con un invito a scrivere un tema.

P02–P05, P06, P07–P09, P11–P12

Al termine di ogni fase, digita qualcosa (comando slash o testo libero) per proseguire. L'output mostra i risultati della fase corrente in forma strutturata (chip colorati, tabelle, sezioni).

P10 — Autoverifica ⚠️

Questa è la fase critica: P10 revisiona tutta l'analisi precedente e segnala:

  • Coerenza complessiva (soddisfacente / con riserve / problematica)
  • Problemi rilevati (leader-centrismo, monocausalità, strutturale/contingente non distinti)
  • Correzioni proposte per ogni problema

Vedi la sezione P10 (Autoverifica) per capire come interpretare e applicare le correzioni.

P13 — Report

Dopo P12, fai click su /concludi report per generare il report narrativo assemblato. Se non hai già cliccato su /concludi report, la pipeline ti suggerirà di farlo.

P14 — Comparazione (opzionale)

Dopo P11, puoi usare /compara [descrizione] per confrontare la tua analisi con un altro caso. Non è obbligatorio; P13 si genera in ogni caso. Attualmente disattivato: risponde «Comando non disponibile» (il pulsante non compare più nei pannelli «Azioni disponibili»; ricompare con la costante accesa). Si riattiva con define('COMPARA_ABILITATO', true); in config-work.php.

Fase P01: Ammissibilità

P01 è il gate d'ingresso della pipeline: prima di avviare l’analisi l’applicazione si preoccupa di verificare che il tema proposto sia davvero trattabile con il metodo geopolitico strutturale. È l'unica fase che può interrompere l'analisi (esito RESPINTO) invece di limitarsi a segnalare un problema e proseguire.

Il test decisivo

Tutto il gate ruota attorno a una sola domanda, applicata al tema proposto:

"Lo spazio in esame è saldamente nelle mani di un singolo attore politico, oppure è conteso o condiviso tra più poteri?"

Se questa domanda non è nemmeno formulabile — non esiste una porzione di spazio di cui si possa predicare il dominio o la contesa — il tema non ammette una risposta geopolitica e va respinto o riformulato. P01 verifica quattro condizioni in sequenza: esiste un candidato-spazio (esplicito o ricavabile), è davvero uno spazio materiale e non una metafora, vi si esercita potere osservabile, e la risposta sarebbe informativa (non ovvia e priva di conseguenze).

I campi che P01 restituisce

CampoCosa rappresenta
esitoAMMESSO, AMMESSO_CON_RISERVA (spazialità debole o rendimento basso, ma il test regge), RIFORMULABILE o RESPINTO
test_decisivo.*formulabile, spazialita_reale, potere_esercitato, risposta_informativa — le quattro verifiche del test, una per una
categoria_blacklistQuale delle cinque famiglie di temi non adatti (o nessuna) motiva un eventuale rifiuto
condizioni_alta_idoneitaQuali delle cinque condizioni che rendono un tema particolarmente adatto sono soddisfatte
tipo_previstoAnticipazione (non vincolante) del tipo che P04 assegnerà: A, B, C.1, C.2 o indeterminato
limiti_da_dichiarareDomande che, anche su un tema ammesso, il metodo non potrà mai soddisfare (es. ponderare i fattori, prevedere il breve periodo)
limiti_generalizzabilitaSolo se il tema è ammesso: in una o due frasi, fin dove è lecito estendere le conclusioni dell'analisi ad altri casi, aree o periodi (testo libero, null se respinto o riformulabile). Prima stava in P02, dove l'utente poteva riscriverlo; ora lo propone P01 e non è modificabile (P01 non ha il modulo di modifica). Viene letto da P02 e P03 (ricevono l'esito di P01); non arriva alle fasi successive
riformulazione_propostaVersione spaziale del tema, proposta quando il test fallisce così com'è ma esiste un'alternativa recuperabile
disciplina_alternativaSe il tema è respinto, quale altra disciplina (storia, scienza politica, psicologia politica…) è più adatta
rendimento_attesoalto se ricorre almeno una delle cinque condizioni di alta idoneità, basso altrimenti (medio è un valore intermedio ammesso dallo schema)
motivazioneDue o tre righe che spiegano l'esito, riferite al test decisivo — non impressioni generiche. Campo obbligatorio
regole_applicateLe sezioni di 00-ammissibilita.md che il modello dichiara di aver applicato (file, sezione, perché) — auto-dichiarazione del modello, non verificabile: vedi "Come leggere le regole citate" nella sezione File di log

Le cinque famiglie di temi non adatti

CategoriaPerché fallisce il test
sequenza_episodiLa spiegazione sta nella catena degli eventi (un negoziato, lo svolgimento di una guerra), non nella configurazione spaziale — attenzione a non confondere il conflitto in sé (non adatto) con lo spazio conteso in cui si svolge (perfettamente adatto)
vita_istituzionePesano tattiche di partito ed equilibri interni contingenti — "perché quell'organo ha deciso X"
singolo_leaderRichiederebbe un profilo psicologico individuale, fuori dagli strumenti dell'analista geopolitico
spazialita_deboleIl tema riguarda ciò che un gruppo pensa o giudica: mapparne le manifestazioni concrete produce solo indizi marginali
componente_spaziale_marginaleLa geografia del fenomeno esiste ma è poco più di una curiosità rispetto a una portata etica, sociale o giuridica ben più ampia

Le ultime due sono le "categorie senza recupero": non consentono mai l'esito AMMESSO, e se il tema risulta RIFORMULABILE la proposta di riformulazione diventa obbligatoria (senza, il tema resta semplicemente respinto).

✓ Collegamento: se P01 propone una riformulazione_proposta, puoi accettarla scrivendola come nuovo tema, oppure ignorarla e proporne una tua. Vedi anche la sezione P02 (Parametri): è la fase immediatamente successiva, ed è l'unico altro punto in cui un tuo messaggio viene letto nel merito invece di limitarsi a far avanzare la pipeline.

Fase P02: Parametri

Subito dopo che P01 ammette il tema, P02 fissa il perimetro e l'impostazione dell'analisi: dove guardare, quanto in profondità, e su quale arco temporale. Sono le decisioni che condizionano tutte le fasi successive — un perimetro tracciato male o un solo fattore causale individuato qui si trascinano fino al report finale.

I campi che P02 fissa

Campo Cosa rappresenta
perimetro.descrizione L'area/spazio su cui verte l'analisi, in prosa
perimetro.criterio Delimitazione del perimetro geografico (nella schermata e nel modulo; il campo si chiama criterio), cioè come va interpretata la descrizione: limitato_allo_spazio (strettamente circoscritta allo spazio indicato) oppure estesa_a_spazi_esterni (anche a spazi esterni con relazioni modeste)
perimetro.ambienti_coinvolti Terrestre, marittimo (superficie/profondità), aerospaziale, extra-atmosferico, digitale — anche più di uno
perimetro.scale_coinvolte Globale, macroregionale, regionale, statuale, sub-statuale, locale — anche più di una
taglio una di due frasi: «Tematicamente ampio…» (molti ambiti, valutati soprattutto nelle loro connessioni) oppure «Tematicamente ristretto…» (approfondimento specifico sugli ambiti più rilevanti). Il valore memorizzato è la frase intera, non un codice breve
ambito_tematico Solo con il taglio ristretto, e solo se lo sceglie l'utente: l'ambito su cui concentrare l'analisi, {modalita:"lista", ambiti:[…]} oppure {modalita:"testo", testo:"…"} (vedi «Taglio ristretto: l'ambito su cui concentrare l'analisi»). Non è nello schema inviato al modello
impianto prevalentemente_teorico, prevalentemente_empirico o bilanciato. Nascosto per ora (schermata e modulo), in attesa dell'integrazione con EIL: vedi «Il campo Impianto è nascosto» più sotto
profondita_storica Almeno tre fattori causali distinti, ciascuno con la propria scala temporale (vedi sotto). I fattori aggiunti o modificati dall'utente nel modulo ricevono anche origine: "utente" e id: "Fn" (posizione nell'elenco): sono obbligatori in P07 e P11 (vedi «Fattori causali dell'utente»). Né id né origine sono nello schema inviato al modello
parametri_assunti_non_confermati Ipotesi di base date per buone ma non verificate, dichiarate esplicitamente

Il perimetro: quanto ampio tracciarlo

La delimitazione estesa_a_spazi_esterni è quella che P02 usa di default quando i confini dello spazio non sono ovvi. La regola del metodo è esplicita: meglio una riduzione deliberata successiva che un'esclusione preventiva affrettata — tagliare fuori qualcosa che poi risulta rilevante è un errore peggiore che includere, all'inizio, qualcosa di superfluo.

Il perimetro scelto nelle fasi successive

La descrizione del perimetro e l'opzione scelta nella «Delimitazione del perimetro geografico» (strettamente circoscritta allo spazio indicato oppure estesa a spazi esterni) non restano un semplice dato di P02: PerimetroP02::blocco() (api/PerimetroP02.php) li inserisce nei prompt di P03, P04, P05 e delle 12 sotto-fasi di P06, con l'etichetta in chiaro (non il valore tecnico) e un comando della fase. P07 e le fasi seguenti non ricevono il blocco. Le etichette delle due opzioni hanno una fonte sola, PerimetroP02::ETICHETTE_CRITERIO, usata anche da api/p02_opzioni.php (tendina del modulo e schermata).

FaseComando
P03«Formula la domanda di ricerca a partire dall'opzione prescelta dall'utente in P02-perimetro geografico»: con «circoscritta» la domanda riguarda lo spazio indicato, con «estesa» può comprendere gli spazi esterni collegati
P04Individua se lo spazio è «dominato» o «conteso» rispetto alla delimitazione indicata in P02. Gli attori e le pressioni esterni a tale delimitazione non modificano il tipo: restano registrati in indizi_contrari o zone_grigie. Per i temi di tipo C il giudizio finale spetta alla riconduzione di P05. Nella classificazione imposta con /riclassifica il comando non c'è (il tipo è deciso dall'utente)
P05 (solo tipo C)Analizza tenendo conto dell'opzione prescelta; il perimetro guida la ricostruzione senza limitarla: se l'oggetto di studio si estende oltre, lo si ricostruisce per intero
P06 (12 proprietà)Analizza tenendo conto dell'opzione prescelta. Per le quattro proprietà relazionali (posizione relativa, accessibilità, mobilità, scalarità) una cautela in più: il perimetro orienta ma non impedisce di considerare spazi, poli, rotte e scale esterni, e peso e ampiezza non devono ridursi solo perché l'opzione è «circoscritta»
  • Se in P02 manca un criterio valido (analisi salvate prima di questa funzione, stato incompleto) il blocco è vuoto e il prompt resta identico a quello di prima.
  • Nei testi per il modello si scrive «perimetro geografico» e mai «delimitazione» (nel blocco di P06): Delimitazione è anche il nome di una proprietà dello spazio, su continuità e confini fisici.
  • Il perimetro si può cambiare solo prima di P03 (vedi «Modifica manuale dei parametri»); dopo, resta fisso per tutte le fasi che lo usano. Nel Wargame il bivio sul perimetro produce ora rami davvero diversi; gli alberi già calcolati non cambiano.
  • Sono istruzioni al modello, non controlli: nessun validatore verifica che il perimetro sia rispettato, e lo schema di P04 non ha un campo che ne registri il peso.
💡 Prova con il modello reale (3 temi × 2 opzioni × 2 semi per P03–P04, 2 temi di tipo C per P05, un tema per 6 proprietà di P06 con 3 semi): il tipo di P04 non è cambiato in nessuno dei 24 casi; la domanda di ricerca segue l'opzione (con «circoscritta» resta nello spazio indicato, con «estesa» arriva agli spazi collegati; col prompt precedente la differenza era debole); P05 non viene tagliato; in P06 i pesi sono rimasti identici e i testi relazionali continuano a guardare fuori dallo spazio. Campione piccolo: indicativo. Test: tests/perimetro_p02_test.php.

Il campo Impianto è nascosto

In attesa della completa integrazione con EIL, il campo impianto non si vede più né nella schermata dei parametri né nel modulo «Modifica parametri» (costante P02_IMPIANTO_VISIBILE = false in js/renderer-fasi.js; per mostrarlo di nuovo basta impostarla a true). Il dato non è stato tolto: P02 lo propone ancora, il modulo rimanda il valore attuale senza chiederlo, lo schema e il validatore lo richiedono, e resta nel JSON di P02 che entra nei prompt delle fasi successive (nessuna fase gli dà un comando specifico). Nel Wargame un bivio sull'impianto, se definito da chi costruisce lo scenario, viene comunque proposto: lo nasconde solo la scheda di P02.

Taglio ristretto: l'ambito su cui concentrare l'analisi

Con il taglio «tematicamente ristretto» il modulo «Modifica parametri» mostra un box in cui l'utente indica l'ambito su cui concentrare l'analisi, in uno solo di due modi: scegliendo da una lista di 16 ambiti (uno o più: economico, militare e della sicurezza, diplomatico, politico-istituzionale, energetico, tecnologico, cibernetico e digitale, ambientale e climatico, demografico e migratorio, culturale e identitario, religioso, giuridico, logistico e dei trasporti, sanitario, informativo e comunicativo, alimentare e idrico) oppure scrivendolo (da 3 a 300 caratteri). Lista e testo non si possono usare insieme: il modulo disabilita l'altro modo e il server (AmbitoP02::normalizza(), api/AmbitoP02.php) rifiuta una richiesta che li contiene entrambi, o nessuno dei due. Con il taglio ampio un eventuale ambito inviato viene scartato.

  • Solo l'utente sceglie il ristretto. Il prompt di P02 dice di proporre sempre il taglio ampio, anche se le preferenze scritte chiedono di restringere; se il modello propone comunque il ristretto, Phase02Params::valida() lo riporta all'ampio (senza far ripetere la fase) e toglie l'ambito.
  • Dove entra. AmbitoP02::blocco() inserisce un blocco «AMBITO TEMATICO SCELTO IN P02» con un comando per fase nei prompt di tutte le fasi da P03 a P14: P03, P04, P05, le 12 sotto-fasi di P06, la sintesi di P06, P07, P08, P09a, P09b, P09c, P10, P11, P12, P13 e P14. Senza taglio ristretto, o senza un ambito valido (analisi salvate prima di questa funzione), il blocco è vuoto e il prompt resta identico a prima.
  • P06: le proprietà dello spazio restano tutte da analizzare per intero; l'ambito è il riferimento per il peso e per il taglio dell'analisi (quali aspetti approfondire), e non è un motivo per il peso «nullo».
  • P07–P09: gli attori e le relazioni degli altri ambiti restano quando sono determinanti.
  • P04 (il giudizio sul tipo riguarda lo spazio nel suo insieme, non l'ambito; nessun blocco nella classificazione imposta con /riclassifica), P10 (ciò che resta fuori per scelta dell'utente non è una lacuna), P13 (l'ambito tra premesse e limiti del report) e P14 (confronto sugli aspetti omologhi nell'ambito): i comandi di P03–P05 e P10–P14 sono formulati da noi; quelli di P06 e P07–P09 seguono la decisione presa (vedi AmbitoP02::COMANDI).
  • Wargame: un bivio sul taglio con l'opzione «ristretto» deve indicare anche l'ambito ('ambito' => {ambiti:[…]} oppure {testo:…}), altrimenti ScenarioBuilder lancia un'eccezione. Gli alberi già calcolati non cambiano.
  • Come per il perimetro, sono istruzioni al modello, non controlli, e l'ambito si può cambiare solo prima di P03. Il testo scritto dall'utente viene ripulito (spazi, caratteri di controllo) ed entra in circa 35 chiamate (circa 100 token ciascuna: costo trascurabile); sulla schermata passa da escapeHtml.
💡 Prova con il modello reale (Svalbard, 2 semi, taglio ampio contro ristretto da lista «economico» e da testo «attività minerarie e sfruttamento delle risorse»; P03, P04, tre proprietà di P06, P07 e P08 su uno stato incompleto, senza sintesi di P06): il tipo di P04 non cambia, i pesi di P06 restano identici (nessun «nullo»), la domanda di ricerca segue l'ambito (con l'ampio parla di competizione nell'intero bacino artico; con il ristretto di regime di sfruttamento economico o di attività minerarie). Gli attori militari come la NATO escono dall'elenco di P08 in tutte e 4 le corse ristrette (presente nelle corse ampie); in una corsa con lista la Russia compare solo come Arktikugol, società di Stato russa. Campione piccolo: indicativo. Test: tests/ambito_p02_test.php.

Profondità storica: perché servono almeno tre fattori

Un'analisi che individua un solo fattore causale è, per il metodo, il primo sintomo di uno squilibrio monocausale — il prompt di P02 lo vieta esplicitamente, chiedendo almeno tre fattori distinti, ciascuno sulla propria scala temporale:

ScalaContenuto
breve_periodoFenomeni passeggeri, effetti limitati, in continuità col passato
medio_periodoSvolte non brusche: linee di politica soggette a variazioni ma con continuità di fondo
lungo_periodoProcessi strutturali (economici, mentalità collettive, rivalità storiche) che mutano lentamente
lunghissimo_periodoSpostamenti dell'asse geopolitico del mondo — il respiro più ampio

Un fattore può anche essere segnato come invariante (es. la posizione assoluta di uno spazio): per quelli non serve nemmeno ricostruire una traiettoria storica.

Fattori causali dell'utente: obbligatori in P07 e P11

Fino a questa versione la profondità storica finiva solo nel JSON di P02 che le fasi successive ricevono, senza nessuna istruzione di usarla (una prova precedente non trovò alcun effetto a valle). Ora i fattori aggiunti o modificati dall'utente nel modulo «Modifica parametri» sono obbligatori; quelli del modello non toccati no. La logica è in api/FattoriP02.php.

  • Marcatura. Validators::validaP02Override() confronta l'elenco inviato con il P02 salvato (stesso testo, scala, punto di partenza e invariante, ignorando spazi e maiuscole): ciò che non corrisponde riceve origine: "utente" e id: "Fn". Più modifiche successive mantengono la marca. Massimo 8 fattori marcati (oltre, il modulo è rifiutato). Un P02 senza fattori marcati — modello non modificato, analisi precedenti, Wargame — lascia prompt e schemi come prima.
  • Prompt. FattoriP02::bloccoP07() e bloccoP11() aggiungono in fondo al prompt l'elenco dei fattori e il comando (P11 non riceve P02: il testo viene dal blocco). In P11, per il tipo A, si chiede coerenza con le voci «Fn ·» di P07.
  • Schema. AbstractPhase::schemaPerStato(): solo con fattori obbligatori P07 e P11 ricevono il campo fattori_p02, una voce per fattore (minItems = maxItems, id tra quelli attesi): collocazione (P07: basico, accessorio, strutturale, contingente; P11: strutturale, contingente), motivazione_collocazione (160 caratteri), valutazione (determinante, concorrente, marginale, non_riscontrato) ed elaborazione (350 caratteri).
  • Controllo. AbstractPhase::validaConStato() (P07 e P11): manca un fattore, id duplicato o inventato, collocazione o valutazione fuori elenco, elaborazione vuota → la fase si ripete con la correzione nel prompt (codici P07.fattori_p02, P11.fattori_p02; vedi il registro dei motivi di retry). Le regole di sempre restano (fattori_basici non vuoto; elementi_strutturali non vuoto).
  • Inserimento. L'elaborazione viene scritta dall'applicazione nella lista scelta dal modello, col formato «Fn · valutazione — «fattore»: elaborazione (Collocazione: motivazione)», e il campo di servizio fattori_p02 viene tolto: P08, P11, P12, P13 e P14 leggono le liste ordinarie, e la schermata le mostra senza modifiche. Anche un fattore «marginale» o «non riscontrato» compare in una lista (quella cui apparterrebbe), con la valutazione scritta in chiaro.
  • Tipo B. P07 non gira: i fattori compaiono solo in P11.
  • Il controllo garantisce che ogni fattore sia elaborato, non che il ragionamento sia corretto: la qualità dell'elaborazione resta quella del modello.

Come vengono trovati questi parametri

P02 riceve in input l'esito di P01 (il tema ammesso) e propone i parametri seguendo le regole del metodo appena descritte. Ma c'è un punto poco intuitivo, utile da sapere:

💡 P02 è l'unica fase, oltre al tema iniziale, che legge davvero quello che scrivi. Il messaggio che invii subito dopo che il tema viene ammesso (quello che fa scattare P02) viene passato al modello come "preferenze indicate dall'utente", con priorità sui default che altrimenti proporrebbe da solo. Da P03 in poi, invece, il testo che scrivi tra una fase e l'altra serve solo a far avanzare la pipeline: il suo contenuto non viene più letto dai prompt delle fasi successive.

In pratica: se hai già un'idea precisa del perimetro (es. "limita l'analisi al solo bacino del Mediterraneo orientale, taglio di profondità"), è qui — e solo qui — che vale la pena scriverlo esplicitamente. Lasciato vuoto o generico ("continua", "ok"), P02 propone i default che ritiene più adatti al tema.

Modifica manuale dei parametri, senza richiamare il modello

Sotto il riepilogo di P02 compare il pulsante "✏️ Modifica parametri". Apre un form precompilato con i valori proposti, dove ogni campo a scelta chiusa — delimitazione del perimetro geografico, ambienti coinvolti, scale coinvolte, taglio, scala temporale di ciascun fattore causale — è una tendina o un gruppo di checkbox con tutti e soli i valori ammessi dallo schema, mai testo libero da indovinare. I campi che nello schema sono effettivamente testo libero (descrizione del perimetro, fattore causale, punto di partenza, parametri assunti non confermati) restano campi di testo, editabili ma non "a scelta".

Il riepilogo di P02 in chat si intitola «Parametri di impostazione» (prima «Parametri suggeriti») e, solo dove c'è il pulsante di modifica, riporta sotto il titolo la nota «ANGST li assegna in base alle proprie risultanze ma l’utente li può modificare orientando così lo sviluppo e i risultati dell’analisi.» Nel Wargame i parametri appartengono a un ramo già calcolato e non modificabile: il pulsante non c'è e la nota nemmeno; con dati vuoti compare solo il titolo. Titolo e nota stanno nello stesso paragrafo (.p02-titolo, renderP02Parametri() in js/renderer-fasi.js), quindi il report finale li toglie insieme, mentre la trascrizione della chat li conserva.

A differenza di /riclassifica (che rifà la fase richiamando di nuovo Gemini), qui non parte nessuna nuova chiamata al modello: il server valida i valori scelti contro le stesse liste che li hanno generati (Validators::opzioniP02(), letta direttamente da schemas/p02_params.json — se lo schema cambia, form e validazione lo seguono senza bisogno di toccare altro) e, se sono tutti validi, sostituisce l'output già salvato di P02 con quello corretto. Nessun token consumato, nessun costo, effetto immediato: la risposta di successo non porta un campo token_usage, apposta perché il frontend non aggiunga un chip token o un badge grounding che non avrebbe senso qui.

💡 Finestra di utilizzo: la modifica è possibile solo mentre P02 è ancora la fase corrente, cioè prima che l'utente scriva qualcosa per proseguire verso P03. Il pulsante resta visibile anche su una card P02 precedente se si scorre indietro in chat, ma un tentativo di modifica a quel punto viene rifiutato con un messaggio esplicito (tipo: 'errore') — l'output è già stato letto dalle fasi successive, e sovrascriverlo a ritroso lascerebbe lo stato incoerente. Prima di proseguire, l'utente può correggere più volte di seguito: ogni conferma sovrascrive la precedente.

Un valore fuori lista (es. un client che chiamasse l'endpoint a mano con un valore inventato) non viene mai salvato: il server risponde con tipo: 'p02_override_invalido' e un messaggio che elenca esattamente quale campo non è valido — distinto apposta da errore_validazione, che nel resto della pipeline significa "il modello ha fallito i tentativi previsti", non "l'utente ha inviato un valore scorretto". Ogni sovrascrittura riuscita lascia una riga nel log per-utente (storage/log/<utente>.log): P02 parametri modificati manualmente dall'utente.

✓ Collegamento: questo è anche il momento più efficace per anticipare possibili lacune — vedi la sezione Lacune dichiarate: una volta superato P02, l'unica leva pratica resta riformulare il tema iniziale e ripartire.

Fase P03: Introduzione

P03 costruisce la cornice introduttiva dell'analisi, prima ancora della classificazione (P04): perché il tema merita uno studio strutturato, quale domanda guiderà l'analisi, e — quando è già formulabile — un'ipotesi di partenza. Riceve in input l'esito di P01 e i parametri di P02.

I tre campi di P03

CampoCosa deve fare
perche_interessanteArgomenta perché il tema meriti un'analisi strutturata (rilevanza strategica, novità, aspetti poco esplorati) — non descrive il tema, ne motiva lo studio
domanda_di_ricercaLa domanda centrale a cui l'analisi risponderà, spazialmente ancorata ("di chi è questo spazio?"), non generica
ipotesi_di_partenzaL'ipotesi iniziale su cui si fonda l'analisi — può restare null se il tema è di tipo C e lo spazio non è ancora ricostruito (la spazializzazione avviene solo dopo, in P05)

Tono quando il rendimento atteso è basso

Il prompt di P03 chiede di motivare lo studio del tema, e questo spingeva il modello a enfatizzarne la rilevanza anche quando P01 aveva appena stimato basso il rendimento_atteso. Ora, se P01 restituisce rendimento_atteso = "basso", il prompt di P03 riceve in più un blocco «TONO» (metodo Phase03Intro::istruzioneTono()) che chiede di:

  • scrivere in modo misurato e sobrio, senza superlativi né aggettivi enfatici («cruciale», «fondamentale», «senza precedenti», «nodo strategico»), né promesse di risultati;
  • motivare lo studio in modo proporzionato, dicendo che cosa l'analisi spaziale può dire sul tema e dove il suo contributo resta limitato;
  • formulare l'ipotesi di partenza in modo prudente.

Con alto, medio o valore assente il prompt non cambia. Il blocco è un'istruzione al modello, non un controllo: ne riduce l'enfasi ma non la elimina, e il validatore non verifica il tono. Il caso è raro, perché P03 viene raggiunta solo con esito AMMESSO o AMMESSO CON RISERVA, e con un tema ammesso P01 stima quasi sempre rendimento alto (con RIFORMULABILE o RESPINTO «basso» è frequente, ma la pipeline si ferma prima di P03). In un confronto su 3 temi × 3 semi con il modello reale, le parole enfatiche per testo sono passate in media da 1,1 a 0, con testi più lunghi del 6%; due dei tre temi avevano il rendimento forzato a «basso». Test: tests/p03_tono_test.php.

ℹ️ Nessun contenuto nuovo da te: a differenza di P02, il messaggio che scrivi per far avanzare la pipeline da P03 in poi non viene più letto nel merito dai prompt delle fasi successive — vedi la nota in P02. P03 lavora solo su ciò che è già stato raccolto (tema, P01, P02).

Fase P04: Classificazione

P04 è il cuore decisionale della pipeline: assegna il tipo (A, B, C.1, C.2 o SOSPESO) da cui dipende l'intero ramo successivo — se il tema è di tipo C, la pipeline devia prima su P05 (Spazializzazione); da lì in poi, e per i tipi A/B fin da subito, il tipo effettivo decide se si procede verso P07/P08 (ramo A) o P09a/b/c (ramo B).

Stati specifici e tipo B

Il metodo dice che l'analisi di uno Stato specifico è di tipo B (01-tipologia.md, §4), eccetto gli Stati falliti o destabilizzati. Il modello non lo applicava in modo stabile, perché la stessa pagina chiedeva anche un accertamento sostanziale del dominio che per gli Stati con porzioni contestate portava a A o C. Prima della correzione, su 6 Stati non falliti e 4 semi (P01–P04, ricerca web spenta), il tipo era B solo in 10 corse su 24 (Italia, Francia e Turchia mai B; Iran 2 su 4), e il gate P01 dichiarava «riformulabile» Italia, Francia e Turchia in 11 corse su 12 (vedi le note di versione, voce 63).

  • Prompt di P04 (Phase04Classify): ora riceve il tema scritto dall'utente (prima non lo vedeva) e un blocco «STATI SPECIFICI» che chiede di compilare verifica_stato prima del tipo.
  • Validatore: Stato specifico non fallito ⇒ tipo B, altrimenti la fase si ripete con la correzione. Nella classificazione imposta dall'utente (/riclassifica) la violazione diventa un'avvertenza.
  • Gate P01: l'analisi di uno Stato nel suo insieme è ammissibile (tipo B previsto), non «troppo generica».
  • Conoscenza: 01-tipologia.md (la riga sullo Stato specifico non chiede più la verifica del controllo blando; resta per le porzioni di Stato) e 00-ammissibilita.md.
  • Limite: «Stato fallito» è un giudizio del modello (Siria, Sudan, Afghanistan, Libia, Somalia, Yemen, Libano e Ucraina sono usciti «falliti»; l'Iraq è oscillato). Se il modello non riconosce che il tema è uno Stato (tema_e_stato_specifico falso), la regola non scatta.

I due assi indipendenti

CampoCosa rappresenta
asse_spaziopre_individuato (lo spazio è già dato dal tema) oppure non_pre_individuato (va ricostruito — tipo C)
asse_attoredominante (tipo B), non_dominante (tipo A) oppure sospeso se non ci sono ancora elementi sufficienti per decidere
verifica_statoCompilato PRIMA del tipo: tema_e_stato_specifico (il tema, come scritto dall'utente, è l'analisi di uno Stato nel suo insieme), nome_stato, stato_fallito (non controlla di fatto il proprio territorio) e motivazione. Con tema_e_stato_specifico vero e stato_fallito falso il tipo DEVE essere B: Validators::validaP04() rifiuta altrimenti (P04.stato_specifico_tipo_b, la fase si ripete). Assente nelle analisi salvate prima: il controllo non scatta. Vedi «Stati specifici e tipo B» più sotto
tipoLa combinazione risultante: A, B, C.1, C.2 o SOSPESO — non è un errore lasciarlo SOSPESO, è previsto dal metodo quando l'asse attore non è ancora determinabile
accertamento_dominio.*Quattro verifiche booleane (materiale, effettivo, manifesto, continuo) più forma_controllo_stimata sulla scala dominio → egemonia → sfera_influenza → … → vuoto_di_potere / spazio_libero (definizioni e corrispondenza con asse_attore: vedi "Forme di controllo" sotto)
zone_grigie.*vuoto_di_potere, spazio_libero, politicizzazione_prospettica, trappola_territoriale_evitata — vedi sotto
confidenzaalta / media / bassa — se bassa, riesame_previsto deve essere true
casisticaA quale voce della casistica ammessa per tipo (01-tipologia.md §3.2/§4) corrisponde il tema — es. "regione naturale", "uno stato specifico"
rendimento_attesoStessa scala alto/medio/basso di P01, ricalcolata qui con gli elementi emersi fino a P04

Accertamento sostanziale, non formale

La regola guida di P04 è che il dominio va accertato sostanzialmente, non per attribuzione convenzionale (salvo l'eccezione descritta più sotto): uno spazio giuridicamente sotto la sovranità di un attore può essere di fatto conteso. Le tre zone grigie verificate esplicitamente sono il vuoto di potere (transitorio, non pregiudica l'ammissibilità), lo spazio libero con eventuale politicizzazione prospettica (un'assenza di interesse oggi può dipendere da limiti tecnologici destinati a cadere), e la trappola territoriale (l'idea che uno spazio esista stabilmente solo perché oggi corrisponde a un territorio riconosciuto sotto un'unica sovranità).

Eccezione per gli spazi di valore politico molto basso

Il criterio sostanziale ha un limite: in uno spazio così poco attrattivo da non richiamare poteri esterni né poterne esprimere uno proprio, non emergono né contese né una presa visibile. Applicato da solo, il criterio lascerebbe lo spazio senza attribuzione (spazio_libero, SOSPESO, oppure un'attribuzione senza prove) — in contrasto con il presupposto del metodo secondo cui nello spazio politico il vuoto non esiste. Per questo, in un caso preciso, l'autorità formale riconosciuta diventa indizio sufficiente per attribuire lo spazio (tipo B). Devono valere tutte e quattro le condizioni:

  1. nessun segno di contrasto, esplicito o latente, tra più poteri;
  2. nessun interesse manifesto di attori esterni, nessuna risorsa o posizione che possa attrarne;
  3. nessuno degli indizi contrari elencati in 01-tipologia.md §6.3 (poteri de facto diversi dal titolare formale, flussi incontrollati, barriere difensive, narrazioni di accerchiamento);
  4. titolare formale identificabile e non contestato.

Se manca anche una sola condizione, vale la regola generale (accertamento sostanziale). L'eccezione riguarda l'attribuzione del dominio, non l'esistenza dello spazio come unità: non autorizza la trappola territoriale.

Come il modello deve dichiararla

Non esiste un campo dedicato nello schema: il modello usa campi esistenti. Una voce in indizi_a_favore indica che l'attribuzione poggia sull'autorità formale ai sensi dell'eccezione; riesame_previsto è true; accertamento_dominio.forma_controllo_stimata è dominio (non autorita_nominale, che presuppone un potere contestato e fragile). Nessun validatore controlla questi tre punti: l'istruzione è nel prompt di P04 (Phase04Classify::costruisciPrompt()) e in 01-tipologia.md, §2 Asse 2.

Perché non è "spazio libero" e che ruolo ha il valore politico

Uno spazio con un titolare formale riconosciuto e incontestato non è spazio libero (§6.2 di 01-tipologia.md): spazio libero è solo quello privo anche di un titolare formale. Il valore politico non assegna il tipo da solo: tara il peso dell'indizio formale. Più è alto, più è probabile la contesa (tipo A) e più prove sostanziali servono per sostenere il dominio; più è basso, più il titolo formale pesa. Non sostituisce le regole di assegnazione di §4 (uno stato specifico resta B a prescindere dal suo valore politico).

Forme di controllo e corrispondenza con il tipo

accertamento_dominio.forma_controllo_stimata è scelta tra dieci forme, in ordine decrescente di intensità del controllo. Le definizioni (colonne "sullo spazio formalmente proprio" e "altrui", più i casi illustrativi) stanno in un file condiviso, knowledge/09-forme-di-controllo.md, caricato da P04, P09b e P09c (non da P09a, che non usa la scala). Prima stavano solo in 05-attore-dominante.md, che P04 non carica: il modello vedeva le dieci etichette dell'enum senza le definizioni. In 05 resta un rinvio.

Forma (valore nello schema)asse_attoreTipo
dominio, egemoniadominanteB (spazio pre-individuato); C.2 (non pre-individuato)
sfera_influenza, ingerenza, sfera_interessi, cogestione, rinuncia_volontaria, autorita_nominale, vuoto_di_poterenon_dominanteA (spazio pre-individuato); C.1 (non pre-individuato)
spazio_libero—nessuna attribuzione: fuori ambito, salvo politicizzazione prospettica (01-tipologia.md §6.2)

Attenzione alla terminologia. Nel metodo "spazio dominato" (tipo B) indica lo spazio con attore dominante e comprende sia il dominio sia l'egemonia; nella tabella del file "Spazio dominato" è invece il carattere della sola forma dominio. Il file ripete l'avvertenza.

⚠️ La coerenza forma/asse è solo un'istruzione, non un controllo. Il prompt di P04 chiede che forma e asse_attore siano coerenti, ma validaP04 non li confronta: potrebbe uscire tipo B con forma ingerenza senza che nulla lo blocchi. Un controllo deterministico è possibile, ma ogni violazione farebbe scattare un retry a pagamento (vedi "Token e costi"): è una decisione di costo, non solo tecnica. La corrispondenza con C.1/C.2 è la generalizzazione, sullo stesso asse attore, della regola "dominio ed egemonia = B".
ℹ️ Dove sta scritto: knowledge/01-tipologia.md (§2 Asse 2, con rinvii in §4 Tipo B e §6.2), 00-ammissibilita.md (§4.3 e pseudo-codice di P01), 05-attore-dominante.md (§2, per P09: se B è stato attribuito per via formale, l'assenza di presa visibile non è una contraddizione da correggere) e 09-forme-di-controllo.md (le dieci forme e la corrispondenza con il tipo).

Riclassificazione imposta dall'utente (/riclassifica)

/riclassifica [tipo] [motivazione] non è una richiesta di rivalutazione al modello: è una decisione dell'utente. Il tipo (A, B, C.1 o C.2, in maiuscolo — una "a" minuscola è anche la preposizione italiana e non verrebbe riconosciuta) e la motivazione (da 10 a 1000 caratteri) sono obbligatori, sia da P04 sia da P10. Un comando incompleto risponde con un messaggio informativo, non chiama il modello e non consuma l'unica riclassificazione disponibile. Esempio: /riclassifica B lo spazio è controllato di fatto da un solo attore.

  • Non può essere rifiutata. Tipo e assi (asse_spazio, asse_attore) sono sempre quelli dell'utente: se il modello risponde un altro tipo o SOSPESO, Orchestrator::imponiClassificazione() li sostituisce e lo registra come avvertenza.
  • I validatori non la bloccano. Se l'output viola un controllo di validaP04 (per esempio B con vuoto_di_potere) non viene scartato né ritentato: la violazione diventa un'avvertenza registrata in P04.imposta_dall_utente.avvertenze, e scritta anche nel log dei motivi (riclassifica_imposta_da_utente). Restano retry normali solo gli errori tecnici (rete, JSON non valido).
  • È premessa di tutte le fasi successive. Tipo e motivazione sono accodati al prompt di ogni fase da P05 a P14 (Orchestrator::bloccoClassificazioneImposta()), anche nella ricerca approfondita sulle lacune: le tensioni con il tipo imposto vengono dichiarate come limiti o lacune senza cambiarlo. P10 riceve in più l'istruzione di non segnalare la classificazione come problema.
  • Il report la dichiara. P13 aggiunge in modo deterministico alla nota metodologica che la classificazione è stata imposta dall'utente, con la motivazione e le riserve del metodo accettate; la stessa informazione compare nella scheda di P04.
  • Resta una sola volta per analisi, ed è consumata solo a successo avvenuto. Dopo il comando la pipeline ripercorre da P05 con il nuovo tipo, come prima. I tipi C passano comunque dalla riconduzione di P05 ad A o B: è previsto dal metodo, non è un rifiuto.
⚠️ Costo e deroga. La motivazione viene reiniettata nel prompt di circa venti chiamate successive: con una motivazione di 500 caratteri sono circa 150–250 token di input in più per chiamata (stima), ma solo se la classificazione è stata imposta. È anche un'eccezione voluta alla regola generale per cui il testo libero dell'utente non viene letto da nessuna fase dopo P02. Per questo la motivazione è limitata a 1000 caratteri. Le regole di metodo sono in 01-tipologia.md §6.6 e 08-struttura-report.md §7.6.

Fase P05: Spazializzazione

P05 esiste solo per i temi classificati tipo C in P04 — uno spazio non pre-individuato, come un settore merceologico o un fenomeno sociale. Il suo compito è ricostruire un vero perimetro spaziale a partire da un oggetto di studio che inizialmente non ne ha uno esplicito, e infine ricondurre il tema al tipo A o B, sbloccando così le fasi successive (P06 in poi).

I quattro passi, in ordine

PassoCosa produce
1. definizione_oggettoDefinizione esplicita dell'oggetto di studio, funzioni per i gruppi umani coinvolti, caratteri intrinseci, peso del materiale rispetto al narrativo
2. aspetti_politiciEffetti di rilievo politico, posta in palio, importanza per i gruppi, livello di politicizzazione (basso → molto_alto)
3. perimetro_spazialeLuoghi di estrazione/lavorazione/consumo, flussi e rotte, infrastrutture, e gli ambienti_geopolitici attraversati (terrestre, marittimo di superficie/profondità, aerospaziale, extra-atmosferico, digitale — anche più di uno)
4. riconduzionetipo_risultante: A se non prevale un attore dominante, B altrimenti — con ragionamento esplicito e, se B, il nome dell'attore_dominante
ℹ️ Il "tipo effettivo": da qui in poi, ogni fase successiva usa il tipo_risultante di P05 (non più il tipo originario di P04) per decidere quale ramo seguire — è quello che nella guida e nel codice si chiama "tipo effettivo".

Fase P06: Caratteri dello spazio

P06 non è una singola chiamata ma una catena di dodici sotto-fasi, una per ciascuna proprietà strutturale dello spazio, seguite da una sintesi trasversale (P06_sintesi). Il frontend le presenta come un unico passo della pipeline, ma tecnicamente sono tredici richieste separate — vedi anche la sezione Token e costi per come vengono conteggiate.

Le dodici proprietà

#Proprietà
1Posizione assoluta
2Estensione
3Posizione relativa
4Delimitazione
5Accessibilità
6Mobilità
7Articolazione interna
8Composizione
9Configurazione geopolitica
10Risorse
11Appropriabilità
12Scalarità

Ogni sotto-fase risponde allo stesso schema e dichiara un peso (peso: alto, medio, basso, nullo). Un validatore lato server impone ciò che il peso comporta:

PesoCosa significaCosa deve produrre
altoÈ tra le poche proprietà (di norma 3-4, al massimo 5 su 12) che reggono la lettura dei rapporti di potere sullo spazio. Prova: togliendola, cambierebbe la risposta alla domanda di ricerca oppure chi risulta avere potere o perché lo spazio è contesoanalisi.testo + analisi.inferenza_principale + motivazione_peso (una riga: «senza questa proprietà non si capirebbe…»)
medioContribuisce in modo reale al quadro ma non lo spiega da sola: togliendola, la lettura cambierebbe nei dettagli, non nella sostanza. È il valore di partenzaanalisi.testo + analisi.inferenza_principale
bassoPrecisa un quadro che altre proprietà spiegano già: l'effetto c'è, ma è secondario o ripetuto altrovetesto di 2-3 frasi (massimo 900 caratteri) + una inferenza breve
nulloNessun effetto, per uno di due motivi. (a) Nessun effetto sul potere in questo caso: applicando le domande della proprietà non emerge nulla di rilevante. (b) Non applicabile: manca un requisito strutturale (per esempio la continuità fisica per la Delimitazione, almeno due porzioni distinguibili per l'Articolazione interna, una rete di spostamenti interni per la Mobilità in uno spazio molto limitato). Un confine contestato o incerto non rende una proprietà «non applicabile»solo motivazione_irrilevanza, specifica per il tema, che dice se è il caso (a) o il caso (b); analisi resta null

La stessa definizione compare in tre punti, da tenere allineati: la riga di compilazione di knowledge/02-proprieta-spazio.md (letta dal modello), la legenda «Come leggere il peso» mostrata sopra l'elenco delle proprietà in P06 (js/renderer-fasi.js) e questa tabella con quella della guida utente. I criteri operativi che guidano il modello (domanda guida, confronto con le altre undici, alto raro) restano nel prompt di Phase06Property.php e in quello di P06_sintesi.

  • Domanda di ricerca nel prompt. La prova dell'«alto» («togliendola, cambierebbe la risposta alla domanda di ricerca…») ha bisogno di quella domanda: il prompt delle 12 sotto-fasi e quello della sintesi riportano ora la riga DOMANDA DI RICERCA (P03) (solo la domanda, non l'intera introduzione). Prima non c'era, e il criterio rimandava a qualcosa che il modello non vedeva.
  • Peso singolo provvisorio, peso finale comparativo. Ogni sotto-fase giudica da sola e tende a dare «alto» (nelle analisi salvate: 27 «alto» su 36 giudizi singoli, nessun «basso»); il peso che conta è quello finale deciso da P06_sintesi (massimo quattro «alto»).
  • Due tipi di «nullo». (a) nessun effetto sul potere; (b) non applicabile perché manca un requisito strutturale. Il modello deve dire quale nella motivazione_irrilevanza; un confine contestato o incerto non rende una proprietà «non applicabile». Non è un campo dello schema: il validatore non lo controlla.

Il campo rilevante non è più chiesto al modello: lo scrive il validatore (false solo se il peso è nullo), così sintesi, interfaccia e analisi salvate prima del peso (che hanno solo rilevante) continuano a funzionare. Un elenco di fatti non è un'inferenza: serve una conclusione esplicita su rapporti di potere o configurazione spaziale. La posizione assoluta non può mai avere peso basso o nullo.

Criteri nel prompt: la domanda guida («se togliessi questa proprietà, cambierebbe la risposta alla domanda di ricerca?»), l'elenco delle altre undici proprietà per il confronto, medio come punto di partenza e alto come valore raro. Requisiti strutturali per i quali il peso è nullo: Delimitazione (spazio discontinuo; la continuità è fisica, i confini contestati non contano) e Articolazione interna (non si indicano almeno due porzioni con ruoli o rapporti di potere diversi, oppure la Composizione ha giudicato omogenea la distribuzione degli elementi: vedi sotto).

Composizione e Articolazione interna: la regola dell'omogeneità

Nell'ordine di esecuzione la Composizione (numero 8 del metodo) gira prima dell'Articolazione interna (numero 7): Orchestrator::PROPRIETA_P06, ScenarioBuilder, FASI_P06_INTERNE in js/app.js e js/wargame.js. La numerazione del metodo, la sintesi di P06 e la schermata mantengono l'ordine storico.

  • Giudizio della Composizione. Lo schema della sola Composizione (Phase06Composizione::schema(), non quello condiviso dalle altre undici) ha il campo obbligatorio distribuzione_elementi = {valutazione, motivazione}, con valutazione omogenea (solo se, per tutte e quattro le categorie — attori, infrastrutture, gruppi umani, risorse — non esistono porzioni che si distinguano: nessuna concentrazione in un punto, nessun contrasto tra zone; tutto concentrato in un unico insediamento non è omogeneità), disomogenea (almeno due categorie differenziate) o mista (una sola categoria differenziata, o nel dubbio). Il prompt non dice al modello che «omogenea» annulla l'Articolazione, per non influenzare il giudizio. È richiesto anche con peso nullo; codice di regola P06.distribuzione_elementi.
  • Regola dell'Articolazione interna. Il suo prompt riceve l'esito della Composizione (giudizio, motivazione, testo e inferenza). Con «omogenea» il peso è obbligatoriamente «nullo», caso (b), con «Caso (b):» in motivazione_irrilevanza e analisi null; lo impone anche Phase06ArtInt::validaConStato() (codice P06.articolazione_omogenea: la fase si ripete con la correzione). Con «mista», «disomogenea» o senza giudizio la regola non scatta e vale quella ordinaria. Si applica a tutti i tipi (A, B, C).
  • Effetti. Un'Articolazione interna nulla finisce tra le proprietà trascurabili della sintesi di P06. Le analisi già salvate non hanno il campo e non cambiano. Un'analisi interrotta tra le due fasi al momento dell'aggiornamento (Articolazione fatta, Composizione no) salterebbe la Composizione: va rifatta da P06.

Scalarità e scale degli attori

La Scalarità (ultima delle 12 proprietà, eseguita prima di P08/P09) elenca sempre gli attori principali con il loro orizzonte d'azione, in un campo obbligatorio del suo solo schema (Phase06Scalarita::schema()): attori_per_scala, da 1 a 8 voci {attore, orizzonte}, con orizzonte tra le sei scale di P02 (globale, macroregionale, regionale, statuale, sub_statuale, locale). Sta prima del peso nell'ordine delle proprietà: il modello elenca e poi giudica. L'elenco è provvisorio, serve solo a questa regola; l'analisi degli attori vera è P08 (tipo A) o P09 (tipo B).

  • Regola (Phase06Scalarita::valida(), per tutti i tipi): tutti gli attori elencati — almeno due — con la stessa scala ⇒ peso «nullo», caso (b), codice P06.scalarita_una_scala; scale distinte almeno tre ⇒ peso almeno «medio» («alto» resta un giudizio del modello, soggetto al tetto di 5), codice P06.scalarita_tre_scale; due scale, o un solo attore in elenco ⇒ giudizio ordinario. Elenco mancante: P06.scalarita_attori. La violazione fa ripetere la fase con la correzione nel prompt. L'output salvato ha anche scale_distinte e regola_scale (una_scala, tre_o_piu o ordinaria), calcolati dall'applicazione.
  • Sintesi di P06. Il peso finale è un confronto tra le dodici e può abbassare il peso: con regola_scale = tre_o_piu la sintesi non porta la Scalarità sotto «medio» (Phase06Sintesi::pesiMinimi(), normalizzazione silenziosa come le altre; nel prompt della sintesi compare una frase solo in quel caso). «Nullo» resta nullo.
  • Tipo B. Il prompt chiede di elencare l'attore stesso, le sue articolazioni interne (regioni, enti locali) e le controparti esterne che contano, ciascuno con la propria scala.
  • Effetto atteso. Nei 10 temi provati (60 corse) il modello ha elencato sempre almeno tre scale: la regola agisce in pratica come un pavimento («almeno medio») e il caso «una sola scala ⇒ nullo» è raro. Le analisi salvate prima non hanno il campo e non cambiano.

Spazi di estensione ridotta: Mobilità e Accessibilità

La Mobilità misura il movimento all'interno dello spazio e conta tanto meno quanto meno è esteso; l'Accessibilità, che guarda ai varchi verso l'esterno, conta tanto di più. La regola è nei prompt delle due sotto-fasi (Phase06Mobilita e Phase06Accessibilita, tramite istruzioniSpecifiche()) e in knowledge/02-proprieta-spazio.md (sezioni 2, 5 e 6), con tre fasce:

Fascia di estensioneMobilitàAccessibilità
Molto limitata (una piazza, un quartiere o un lido, un complesso, un isolotto)nullo, caso (b): manca una rete di spostamenti interni; la motivazione inizia con «Caso (b):»almeno medio, di norma alto; mai basso né nullo
Limitata (un'isola piccola, una valle, un borgo, un'area portuale)al più bassoalmeno medio
Media o grandegiudizio ordinariogiudizio ordinario
  • Fonte della dimensione. Non c'è un campo strutturato: Estensione (che in P06 precede Accessibilità e Mobilità) chiude la sua analisi dichiarando la fascia, e il suo testo e la sua inferenza vengono riportati nel prompt delle due fasi successive (circa 400 token ciascuna). Se Estensione manca o è nulla, il prompt lo dice e la fascia si stima dal tema.
  • Dimensione dello spazio «come delimitato». Conta il perimetro di P02, non il solo luogo nominato nel tema: una piazza estesa al centro politico che la circonda può uscire dalla fascia molto limitata.
  • Eccezione dei nodi attraversati da un flusso (valico, ponte, porto, posto di controllo, canale): il flusso si analizza in Accessibilità; la Mobilità non è forzata a nullo ma resta al più bassa.
  • Solo istruzione. Nessun validatore la fa rispettare (non c'è un dato di dimensione su cui basarlo). La sintesi riceve l'indicazione che, se la Mobilità è nulla per spazio molto limitato, l'Accessibilità non scende sotto «medio». La regola non si applica a uno spazio non fisico (un settore, un fenomeno) e dipende dalla dimensione, non dall'opzione di perimetro (la cautela per le proprietà relazionali resta).
⚖️ Perché il peso finale lo decide la sintesi. Ogni sotto-fase vede solo la propria proprietà e non può confrontarla con le altre: in una prova su tre temi con modello reale (Panama, Kaliningrad, Kashmir) 8-12 proprietà su 12 si erano date peso alto anche con la scala e i criteri sopra. Il confronto si fa quindi in P06_sintesi, dove si vedono tutte e dodici.

P06_sintesi: non un riassunto, un'elaborazione

Dopo le dodici proprietà, P06_sintesi le rilegge tutte e produce un livello di analisi che non emerge guardando ogni proprietà isolatamente:

CampoCosa contiene
pesiIl peso FINALE e comparativo delle dodici proprietà (alto, medio, basso, nullo) con una riga di motivo ciascuna; al massimo 5 con peso alto, una proprietà nulla nell'analisi singola resta nulla
proprieta_piu_rilevantiDerivato dai pesi: le proprietà di peso alto (completate con le prime di peso medio se sono meno di tre)
proprieta_trascurabiliDerivato dai pesi: quelle di peso basso o nullo (il report non dedica loro uno spazio proprio)
sintesi_strutturaleUn paragrafo analitico sul quadro di potere spaziale complessivo — non un riepilogo per punti, ma un'elaborazione di come le proprietà si condizionano a vicenda
inferenze_trasversali3-5 inferenze che emergono dall'interazione tra proprietà diverse, non visibili guardandole una per una
conferma_tipoValorizzato solo se il tipo era rimasto SOSPESO fino a qui e i caratteri dello spazio ora permettono di stabilirlo — altrimenti resta null
✓ Ricerca approfondita e P06: le sotto-fasi non sono un punto della pipeline visibile all'utente, quindi le loro lacune ricercabili non vengono risolte una per una: si accumulano e vengono tentate tutte insieme una sola volta, a P06_sintesi. Vedi la sezione Lacune dichiarate.

Posizione assoluta: localizzazione e geografia fisica

La prima proprietà ha regole proprie, che le altre undici non hanno:

  • Il testo apre sempre con una breve localizzazione dello spazio (una frase): dove si trova — continente o regione, con i riferimenti che lo situano — e in quale ambiente (terrestre, marittimo, subacqueo, aereo, extra-atmosferico, digitale). Per un tema non pre-individuato (tipo C) indica le aree o i nodi principali e gli ambienti attraversati, non un luogo unico.
  • Poi la geografia fisica, ma solo ciò che pesa politicamente: due o tre caratteri tra clima e regime delle acque, rilievo e morfologia, idrografia, coste e profondità, rischi naturali permanenti, ciascuno con il suo effetto (condizionamento, opportunità o protezione). Non un inventario: la regola di tutte le proprietà resta che un elenco di fatti non è un'analisi.
  • Non può mai essere dichiarata non rilevante. È il punto di partenza dell'analisi. Validators::validaP06PosizioneAssoluta() scarta (con retry) un output con rilevante: false anche se motivato; per le altre undici proprietà rilevante: false con motivazione resta valido.
  • La frase di localizzazione non richiede fonti (deriva dal tema e dai parametri); le cifre (altitudini, temperature, profondità) sì.
  • Sinteticità 4-7 frasi invece di 3-6 (come l'Estensione, tramite l'hook frasiIndicative()); il tetto di 1200 caratteri di analisi.testo nello schema resta quello comune.
ℹ️ Come è fatto: le dodici sotto-fasi condividono lo stesso prompt (AbstractPhase06Property); le regole sopra stanno in un punto di estensione, istruzioniSpecifiche(), valorizzato solo da Phase06PosAss e da Phase06Estensione (vedi sotto), quindi le altre dieci proprietà non hanno nessun costo in più. Nel file 02-proprieta-spazio.md (proprietà 1) la regola è dichiarata come "Apertura obbligatoria", "Geografia fisica" e "Mai trascurabile"; essendo il file caricato in tutte le 13 chiamate di P06 pesa circa 250-300 token in più ciascuna (stima). La prima frase è un'istruzione, non un controllo: non c'è un validatore che verifichi il contenuto della frase, e si verifica dalla pagina Debug fasi (P06_posizione_assoluta).

Estensione: dimensione volumetrica e dimensione fisica assoluta

L'estensione non si ferma alla superficie: lo spazio è considerato come un volume, con le sue proiezioni verticali. Una superficie marittima ha una proiezione aerea (lo spazio aereo sovrastante) e una subacquea (colonna d'acqua, fondale, sottosuolo marino); una superficie terrestre ha il sottosuolo e lo spazio aereo. La regola vale per ogni ambiente, non solo per il marittimo. Per ogni proiezione con rilievo politico il testo dichiara se è inclusa nello spazio in esame, quanto si estende (profondità, quota utile) e se la presa di chi domina la superficie arriva fin lì: può non arrivarci, ed è un limite effettivo del suo controllo.

  • Rapporto con P02. Le proiezioni si considerano anche quando l'ambiente corrispondente non è tra gli ambienti_coinvolti dichiarati in P02 (per esempio solo marittimo_superficie): vengono riportate come proiezioni dello spazio, senza modificare i parametri né il perimetro di P02, che restano quelli scelti (e modificabili dall'utente). P02 e le fasi che ne dipendono non cambiano.
  • Dove sta scritto. 02-proprieta-spazio.md (proprietà 2: "Dimensione volumetrica", una domanda in più per il tipo A, un inciso nel tipo B) e un blocco di regole nel prompt di Phase06Estensione, che riceve lo stato e legge gli ambienti dichiarati in P02. Il modello tendeva a fermarsi alla superficie pur avendo "volume" nella definizione: l'istruzione nel prompt di una sola chiamata pesa di più di quella nel file di conoscenza.
  • Confini con le altre proprietà. Profondità e quote richiedono una fonte; i regimi giuridici dei volumi (acque territoriali, spazio aereo sovrano) restano a Delimitazione e Accessibilità. Contano solo le proiezioni con rilievo politico, non tutte quelle possibili.
  • Limiti. È un'istruzione, non un controllo: nessun validatore verifica che le proiezioni siano trattate. Estensione può ancora essere dichiarata non rilevante, con motivazione (a differenza della posizione assoluta). La sinteticità sale a 4-7 frasi (come la posizione assoluta; le altre dieci proprietà restano a 3-6) perché il testo deve contenere estensione, proiezioni verticali e dimensione assoluta; il tetto di 1200 caratteri di analisi.testo nello schema non cambia, quindi un troncamento è possibile e si controlla dalla pagina Debug fasi. Costo: la sezione Estensione nel file di conoscenza è passata da circa 870 a circa 3760 caratteri con le due aggiunte, cioè circa 700-800 token in più per ciascuna delle 13 chiamate di P06 (stima), più una riga di prompt per Estensione.

Dimensione fisica assoluta

Oltre a forma e volume conta la grandezza assoluta dello spazio (superficie, profondità, larghezza), perché ha effetti politici propri in entrambe le direzioni: una grande dimensione incide sulla politica interna (distanze da coprire, difficoltà di governare e tenere unite le periferie) e sulla politica estera (profondità strategica, numero di vicini e di fronti); una dimensione ridotta incide sui flussi (passaggi obbligati) e sul controllo (facilità di sorveglianza, interdizione e blocco). Il testo dà l'ordine di grandezza con la sua fonte (in mancanza, lacuna dichiarata) e l'effetto politico che ne discende per questo spazio. "Assoluta" significa il valore in sé, non il confronto con altri spazi (quello è Posizione relativa).

  • Confine con Mobilità e Accessibilità. In Estensione si valuta solo ciò che dipende dalla dimensione: i flussi e i varchi in sé restano alle altre due proprietà.
  • Domande. Tipo A: effetti della dimensione assoluta su flussi e controllo. Tipo B: effetti sulla politica interna ed estera dell'attore (nel tipo A non esiste un attore unico, quindi la "politica interna" non si applica).
  • Esempi anonimi. Nel file di conoscenza sono in un blocco marcato "da non citare nell'output" e senza nomi di luoghi: il rischio dei casi reali è che il modello li ricopi, senza fonte, anche quando si analizza altro. Il prompt di Phase06Estensione non contiene casi reali.

Posizione relativa: le relazioni di prossimità

Oltre al quadro regionale, la posizione relativa valorizza ciò che sta a ridosso dello spazio: porti, aeroporti, basi, poli industriali o urbani, confini, nodi di rete, spazi di altri attori che per vicinanza fisica ne condizionano l'uso, lo sviluppo o l'autonomia. Per ogni prossimità con rilievo politico il testo indica chi la esercita, il vincolo o l'opportunità che produce (dipendenza, subordinazione di fatto, protezione, esposizione, rendita di posizione) e quanto è ineludibile: uno spazio piccolo vicino a un polo molto più grande ne è spesso condizionato a prescindere dall'appartenenza formale.

  • Niente cartografia. Il client Gemini ha solo lo strumento di ricerca web (google_search), non uno strumento cartografico: il modello non "guarda la mappa", attinge alla propria conoscenza geografica e a ciò che trova in rete. Per questo la regola chiede la geografia concreta del luogo (che cosa c'è nelle vicinanze, a quale distanza e in che direzione), la fonte per le distanze e la lacuna dichiarata se la prossimità non è verificabile, invece di presumerla. Un eventuale strumento cartografico (il grounding con mappe di Gemini, da verificare per il modello configurato) sarebbe un'integrazione a parte.
  • Dove sta scritto. 02-proprieta-spazio.md (proprietà 3: paragrafo "Relazioni di prossimità", una domanda in più per il tipo A e una per il tipo B) e un promemoria nel prompt di Phase06PosRel, l'unica chiamata che lo riceve. L'esempio nel file è anonimo (un piccolo centro costiero e un grande porto) e marcato "da non citare nell'output".
  • Confini con le altre proprietà. Contano solo le prossimità politicamente rilevanti, non un elenco di ciò che sta intorno; varchi e passaggi restano ad Accessibilità, i rapporti tra scale a Scalarità.
  • Non un dato permanente. Il prompt di Phase06PosRel chiede di indicare da quando e per effetto di che cosa lo spazio è collocato così e perché oggi ha, o non ha, valore politico. Passato di riferimento: i fattori di profondità storica di P02 (il prompt riceve già tutto il JSON di P02). Se la condizione era diversa: com'era e che cosa è cambiato; se NON è cambiata: perché è rimasta uguale e perché oggi conta o non conta. Non inventare un cambiamento che non c'è. Date ed eventi specifici richiedono una fonte; senza, formulazione strutturale o lacuna. L'inferenza principale deve contenere il nesso ieri-oggi (è l'unica parte che la sintesi di P06 legge); nessun esempio di apertura nel prompt (con «da sempre ...» il modello lo copiava anche dove era impreciso). Vale per tutti i tipi. Stessa regola in 02-proprieta-spazio.md (§3, «Non un dato permanente»). Nessun campo nuovo e nessun validatore: la regola non è verificabile in automatico.
  • Limiti. È un'istruzione, non un controllo: nessun validatore. Posizione relativa può ancora essere dichiarata non rilevante, con motivazione. La sinteticità resta a 3-6 frasi: se il testo risultasse troncato dal tetto di 1200 caratteri si vede dalla pagina Debug fasi (P06_posizione_relativa). Costo: circa 250-300 token in più per ciascuna delle 13 chiamate di P06 (stima), circa 60 nella sola chiamata di Posizione relativa.

Risorse: valore relativo e poste in palio

Il valore di una risorsa è relativo, da attore ad attore e, per lo stesso attore, nel tempo. La Risorse (10ª proprietà di P06, eseguita prima di P08/P09) ha un campo obbligatorio nel suo solo schema (Phase06Risorse::schema()), prima del peso: risorse_valutate, da 0 a 5 voci {risorsa, attori[1-3]{attore, valore}, nel_tempo, verifiche{interesse_di_controllo, rivalita, competizione_visibile_o_condizione}, motivazione_competizione}. Vuoto solo con peso nullo (nessuna risorsa che conti). Il modello NON scrive il verdetto «posta in palio»: lo ricava l'applicazione dai tre controlli.

  • Posta in palio = i tre controlli tutti veri: (1) interesse_di_controllo: almeno due attori distinti con un interesse specifico a controllarne accesso o uso; (2) rivalita: il controllo dell'uno riduce o impedisce quello dell'altro (non accordi di fornitura o protezione, dipendenze reciproche, risorse abbondanti e condivise); (3) competizione_visibile_o_condizione: competizione già visibile o condizione concreta nominata (attuale o plausibile). Nel dubbio false. Phase06Risorse::valida() calcola posta_in_palio per ogni risorsa e poste_in_palio (sovrascrivendo ciò che scrivesse il modello) e rifiuta, con la fase che si ripete: elenco mancante o vuoto con peso diverso da nullo, risorsa senza attori con il loro valore, controllo non booleano o mancante (P06.risorse_valutate); interesse_di_controllo vero con un solo attore (anche scritto due volte con maiuscole diverse) o una posta in palio senza motivazione (P06.risorse_posta_in_palio).
  • Passato di riferimento: i fattori di profondità storica di P02 (il prompt riceve già il JSON di P02); date ed eventi specifici solo con fonte. Tipo B: l'attore stesso più i rivali che contano. Gli attori sono un elenco provvisorio, non vincolano P08/P09.
  • A valle. L'applicazione calcola poste_in_palio (i nomi delle risorse con posta_in_palio vero). La sintesi di P06 le riceve nel riepilogo, accanto all'inferenza di Risorse («Poste in palio (risorse contese da almeno due attori): …» oppure «Nessuna delle risorse è una posta in palio»), e solo se il campo c'è: per le analisi precedenti il prompt della sintesi è identico. P07 e P08 non le ricevono direttamente.
  • Schermata: nella scheda di P06, sotto Risorse, «Risorse e per chi valgono» con il chip «posta in palio» (js/renderer-fasi.js).
  • Limiti. I tre controlli sono comunque giudizi del modello: rispetto a un solo sì/no la classificazione è più stabile tra semi, ma non del tutto, e in parte la differenza viene dall'elenco di risorse, che cambia da una corsa all'altra (vedi le note di versione, voce 59).

Delimitazione: trascurabile quando lo spazio non è continuo

La delimitazione riguarda le frontiere, quindi presuppone uno spazio continuo (fisicamente contiguo, con un perimetro). Se lo spazio in esame è un insieme di aree o nodi non contigui legati da relazioni funzionali (una filiera, una rete) e non dalla continuità della geografia fisica, non c'è una frontiera da analizzare: la proprietà va dichiarata non rilevante, con una motivazione che dice che lo spazio è discontinuo.

  • Regola parziale. Se lo spazio è continuo solo in parte (un territorio con exclave, un arcipelago, un'area con una porzione staccata), la delimitazione si tratta solo per le porzioni continue, in poche righe, senza estenderla all'insieme.
  • Forma dello spazio, non tipo. Il criterio non dipende dal tipo di analisi: dopo la spazializzazione un tipo C.1 o C.2 può risultare continuo o no. La continuità è spaziale e non va confusa con quella temporale del controllo (01-tipologia.md, sezione 2).
  • Dove sta scritto. 02-proprieta-spazio.md (proprietà 4, paragrafo "Quando è trascurabile") e un promemoria nel prompt di Phase06Delimitazione, l'unica chiamata che lo riceve. L'esempio nel file è anonimo (una filiera, senza materie prime con nome) e marcato "da non citare nell'output".
  • Limiti. È un'istruzione, non un controllo: la continuità è un giudizio e non c'è un validatore dedicato (quello comune impone già la motivazione se la proprietà è dichiarata non rilevante). Si verifica dalla pagina Debug fasi (P06_delimitazione). Nella sintesi P06 la proprietà compare come non rilevante con la sua motivazione. Costo: circa 150-200 token in più per ciascuna delle 13 chiamate di P06 (stima), circa 40 nella sola chiamata di Delimitazione.

Classificazione delle proprietà dello spazio: il peso

Le proprietà hanno un peso in due momenti: iniziale, giudicato da ogni sotto-fase da sola, e finale, assegnato in P06_sintesi con un confronto tra le dodici (massimo 5 di peso alto). Il peso finale è quello mostrato accanto a ogni proprietà nell'interfaccia (con il motivo); nelle analisi salvate prima dell'introduzione del peso si vedono ancora i badge «rilevante / non rilevante». Il criterio non è una soglia numerica ma se l'analisi di quella proprietà, applicata al tema concreto, porta a una conclusione sui rapporti di potere o sulla configurazione dello spazio, oppure resta solo descrittiva.

🔒 Non è solo una regola nel prompt: un validatore lato server rifiuta l'output (facendo scattare un retry) se una proprietà di peso alto/medio/basso manca dell'inferenza, se il peso alto non ha motivazione_peso, se il peso basso ha un testo troppo lungo, se il peso nullo non ha la motivazione; e rifiuta la sintesi se mancano o si ripetono proprietà nei pesi o se più di 5 hanno peso alto.

La base di conoscenza (02-proprieta-spazio.md, sezione 5) invita a un esame attento prima di declassare una proprietà (proprietà apparentemente neutre, come l'accessibilità formale, spesso rivelano condizioni sostanziali di potere) ma ammette il peso basso o nullo, con motivazione specifica, quando l'esame non produce alcun effetto sul potere: il peso alto non è un default.

Un meccanismo per certi versi simile esiste anche in P09a, per i 12 "piani della coesione interna" (quando l'analisi segue il ramo dell'attore dominante): anche lì ogni piano richiede una dichiarazione binaria (pertinente/non pertinente). Il validatore server-side è però meno rigoroso di quello di P06: impone solo che tutti e 12 i piani compaiano nell'array, senza verificare che l'analisi o la motivazione siano effettivamente compilate.

Fase P07: Relazioni tra gruppi

P07 apre il ramo di tipo A (spazio senza attore dominante): analizza come i gruppi umani coinvolti si relazionano tra loro, prima ancora di descrivere i singoli attori (che arriva dopo, in P08). Riceve in input parametri, classificazione e la sintesi di P06.

I campi principali

CampoCosa deve distinguere
espressioni_relazioni.*Relazioni cooperative e conflittuali descritte separatamente, più eventuali assi informali che alterano i rapporti formali
conflittualita.*storia_di_violenza, uso_armi_immateriali (disinformazione, sanzioni, pressione normativa) e una caratterizzazione a etichette multiple (esplicita/latente, armata/non_violenta, simmetrica/asimmetrica, manifesta/dissimulata, materiale/immateriale)
ragioni_scontro.*Quattro liste distinte: fattori_basici (bisogni primari, identità), fattori_accessori (contingenti, ideologici), fattori_strutturali (persistono nel lungo periodo), fattori_contingenti (episodici) — un validatore richiede che fattori_basici non sia mai vuoto
spazio_come_moventeLo spazio è causa scatenante o concausa? (identitario/economico/strategico) — null se nessuno è pertinente
spazio_come_condizionamentoCome le caratteristiche fisiche dello spazio modellano le opzioni strategiche dei gruppi
spazio_come_esitoLe relazioni di potere si sono già cristallizzate nello spazio (confini, infrastrutture, accordi)? Distingue manifestazioni materiali/immateriali e formalizzate/informali
⚠️ Regola critica: il prompt vieta esplicitamente di attribuire peso maggiore ai fattori basici rispetto agli accessori per default — il peso va sempre giustificato sul caso concreto, non assunto in automatico.

Fase P08: Attori geopolitici

P08 completa il ramo di tipo A: mappa i singoli attori dello spazio, il loro peso e le loro narrazioni, sulla base delle relazioni già descritte in P07. La tassonomia delle categorie, i ruoli e la visibilità sono descritti in dettaglio nella sezione Attori: categorie, ruoli, visibilità — qui trovi come la fase li usa.

I quattro compiti, in ordine

PassoCosa richiede
1. VarietàIndividuare tutti gli attori pertinenti dalle undici categorie del metodo, cercando attivamente quelli a bassa visibilità (reti informali, lobby, entità non istituzionalizzate) invece di limitarsi ai più visibili
2. PesoAssegnare un ruolo a ciascun attore — un validatore richiede che compaia almeno un ruolo non polarizzato (mediatore, garante, guastatore, coinvolto_indirettamente, beneficiario_passivo)
3. Descrizione individualePer ogni attore: controllo_de_facto (reale, non formale), beneficio_atteso, costo_accettato, ed eventualmente porzione_di_interesse e intensita_controllo
4. NarrazioniPer gli attori principali: legittimazione (come giustificano la propria posizione), strumenti_soft_power, pregiudizi_verso_avversario — applicando la checklist degli artifici retorici del file fonti
⚠️ I due validatori di P08: almeno 2 attori distinti; almeno un ruolo non polarizzato; almeno un attore a visibilità bassa — quest'ultimo è il motivo più comune di un errore di validazione su questa fase (vedi la sezione FAQ su cosa fare quando una fase non passa i validatori).

Fasi P09a/b/c: il ramo dell'attore dominante

Quando il tipo effettivo è B (uno spazio sottoposto al controllo di un attore dominante), la pipeline segue tre fasi in sequenza invece di P07/P08: coesione interna, intensità della presa, fattori di forza per la proiezione esterna. Tutte e tre si concentrano sullo stesso attore, identificato per primo in P09a.

P09a — Coesione interna

Prima cosa: identifica e nomina l'attore dominante (nome_attore). Poi vaglia sistematicamente tutti e dodici i piani della coesione interna — storico, demografico, istituzionale, immigratorio, mediatico, sociale, politico_ideologico, geografico, etnico, religioso, culturale, infrastrutturale — un validatore impone che compaiano tutti e dodici nell'array piani_coesione, anche quelli dichiarati non pertinenti. Per ognuno: pertinente sì/no e, se sì, un'analisi con valutazione (fattore di coesione / divisione / neutro). Chiude con valutazione_complessiva (alta/media/bassa) e un' inferenza_principale.

P09b — Intensità della presa

Analizza quanto a fondo l'attore identificato in P09a esercita il controllo, rispondendo a quattro interrogativi: funzioni di sicurezza, funzioni organizzative, sfruttamento delle opportunità offerte dallo spazio, struttura organizzativa articolata sul territorio. Ne deriva forma_controllo_interna sulla stessa scala usata in P04 (dominio → egemonia → sfera_influenza → ingerenza → sfera_interessi → cogestione → rinuncia_volontaria → autorita_nominale; definizioni in 09-forme-di-controllo.md, colonna "sullo spazio formalmente proprio") e intensita_presa (forte/media/debole).

P09c — Fattori di forza per la proiezione esterna

Esamina dieci ambiti (economico, istituzionale, militare, reputazionale, sensibilità collettive, geografico, tecnologico, legale, ideologico, demografico) e, per ciascuno rilevante, classifica il fattore secondo quattro dicotomie indipendenti: rendimento (remunerativo/tattico/simbolico), natura (materiale/immateriale), stato (già posseduto/potenziale), origine (tradizionale/recente). Indica anche, se determinabile, la forma_controllo_esterna sulla stessa scala, letta con la colonna "sullo spazio formalmente altrui" di 09-forme-di-controllo.md.

⚠️ Regola critica — nessun valore assoluto: l'array concorrenti_considerati non può mai essere vuoto per nessun fattore — è il validatore più stringente di P09c. Ogni fattore di forza vale solo rispetto a concorrenti espliciti, mai in termini assoluti.

Fase P10: Autoverifica

P10 è la revisione critica dell'intera analisi. Legge tutte le fasi precedenti e identifica incoerenze, pregiudizi, assunzioni non fondate.

Cosa segnala P10

  • Coerenza complessiva: soddisfacente / con riserve / problematica
  • Fattori strutturali vs contingenti: sono chiaramente distinti?
  • Leader-centrismo: l'analisi dipende troppo da un singolo attore?
  • Monocausalità: si assegna troppo peso a una sola causa?
  • Problemi rilevati: lista di problemi specifici con gravità (alta/media/bassa)
  • Lacune non dichiarate: a differenza delle lacune viste durante l'analisi (vedi sezione Lacune dichiarate), qui P10 rilegge tutto il lavoro già fatto e segnala mancanze che avrebbero dovuto essere dichiarate prima e non lo sono state — un controllo a posteriori, non una dichiarazione nel momento in cui si scrive
  • Approvazione per le conclusioni (approvazione_per_conclusioni): giudizio booleano se l'analisi è abbastanza solida da procedere così com'è o richiederebbe revisioni sostanziali. Non blocca la pipeline — validaP10 non lo controlla, resta informativo — ma viene letto dal costruttore di scenari del Wargame per segnalare le analisi da rivedere

Come applicare una correzione

Quando P10 suggerisce una correzione (es: "Riconsiderare i fattori basici di P07: la conflittualità non è sufficientemente radicata in fattori strutturali"), il suggerimento è informativo, non esecutivo.

  • Se il problema è in P04 (classificazione): Usa /riclassifica [tipo] [motivazione] una sola volta, indicando tu il tipo (A, B, C.1 o C.2) e perché: sono obbligatori. La pipeline ricomincerà da P05 con il tipo che hai imposto e ripeterà tutte le fasi successive. I problemi rilevati da P10 non vengono più passati a P04: la classificazione è una tua decisione e il sistema non la rifiuta, la tua motivazione guida le fasi successive e il report finale la dichiara. Vedi "Riclassificazione imposta dall'utente" nella sezione P04 (Classificazione).
  • Se il problema è in P07, P08, P09a/b/c (rami analitici): Al momento non è possibile "rifare" una singola fase intermedia. Puoi resettare tutto (Nuova analisi) se il problema è critico, oppure procedere comunque verso P11/P12/P13.
  • Se il problema è di coerenza complessiva: La nota di P10 rimane nel report finale (P13) come dichiarazione di limite metodologico. Serve a segnalare ai lettori i vincoli dell'analisi.
  • Strategia consigliata

    1. Leggi attentamente il riepilogo di P10
    2. Se sono presenti problemi di gravità alta in P04, considera /riclassifica
    3. Per problemi in fasi successive, continua comunque verso P11/P12/P13
    4. Nel report finale (P13), i limiti metodologici saranno documentati
    ⚠️ Importante: /riclassifica può essere usato una sola volta per analisi, ed è consumato solo se la riclassificazione riesce (StateManager::incrementaRiclassificazioni()). Usalo solo se il tipo di classificazione è significativamente sbagliato secondo te. Non è una richiesta di rivalutazione: il tipo che indichi viene applicato sempre, anche se il modello o i validatori avrebbero deciso diversamente (le riserve restano registrate come avvertenze). Dopo averlo usato, P10 non può più suggerirne un altro.
    ✓ Ricorda: Dichiarare i limiti (leader-centrismo, assunzioni non testate) è parte del metodo strutturale. Non è un fallimento, è trasparenza metodologica.

    Fase P11: Conclusioni

    P11 chiude la parte analitica della pipeline: rilegge introduzione, sintesi di P06, il ramo completato (P07/P08 o P09a/b/c) e l'autoverifica di P10, e ne trae le conclusioni. È l'ultima fase prima degli scenari (P12) e del report (P13).

    La struttura obbligatoria

    CampoCosa deve contenere
    elementi_strutturaliFattori costanti di lungo periodo — un validatore impone che non sia mai vuoto
    elementi_contingentiFattori temporanei, legati a leadership o cicli economici brevi — tenuti nettamente separati dagli strutturali
    elementi_inattesiCiò che ha sorpreso o è emerso contro le aspettative iniziali — l'occasione per mostrare il valore aggiunto dell'analisi
    dimensione_interna / dimensione_esternaSolo per tipo effettivo B: rapporti con le scale inferiori e capacità di contrastare contropoteri interni (interna), spazio di proiezione e risultato tendenziale dell'azione esterna (esterna). Per tipo A restano null
    dichiarazione_soggettivitaFormula esplicita, obbligatoria, che riconosce la natura interpretativa delle conclusioni e la loro contestabilità — un validatore la richiede sempre non vuota
    completezza_dichiaratacompleta o parziale; se parziale, limitazioni_dichiarate spiega cosa manca
    lacune_rimaste_aperteElenco delle lacune che, a questo punto dell'analisi, restano non colmate — riepilogo finale, non una nuova dichiarazione fase per fase (vedi Lacune dichiarate)
    ℹ️ Vincoli trasversali: le conclusioni non possono reggersi su un singolo leader o su una sola causa, devono produrre inferenze (non un inventario di fatti già detti) e segnalare esplicitamente gli elementi inattesi — sono gli stessi rischi che P10 verifica retrospettivamente.

    Fase P12: Scenari

    P12 costruisce gli scenari futuri a partire dalle conclusioni di P11. È, per esplicita scelta del metodo, la fase con i vincoli più stringenti di tutta la pipeline — cinque regole vincolanti, tutte verificate da un validatore dedicato.

    Le cinque regole vincolanti

    RegolaCosa impone
    1. Nessuna certezza assolutaOgni scenario è un'ipotesi, mai una previsione sicura
    2. Valore probabilistico qualitativoprobabilita_qualitativa: buone_probabilita / possibile / improbabile — mai percentuali numeriche (vietate anche nel testo libero, es. "30%" o "0,3")
    3. Solo variazioni strutturali aggregateNessun episodio singolo. Scala temporale minima medio_periodo: breve_periodo non è mai ammesso in P12
    4. Fattore stabilizzatore obbligatorioOgni scenario deve poggiare su almeno un fattore con stabilita massima/molto_alta/alta/media — mai solo su fattori bassa/minima (finanziari, tecnologici, leader, idee, contingenze politiche): troppo passeggeri da soli
    5. Ventaglio di scenariAlmeno due scenari — uno solo trasmetterebbe falsa certezza. Uno scenario a bassa probabilità va incluso comunque se le conseguenze sarebbero clamorose

    Ogni scenario, campo per campo

    denominazione (nome breve e memorabile), descrizione, probabilita_qualitativa, motivo_di_inclusione (probabilità / conseguenze_clamorose / entrambi), nessi_causali (la catena logica che porta allo scenario), condizioni_abilitanti, fattori_stabilizzatori (con stabilita per ciascuno), fattori_aleatori (cosa potrebbe smentirlo), scala_temporale. A chiusura dell'intera fase (non per singolo scenario): variabili_nuove_ipotizzabili, fattori imprevisti emersi solo a questo punto che potrebbero cambiare il quadro.

    ⚠️ Il validatore più severo della pipeline: P12 controlla con regex il testo di ogni scenario per percentuali (\d+\s?%) e probabilità numeriche (0.3, 0,3) e li rifiuta automaticamente se presenti — non solo nel campo probabilità, in qualunque testo dello scenario.

    Fase P13: Report narrativo

    P13 non produce nuova analisi: assembla in prosa continua tutto ciò che le fasi precedenti hanno già stabilito. Va invocata esplicitamente col comando /concludi report dopo P12 — non parte da sola. È l'unica fase il cui output non è pensato per essere letto come un messaggio strutturato in un certo formato, ma come testo narrativo leggibile.

    Cosa riceve in input

    Introduzione (P03), la sintesi di P06 (non le 12 proprietà per esteso, solo sintesi_strutturale, proprieta_piu_rilevanti e inferenze_trasversali — selezione deliberata per non saturare il contesto), il ramo analitico completo (P07/P08 o P09a/b/c), conclusioni (P11), scenari (P12), e un elenco esatto delle fonti citabili in-text con l'etichetta autore/anno esatta con cui compariranno in bibliografia — vedi Fonti e bibliografia.

    La struttura attesa

    Cinque sezioni, in ordine dal generale al particolare: introduzione, caratteri dello spazio, poi — a seconda del tipo effettivo — relazioni e attori (tipo A) oppure presa interna e proiezione esterna (tipo B), infine conclusioni e scenari. La sezione dedicata agli attori (o all'attore, tipo B) non va mai compressa: è il punto su cui si concentra la curiosità del lettore, e un validatore dedicato la confronta con la lunghezza media delle altre sezioni.

    Regola redazionaleIn pratica
    Tracciabilità in-textOgni affermazione fattuale derivata da una fonte va citata nel testo come "(Autore, Anno)", usando esattamente una delle etichette fornite — mai inventata o riformulata
    Verifica incrociataSe più fonti indipendenti confermano lo stesso fatto, si citano tutte insieme nella stessa parentesi
    Niente valutazioni indebiteVietata l'aggettivazione valutativa, i nessi non argomentati, gli scenari presentati come necessari — gli stessi artifici retorici verificati altrove nella pipeline
    ⚠️ I due validatori di P13: ogni fase attesa per il tipo effettivo deve essere coperta da almeno una sezione (punti_coperti); la sezione attori/attore non può essere sproporzionatamente più corta della media delle altre — vedi FAQ per come reagire se il report non passa questi controlli.

    Fase P14: Comparazione (opzionale)

    P14 non fa parte del percorso lineare: si invoca col comando /compara [descrizione del caso] dopo P11, per confrontare l'analisi appena condotta con un altro caso proposto da te. Non è mai obbligatoria — P13 si genera comunque senza passare da qui.

    ⏸ Comando disattivato. Attualmente disattivato: risponde «Comando non disponibile» (il pulsante non compare più nei pannelli «Azioni disponibili»; ricompare con la costante accesa). Si riattiva con define('COMPARA_ABILITATO', true); in config-work.php. Il codice della fase non è stato toccato: la descrizione qui sotto vale quando il comando è attivo.

    I tre divieti, verificati prima di tutto

    Prima di procedere al confronto vero e proprio, P14 verifica esplicitamente tre condizioni di ammissibilità — se anche una sola è violata, la comparazione viene rifiutata (ammissibilita.ammessa = false), con motivazione (ammissibilita.motivazione_rifiuto) e, quando possibile, una proposta alternativa (ammissibilita.proposta_alternativa) di confronto tra singoli aspetti omologhi invece che tra i due casi nella loro interezza. Nello schema non sono tre campi booleani indipendenti: sono i tre valori possibili di un unico campo, ammissibilita.divieto_violato (nullo se la comparazione è ammessa) — il modello può quindi dichiarare un solo divieto violato alla volta, anche se più di uno fosse tecnicamente applicabile:

    Valore di divieto_violatoCosa verifica
    divieto_1_categorie_diverseGli attori protagonisti appartengono alla stessa categoria geopolitica — non basta la stessa categoria politologica: uno stato globale e uno stato minore non sono termini omogenei
    divieto_2_livelli_controllo_diversiI due spazi sono sottoposti allo stesso livello di controllo (entrambi contesi, o entrambi dominati)
    divieto_3_ambienti_geopolitici_diversiI due casi appartengono allo stesso ambiente geopolitico (terrestre, marittimo, aerospaziale, extra-atmosferico, digitale…)

    Se la comparazione è ammessa

    Il confronto procede aspetto per aspetto (mai i due casi nella loro interezza): per ciascun aspetto, caso_principale vs caso_confronto, le differenze_rilevanti e un'inferenza. Chiude con variazioni_locali_emerse (differenze che illuminano aspetti non visibili in una singola analisi) e nuove_chiavi_lettura.

    ℹ️ Dichiarazione obbligatoria: il giudizio sulla liceità di una comparazione non ha regole prestabilite in astratto — un validatore richiede sempre la dichiarazione_limite_soggettivo, per rendere esplicito che è comunque un giudizio interpretativo, non un calcolo oggettivo.

    Lacune dichiarate

    Durante l'analisi vedi comparire, nella sidebar "Lacune dichiarate", elementi che il modello segnala come mancanti invece di inventarli. Questa sezione spiega da dove nascono, cosa significano davvero, e come usarle.

    Da dove nascono

    Ogni fase riceve, tra le sue regole permanenti (lo stesso blocco iniettato in ogni fase, vedi Fonti e bibliografia), questa istruzione letterale:

    "Nessun fatto senza fonte. Non asserire dati specifici (cifre, date, quote, assetti attuali, dichiarazioni) senza una fonte verificabile o fornita dall'utente. In assenza, usa il campo lacune con impatto dichiarato e prosegui al livello strutturale."

    In pratica: quando il modello dovrebbe affermare un dato preciso ma non ha una fonte verificabile a sostegno, l'alternativa all'inventare (o all'affermarlo comunque, senza basi) è dichiarare esplicitamente cosa manca. Ogni lacuna ha due parti:

    CampoCosa contiene
    cosa_servirebbe Che informazione mancherebbe per colmare il punto (es. "dato demografico aggiornato al 2025", "testo integrale dell'accordo non reso pubblico")
    impatto_sulla_analisi Quanto quella mancanza pesa sulle conclusioni — testo libero scritto dal modello, non un valore da un elenco fisso (vedi più sotto perché questo conta)

    In quali fasi possono comparire

    Solo le fasi che devono affermare fatti verificabili hanno un campo lacune nel proprio schema: P03 (Introduzione), P05 (Spazializzazione), ogni sotto-fase di P06 (le 12 proprietà strutturali) più P06_sintesi, P07 (Relazioni), P08 (Attori), P09a/P09b/P09c (coesione, presa, fattori di forza — solo tipo B, attore dominante).

    Non compaiono in P01, P02, P04, P12, P13, P14. Sono fasi di setup, classificazione, generazione di scenari o assemblaggio — P04, ad esempio, esprime l'incertezza in altro modo, con il campo confidenza (alta/media/bassa), non con lacune.

    Due campi diversi, spesso confusi con le lacune

    P10 e P11 hanno campi che sembrano lacune ma non lo sono, nello stesso senso:

    FaseCampoCosa rappresenta davvero
    P10 — Autoverifica lacune_non_dichiarate_rilevate Audit a posteriori: il modello rilegge tutto il lavoro già fatto e segnala mancanze che avrebbero dovuto essere dichiarate prima (con il meccanismo qui sopra) e non lo sono state — non è una dichiarazione nel momento in cui si scrive, è un controllo di qualità retrospettivo
    P11 — Conclusioni lacune_rimaste_aperte Sintesi finale: semplice elenco di frasi, quello che resta irrisolto una volta arrivati alle conclusioni — un riepilogo per il lettore, non una nuova dichiarazione puntuale

    Come vengono raccolte e mostrate

    Il server cerca ricorsivamente un array lacune ovunque si trovi nell'output di ogni fase (a seconda della fase può essere alla radice o annidato, come per le fonti — vedi Fonti e bibliografia) e lo accumula per l'intera sessione. La sidebar mostra sempre il totale accumulato fino a quel momento, non solo quelle dell'ultima fase completata.

    Le lacune in sidebar sono ordinate per gravità stimata, dedotta dal testo di impatto_sulla_analisi cercando parole chiave comuni in italiano (es. "critico", "significativo" → gravità alta; "marginale", "trascurabile" → gravità bassa) — quelle ad alto impatto salgono in cima con un bordo rosso e ⚠, quelle a basso impatto scendono con un bordo grigio.

    ⚠️ È un'euristica, non un giudizio affidabile al 100%: impatto_sulla_analisi è testo libero scritto dal modello, non un valore strutturato tra alternative fisse — non c'è modo di leggerne la gravità con certezza meccanica. Una lacuna il cui testo non contiene nessuna delle parole chiave riconosciute resta "non specificato" e mantiene l'ordine di arrivo: leggi comunque il testo per intero prima di dare peso alla posizione in lista.

    Dove le trovi

    • Sidebar "Lacune dichiarate" durante l'analisi, sempre aggiornata al totale reale
    • Scrivendo stato in chat, che riporta comunque l'elenco completo accumulato
    • Nei documenti salvati ("Salva chat" e "Salva report finale"): una sezione dedicata elenca tutte le lacune dichiarate, nello stesso ordine per gravità della sidebar

    Come interpretarle

    ✓ Non bloccano l'analisi. Sono il meccanismo con cui il sistema preferisce dichiarare onestamente un limite piuttosto che inventare un dato plausibile — coerente con lo spirito generale dell'app (vedi anche P10 — Autoverifica). Una lacuna ad alto impatto su un punto centrale del tema merita più attenzione di una a basso impatto su un dettaglio marginale: usa il testo di impatto_sulla_analisi (non solo la sua posizione in lista) per decidere se vale la pena colmarla — ad esempio fornendo tu stesso l'informazione mancante nel messaggio successivo, prima che la pipeline prosegua oltre il punto in cui servirebbe.

    Fonti e bibliografia

    Ogni fase può citare fonti a sostegno delle proprie affermazioni. Alla fine dell'analisi (P13), tutte le fonti raccolte lungo il percorso confluiscono in una bibliografia unica, allegata al report.

    Da dove vengono raccolte

    Non solo alla fine: dopo ogni singola fase, l'app cerca ricorsivamente un array fonti ovunque si trovi nell'output — a seconda della fase può essere alla radice, oppure annidato (es. dentro ogni indizio di P04, dentro ogni proprietà di P06, dentro ogni attore di P08) — e lo accumula in una lista di sessione. Alla fine, quella lista diventa la bibliografia completa.

    La regola che genera le fonti

    Ogni fase riceve, oltre alle sue istruzioni specifiche, un identico blocco di regole permanenti. Due riguardano direttamente le fonti:

    • Nessun fatto senza fonte: il modello non può asserire dati specifici (cifre, date, citazioni, assetti attuali) senza una fonte verificabile o fornita da te. Se non ce l'ha, deve dichiarare una lacuna invece di inventare.
    • Ogni affermazione "accertata" richiede una fonte: se il tipo di un'informazione è informazione_accertata ma non c'è una fonte reale a supporto, il modello scrive inferenza_propria — un modo per segnalare "questo è un mio ragionamento, non un dato verificato". Anche il valore "Analista" con anno assente ("n.d.") ha lo stesso significato.
    ℹ️ Perché non le vedi in bibliografia: Inferenza propria e Analista (n.d.) non sono fonti verificabili dal lettore — sono etichette che il modello usa quando non ne ha una vera. La bibliografia finale le esclude automaticamente, insieme ai duplicati (stesso autore, titolo e URL).

    Da dove viene, davvero, ogni fonte

    Ogni fonte dichiara una provenienza:

    ProvenienzaEtichetta mostrata in bibliografiaCosa significa in pratica
    ricerca_web_attiva 🌐 verificata via ricerca web Il modello dichiara di averla trovata cercando sul web
    fornita_da_utente fornita dall'utente L'hai indicata tu nel testo scritto in chat
    file_conoscenza da file di conoscenza del metodo Riferita ai file metodologici interni dell'app (usati per guidare il ragionamento, non come fatti da citare — vedi sotto)
    documento_allegato da documento allegato Valore previsto dallo schema, ma l'app non ha oggi una funzione per allegare documenti: in pratica non compare
    eil_certificato 📚 documento certificato (EIL) Documento della base di conoscenza certificata EIL. Le voci sono costruite in codice da ANGST dalle citazioni di EIL (non lasciate al modello), deduplicate per reference_id. Solo nelle modalità Certificata / Mista
    eil_elaborazione 📚 elaborazione interna (EIL) Voce wiki / evidence di EIL: sintesi interna, esclusa dalla bibliografia (resta solo contesto nel prompt)
    ⚠️ Da sapere sulla ricerca web reale (grounding): ogni fase dell'analisi produce il proprio risultato con una sola chiamata al modello, senza ricerca web: i dati, le date e le fonti che il modello indica con provenienza ricerca_web_attiva vengono dalla sua conoscenza pregressa, non da una verifica in tempo reale, e la bibliografia le etichetta «non verificata». Vanno trattati come affermazioni da controllare tu stesso, non come citazioni già verificate. La ricerca web reale parte solo per i «fatti di riferimento» (una ricerca prima di P03, se abilitati: vedi la tabella delle costanti), per la «Ricerca approfondita» (colma le lacune dichiarate, entro il tetto LACUNE_MAX_RICERCHE_PER_ANALISI: oggi 0, cioè non lo fa) e, in modalità «Mista integrata», per l'arricchimento EIL; richiede l'accesso a internet attivo — è attivo di default e torna su "attivato" quando l'utenza «admin» rilancia l'app (apre una nuova analisi o riprende quella in corso; non riaprendo la pagina di configurazione, che invece mostra lo stato reale). Gli altri utenti non lo cambiano: se l'amministratore lo spegne, resta spento finché non lo rilancia lui. Quindi, per evitare il costo aggiuntivo del grounding per le analisi in corso, l'amministratore deve spegnerlo di proposito dopo ogni suo rilancio. Anche con la ricerca riuscita non dare per scontato ogni risultato: verifica comunque le fonti che contano davvero per la tua analisi.
    ℹ️ Il grounding costa a parte: quando attivo, ogni ricerca web reale eseguita durante l'analisi si paga in aggiunta ai token, con un prezzo per numero di richieste (non per quanto testo genera il modello) — vedi la sezione Token e costi e, se sei l'amministratore, la pagina di configurazione per il dettaglio.

    I file di conoscenza (knowledge/*.md) sono invece un caso diverso: vengono caricati per davvero nelle istruzioni della fase, ma sono guide sul metodo (come ragionare), non fatti sul tema analizzato — una regola permanente vieta esplicitamente al modello di citare come dato gli esempi contenuti in quei file.

    Quanto è autorevole ogni fonte — il campo natura

    Sotto ogni voce della bibliografia trovi una o più etichette (es. fonte primaria, fonte secondaria — verificare, oltre alla provenienza vista sopra): sono due campi diversi e indipendenti. La provenienza dice da dove il modello l'ha presa; natura dice quanto dovresti fidartene — la stessa gerarchia di autorevolezza descritta in dettaglio nel file di metodo knowledge/06-fonti-e-retorica.md, che ogni fase consulta prima di accettare una fonte.

    Etichetta in bibliografiaCampo naturaCosa significa
    fonte primaria primaria Massima autorevolezza: riviste scientifiche peer-reviewed (in particolare Fascia A ANVUR o indicizzate su Scopus/Web of Science), libri e collettanee accademiche, atti di convegni ed enciclopedie scientifiche (es. Treccani), manuali universitari di settore, rapporti e banche dati di organizzazioni intergovernative (ONU, UE, NATO, Banca Mondiale, FMI, OCSE...) e think tank riconosciuti (ISPI, IAI, SIPRI, RAND Corporation, Chatham House, CSIS...), siti e archivi ufficiali di questi enti.
    fonte secondaria — verificare secondaria_verificata Autorevolezza minore, da usare con circospezione e possibilmente previo riscontro incrociato con una fonte primaria: recensioni su riviste di settore o blog accademici, resoconti non ufficiali di convegni, contenuti audio/video di canali indipendenti o divulgativi (solo se le tesi esposte sono riscontrabili altrove in fonti primarie), articoli di stampa internazionale o nazionale di comprovata reputazione (es. Foreign Affairs, Le Monde Diplomatique, Financial Times, The Economist) — distinguendo sempre un reportage fattuale da un editoriale d'opinione.
    ⚠️ Un terzo livello che non vedrai mai in bibliografia: esiste anche un "livello escluso" — propaganda non dichiarata, blog personali privi di affiliazione accreditata, post sui social senza riscontro ufficiale, siti clickbait, contenuti generati da altre intelligenze artificiali non revisionati da esperti umani — che non ha un valore natura valido: una regola permanente vieta al modello di aggiungere queste fonti a fonti[], nemmeno come voce secondaria. Se l'unica informazione disponibile su un punto viene da una fonte di questo livello, il modello deve dichiarare una lacuna invece di citarla — coerente con la regola "nessun fatto senza fonte".

    Il formato della citazione cambia in base al tipo di fonte

    Ogni fonte dichiara anche un campo tipo_fonte, che determina quali dettagli compaiono nella citazione stile APA — non è lo stesso identico formato per tutte le voci:

    Campo tipo_fonteDettagli aggiuntivi mostrati
    rivista_scientifica Volume ed eventuale fascicolo tra parentesi, pagine (es. Rivista di Studi Politici, 12(3), 45-67) — se presenti nella fonte
    libro Edizione tra parentesi e luogo di pubblicazione, se presenti (es. L'analisi geopolitica (3ª ed.). Carocci, Roma)
    sito_web Nessun dettaglio aggiuntivo nel corpo della citazione, ma se la fonte dichiara una data di consultazione il link viene introdotto da "Consultato il [data], da:" invece del generico "Disponibile su:" (vedi sotto)
    rapporto_istituzionale, articolo_stampa, altro Formato generico: autore, anno, titolo in corsivo, editore — nessun campo specifico aggiuntivo

    Volume, fascicolo, pagine, edizione, luogo di pubblicazione e data di consultazione sono tutti campi facoltativi: se il modello non li valorizza, la citazione ricade comunque nel formato generico corretto per quel tipo, senza campi vuoti o mancanti visibili.

    Il link alla fonte

    Quando una fonte ha un URL, compare in coda alla citazione preceduto da "Disponibile su:" (o "Consultato il [data], da:" per i siti web con data di consultazione dichiarata, vedi sopra). Il testo del link normalmente è l'indirizzo stesso — con un'eccezione:

    ℹ️ "Link alla fonte" al posto dell'URL: quando una fonte proviene da ricerca web reale (grounding), Google restituisce l'indirizzo come un link di redirect (vertexaisearch.cloud.google.com/grounding-api-redirect/...), non l'URL reale della pagina. L'app prova a risolverlo lato server prima di mostrarlo; se ci riesce, vedi l'indirizzo vero per intero. Se il redirect sopravvive (risoluzione fallita o non disponibile su quel server), il link resta comunque funzionante al click, ma il testo mostrato diventa la dicitura fissa "Link alla fonte" invece della stringa di redirect, illeggibile e poco utile da mostrare per intero.

    Citazioni in-text e numerazione

    Nel testo del report, le affermazioni che derivano da una fonte specifica sono accompagnate da una citazione tra parentesi quadre e in corsivo, del tipo [Autore, Anno, N] — dove N è il numero della voce corrispondente qui in bibliografia (mostrato anch'esso tra parentesi quadre davanti a ogni voce, riferimento metodologico compreso, che è sempre la voce numero 1). Quando un'affermazione è confermata da più fonti indipendenti, compaiono insieme nella stessa parentesi, es. [Rossi, 2021, 3; Bianchi, 2022, 5] — un modo semplice per distinguere a colpo d'occhio un dato corroborato da più fonti da uno sorretto da una sola. Una parentesi nel testo che non corrisponde esattamente a una voce della bibliografia resta tonda, non quadra: non è una citazione, solo un inciso del testo.

    Orientamento dichiarato

    Quando una fonte esprime un punto di vista riconoscibile — un think tank vicino a un determinato governo, un editoriale schierato, un canale che rappresenta gli interessi di un attore specifico — il modello può valorizzare il campo facoltativo orientamento_dichiarato. In bibliografia compare come nota a margine sotto la citazione (es. "Orientamento dichiarato: vicino al governo di X"): non è un giudizio di valore dell'app, serve solo a segnalarti che quella fonte non è neutra "per definizione" e va letta tenendone conto — coerente con la regola di pluralismo delle prospettive del report finale.

    Come si arriva alla bibliografia finale

    1. Ogni fase completata contribuisce le proprie fonti alla lista di sessione
    2. A P13, i link di redirect da ricerca web (grounding) vengono risolti all'URL reale, dove possibile (vedi sopra)
    3. La lista completa viene deduplicata (stesso autore+titolo+URL, senza distinguere maiuscole)
    4. Le voci segnaposto (Inferenza propria, Analista) vengono escluse
    5. Viene aggiunto un riferimento fisso, sempre presente: Boria, E. — L'analisi geopolitica (il testo metodologico su cui si basa l'intero approccio)
    6. L'elenco finale è ordinato alfabeticamente per autore
    7. Ogni voce riceve il numero progressivo mostrato tra parentesi quadre (il riferimento metodologico è sempre il numero 1) — lo stesso numero usato nelle citazioni in-text del report
    ✓ In pratica: tratta la bibliografia come un punto di partenza per verificare, non come una lista già controllata. È coerente con lo spirito dell'app: dichiarare i limiti (vedi anche la sezione P10 — Autoverifica) fa parte del metodo, non è un difetto da nascondere.

    Attori: categorie, ruoli, visibilità

    Nella sezione P08 — Attori geopolitici del report (ramo di tipo A, multi-attore), ogni riga della tabella descrive un attore con quattro campi: Nome, Categoria, Ruolo e Visibilità. Sono tre vocabolari chiusi (il modello sceglie da un elenco fisso, non inventa etichette), definiti nel file di metodo knowledge/04-attori.md che la fase usa per costruire il proprio prompt.

    Categoria — la tassonomia degli undici attori

    Undici categorie, classificate per orizzonte d'azione, obiettivo reale e grado di istituzionalizzazione. Non è un dettaglio formale: la categoria condiziona cosa quell'attore può realisticamente ottenere e quali vincoli subisce — ignorarla porta a giudicare le mosse di un attore con il metro di un altro.

    CategoriaCosa persegue tipicamente
    potenza_globaleEgemonia estesa anche oltre i propri confini formali, proiettata sia direttamente (presenza militare) sia indirettamente (dipendenza economica, sudditanza politica)
    organizzazione_internazionale_universaleGestire pacificamente l'ordine vigente promuovendo la cooperazione — capacità in genere bassa, dipende dagli stati membri che la finanziano
    colosso_transnazionale_privato_lucroProfitto da un'attività economica; sottostà (almeno formalmente) alle leggi statali
    entita_transnazionale_privata_no_profitProselitismo: il numero di aderenti è la sua misura di potenza, per portare avanti battaglie ideali
    movimento_contestazione_radicaleRovesciare, corrompere o intralciare il modello e l'autorità dominanti; tipicamente non istituzionalizzato, rischia la repressione
    potenza_regionaleAcquisire influenza e status nella propria area, spesso approfittando del disordine internazionale
    organizzazione_internazionale_regionaleIntegrare e stabilizzare un'area per rafforzarne coesione e status
    raggruppamento_umano_non_politicizzatoEtnie, civiltà, nazioni: rafforzare la coesione interna e diffondersi, spinte da un forte richiamo identitario
    ente_pubblicoContribuire al funzionamento dello stato — capacità in genere bassa, molto variabile tra modelli accentrati e decentrati
    realta_ufficiale_anti_statalePartiti regionalisti, movimenti localistici: difendere interessi e identità locali contro l'autorità centrale
    entita_non_istituzionalizzataPoteri mediatici, logge, lobby, movimenti d'opinione, gruppi terroristici: interessi di parte, spesso perseguiti in modo occulto

    Ruolo — oltre dominatore e dominato

    Il metodo mette in guardia esplicitamente dal farsi attrarre dalle due figure "idealtipiche" di dominatore e dominato: molti attori reali ricadono in posizioni intermedie. Nel tipo A, inoltre, nessun attore può essere classificato «dominatore»: lo spazio è, per definizione, senza attore dominante. L'attore più forte si descrive con il controllo de facto e con l'intensità del controllo, non con il ruolo; se un attore sembra davvero dominare lo spazio, la fase lo dichiara tra le lacune (la classificazione di tipo A potrebbe essere da rivedere) e non lo chiama dominatore. Un validatore impone che nell'elenco compaia almeno un ruolo non polarizzato, proprio per impedire che l'analisi collassi sui due estremi.

    • Come è imposta la regola sul dominatore. Il ruolo non è più nell'enum di schemas/p08_attori.json (P08 gira solo per il tipo A; il «dominatore» del tipo B è l'attore dominante di P09 e non è toccato) e Validators::validaP08() rifiuta, con la fase che si ripete, chi lo scrivesse comunque (P08.dominatore_tipo_a). Il prompt di Phase08Attori ha la «REGOLA DEL TIPO A». Le analisi salvate prima, con dominatori, restano leggibili.
    • Grafo degli attori. Senza dominatori né dominati, Grafo::costruisciTipoA() usa come poli gli attori con intensita_controllo «forte» (se non ce ne sono, «media»): mediatori e garanti si legano a loro con archi di mediazione, i guastatori competono con loro, coinvolti e beneficiari hanno un legame di coinvolgimento. Senza intensità resta la maglia uniforme di prima. Nessun arco di un nodo verso sé stesso.
    • Effetto sui ruoli. I ruoli che prima erano «dominatore» finiscono su garante, guastatore o mediatore (vedi le note di versione, voce 60): possono essere un'etichetta meno naturale per l'attore più forte.
    RuoloSignificato
    dominatoreNon assegnato nelle analisi di tipo A (per definizione nessun attore domina lo spazio): non è tra i ruoli ammessi in questa fase; compare solo nelle analisi salvate prima e come nodo dell'attore dominante nel grafo di tipo B. Significava: esercita il controllo effettivo sullo spazio o sulla situazione contesa
    dominatoSubisce quel controllo
    mediatoreSi frappone tra i poli, senza essere parte del controllo o della contesa
    coinvolto_indirettamenteNon è un polo della contesa, ma ne è comunque toccato
    beneficiario_passivoTrae vantaggio da un assetto di potere che non ha contribuito a determinare
    garanteAssicura la tenuta di un equilibrio tra altri attori, senza essere lui stesso uno dei poli
    guastatoreAgisce per alterare o disturbare un equilibrio esistente tra altri attori
    ℹ️ Ruoli multipli e asimmetrie: lo stesso attore può rivestire ruoli diversi a seconda dell'interlocutore e del momento — il report può descriverlo di conseguenza. Il peso di un attore inoltre non è mai presunto proporzionale alla sua taglia: va accertato caso per caso, non dedotto dalle dimensioni.

    Visibilità — non è la stessa cosa del peso reale

    Alta, media o bassa: quanto un attore è esposto/riconoscibile pubblicamente — non quanto conta davvero. Il metodo segnala un rischio specifico: la copertura mediatica dà risalto in base a ciò che colpisce il pubblico, non in base all'importanza politica reale, per cui attori a bassa visibilità (reti informali, lobby, apparati poco trasparenti) rischiano di restare fuori da un'analisi che parte dai soggetti più evidenti. Per questo un validatore impone che nell'elenco compaia almeno un attore a visibilità bassa: è una spinta a cercarli attivamente, non un dettaglio decorativo.

    Token e costi

    Nella sidebar sinistra, il pannello "Token / Costo" traccia il consumo di token per ogni fase e il costo totale dell'analisi.

    Cosa vedi nel pannello

    • Input: token usati per il prompt (testo della fase + contesto)
    • Output: token generati dal modello (risposta strutturata)
    • Pensiero: token usati dal modello per ragionamento interno (se attivo)
    • Ricerche web: richieste di ricerca eseguite dal grounding, se attivo — vedi sotto (compare solo se maggiore di zero)
    • Totale: somma di tutti i token della sessione
    • Costo: stima in valuta locale (di default USD), token + eventuale grounding

    Configurazione dei prezzi

    I prezzi (e l'interruttore del grounding, vedi Fonti e bibliografia) si gestiscono da una pagina dedicata, visibile solo all'utenza amministrativa di sistema — non a ogni account con ruolo amministratore:

    • Preset rapidi: Gemini 2.5 Pro, 1.5 Pro, Flash (con prezzi attuali)
    • Costo input/M: prezzo per milione di token di input
    • Costo output/M: prezzo per milione di token di output
    • Costo pensiero/M: prezzo per milione di token di ragionamento
    • Costo grounding/1.000 richieste: prezzo delle ricerche web reali, indipendente dai token
    • Valuta: simbolo della valuta (USD, EUR, GBP, JPY, ecc.)

    I prezzi si salvano sul server (storage/token_costs.json e storage/grounding_config.json), non inviati al server Gemini.

    💡 Nota: I costi sono calcolati localmente nel browser per la stima mostrata in sidebar, e lato server per l'addebito reale sulla quota di ogni utente — con la stessa formula, in modo che coincidano. Modifica i prezzi per riflettere i tuoi accordi contrattuali con Google Cloud.

    Prezzi di riferimento per famiglia di modello

    Valori pubblici indicativi (possono cambiare nel tempo): usali come punto di partenza per compilare i prezzi nella pagina di configurazione, non come listino garantito.

    Famiglia Modello ID Modello API (Uso in URL / SDK) Costo Input (1M token) Costo Output / Pensiero (1M token) Quota Grounding Gratuita Costo Grounding (Oltre soglia)
    Gemini 2.5 Flash-Lite gemini-2.5-flash-lite $0,10 $0,40 1.500 prompt / giorno $35,00 / 1K prompt
    Gemini 3.1 Flash-Lite gemini-3.1-flash-lite $0,25 $1,50 5.000 ricerche / mese $14,00 / 1K query
    Gemini 2.5 Flash gemini-2.5-flash $0,30 $2,50 1.500 prompt / giorno $35,00 / 1K prompt
    Gemini 3.5 / 3.6 Flash gemini-3.5-flash / gemini-3.6-flash $0,50 - $0,75 $3,00 - $3,75 5.000 ricerche / mese $14,00 / 1K query
    Gemini 2.5 Pro gemini-2.5-pro $1,25 $10,00 10.000 prompt / giorno $35,00 / 1K prompt
    Gemini 3.1 Pro (Preview) gemini-3.1-pro-preview $2,00 $12,00 5.000 ricerche / mese $14,00 / 1K query

    Costo per fase

    Dopo ogni fase, un piccolo chip mostra i token consumati in quel passaggio:

    in 1.234 · out 856 · tot 2.090 · $0.0342

    Blocco P06

    P06 esegue 13 fasi in parallelo (12 proprietà + sintesi). Il totale aggregato viene mostrato al termine di P06_sintesi.

    Costo della base di conoscenza certificata (EIL)

    Se l'integrazione EIL è attiva (EIL_ABILITATO in config.php) e l'utente sceglie una modalità di conoscenza diversa da Web, ogni interrogazione a EIL ha un costo: EIL usa Gemini al proprio interno per comporre la risposta, e riporta ad ANGST i token consumati e il costo in USD già calcolato con il suo listino (che può differire dal tuo). ANGST:

    • mostra una riga EIL nel pannello Token / Costo (token consumati da EIL, già inclusi nel Totale);
    • non riprezza quei token con il tuo listino — somma direttamente la cifra in USD fornita da EIL (canale di costo a sé, come il grounding);
    • conta comunque i token EIL nella quota utente e nel tetto di sessione (LIMITE_TOKEN_SESSIONE / LIMITE_COSTO_SESSIONE).

    In Mista integrata si aggiunge, per ogni macro-sezione, una chiamata Gemini di arricchimento: quella è consumo Gemini normale, prezzata con il tuo listino (voce di log ARRICCHIMENTO:S1/S2/S3).

    Costanti config.php per EIL

    In produzione vanno nel config-work.php privato (fuori da public_html), non nel config.php del repository.

    CostanteEffetto
    EIL_ABILITATOfalse = integrazione EIL spenta ovunque, il selettore "Conoscenza" resta nascosto e nessuna query parte nemmeno chiamando l'API a mano. Default: false (funzione opt-in).
    EIL_API_BASEURL base dell'istanza EIL, senza /api/v1.
    EIL_USERNAME · EIL_PASSWORDCredenziali di un account di servizio unico e condiviso (non per-utente ANGST), come la chiave Gemini.
    EIL_TIMEOUT_SECONDSTimeout di rete per ogni chiamata a EIL (una risposta reale richiede qualche decina di secondi).
    EIL_MAX_QUERY_PER_ANALISITetto duro di interrogazioni EIL per singola analisi (le sezioni base sono 3). 0 = nessun limite. Oltre il tetto, la sezione prosegue senza contesto EIL.

    Il token di servizio EIL (JWT, 12 h) è cachato in storage/eil_token.json; viene rinnovato da solo. Le tracce delle interrogazioni (EIL:S1 "interrogazione" / "nessuna fonte pertinente" / "non raggiungibile", ARRICCHIMENTO:S2 …) sono nel log per-utente in storage/log/.

    Salvataggio e gestione dei report

    L'app ti permette di salvare l'intera chat di analisi e il report finale in formato HTML, gestendoli su server: scaricare, rinominare, eliminare.

    Salvataggio automatico (solo utenti) e avviso agli amministratori

    Per gli utenti (ruolo «utente») la chat dell'analisi viene salvata automaticamente alla fine di ogni fase e, alla fine di P13, anche il report finale. Per ogni analisi esiste un solo file di chat e un solo report finale, aggiornati a ogni salvataggio: api/reports.php li riconosce dal metadato (auto, id dell'analisi dalla sessione, tipo) e li riscrive sullo stesso nome, in modo atomico (file temporaneo + rename). I file salvati a mano non hanno il metadato e non vengono mai sovrascritti.

    • Gli amministratori non salvano da soli, né dal browser né dal server (auto da un admin riceve 403). Alla fine di P13 compare un avviso che li invita ad aprire «📋 I miei report» per salvare il report corrente (pulsanti «Apri I miei report» e «Non ora»).
    • Il salvataggio parte circa 0,7 s dopo la fase e si accorpa: a fine P13 grafo, bibliografia e siti visitati si aggiungono dopo il pannello delle azioni e devono essere nel file. In modalità automatica e con /concludi si salva una volta, alla fine.
    • Il replay di «Riprendi l'analisi» non salva e non avvisa (altrimenti sostituirebbe la chat completa con una ricostruita senza i messaggi dell'utente); si riprende dalla fase successiva. «Nuova analisi» annulla un salvataggio in attesa.
    • Il salvataggio automatico non cambia le altre funzioni di «I miei report», e i file compaiono anche in «Tutti i report» nella cartella dell'utente.

    Accesso alla gestione report

    Nel sidebar sinistro, clicca il pulsante 📋 I miei report per aprire la modalità di gestione. Qui trovi:

    • Due pulsanti di salvataggio rapido
    • Elenco di tutti i report già salvati
    • Azioni per ciascun report (scarica, rinomina, elimina)

    Tipi di report

    L'app ti permette di salvare due cose diverse:

    1. Chat di analisi completa (analisi_del_[data].html)

    • Contiene tutta la conversazione (messaggi dell'utente e risposte del sistema)
    • Utile per documentare l'intero processo di analisi
    • Formattato come pagina HTML leggibile
    • Pulsante: 💾 Salva chat

    2. Report finale (nome proposto: report_finale_analisi_del_[data].html)

    • Contiene i risultati di tutte le fasi completate, una sezione per fase in ordine, con un indice delle fasi in testa, il tema analizzato e la classificazione
    • In coda, le lacune dichiarate; se l'analisi è arrivata a P13, anche il grafo attori e relazioni e la bibliografia
    • Non include i pannelli «Azioni disponibili», il JSON tecnico, i chip dei token né l'elenco «Siti Web visitati»: è un documento pulito, pensato per essere letto o condiviso
    • La sezione P02 si intitola «Parametri dell'analisi» e riporta i parametri definitivi, con gli stessi nomi dei campi della chat; non contiene il pulsante «Modifica parametri» (che in un file statico non funzionerebbe)
    • Più ordinato e compatto della chat completa, che invece conserva anche i tuoi messaggi
    • Pulsante: 💾 Salva report finale (disponibile dopo almeno una fase completata)

    Nome del file

    Quando premi un pulsante di salvataggio, l'app ti chiede il nome del file in una finestra di dialogo, già compilata con un nome proposto che contiene data e ora (fuso orario italiano):

    analisi_del_12-08-2026_14-30-45.html report_finale_analisi_del_12-08-2026_14-30-45.html

    Puoi accettarlo o scriverne uno tuo (per esempio report_Hormuz_agosto.html); se annulli, non viene salvato nulla. Il nome viene reso sicuro dal server: / e \ diventano spazi, i caratteri insoliti diventano _, l'estensione .html viene aggiunta se manca, e se nella tua cartella esiste già un file con quel nome ne viene creato uno nuovo con un numero: nome (2).html, nome (3).html…

    Azioni sui report

    ⬇ Scarica

    Scarica il file HTML nel tuo computer. Puoi aprirlo in qualsiasi browser senza necessità di connessione internet.

    ✏ Rinomina

    Rinomina il file con un nome personalizzato. Esempi:

    • analisi_Stretto_di_Hormuz.html
    • report_geopolitica_Pacifico.html
    • 2026_Q3_area_MENA.html

    L'estensione .html viene aggiunta automaticamente se omessa.

    ✕ Elimina

    Elimina definitivamente il file dal server. Richiede conferma. Non è possibile recuperare un file eliminato, quindi usa con cautela.

    Informazioni metadata

    Per ciascun report salvato, puoi vedere:

    • Tipo: analisi | report_finale
    • Dimensione: in KB
    • Data di salvataggio: GG/MM/AAAA HH:MM
    • Token e costo dell'analisi che ha prodotto il documento (per esempio 412.000 tok · $0.4944), nella valuta e al listino in vigore al momento del salvataggio: restano quelli anche se in seguito i prezzi cambiano. Non compaiono per i file salvati prima che questa informazione venisse registrata.

    Il nome del file nella lista è un link: lo apre in una nuova scheda del browser, senza scaricarlo.

    Come usare i report HTML

    I file HTML salvati sono documenti autoportanti e professionali:

    1. Scarica il file dal pannello report
    2. Apri nel browser (o condividi per email)
    3. Stampa in PDF (Ctrl+P) se hai bisogno di un formato statico
    4. Modifica con un editor HTML se vuoi personalizzarlo ulteriormente
    ✓ Consiglio: Salva il report finale dopo aver completato P13, e la chat completa se vuoi documentare l'intero processo decisionale.

    Dove vengono archiviati

    I file vengono salvati nel server backend, in una cartella per utente: storage/reports/<username>_<id>/. Accanto a ogni nome.html c'è un nome.meta.json con il tipo e, se noti, i token totali, il costo e la valuta dell'analisi (api/reports.php). Ogni utente, amministratori compresi, elenca e rinomina soltanto i file della propria cartella; un amministratore può inoltre eliminare i file degli altri dalla finestra «Tutti i report» (vedi sotto). Rimangono disponibili finché l'utente (o un amministratore) non li elimina.

    🗂 Tutti i report (solo amministratori)

    Gli account con ruolo amministratore hanno nella barra laterale (scheda «Altro» su smartphone) un secondo pulsante, 🗂 Tutti i report: apre i report salvati da tutti gli utenti, organizzati come le cartelle di Windows.

    • Prima schermata: un elenco con una cartella per ogni utente che ha almeno un file: icona piccola, nome nome_utente-email (per esempio lino-lino.achille@gmail.com; se l'utente non ha un'email compare solo il nome) e, sulla destra, il numero di report contenuti. L'email è quella attuale del database, quindi segue le modifiche fatte in «Utenti».
    • Cliccando una cartella si apre l'elenco delle chat e dei report di quell'utente, con tipo, dimensione, data e token/costo. In cima, ← Cartelle riporta alla schermata iniziale. Dal nome si apre il file in una nuova scheda.
    • ⬇ Scarica e ✕ Elimina per ogni file. L'eliminazione chiede conferma, è definitiva (insieme al file dei metadati) e vale anche per i file degli altri utenti; quando si elimina l'ultimo file di un utente la cartella sparisce dall'elenco. Non c'è «Rinomina»: si rinominano solo i propri file da «I miei report».

    Serve a controllare cosa è stato prodotto, a recuperare un documento per conto di un utente e a fare pulizia. Lato server l'eliminazione di un file altrui passa da DELETE api/reports.php?file=…&cartella=<username_id> ed è consentita solo agli amministratori: per un utente semplice il parametro cartella viene ignorato e la richiesta resta sulla sua cartella.

    ℹ️ Nota: La gestione dei report è del tutto locale/server-side. I file non vengono inviati a Google Gemini o a servizi terzi.

    👥 Utenti: registrazione di nuovi utenti (file Excel o modulo online)

    Per registrare nuovi utenti ci sono due strade alternative, che portano allo stesso risultato: ogni persona entra nell'elenco dei candidati e un amministratore la accetta o la rifiuta; solo quando viene accettata nasce l'account. Si sceglie una strada o l'altra, o entrambe, a seconda di quante persone si devono registrare e di chi inserisce i dati.

    Da file ExcelDa modulo online
    Chi inserisce i datiL'amministratore, con Crea utenti da lista (Amministrazione → Crea nuovo utente)La persona stessa, in una pagina pubblica di richiesta accesso
    Quando convieneMolti utenti insieme, con i dati già in un fileRichieste singole, senza dover raccogliere i dati a mano
    DatiFile .xlsx con Nome, Email e PasswordNome, Email/Username e Password, scritti dalla persona
    Nell'elenco candidatiOrigine «File Excel»Origine «Richiesta online»
    Email di confermaSì, quando accetti il candidato: «un amministratore ha attivato il tuo account» (senza la password, che hai già comunicato tu)Sì, quando accetti la richiesta: «la tua richiesta è stata accettata» (senza la password, che ha scelto la persona)
    DettagliSezioni «Il file Excel» e «I candidati: accetta o rifiuta»Sezione «Richieste di accesso dalla pagina pubblica»
    🔗 Indirizzo della pagina di richiesta accesso Nella pagina Amministrazione, sezione Crea nuovo utente, il bottone Copia link copia quello dell'ambiente in cui stai lavorando. Gli utenti di test e di produzione sono separati: una richiesta fatta su un indirizzo arriva solo ai candidati di quella versione.

    In alternativa a entrambe, per un utente alla volta c'è il modulo Crea nuovo utente (username, password, nome, email, ruolo, quote), che crea l'account subito, senza passare dai candidati.

    Il file Excel

    • Formato .xlsx (Cartella di lavoro di Excel). Il vecchio .xls e il .csv sono rifiutati con un messaggio che dice cosa fare.
    • Si legge il primo foglio. La prima riga deve avere tre intestazioni il cui nome contiene la parola nome, la parola email e la parola password: non serve una corrispondenza esatta, vanno bene «Nome e cognome», «Indirizzo e-mail», «Password iniziale». In qualunque ordine; maiuscole, minuscole, spazi, trattini e punti non contano (quindi «E-mail» e «e mail» valgono «email»). Non vanno bene: una colonna senza nessuna delle tre parole (per esempio «Note»), una che ne contiene più di una (per esempio «Nome ed email»), due colonne per la stessa parola (per esempio «Nome» e «Cognome», perché «cognome» contiene «nome»), né una parola mancante.
    • Poi un utente per riga, al massimo 200 righe per file; le righe del tutto vuote si saltano.
    • Le password vanno scritte come testo, di almeno 8 caratteri (al massimo 72). Se sono solo cifre, Excel le tratta come numeri e toglie gli zeri iniziali: formatta la colonna come testo. Gli spazi all'inizio e alla fine di ogni cella si ignorano.

    Se il formato non è questo, il file è rifiutato per intero con un messaggio che dice cosa non va (per esempio «mancano: Password» o «colonne non riconosciute: Note») e non viene inserito nulla. Se il formato è giusto ma alcune righe no, le righe buone entrano tra i candidati e quelle scartate sono elencate sotto i bottoni, con il numero di riga di Excel e il motivo: nome o email mancanti, email non valida o più lunga di 64 caratteri, password troppo corta o troppo lunga, email ripetuta nel file, email di un utente già esistente, email già tra i candidati.

    I candidati: accetta o rifiuta

    • Dopo il caricamento, sotto i bottoni compare l'esito. Il bottone Mostra candidati (N) apre — e poi richiude — la tabella dei candidati, che di default è chiusa. Tutto avviene nella sezione, senza finestre.
    • La tabella ha Nome, Email, Password e due pulsanti per riga. La password non è scritta nella tabella: il bottone 👁 Mostra la rivela (vedi «Vedere le password»).
    • Accetta utente crea l'account con username = email (in minuscolo; con quella e la password del file si fa il login), nome visualizzato = Nome, ruolo utente, stato abilitato, quota token = DEFAULT_QUOTA_TOKEN_TOTALE e quota budget = DEFAULT_QUOTA_BUDGET_TOTALE (di config-work.php; 0 = illimitato se non definite). Il candidato esce dall'elenco e l'utente compare subito nella tabella «Utenti» sotto.
    • Con Accetta utente parte anche una email di conferma all'interessato, qualunque sia l'origine (file Excel o modulo online), subito dopo la creazione dell'account; in fondo c'è sempre il link alla pagina di registrazione da usare se la password si dimentica. Per le candidature da Excel il testo dice che un amministratore ha attivato l'account, che l'username è l'email e che la password è quella comunicata dall'amministratore (non c'è mai la password nel messaggio, e non si parla di «richiesta»: la persona non ne ha fatta una). L'oggetto è «ANGST: il tuo account è stato attivato». Se l'invio non riesce l'account esiste lo stesso e il messaggio sotto i bottoni dice perché: avvisa tu la persona. Caricare il file e rifiutare non spediscono nulla.
    • Rifiuta utente toglie la candidatura dall'elenco e non crea nulla (e non invia email).
    • I candidati restano nell'elenco finché non vengono accettati o rifiutati, anche dopo aver chiuso la pagina, e sono visibili a tutti gli amministratori. Se nel frattempo un'altra persona ha già creato un utente con la stessa email, «Accetta» lo segnala e la candidatura resta da rifiutare.
    ℹ️ Dettagli tecnici. Il file è letto sul server (api/ExcelLettore.php, senza librerie esterne: un .xlsx è uno ZIP di file XML), controllato (api/CandidatiUtenti.php) e inserito nella tabella utenti_candidati, che il codice crea da solo alla prima volta (db/migrate_utenti_candidati.sql per farlo a mano). Un username uguale all'email compare una sola volta nelle etichette delle cartelle dei report e dei log («mario@x.it», non «mario@x.it-mario@x.it»).

    Lista utenti: menu «Azioni»

    Ogni riga della lista Utenti ha un solo bottone Azioni ▾, che apre un menu con: Modifica, Disabilita / Abilita (a seconda dello stato), Ricarica (aggiunge quota), Azzera consumo, Storico ed Elimina (in rosso, in fondo). Le azioni sono le stesse di prima, con le stesse conferme. Il menu si chiude con Esc, cliccando fuori, scorrendo la pagina o scegliendo una voce; con la tastiera si naviga con le frecce (↑ ↓, Home, Fine). Si apre sotto il bottone, o sopra se in basso non c'è spazio.

    Vedere le password di utenti e candidati

    Nella lista Utenti e nella tabella dei candidati c'è la colonna Password con il bottone 👁 Mostra: mostra la password di quella riga, con Copia e Nascondi; si nasconde da sola dopo 30 secondi. La password non è mai nell'elenco: viene chiesta al server solo quando clicchi, e ogni consultazione è scritta nel tuo file di log («password consultata», senza la password).

    • Come sono conservate: l'hash (password_hash) resta l'unica cosa su cui si verifica l'accesso. In più, ogni volta che una password viene impostata (nuovo utente, modifica da «Modifica», file Excel, modulo di richiesta accesso, cambio dalla pagina pubblica) se ne salva una copia cifrata nella colonna password_cifrata (utenti e utenti_candidati), con XSalsa20-Poly1305 e una chiave del server. Chi legge solo il database non vede le password; chi ha database e chiave le legge tutte.
    • La chiave è la costante PASSWORD_CHIAVE di config-work.php (una frase lunga e casuale); se manca, al primo uso si crea storage/password_chiave.key.php (non servibile dal web). Metti la chiave nel backup, separata da quello del database. Se la perdi, le copie cifrate diventano illeggibili ma gli accessi continuano a funzionare: basta reimpostare le password.
    • Password impostate prima di questa funzione: non esistono in forma leggibile e non si possono ricostruire dall'hash. Il bottone risponde «non disponibile» finché l'utente non la cambia o tu non la reimposti da «Modifica».
    • Chi può vederle: ogni amministratore, per utenti e candidati. La password di un altro amministratore la vede solo l'utenza «admin»; ognuno vede la propria.
    • Le copie si aggiornano a ogni cambio. Quando un candidato viene accettato la copia passa all'utente creato. Il database si aggiorna da solo (ALTER TABLE al primo uso); in alternativa db/migrate_password_cifrata.sql.

    Richieste di accesso dalla pagina pubblica

    Chi vuole un account non deve passare da te per ogni dettaglio: la pagina di richiesta accesso è registrazione.html, all'indirizzo https://test.angst.geopolitical-evidence.com/registrazione.html per la versione di test e https://angst.geopolitical-evidence.com/registrazione.html per la versione in produzione. Nella sezione Crea nuovo utente trovi il link alla pagina con il bottone Copia link, che lo copia negli appunti. Mandalo a chi deve registrarsi (il link è quello dell'ambiente in cui stai lavorando).

    • La pagina ha il titolo «Modulo di richiesta accesso alla applicazione ANalisi Geopolitica STrutturale (ANGST)» e chiede Nome, Email/Username e Password (almeno 8 caratteri); sotto il campo una nota avvisa che la username per entrare in ANGST sarà la email (anche nel login il campo si chiama «Email/Username»). Controlla i campi nel browser e di nuovo sul server: nome presente, email valida (al massimo 64 caratteri e dominio esistente, per intercettare errori come «@gmial.co»), password da 8 a 72 caratteri.
    • Una richiesta valida non crea un utente: entra tra i candidati («Mostra candidati»), con la colonna Origine = «Richiesta online», in attesa che tu la accetti o la rifiuti. La password è conservata cifrata (la vedi con «Mostra»).
    • Quando accetti la richiesta nasce l'utente (username = email, ruolo utente, abilitato, quote di default) e all'interessato parte una email di conferma con il link per entrare. L'email non contiene la password, ma ha in fondo il link alla pagina di registrazione (registrazione.html#password, che apre direttamente il modulo «Cambia o recupera la password») da usare se la password si dimentica. Se non parte, l'utente c'è lo stesso e il messaggio sotto i bottoni lo dice con il motivo: avvisalo tu. L'email parte anche per le candidature da file Excel, con un testo diverso (vedi «I candidati: accetta o rifiuta»).
    • Se l'email è già tra i candidati in attesa o è già un utente, la richiesta non viene inserita e sotto il campo email compare il messaggio «Attenzione! L'utente ha già inviato una richiesta. Questa email è già stata utilizzata.». Per questo la pagina permette di sapere se un indirizzo è già registrato: il tetto di 6 tentativi all'ora per IP limita chi volesse provare molti indirizzi.
    • Difese (la pagina è pubblica): campo trappola per i robot, al massimo 6 tentativi all'ora per IP e 60 all'ora in tutto, al massimo 500 richieste online in attesa. Oltre, l'utente vede «Troppi tentativi» o «non possiamo accettare nuove richieste». Il vecchio modulo di registrazione (che creava un utente disabilitato) non esiste più.

    Limite ai tentativi di login sbagliati

    Il login conta i tentativi falliti (username o password errati) in una finestra scorrevole di 15 minuti (api/LimiteLogin.php). Raggiunto il tetto risponde «Troppi tentativi di accesso. Riprova tra N minuti.» (HTTP 429) anche con la password giusta, finché il tentativo più vecchio non esce dalla finestra; durante il blocco i nuovi tentativi non lo allungano.

    ChiaveUtentiAmministratori
    Per username (scritto nel login, maiuscole ignorate, anche se non esiste)LOGIN_TENTATIVI_MAX = 10LOGIN_TENTATIVI_MAX_ADMIN = 20
    Per IP di chi scrive (su qualunque username)LOGIN_TENTATIVI_MAX_IP = 20LOGIN_TENTATIVI_MAX_IP_ADMIN = 60 (quando l'username è quello di un amministratore)
    • Un login riuscito azzera il contatore di quell'username (non quello dell'IP). Un account disabilitato con la password giusta non conta come errore.
    • Il tetto più alto per gli amministratori esiste perché il blocco per username permette a chiunque di bloccare l'account altrui sbagliando apposta la password: l'amministratore non deve poter essere messo fuori in pochi secondi. Resta un tetto (20 in 15 minuti, circa 80 all'ora). Chi supera i 10 tentativi su un username scopre, dal fatto di non essere bloccato, che è un amministratore: è un'informazione piccola, ma esiste.
    • Sblocco: il blocco passa da solo allo scadere della finestra (al massimo 15 minuti). Se un utente non può aspettare, vedi «Sbloccare tutti subito» qui sotto.
    • Impostazioni in config-work.php: LOGIN_LIMITE_ABILITATO (false = nessun limite), LOGIN_FINESTRA_MINUTI e le quattro soglie sopra. Il file dei contatori (storage/limite_login.json) contiene solo hash di username e IP. Se non è scrivibile non si blocca nessuno.
    • È un limite sul login dell'applicazione: non sostituisce eventuali protezioni del server o del reverse proxy.

    Sbloccare tutti subito: cancellare storage/limite_login.json

    Tutti i contatori (utenti e IP) stanno in un unico file, storage/limite_login.json. Cancellandolo si sbloccano tutti in un colpo: al tentativo successivo i contatori ripartono da zero e il file viene ricreato da solo alla prima password sbagliata. Non serve riavviare nulla e non si perde nessun dato (il file contiene solo hash di username e IP e i loro orari). Da riga di comando, sul server:

    docker exec angst-php rm -f /var/www/html/storage/limite_login.json        # produzione
    docker exec angst-test-php rm -f /var/www/html/storage/limite_login.json   # test
    • Non esiste uno sblocco per un solo utente: il file non conserva gli username in chiaro (solo hash), quindi si azzerano tutti i contatori insieme. Chi è già a metà dei tentativi riparte da zero.
    • Se l'utente bloccato è un amministratore, il tetto è più alto (20) ma il blocco funziona allo stesso modo: stessa procedura.
    • Per sbloccare e evitare che succeda di nuovo basta alzare le soglie in config-work.php (LOGIN_TENTATIVI_MAX e le altre) o impostare LOGIN_LIMITE_ABILITATO a false: la modifica vale dalla richiesta successiva.
    • Dopo lo sblocco, ricorda all'utente che se non ricorda la password può usare «Ho dimenticato la password» nella pagina di richiesta accesso: gli arriva una password nuova per email.

    Cambio password dalla pagina di richiesta accesso

    La stessa pagina (registrazione.html, link «Hai già una richiesta o un account? Cambia o recupera la password», con sotto la nota «Cliccando su questo link si apre un modulo per cambiare la password o, se l'hai dimenticata, per recuperarla», oppure registrazione.html#password; il modulo che si apre si intitola «Cambia o recupera la password») permette di cambiare la password, sia a chi è ancora tra i candidati sia a chi è già utente. La nuova password viene inviata automaticamente per email all'interessato (servizio api/password_accesso.php) e la pagina mostra «La password corrente ti è stata inviata via email. Controlla anche la casella Spam o posta indesiderata».

    • Cambia password: servono email, password corrente e nuova password (da 8 a 72 caratteri, diversa dalla corrente). Senza la password corrente non si cambia nulla: conoscere un indirizzo email non basta per prendere un account. Se la password è giusta ma l'email non parte, la password risulta cambiata e la pagina lo dice.
    • Ho dimenticato la password: basta l'email. L'hash non si può invertire e per le password impostate prima della copia cifrata (vedi «Vedere le password») non c'è nulla da rileggere, quindi il sistema ne genera una nuova (12 caratteri), sostituisce la precedente e la invia all'indirizzo dell'account. Se l'invio fallisce, la password precedente viene ripristinata. Non vale per gli amministratori (la password di un admin la reimposta un altro admin da «Modifica utente»). La risposta è sempre la stessa, per qualunque indirizzo: «Se l'indirizzo corrisponde a un account, la password ti è stata inviata via email. Controlla anche la casella Spam o posta indesiderata. Le password degli account amministratore non si reimpostano da qui.» Non dice se l'indirizzo esiste, se è un amministratore o se l'invio è riuscito (prima rispondeva «nessun account», «non può essere reimpostata da qui» o un errore di invio, e chiunque poteva così scoprire chi ha un account e chi è admin); gli esiti veri stanno nel log degli errori. Con «Cambia password» un indirizzo sconosciuto riceve lo stesso errore di una password sbagliata («La password corrente non è corretta»).
    • La password compare solo in queste email, mai in quella di conferma accesso. Il link nell'email è sempre quello di APP_URL (config-work.php): non viene ricavato dalla richiesta, per non mettere nell'email di un altro un indirizzo falsificato.
    • Difese: campo trappola, al massimo 5 tentativi all'ora per indirizzo email (anche con la password giusta, finché dura il blocco), 15 per IP e 120 in tutto. Con «Ho dimenticato la password» chiunque può far reimpostare l'account di un altro (il nuovo accesso arriva solo alla casella dell'interessato), ma al massimo 5 volte all'ora per indirizzo.
    • Funziona solo se la posta in uscita è configurata (sezione seguente): se non lo è, «Ho dimenticato la password» risponde che non è stato possibile inviare l'email e non modifica nulla.

    Posta in uscita: configurazione e come non finire in spam

    L'email di conferma parte dal server SMTP del provider della casella, non dal server di ANGST, e si configura in config-work.php (per ambiente, fuori dal repository). Finché non è configurata l'email non parte e l'accettazione lo segnala.

    define('MAIL_ABILITATO', true);
    define('SMTP_HOST', 'ssl0.ovh.net');           // server SMTP di OVH per le caselle del dominio
    define('SMTP_PORTA', 465);                     // 465 = TLS diretto, 587 = STARTTLS
    define('SMTP_SICUREZZA', 'ssl');               // 'ssl' | 'tls' (STARTTLS)
    define('SMTP_UTENTE', 'noreply@geopolitical-evidence.com');    // indirizzo completo della casella
    define('SMTP_PASSWORD', '…');
    define('MAIL_MITTENTE', 'noreply@geopolitical-evidence.com');  // lo stesso indirizzo (o un alias della casella)
    define('MAIL_NOME_MITTENTE', 'ANGST');         // facoltativo
    define('MAIL_RISPONDI_A', 'indirizzo@…');      // facoltativo: dove arrivano le risposte
    define('APP_URL', 'https://angst.geopolitical-evidence.com');  // facoltativo: base del link nell'email
    ⚠️ Perché non basta «spedire dal server». Verificato il 2026-10-26 su geopolitical-evidence.com: il DNS ha SPF = v=spf1 include:mx.ovh.com -all, cioè solo i server di OVH possono spedire per il dominio e tutto il resto è respinto («-all»). Un messaggio spedito direttamente da questo server (IP 57.128.209.130, reverse DNS vps-….vps.ovh.net) fallirebbe l'SPF e finirebbe in spam o verrebbe rifiutato. Per questo l'invio passa dal server SMTP di OVH con una casella del dominio: SPF risulta allineato. Le porte SMTP in uscita del server sono aperte (25, 465, 587), quindi tecnicamente si può.
    ControlloStato oggiCosa fare
    SPFpresente, autorizza OVHNiente: basta spedire dal server SMTP di OVH.
    DKIM (firma del messaggio)attivo: selettori ovhmo-selector-1 e ovhmo-selector-2 (due CNAME verso *.dkim.mail.ovh.net); in Gmail, «Mostra originale» dà DKIM: PASS (verificato il 2026-11-07)Niente. Se la diagnosi non lo trovasse, non vuol dire che manchi: il selettore vero si legge in «Mostra originale» di un'email ricevuta (intestazione DKIM-Signature, campo s=) e si prova con --selettori=nome, oppure si imposta MAIL_DKIM_SELETTORI in config-work.php. Se invece Gmail dicesse DKIM: NONE, attivalo nel pannello OVH (sezione «DKIM»).
    DMARCpresente: v=DMARC1; p=none; (solo osservazione, senza indirizzo per i rapporti)Più avanti: aggiungere rua=mailto:postmaster@geopolitical-evidence.com per ricevere i rapporti e, dopo qualche settimana di invii puliti, valutare p=quarantine. Gmail e Yahoo chiedono un DMARC a chi spedisce.
    MX / casellaMX di OVH presentiServe una casella vera del dominio (es. noreply@…) per autenticarsi: la password SMTP è quella della casella.
    Reverse DNSgenerico di OVHIrrilevante se si spedisce dal relay di OVH (conta solo per l'invio diretto).

    Il messaggio è composto per non sembrare spam: mittente sul dominio autenticato, testo e HTML insieme, oggetto sobrio, intestazioni complete (Date, Message-ID sul dominio, MIME), due soli link, entrambi all'applicazione (la pagina di accesso e la pagina di registrazione per la password dimenticata), nessun allegato né immagine di tracciamento, nessuna password (nell'email di conferma accesso: nell'email del cambio password invece compare, e per questo è un po' più esposta ai filtri antispam; la pagina avvisa di guardare anche nella posta indesiderata). Restano fuori dal nostro controllo la reputazione del dominio e il filtro del destinatario: conviene provare l'invio a una casella Gmail, una Outlook e una aziendale.

    Strumento di diagnosi e prova

    docker exec -u www-data angst-test-php php tools/prova_email.php                       # diagnosi: configurazione, SPF/DKIM/DMARC/MX e collegamento al server SMTP (non invia nulla)
    docker exec -u www-data angst-test-php php tools/prova_email.php --invia=indirizzo@esempio.it  # invia davvero l'email di conferma di prova
    docker exec -u www-data angst-test-php php tools/prova_email.php --selettori=nome1,nome2   # prova altri selettori DKIM (predefiniti: quelli di OVH e alcuni comuni)

    La diagnosi prova anche il collegamento al server SMTP con utente e password, senza inviare. Dopo l'invio di prova, in Gmail apri «Mostra originale»: devono comparire SPF: PASS, DKIM: PASS e DMARC: PASS.

    🔑 Pagina di registrazione e cambio password

    La pagina pubblica di richiesta accesso (registrazione.html) è il canale con cui le persone chiedono un account e, nella stessa pagina, cambiano o recuperano la password. È una sintesi per chi la deve spiegare o fornire agli utenti: i dettagli (candidati, file Excel, difese, email) sono nella sezione Utenti: registrazione di nuovi utenti.

    🔗 Indirizzi da dare agli utenti Nella pagina Amministrazione, sezione Crea nuovo utente, il bottone Copia link copia il link dell'ambiente in cui stai lavorando. Gli utenti di test e di produzione sono separati.

    Come funziona la pagina di registrazione

    1. L'utente apre la pagina e compila Nome, Email/Username (sarà la username per entrare) e Password (da 8 a 72 caratteri), poi clicca Invia. I campi sono controllati nel browser e di nuovo sul server (email valida e con dominio esistente, al massimo 64 caratteri).
    2. La richiesta non crea un utente: entra tra i candidati con Origine «Richiesta online».
    3. Con Accetta utente nasce l'account (username = email, ruolo utente, abilitato, quote di default) e all'interessato parte l'email di conferma con il link per entrare. Con Rifiuta la richiesta viene scartata.
    4. Se l'email è già tra i candidati in attesa o è già un utente, la richiesta non viene inserita e la pagina avvisa che l'email è già stata utilizzata.

    La pagina è pubblica, quindi ha delle difese: campo trappola per i robot, al massimo 6 tentativi all'ora per IP e 60 in tutto, al massimo 500 richieste in attesa.

    Come si cambia la password

    Dalla stessa pagina, con il link «Hai già una richiesta o un account? Cambia o recupera la password» (o registrazione.html#password), si apre il modulo «Cambia o recupera la password». Vale sia per i candidati sia per gli utenti già attivi. Il servizio è api/password_accesso.php.

    AzioneChe cosa serveChe cosa succede
    Cambia passwordEmail, password corrente, nuova password (8–72 caratteri, diversa dalla corrente)La password cambia e la nuova viene inviata per email all'interessato. Se la password corrente è giusta ma l'email non parte, la password risulta cambiata e la pagina lo dice.
    Ho dimenticato la passwordSolo l'emailSe l'indirizzo ha un account (non amministratore), il sistema genera una password nuova (12 caratteri), sostituisce la precedente e la invia all'indirizzo dell'account. Se l'invio fallisce, la precedente viene ripristinata. La pagina mostra sempre lo stesso messaggio, anche se l'indirizzo non esiste.
    • Amministratori: «Ho dimenticato la password» non vale per loro (e la pagina non lo dice a chi prova: risponde come per tutti); la password di un admin la reimposta un altro admin da Modifica utente.
    • Per cambiare la password di un utente senza passare dalla pagina pubblica puoi usare Modifica in Amministrazione (vedi Utenti).
    • La password compare solo in queste email, mai in quella di conferma accesso. Il link nell'email è sempre quello di APP_URL (config-work.php).
    • Difese: al massimo 5 tentativi all'ora per indirizzo email, 15 per IP e 120 in tutto. Se un utente è bloccato dal login sbagliato, vedi «Sbloccare tutti subito» nella sezione Utenti.

    🔍 Debug fasi: richiesta e risposta Gemini

    Ogni chiamata reale a Gemini — la richiesta esatta inviata e la risposta grezza ricevuta, prima della validazione — viene salvata per consultazione, solo per le ultime 3 analisi eseguite (rotazione automatica delle più vecchie). Serve a capire esattamente cosa è stato chiesto al modello e cosa ha risposto, fase per fase, senza dover rileggere il codice.

    ℹ️ Riservato agli amministratori. La pagina non compare nel menu utente: si apre dal pannello Amministrazione → pulsante Debug fasi (Gemini), oppure direttamente su debug-fasi.html.

    Come funziona

    1. Seleziona un'analisi dall'elenco — tema, utente, data dell'ultimo aggiornamento e quante fasi hanno registrato almeno una chiamata
    2. Seleziona una fase per aprire il dettaglio
    3. Una fase può contenere più "chiamate" reali distinte: un retry dopo un errore di validazione, le due passate del grounding (ricerca + strutturazione, solo con RICERCA_PASSATA_ANALISI = true), oppure un tentativo di ricerca approfondita per colmare una lacuna — ciascuna mostrata separatamente, con la propria etichetta

    Cosa mostra ogni chiamata

    • Richiesta: il payload esatto inviato a Gemini — system_instruction (comprese le conoscenze di fase), il prompt, lo schema JSON richiesto, temperatura e seed effettivamente usati per quel tentativo
    • Risposta: il testo grezzo ricevuto — se è JSON valido viene mostrato come albero navigabile, altrimenti come testo libero (es. la prosa della passata di ricerca del grounding, solo con RICERCA_PASSATA_ANALISI = true)
    • Token consumati da quella specifica chiamata

    Leggibilità e ricerca

    Il contenuto non è una stringa di testo grezza: è un albero JSON collassabile, con chiavi e valori colorati. Le stringhe lunghe o multi-riga (un prompt intero, una risposta lunga) vengono mostrate in un blocco di testo a parte, con gli a-capo reali — non come un'unica riga con \n letterali.

    La casella di ricerca in alto cerca il testo sia nelle chiavi sia nei valori, evidenzia tutte le occorrenze, espande automaticamente le sezioni compresse che le contengono, e permette di saltare da un risultato al successivo (pulsanti ↑/↓, o Invio). "Espandi tutto"/"Comprimi tutto" e "Copia JSON" completano la pagina.

    ✓ Nessun costo aggiuntivo. I dati vengono scritti su file dopo che Gemini ha già risposto: consultare questa pagina non genera nessuna chiamata al modello né consuma token.

    Dove vengono archiviati

    In storage/debug_gemini/<id analisi>/<fase>.json sul server, con la stessa protezione delle altre cartelle di log (non raggiungibile via URL diretto). Disattivabile del tutto con DEBUG_FASI_ABILITATO = false in config-work.php; il numero di analisi conservate si regola con DEBUG_FASI_MAX_ANALISI (default 3).

    📄 File di log: consultazione e gestione

    ANGST scrive alcuni file di log sul server per ricostruire cosa è successo durante le analisi e perché una fase si è comportata in un certo modo. Si consultano ed eliminano dal pannello Amministrazione → card File di log, senza accedere al server.

    I file sono organizzati in cartelle, come in Esplora risorse: una per ogni utente, con il nome nome_utente-email e, a destra, il numero di file; in più Sistema (error.log) e Storico (i file scritti prima dell'attuale organizzazione). Un clic sulla cartella la apre sul posto, sotto il suo nome, con l'elenco dei file (tipo, data, ora, analisi, tema, dimensione, ultima modifica) e le azioni di sempre: visualizza testo, visualizza HTML, scarica HTML, elimina; un secondo clic la richiude. Più cartelle possono restare aperte insieme, e restano aperte dopo «Aggiorna elenco» o dopo un'eliminazione. Quando si elimina l'ultimo file di un utente, la sua cartella sparisce.

    ℹ️ Riservato agli amministratori. I log contengono il testo dei temi analizzati e le motivazioni del modello: hanno la stessa sensibilità dei dati utente. Non sono raggiungibili via URL (la cartella è protetta con .htaccess), solo da questa card. Gli orari sono nel fuso Europe/Rome. Scrivere o leggere i log non consuma token e non genera chiamate al modello.

    Un file per analisi: il nome dice chi, quando e quale analisi

    Ogni file di log è associato a una sola analisi, fatta da un utente a una certa ora. Il nome ha il formato:

    <utente>_<AAAA-MM-GG>_<HH-MM-SS>_<idAnalisi>.log
    es. admin_2026-10-05_15-06-37_00d9962572c8de18.log
    • Data e ora sono quelle del primo evento registrato per quell'analisi (di norma il primo messaggio dell'utente), nel fuso Europe/Rome. Il file è lo stesso per tutta l'analisi, anche se supera la mezzanotte o riprende dopo una pausa: il file si ritrova dall'id.
    • L'id dell'analisi è lo stesso che compare nella pagina Debug fasi e nei report: permette di collegare il log alle richieste a Gemini della stessa analisi. Una nuova analisi (nuovo tema, /abbandona, /riformula) apre un nuovo file.
    • Un solo file per i tre tipi di evento: narrativa delle fasi, ricerche web del grounding e motivi di riformulazione/validatori finiscono nello stesso file, nell'ordine in cui sono avvenuti. Per confrontare più analisi si può usare grep -r sulla cartella storage/log/ del server.

    I file e cosa contengono

    FileContenutoInterruttore in config-work.php
    <utente>_<data>_<ora>_<idAnalisi>.log Un file per analisi. Righe di narrativa: fase completata (con lacune dichiarate e stato di ricerca approfondita e grounding), tentativo di ricerca approfondita, fase fallita dopo i tentativi previsti, comandi slash, errori. Se sono attivi gli altri due interruttori, anche le righe del grounding ([fase] utente=… {query, url}: query lanciate e URL trovati, già risolti alla pagina finale) e i blocchi dei motivi (sotto). Se non ci sono righe di grounding per un'analisi, il modello non ha cercato davvero sul web — vedi anche Fonti e bibliografia. LOG_ANALISI_ABILITATO (narrativa, acceso di default), LOG_GROUNDING_ABILITATO, LOG_MOTIVI_ABILITATO
    <utente>_<data>_fuori-analisi.log Eventi di un utente che non appartengono a nessuna analisi in corso (per esempio un errore fuori da una pipeline). Uno per utente al giorno. come sopra
    <utente>_<data>_<ora>_scenari-<id>.log Il costruttore di scenari del Wargame non ha un'analisi dell'utente: scrive a nome dell'amministratore che lo usa, con l'etichetta scenari-<id> al posto dell'id analisi. L'id resta lo stesso per tutta una generazione (i passi HTTP successivi scrivono nello stesso file). come sopra
    error.log Errori applicativi ed eccezioni non gestite, con file, riga e stack trace. Compare solo se si è verificato almeno un errore; lo scrive il sistema direttamente, indipendentemente dagli altri interruttori. È globale (gli errori possono avvenire prima del login); quando l'utente è noto lo stesso errore compare anche nel log della sua analisi. — (sempre attivo)
    storico: <utente>.log, grounding.log, motivi_fasi.log I file del formato precedente (un file per utente con tutte le analisi mescolate; grounding e motivi in due file globali). Non vengono più scritti; restano leggibili ed eliminabili, marcati «storico» nell'elenco. Non possono essere spezzati per analisi: le loro righe non contengono l'id. —

    Se un interruttore manca da config-work.php, LOG_ANALISI_ABILITATO resta acceso (è il comportamento storico), mentre LOG_GROUNDING_ABILITATO e LOG_MOTIVI_ABILITATO restano spenti (sono diagnostica aggiunta dopo).

    I motivi nel log dell'analisi

    Sono le voci da cercare quando ci si chiede "perché ha riformulato il mio tema?" oppure "perché la fase non è passata?". Stanno nel file dell'analisi (prima erano in motivi_fasi.log). Ogni voce è un blocco su più righe, separato dal successivo da ---; la prima riga si può cercare con un semplice filtro di testo:

    [2026-10-02 15:22:28] [P08] evento=validatore_fallito utente=admin analisi=a1b2c3d4e5f60718
        tentativo: 1/2 (offset seed: 0)
        1. Nessun attore con ruolo non polarizzato: includere almeno un mediatore, ...
           regola: 04-attori.md §4 Punto 23 — Peso degli attori ...
    EventoQuando compare
    riformulazione_propostaP01 ha giudicato il tema riformulabile: riporta tema, motivazione, la riformulazione proposta e le regole di ammissibilità applicate.
    tema_respintoP01 ha respinto il tema (con l'eventuale disciplina alternativa suggerita).
    riformula_da_utenteL'utente ha usato /riformula: riporta tema e esito precedenti, la proposta del sistema, il nuovo tema indicato e se coincide con la proposta.
    validatore_fallitoUn tentativo di una fase è stato scartato da un validatore. Una voce per ogni tentativo, anche se un retry poi riesce, con ogni violazione numerata e la regola .md violata.
    validatori_superatiLa fase è passata, ma solo dopo almeno un tentativo non riuscito (i motivi sono nelle voci precedenti della stessa fase).
    fase_fallitaTutti i tentativi sono esauriti e la fase non è avanzata.
    json_non_conforme / errore_tecnicoRisposta del modello troncata o non conforme allo schema, oppure errore di rete/HTTP. Non è la violazione di una regola metodologica: il log lo dichiara esplicitamente ("regola: nessuna").

    Come leggere le regole citate

    Per i temi riformulati o respinti le regole compaiono su due livelli distinti, perché hanno affidabilità diversa:

    • Regole applicate (dedotte dai campi strutturali dell'output): ricavate in modo deterministico da campi che il modello ha compilato — per esempio la categoria di tema non adatto corrisponde a una sezione precisa di 00-ammissibilita.md (§2a–§2e). Sono un dato certo.
    • Regole dichiarate dal modello: le cita il modello stesso nel campo regole_applicate di P01. È un'auto-dichiarazione, non verificabile: può essere una spiegazione costruita a posteriori. Utile come indizio, da non trattare come prova di quale regola abbia davvero guidato la decisione. Se il modello non la compila, il log lo dice.

    Per i validatori la regola citata è quella che il controllo fa rispettare (e che il modello ha violato), non una regola "seguita": è l'unica informazione certa disponibile. Alcuni controlli vivono solo nel prompt o nello schema della fase e non hanno un riferimento in un file .md: il log lo scrive apertamente invece di inventare una citazione.

    Consultare ed eliminare

    1. La tabella elenca, per ogni file, utente, tipo, data, ora e id dell'analisi (ricavati dal nome — tipo è una delle quattro etichette della riga sopra: Analisi, Fuori analisi, Sistema, Storico), il tema dell'analisi, dimensione e ultima modifica. Il tema è letto dalla tabella analisi del database (stesso meccanismo di Debug fasi): compare solo per i log di tipo Analisi, ed è un trattino se l'analisi è già stata ripulita dal database o il log non è associato a nessuna (Fuori analisi, Sistema, Storico). L'ordine è: error.log, poi i file per utente dal più recente, poi lo storico. Il menu Utente filtra l'elenco; Aggiorna elenco lo ricarica.
    2. Visualizza apre il contenuto in una finestra. Se il file supera 500 KB vengono mostrate solo le righe finali (con una nota che lo segnala): per leggerlo per intero serve l'accesso al server. «Visualizza HTML» e «Scarica HTML» mostrano la versione formattata, con i blocchi dei motivi resi come voci a sé.
    3. Elimina chiede conferma e cancella il file in modo irreversibile — non c'è cestino. Un log di analisi si ricrea solo se l'analisi continua a scrivere; per un'analisi conclusa il file eliminato non torna.

    Chi vede l'elenco. Solo gli amministratori: l'elenco, la lettura e l'eliminazione passano da un unico endpoint (api/admin_utenti.php) che risponde 403 a chiunque non lo sia. Gli utenti normali non hanno nessun accesso ai log, nemmeno ai propri.

    ⚠️ Nessuna rotazione automatica. I log crescono finché non vengono eliminati, e con un file per analisi il numero di file cresce a ogni analisi. Conviene eliminare periodicamente quelli delle analisi vecchie o di prova (le cartelle per utente e la data nel nome aiutano). Per conservarli prima di eliminarli, l'archivio completo della Backup Console include già la cartella storage/ (quindi anche i log).
    💡 Un log non compare o non si aggiorna? Controlla prima l'interruttore corrispondente in config-work.php, poi i permessi della cartella storage/log/: deve essere scrivibile dall'utente con cui gira il server web, altrimenti la scrittura fallisce in silenzio (i log non devono mai bloccare un'analisi).

    Non confondere con "Debug fasi"

    I log qui descritti raccontano cosa è successo e perché. Per vedere invece la richiesta esatta inviata a Gemini e la risposta grezza ricevuta, fase per fase, c'è la pagina dedicata: Debug fasi: richiesta e risposta Gemini. Per collegare le due viste, la pagina Debug fasi elenca le analisi per tema, utente e data: usa l'utente= e l'orario di una voce del log dei motivi per ritrovare la stessa analisi lì.

    ⚙️ Configurazione: le costanti di config-work.php

    Il comportamento dell'applicazione si regola in config-work.php, alla radice del progetto. Il file non è nel repository (è in .gitignore): ogni ambiente — produzione e test — ha il proprio, quindi un valore cambiato in uno non vale nell'altro. Le credenziali (database, chiave Gemini, accesso a EIL) e i percorsi non sono elencati qui. Le costanti segnate «opzionale» valgono il default indicato se la riga manca. Dopo aver modificato il file non serve riavviare nulla: le modifiche valgono dalle richieste successive (la cache di PHP le rileva entro un paio di secondi).

    ℹ️ Che valori mostra la tabella. La colonna «valore» riporta quello impostato nei config-work.php di test e produzione (il 15 novembre 2026 hanno gli stessi valori) e, dove la costante nel file non c'è, il default del codice. Quando il valore nel file è diverso dal default del codice, la colonna riporta anche quest'ultimo («default del codice: …»): è quello che vale se un giorno la riga viene tolta. Un ambiente può avere valori diversi dall'altro: controlla sempre il file dell'ambiente su cui lavori.

    Modello e comportamento delle fasi

    CostanteValoreEffetto
    GEMINI_MODELgemini-3.1-flash-liteModello usato per tutte le fasi (nel file c'è, commentato, gemini-3.1-pro-preview). Il listino dei costi si aggiorna a parte, da Token e costi
    GEMINI_TIMEOUT_SECONDS300Attesa massima per una singola chiamata a Gemini
    MAX_RETRY_PER_FASE2Tentativi per fase quando un validatore respinge l'output; ogni tentativo usa un seed diverso. P08 ne chiede tre per conto suo (AbstractPhase::maxTentativi())
    MAX_RICLASSIFICAZIONI1Quante volte per analisi l'utente può imporre /riclassifica
    GEMINI_TEMPERATURE_P01_P040.2Temperatura di P01 e P04, le due fasi che decidono il ramo; tutte le altre usano 0.4. Opzionale. Più bassa = classificazioni più stabili sui temi borderline
    GEMINI_SEED_ABILITATO, GEMINI_SEEDtrue, 42Seed fisso per il primo tentativo di ogni fase (riduce la variabilità, non la azzera). Ogni nuovo tentativo aggiunge un offset, anche tra una richiesta e la successiva, perché un seed identico riproduceva lo stesso guasto. Opzionali
    GEMINI_LIMITI_CAMPO_ABILITATOtrueApplica i maxLength dei campi di testo di P06-P09 (500 / 1200 / 300 caratteri, vedi schemas/p0[6-9]*.json). false = schemi senza limiti. Opzionale. Gemini non applica il tetto in modo rigido (vedi la diagnosi del ciclo di P08 nelle FAQ); nelle analisi salvate controllate il valore più lungo arriva a circa l'83% del limite
    RICERCA_APPROFONDITA_ABILITATAtrueInterruttore generale della «Ricerca approfondita»: se false lo switch sparisce dall'interfaccia e il server ignora la richiesta
    RICERCA_APPROFONDITA_DEFAULTtrueValore con cui lo switch «Ricerca approfondita» parte a ogni nuova analisi e a ogni apertura della pagina (true = attivo, false = spento). Gli utenti possono cambiarlo dallo switch prima del primo messaggio; la scelta vale solo per quell'analisi e non viene ricordata. Senza effetto se RICERCA_APPROFONDITA_ABILITATA è false
    LOGIN_LIMITE_ABILITATO, LOGIN_FINESTRA_MINUTI, LOGIN_TENTATIVI_MAX, LOGIN_TENTATIVI_MAX_ADMIN, LOGIN_TENTATIVI_MAX_IP, LOGIN_TENTATIVI_MAX_IP_ADMINtrue, 15, 10, 20, 20, 60Limite ai tentativi di login sbagliati: finestra scorrevole in minuti e numero di errori consentiti per username e per IP, con tetti più alti per gli amministratori. Vedi «Limite ai tentativi di login sbagliati»; LOGIN_LIMITE_ABILITATO = false lo spegne
    PASSWORD_CHIAVE(assente)Chiave con cui si cifra la copia consultabile delle password (vedi «Vedere le password di utenti e candidati»). Una frase lunga e casuale; se manca si crea storage/password_chiave.key.php al primo uso. Conservala nel backup, separata dal database: senza, le copie cifrate non si leggono più (gli accessi funzionano comunque)
    LACUNE_MAX_RISOLTE_PER_FASE3Quante lacune la ricerca approfondita tenta di colmare in ogni fase
    LACUNE_MAX_RICERCHE_PER_ANALISI0 (default del codice: 3)Quante ricerche web sulle lacune si fanno al massimo in tutta un'analisi (ogni ricerca costa circa 3–5 richieste di grounding più i token); superato il tetto la ricerca approfondita non parte più per quell'analisi (compare nel log). 0 = nessuna ricerca sulle lacune: è il valore dei config-work.php di test e produzione, scelto perché le date che quella ricerca troverebbe non passano dai controlli sui fatti (fase 5); per riattivarla si imposta 3 (o un altro tetto). Con 0 l'interruttore «Ricerca approfondita» non colma le lacune e resta attivo solo per la ricerca dei fatti di riferimento. Non si azzera con /riclassifica
    FATTI_RIFERIMENTO_ABILITATItrue (default del codice: false)Fatti di riferimento (piano fatti/fonti, fase 1). true = dopo P02 e prima di P03 una ricerca web reale (5 ricerche circa, istruzione di sistema dedicata) raccoglie fatti ed eventi con data e fonte; una seconda chiamata li trascrive in JSON e il codice li controlla senza il modello: la data deve comparire alla lettera nel testo della ricerca, le fonti devono essere risultati reali, gli attori e le cifre devono comparire nel testo, i groundingSupports devono legare la fonte al segmento del fatto. I fatti che non superano i controlli restano nello stato (fatti_riferimento) ma non sono usati. Compaiono nella scheda di P03 (con avvisi se la ricerca non parte o i fatti sono pochi) e entrano nei prompt da P03 a P14 (fase 2): blocco «FATTI DI RIFERIMENTO» con il comando della fase e la regola «date e cifre solo dai fatti, dall'input dell'utente o dalla base di conoscenza» (non completare con date ricordate); i fatti «fonte unica» si citano «secondo [fonte]»; in P06, P07, P08, P09a/b/c, P11 e P12 il campo facoltativo fatti_usati elenca gli id dei fatti su cui poggia l'output (restano solo gli id esistenti: non prova che il fatto sia pertinente). Senza fatti i prompt restano identici a prima. Il report contiene il «Quadro dei fatti» (fase 3): tabella cronologica scritta dal codice (non dal modello) con data, evento, attori, numeri delle fonti nella bibliografia e corroborazione, la nota «non verificati manualmente», gli avvisi (ricerca non riuscita, fatti pochi, numero di date non tracciate) e l'esito della validazione dei richiami [Fn] che P13 scrive nel testo (ogni richiamo deve riferirsi a un fatto esistente e, se nella frase c'è una data, a una data compatibile con quella del fatto: l'id inesistente si toglie, l'id con data incoerente si corregge solo se un solo altro fatto corrisponde, altrimenti il richiamo si toglie; la prosa non viene mai riscritta). La bibliografia numera ogni fonte a parte (anche due pagine dello stesso dominio). Fonti web (fase 3b): quando c'è stata la ricerca dei fatti, le fonti web della bibliografia sono solo quelle trovate dalla ricerca (indirizzo e dominio reali) con i metadati letti dalla pagina e la classificazione indicativa del dominio (istituzionale, accademico, centro studi, agenzia di stampa, stampa, media di Stato, enciclopedia, altro; tabella modificabile nella pagina Amministrazione, «Classificazione dei domini delle fonti web»). Le voci «ricerca web attiva» scritte dalle fasi (autore, anno e URL a memoria) non entrano più in bibliografia (il quadro dei fatti dice quante sono state escluse); restano le fonti del metodo, dell'utente, di EIL e dei documenti allegati. Ogni voce dice se il link è raggiungibile, se l'autore o l'ente e l'anno vengono dalla pagina o mancano, e se il titolo della pagina combacia con quello del risultato di ricerca (quando il risultato ha solo il dominio il confronto non è possibile). Due pagine con lo stesso titolo su domini diversi (copie, aggregatori) contano come una fonte sola nella corroborazione. Limite: questi controlli provano che la fonte esiste e come si presenta, non che sostenga l'affermazione. Costo circa 0,076 $ in più per la ricerca (circa 10 secondi) e circa 0,02 $ per i fatti nei prompt (misurato su una analisi completa: 0,105 → 0,20 $ in tutto). Parte solo con «Ricerca approfondita» accesa, grounding attivo e modalità conoscenza diversa da Certificata; non nelle sessioni Wargame. Se manca vale false
    FATTI_FILTRO_RECENTI, FATTI_VERIFICA_A_VALLEtrue, true (default del codice: false, false)Filtro dei fatti recenti e verifica a valle (fase 5, per la massima accuratezza). Con il filtro, un fatto datato entro FATTI_ETA_MIN_MESI mesi dalla raccolta (12) entra nell'analisi solo se ha due domini indipendenti oppure data ed evento compaiono nel testo di una pagina che cita (richiede FONTI_METADATI_ABILITATI); i fatti più vecchi entrano senza altro. Con la verifica a valle, una ricerca web indipendente sui fatti recenti ammessi (al massimo FATTI_VERIFICA_MAX, 10) deve trovare la stessa data in una fonte diversa da quelle del fatto: il codice controlla che la data compaia nel testo della ricerca, sia compatibile con quella del fatto (stessa precisione o più precisa), sia sostenuta da una fonte reale e che la fonte non sia già tra quelle del fatto. Se la data trovata è diversa il fatto è «contestato» (le due versioni restano visibili, il sistema non sceglie); se non trova nulla è «non verificato». I fatti esclusi restano nel quadro del report con la loro etichetta ma non entrano nei prompt, nei richiami né nelle date ammesse. Costo circa 0,08 $ e 10 secondi in più per analisi (due chiamate: ricerca con circa 4–6 query e trascrizione). Se le costanti mancano valgono false
    FATTI_SOLO_STORICItrue (default del codice: false)Massima accuratezza, minor volume. Con true i fatti recenti (entro FATTI_ETA_MIN_MESI mesi) restano nel quadro del report e nella scheda con l'etichetta ma non entrano mai nell'analisi, neppure se corroborati o confermati dalla verifica; la verifica a valle e la lettura delle pagine per il filtro non servono più. Nelle prove i fatti oltre 12 mesi erano esatti (23 su 23 verificati), i recenti ammessi da filtro e verifica nell'86% dei casi verificati (4 errori su 29: date di pubblicazione al posto della data dell'evento, scarto di un giorno, qualificazione dell'evento). Contropartita: pochi fatti nell'analisi (circa 3 per analisi nella serie di prova) e quasi sempre l'avviso «fatti scarsi»
    FATTI_ETA_MIN_MESI, FATTI_VERIFICA_MAX, FATTI_VERIFICA_NON_TROVATO12, 10, escludiMesi entro cui un fatto è «recente»; quanti fatti verificare per analisi (gli altri recenti restano non confermati); con «tieni» un fatto recente non confermato resta nell'analisi con l'etichetta invece di essere escluso (meno accurato)
    FONTI_METADATI_ABILITATI, FONTI_METADATI_MAX, FONTI_METADATI_TIMEOUTtrue (default del codice: false), 25, 6Metadati delle fonti (fase 3b). La classificazione indicativa dei domini è sempre attiva. Con la prima costante a true il server legge l'inizio delle pagine delle fonti dei fatti (richieste http/https in uscita, solo a indirizzi pubblici sulle porte 80 e 443, reindirizzamenti seguiti a mano e ricontrollati, al massimo 25 pagine e 6 secondi, in parallelo, circa 2–5 secondi in più) per ricavare autore o ente, anno di pubblicazione e stato del link (raggiungibile, non raggiungibile, non verificato). I siti visitati vedono l'indirizzo IP del server e un nome di client generico (AnalistaGeopoliticoBot); il file robots.txt non viene consultato. Il testo delle pagine non entra nei prompt e non si conserva. Un metadato che la pagina non fornisce resta vuoto: non si completa a memoria. Se la costante manca vale false
    FATTI_CONTROLLO_DATEtrueControllo delle date (fase 2b). Con fatti utilizzabili, dopo ogni fase da P03 a P13 il codice (senza il modello, costo nullo) estrae anni, date e cifre significative dai testi e segnala come «Date non verificate» (nella scheda della fase e in un riepilogo nel report) quelle che non sono nei fatti di riferimento (alla loro precisione: un fatto «1920-02» non autorizza «9 febbraio 1920»), nel tema, nel perimetro o nell'ambito dell'utente né nella base di conoscenza (knowledge/*.md). Gravità alta: data completa o cifra; media: mese o anno. Non sono errori accertati ma dati scritti a memoria. Non segnala articoli di legge, risoluzioni, citazioni «(Autore, anno)», decenni. Non si applica senza fatti. false lo spegne
    FATTI_CONTROLLO_DATE_RIESECUZIONE, FATTI_CONTROLLO_DATE_MAX_RIESECUZIONIfalse, 3Se true, per le sole segnalazioni di gravità alta la fase viene rieseguita con l'indicazione «rimuovile oppure attribuiscile a un fatto di riferimento»; la nuova versione sostituisce l'originale solo se è valida e ha meno segnalazioni gravi. Circa 0,003–0,005 $ a esecuzione, al massimo il secondo valore per analisi (il tetto non si azzera con la riclassificazione)
    FATTI_MAX, FATTI_MIN_UTILIZZABILI15, 8Numero massimo di fatti tenuti; sotto il minimo di fatti utilizzabili l'utente vede l'avviso «Fatti non disponibili o scarsi»
    FATTI_SOGLIA_DATATO_MESI24Un «assetto attuale» con data più vecchia di questi mesi è marcato «dato non recente»
    FATTI_TEMPERATURA, FATTI_MAX_CARATTERI_PROSA0.1, 30000Temperatura della chiamata di trascrizione in JSON e lunghezza massima del testo di ricerca che le viene passato
    RICERCA_PASSATA_ANALISIfalsefalse = ogni fase fa una sola chiamata con schema (la passata di ricerca delle fasi non eseguiva ricerche e raddoppiava il costo); true = ripristina il flusso storico a due chiamate (ricerca + strutturazione). Non tocca la ricerca approfondita né l'arricchimento EIL
    MOSTRA_JSON_TECNICOfalseMostra o nasconde il JSON tecnico grezzo nell'interfaccia (solo visualizzazione, nessun effetto sul server)

    Quote, limiti e conservazione

    CostanteValoreEffetto
    DEFAULT_QUOTA_TOKEN_TOTALE, DEFAULT_QUOTA_BUDGET_TOTALE10.000.000, 4.00 (default del codice: 0, 0 = illimitata)Quota proposta ai nuovi utenti non amministratori; 0 = illimitata. Si cambia poi per ogni utente da Amministrazione. Vale per «Accetta utente» e per il modulo «Crea nuovo utente», che ne precompila i campi (per gli amministratori propone 0); lasciando un campo vuoto il server usa comunque questo valore, mentre uno «0» scritto resta illimitato
    LIMITE_TOKEN_SESSIONE, LIMITE_COSTO_SESSIONE1.000.000, 1.00Tetto per singola analisi, uguale per tutti gli account; al 100% l'analisi si ferma e serve una nuova analisi
    SOGLIA_AVVISO_QUOTA_PERCENTUALE90Percentuale oltre cui compare l'avviso non bloccante, sia sulla quota utente sia sul limite di sessione
    GEMINI_LIMITE_RPM, GEMINI_LIMITE_TPM, GEMINI_LIMITE_MARGINE1000, 1.000.000, 0.8Limiti di richieste e token di ingresso al minuto della chiave Gemini e quota usata davvero. Più le opzionali GEMINI_LIMITATORE_* e GEMINI_RETRY_*: vedi Quanti utenti insieme?
    ANALISI_RITENZIONE_GIORNI90 (default del codice: 30)Dopo quanti giorni dall'ultimo aggiornamento un'analisi viene cancellata dal database; 30 se la riga manca, 0 = mai
    SESSION_LIFETIME_SECONDS7200Durata della sessione (login e analisi in corso) per inattività: 2 ore. Vedi «Per quanto tempo resto collegato?»

    Log e diagnostica

    CostanteValoreEffetto
    LOG_ANALISI_ABILITATO, LOG_GROUNDING_ABILITATO, LOG_MOTIVI_ABILITATOtrue, true, trueCosa finisce nel file di log di ogni analisi: narrativa delle fasi, ricerche web, motivi di riformulazione e fallimento dei validatori. Vedi File di log
    DEBUG_FASI_ABILITATO, DEBUG_FASI_MAX_ANALISItrue, 3Cattura di richiesta e risposta grezza di ogni chiamata, per le ultime N analisi di tutti gli utenti insieme. Vedi Debug fasi

    EIL e modalità Wargame

    CostanteValoreEffetto
    EIL_ABILITATOfalseInterruttore generale della base certificata EIL: false = selettore «Conoscenza» nascosto e nessuna query neppure chiamando l'API a mano. Vedi Modalità di conoscenza
    EIL_TIMEOUT_SECONDS, EIL_MAX_QUERY_PER_ANALISI300, 40Attesa massima per una query EIL e tetto di query per analisi (0 = nessun limite)
    MODALITA_WARGAME_ABILITATAfalseInterruttore generale della modalità Wargame didattica. Da sola non genera costi: il percorso principale non chiama Gemini
    WARGAME_VALUTAZIONE_GIUSTIFICAZIONI_ABILITATA, WARGAME_MODELLO_VALUTAZIONE, WARGAME_LIMITE_VALUTAZIONI_PER_PARTITAfalse, gemini-3.1-flash-lite, 10Valutazione facoltativa con Gemini delle giustificazioni scritte in testo libero: interruttore indipendente, modello economico dedicato e tetto di chiamate per partita

    🏷️ Release numerate (test e produzione)

    Sotto il bottone Amministrazione (e per tutti gli utenti, nello stesso punto della barra laterale) compare il numero della release in uso: Release 12 · 14/11/2026, cioè un progressivo e la data di rilascio. Passando il mouse si vede anche la data dell'ultima modifica ai file. Test e produzione hanno contatori separati: la release 5 di produzione non è la release 5 di test. Finché non è stata creata nessuna release compare la vecchia dicitura «Release del gg-mm-aa».

    ℹ️ Come funziona
    • Una release è un tag git (test-N in test, prod-N in produzione). Il commit taggato contiene il file release/test.json o release/prod.json (ambiente, progressivo, data), che l'applicazione legge per mostrare il numero.
    • Si gestiscono dalla pagina «Release» (releases.html), raggiungibile dal bottone «Release» nella pagina Amministrazione e riservata all'utenza admin, oppure dal server con lo script tools/release.sh.
    • Il container dell'applicazione non ha git: la pagina manda la richiesta a api/releases.php, che la controlla e la mette in coda, e la esegue un agente sul server (release-agent.sh, da cron, ogni minuto). La pagina mostra se l'agente risponde e disabilita le operazioni se non risponde.
    • Tornare a una release precedente (e poi a una successiva) cambia i file del codice; config-work.php, storage/ e gli altri file non tracciati restano come sono.

    La pagina «Release»

    Cosa vedi / faiDoveEffetto
    Statotest e produzioneAmbiente, release attiva, se l'agente risponde, e un riquadro: «sul ramo di sviluppo, N commit dopo test-N» oppure, in rosso, «stai eseguendo la release N, non lo sviluppo»
    Crea release (con una nota)solo testCrea test-N dal ramo test. Disabilitato se non c'è nulla di nuovo dopo l'ultima release, se sei su una release «staccata» o se ci sono modifiche non committate
    Promuovisolo produzionePorta una release di test, scelta tra quelle non ancora in produzione, in main e crea prod-M. Il codice in produzione cambia subito
    Attiva (accanto a ogni release)test e produzionePorta il codice a quella release, indietro o avanti. Chiede sempre conferma; in produzione lo ricorda in maiuscolo
    Annulla e torna a test-N (sulla release attiva)test e produzioneAnnulla l'ultima release e riporta il ramo di sviluppo alla precedente: i file tornano quelli della precedente, il numero sotto «Amministrazione» scende e la release annullata esce dall'elenco. Compare solo sull'ultima release, quando è quella attiva sul ramo (nessun commit dopo, nessuna modifica locale) e se ce n'è una precedente; in test, se la release è già in produzione, il pulsante resta visibile ma disabilitato, con la spiegazione scritta accanto (si annulla dalla pagina di produzione). In produzione chiede di scrivere PRODUZIONE e le release di test portate con quella promozione tornano tra quelle da promuovere. La conferma elenca i commit che escono dal ramo (i 25 più recenti, con «… e altri N» se sono di più), oltre alle altre conseguenze. Non cancella nulla: la release annullata resta nell'archivio e il suo numero non viene riusato (vedi sotto)
    Torna allo sviluppotest e produzioneDopo un «Attiva», riporta il codice al ramo di lavoro (test in test, main in produzione)
    Pannello Databasetest e produzioneMigrazioni registrate e in sospeso, Applica migrazioni in sospeso, Crea un dump ora e l'elenco dei dump con Ripristina (chiede di scrivere TEST o PRODUZIONE). Compare solo se le operazioni sul database sono abilitate per l'ambiente (vedi «Installazione dell'agente»)
    Cronologiatest e produzioneChi ha fatto cosa, quando, da dove a dove, con l'esito (storage/releases/registro.jsonl)

    Una richiesta alla volta: mentre ce n'è una in coda o in esecuzione i pulsanti sono disabilitati. Per circa un secondo, mentre i file cambiano, l'applicazione risponde «aggiornamento in corso» (modalità manutenzione, che scade da sola dopo 3 minuti se l'agente si interrompe).

    Comandi da terminale (tools/release.sh)

    ComandoDoveEffetto
    tools/release.sh elencatest e produzioneElenca le release (dalla più recente) e segna con * quella attiva; dice se sei sul ramo di sviluppo o su una release «staccata» e quale numero mostra l'applicazione
    tools/release.sh crea "note"solo testCrea la release test-N dal ramo test: aggiorna release/test.json, fa il commit e mette il tag con le note. Si ferma se ci sono modifiche non committate o se non c'è nulla di nuovo dopo l'ultima release
    tools/release.sh promuovi test-Nsolo produzionePorta la release di test test-N in main (merge), aggiorna release/prod.json e crea prod-M, con l'origine nelle note. Se il merge ha conflitti viene annullato e non cambia nulla
    tools/release.sh attiva test-N / prod-Ntest / produzionePorta il codice a una release esistente, indietro o avanti. Il numero sotto «Amministrazione» cambia subito. Rifiutato se ci sono modifiche locali ai file tracciati
    tools/release.sh annulla test-N / prod-Ntest / produzioneAnnulla l'ultima release (reset del ramo alla precedente, con il tag spostato in refs/archivio/). Stesse condizioni della pagina; con differenze in db/ chiede --conferma-db
    tools/release.sh sviluppotest e produzioneDopo un «attiva», torna al ramo di lavoro
    tools/release.sh migratest e produzioneApplica al database le migrazioni di db/migrations/ del commit in esecuzione non ancora applicate, dopo un dump automatico
    tools/release.sh dump [etichetta], dump-elencatest e produzioneCrea una copia compressa del database / elenca i dump dell'ambiente
    tools/release.sh ripristina-db ID --conferma-dbtest e produzioneRiporta il database al contenuto di un dump (vedi «Database» sotto)
    cd /home/ubuntu/angst-project-test
    tools/release.sh elenca                  # quali release ci sono, quale è attiva
    tools/release.sh attiva test-12          # indietro alla release 12
    tools/release.sh attiva test-15          # poi avanti alla 15
    tools/release.sh sviluppo                # di nuovo sul ramo di lavoro

    Installazione dell'agente (una volta per ambiente)

    L'agente sta fuori dall'albero del progetto, in /home/ubuntu/angst-release/: se stesse dentro, tornando a una release vecchia sparirebbe o cambierebbe insieme a quella. Si installa dalla cartella dell'ambiente e si collega a cron (una riga per ambiente, con la sua ANGST_RADICE):

    cd /home/ubuntu/angst-project-test && tools/installa-agente.sh      # stampa la riga di crontab da aggiungere
    crontab -e                                                         # aggiungi la riga stampata (test e, a parte, produzione)

    La copia installata non si aggiorna da sola: dopo ogni modifica a tools/release.sh, tools/release-db.sh o tools/release-agent.sh si rilancia tools/installa-agente.sh. Attenzione: la cartella installata è condivisa da test e produzione, quindi rilanciare l'installazione aggiorna gli script di tutti e due gli ambienti.

    Operazioni sul database: un interruttore per ambiente. Migrazioni, dump e ripristino partono solo se esiste il file db-abilitato-test (o db-abilitato-prod) in /home/ubuntu/angst-release/, e solo per le due cartelle vere dell'applicazione. Senza il file tutto funziona come prima (le release cambiano solo il codice) e il pannello «Database» non compare. Si abilita e si disabilita così:

    touch /home/ubuntu/angst-release/db-abilitato-test       # abilita il database per il test (…-prod per la produzione)
    rm /home/ubuntu/angst-release/db-abilitato-test          # lo disabilita

    Database: migrazioni, dump e ripristino

    • Migrazioni. Le modifiche allo schema si scrivono come file NNNN_descrizione con estensione .sql nella cartella db/migrations/ (regole in db/migrations/LEGGIMI.txt): quattro cifre progressive, additive (solo nuove tabelle, colonne, indici: niente DROP né RENAME) e ripetibili (IF NOT EXISTS). Si applicano in ordine, una sola volta per database, e quali sono già applicate lo dice la tabella schema_migrazioni. Vanno committate prima di applicarle: si leggono dal commit, non dai file non committati. Le migrazioni storiche (db/migrate_*.sql) risultano già applicate su test e produzione e non si rieseguono.
    • Tornare indietro non annulla le migrazioni. Il codice vecchio gira sullo schema nuovo: per questo devono essere additive. La tabella segna con «schema più recente (N)» le release che non conoscono N migrazioni già applicate.
    • Dump. Copie compresse del database, fatte con l'utente applicativo (che ha accesso solo ai due database dell'applicazione) in /home/ubuntu/angst-release/dump/<ambiente>/. Cartella 700 e file 600: contengono dati degli utenti, non vanno copiati né condivisi. Se ne tengono gli ultimi 5. Si fanno da soli prima di «Attiva», «Promuovi» e «Applica migrazioni» quando cambia db/, e a richiesta con «Crea un dump ora»: non a ogni cambio, per non far scorrere via i dump utili.
    • Ripristino. Riporta il database al contenuto di un dump: tutto ciò che è stato scritto dopo (utenti, analisi, quote) va perso; i report salvati su file non cambiano. Prima fa un dump di sicurezza e, se il ricaricamento fallisce, rimette il database com'era. Dalla pagina chiede una conferma e poi di scrivere TEST o PRODUZIONE. Non è una operazione di routine.

    Costanti di config-work.php

    Il file release/config.txt elenca le costanti che la release legge, una per riga: NOME;obbligatoria|facoltativa;descrizione. Una costante conta come definita solo se in config-work.php c'è un define('NOME', …) non commentato. Se manca una costante obbligatoria, «Attiva» e «Promuovi» si rifiutano (la tabella lo segna con «manca in config-work.php: NOME»; da terminale l'uscita è 4 e --ignora-config la forza). Una costante facoltativa nuova non definita non blocca nulla: la conferma lo ricorda, e il codice usa il valore predefinito. In produzione le aggiunte a config-work.php le fa l'amministratore del server. Chi aggiunge a una release una costante senza valore predefinito deve aggiungerla a questo file.

    Cose da sapere

    • Il database e le release. Se tra la release attuale e quella richiesta (in «Attiva» o «Promuovi») cambiano file di db/, l'operazione si ferma, li elenca insieme alle migrazioni da applicare e chiede conferma (da terminale: --conferma-db). Con la conferma, prima di cambiare il codice fa un dump automatico e applica le migrazioni della release; se una migrazione fallisce il codice non cambia. Se le operazioni sul database non sono abilitate per l'ambiente, il gate resta ma il database non viene toccato. Vedi «Database: migrazioni, dump e ripristino».
    • Release senza la pagina. Le release create prima della pagina «Release» (per esempio test-1 e prod-1) non la contengono: attivandole la pagina scompare. La tabella le segna con «senza pagina Release» e la conferma lo ricorda. Per tornare avanti serve il terminale: ANGST_RADICE=<cartella dell'ambiente> /home/ubuntu/angst-release/release.sh attiva <release> (oppure sviluppo).
    • Release annullate. «Annulla e torna a…» non cancella la release: il tag va in refs/archivio/test-N, che tiene vivi i suoi commit, e il numero resta occupato (la prossima release non lo riusa: dopo aver annullato la 7, la successiva è la 8). Nel registro dell'ambiente compare come «Annulla release». Per recuperarla, dalla cartella dell'ambiente: git update-ref refs/tags/test-N refs/archivio/test-N && git reset --hard test-N (la seconda parte riporta anche il ramo). tools/release.sh elenca elenca le release annullate. Il ramo di sviluppo viene riscritto: per questo non si annulla in test una release già portata in produzione. Le modifiche non committate non vengono scartate: l'operazione si rifiuta finché ci sono.
    • Commit su una release «staccata». Se dopo un «Attiva» fai dei commit (da terminale), non vanno sul ramo di sviluppo ma su un ramo anonimo: spostando poi il codice resterebbero senza nome e git, col tempo, li elimina. Per evitarlo, finché ci sono commit che non stanno in nessun ramo, tag o archivio, «Attiva» e «Torna allo sviluppo» si rifiutano (da terminale: uscita 5): la pagina mostra un riquadro rosso con i commit e disabilita quei pulsanti. Per salvarli: git -C <cartella dell'ambiente> switch -c nome-del-ramo. Per abbandonarli di proposito (solo da terminale): tools/release.sh sviluppo --abbandona-commit o attiva TAG --abbandona-commit; restano ancora per un po' in git reflog. Per lavorare partendo da una release vecchia è meglio creare subito un ramo dal tag: git switch -c nome test-N.
    • Release «staccata». Dopo «Attiva» il codice non è più sul ramo di sviluppo (anche se la release attivata è l'ultima e coincide con la punta del ramo): finché non fai «Torna allo sviluppo» non si creano release né commit su quel ramo.
    • Il numero va cambiato solo da qui o con lo script: un git checkout a mano porta ai file giusti ma non sempre al numero giusto, perché il numero è dentro il tag.

    🧪 Provare la pagina «Release» (nell'ambiente di test)

    Percorso per verificare a mano, nell'ambiente di test, che la pagina «Release» faccia quello che deve. Si accede con l'utenza admin; la provi su un sito che non è la produzione, e il database non viene toccato.

    Prima di cominciare

    • L'agente deve girare. Controlla la riga in crontab -l (vedi «Installazione dell'agente»). Dopo al massimo un minuto, nella pagina deve comparire «Agente attivo (stato aggiornato N s fa)»; se compare «non risponde», le operazioni sono disabilitate di proposito.
    • Il codice sul server deve essere pulito: nessuna modifica non committata ai file tracciati (git status), altrimenti tutte le operazioni sono bloccate.
    • Serve almeno un commit dopo l'ultima release, altrimenti «Crea release» resta disabilitato («nulla di nuovo»). Se non ne hai uno, ne basta uno vuoto:
    cd /home/ubuntu/angst-project-test
    git commit --allow-empty -m "Commit di prova per la pagina Release"
    • Non usare le release senza la pagina (test-1, segnata «senza pagina Release») per provare il ritorno indietro: ci si torna dal terminale. Per questa prova servono due release che contengano la pagina, cioè test-2 e quella che creerai al punto 4.

    Percorso di prova

    #Cosa faiCosa devi vedere
    1Accedi come admin, apri Amministrazione e clicca il bottone Release in alto.Si apre releases.html. Il bottone non compare per gli altri account, neppure per quelli con ruolo amministratore; chi apre l'indirizzo a mano viene rimandato all'app.
    2Guarda il pannello Stato e la tabella.Il riquadro «TEST»; «Agente attivo (stato aggiornato N s fa)». Se c'è almeno un commit dopo l'ultima release (il caso normale per questa prova): «Nessuna release attiva: sei sul ramo «test»» e il riquadro «Sei sul ramo di sviluppo «test»: N commit dopo test-2», senza rosso; nella tabella test-2 non ha il segno «attiva» e ha il pulsante «Attiva», mentre test-1 ha «senza pagina Release». Se invece non ci sono commit dopo l'ultima release, quella release è segnata «attiva» e il riquadro dice «0 commit dopo…».
    3Controlla i pulsanti.Con almeno un commit dopo l'ultima release: «Crea release» abilitato, «Torna allo sviluppo» disabilitato (sei già sul ramo). Senza commit nuovi, «Crea release» è disabilitato: non c'è nulla da rilasciare.
    4Crea release: scrivi una nota (per esempio «Prova della pagina Release») e conferma.Un messaggio che passa da «richiesta inviata» a «in attesa dell'agente» e a «fatto». Entro pochi secondi compare test-3 con «attiva», e la cronologia ha la riga «Crea release». Nell'app, ricaricando, sotto «Amministrazione» c'è Release 3 · data.
    5Attiva accanto a test-2 (indietro) e conferma.In 3-5 secondi test-2 diventa attiva; compare il riquadro rosso «Stai eseguendo la release test-2, non lo sviluppo»; «Crea release» è disabilitato e «Torna allo sviluppo» abilitato. Nell'app il numero è Release 2.
    6Attiva accanto a test-3 (avanti) e conferma.Il numero torna a 3 e la cronologia ha la riga «Attiva test-3, test-2 → test-3». Il riquadro resta rosso («Stai eseguendo la release test-3, non lo sviluppo»): ogni «Attiva» lascia il codice su una release «staccata», anche quando è l'ultima e coincide con il ramo di sviluppo.
    7Premi Torna allo sviluppo e conferma.Il riquadro torna normale: «Sei sul ramo di sviluppo «test»: 0 commit dopo test-3»; «Torna allo sviluppo» è di nuovo disabilitato e test-3 è di nuovo segnata «attiva».
    8Ad ogni conferma («Attiva», «Crea release», «Torna allo sviluppo»), premi Annulla invece di confermare.Non succede nulla: nessun messaggio di operazione, nessuna riga nella cronologia, nessuna release nuova. Per provarlo su «Crea release» serve almeno un commit dopo l'ultima release (il pulsante, altrimenti, è disabilitato): ne basta uno vuoto, con il comando indicato sopra.

    Controlli che devono fallire (e come)

    • File modificato sul server: cambia a mano un file tracciato (per esempio aggiungi una riga a un file in api/) e attendi 15 secondi. Compare il riquadro rosso «Ci sono modifiche non committate» e tutti i pulsanti si disabilitano. Annulla con git checkout -- <file>.
    • Agente fermo: togli la riga di cron (crontab -e) e attendi circa 90 secondi: «L'agente delle release non risponde» e operazioni disabilitate. Rimettila e dopo un minuto torna tutto. Rimettila subito: senza agente nessuna operazione dalla pagina è possibile.
    • Accesso senza essere admin: con un altro account amministratore, releases.html rimanda all'app e api/releases.php risponde 403.
    • Due clic ravvicinati: mentre una richiesta è in corso i pulsanti sono disabilitati; un'altra richiesta, se arrivasse, viene rifiutata («c'è già un'operazione in corso»).

    Controllare anche dal server

    cd /home/ubuntu/angst-project-test
    tools/release.sh elenca                           # release attiva e ramo, come nella pagina
    tail -n 5 storage/releases/registro.jsonl         # le operazioni della cronologia
    cat /home/ubuntu/angst-release/agente.log         # vuoto se l'agente non ha avuto errori

    Provare la parte database (solo nel test)

    Servono le operazioni sul database abilitate (touch /home/ubuntu/angst-release/db-abilitato-test): senza il file il pannello «Database» non compare. Le prove lavorano sul database di test vero (angst_test): il ripristino di un dump appena creato non fa perdere nulla (si perde solo ciò che si scrive nel frattempo).

    #Cosa faiCosa devi vedere
    D1Apri la pagina Release.Compare il pannello Database con «angst_test» e il numero di migrazioni registrate. La prima volta la tabella schema_migrazioni non c'è ancora e lo dice.
    D2Crea un dump ora e conferma.In pochi secondi compare in elenco un dump «manuale» con data e dimensione. Si tengono gli ultimi 5.
    D3Scrivi e committa una migrazione di prova (esempio sotto), poi ricarica la pagina.Il pannello dice «ne restano da applicare 1» e il pulsante Applica migrazioni in sospeso si abilita.
    D4Applica migrazioni in sospeso e conferma.Un dump «pre-migra» in più; «Nessuna migrazione in sospeso»; la tabella schema_migrazioni ha la nuova riga (la prima volta anche le 6 storiche come «legacy/…»).
    D5Crea una release (come al punto 4) con la migrazione committata, poi attiva una release precedente e riattiva questa.All'«Attiva» verso la release senza la migrazione, la conferma dice che il database ha una migrazione che quella release non conosce; tornando avanti non c'è nulla da applicare.
    D6Ripristina il dump del punto D2 (o uno appena creato), scrivi TEST.Un dump «pre-ripristino» in più e l'esito «riuscita» in cronologia; schema_migrazioni torna a com'era in quel dump. Sbagliare la parola (per esempio minuscola) annulla tutto senza cambiare nulla.

    Una migrazione di prova innocua (committala, poi applicala):

    cd /home/ubuntu/angst-project-test
    echo "CREATE TABLE IF NOT EXISTS prova_release (id INT PRIMARY KEY) ENGINE=InnoDB;" > db/migrations/0001_prova_release.sql
    git add db/migrations/0001_prova_release.sql && git commit -m "Migrazione di prova"

    Per toglierla dopo la prova: DROP TABLE prova_release; e cancellare la sua riga da schema_migrazioni, oppure ripristinare il dump fatto al punto D2.

    Dopo la prova

    • Riporta il test sul ramo di sviluppo con Torna allo sviluppo (punto 7) e controlla che git status sia pulito.
    • La release creata per la prova (test-3) resta nell'elenco: è una release come le altre. Non c'è un comando per cancellare una release dalla pagina.
    • Il cambio di database non si prova da qui: la conferma aggiuntiva compare solo quando tra due release cambiano i file di db/. Per provarla servono due release che differiscono in db/.
    • La produzione non si prova con questo percorso: lì «Crea release» non c'è, e «Promuovi» porta davvero il codice in produzione.

    🔒 File pubblici e protezioni

    La cartella dell'applicazione è anche la radice web: tutto ciò che c'è dentro è raggiungibile da chiunque, a meno che una regola lo blocchi. Al browser servono solo le pagine .html, js/, css/, il logo e gli endpoint api/*.php (che chiedono l'accesso). Tutto il resto — repository git, test, strumenti, schemi, documenti interni, configurazione — non deve essere scaricabile.

    ⚠️ Perché è importante Il 15 novembre 2026 si è scoperto che in produzione la cartella .git/ era scaricabile: dai log, scanner automatici l'hanno copiata più volte dal 20 settembre (codice, storia dei commit, metodo in knowledge/, schema del database, test). Nella storia non risultano segreti (config-work.php non è mai stato committato), ma il codice va considerato noto a terzi. Anche i 78 file PHP di tests/ erano raggiungibili ed eseguibili da chiunque.

    Le protezioni, a più livelli

    LivelloCosa faDove sta
    1. Caddy (davanti all'app)Risponde 404 a /.git, tests/, tools/, db/, knowledge/, schemas/, release/, pres/, storage/, config-work.php, wargame-admin-* e a ogni file .md .txt .sql .sh .bak .log; aggiunge HSTS, X-Frame-Options, Referrer-Policy, Permissions-Policy e toglie l'intestazione Server/opt/stack/caddy/conf/Caddyfile, blocco di produzione. Attivo solo dopo il ricaricamento (docker exec caddy caddy reload --config /etc/caddy/Caddyfile)
    2. Apache (.htaccess)Stessa chiusura, a prova di errore: Require all denied in tests/ db/ knowledge/ schemas/ release/ pres/ tools/; nella radice nega .md .txt .sql .sh .bak .log, config-work.php, wargame-admin-*.php, .gitignore; spegne display_errors (un errore PHP non mostra più percorsi interni)Nel repository: viaggia con le release
    3. Per ambiente (non tracciati da git)storage/.htaccess: Require all denied (prima era invalido e rispondeva 500 per caso; non va «corretto» permettendo i report). .git/.htaccess nella produzione, con lo stesso testo (nel test .git è un file, non una cartella)Da rifare a mano in ogni ambiente

    L'ambiente di test è inoltre interamente dietro la password di Caddy (basic auth): tutto risponde 401 senza credenziali. Le API rispondono 401 senza sessione; la registrazione e il cambio password sono solo POST per scelta; architettura.php richiede l'account admin.

    Come verificare

    Dal container di test, tests/esposizione_web_test.php controlla la struttura e fa richieste vere (403 sui percorsi riservati, risposte invariate sulle pagine e sulle API). Può provare anche un altro server, per esempio la produzione:

    docker exec angst-test-php php /var/www/html/tests/esposizione_web_test.php
    docker exec -e ESPOSIZIONE_BASE=http://angst-php angst-test-php php /var/www/html/tests/esposizione_web_test.php   # produzione

    Dall'esterno, per un controllo rapido (devono dare 404 o 403, mai 200): curl -s -o /dev/null -w "%{http_code}\n" https://angst.geopolitical-evidence.com/.git/HEAD.

    Da sapere

    • pres/ (le presentazioni, circa 38 MB) è chiusa: se vanno condivise con link, tolgono «pres/» dall'elenco di Caddy e il .htaccess di quella cartella, oppure si mettono dietro una password.
    • Le pagine wargame-admin-*.php sono bloccate: il Wargame è disattivato e, richiamate dalla radice, già non funzionavano (errore sul percorso di config-work.php). Quando lo riattiverai, il percorso va sistemato e la regola rivista.
    • Nessuna pagina o script collega percorsi bloccati; il test lo controlla, per accorgersi se un giorno una modifica ne avesse bisogno.
    • Cookie di sessione: è HttpOnly e SameSite=Lax e, quando la richiesta arriva in HTTPS (direttamente o tramite Caddy, che manda X-Forwarded-Proto: https), anche Secure: il browser non lo invia mai su una connessione non cifrata. In HTTP semplice (sviluppo locale) il flag non c'è, così il login funziona. Le sessioni già aperte non si interrompono: il cookie viene riemesso con il flag alla richiesta successiva.
    • Log di accesso (Caddy). I log di Apache vedono solo l'indirizzo interno di Docker; quello reale dei visitatori è nel log di Caddy della produzione, /data/logs/angst-access.log nel container caddy (sul server /srv/caddy/data/logs, file riservato a root: si legge con docker exec). È in formato JSON, non registra cookie né credenziali, ruota a 25 MiB e conserva al massimo 10 file e 30 giorni: gli indirizzi IP sono dati personali, la durata va coerente con l'informativa. Esempi: docker exec caddy cat /data/logs/angst-access.log | jq -r 'select(.status==404) | [.request.client_ip, .request.uri] | @tsv' (tentativi su percorsi chiusi) e … | jq -r '.request.client_ip' | sort | uniq -c | sort -rn | head (chi fa più richieste).
    • Report salvati (api/reports.php). Un report è HTML scritto dal browser dell'utente: se l'amministratore lo apriva da «Tutti i report», uno script nascosto dentro poteva agire con la sua sessione. Ora ogni report si serve con la politica Content-Security-Policy: sandbox (nessuno script, nessun modulo, nessun accesso a cookie e pagine dell'app; i link esterni si aprono normalmente) e con nosniff, senza referrer e senza cache; in più si tolgono <script>, <iframe>, attributi on… e indirizzi javascript: (cintura di sicurezza, non la barriera vera). Un report che prima conteneva uno script lo mostra ora senza. I nomi ammessi sono solo nome.html: la rinomina non può più produrre .htaccess, .php o nomi con punto iniziale. Limiti per utente: 2 MB per report, 300 report, 100 MB in tutto (modificabili con REPORTS_MAX_BYTE_FILE, REPORTS_MAX_FILE_UTENTE, REPORTS_MAX_BYTE_TOTALI_UTENTE in config-work.php). Test: tests/reports_sicurezza_test.php (nel container, come www-data).
    • Reset dell'analisi e ricerca web (api/index.php). ?reset=1 azzera l'analisi in corso e ora funziona solo con POST (con una GET risponde 405): prima bastava far aprire un link a un utente loggato per azzerargli l'analisi. Anche l'interruttore globale della ricerca web (grounding) non può più essere riacceso da un utente qualsiasi: il «rilancio dell'applicazione» (POST ?reset=1 o ?riprendi=1, cioè «Nuova analisi» o «Riprendi») lo riaccende solo se a farlo è l'utenza admin, l'unica che può cambiarlo; ?stato_analisi=1 (GET) è ora di sola lettura. Se spegni la ricerca web per contenere i costi, resta spenta anche quando gli altri utenti aprono l'app. Test: tests/reset_get_grounding_test.php (nel container, come root: il file storage/grounding_config.json non è scrivibile da www-data).
    • Chi ha un account? Nessuna risposta lo rivela. Il login risponde sempre «Credenziali non valide» e ora ci mette lo stesso tempo (circa 80 ms di bcrypt) per un username inesistente e per una password sbagliata: prima un username inesistente rispondeva in ~1 ms e dal tempo si capiva quali account esistono (Auth::HASH_FINTO). Il recupero password (api/password_accesso.php) dà la stessa risposta, e la manda prima di cercare l'account e inviare l'email, per indirizzi esistenti, inesistenti e amministratori. Resta distinguibile solo l'amministratore, e solo dopo 10 tentativi sbagliati sullo stesso username (il suo tetto è 20, quello degli utenti 10): è una scelta voluta per non lasciare l'admin bloccabile da chiunque. Test: tests/enumerazione_account_test.php (nel container, come www-data).
    • Redirect di Google nella bibliografia (api/Bibliografia.php). Per mostrare l'indirizzo vero delle fonti di ricerca, il server segue i link «grounding-api-redirect» di Google. Prima bastava che un indirizzo contenesse quel testo (anche in coda a un indirizzo qualunque) e il server lo richiamava, seguendo fino a 10 redirect con qualunque protocollo: un'iniezione indiretta (una pagina web ostile letta dal modello) poteva far chiamare indirizzi interni (la rete Docker, i metadati del cloud). Ora si parte solo da un vero redirect di Google (https, host esatto, senza credenziali); i redirect si seguono a mano, al massimo 5, e ogni salto passa da FontiWeb::urlConsentito() (solo porte 80/443, solo nomi che risolvono in indirizzi pubblici, mai indirizzi IP o nomi interni; la richiesta è fissata all'IP controllato) con protocolli limitati a http/https. Se un salto non è consentito, la fonte resta con l'indirizzo originale. Test: tests/bibliografia_ssrf_test.php (nel container; DNS e richieste simulati, più un server locale per il livello cURL).
    • Testo del modello nelle pagine (js/renderer-fasi.js, js/app.js, js/admin.js). Il testo scritto dal modello (o preso dal web) deve entrare nelle pagine solo dopo escapeHtml(); dentro un attributo (value="…", aria-label="…") serve escapeAttr(), perché escapeHtml() non tocca le virgolette; gli indirizzi si scrivono solo con hrefSicuro() (solo http/https); i nomi di file non vanno mai dentro un onclick="…('nome')" ma in data-*. Corretti: motivazione e rendimento atteso dell'ammissibilità (P01), casistica/confidenza/nota della classificazione, stato, link della bibliografia e dei siti visitati (prima un javascript: o una virgoletta nell'indirizzo erano ammessi), i campi del modulo di modifica di P02, i pulsanti di «I miei report» e l'etichetta del menu utenti. Non si è cambiato escapeHtml() in sé: la ricerca delle citazioni «(Autore, Anno)» confronta i nomi come testo e un apostrofo trasformato in &#39; la romperebbe. Test: tests/renderer_xss_test.js (si lancia con node, senza rete: docker run --rm --network none -v "$PWD":/p:ro -w /p node:20-slim node tests/renderer_xss_test.js): riempie ogni campo di testo libero con una stringa ostile e controlla l'HTML che i renderer scrivono. Dopo l'aggiornamento di admin.js ricarica la pagina con Ctrl+F5 (quel file non ha il numero di versione nell'indirizzo).
    • storage/ non si riapre dall'interno (Apache, fuori dal progetto). L'immagine di Apache ha «AllowOverride All» su tutto il sito: un file .htaccess scritto in una sottocartella di storage/ (con Order Allow,Deny, Allow from all, Require all granted) annullava il divieto di storage/.htaccess e rendeva scaricabile — ed eseguibile, se era un .php — ciò che vi si trovava (provato). Oggi un utente non può più creare quei file (rinomina dei report corretta) e in produzione Caddy risponde 404 su /storage/, ma la difesa vera è nel server: /opt/stack/angst/apache-storage.conf dichiara per /var/www/html/storage AllowOverride None e Require all denied e il docker-compose.yml lo monta su /etc/apache2/conf-enabled/zzz-angst-storage.conf. È attivo in test; la produzione lo avrà quando si aggiunge la stessa riga di montaggio a angst-php e lo si ricrea (docker compose up -d --no-deps angst-php: qualche secondo di interruzione). Test: docker exec -u www-data angst-test-php php /var/www/html/tests/storage_override_test.php.
    • Seconda password sulle pagine di amministrazione (proposta, non attiva). In /opt/stack/caddy/conf/Caddyfile.proposta-admin-basic-auth c'è un blocco basic_auth per admin.html, releases.html, api/admin_utenti.php e api/releases.php, con le istruzioni per attivarlo (hash scelto da te con docker exec -it caddy caddy hash-password, validate, reload). Va aggiunto al blocco di produzione del Caddyfile; il blocco del test è già interamente dietro password.

    🧪 Gemini simulato (modalità prova) e test automatici

    Per provare l'applicazione senza usare Gemini — interfaccia, barre di avanzamento, /concludi, carico — esiste la modalità prova: GeminiClientProva è il client Gemini vero con il solo trasporto HTTP simulato. Il resto della catena è quello di produzione: prompt reali con i file di conoscenza (quindi token di ingresso realistici), limitatore di quota, nuovi tentativi, battiti verso il browser, validatori, contabilità dei token e Debug fasi. Nessuna chiamata a Gemini, nessun costo.

    Cosa simula

    • La risposta: costruita dallo schema richiesto con dati segnaposto (testi che iniziano con «[PROVA]»), validi per i validatori e conformi agli schemi. Non è un'analisi: serve a far girare l'impianto.
    • La latenza di ogni chiamata, 3-9 secondi di default (le reali durano in media circa 5,6): l'analisi completa richiede qualche minuto, ed è quello che permette di vedere gli indicatori d'attesa.
    • I token: ingresso dalla lunghezza della richiesta, uscita casuale tra 300 e 1200.
    • La quota lato server (429 con il ritardo suggerito) e, a richiesta, errori transitori casuali, per provare coda e nuovi tentativi.

    Come si attiva

    Nel config-work.php del solo ambiente di test (la riga è presente ma commentata) si abilita:

    CostanteDefaultEffetto
    GEMINI_MODALITA_PROVAspentadefine('GEMINI_MODALITA_PROVA', true); accende la modalità. Il primo evento di ogni client lo scrive nel log dell'analisi («MODALITÀ PROVA: Gemini simulato»)
    GEMINI_PROVA_LATENZA_MIN, GEMINI_PROVA_LATENZA_MAX3, 9Secondi per chiamata simulata
    GEMINI_PROVA_QUOTA_RPM, GEMINI_PROVA_QUOTA_TPM1000, 1.000.000Quota simulata; 0 = nessuna quota
    GEMINI_PROVA_ERRORI0Probabilità (0-1) di un errore transitorio casuale (429 o 503) per chiamata
    ⚠️ Cose da sapere prima di accenderla
    • Mai in produzione: tutte le analisi di tutti gli utenti di quell'ambiente diventerebbero simulate, con testi «[PROVA]».
    • Debug fasi ruota: tiene solo le ultime DEBUG_FASI_MAX_ANALISI analisi (3) di tutti gli utenti. Ogni prova ne aggiunge una e fa sparire le più vecchie, comprese quelle degli altri utenti. Prima di una serie di prove metti DEBUG_FASI_ABILITATO a false (e rimettilo a true dopo).
    • La quota dell'utente scende: i token simulati si registrano nel database come quelli veri, e il costo con il listino configurato. Usa un utente di prova o ricarica la quota dopo.
    • Pulizia: le analisi di prova restano nel database fino alla scadenza e i loro file nell'elenco «File di log» finché non li elimini.
    • Cosa non prova: la qualità delle risposte, i rifiuti di Gemini sugli schemi (un campo non ammesso restituisce HTTP 400 solo con il servizio vero), le risposte troncate, il grounding reale e EIL. Per questi serve una prova con una sola analisi reale.

    Test automatici e test di carico

    • Test PHP (tests/*_test.php, nessun database né rete). Si lanciano uno per volta dal server, per esempio docker exec -w /var/www/html angst-test-php php tests/concludi_test.php; il pannello tests/esegui_test.php li esegue tutti, ma è solo per uso locale e non va lasciato raggiungibile da un dominio pubblico. Alcuni (carico_prova_test.php, prossima_fase_test.php, concludi_test.php) fanno un'analisi intera con il Gemini simulato. p02_override_test.php fallisce da prima per un confronto con vecchi codici del campo «taglio»: è un problema noto, non una regressione.
    • Test di carico (tools/carico/, vedi il suo README.md): fino a 30 analisi automatiche contemporanee sull'ambiente di test, prima con Gemini simulato e poi, con cautela, con quello reale. Gli script rifiutano un database il cui nome non finisce in _test e non girano da web.

    Domande frequenti

    Che cosa succede se non digito nulla?

    L'app rimane in attesa. Digita qualcosa (anche solo "continua") o fai click su un comando per proseguire alla fase successiva.

    Posso tornare indietro a una fase precedente?

    No, tranne con /riclassifica che ricomincia da P04. Se hai bisogno di riconsiderare fasi precedenti, devi resettare l'analisi (pulsante "Nuova analisi") e ricominciare dal principio.

    Cosa significa "Tipo SOSPESO"?

    Se in P04 la classificazione non è chiara (né A né B), il tipo rimane SOSPESO. P06 (Caratteri dello spazio) fornisce ulteriori indizi per risolverlo in P06_sintesi. Se rimane indeterminato, si usa A come fallback.

    Le lacune dichiarate bloccano l'analisi?

    No. Le lacune (dati mancanti, fonti non disponibili, ipotesi non testate) si registrano lungo il percorso, senza mai bloccare il flusso — vedi la sezione Lacune dichiarate per il dettaglio completo su come nascono, dove trovarle e come interpretarle.

    Cosa fare se P10 segnala molti problemi?

    Leggi la gravità di ciascun problema. Se ci sono problemi alti in P04, considera /riclassifica [tipo] [motivazione]: tipo e motivazione sono obbligatori e il tipo che indichi viene applicato sempre. Per problemi in fasi successive, procedi verso il report finale (P13) che documentarà i limiti metodologici.

    Posso salvare l'analisi? Cosa succede se ricarico la pagina?

    L'analisi è salvata sul server, collegata alla tua sessione (che dura 2 ore di inattività, vedi «Per quanto tempo resto collegato?»). Se ricarichi la pagina, la riapri da un'altra scheda o torni dalla pagina Amministrazione, non viene più azzerata: la chat compare con la scelta «Riprendi l'analisi» o «Nuova analisi». «Riprendi» ricostruisce tutte le fasi già completate dallo stato salvato e ti riporta al pannello di quella corrente: prosegui con /continua. Se il blocco «Caratteri dello spazio» era a metà, riparte dalla proprietà successiva senza rifare le altre. «Nuova analisi» la azzera (e non si recupera dalla pagina). Passate le 2 ore di inattività, dopo un nuovo accesso, o con «Nuova analisi», l'analisi non è più raggiungibile da qui: salva comunque il report (comando /concludi report, oppure «Salva report finale» a fine analisi) per conservarlo.

    Per quanto tempo resto collegato? (sessione e login)

    La sessione dura 2 ore di inattività (SESSION_LIFETIME_SECONDS in config-work.php). Una pausa a metà analisi non fa perdere il login finché la pagina resta aperta: il browser invia un battito leggero (api/session.php?ping=1) ogni 5 minuti che rinnova la sessione. Il battito parte solo se hai toccato la pagina (mouse, tastiera, scorrimento, tocco) nelle ultime 4 ore: una scheda dimenticata aperta non resta collegata per sempre e scade come prima. Al ritorno sulla scheda il controllo è immediato.

    • Avviso di sessione scaduta. Se un'API risponde 401 (login perso) la pagina mostra una barra rossa in alto, «La sessione è scaduta», con il pulsante Accedi di nuovo, invece di un generico errore nella chat. Nessun redirect automatico, così puoi copiare il contenuto della chat. Dopo il nuovo accesso la pagina non riprende l'analisi in corso (le fasi già completate restano salvate sul server).
    • Perché il login saltava dopo circa 20 minuti. I file di sessione stavano nel /tmp del container, condiviso con ogni altro processo PHP (script e test da riga di comando), che hanno il valore di default di PHP: 1440 s, cioè 24 minuti. La pulizia delle sessioni scadute è probabilistica e cancella i file più vecchi del tempo di vita di chi la esegue. In più il cookie di sessione veniva emesso una sola volta, con scadenza assoluta dal login.
    • Cosa fa ora api/Sessione.php (richiamato da config-work.php al posto di session_start()): usa una cartella dedicata storage/sessions (0700, con un .htaccess che ne nega l'accesso web), quindi la pulizia la fa solo l'applicazione con la durata configurata; riemette il cookie a ogni richiesta (le 2 ore diventano inattività e non durata assoluta); se la cartella non è creabile ricade sul percorso di default di PHP.
    • Per applicarlo a un altro ambiente (config-work.php non è versionato): sostituire il blocco della sessione con define('SESSION_LIFETIME_SECONDS', 2 * 60 * 60); require_once API_DIR . '/Sessione.php'; Sessione::avvia();. Senza questa modifica i file nuovi (battito, avviso) funzionano ma la sessione resta con le impostazioni precedenti.
    • Sicurezza. Con il battito, una scheda lasciata aperta e attiva resta collegata; il tetto di 4 ore dall'ultima interazione limita il rischio. Per un tetto assoluto o un tempo diverso si cambiano HEARTBEAT_MAX_INATTIVITA_MS in js/app.js e SESSION_LIFETIME_SECONDS.

    Quanti utenti insieme? Limiti di Gemini, coda e nuovi tentativi

    Gemini limita le richieste (RPM), i token di ingresso (TPM) e le richieste al giorno (RPD) per progetto. Con i limiti attuali (1.000 RPM, 1M TPM, 10.000 RPD, letti da AI Studio) il vincolo è il TPM: un'analisi in modalità automatica consuma in media circa 94.000 token di ingresso al minuto, con picchi di circa 210.000 nella fase P06 (misura su analisi reali), quindi bastano 5-10 analisi automatiche insieme per superarlo. Le richieste al minuto (circa 11 in media, 20 al picco per analisi) e al giorno (circa 55 per analisi) sono molto più larghe.

    • Limitatore condiviso (api/GeminiLimitatore.php). Ogni chiamata a Gemini prenota spazio in una finestra mobile di 60 secondi su richieste e token, condivisa tra tutti i processi PHP, all'80% dei limiti (800 RPM, 800.000 TPM). Se la finestra è piena la chiamata attende invece di partire e ricevere un 429: con molte analisi insieme rallentano tutte, non ne falliscono alcune. Trenta analisi automatiche (circa 11 milioni di token di ingresso) finiscono in circa 14-17 minuti invece dei 4 a ritmo pieno. I token prenotati sono una stima (caratteri / 3,5, prudente rispetto al rapporto misurato di circa 4,2); dopo la risposta vengono sostituiti da quelli reali.
    • Nuovi tentativi. Su HTTP 429, 500, 502, 503, 504 e connessione non stabilita la chiamata viene ripetuta (fino a 4 volte) con attesa crescente e casuale (circa 2, 4, 8, 16 s), rispettando il ritardo suggerito da Gemini (Retry-After o retryDelay). Un 429 ferma anche gli altri processi per quel tempo. Se il ritardo suggerito supera 60 secondi (tipicamente la quota giornaliera esaurita) non si aspetta: l'errore risale subito, con il motivo nel messaggio. I timeout e gli errori permanenti (400, 401, 403) non si ripetono.
    • Mentre si aspetta parte il battito verso il browser (come per le chiamate lente), quindi l'analisi automatica non perde la connessione. L'attesa in coda ha un massimo (300 s): oltre, la chiamata fallisce con «Coda Gemini troppo lunga» e vale come errore tecnico della fase.
    • Dove si vede. Ogni attesa in coda (da 1 s) e ogni nuovo tentativo compaiono nel log dell'analisi come righe [gemini] (vedi File di log) e nel record di Debug fasi (tentativi, attesa_coda_s, attesa_retry_s).
    • Configurazione (config-work.php, tutte opzionali con questi valori di default): GEMINI_LIMITE_RPM (1000), GEMINI_LIMITE_TPM (1000000), GEMINI_LIMITE_MARGINE (0.8), GEMINI_LIMITATORE_ABILITATO, GEMINI_LIMITATORE_MAX_ATTESA_SECONDI, GEMINI_RETRY_MAX, GEMINI_RETRY_ATTESA_TOTALE_SECONDI, GEMINI_RETRY_ATTESA_MAX_SINGOLA_SECONDI. Lo stato della finestra è nel file storage/gemini_limiter.json.
    • Test e produzione condividono la stessa chiave Gemini, quindi la stessa quota, ma ciascuno ha la propria finestra: se girano insieme sotto carico, ripartisci i limiti (per esempio TPM 600.000 in produzione e 400.000 nel test; oggi entrambi i config-work.php hanno 1.000.000, quindi ciascun ambiente conta l'intera quota). Il limitatore non vede il traffico dell'altro ambiente. EIL ha una chiave diversa e non ne è coinvolto.
    • Limiti. Conta i token di ingresso (come il TPM di Gemini, per quanto ne so) e le richieste, non quelli di output né la quota separata delle ricerche web (grounding), da controllare in AI Studio. Non c'è una coda con priorità: chi trova spazio per primo passa.

    Ricaricare la pagina non azzera più l'analisi: «Riprendi» e parole di continuazione

    Incidente del 06/10/2026: alla riapertura di index.html (ricarica, seconda scheda, ritorno da Amministrazione) la pagina chiamava ?reset=1, che scollega la sessione dall'analisi in corso. Un «continua» successivo trovava l'analisi vuota (fase P00) ed era trattato come tema di una nuova analisi: P01 lo respingeva («Tema non ammesso: il termine 'continua' è privo di referenza spaziale…») con una chiamata a Gemini a pagamento. L'analisi originale restava nel database, ma non era più raggiungibile dalla sessione.

    • Riprendi invece di azzerare. All'apertura la pagina chiede GET api/index.php?stato_analisi=1. Se la sessione ha un analisi a metà (tema ammesso da P01, fase oltre P00) mostra «Riprendi l'analisi / Nuova analisi» e blocca l'input finché non si sceglie; altrimenti azzera come prima. In caso di errore nella richiesta si comporta come prima (azzera). ?stato_analisi=1 e ?riprendi=1 non azzerano mai; solo «Nuova analisi» (o /abbandona) lo fa.
    • Cosa ricostruisce «Riprendi» (POST ?riprendi=1 → Orchestrator::riepilogoAnalisi()): tema, modalità (automatica/semi-automatica, ricerca approfondita, modalità di conoscenza: gli interruttori tornano come erano e restano bloccati), tutte le fasi presenti con gli stessi renderer dell'analisi automatica, lacune, siti visitati, totali di token, quota e, se c'è P13, bibliografia e grafo ricostruiti dallo stato. Senza chiamate a Gemini e senza modificare lo stato. Poi il pannello azioni dell'ultima fase: si prosegue con /continua.
    • Blocco P06 a metà: le proprietà già analizzate restano disponibili alla sintesi; il server riparte dalla successiva (current_phase è l'ultima fase completata, anche dentro P06).
    • Parole di continuazione senza analisi. «continua», «ok», «avanti», «prosegui», «procedi», «vai», «sì», «va bene», «grazie»… (anche con «/» iniziale, maiuscole o punteggiatura) o un messaggio vuoto, quando non c'è un'analisi in corso, non vengono più mandati al router P00 e a P01: nessuna chiamata a Gemini, risposta nessuna_analisi con un messaggio che spiega cosa è successo. Vale solo se il messaggio è solo quella parola: una frase che la contiene («la continuità dello stretto…») è un tema. Con un'analisi in corso «continua» fa avanzare la fase come sempre.
    • Limiti. «Riprendi» è offerto solo finché la sessione è viva (2 ore di inattività): dopo un nuovo accesso la sessione non punta più all'analisi. Le analisi restano nel database per ANALISI_RITENZIONE_GIORNI giorni (30 se la costante manca; 0 = mai cancellate; ora 90 in test e produzione), ma non c'è ancora un elenco per riaprire una vecchia. Un tema respinto o da riformulare da P01 non si riprende (non c'è nulla da continuare); un tema AMMESSO_CON_RISERVA invece sì, come uno AMMESSO. I chip dei token per fase e i badge di grounding delle fasi non vengono ricostruiti (restano i totali in sidebar).
    • Recupero manuale di un'analisi scollegata (come è stato fatto il 06/10): il puntatore è nel file di sessione in storage/sessions/sess_* (analysis_id|s:16:"…"); va riportato all'id dell'analisi nel database (tabella analisi) senza ricaricare la pagina.

    Fase P08 (attori) che fallisce con un JSON troncato, e errori permanenti di Gemini

    Nel test di carico del 06/10/2026 il 17,5% delle analisi (10 su 57) falliva a P08 con «Il modello non ha restituito JSON conforme allo schema»: la risposta era un JSON troncato di 260.000-326.000 caratteri, cioè arrivava al tetto di 65.536 token di uscita (un ciclo di ripetizione). Non dipendeva dal carico ma dal tema, e nel 91% dei casi anche il secondo tentativo falliva: ogni analisi persa bruciava circa 130.000 token di uscita per niente. La causa esatta non è stata confermata (il testo completo non era conservato e Gemini aveva esaurito i crediti prima della diagnosi): le misure sotto sono prudenziali.

    • Schema (schemas/p08_attori.json): al massimo 4 fonti per attore (maxItems), governato dall'interruttore GEMINI_LIMITI_CAMPO_ABILITATO come i limiti di lunghezza dei campi. Attenzione: un maxItems sull'array attori di primo livello non si può usare, Gemini rifiuta la richiesta con HTTP 400 INVALID_ARGUMENT (verificato con chiamate reali il 06/10/2026: era stato messo e ha bloccato a P08 la prima analisi di prova); quello sulle fonti annidate è accettato.
    • Prompt (Phase08Attori): il paragrafo «LIMITI (obbligatori)» (12 attori, ciascuno una volta, 4 fonti) e, in fondo al prompt, la frase «LIMITI RINFORZATI: elenca al massimo 8 attori, ciascuno UNA sola volta, con testi brevi e al massimo 2 fonti per attore. Non ripetere nessun attore. Chiudi correttamente il JSON». Misurato con Gemini reale (richiesta di produzione, 3 temi che fallivano, semi diversi): senza la frase in fondo il 25% delle richieste (8 su 32) finiva in un ciclo; con la frase, 2 su 60 (3,3%) in due prove (0 su 30 e 2 su 30; Fisher p = 0,003). Attenzione: sostituire il paragrafo esistente con la sola frase non ha funzionato (5 su 30, 17%), e una «regola di brevità» per campo (2 frasi, 300 caratteri) nemmeno (13 su 32, 41%): la formulazione conta, e se si tocca il prompt va rimisurata. Non c'è un controllo che imponga il limite.
    • Tetto di uscita per fase (AbstractPhase::maxOutputTokens()): P08 usa 16.384 token invece di 65.536 (le risposte buone ne usano 1.100-2.200): un ciclo costa un quarto prima di fermarsi. Le altre fasi non cambiano.
    • Tre tentativi per P08 (AbstractPhase::maxTentativi(), gli altri restano a due): il ciclo è intermittente e i tentativi sono circa indipendenti. Con la frase di limiti il rischio di una analisi fallita a P08 stimato è circa 0,1% con due tentativi, il terzo è soprattutto un'assicurazione.
    • Secondo tentativo: dopo un JSON troncato non si reinserisce più nel prompt il testo della risposta rotta (conteneva l'inizio del ciclo e poteva indurlo di nuovo) ma un'istruzione di concisione, per P08 «al massimo 8 attori, una sola volta, al massimo 2 fonti per attore» (la stessa frase di «LIMITI RINFORZATI»). Per le violazioni dei validatori resta l'elenco delle regole violate.
    • Errori permanenti di Gemini (HTTP 400, 401, 402, 403, 404: crediti esauriti, chiave non valida, richiesta rifiutata): nessun nuovo tentativo e nessun tentativo «consumato»; l'utente vede un messaggio comprensibile («servizio non disponibile… contatta l'amministratore») invece del JSON grezzo con il link ad AI Studio, e potrà usare /continua dopo il ripristino. Il dettaglio tecnico (messaggio di Gemini) compare solo agli amministratori. Gli errori transitori (429, 5xx) restano gestiti dal limitatore e dai nuovi tentativi descritti sopra.
    • Avviso «in coda per il limite di Gemini» (solo modalità automatica): quando una chiamata attende nella coda del limitatore, o dopo un 429, l'endpoint manda una riga di streaming {"tipo":"attesa","motivo":"coda"|"retry", "stato":"in_corso"|"fine","secondi":N,"fase":…} e la barra di avanzamento mostra sotto di sé il messaggio con i secondi e la fase, finché la chiamata non riparte. Al massimo un avviso ogni 5 secondi. In modalità semi-automatica (una richiesta per fase, senza streaming) l'attesa resta silenziosa.
    • Cos'era il ciclo (diagnosi del 06/10/2026 con Gemini reale): non troppi attori (nel caso catturato l'attore era uno solo) ma un solo campo di testo, porzione_di_interesse, di 143.755 caratteri con 20 frasi diverse ripetute circa 35 volte; nasce nella seconda passata (struttura), non nella ricerca. Gemini non applica il maxLength dello schema. Frequenza intermittente, anche a parità di richiesta.

    Quale modello usa questa app?

    Quello impostato da GEMINI_MODEL in config-work.php (nel test, al momento, gemini-3.1-flash-lite; è un'impostazione per ambiente, quindi la produzione può averne un altro), con output strutturato (JSON conforme agli schemi di ogni fase). Per cambiarlo si modifica il file e non serve altro; il listino dei costi si aggiorna a parte da Token e costi. Il modello economico della modalità Wargame è WARGAME_MODELLO_VALUTAZIONE.

    I dati della mia analisi vengono inviati da qualche parte?

    I dati vengono inviati a Google Gemini API per l'elaborazione (tema, parametri, contesto dello spazio, ecc.). Non vengono archiviati su server terzi oltre Google Cloud; con EIL attivo (modalità Certificata o Mista) le domande di inquadramento vanno anche a EIL. L'analisi resta nel database (tabella analisi) e viene cancellata dopo ANALISI_RITENZIONE_GIORNI giorni; i log su file (che contengono il testo del tema) e i dati di Debug fasi restano sul server, leggibili solo dagli amministratori. Il costo mostrato in sidebar è una stima calcolata nel browser; il server applica la stessa formula per scalare la quota.

    Posso fare più analisi contemporaneamente?

    Le schede e le finestre dello stesso browser condividono la sessione, e quindi la stessa analisi: non sono indipendenti. Aprire la pagina in una seconda scheda mostra la scelta «Riprendi l'analisi» / «Nuova analisi»; scegliere «Nuova analisi» azzera quella in corso anche nella prima scheda. Per due analisi in parallelo usa browser o profili diversi (ognuno ha la propria sessione) oppure utenti diversi.

    Cosa succede se il modello genera un output che non rispetta lo schema?

    L'app ritenta automaticamente fino a 2 volte, iniettando l'errore nel prompt successivo perché il modello lo corregga. Se fallisce dopo i tentativi, la pipeline si ferma e mostra l'errore di validazione.

    Ulteriore aiuto: Se hai domande specifiche non coperte qui, riprovao il comando /stato per verificare lo stato corrente della pipeline.