[Task] Rafforzare il bridge RAW -> CLEAN

[Gabrymi93]

Obiettivo

Rendere piu chiaro e piu utile il passaggio RAW -> CLEAN nel toolkit, senza aggiungere nuova complessita inutile e senza cambiare il workflow base run all.

In particolare:

• rendere visibili i principali profile_hints gia prodotti dal RAW
• lasciare un artefatto riusabile dal clean gia dopo run raw
• chiarire il percorso operativo consigliato per dataset nuovi o sporchi

Contesto

Durante il lavoro su dataset reali come:

• IRPEF comunale
• popolazione ISTAT comunale

e emerso che il toolkit ha gia buona parte dei mattoni utili per il passaggio raw -> clean, ma oggi sono troppo dispersi:

• run raw scrive metadata.json con profile_hints
• profile raw scrive suggested_read.yml
• clean sa gia consumare suggested_read.yml

Il problema quindi non e tanto l'assenza di feature, ma la loro scarsa integrazione nel flusso operativo principale.

Questo porta a:

• aperture manuali di metadata.json
• passaggi poco intuitivi tra run raw e definizione del clean
• minore visibilita dei segnali utili gia disponibili

Criteri di completamento

• inspect paths espone in modo leggibile i principali raw profile hints o un blocco equivalente
• run raw scrive _profile/suggested_read.yml quando il file primario e profilabile e il comportamento e coerente con la artifact policy
• documentazione aggiornata sul workflow consigliato per il bridge raw -> clean

Collegamenti

[Gabrymi93]

Aggiornamento operativo.

Nel branch feat/raw-clean-bridge ho chiuso un primo blocco coerente del task, con due commit locali:

• 0f51999 Improve RAW to CLEAN bridge visibility
• 94f62fa Show RAW hints in status output

Perimetro coperto:

• run raw scrive _profile/suggested_read.yml in modo conservativo quando il file primario e profilabile
• inspect paths espone un blocco raw_hints con:
  • primary_output_file
  • path/presenza di suggested_read.yml
  • encoding, delim, decimal, skip
  • warnings del RAW
• status espone una vista sintetica degli stessi raw_hints
• documentazione aggiornata sul bridge raw -> clean

Scelta di perimetro:

• tenuto fuori schema diff multi-anno
• tenuto fuori il tema suggested_mapping / eventuale ritorno del concetto gen-sql

Verifica:

py -m pytest tests/test_cli_status.py tests/test_cli_inspect_paths.py tests/test_project_example_e2e.py tests/test_artifacts_policy.py tests/test_clean_duckdb_read.py -q

Esito:

• 22 passed

Per me questo chiude bene il task nella sua prima forma utile. I filoni successivi piu naturali sono:

1. schema diff multi-anno per dataset storici
2. lavoro separato su suggested_mapping, senza reintegrare un comando gen-sql dedicato