Review e verifica

La verifica chiede se l’implementazione soddisfa il contratto approvato. La review chiede se il developer accetta implementazione, evidenze e limitazioni residue.

Sono collegate, ma non equivalenti.

Un modello può riportare evidenze. Non può sostituire l’accettazione ingegneristica.

Evidenze invece di affermazioni convincenti

Una risposta come “task completato” non è un’evidenza. TCAF richiede che il risultato identifichi cosa è stato realmente controllato e cosa resta sconosciuto.

Le evidenze utili possono comprendere:

• test automatico mirato e relativo esito;
• output di typecheck, build o lint pertinente all’area modificata;
• validazione strutturale;
• diff e file coinvolti realmente ispezionati;
• scenario manuale eseguito dal developer;
• risultato UI o di integrazione osservato;
• conferma esplicita che un controllo richiesto non poteva essere eseguito.

Il framework non richiede ogni controllo possibile. Richiede una rappresentazione onesta dei controlli rilevanti per il contratto.

Usare i controlli minimi significativi

Normalmente si scelgono da uno a tre controlli che coprono i rischi principali del task.

Esempi:

• unit test e typecheck per una modifica a una funzione di dominio;
• test API mirato e verifica manuale del percorso di errore;
• build e singolo flusso UI per un’integrazione visuale;
• tcaf validate --target <percorso> dopo modifiche ai documenti di progetto.

Suite estese possono essere appropriate quando progetto o contratto le richiedono. Non dovrebbero essere eseguite soltanto per creare un’apparenza di completezza quando un insieme più piccolo e mirato è più informativo.

Verifica automatica e manuale

I limiti degli strumenti sono normali. Un agente potrebbe non poter eseguire comandi, aprire un browser, accedere a credenziali o riprodurre una dipendenza esterna.

In questo caso dovrebbe riportare controlli per il developer, per esempio:

DEVELOPER_RUN: pnpm test -- customer-service.test.ts
MANUAL_CHECK: invia il form con email non valida e verifica l’errore inline

L’agente non deve presentare come superato un comando non eseguito.

L’attribuzione è importante

Ogni risultato dovrebbe chiarire chi ha eseguito la verifica:

• agente;
• developer;
• CI;
• in attesa;
• non disponibile.

Questo è particolarmente importante quando il task passa tra strumenti o sessioni differenti. Chi revisiona in seguito deve sapere se l’evidenza è stata osservata o soltanto richiesta.

Revisionare la modifica reale

La review umana dovrebbe ispezionare l’implementazione e non affidarsi esclusivamente alla risposta finale.

Verifica che:

• il diff corrisponda all’obiettivo approvato;
• file e comportamenti estranei siano rimasti intatti;
• metodi, guard e utility locali siano stati riusati correttamente;
• i criteri di accettazione siano soddisfatti;
• test o controlli manuali coprano il comportamento importante;
• nessuna dipendenza, configurazione o ristrutturazione nascosta sia entrata nel task;
• le modifiche del developer siano state preservate;
• le limitazioni dichiarate siano accurate.

Review gate

Un review gate è uno stop deliberato prima di una transizione sostanziale.

I gate tipici comprendono:

• dopo la generazione dei documenti di adozione;
• dopo la proposta di un Task Contract;
• dopo implementazione e controlli;
• prima che la riconciliazione aggiorni lo stato del progetto;
• prima di commit, push, merge, tag, release o deploy.

Il gate consente al developer di approvare, correggere, rifiutare, dividere o continuare il lavoro.

La verifica non dimostra tutto

Test superati dimostrano soltanto ciò che quei test coprono. Una build riuscita non dimostra la correttezza funzionale. Un validatore strutturale non dimostra che la documentazione sia fattualmente vera.

La risposta finale dovrebbe interpretare le evidenze in modo ristretto:

• typecheck PASS significa che i tipi controllati compilano;
• target validation PASS significa che la struttura documentale richiesta è valida;
• un test mirato PASS significa che lo scenario testato è passato;
• resta necessaria review manuale per i comportamenti non coperti.

Controlli falliti

Un controllo richiesto fallito produce FAIL, a meno che il fallimento sia chiaramente estraneo e il developer decida esplicitamente come trattarlo.

Non bisogna:

• eliminare un test fallito per ottenere PASS;
• indebolire i criteri di accettazione dopo l’implementazione;
• dichiarare completato il task nascondendo il fallimento;
• ampliare il task in una riparazione estranea senza approvazione.

Riporta comando, fallimento, criterio del contratto coinvolto e decisione successiva.

Verifica incompleta

Quando l’implementazione è completa ma resta un controllo manuale richiesto, usa READY FOR CHECK invece di PASS.

Quando è stata implementata soltanto una parte del lavoro approvato, usa PARTIAL.

Quando la verifica non può proseguire per una decisione, dipendenza o condizione ambientale mancante, usa BLOCKED.

L’etichetta deve descrivere l’evidenza corrente, non la fiducia dell’agente.

L’accettazione resta esplicita

Anche dopo una verifica riuscita, è il developer a decidere se accettare il lavoro.

L’accettazione può essere negata perché:

• il comportamento è tecnicamente corretto ma non desiderabile;
• l’implementazione è incoerente con l’architettura locale;
• un controllo manuale rivela un problema di usabilità;
• il diff è più ampio di quanto approvato;
• il contesto del progetto è cambiato durante il task.

TCAF supporta il giudizio ingegneristico; non riduce l’accettazione allo stato dei test automatici.

Dopo l’accettazione

Il lavoro accettato può autorizzare azioni separate:

• aggiornare backlog o stato della issue;
• riconciliare documentazione di progetto;
• creare un commit;
• aprire una pull request;
• pubblicare o distribuire.

Queste azioni devono usare implementazione ed evidenze accettate come fonte, senza presumere che la verifica autorizzi automaticamente le operazioni di release.