v1 del toolkit come runtime tecnico stabile

[Gabrymi93]

🧾 Pull Request – DataCivicLab

🔗 Issue collegata

Closes #1

🎯 Contesto

Questa PR prepara e consolida la v1 del toolkit come runtime tecnico stabile dei repo dataset DataCivicLab.

Nel nuovo assetto dell’ecosistema:

• .github gestisce policy condivise, community health e UX organizzativa
• dataciviclab è l’hub pubblico dell’organizzazione
• project-template è il template operativo dei repo dataset
• toolkit deve restare il motore tecnico della pipeline e la fonte della documentazione runtime

La PR chiude il lavoro di hardening, riallineamento documentale e chiarimento del contratto stabile tra toolkit, project-template e repo dataset.

⚙️ Cosa cambia

• consolida il workflow canonico del toolkit:
  • run all
  • validate all
  • status
  • inspect paths
• rafforza il contratto di config/path/output:
  • path relativi risolti rispetto a dataset.yml
  • helper stabile inspect paths --json per notebook e repo dataset
• rifocalizza la documentazione del toolkit:
  • README centrato sul percorso base
  • docs separate per workflow advanced, feature stability e notebook contract
• chiarisce il ruolo del toolkit nell’ecosistema DataCivicLab
• mantiene le feature advanced supportate ma fuori dall’happy path
• prepara la repo alla pubblicazione come v1

📊 Impatto su dati / metodo / dashboard

Indicare se questa PR impatta:

• RAW
• CLEAN
• MART
• Dashboard
• Metodo
• Documentazione
• Bugfix
• Nessun impatto dati

Effetti su replicabilità e confrontabilità:

• migliora la replicabilità dei repo dataset perché riduce la dipendenza dal cwd e da logiche di path ricostruite a mano
• migliora la confrontabilità tra repo clonati dal template, grazie a un contratto più stabile su config, output e notebook
• non introduce logica dataset-specifica

🧪 QA Checklist

• Ho testato il codice / notebook
• Non rompe pipeline esistenti
• Naming coerente (snake_case, convenzioni Lab)
• Documentazione aggiornata
• Ho collegato l’issue corretta

Verifiche eseguite:

• test CLI e path contract
• test inspect paths
• smoke su project-example
• ruff check
• CI matrix già predisposta su Ubuntu/Windows e Python 3.10/3.11

📝 Note per i reviewer

Aspetti da verificare con attenzione:

• il README deve presentare il toolkit come motore tecnico, non come hub organizzativo
• inspect paths deve restare minimale, read-only e notebook-friendly
• la distinzione tra workflow canonico e workflow advanced deve essere netta
• la repo deve risultare coerente con il nuovo assetto:
  • .github = policy condivise
  • dataciviclab = hub pubblico
  • toolkit = runtime tecnico
  • project-template = template operativo dei repo dataset