From 0bf17db50a7d4dcc4df41381ec76ddaa978a3581 Mon Sep 17 00:00:00 2001 From: DevEnv nis2-agile Date: Mon, 10 Aug 2026 14:11:52 +0200 Subject: [PATCH] [DOCS] Piano Guida a percorsi guidati NIS2 (dal metodo TRPG): mapping su asset esistenti + 3 trappole + fasi Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/PIANO_GUIDA_PERCORSI_NIS2.md | 80 +++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 docs/PIANO_GUIDA_PERCORSI_NIS2.md diff --git a/docs/PIANO_GUIDA_PERCORSI_NIS2.md b/docs/PIANO_GUIDA_PERCORSI_NIS2.md new file mode 100644 index 0000000..2738dfd --- /dev/null +++ b/docs/PIANO_GUIDA_PERCORSI_NIS2.md @@ -0,0 +1,80 @@ +# 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.*