Riallinea project-template al nuovo assetto organizzativo di DataCivicLab

.github/seed-issues/00_kickoff.md

@@ -0,0 +1,48 @@
+---
+title: "[Kickoff] Definire domanda civica, perimetro e contratto iniziale del dataset"
+labels: ["LEAD", "METODO"]
+assignees: []
+---
+## Perche questa fase conta
+
+Qui si decide se il progetto ha una domanda utile, comprensibile e davvero sostenibile nel tempo.
+Un kickoff fatto bene evita di costruire dati che poi non rispondono alla domanda iniziale.
+
+## Output visibile al pubblico
+
+Una spiegazione chiara di cosa vuole capire il progetto e di quali dati usera.
+
+## Obiettivo
+
+Avviare il progetto dataset con perimetro chiaro, domanda civica misurabile e contratto toolkit-first coerente con il template.
+
+## Checklist
+
+- [ ] Definire una sola domanda civica, chiara e misurabile
+- [ ] Compilare `dataset.yml` con `dataset.name`, `dataset.years` e `root`
+- [ ] Verificare che i path in config siano root-relative POSIX
+- [ ] Confermare la struttura canonica `sql/clean.sql` e `sql/mart/<table>.sql`
+- [ ] Allineare ruoli e ownership con `docs/lab_links.md`
+- [ ] Verificare che `tests/test_contract.py` sia verde in locale
+
+## Output atteso
+
+Progetto inizializzato con contratto di base valido e documentazione minima pronta per il source onboarding.
+
+## Supporto operativo
+
+- notebook consigliato: `notebooks/00_quickstart.ipynb`
+- comando minimo: `py -m pytest tests/test_contract.py`
+
+## File da toccare
+
+- `dataset.yml`
+- `README.md`
+- `docs/lab_links.md`
+
+## Acceptance criteria
+
+- `dataset.yml` esiste in root ed e coerente con il contratto smoke reale
+- il perimetro del progetto e documentato in modo comprensibile
+- `pytest tests/test_contract.py` passa
+- il progetto puo passare alla fase Source onboarding senza ambiguita su nome dataset, anni e scope

.github/seed-issues/01_civic_questions.md

@@ -0,0 +1,47 @@
+---
+title: "[Questions] Esplicitare domande civiche, metriche e ipotesi iniziali"
+labels: ["METODO", "LEAD"]
+assignees: []
+---
+## Perche questa fase conta
+
+Un progetto dati utile nasce da domande chiare, non da una pipeline costruita nel vuoto.
+Questa fase serve a collegare il lavoro tecnico a un problema pubblico leggibile.
+
+## Output visibile al pubblico
+
+Un set di domande guida che spiega cosa il progetto prova a capire e con quali misure.
+
+## Obiettivo
+
+Definire le domande civiche che guideranno fonti, metriche, unità di analisi e output del progetto.
+
+## Checklist
+
+- [ ] 3-5 domande civiche esplicite
+- [ ] 3-5 metriche collegate
+- [ ] Ipotesi dichiarate
+- [ ] Coerenza con unità di analisi
+
+## Output atteso
+
+Una base pubblica e metodologica chiara da cui far discendere le scelte su fonti, CLEAN, MART e output finali.
+
+## Supporto operativo
+
+- notebook consigliato: nessuno, il lavoro e principalmente metodologico e documentale
+- file guida: `README.md`, `docs/overview.md`, `docs/decisions.md`
+
+## File da toccare
+
+- `README.md`
+- `docs/overview.md`
+- `docs/lab_links.md`
+- `docs/decisions.md`
+
+## Acceptance criteria
+
+- le domande guida sono scritte in linguaggio semplice
+- le metriche proposte sono coerenti con le domande
+- le ipotesi iniziali sono esplicitate
+- c'e coerenza fra domande, metriche e unità di analisi

.github/seed-issues/02_sources.md

