nis2-agile/docs/PIANO_GUIDA_PERCORSI_NIS2.md

Piano — «Guida a percorsi guidati» per NIS2 (dal metodo TRPG)

Origine: handover cross-prodotto scritto da Cristiano in trpg-agile/docs/HANDOVER_GUIDA_PERCORSI_CROSS_PRODOTTO.md (commit 696ce18). Regola: partire da lì, non da zero. Questo doc mappa il metodo TRPG sulla base che NIS2 ha GIÀ e definisce cosa copiare, le trappole da non ripetere e le fasi. ⚠️ Il repo trpg-agile NON è montato in questo devenv: per copiare i file serve montarlo RO, incollarli, o accesso host; la Guida live è su trpg.agile.software (5 min di prova valgono più di ogni spiegazione).

1. Che cos'è il metodo (TRPG)

Una Guida a percorsi guidati: l'AI naviga le schermate vere dentro una palestra di dati sintetici, narra capitolo per capitolo con evidenziazioni e dati live, e ogni capitolo ha un pulsante per chiedere all'assistente. Non è un video né un testo: è il prodotto reale, guidato.

Componenti TRPG (ordine di studio dall'handover):

1. La Guida live (trpg.agile.software) — riferimento esperienziale.
2. copilot-catalog/analisi-gpg.js — formato canonico dei contenuti: card con title/narr/explain/ask, bilingue IT/EN.
3. copilot-selectors/ — registro selettori per vista (es. organizzazione.js, costruito da zero).
4. screen-formazione.html + copilot-mode.js — hub + player immersivo + motore postMessage (commenti = trappole).
5. sql/104 — la palestra: seed idempotente su range ID riservato + reset config.
6. scripts/guida-e2e-browser.py — harness di test browser (da copiare pari pari).
7. Le due SEG di agosto — storia vera dei bug con cause esatte.

2. Cosa NIS2 ha GIÀ (non ripartire da zero) — vedi memoria project_demo_avatar

Componente TRPG	Equivalente NIS2 esistente	Stato
Guida/copilot runtime + postMessage	public/js/demo-mode.js + demo-selectors.js	Costruito, E2E PASS (headless)
Manifest capitoli/step	manifest 10 step ARIA (public/demo/nis2-tour-2026.json) + DemoController::buildManifest	Esiste
copilot-selectors/ (registro per vista)	docs/mappa-logica/* (22 viste) + docs/mappa-logica/SELETTORI_DEMO.md (131 vis. + 89 azioni)	Mappato; ~132 id stabili da iniettare
copilot-catalog/analisi-gpg.js (contenuti title/narr/explain/ask IT/EN)	DA CREARE — sorgente naturale = public/js/help.js (testi già validati) + TASSONOMIA_CORSO_NIS2	Gap principale
screen-formazione.html (hub+player)	DA CREARE (oggi guida.html/workflow.html sono statici)	Gap
sql/104 palestra + reset	org 996001 (RO) + 996002 (sandbox), range 996xxx, scripts/seed-demo-dataset.php + /api/demo/reset-dataset, guard applyDemoGuard	Esiste e collaudato
scripts/guida-e2e-browser.py	harness headless chrome già usato per il tour 10 step	Pattern già in casa
Persona narrante	ARIA_SUPPORT_NIS2 (id=4) live + sottodominio nis2.dimostrazione.agile.software	Esiste
Formazione con esame	TASSONOMIA_CORSO_NIS2 (10 moduli/28 lezioni, esame soglia 80%)	Progettata

Conclusione: a NIS2 mancano soprattutto il catalogo contenuti canonico (le card title/narr/explain/ask per vista) e l'hub/player screen-formazione. Palestra, selettori, guard, persona e harness ci sono già.

3. Le 3 trappole (le hanno già pagate) — applicate al dominio NIS2

1. Palestra pulita — nessuna lezione salva dati. Rischio reale in TRPG: una lezione corrompeva la config di calcolo, un'altra registrava near-miss veri ad ogni run. Per NIS2:
   • le lezioni girano in sola lettura su 996001 (guard applyDemoGuard già 403 sui verbi di scrittura) e in sandbox solo su 996002; nessuna lezione tocca config/valutazioni reali;
   • i cleanup "demo" DEVONO ESCLUDERE il range 996xxx — verificare docs/sql/reset-demo.sql (memoria: «NON usare reset-demo.sql» sul dataset golden) e il reset del supervisore/cron.
2. Verdetto di dominio prima di pubblicare. Le card entrano spente e si accendono solo dopo validazione dei contenuti. Per NIS2 il validatore è l'agente nis2-expert (e iso-27001-expert dove serve): ogni card normativa passa il verdetto prima di enabled:true; sui nodi non ratificati si scrive neutro (nessuna affermazione d'obbligo). Coerente con la regola prodotto «fonti certe» (AIService::authoritativeSourcesBlock).
3. Test solo nel browser reale. La "pagina bianca" di TRPG era invisibile ai test API. Per NIS2: harness E2E headless chrome con screenshot (già in uso), il DOM dump al timing reale è la verità (i falsi NOT_FOUND da virtual-time sono documentati nella memoria demo).

4. Formato card canonico da adottare (da analisi-gpg.js)

Per ogni capitolo/step di ogni vista:

{ key, view, selector, order,
  title:   { it, en },
  narr:    { it, en },   // cosa dice la guida mentre evidenzia
  explain: { it, en },   // approfondimento
  ask:     { it, en },   // domanda suggerita all'assistente ARIA
  enabled: false,        // OFF finché nis2-expert non ratifica
  sources: [...] }       // fonti certe (nis2_sources) per i nodi normativi

Sorgente contenuti NIS2: help.js (già validato) + TASSONOMIA_CORSO_NIS2 + mappa-logica.

5. Fasi (stima onesta dall'handover: ~1 giornata impianto, poi poche ore a percorso)

• F0 — Studio base TRPG (blocca finché non ho accesso): provare la Guida live + copiare analisi-gpg.js, copilot-selectors/, screen-formazione.html, copilot-mode.js, sql/104, guida-e2e-browser.py. Serve: montare trpg-agile RO qui, oppure incolli i file, oppure chiave SSH host.
• F1 — Impianto (~1 giorno): hub formazione.html + player + motore (adatta demo-mode.js), catalogo card vuoto, reset palestra con guardia range 996xxx, harness E2E screenshot.
• F2 — Primo percorso pilota (poche ore): una vista (proposta: Gestione Rischi, appena rifatta) → card title/narr/explain/ask IT/EN da help.js, validazione nis2-expert, accensione, E2E in browser.
• F3 — Estensione percorso-per-percorso + collegamento formazione/esame (soglia 80%) su sandbox 996002.

6. Cosa mi serve per riprendere la costruzione

1. Accesso a trpg-agile (mount RO nel devenv, oppure i file incollati, oppure chiave SSH host per leggerlo/vedere la Guida live).
2. Per il collaudo autenticato e il deploy-check: chiave SSH temporanea rigenerata (il push da devenv funziona già).

Nota: questo piano è additivo e non tocca codice di produzione; è il ponte tra l'handover TRPG e gli asset NIS2 esistenti.