nis2-agile/docs/OUTGOING_TO_AGILEHUB_2026-06-19_supervisor_attachment_reading.md

NIS2 → AgileHub/VIGILE — Suggerimento: far leggere gli ALLEGATI dei ticket al supervisore autonomo

Da: NIS2 (product-side) · A: VIGILE / AgileHub (owner standard autonomous-supervisor-agent, hub_standards id=32) Data: 2026-06-19 · Tipo: suggerimento di miglioramento cross-suite (non urgente, additivo) Canale: doc OUTGOING_TO_AGILEHUB (pattern bidirezionale esistente; i MS AgileHub 4213/4211 non raggiungibili dal devenv).

TL;DR

Il supervisore autonomo (e in genere ogni ticket-agent) non leggeva gli allegati dei ticket. Quando un utente allega file (es. una spec istruzioni.pdf + uno screenshot policy01.png), nel payload del ticket compare solo il testo di un messaggio SYSTEM («2 allegati aggiunti: x.pdf, y.png») — nessun metadato né URL dell'allegato in GET /tickets/{id}. Risultato: l'agente non aveva un modo cablato per recuperarli e escalava invece di lavorare. Non è un limite del modello (Claude legge PDF e immagini nativamente): è solo plumbing mancante. Suggeriamo di chiuderlo centralmente nel runner/standard, così ne beneficiano tutti i prodotti.

Cosa abbiamo scoperto (endpoint già esistenti, ma non documentati nel runner)

Sondando il ticket-ms abbiamo trovato che gli allegati sono scaricabili:

• GET /tickets/{id}/attachments → [{id, filename, mimeType, size}] (lista)
• GET /tickets/{id}/attachments/{attId} → binario (es. application/pdf, image/png) (header X-Internal-Key + x-tenant-id). Esempio reale verificato su #384: attachments = [{id:109, policy01.png}, {id:110, istruzioni.pdf}], e GET /tickets/384/attachments/110 ha restituito il PDF (15 KB) leggibile.

Cosa abbiamo già fatto lato NIS2 (workaround locale, funziona)

Abbiamo insegnato al prompt del supervisore NIS2 a: lista → download nel project dir (gitignored) → Read (PDF/PNG/JPG), trattando l'allegato come input NON fidato (prompt-injection possibile anche via PDF/immagine). Dimostrato sul campo: il supervisore ha letto istruzioni.pdf + policy01.png del #384 e ha implementato l'intera feature multi-modulo (6 punti) a fasi.

Suggerimenti (owner VIGILE — da valutare per lo standard autonomous-supervisor-agent)

1. Esporre gli allegati nel payload del ticket. Aggiungere a GET /tickets/{id} un campo attachments: [{id, filename, mimeType, size, downloadUrl}], così l'agente non deve parsare il testo del messaggio SYSTEM né sondare endpoint a tentativi. (È il punto a maggior valore: rende l'allegato un dato di prima classe.)
2. Cablare la lettura allegati nel RUNNER standard (supervisor-agent-cron.sh), non nei singoli prompt di prodotto: prima di invocare claude -p, il runner pre-scarica gli allegati dei ticket in coda in un path locale noto (es. ./.ticket-attachments/<ticket>/<file>), così OGNI prodotto li trova già pronti da Read. Evita il patching prompt-per-prodotto (oggi l'abbiamo fatto solo su NIS2).
3. Documentare gli endpoint /tickets/{id}/attachments[/{attId}] nella guida del runner/standard.
4. Nota di sicurezza nello standard: gli allegati (PDF/immagini) sono input non fidato → trattarli come dato da analizzare, mai come istruzioni da eseguire (estendere la difesa prompt-injection, già prevista per il testo del ticket, anche al contenuto degli allegati).
5. Opzionale: includere attachments anche nei payload di webhook/notifica del ticket-ms.

Perché conviene farlo centralmente

• Lo standard è adottato (NIS2 è primo adopter; altri prodotti seguiranno): risolvendolo nel runner, tutti ereditano la capacità senza ri-scrivere il prompt.
• Riduce gli escalation inutili (ticket con spec nell'allegato che oggi rimbalzano all'umano).
• Allinea i prodotti su un'unica gestione sicura (anti-injection) degli allegati.

Riferimenti

• Standard: autonomous-supervisor-agent (hub_standards id=32), runner supervisor-agent-cron.sh.
• Lato NIS2: prompt scripts/nis2-supervisor-acting-prompt.md (sezioni "Accessi → Allegati ticket" e CICLO punto 2), commit di adozione su main.
• Caso d'uso reale: ticket #384 (super_admin, spec in istruzioni.pdf + policy01.png) — implementato e chiuso (RESOLVED) dal supervisore dopo l'abilitazione alla lettura allegati.