@@ -0,0 +1,49 @@
+---
+title: "[Sources] Onboarding fonti, licenza, refresh e decisioni di ingestione"
+labels: ["DATA", "METODO"]
+assignees: []
+---
+## Perche questa fase conta
+
+Se la fonte non e chiara, tutto il resto del progetto diventa fragile.
+Questa fase serve a capire da dove arrivano i dati e con quali limiti.
+
+## Output visibile al pubblico
+
+Una scheda semplice delle fonti usate, con link e note di contesto.
+
+## Obiettivo
+
+Qualificare la fonte e codificare in modo riproducibile come il toolkit deve leggerla.
+
+## Checklist
+
+- [ ] Identificare fonte primaria, URL canonico e frequenza di aggiornamento
+- [ ] Aggiornare `raw.sources[].type` e `raw.sources[].args` in `dataset.yml`
+- [ ] Documentare licenza, coverage, refresh cadence e note in `docs/sources.md`
+- [ ] Registrare trade-off e assunzioni di ingestione in `docs/decisions.md`
+- [ ] Verificare che non esistano path assoluti o riferimenti locali
+- [ ] Rieseguire i contract tests
+
+## Output atteso
+
+Fonte verificata e configurata in `dataset.yml`, con documentazione sufficiente per procedere al layer RAW.
+
+## Supporto operativo
+
+- notebook consigliato: `notebooks/01_inspect_raw.ipynb`
+- comando minimo: `toolkit run raw --config dataset.yml`
+- dopo il run usa: `toolkit inspect paths --config dataset.yml --year <year> --json`
+
+## File da toccare
+
+- `dataset.yml`
+- `docs/sources.md`
+- `docs/decisions.md`
+
+## Acceptance criteria
+
+- la fonte e verificabile e documentata
+- `raw.sources` e compilato con campi sufficienti all'esecuzione
+- `docs/sources.md` contiene note su licenza, refresh e limiti noti
+- `pytest tests/test_contract.py` passa

.github/seed-issues/03_raw.md

@@ -0,0 +1,49 @@
+---
+title: "[RAW] Rendere riproducibile l'ingestione RAW con il toolkit"
+labels: ["DATA"]
+assignees: []
+---
+## Perche questa fase conta
+
+Questa e la base del progetto: se il dato in ingresso non e stabile o tracciabile, anche le analisi finali diventano deboli.
+
+## Output visibile al pubblico
+
+Una fonte acquisita in modo ripetibile, con traccia di cosa e stato usato e quando.
+
+## Obiettivo
+
+Ottenere un layer RAW eseguibile e ripetibile, senza committare output in repo.
+
+## Checklist
+
+- [ ] Verificare `raw.sources[]`, `primary` ed eventuale extractor in `dataset.yml`
+- [ ] Eseguire `toolkit run raw --config dataset.yml`
+- [ ] Usare `toolkit inspect paths --config dataset.yml --year <year> --json` per localizzare gli artifact RAW
+- [ ] Controllare `manifest.json`, `metadata.json` e `raw_validation.json`
+- [ ] Controllare metadata, manifest e validation report del RAW
+- [ ] Confermare che `data/` non contenga output committati
+- [ ] Aggiornare `docs/decisions.md` con eventuali eccezioni o failure modes
+
+## Output atteso
+
+RAW eseguibile con report minimi di validazione e metadata disponibili negli artifact di run.
+
+## Supporto operativo
+
+- notebook consigliato: `notebooks/01_inspect_raw.ipynb`
+- path attesi: `root/data/raw/<dataset>/<year>/`
+- comando di discovery: `toolkit inspect paths --config dataset.yml --year <year> --json`
+
+## File da toccare
+
+- `dataset.yml`
+- `docs/decisions.md`
+- `docs/sources.md`
+
+## Acceptance criteria
+
+- il run RAW completa o il blocco e documentato in modo riproducibile
+- nessun output RAW viene aggiunto sotto `data/`
+- gli artifact minimi del RAW sono attesi sotto `root/data/raw/<dataset>/<year>/`
+- il progetto puo passare a CLEAN con input RAW deterministico

.github/seed-issues/04_clean.md

