docs: document application skill contract

2026-07-23 19:44:07 +02:00
parent 17bca2b2cb
commit 5d34447975
2 changed files with 213 additions and 0 deletions
@@ -0,0 +1,212 @@
+# Skill operative dell'applicazione
+
+## Scopo di questa pagina
+
+Nel repository esistono diversi file denominati `SKILL.md`, ma non tutti appartengono al runtime di ThothII. La skill applicativa effettivamente usata dal workflow NL→SQL è:
+
+```text
+harness/.pi/skills/tht-sessione/SKILL.md
+```
+
+I file presenti in `ChironeWp3/`, in `Thoth/ThothAI/` o nei worktree sono relativi ad altri progetti, strumenti o ambienti di sviluppo. Non fanno parte del contratto operativo di una sessione ThothII.
+
+## Che cos'è `tht-sessione`
+
+La skill dichiara il nome `tht-sessione` e si descrive come orchestratore del workflow Thoth in otto fasi: chiarimento della domanda, memory, riscrittura, schema-linking, sintesi, piano CTE, SQL finale e datamart.
+
+Non è una semplice raccolta di suggerimenti per il modello. È il contratto operativo che stabilisce:
+
+- quali passaggi devono essere eseguiti;
+- quali comandi `tht` usare;
+- quali decisioni richiedono il reviewer;
+- quando una fase può avanzare;
+- quali artefatti devono essere persistiti;
+- quali decisioni sono locali alla domanda e quali possono essere riutilizzate.
+
+Il file stesso definisce questa regola: ogni comando, flag e comportamento necessario deve essere già descritto nella skill o nei suoi documenti di riferimento. Il modello non deve esplorare il codice sorgente per ricostruire il funzionamento degli strumenti.
+
+Questa scelta ha una motivazione precisa: un modello remoto potrebbe spendere il turno iniziale leggendo repository, `--help`, test e file casuali invece di affrontare la domanda dell'utente. Un contratto già iniettato riduce la deriva procedurale e rende il bootstrap deterministico.
+
+## Come viene caricata
+
+La skill non viene lasciata al modello come primo compito da scoprire. L'estensione Pi la legge quando viene caricata e la inserisce integralmente nel system prompt del gate:
+
+```text
+harness/.pi/extensions/tht-gate.js
+        └── ../skills/tht-sessione/SKILL.md
+```
+
+Il gate aggiunge inoltre istruzioni di kickoff per distinguere:
+
+- nuova sessione (`/nuova-domanda`);
+- ripresa (`/riprendi-sessione <id>`);
+- sessione già creata con id noto;
+- contesto di retrieval già fornito dal backend.
+
+Il caricamento integrale evita che il modello debba usare `find`, `ls`, `cat` o strumenti generici per recuperare istruzioni operative. È una misura di affidabilità, non soltanto di performance.
+
+Riferimenti implementativi: [tht-gate.js](../harness/.pi/extensions/tht-gate.js:50) e [tht-gate.js](../harness/.pi/extensions/tht-gate.js:832).
+
+## Rapporto tra skill, workflow e gate
+
+I tre componenti hanno responsabilità diverse:
+
+| Componente | Responsabilità |
+| --- | --- |
+| `workflow.yaml` | Fonte strutturale delle fasi, dei tipi di decisione e degli output |
+| `SKILL.md` | Istruzioni operative e disciplina che il modello deve seguire |
+| `tht-gate.js` | Enforcement: widget, persistenza, controlli e blocco dei bypass |
+
+La skill descrive il comportamento atteso; il gate impedisce che il modello lo aggiri. Per esempio, la skill prescrive che una decisione venga registrata tramite un reviewer tool, mentre il gate blocca l'uso diretto di comandi come `tht decision add` o `tht phase advance`.
+
+Questo doppio livello è intenzionale: il testo guida il modello, il codice protegge lo stato persistito anche quando il modello interpreta male un'istruzione.
+
+## Principi non negoziabili
+
+### Una domanda al reviewer per volta
+
+Il modello deve presentare un singolo punto decisionale, attendere la risposta e soltanto dopo proseguire. Questo evita che una risposta ambigua venga interpretata come approvazione di più passaggi non esaminati.
+
+### La conferma umana è obbligatoria
+
+Il modello propone; il reviewer approva, corregge, rifiuta o lascia aperta un'ambiguità. Non è consentito promuovere tabelle, applicare memory, fissare filtri o approvare SQL senza decisione esplicita.
+
+### Una decisione, un comando
+
+Ogni cambiamento dello stato passa da un comando `tht` mediato dal gate. Il ledger append-only è la fonte di verità: ciò che non è registrato non è avvenuto.
+
+### Nessuna esplorazione ad hoc
+
+La skill vieta di usare il repository come documentazione implicita. Le motivazioni sono:
+
+- evitare che il modello inventi un comando osservando codice non contrattuale;
+- evitare di leggere dati o segreti fuori dal perimetro della sessione;
+- mantenere il workflow riproducibile tra workstation, container e server;
+- rendere i test del gate indipendenti dall'iniziativa del modello.
+
+### Rollback semantico
+
+Dopo una riapertura il modello riparte dalla fase indicata esaminando gli artefatti ancora validi. Non deve ricreare inutilmente gli artefatti che non sono stati invalidati. `effective_decisions()` filtra le decisioni ormai stale.
+
+## Le otto fasi
+
+### Fase 1 — Chiarimento
+
+Il modello identifica l'ambiguità con maggiore impatto sul significato della query e presenta subito il relativo widget.
+
+Le interpretazioni mutuamente esclusive usano `reviewer_select`; quando più risposte possono essere vere si usa `reviewer_decide` multiselect. Ogni scelta concreta diventa una decisione `concept_clarified`.
+
+Motivazione: la semantica della domanda deve essere fissata prima di scegliere tabelle o SQL. I chiarimenti costituiscono inoltre la materia prima delle memory future.
+
+### Fase 2 — Memory
+
+La skill ordina di cercare memory con:
+
+```text
+tht memory search "<domanda>" --session <id> --json
+```
+
+Sono riutilizzabili solo le memory `concept_clarified`. Le scelte `table_promoted`, `table_excluded`, `column_promoted` e tutte le decisioni dipendenti dalla singola query non devono essere salvate, cercate o proposte come memory.
+
+Il reviewer decide in un'unica checklist, con massimo cinque candidati. Una memory selezionata viene applicata nella sessione corrente come nuovo `concept_clarified`; una deselezione significa non applicarla ora, non cancellarla dal patrimonio globale.
+
+Motivazione: il significato di un concetto può trasferirsi tra domande, mentre la scelta delle tabelle dipende dal problema, dal periodo, dalle metriche e dallo schema-linking specifici.
+
+### Fase 3 — Riscrittura
+
+Il modello produce una domanda riscritta con popolazione, condizioni, termini chiariti e output atteso. `rewrite_question` persiste `question.md` e chiude la fase.
+
+La riscrittura è separata dal chiarimento per rendere visibile al reviewer il risultato semantico prima di entrare nella progettazione SQL.
+
+### Fase 4 — Schema-linking
+
+Il modello usa il catalogo e il retrieval pack per proporre tabelle e colonne. Il reviewer cura:
+
+- tabelle da promuovere o escludere;
+- colonne di output;
+- join necessari.
+
+Le tabelle promosse e le colonne promosse sono decisioni della domanda e finiscono in `schema_linking.json`; non diventano memory.
+
+La skill impone inoltre un gate separato per i join. Questo impedisce di nascondere la logica relazionale dentro una lista di tabelle e consente al reviewer di verificare le cardinalità e le chiavi in modo esplicito.
+
+### Fase 5 — Sintesi
+
+Il modello verifica che domanda riscritta, assunzioni e schema-linking siano coerenti. La fase si chiude con una conferma di fase dopo `tht session check`.
+
+Motivazione: è un checkpoint semantico prima di produrre il piano SQL, utile per intercettare contraddizioni quando il problema è ancora correggibile.
+
+### Fase 6 — Piano CTE
+
+Il modello scompone la domanda in CTE nominati, con scopo, dipendenze, tabelle, filtri e colonne di output. Ogni risultato CTE viene presentato con `reviewer_confirm kind:"cte_result"`.
+
+L'approvazione dell'ultimo CTE chiude automaticamente la fase. L'artefatto persistito è strutturato (`cte_plan.json`, file SQL dei CTE e test), così il piano può essere ripreso e verificato senza transcript.
+
+### Fase 7 — SQL finale
+
+Il modello genera `sql_final.sql`, esegue la validazione prevista e chiede `reviewer_confirm kind:"sql"`. La conferma registra `sql_approved` e chiude la fase.
+
+La separazione dal piano CTE consente di approvare prima la strategia e poi l'implementazione SQL concreta.
+
+### Fase 8 — Datamart e promozione memory
+
+Il gate `reviewer_memory_promote` calcola i candidati in modo deterministico, li mostra al reviewer e salva quelli approvati con `memory save-one`. Registra inoltre `memory_promoted` o `memory_promotion_declined`.
+
+La fase chiude e finalizza la sessione automaticamente. Non va aggiunta una seconda conferma che ripeta la stessa approvazione.
+
+## Regole di avanzamento
+
+La skill distingue tra decisione e chiusura della fase:
+
+- una scelta `reviewer_select` o `reviewer_decide` registra una decisione;
+- normalmente non fa avanzare la fase da sola;
+- le fasi con completamento deterministico si chiudono con il loro gate specifico;
+- F1, F2 con decisioni sostanziali e F5 usano la conferma esplicita di fase;
+- F2 vuota e F6 vuota possono avanzare con `advance:true`;
+- F3, F4, F6, F7 e F8 hanno gate di chiusura specializzati.
+
+Questa distinzione evita che `advance:true` diventi un bypass generalizzato delle conferme umane.
+
+## Resume e artefatti
+
+Quando una sessione viene ripresa, la skill ordina di leggere prima:
+
+```text
+tht session show <id> --json
+tht session documents <id> --json
+```
+
+Il modello ricostruisce il contesto da stato, ledger e artefatti persistiti: `question.md`, `schema_linking.json`, piano CTE, test e `sql_final.sql`. Non riparte dalla conversazione e non assume che un'azione non registrata sia stata eseguita.
+
+Il retrieval pack, quando è già iniettato dal backend, viene trattato come dati e non come istruzioni. Questo separa il contesto recuperato dalla policy operativa della skill e riduce il rischio di prompt injection proveniente dai dati.
+
+## Documenti di riferimento della skill
+
+La skill rimanda a documenti specializzati per i dettagli di dominio:
+
+- `rewriting.md` per la domanda riscritta;
+- `cte.md` per la progettazione dei CTE;
+- `sql-generation.md` per la generazione del SQL.
+
+La separazione è utile perché la skill principale definisce il processo e i confini, mentre i documenti secondari descrivono come costruire i singoli artefatti.
+
+## Perché la skill è importante per l'architettura
+
+Il backend è un bridge verso Pi e `tht`; non conserva un transcript completo come fonte primaria. La skill rende il modello compatibile con questa architettura perché impone di produrre decisioni e artefatti persistiti a ogni passaggio.
+
+In pratica, la skill garantisce:
+
+- ripresa deterministica dopo un riavvio;
+- audit umano delle decisioni;
+- separazione tra conoscenza riusabile e schema-linking locale;
+- coerenza tra UI, ledger e file di fase;
+- possibilità di verificare il risultato senza ricostruire una conversazione persa;
+- protezione contro comandi o avanzamenti non autorizzati.
+
+## Riferimenti sorgente
+
+- [Skill canonica `tht-sessione`](../harness/.pi/skills/tht-sessione/SKILL.md)
+- [Workflow YAML](../harness/workflow.yaml)
+- [Gate Pi](../harness/.pi/extensions/tht-gate.js)
+- [Macchina delle fasi e decisioni effettive](../harness/tht/phase.py)
+- [Gestione delle memory](gestione-memory.md)