docs: PRD di progetto + fonti non-LOD Camera (convocazioni, note votazioni)

PRD.md in root: visione, 7 principi di prodotto (incluso URL human-readable
ovunque possibile), requisiti trasversali; prd-human-readable-urls.md marcato
come spec di dettaglio del principio 1.

lod-wiki/camera: nuova pagina convocazioni-commissioni.md (agenda prospettica
mobile.camera.it, dato assente dal LOD, rif #63); nota su schedaVotazione
ridondante col LOD in votazioni-ricerca-html.md; index aggiornato.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: aborruso

PRD.md

@@ -0,0 +1,48 @@
+# PRD — italianparliament-mcp
+
+Stato: vivente · derivato dal progetto realizzato · aggiornato 2026-07-12
+
+Documento sintetico di visione e principi. I requisiti di dettaglio e le decisioni tecniche vivono nei documenti collegati in fondo; questo file tiene insieme il "perché" e le regole trasversali che ogni intervento deve rispettare.
+
+## Visione e destinatari
+
+Rendere interrogabili i dati aperti del Parlamento italiano — Camera (`dati.camera.it`) e Senato (`dati.senato.it`) — senza dover conoscere SPARQL né la struttura dei grafi RDF.
+
+Il destinatario primario è il **giornalista parlamentare**; secondari ricercatori e analisti. La conseguenza guida ogni scelta: l'output deve essere verificabile, citabile e pronto per l'analisi, non un dump tecnico. Chi usa lo strumento vuole rispondere a una domanda giornalistica ("chi ha firmato questo ddl?", "come ha votato quel gruppo?") e poterla portare in un articolo.
+
+Tre modalità d'uso: **CLI** da terminale, **MCP server** dentro un client (Claude Desktop/Code), **Worker HTTP** remoto per la prova rapida. L'MCP orchestrato da un agente è il bersaglio principale; la CLI è la stessa capacità esposta a riga di comando e per lo scripting.
+
+## Principi di prodotto
+
+Derivati da come il progetto è stato costruito. Sono vincoli, non aspirazioni.
+
+1. **URL human-readable ovunque possibile.** Accanto all'identificatore tecnico (URI LOD, codice atto) l'output include, quando la risorsa ha una pagina pubblica, un `html_url`/`url` navigabile. Serve al giornalista per verificare alla fonte e per citarlo come link. Vale anche per le fonti non-LOD (scheda votazione, Bollettino, emendamenti). Dettaglio: [prd-human-readable-urls.md](docs/prd-human-readable-urls.md).
+2. **Output strutturato e agent-friendly.** Ogni comando restituisce CSV o JSONL pulito; gli errori sono messaggi chiari senza stack trace; naming coerente `risorsa + verbo`. Deve essere leggibile tanto da un umano quanto da un agente che lo pipeline.
+3. **CLI e MCP sempre allineati.** Ogni capacità esiste sia come subcommand CLI sia come tool MCP registrato, con lo stesso schema. Un intervento che tocca una delle due facce tocca anche l'altra; entrambe vanno testate.
+4. **Niente tool nuovo se il risultato è derivabile.** Se una domanda si risponde componendo i tool esistenti, non si aggiunge un tool o un flag: lo si dimostra con la pipeline. Si aggiunge capacità solo per dati realmente non ottenibili.
+5. **Correttezza garantita sulla legislatura corrente (19), best-effort sullo storico.** I pattern e le query sono verificati sulla 19; le legislature precedenti sono esposte ma meno battute. Dove l'incertezza esiste, va resa esplicita, mai nascosta.
+6. **Fonti non-LOD solo quando colmano un vuoto reale.** Il perimetro nativo è LOD/SPARQL. Si ricorre allo scraping di fonti HTML/PDF (`documenti.camera.it`, `www.senato.it`) solo per dati **assenti dal LOD** — es. emendamenti Camera (issue #62), audizioni/pareri di commissione, testo dei ddl Senato. Quando una fonte HTML replica un dato LOD già completo (es. le votazioni, coperte fino al voto nominale), **non** si integra: è ridondante.
+7. **Advocacy quando il dato manca a monte.** Se l'assenza è strutturale (dato non modellato dal gestore, non un limite di tooling), oltre al workaround si documenta il caso e si propone al gestore di esporlo come dato aperto.
+
+## Requisiti trasversali
+
+- **Verificabilità.** Ogni risultato deve poter essere ricondotto a una fonte ufficiale: URI LOD + URL human-readable.
+- **Nessun URL inventato.** Gli URL derivati localmente da un identificatore sono valorizzati solo se il pattern combacia, altrimenti stringa vuota.
+- **Uso locale come modalità piena.** Alcune fonti (`documenti.camera.it`, WAF di `senato.it`) bloccano il traffico da datacenter: la copertura completa è garantita da CLI/MCP installati in locale, non dal Worker remoto.
+- **Documentazione per il destinatario.** README e guide sono scritti per giornalisti, non per sviluppatori; la conoscenza LOD verificata (trappole, assenze, classi) è consolidata nel wiki `docs/lod-wiki/`.
+
+## Copertura funzionale (aree)
+
+Circa 48 tool raggruppabili per area: **persone** (deputati, senatori, ricerca, carriera, gruppi), **atti e iter** (ddl, firmatari, relatori, progresso, testo), **votazioni** (elenco, dettaglio nominale per deputato, gruppi), **emendamenti** (Senato via LOD; Camera via fonte HTML), **commissioni** (composizione, sedute, audizioni), **sindacato ispettivo**, **governo**, **aggregazioni** (rank, group-rank). Il catalogo puntuale e lo stato di copertura sono nelle gap-analysis collegate.
+
+## Fuori scope / roadmap
+
+- Estrazione del **contenuto** di pagine human-readable oltre al link (testo integrale delle schede).
+- Gap aperti prioritari: esito+cofirmatari degli emendamenti Camera (#62), pareri e audizioni di commissione dal Bollettino, copertura storica pre-legislatura 19.
+
+## Documenti collegati
+
+- [docs/prd-human-readable-urls.md](docs/prd-human-readable-urls.md) — spec di dettaglio del principio 1 (persone e atti).
+- [docs/user-stories-parlamento.md](docs/user-stories-parlamento.md) — user story giornalistiche.
+- [docs/gap-analysis-2026-06-28/](docs/gap-analysis-2026-06-28/) — copertura vs bisogni reali.
+- [docs/analisi-fonti-non-lod.md](docs/analisi-fonti-non-lod.md) e [docs/lod-wiki/](docs/lod-wiki/) — fonti, trappole e assenze verificate.

docs/lod-wiki/camera/convocazioni-commissioni.md

@@ -0,0 +1,45 @@
+---
+type: Reference
+title: Convocazioni delle commissioni — agenda prospettica (mobile.camera.it)
+description: Le convocazioni delle commissioni permanenti espongono l'ordine del giorno FUTURO delle sedute (data, ora, argomenti con codice atto e relatore, audizioni con auditi, previsione di voto). È un dato prospettico assente dal LOD, che è tutto consuntivo. Fonte HTML pulita, curl-friendly.
+resource: https://mobile.camera.it/convocazioni-commissioni-permanenti
+tags: [camera, non-lod, convocazioni, commissioni, agenda, odg, audizioni, mobile]
+timestamp: 2026-07-12
+---
+
+Le **convocazioni delle commissioni permanenti** pubblicano l'**ordine del giorno prospettico** dei lavori: cosa farà ogni commissione nei giorni a venire. È un dato **forward-looking assente dal LOD**, che espone solo il consuntivo (`ocd:seduta` passate, `ocd:discussione`, Bollettino). Copre quindi un vuoto reale e ad alto interesse giornalistico: *"cosa c'è all'ordine del giorno questa settimana", "quando si vota su X", "chi viene audito domani"*. Nessun tool attuale lo deriva.
+
+# Endpoint
+
+- **Indice**: `https://mobile.camera.it/convocazioni-commissioni-permanenti` → le 14 commissioni permanenti, ciascuna con link alla propria convocazione.
+- **Convocazione di una commissione**: `…/convocazioni-commissioni-permanenti/convocazioni?shadow_organo_parlamentare={ID}&idlegislatura=19`.
+- **Filtro temporale**: la pagina ha un selettore "Cerca per data" (mese/anno + giorno) per navigare lo storico e il futuro.
+
+`ID` è l'identificatore d'organo di `mobile.camera.it` (**diverso** dagli `idCommissione` del Bollettino): mappatura parziale verificata — 3501 = I (Affari costituzionali), 3505 = V (Bilancio), 3507 = VII (Cultura), 3508 = VIII (Ambiente), 3512 = XII (Affari sociali). L'indice va letto per ottenere tutti gli ID in modo affidabile, non costruiti a mano.
+
+Fonti sorelle nello stesso portale: *"Convocazioni Commissioni Bicamerali e d'inchiesta"* e *"Oggi in Commissione"*.
+
+# Struttura del dato
+
+HTML server-rendered, **curl-friendly** (nessun WAF/anti-bot come `documenti.camera.it`; da confermare se passa anche da IP datacenter/Worker). Per ogni giorno con sedute, l'OdG è semi-strutturato:
+
+- **data** (es. "Martedì 14 luglio 2026") e **ora** di inizio (`Ore 13`, `Ore 13.30`);
+- **tipo di seduta**: Audizioni, Comitato dei Nove, Comitato permanente per i pareri, Ufficio di presidenza, Esame di schemi di intesa, ecc.;
+- **argomenti** con **codice atto** (`C. 2822`, `Doc. CCXLVII`) e **relatore** (`Rel. …` / `Rell. …`);
+- **audizioni** con il nome degli **auditi** (es. Ministri Musumeci e Schillaci);
+- **previsione di voto** esplicita: `(Sono previste votazioni)` / `(Non sono previste votazioni)`;
+- sede quando diversa (es. commissioni riunite, Aula convegni del Senato).
+
+Codici atto (`C. NNNN`), relatori (`Rel\.?\s`) e orari (`Ore \d`) sono estraibili con regex; il resto dell'OdG è testo narrativo.
+
+# Esempio verificato (2026-07-12)
+
+I Commissione, `shadow_organo_parlamentare=3501`, settimana 13–16 luglio 2026. Tra le voci, l'agenda dell'esame emendamenti del ddl legge elettorale / voto fuorisede (caso reale seguito nel progetto):
+
+> Ore 13.30 — COMITATO DEI NOVE — *Disposizioni in materia di elezioni della Camera dei deputati e del Senato della Repubblica* (esame emendamenti **C. 2822 - 157 - 2236-A** – Rell. Alessandro Colucci, Iezzi, Pagano, Angelo Rossi)
+
+Conferma il legame atto portante ↔ abbinati già emerso dagli emendamenti ([assenti.md](assenti.md)): 2236 confluito nel testo unificato 2822.
+
+# Valutazione — candidata a tool nuovo
+
+A differenza delle votazioni (ridondanti col LOD) e in linea con gli emendamenti, qui il dato è **genuinamente assente e non derivabile**: un tool nuovo è giustificato (es. `committee-agenda` / `convocazioni`, per organo e per data). Per rapporto valore/costo è **davanti al Bollettino**: parsing più semplice del resoconto narrativo e dato prospettico che nessun'altra fonte del progetto copre. Complementare al Bollettino (consuntivo) e all'iter LOD (stato corrente/passato).

docs/lod-wiki/camera/index.md

@@ -14,6 +14,8 @@ Endpoint SPARQL: `https://dati.camera.it/sparql`. Ontologia OCD (namespace `http
 # Fonti non-LOD (HTML/PDF)
 
 * [getDocumento.ashx — router delle fonti non-LOD](getdocumento-router.md) - il servizio `CommonServices/getDocumento.ashx` serve, cambiando `sezione`/`tipoDoc`, testi dei ddl, schede-attività dei deputati e Bollettini delle Giunte e Commissioni. Mappa delle facce, copertura vs LOD e priorità di integrazione (scraping, non dato strutturato).
+* [Convocazioni delle commissioni — agenda prospettica](convocazioni-commissioni.md) - `mobile.camera.it` pubblica l'ordine del giorno FUTURO delle sedute di commissione (data, ora, argomenti+relatore, audizioni con auditi, previsione di voto). Dato prospettico assente dal LOD (tutto consuntivo): colma un vuoto reale, candidata a tool nuovo. Fonte HTML curl-friendly.
+* [Votazioni: ricerca HTML e ridondanza schedaVotazione](votazioni-ricerca-html.md) - form di ricerca votazioni per provvedimento (link voto→ddl che manca nel LOD); la scheda di dettaglio è invece ridondante col LOD (`votes` + `vote-detail`).
 
 # Assenti
 

docs/lod-wiki/camera/votazioni-ricerca-html.md

@@ -119,6 +119,10 @@ Non integrato nel progetto: è scraping HTML di un endpoint non documentato (fra
 1. **Prova indipendente** che il gap `ocd:rif_attoCamera` (issue #21) è puramente un problema del LOD e non di dato mancante a monte — anche questo canale "ufficiale ma non documentato" conferma lo stesso numero (62).
 2. **Fallback pratico** se in futuro servisse risolvere un DDL non ancora coperto dal parsing di `dc:description` (es. formati di titolo imprevisti): la ricerca full-text qui è fatta dal motore stesso della Camera, non da un regex nostro.
 
+# La scheda di dettaglio (`schedaVotazione.asp`) è ridondante col LOD — non integrare
+
+Diverso dal form di ricerca sopra: la scheda della singola votazione (`schedaVotazione.asp?...&RifVotazione=<seduta>_<n>&tipo=gruppi|dettaglio`) **non copre alcun vuoto del LOD**. Verificato il 2026-07-12 sulla votazione `587_2` (ODG 9/2736/39): il riepilogo (presenti/votanti/favorevoli/contrari/esito) è già in `votes`, e il **voto nominale per singolo deputato** (nome, voto, gruppo) è già in `vote-detail`. L'unico dato pre-confezionato solo qui è il *riepilogo percentuale di partecipazione per gruppo* (`tipo=gruppi`), ma è banalmente **derivabile** aggregando `vote-detail` per `group_acronym` — quindi niente fonte/tool nuovo. Le votazioni Camera sono anzi un punto forte del LOD (copertura fino al nominale), all'opposto di emendamenti e Bollettino. Il campo `url` di `votes` linka già a questa scheda per l'uso umano.
+
 # Citations
 
 [1] Intercettazione traffico con agent-browser (`network requests`) il 2026-07-01: nessuna chiamata XHR, singola POST server-rendered.

docs/prd-human-readable-urls.md

@@ -1,6 +1,6 @@
 # PRD — URL human-readable per le entità (persone e atti)
 
-Stato: bozza · 2026-06-29
+Stato: bozza · 2026-06-29 · spec di dettaglio del **principio 1** di [../PRD.md](../PRD.md)
 
 ## Problema
 
@@ -16,6 +16,10 @@ Per le persone è una funzione nuova (oggi assente). Per le leggi `html_url` esi
 
 Vincolo dichiarato dall'utente: garantire la correttezza **almeno per la legislatura corrente (19)**, perché i pattern URL dei siti istituzionali possono essere cambiati nel tempo e non è detto che valgano per le legislature passate.
 
+## Principio generale (linea guida di progetto)
+
+La regola non si limita a persone e atti: vale per **qualsiasi risorsa** che abbia una pagina pubblica corrispondente. Ogni volta che è possibile, l'output di un tool include un **URL human-readable** accanto all'identificatore tecnico. Motivo: il target è il giornalista, che usa quel link per (1) **verificare il dato alla fonte** e (2) **citarlo come link nel proprio articolo** — l'URI LOD non serve a nessuno dei due scopi. Si applica anche alle **fonti non-LOD** (scheda votazione, Bollettino delle Giunte e Commissioni, emendamenti, scheda-attività del deputato): i pattern sono nel wiki `docs/lod-wiki/camera/getdocumento-router.md`. Esempi già coperti oltre a persone/atti: `votes.url` → scheda votazione della Camera. Regola invariata: URL generato **localmente** dall'identificatore quando derivabile, **mai inventato** (stringa vuota se il pattern non combacia).
+
 ## Pattern URL verificati
 
 Mappatura URI SPARQL → URL scheda, verificata aprendo le pagine reali con browser: