DevEnv nis2-agileandClaude Opus 4.8
4d676f2e21
Pipeline a trittici (Esecutore->Revisore->Controllore avversariale), 6 trittici T1-T6. Tutto ADDITIVO: nessuna pagina/JS live modificata, produzione intatta. Swap non incluso. - public/vendor/bootstrap-italia/ : BI v2.18.1 self-hostato (CSS+JS bundle+16 woff2+sprite), MAI CDN - 16 pagine *-bi.html (login/register/onboarding/forgot/reset/index + dashboard/assessment/ risks/incidents/policies/supply-chain/training/assets/reports/settings) - public/js/common-bi.js : sidebar/topbar in markup BI (additivo, riusa stessi ID + common.js) - Verifica sul path servito reale: 16/16 -> 200, 0 CDN, 0 FontAwesome residui, parita ID/hook completa, WCAG AA - docs/SISTEMA_TRITTICI_AGENTI.md : design del sistema a trittici Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
148 lines
11 KiB
Markdown
148 lines
11 KiB
Markdown
# Sistema a Trittici di Agenti (Esecutore → Revisore → Controllore) — NIS2 Agile
|
||
|
||
> **Obiettivo**: eseguire lavori a rischio (es. rollout UI Bootstrap Italia, correzioni di conformità) con **qualità garantita da una catena a 3 agenti** per ogni unità di lavoro: **uno fa, uno controlla, uno ricontrolla** in modo avversariale. Almeno **5 trittici** (qui 6).
|
||
> **Principi del progetto incorporati**: *fonti certe* (niente invenzioni, tutto citato/verificato), **verifica sul path reale** (login/render vero, mai CLI/"a memoria"), **zero backend** per la UI, **produzione intatta** (worktree / pagine `-bi`), **incrementale** (un'ondata per volta).
|
||
> Tipo: design realizzativo · v1 · 2026-06-11.
|
||
|
||
---
|
||
|
||
## 1. Il protocollo "trittico" (3 agenti per unità di lavoro)
|
||
|
||
```
|
||
┌─────────────┐ artefatti ┌─────────────┐ difetti? ┌──────────────┐
|
||
IN ──▶│ A1 ESECUTORE│ ─────────────────▶ │ A2 REVISORE │ ──── sì ───────▶│ (rework A1) │
|
||
│ "fa" │ │ "controlla" │ ──── no ───┐ └──────────────┘
|
||
└─────────────┘ └─────────────┘ ▼
|
||
┌──────────────────────┐ PASS/FAIL
|
||
│ A3 CONTROLLORE │ ───────────▶ GATE
|
||
│ "ricontrolla" (avvers)│
|
||
└──────────────────────┘
|
||
```
|
||
|
||
| Ruolo | Cosa fa | Mentalità | Output |
|
||
|---|---|---|---|
|
||
| **A1 — Esecutore** | Implementa l'unità (es. converte N pagine a BI), self-host asset, scrive gli artefatti | costruttiva, segue gli acceptance criteria | file modificati + self-report (cosa, dove, come verificato) |
|
||
| **A2 — Revisore** | Verifica l'output di A1 contro i **criteri di accettazione** (conformità BI, WCAG, parità funzionale, zero backend) | critica ma collaborativa | verdetto + **lista difetti** (file:riga, severità) |
|
||
| **A3 — Controllore** | Re-review **indipendente e avversariale**: cerca ciò che A2 ha mancato, **verifica sul path reale** (la pagina si serve/renderizza? login funziona? niente regressioni?), conferma che i difetti siano reali e chiusi | "rompila": prova a smontare il lavoro | **GATE PASS/FAIL** + motivazione |
|
||
|
||
**Regole della catena**
|
||
- A2 e A3 sono **read-only** (non modificano): producono rilievi. Il rework lo fa A1 (loop A1↔A2 fino a "0 difetti bloccanti"), poi A3 dà il sigillo.
|
||
- **A3 ≠ A2**: lente diversa e adversariale, deve esercitare il *path reale* (curl della pagina servita via bind-mount, login vero), non test sintetici (lezione delle 3 nottate DB).
|
||
- **Gate FAIL** → l'unità torna ad A1 con i rilievi di A3; non si procede all'ondata successiva.
|
||
- **Fonti certe**: A1/A2/A3 citano sempre la fonte (BI docs, WCAG, file:riga); marcano `[da verificare]` ciò che non confermano.
|
||
|
||
---
|
||
|
||
## 2. Criteri di accettazione comuni (Definition of Done per ogni trittico UI)
|
||
1. **Conformità BI**: usa Bootstrap Italia v2.18.1 **self-hostato** (`public/vendor/bootstrap-italia/`), componenti/markup ufficiali, Blu Italia #0066CC, Titillium.
|
||
2. **Accessibilità WCAG 2.1 AA**: contrasti ≥ soglie, label associate, focus visibile, `aria-*`/alt, navigazione tastiera.
|
||
3. **Parità funzionale**: stessa logica (`api.js`/`common.js`), stessi `id`/flussi → **zero modifiche backend**; la pagina fa esattamente quel che faceva prima.
|
||
4. **Nessuna regressione**: la pagina si serve **200**, JS senza errori console, login/azioni reali OK (verifica sul path fpm reale).
|
||
5. **Produzione intatta** fino al gate: lavoro su pagine `-bi` / worktree; swap solo dopo PASS.
|
||
|
||
---
|
||
|
||
## 3. I 6 trittici (unità di lavoro — rollout Opzione B)
|
||
|
||
| # | Trittico | A1 Esecutore produce | A2/A3 verificano |
|
||
|---|---|---|---|
|
||
| **T1** | **Base & self-host** | `public/vendor/bootstrap-italia/` (CSS/JS/font self-hostati v2.18.1) + token AGID confermati (da AgileHub V2 o BI ufficiale) + pagina di smoke | asset serviti 200, font caricati, `loadFonts` ok, nessun riferimento CDN residuo |
|
||
| **T2** | **Pagine pubbliche** | login, register, onboarding, forgot/reset, landing → BI (riusando il pilota `login-bi.html`) | render BI, WCAG, login reale 200, redirect corretti |
|
||
| **T3** | **Sidebar/Topbar (componente)** | `common.js` `loadSidebar()`/topbar come componenti BI (header slim+main, sidebar) | si propaga a tutte le app-page senza romperle; voci/permessi intatti |
|
||
| **T4** | **App-pages onda A** | dashboard, assessment, risks, incidents, policies → BI | parità funzionale (grafici/form/azioni), WCAG, nessuna regressione |
|
||
| **T5** | **App-pages onda B** | supply-chain, training, assets, reports, settings, acn-gap, normative, whistleblowing, kb, companies, cross-analysis | idem T4 |
|
||
| **T6** | **WCAG & cross-check finale** | report contrasti/accessibilità su tutte le pagine + fix residui + rimozione pagine `-bi`/CDN | audit AA completo, 0 hardcoded color fuori token, suite verde end-to-end |
|
||
|
||
> ≥5 trittici richiesti → qui **6**. (Lo stesso schema è riusabile per l'**Asse A conformità**: es. T-AI = AI Act/GDPR nel registro; vedi `PROGETTO_REVISIONE_NIS2.md`.)
|
||
|
||
---
|
||
|
||
## 4. Orchestrazione "in background"
|
||
|
||
**Esecuzione**: i trittici girano **in pipeline** (un'unità entra in A1 mentre la precedente è già ad A2/A3 — niente barriere inutili), con **concorrenza limitata** e **gate** tra ondate dove serve l'ordine (T1 prima di tutto; T3 prima di T4/T5).
|
||
|
||
Due modalità:
|
||
- **(a) Workflow deterministico** (consigliato): un unico script orchestratore (`Workflow`) che fa `pipeline(unità, A1, A2, A3)` con i gate. Vedi skeleton §6. È ripetibile, journaled, con resume.
|
||
- **(b) Agenti in background manuali**: lanciare i 3 agenti per trittico via `Agent(run_in_background:true)`, leggere i report, gateare a mano. Più controllo, meno automazione.
|
||
|
||
**Stato condiviso & isolamento**
|
||
- Lavoro in **worktree isolato** (es. `/tmp/nis2-ui-bi`, branch `ui-bi`) → produzione `main` intatta.
|
||
- Ogni trittico scrive un **report** in `docs/revisione/Tn-report.md` (artefatti + verdetti A2/A3) → tracciabilità e input per il trittico successivo.
|
||
- I **token AGID** (output di T1) sono la single-source-of-truth per T2–T6.
|
||
|
||
**Sequenza dei gate**
|
||
```
|
||
T1 ─PASS─▶ T2 ─┐
|
||
├─PASS─▶ T3 ─PASS─▶ T4 ─┐
|
||
│ ├─PASS─▶ T6 (finale)
|
||
└────────────────▶ T5 ──┘
|
||
```
|
||
(T2 e T5 possono partire in parallelo dopo T1; T4 richiede T3 per la sidebar.)
|
||
|
||
---
|
||
|
||
## 5. Ruoli ↔ agenti specializzati
|
||
- A2/A3 dei trittici UI usano lente **UI/accessibilità**; per i contenuti normativi si innestano gli agenti già creati **`nis2-expert`** e **`iso-27001-expert`** (`.claude/agents/`) come A2/A3 dell'Asse A.
|
||
- Finché il harness non carica gli agenti nativi nella sessione, si usano agenti `general-purpose` con le istruzioni-persona iniettate (come fatto in R1/R2).
|
||
|
||
---
|
||
|
||
## 6. Skeleton orchestratore (Workflow) — pronto da adattare
|
||
```js
|
||
export const meta = {
|
||
name: 'trittici-ui-bi',
|
||
description: 'Rollout Bootstrap Italia a trittici Esecutore→Revisore→Controllore',
|
||
phases: [{title:'T1 Base'},{title:'T2 Pubbliche'},{title:'T3 Sidebar'},
|
||
{title:'T4 App-A'},{title:'T5 App-B'},{title:'T6 WCAG'}],
|
||
}
|
||
const VERDICT = { type:'object', properties:{ pass:{type:'boolean'}, difetti:{type:'array', items:{type:'string'}}, note:{type:'string'} }, required:['pass','difetti'] }
|
||
|
||
async function trittico(unit, phase) {
|
||
// A1 fa
|
||
const fatto = await agent(`ESECUTORE ${unit.titolo}: ${unit.task}. Zero backend; pagine -bi; report cosa/dove/come verificato.`, {phase, label:`A1:${unit.id}`})
|
||
// A2 controlla
|
||
let rev = await agent(`REVISORE ${unit.titolo}: verifica contro i criteri (BI self-host, WCAG AA, parità funzionale, no backend). Output difetti. Contesto:\n${fatto}`, {phase, label:`A2:${unit.id}`, schema:VERDICT})
|
||
// loop rework finché 0 difetti bloccanti (max 2 giri)
|
||
let giro=0
|
||
while(rev && !rev.pass && giro++<2){
|
||
await agent(`ESECUTORE ${unit.titolo}: correggi questi difetti:\n${(rev.difetti||[]).join('\n')}`, {phase, label:`A1-fix${giro}:${unit.id}`})
|
||
rev = await agent(`REVISORE ${unit.titolo}: ri-verifica.`, {phase, label:`A2-r${giro}:${unit.id}`, schema:VERDICT})
|
||
}
|
||
// A3 ricontrolla (avversariale, sul path reale)
|
||
const gate = await agent(`CONTROLLORE AVVERSARIALE ${unit.titolo}: re-review indipendente. ESERCITA IL PATH REALE (curl della pagina servita, login vero, niente test sintetici). Conferma 0 regressioni e difetti chiusi. PASS solo se tutto verde.`, {phase, label:`A3:${unit.id}`, schema:VERDICT})
|
||
return { unit:unit.id, rev, gate }
|
||
}
|
||
|
||
phase('T1 Base')
|
||
const t1 = await trittico({id:'T1', titolo:'Base & self-host BI', task:'self-host bootstrap-italia 2.18.1 + token AGID + smoke'}, 'T1 Base')
|
||
if(!t1.gate?.pass){ log('T1 FAIL — stop'); return { stop:'T1', t1 } }
|
||
|
||
// T2 e T5 in parallelo dopo T1; T3→T4 in sequenza
|
||
const UNITS = [
|
||
{id:'T2', titolo:'Pagine pubbliche', task:'login/register/onboarding/forgot/reset/landing → BI', phase:'T2 Pubbliche'},
|
||
{id:'T3', titolo:'Sidebar/Topbar', task:'common.js loadSidebar/topbar come componenti BI', phase:'T3 Sidebar'},
|
||
{id:'T5', titolo:'App-pages onda B', task:'supply-chain/training/assets/reports/settings/... → BI', phase:'T5 App-B'},
|
||
]
|
||
const par = await parallel(UNITS.map(u => () => trittico(u, u.phase)))
|
||
const t3 = par.find(x=>x?.unit==='T3')
|
||
const t4 = t3?.gate?.pass ? await trittico({id:'T4', titolo:'App-pages onda A', task:'dashboard/assessment/risks/incidents/policies → BI'}, 'T4 App-A') : null
|
||
phase('T6 WCAG')
|
||
const t6 = await trittico({id:'T6', titolo:'WCAG & cross-check', task:'audit AA completo + rimozione -bi/CDN + suite verde'}, 'T6 WCAG')
|
||
return { t1, par, t4, t6 }
|
||
```
|
||
|
||
---
|
||
|
||
## 7. Come si lancia (governance)
|
||
- **Costo**: ~3 agenti × 6 trittici (+ rework) = **~20–30 agenti**. È orchestrazione multi-agente esplicita → si lancia **solo su tua conferma** (`Workflow`), perché consuma molti token.
|
||
- **Avvio**: `Workflow({name:'trittici-ui-bi'})` dopo aver materializzato lo script da §6 (con i task reali) e creato il worktree.
|
||
- **Monitoraggio**: `/workflows` per la progress; ogni gate FAIL ferma l'ondata.
|
||
- **Reversibile**: tutto su worktree/pagine `-bi`; il `main` resta verde finché non approvi lo swap.
|
||
|
||
---
|
||
|
||
## 8. Riferimenti
|
||
- Progetto di revisione: `docs/PROGETTO_REVISIONE_NIS2.md` · Gap UI: `docs/VERIFICA_GAP_UI_AGID_BOOTSTRAP_ITALIA.md`
|
||
- Agenti esperti: `.claude/agents/nis2-expert.md`, `.claude/agents/iso-27001-expert.md`
|
||
- Pilota: `public/login-bi.html` · Bootstrap Italia v2.18.1 (italia.github.io/bootstrap-italia)
|