Conformità

Versione 1.3. Stato: Stabile. Questo documento definisce cosa significhi per un repository essere conforme a Deep Work Plan — ossia AI-first e pilotabile dagli agenti. Le parole chiave MUST, MUST NOT, SHOULD, SHOULD NOT e MAY devono essere interpretate come descritto nella RFC 2119.

La conformità esiste affinché «AI-first» sia una proprietà oggettiva e verificabile anziché un’impressione. Un repository soddisfa i criteri qui sotto oppure no. La sub-skill verify (/dwp-verify) li controlla in modo meccanico.

Un repository conforme

Un repository conforme a DWP DEVE soddisfare tutto quanto segue. Ogni artefatto DEVE essere ragionato per il repository — adattato ai suoi linguaggi, framework e comandi reali. Uno stub generico, un segnaposto o contenuto copiato da un altro repository non soddisfa un criterio.

1. AGENTS.md nella radice. Il repository DEVE contenere un AGENTS.md di radice che includa (a) un indice della documentazione, (b) le regole obbligatorie per il repository e (c) un blocco Quick Commands i cui comandi siano reali ed eseguibili in questo repository. Comandi segnaposto (per esempio, npm test in un repository che non usa npm) NON DEVONO comparire. L’indice NON DEVE collegare un file docs/ che non esiste, e il file DOVREBBE restare entro un budget di 150–500 righe, spostando il dettaglio in docs/ e collegandolo anziché crescere senza limite.
2. CLAUDE.md si risolve in AGENTS.md. Un CLAUDE.md DEVE esistere e risolversi in AGENTS.md (un symlink, o un equivalente che garantisca un’unica fonte di verità). I due NON DEVONO divergere.
3. Una gerarchia docs/. Il repository DEVE contenere una directory docs/ che copra le categorie standard (architettura, standard, testing, comandi di sviluppo, sicurezza e onboarding degli agenti) con contenuto reale e specifico del repository. I moduli complessi DOVREBBERO avere un proprio README.md. La guida al testing DEVE definire una toolchain reale di test, lint e type-check — oppure, per un repository che non ne ha alcuna, un setup concreto proposto a partire dallo stack durante l’onboarding. Una guida al testing vuota o «nessun test» non soddisfa questo criterio: senza un modo definito per validare il comportamento, un piano non ha alcun validation gate oggettivo.
4. Una home .agents/. Il repository DEVE contenere una directory .agents/ con agents/, commands/ e skills/, più un catalogo sotto .agents/docs/ che corrisponda a ciò che è su disco. I comandi dwp-* DEVONO essere sottili delegatori alla skill installata. Un percorso .claude DEVE risolversi in .agents.
5. Un workspace .dwp/ escluso da git. Il repository DEVE contenere una directory .dwp/ con plans/, e .dwp/ DEVE essere escluso da git. Uno spazio di lavoro temporaneo tmp/ DOVREBBE esistere e DOVREBBE essere escluso da git.
6. La skill della metodologia è risolvibile. La skill Deep Work Plan DEVE essere installata o referenziata in modo tale che un agente nel repository possa invocarne le sub-skill.

Un repository è pienamente conforme con zero addon opzionali. Gli addon opzionali (devcontainer, Dailybot, dependency-upgrade, design-system) NON DEVONO essere richiesti per la conformità. Dallo standard 2.3.0 la revisione locale AI Diff Reviewer (skill vendorizzata + file di estensione) fa parte della baseline: la sua assenza è un fallimento per un repository che dichiara la 2.3.0 o successiva e un rilievo sulla versione della harness per un repository legacy. La sua superficie CI resta opzionale.

Un piano ben formato

Un Deep Work Plan in .dwp/plans/ è ben formato quando:

