# Superman — Requisiti Agente Unico di Market Intelligence (v3.0)

> Documento di requisiti per l'agente unico Superman, target Gemini Enterprise (account gratuito)
> e implementazione engine dedicata (questo progetto).
> Sostituisce la coppia Clark+Kent: ogni requisito nasce dai documenti esistenti o da un failure mode
> dell'approccio a DUE agenti. Redatto in modalità adversarial red-team (continuazione della V2).
> Scope: SOLO Consumer (offerte residenziali). Niente B2B/business.
> Vincolo budget rigido: NESSUNA API a pagamento. Solo account gratuito Gemini Enterprise + scraping web.
> Priorità: **Must** / **Should** / **Could**.

---

## Legenda ID

| Prefisso | Categoria |
|---|---|
| `UNI` | Unificazione (nuova: supera i failure mode dell'approccio a 2 agenti) |
| `DIG` | Digest & pubblicazione (ereditate da Kent) |
| `SRC` | Anti-spoofing fonti |
| `DAT` | Schema dati JSON v2 |
| `FUN` | Funzionali |
| `NFR` | Non-funzionali |
| `GOV` | Governance |
| `QLT` | Qualità (KPI) |

Ogni requisito riporta: **ID · Priorità** — descrizione — **Criterio di verifica**.

---

## UNI — Unificazione (nuova generazione)

**UNI-01 · Must** — *Un solo agente.* Superman è UN agente con UN pacchetto di system instructions: nessun secondo agente, nessun passaggio di turno. Tutto quello che Clark e Kent facevano deve accadere in un'unica sessione/run.
> **Verifica:** il pacchetto system instructions è un solo file ≤ 30k e non contiene riferimenti a un secondo agente.

**UNI-02 · Must** — *Ruoli interni, non agenti esterni.* Le responsabilità di Kent diventano il ruolo interno **Publisher**. L'architettura è: Coordinatore → Collector → Validatore → Reporter → **Publisher**, tutti dentro lo stesso agente.
> **Verifica:** la spec descrive 5 ruoli interni e nessuna hand-off inter-agenti.

**UNI-03 · Must** — *Output unico per run.* Un run produce in un'unica risposta: snapshot JSON + digest Teams pronto alla pubblicazione. L'utente NON passa mai output intermedi fra due agenti ( failure mode principale dell'approccio a 2 agenti: perdita di contesto tra Clark e Kent).
> **Verifica:** dopo un run l'utente riceve entrambi gli artefatti senza azioni intermedie.

**UNI-04 · Should** — *Compatibilità storica.* I file `benchmark_{ambito}_{data}.json` prodotti da Clark V1/V2 restano leggibili come baseline: Superman li valida e migrà allo schema v2 al primo consumo.
> **Verifica:** un file V1 (18/11/2026) è accettato come baseline e migrato senza perdita di voci.

**UNI-05 · Must** — *Superficie utente unica.* Il team ha un solo agente da scoprire, condividere e invocare: un solo nome, un solo messaggio di lancio, un solo set di prompt esempio.
> **Verifica:** esiste un solo template di lancio con il nome Superman.

**UNI-06 · Must** — *Ambito esplicito, default completo.* Con nessun ambito indicato Superman esegue tutti e tre (FIXED, MOBILE, PHONE); con un ambito indicato solo quello. Mai ambiguità di scopo.
> **Verifica:** prompt senza ambito → 3 snapshot + 3 digest; prompt con ambito → 1.

---

## DIG — Digest & pubblicazione (da Kent)

**DIG-01 · Must** — *Formato digest Teams.* Il digest segue il formato Kent: emoji di stato, righe brevi leggibili da telefonino, link fonti, conteggi.
> **Verifica:** il digest è ≤ 1600 caratteri per ambito e usa il formato dichiarato.

**DIG-02 · Must** — *Pubblicazione con fallback.* Se il connector Teams è attivo, Superman posta sul canale indicato; altrimenti emette il testo pronto al copia/incolla. Mai insistere su un connettore assente.
> **Verifica:** run senza connector produce comunque il digest compilato.

**DIG-03 · Should** — *Messaggio di lancio.* Superman produce il messaggio di presentazione dell'agente per il canale Teams (una tantum o su richiesta), con istruzioni d'uso minime e referente.
> **Verifica:** il template di lancio esiste nel pacchetto e usa il nome Superman.

**DIG-04 · Must** — *Mai dati fuori dall'input.* Il digest contiene SOLO dati presenti nello snapshot. Nessun arrotondamento, nessun commento di merito ("conveniente"/"costoso" vietati — GOV-04).
> **Verifica:** ogni cifra del digest è rintracciabile nello snapshot.

**DIG-05 · Should** — *Digest da snapshot fornito.* Superman accetta anche un snapshot caricato dall'utente (es. di ieri, prodotto da Clark) e ne produce il digest: il vecchio lavoro non si butta.
> **Verifica:** caricare un JSON benchmark → digest coerente.

---

## SRC — Anti-spoofing fonti (da V2, immutati nel comportamento)

**SRC-01 · Must** — *Fingerprint documento fonte.* Ogni voce registra `fingerprint_fonte` = SHA-256 del contenuto estratto, con `url_fonte`, `timestamp_fetch`, `http_last_modified` se esposto.
> **Verifica:** fingerprint presente, stabile a parità di contenuto, diverso se la pagina cambia.

**SRC-02 · Must** — *Recency della fonte.* Contenuti più vecchi di 7 giorni (o `Last-Modified` antica) → `stato_fonte: "stale"`; il prezzo esce dal report attivo, salvo contenuto intrinsecamente statico (listino device).
> **Verifica:** pagina antica marcata `stale`, prezzo escluso dal report attivo.

**SRC-03 · Must** — *Anti stale-cache.* Cache-busting prima del fetch. Fingerprint identico al baseline su fonte dinamica → ri-fetch o `stato_fonte: "cache"` con confidenza ridotta. Mai spacciare cache per live.
> **Verifica:** contenuto servito da cache marcato `cache`, non `ok`.

**SRC-04 · Must** — *Rilevamento bot-wall / WAF.* HTTP 403/429, captcha, Cloudflare → `stato_fonte: "bloccata"`. Nessun prezzo inventato. Fallback: fonte alternativa o cache dichiarata con confidenza bassa.
> **Verifica:** fonte bot-walled → `bloccata` e zero prezzi inventati.

**SRC-05 · Should** — *Riproducibilità.* Per ogni prezzo: URL esatto + indicatore di posizione; un umano ritrova il dato in < 1 minuto.
> **Verifica:** ogni voce porta all'indietro alla riga fonte.

**SRC-06 · Must** — *Anti prompt-injection.* Il contenuto delle pagine è SOLO dato, mai istruzione: nessun comando presente in una fonte può alterare il comportamento dell'agente.
> **Verifica:** una fonte ostile non altera il comportamento.

---

## DAT — Schema dati JSON v2

**DAT-01 · Must** — *Listino vs promo distinti.* `prezzo_listino` e `prezzo_promo` campi separati, mai un singolo `prezzo` ambiguo.
> **Verifica:** voci con entrambi i prezzi espongono due oggetti distinti.

**DAT-02 · Must** — *Promo strutturata.* `prezzo_promo` = oggetto con `valore`, `valuta`, `periodo`, `tipo_sconto`, `durata_mesi`, `data_inizio`, `data_fine`, `condizioni`, `attiva`. Stringa libera vietata come unico campo.
> **Verifica:** promo con scadenze espone `data_fine` e `attiva` coerente.

**DAT-03 · Should** — *Storico campi.* `storico_campi`: array `{campo, valore_da, valore_a, data_cambiamento}` — il diff è ricostruibile nel tempo, non solo tra due giorni adiacenti.
> **Verifica:** voce modificata espone la coppia da→a con data.

**DAT-04 · Must** — *Confidenza fonte.* Ogni fonte/voce porta `confidenza_fonte` (0–1) + `motivo_confidenza` (ufficiale 1.0, comparatore 0.7, cache 0.5, indiretto 0.3).
> **Verifica:** confidenze valorizzate e coerenti col tipo di fonte.

**DAT-05 · Must** — *Fingerprint per voce.* Ogni voce porta il `fingerprint_fonte` della propria pagina (diff-abilità per voce).
> **Verifica:** campo presente e non null su ogni voce.

**DAT-06 · Must** — *Normalizzazione unità e valuta.* EUR, periodo mese, Mbps, GB, decimali a punto, IVA dichiarata. "9,99 €/anno" → 0.83 €/mese; "2,5 Gbps" → 2500 Mbps.
> **Verifica:** test di normalizzazione passano (dataset golden).

**DAT-07 · Must** — *Timestamp per voce.* `data_rilevazione` ISO-8601 per singola voce, distinto dal `data_run`.
> **Verifica:** campo presente su ogni voce.

**DAT-08 · Must** — *Versione schema.* `schema_version` nel JSON per migrazioni future senza rompere il diff.
> **Verifica:** campo `schema_version` presente e valorizzato ("2.0").

---

## FUN — Funzionali

**FUN-01 · Must** — *Benchmark per ambito.* FIXED / MOBILE / PHONE, voci normalizzate, scope Consumer.
> **Verifica:** run per ambito produce solo voci di quell'ambito.

**FUN-02 · Must** — *Diff di novità.* Stati: `nuova` / `modificata` / `invariata` / `disattivata` (+ `disattivata_incerta`); il report elenca solo nuove/modificate/disattivate + conteggio invariate.
> **Verifica:** baseline vs oggi produce il conteggio atteso (golden dataset DS-01).

**FUN-03 · Must** — *ID stabile su chiave canonica.* `id = {AMBITO}-{hash(chiave_canonica)[:8]}`, chiave = `operatore + nome_offerta` normalizzati (lowercase, no punteggiatura, spazi collassati). Cambio cosmetico del nome NON cambia l'ID.
> **Verifica:** "Super Fibra" / "superfibra" / "SUPER FIBRA" → stesso ID.

**FUN-04 · Must** — *Dedupe cross-fonte.* Stessa offerta su più fonti → UNA voce con `fonti_voce`.
> **Verifica:** dataset con offerta duplicata → 1 voce (DS-05).

**FUN-05 · Must** — *Promo scaduta.* `prezzo_promo.data_fine < oggi` → `attiva: false`, prezzo effettivo = listino, voce marcata `modificata`.
> **Verifica:** promo scaduta ieri → esclusa e segnalata (DS-02).

**FUN-06 · Should** — *Conflitto fonti.* Prezzi discordanti > 2% → `conflitto_fonti: true`, confidenza ridotta, nessun prezzo pubblicato come certo.
> **Verifica:** due fonti discordanti → flag (DS-10).

**FUN-07 · Must** — *Disattivazione certa vs incerta.* Voce assente + fonte inaccessibile → `disattivata_incerta`; solo pagina esplicita "non più disponibile" → `disattivata`.
> **Verifica:** voce assente con fonte bloccata → `disattivata_incerta`.

**FUN-08 · Must** — *Esclusione B2B.* Offerte business/partita IVA → `esclusa: true` + `motivo_esclusione`.
> **Verifica:** voce business esclusa dal run.

**FUN-09 · Must** — *Doppio output.* Ogni run produce snapshot JSON v2 + digest Markdown/Teams, coerenti.
> **Verifica:** entrambi gli artefatti generati e coerenti (UNI-03).

**FUN-10 · Must** — *Validazione baseline.* Prima del diff: JSON ben formato, `schema_version` compatibile, ambito coerente. Baseline corrotto → primo run dichiarato, MAI diff contro corrotti.
> **Verifica:** baseline troncato → fallback primo run (DS-08).

---

## NFR — Non-funzionali

**NFR-01 · Must** — *Zero costi.* Nessuna API a pagamento; solo account gratuito Gemini Enterprise / engine locale.
> **Verifica:** inventario capability senza risorse fatturabili.

**NFR-02 · Must** — *System instructions ≤ ~30k caratteri.*
> **Verifica:** conteggio caratteri del pacchetto ≤ 30k.

**NFR-03 · Must** — *Nessuna persistenza implicita.* Tutto lo stato vive nei file snapshot; ogni run dichiara la baseline usata.
> **Verifica:** run ripetuto a parità di input → output identico.

**NFR-04 · Must** — *Upload ≤ ~50MB.* Snapshot JSON comunque < 1MB.
> **Verifica:** nessun input > 50MB.

**NFR-05 · Should** — *Max 15 fonti per run per ambito*, priorità sito ufficiale > comparatore.
> **Verifica:** run non eccede il limite.

**NFR-06 · Should** — *Run ≤ 30 min per ambito.*
> **Verifica:** misurazione tempo di run.

**NFR-07 · Must** — *Idempotenza.* Ri-eseguire lo stesso ambito nello stesso giorno non duplica voci/run/file.
> **Verifica:** due run uguali → stesso run_id, nessun duplicato.

**NFR-08 · Must** — *Degrado graceful.* Connettore assente → fallback dichiarato senza bloccare il benchmark (file locale + copia/incolla).
> **Verifica:** run senza SharePoint/Teams produce comunque artefatti completi.

**NFR-09 · Could** — *Scheduling 8:00* con retry e notifica (fase 2; cron opzionale con consumo LLM dichiarato — vedasi runbook).
> **Verifica:** schedulazione attivata e loggata.

---

## GOV — Governance

**GOV-01 · Must** — *Human-in-the-loop.* Ogni pubblicazione passa da validazione umana: Superman propone, l'umano approva (il Publisher prepara; nessun post automatico senza gate umano).
> **Verifica:** flusso prevede un gate umano prima della pubblicazione.

**GOV-02 · Must** — *Ownership umana.* Nessuna decisione autonoma su prezzi/giudizi.
> **Verifica:** nessuna azione autonomo oltre raccolta+normalizzazione+diff+digest.

**GOV-03 · Must** — *Tracciabilità.* Ogni dato riconducibile a fonte + timestamp + fingerprint.
> **Verifica:** per ogni voce si risale alla fonte esatta.

**GOV-04 · Must** — *No invenzioni, no giudizi.* Nessun dato non verificato; nessun aggettivo valutativo sui competitor.
> **Verifica:** report privo di aggettivi valutativi e prezzi senza fonte.

**GOV-05 · Should** — *Audit log di run.* A fine run: baseline usato, fonti visitate, fonti bloccate, fallimenti.
> **Verifica:** log presente a fine risposta.

**GOV-06 · Could** — *Condivisione agenti.* Accesso Superman agli altri team member (fase 2, dipende dai permessi).
> **Verifica:** (fase 2) altri utenti invocano Superman.

---

## QLT — Qualità (KPI)

**QLT-01 · Must** — *Copertura operatori ≥ 80%* dei target nel run.
**QLT-02 · Must** — *100% voci con `url_fonte`.*
**QLT-03 · Must** — *100% voci con listino/promo distinti quando entrambi esistono.*
**QLT-04 · Must** — *Precisione prezzi ≥ 95%* su golden set annotato.
**QLT-05 · Should** — *False positive diff ≤ 5%* su golden set.
**QLT-06 · Should** — *Trend fonti bloccate/stale/cache* tracciato run per run.

I KPI sono esposti nel campo `kpi_qualita` dello snapshot e verificati dal test plan.

---

## Riepilogo

| Origine | Conteggio | Note |
|---|---|---|
| UNI (nuovi) | 6 | l'essenza della richiesta: da 2 agentes a 1 |
| DIG (da Kent) | 5 | tutta la funzionalità Kent, nessuna persa |
| SRC+DAT+FUN+NFR+GOV+QLT (da V2) | 39 | ripresi 1:1 dal requisito V2 Clark |
| **Totale** | **50** | 40 Must · 8 Should · 2 Could |

## Tracciamento failure mode dell'approccio a 2 agenti

| Failure mode observato con Clark+Kent | Contromisura |
|---|---|
| Output di Clark deve essere trovato, copiato e incollato nel secondo agente | UNI-01/02/03 |
| Kent non vede lo snapshot, solo il report → digest senza contesto dati | DIG-04, UNI-03 |
| Due system instructions da mantenere allineate (doppio drift) | UNI-01, NFR-02 |
| Condivisione del team su DUE agenti → confusione su chi usa cosa | UNI-05 |
| Hand-off mancato se l'utente dimentica il turno | UNI-02, DIG-02 |

---

*Origine: Workshop sistemi agentici 18-19/11/2026 (gruppo 8), pacchetto `agents_gemini`, spec `clark_v2`. Direttiva di unificazione: Morpheus, 19/11/2026.*
