chore: refresh seed issues e policy del template

.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.py]
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

.gitattributes

@@ -0,0 +1,9 @@
+* text=auto eol=lf
+
+*.md text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.json text eol=lf
+*.txt text eol=lf
+*.sql text eol=lf
+*.py text eol=lf

.github/seed-issues/00_kickoff.md

@@ -1,48 +1,29 @@
 ---
-title: "[Kickoff] Definire domanda civica, perimetro e contratto iniziale del dataset"
+title: "[Kickoff] Definire perimetro, domanda e contratto iniziale"
 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.
+Aprire il progetto con un perimetro chiaro e un contratto minimo coerente con il template.
+
+Usare questa issue solo se il repo e appena nato o se il perimetro e ancora ambiguo.
 
 ## Checklist
 
-- [ ] Definire una sola domanda civica, chiara e misurabile
+- [ ] Definire una domanda guida chiara
 - [ ] 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 i path in config siano root-relative POSIX
 - [ ] 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
+- `dataset.yml` esiste ed e coerente con il contratto del template
+- il perimetro del progetto e leggibile nel `README`
+- `py -m pytest tests/test_contract.py` passa

.github/seed-issues/01_sources.md

@@ -0,0 +1,32 @@
+---
+title: "[Sources] Verificare fonte, licenza e configurazione di ingestione"
+labels: ["DATA", "METODO"]
+assignees: []
+---
+## Obiettivo
+
+Qualificare una fonte e codificare in modo riproducibile come il toolkit deve leggerla.
+
+Usare questa issue quando il blocco vero e ancora sulla fonte, non su CLEAN o MART.
+
+## Checklist
+
+- [ ] Identificare fonte primaria, URL canonico e frequenza di aggiornamento
+- [ ] Aggiornare `raw.sources[].type` e `raw.sources[].args` in `dataset.yml`
+- [ ] Documentare licenza, coverage e refresh in `docs/sources.md`
+- [ ] Registrare trade-off rilevanti in `docs/decisions.md`
+- [ ] Verificare che non esistano path assoluti o riferimenti locali
+- [ ] Rieseguire `py -m pytest tests/test_contract.py`
+
+## 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 minime su licenza, refresh e limiti noti
+- `py -m pytest tests/test_contract.py` passa

.github/seed-issues/02_raw.md

@@ -0,0 +1,32 @@
+---
+title: "[RAW] Rendere l'ingestione riproducibile e tracciabile"
+labels: ["DATA"]
+assignees: []
+---
+## Obiettivo
+
+Ottenere un layer RAW eseguibile e ripetibile, senza committare output in repo.
+
+Usare questa issue quando la fonte e gia stata scelta ma il run RAW non e ancora affidabile.
+
+## 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`
+- [ ] Confermare che `data/` non contenga output committati
+- [ ] Documentare eventuali eccezioni o failure modes in `docs/decisions.md`
+
+## 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>/`
+- l'input per CLEAN e deterministico

.github/seed-issues/04_clean.md → .github/seed-issues/03_clean.md

@@ -1,21 +1,14 @@
 ---
-title: "[CLEAN] Implementare normalizzazione, required columns e validazioni CLEAN"
+title: "[CLEAN] Normalizzare input e chiudere il contratto CLEAN minimo"
 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.
 
+Usare questa issue quando il problema vero e sulla lettura, normalizzazione o stabilita dello schema.
+
 ## Checklist
 
 - [ ] Implementare o aggiornare `sql/clean.sql`
@@ -25,17 +18,7 @@ Portare il dataset da RAW a CLEAN con SQL esplicita, schema documentato e valida
 - [ ] 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`
+- [ ] Loggare mapping o assunzioni non ovvie in `docs/decisions.md`
 
 ## File da toccare
 

.github/seed-issues/05_mart.md → .github/seed-issues/04_mart.md

@@ -1,21 +1,14 @@
 ---
-title: "[MART] Costruire tabelle analitiche e regole di validazione MART"
+title: "[MART] Costruire tabelle finali e validation rules essenziali"
 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.
 
+Usare questa issue quando CLEAN regge gia e il prossimo blocco e arrivare a un output leggibile.
+
 ## Checklist
 
 - [ ] Creare o aggiornare `sql/mart/<table>.sql` per ogni tabella dichiarata
@@ -26,16 +19,6 @@ Produrre uno o piu mart orientati a KPI e output finali, con tabella/e e validat
 - [ ] 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`
@@ -48,4 +31,4 @@ Mart pronti per dashboard o report, con SQL separata per tabella e regole di val
 - 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
+- il progetto produce almeno un mart leggibile e validabile