feat(validation): quality score, readiness estesa, transizioni blocking

[Gabrymi93]

Sintesi

Pipeline di validazione resa più robusta: quality score con gradiente,
transizioni bloccanti di default, readiness estesa con check di qualità.

Contesto collegato

Analisi dei gap nella validazione del toolkit (sessione 2026-06-20):

• Gap 5 — transizioni bloccanti: fail_on_row_drop_exceeded
• Gap 1 — quality score: gradiente 0-100 invece di binario ok/fail
• Gap 3 — quality score propagato a tutti i consumatori
• Gap 2 — readiness estesa con naming colonne, coverage regole, metadata

Cosa cambia

• Bug fix (transizioni non bloccavano mai, qualità senza gradiente)
• Nuova funzionalità del motore
• Nuovo plugin sorgente
• Modifica contratto pubblico (dataset.yml, path output, schema parquet)
• Refactor / performance
• Documentazione
• Dipendenze o CI

Impatto su contratti pubblici

• Struttura dataset.yml (nuovo campo, cambio obbligatorietà)
• Path output (nuovo layer, cambio percorso artifact)
• Schema parquet (nuova colonna, rename, cambio tipo)
• CLI o MCP tool (nuovo campo quality_score in validation JSON, quality_verdict)
• API pubblica del toolkit (firma funzione, classe, eccezione)

Note: Tutti i nuovi campi sono aggiuntivi (non rompono consumatori esistenti).
fail_on_row_drop_exceeded default True, opt-out per dataset.

Verifica

pytest tests/test_validate_layers.py tests/test_validate_rules.py tests/test_run_validation_gate.py tests/test_mcp_toolkit_client.py tests/test_config_loading.py tests/test_report_ops.py -q
pytest -m smoke -q
ruff check .
ruff format --check .
toolkit run full -c project-example/dataset.yml

• pytest passa (110 test)
• ruff check . passa
• mypy toolkit/ passa
• Smoke test passano (18/19, 1 skip S3)
• Modificati o aggiunti test con marker (policy)

Checklist PR

• Perimetro stretto: 4 gap correlati, stesso contratto centrale
• Issue collegata: analisi verbale in sessione
• Nessun modulo rimosso

Riepilogo modifiche

File	Cosa
core/config_models/mart.py	fail_on_row_drop_exceeded in TransitionConfig (default True)
core/validation.py	quality_score + quality_verdict in build_validation_summary(); error/warning text persistiti; check_transitions() supporta error mode
clean/validate.py	Propagazione errori da check_transitions()
mart/validate.py	Propagazione errori da check_transitions()
cli/inspect/readiness_ops.py	3 nuovi check (naming, coverage, metadata); ok=None escluso dal conteggio
cli/inspect/_helpers.py	quality_score + quality_verdict in _validation_summary_for_layer(); columns e rules
cli/inspect/report_ops.py	quality_score in layer validation report; fallback qualità
cli/cmd_run.py	qs=N in output CLI; recap warnings messaggi
project-example/dataset.yml	Aggiunto source_id per readiness
tests/test_validate_layers.py	9 nuovi test per quality score e transizioni blocking

Dettaglio nuovi campi pubblici

validation JSON su disco (raw_validation.json, clean_validation.json, mart_validation.json):

{
  "quality_score": 90,
  "quality_verdict": "buona",
  "errors": ["..."],
  "warnings": ["..."]
}

Run record (_runs/{dataset}/{year}/*.json):

"validations": {
  "raw": { "quality_score": 100, "quality_verdict": "buona", "errors": [], "warnings": [] }
}

Note per chi revisiona

• fail_on_row_drop_exceeded è True di default. Chi vuole il vecchio comportamento aggiunga fail_on_row_drop_exceeded: false nel transition config.
• I 3 nuovi check di readiness possono produrre needs-review anche su dataset funzionanti ma con naming o coverage parziali — è il comportamento voluto.
• Warning/error text nel run record capped a 20 messaggi per evitare run record enormi.