1. Ogni attività DEVE dichiarare uno scope esplicito, criteri di accettazione e almeno un validation gate (un comando o una verifica che ha esito oggettivamente positivo o negativo).
2. Ogni attività che aggiunge nuove funzionalità fondamentali o modifica il comportamento del prodotto DEVE includere una copertura di test automatizzati per quel comportamento nei suoi criteri di accettazione, e DEVE eseguire i test del repository insieme ai suoi controlli di lint e type-check nel suo validation gate — non solo la build. I test esistenti DEVONO restare verdi; un cambiamento di comportamento DEVE aggiornare un test che rompe anziché eliminarlo o saltarlo. Le attività di pura documentazione, configurazione o ricerca sono esentate dal creare test ma eseguono comunque il gate del repository.
3. Ogni attività che tocca autenticazione, gestione degli input, segreti o configurazione, superficie di rete o dipendenze DEVE portare le aspettative di sicurezza di quella modifica nei suoi criteri di accettazione, e ogni commit DEVE essere privo di materiale segreto.
4. Il piano DEVE persistere i progressi così che il lavoro sopravviva all’interruzione e possa essere ripreso da un agente diverso. Un’attività NON DEVE essere registrata come completed mentre uno qualsiasi dei suoi record di validation gate mostra ancora un’esecuzione fallita e non risolta, e il log di completamento di un’attività NON DEVE contraddire il suo stato registrato (per esempio un’attività completed il cui log riporta ancora “Status: pending” è un difetto, non un esito positivo).
5. Il piano DEVE chiudersi con la propria revisione finale registrata. Un piano redatto con questa versione DEVE terminare con esattamente un Final Review obbligatorio — il passaggio di sicurezza, la validazione dello stato finale e la riconciliazione delle skill. Un piano redatto con una versione precedente termina con le tre attività finali obbligatorie (Security Review, Skills & Agents Discovery, Executive Report) e resta conforme. Un rilievo di sicurezza critico blocca il completamento finché non viene corretto o esplicitamente accettato. Il completamento stesso è una transazione verificata e recuperabile, non un semplice cambio di stato: l’attività terminale si chiude attraverso un passaggio di pubblicazione protetto che valida gli artefatti del piano terminato prima di scrivere lo stato e lascia una ricevuta FINALIZATION.json verificabile meccanicamente; una pubblicazione interrotta viene recuperata dall’evidenza, mai silenziosamente ridichiarata completa. Qualsiasi puntatore di evidenza citato da un gate record DEVE risolversi dentro la cartella propria del piano — un puntatore penzolante o che ne esce è un rilievo, non un’evidenza valida.
6. Le attività DOVREBBERO riancorarsi all’obiettivo del piano prima di eseguire, per prevenire la deriva su un orizzonte lungo.

Verificare la conformità

La conformità DOVREBBE essere verificata in modo meccanico anziché per ispezione. Eseguire /dwp-verify produce un report di esito positivo/negativo rispetto ai criteri qui sopra: la presenza e il contenuto reale di AGENTS.md, la risoluzione di CLAUDE.md, le categorie docs/, la corrispondenza tra catalogo .agents/ e disco, lo stato di esclusione da git di .dwp/ e tmp/ e — per un piano — che ogni attività porti con sé criteri di accettazione e un validation gate, con copertura di test per le attività che modificano il comportamento e la revisione finale registrata presente. Per un piano, verifica anche che il markdown del piano e il suo stato leggibile dalle macchine concordino (una desincronizzazione tra README e state.json è un rilievo, mai un esito positivo silenzioso), che le attività completate portino evidenze di gate e di log non contraddittorie e — dove un piano completato vi arriva — che una ricevuta di pubblicazione sostenga il completamento dichiarato. Il checker è consapevole della versione: DEVE accettare come conforme un piano legacy (tre attività finali obbligatorie, nessuna Superficie toccata) e DEVE rifiutare un piano che dichiara questa versione e che è oggettivamente invalido sotto di essa. Riporta inoltre una riga di provenienza DWP standard: mancante o non aggiornata come un rilievo che nomina l’aggiornamento mirato della harness. Il livello meccanico è onesto sui propri limiti: senza un interprete capace (Python 3.9+) termina con un’uscita diversa da zero e un verdetto UNVERIFIED esplicito, invece di saltare le proprie verifiche — un verificatore non riporta mai un risultato che non ha verificato.

Un repository DOVREBBE essere ri-verificato dopo l’onboarding e dopo ogni piano completato, così che la conformità sia mantenuta anziché dichiarata una sola volta.