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.*