@@ -0,0 +1,53 @@
+---
+title: "[CLEAN] Implementare normalizzazione, required columns e validazioni CLEAN"
+labels: ["DATA"]
+assignees: []
+---
+## Perche questa fase conta
+
+Qui il dato diventa davvero leggibile e confrontabile.
+Una buona fase CLEAN riduce errori, ambiguita e lavoro manuale futuro.
+
+## Output visibile al pubblico
+
+Un dataset piu chiaro, con colonne coerenti e significato documentato.
+
+## Obiettivo
+
+Portare il dataset da RAW a CLEAN con SQL esplicita, schema documentato e validazioni minime.
+
+## Checklist
+
+- [ ] Implementare o aggiornare `sql/clean.sql`
+- [ ] Allineare `clean.read`, `clean.required_columns` e `clean.validate` in `dataset.yml`
+- [ ] Verificare chiavi logiche, `not_null`, `min_rows` e duplicati
+- [ ] Eseguire `toolkit run clean --config dataset.yml`
+- [ ] Eseguire `toolkit validate clean --config dataset.yml`
+- [ ] Usare `toolkit inspect paths --config dataset.yml --year <year> --json` per localizzare il layer CLEAN
+- [ ] Aggiornare `docs/data_dictionary.md` per il layer CLEAN
+- [ ] Loggare assunzioni e mapping in `docs/decisions.md`
+
+## Output atteso
+
+Layer CLEAN riproducibile, con schema e regole di validazione sufficienti per alimentare i mart.
+
+## Supporto operativo
+
+- notebook consigliato: `notebooks/02_inspect_clean.ipynb`
+- path attesi: `root/data/clean/<dataset>/<year>/`
+- comando di discovery: `toolkit inspect paths --config dataset.yml --year <year> --json`
+
+## File da toccare
+
+- `sql/clean.sql`
+- `dataset.yml`
+- `docs/data_dictionary.md`
+- `docs/decisions.md`
+
+## Acceptance criteria
+
+- `sql/clean.sql` legge da `raw_input`
+- `clean.required_columns` e aggiornato
+- `clean.validate` copre almeno chiavi, `not_null` e `min_rows` quando applicabile
+- rowcount sanity e duplicate check sono stati eseguiti
+- il progetto puo passare a MART senza ambiguita sullo schema CLEAN

.github/seed-issues/05_mart.md

@@ -0,0 +1,51 @@
+---
+title: "[MART] Costruire tabelle analitiche e regole di validazione MART"
+labels: ["DATA", "METODO"]
+assignees: []
+---
+## Perche questa fase conta
+
+Qui il progetto inizia a produrre risposte utilizzabili.
+I mart sono la parte che alimenta analisi, dashboard e insight condivisibili.
+
+## Output visibile al pubblico
+
+Tabelle finali leggibili, da cui ricavare indicatori e confronti.
+
+## Obiettivo
+
+Produrre uno o piu mart orientati a KPI e output finali, con tabella/e e validation rules esplicite.
+
+## Checklist
+
+- [ ] Creare o aggiornare `sql/mart/<table>.sql` per ogni tabella dichiarata
+- [ ] Allineare `mart.tables` in `dataset.yml` e aggiungere eventuali regole di validazione supportate dal toolkit
+- [ ] Eseguire `toolkit run mart --config dataset.yml --year <year>`
+- [ ] Eseguire `toolkit validate --config dataset.yml --year <year>`
+- [ ] Usare `toolkit inspect paths --config dataset.yml --year <year> --json` per localizzare i mart
+- [ ] Verificare required columns, chiavi, `not_null`, `min_rows` e KPI sanity
+- [ ] Aggiornare `docs/data_dictionary.md` con granularita, KPI e semantica dei mart
+
+## Output atteso
+
+Mart pronti per dashboard o report, con SQL separata per tabella e regole di validazione chiare.
+
+## Supporto operativo
+
+- notebook consigliato: `notebooks/03_explore_mart.ipynb`
+- comando minimo: `toolkit run mart --config dataset.yml`
+- comando di discovery: `toolkit inspect paths --config dataset.yml --year <year> --json`
+
+## File da toccare
+
+- `sql/mart/<table>.sql`
+- `dataset.yml`
+- `docs/data_dictionary.md`
+- `docs/decisions.md`
+
+## Acceptance criteria
+
+- ogni tabella dichiarata in `mart.tables[]` ha un file SQL dedicato
+- eventuali regole MART dichiarate in `dataset.yml` sono coerenti con le tabelle pubblicate
+- rowcount sanity e duplicate check sono stati eseguiti
+- il progetto puo passare a QA con mart leggibili e validabili