Specifica DWP

Versione 4.0.0. Stato: Stabile. Questo documento è la specifica normativa per la metodologia Deep Work Plan (DWP). Le parole chiave MUST, MUST NOT, SHOULD, SHOULD NOT e MAY devono essere interpretate come descritto nella RFC 2119.

Additivi in 2.4.0, nessuna modifica incompatibile. (1) La sezione Superficie toccata — il contratto tra ciò che un’attività modifica e ciò che deve essere validato, con la selezione del gate per classe di rischio (isolata / giuntura / condivisa-core / sconosciuta); (2) la validazione completa diventa un requisito di stato finale eseguito nel singolo Final Review obbligatorio del piano, con regole esplicite di riutilizzo delle evidenze; (3) le decisioni locali per attività sulle skill si spostano nell’attività proprietaria e l’Executive Report diventa facoltativo, su richiesta; (4) un flusso create consapevole della modalità — la modalità trust materializza direttamente mantenendo analisi e controlli di qualità; (5) materializzazione Lite-first del piano — il create guidato produce direttamente un piano Lite eseguibile invece di una bozza non eseguibile, promuovibile a un piano Full in qualsiasi momento (vedi Piani Lite); e (6) una matrice di compatibilità esplicita: i piani e i repository di versioni precedenti restano conformi.

Standard 4.0.0. Il salto di versione allinea il numero dello standard alla linea di prodotto — 2.x è storico e non esiste uno standard 3.x — e non cambia alcun requisito rispetto a 2.4.0. Piani e repository di versioni precedenti restano conformi.

Definizione

Un Deep Work Plan è un artefatto strutturato e solo-Markdown che descrive un’attività di ingegneria complessa scomposta in unità di lavoro sequenziali e revisionabili, progettato per essere creato, eseguito e mantenuto da agenti di coding AI che operano in autonomia.

DWP è spec-driven: il piano è la specifica e gli agenti DEVONO eseguire rispetto ai suoi criteri di accettazione e validation gate espliciti anziché improvvisare. La specifica — non una trascrizione di chat — è la fonte di verità duratura, così il lavoro è verificabile e ripristinabile tra sessioni e agenti. È anche harness engineering reso portabile: il contesto, il ciclo di controllo, le salvaguardie e lo stato ripristinabile che rendono un agente affidabile vengono installati nel repository stesso come semplice Markdown, così qualsiasi agente conforme PUÒ pilotare il repository senza un framework specifico per uno strumento.

Flusso create — passo unico, consapevole della modalità

Il flusso create raccoglie una sola volta obiettivo, contesto, vincoli e struttura delle attività, esegue la propria analisi dei requisiti (ambito, ordinamento delle dipendenze tra attività, selezione della validazione dalla Superficie toccata, livello di rigore proporzionale) e poi materializza secondo la modalità scelta dallo sviluppatore:

• Modalità guidata (predefinita). Il flusso materializza direttamente un piano Lite — una proposta compatta e già eseguibile con record di attività {#task-N} inline, revisionabile in un solo passaggio — e chiede allo sviluppatore di conservarlo come Lite, promuoverlo a un piano Full, richiedere modifiche o fermarsi. Non viene prodotta alcuna bozza intermedia non eseguibile.
• Modalità trust (trust / auto). Il flusso materializza direttamente la rappresentazione scelta (Lite, oppure Lite seguito immediatamente dalla promozione a Full), senza passaggio di revisione — lo sviluppatore vi ha rinunciato. L’analisi dei requisiti, l’ordinamento delle dipendenze e un controllo di qualità del piano vengono comunque eseguiti: trust rinuncia alla revisione, non all’analisi. Un piano in modalità trust è registrato come pre-approvato per l’esecuzione non presidiata.

Entrambe le modalità decidono il formato del piano (Lite o Full) come parte della stessa analisi dei requisiti, mai a posteriori. Vedi Piani Lite per il ciclo di vita completo di rappresentazione, creazione-e-selezione e promozione.

Struttura del piano

Un piano DEVE essere una directory sotto .dwp/plans/ denominata PLAN_<slug>/, in una di due rappresentazioni:

• Full. La directory DEVE contenere README.md (panoramica del piano, obiettivo, tabella delle attività e stato), un file per attività denominato <n>.task_<slug>.md, e PROGRESS.md (un log di esecuzione continuo).
• Lite. Record di attività compatti e completamente eseguibili vivono inline in README.md dietro ancore stabili {#task-N} invece di file di attività separati — ogni record porta comunque un obiettivo, una Superficie toccata, criteri di accettazione, validazione e un Completion & Log. PROGRESS.md resta OBBLIGATORIO. Un piano Lite PUÒ essere promosso a Full in qualsiasi momento. Vedi Piani Lite per il ciclo di vita completo, anziché duplicarlo qui.

Un piano PUÒ portare in aggiunta il livello di stato leggibile dalle macchine: manifest.json (identità statica, scritto una volta alla materializzazione) e state.json (stato di esecuzione live per attività). Il livello di stato è RACCOMANDATO per i nuovi piani e OBBLIGATORIO per l’esecuzione non presidiata e per i workspace agente senza git. Vedi Stato del piano.

Anatomia dell’attività

File di attività

1. 01 Title
2. 02 Context
3. 03 Read Before Starting
4. 04 Goal
5. 05 Touched Surface
6. 06 Instructions
7. 07 Acceptance Criteria
8. 08 Outputs
9. 09 Validation
10. 10 Execution Checklist + Completion & Log

Ogni file di attività DEVE contenere queste dieci sezioni, nell’ordine:

1. Goal — una dichiarazione di un paragrafo su cosa l’attività realizza.
2. Context — contesto, link e il perché questa attività esiste.
3. Superficie toccata — il contratto tra ciò che l’attività modifica e ciò che deve essere validato.
4. Steps — azioni ordinate e concrete da svolgere.
5. Acceptance criteria — una checklist di condizioni che definiscono il completamento.
6. Validation — comandi o test da eseguire per verificare, selezionati dalla Superficie toccata.
7. Files — percorsi che ci si aspetta vengano creati o modificati.
8. Dependencies — altre attività o prerequisiti esterni.
9. Risks — cosa potrebbe andare storto e le relative mitigazioni.
10. Completion & Log — un marcatore di stato più note cronologiche.

Un’attività PUÒ includere in aggiunta una sezione Delta (RACCOMANDATA per le modifiche al comportamento brownfield — vedi di seguito) e una sezione Rollback (RACCOMANDATA per migrazioni, modifiche infrastrutturali o deployment).

La Superficie toccata

La Superficie toccata è il contratto tra ciò che un’attività modifica e ciò che deve essere validato. Esiste affinché la validazione sia selezionata per effetto, non per abitudine, e affinché un lettore successivo possa vedere perché un gate è stato scelto. Un’attività che modifica il comportamento DEVE registrare:

• Superficie pianificata — i percorsi, i moduli, i package o la configurazione che l’attività intende modificare, scritti prima di modificare.
• Superficie effettiva — l’elenco riconciliato dopo la modifica, preso dal diff reale. L’agente DEVE riconciliare le superfici pianificata ed effettiva prima di selezionare il gate.
• Consumatori interessati — i moduli, i package o i servizi che dipendono dalla superficie effettiva, per quanto la mappatura documentata del repository possa stabilire. Dove non può, la voce DEVE dirlo.
• Classe di rischio — una tra: isolata (confinata a un modulo e ai suoi test); giuntura (altera un contratto, la persistenza, il routing, la serializzazione, l’auth o il cablaggio del framework tra collaboratori); condivisa/core (importata ampiamente, oppure una modifica a dipendenza, migrazione, configurazione build/test, schema o toolchain); sconosciuta (la mappatura manca, è non aggiornata o non verificata).
• Mappatura dei test usata — quale mappatura documentata o quale strumento ha prodotto la selezione.
• Gate selezionato e motivazione — i comandi esatti e perché coprono la superficie effettiva.

I file di configurazione, gli schemi, i manifest delle dipendenze, i template, le fixture, le migrazioni e i file di istruzioni per gli agenti possono cambiare il comportamento e DEVONO essere classificati per il loro effetto, mai per estensione di file. Un’attività che modifica solo prosa, commenti o artefatti di ricerca PUÒ dichiarare la superficie non applicabile ed esegue comunque i controlli non a runtime del repository.

La sezione Delta (modifiche brownfield)

La maggior parte del lavoro reale modifica il comportamento esistente anziché crearne di nuovo. Un’attività che cambia il comportamento di un sistema esistente DOVREBBE portare una sezione Delta che descrive la modifica come un contratto esplicito prima/dopo, usando tre intestazioni di elenco:

• ADDED — comportamento che esiste dopo l’attività e non esisteva prima.
• MODIFIED — comportamento che esiste in entrambi, espresso come was: … → now: ….
• REMOVED — comportamento che esisteva prima ed è intenzionalmente rimosso dopo.

Ogni voce DEVE essere un comportamento osservabile — la risposta di un endpoint, un flag CLI, uno stato UI, un valore predefinito — non un dettaglio di implementazione. La sezione Delta è il diff del revisore a livello di comportamento: i criteri di accettazione verificano le voci ADDED/MODIFIED, e le voci REMOVED sono la licenza esplicita a eliminare. Qualsiasi cosa non elencata come REMOVED DEVE continuare a funzionare.

Validation gate — selezionati per classe di rischio

La validazione è il gate che trasforma una dichiarazione di completamento nella sua prova: un’attività NON DEVE essere segnata come completata finché ogni comando della sua sezione Validation non è stato eseguito con esito positivo. Il gate di un’attività che modifica il comportamento è selezionato dalla sua Superficie toccata riconciliata, per classe di rischio:

Un cambiamento di comportamento DEVE produrre una selezione di test non vuota e pertinente — un selettore non valido o un runner che ha selezionato zero test non è copertura. Dove la mappatura dei test del repository è non aggiornata, l’invocazione corretta viene derivata e l’aggiornamento della mappatura registrato; un piccolo comando mancante non richiede mai un’esecuzione completa di onboarding. Dove non esiste un’invocazione con ambito, si applica la suite completa applicabile — comportamento legacy, mai un errore.

Quando un’attività aggiunge nuove funzionalità fondamentali o modifica in modo sostanziale il comportamento esistente, i suoi criteri di accettazione DEVONO includere una copertura di test automatizzati per il comportamento nuovo o modificato, e la sua validazione esegue i test del repository insieme ai controlli di lint, type-check e formattazione — non solo la build. I test esistenti DEVONO restare verdi.

Validazione dello stato finale

I gate per attività validano ciò che ogni attività ha toccato; non sostituiscono la validazione del piano nel suo insieme. Prima che un piano sia completato, la validazione completa applicabile del repository DEVE essere eseguita e superata sullo stato finale rilevante, dopo l’ultima modifica sostanziale — nel Final Review. Esecuzioni più ampie in precedenza avvengono ai confini di integrazione o dopo modifiche condivise/core, non secondo una tabella di marcia basata sul numero di attività. Un risultato positivo PUÒ essere riutilizzato solo con l’evidenza che gli input rilevanti sono equivalenti; altrimenti viene rieseguito. Ogni esecuzione di un gate lascia un record conciso: comando, ambito, revisione, esito e un percorso di evidenza.

Disciplina di sicurezza

La sicurezza è di prima classe allo stesso modo dei test, e segue lo stesso modello a due livelli: disciplina per attività mentre il lavoro avviene, più il passaggio di sicurezza del Final Review sull’intero insieme di modifiche alla fine. Ogni volta che un’attività tocca l’autenticazione o l’autorizzazione, la gestione dell’input, segreti o configurazione, la superficie di rete, file o shell, oppure le dipendenze:

• I suoi criteri di accettazione DEVONO dichiarare le aspettative di sicurezza della modifica — input validato e sottoposto a escape, nessun materiale segreto nel codice o nelle fixture, controlli di autenticazione preservati o rafforzati — in modo coerente con docs/SECURITY.md.
• Ogni commit DEVE essere confermato privo di segreti o credenziali prima di essere integrato, incluse le fixture di test e gli esempi di documentazione. Un segreto in un commit già pubblicato DEVE essere trattato come trapelato e ruotato, non semplicemente rimosso.
• Dove il lavoro sensibile alla sicurezza è sostanziale, un’attività di hardening dedicata DOVREBBE essere collocata immediatamente dopo le attività di implementazione e prima dell’attività di test completi, così che i rilievi siano corretti prima che i test codifichino il comportamento e ogni rilievo diventi un caso di regressione anziché rilavorazione.

Questa disciplina per attività non sostituisce il passaggio di sicurezza del Final Review: i controlli per attività intercettano i problemi nel commit in cui nascono, mentre il gate finale verifica l’intero piano — incluse le stesse attività di test e documentazione.

Ciclo di vita del piano — il Final Review

Ogni piano conforme redatto con questa versione termina con esattamente un’unica attività obbligatoria: il Final Review (attività N). Due responsabilità che le versioni precedenti collocavano in attività di chiusura separate sono ricollocate: le decisioni sulle skill si spostano nell’attività che ha prodotto il pattern, e l’Executive Report diventa un artefatto facoltativo, su richiesta. Nulla del passaggio di sicurezza viene allentato.

Il Final Review DEVE, nell’ordine:

(a) Passaggio di sicurezza — esaminare l’intero insieme di modifiche accumulato dal piano alla ricerca di segreti hardcoded, rischi di injection, nuova superficie di attacco, auth indebolita e dati sensibili nei log o nei documenti; verificare le dipendenze introdotte; accertare che docs/SECURITY.md rifletta ancora la realtà; scrivere il report di revisione di sicurezza anche quando è pulito. Un rilievo critico viene corretto — o esplicitamente accettato dall’utente — prima che il piano sia completato.

(b) Validazione dello stato finale — la validazione completa applicabile del repository viene eseguita e superata sullo stato finale rilevante.

(c) Riconciliazione delle skill — ogni attività porta una disposizione delle skill e ogni candidato registrato ha una disposizione; nessun secondo report di discovery.

(d) Completamento — riferire il completamento con deliverable, evidenze di validazione e limitazioni; offrire l’Executive Report una volta. Il piano è completo sia che l’offerta riceva risposta sia che rimanga senza risposta.

Il Final Review viene eseguito sequenzialmente dopo tutte le altre attività e non è mai collocato in un gruppo parallelo.

Decisioni locali per attività sulle skill

La domanda «questo lavoro ha creato un pattern riutilizzabile che merita una skill o un agente?» riceve risposta dentro l’attività che ha prodotto il pattern, mentre la sua evidenza è in contesto. Il Completion & Log di ogni attività porta una disposizione delle skill: nessuna, aggiornamento di una skill esistente, creazione di un artefatto con nome o un rinvio con una motivazione. L’authoring giustificato avviene dentro quell’attività, prima del suo validation gate e del commit, dopo aver controllato il catalogo esistente per i duplicati.

Executive report — facoltativo, su richiesta

L’Executive Report non è più un’attività obbligatoria. Al completamento l’agente lo offre una volta; viene generato solo su richiesta esplicita, soddisfatto da evidenze durevoli senza rieseguire il piano. Nessuna risposta o un’esecuzione non presidiata lascia il piano completato senza report generato.

Protocollo di completamento dell’attività

Dopo aver superato la validazione e prima di avanzare all’attività successiva, l’agente DEVE, nell’ordine: (1) segnare l’attività [x] nel README del piano; (2) incrementare il contatore di stato del piano; (3) compilare la sezione Completion & Log dell’attività senza valori segnaposto; (4) aggiungere una voce di 3–5 punti in PROGRESS.md; (5) eseguire il commit (dove il piano esegue commit) con il formato {type}({scope}): {description} — Task {N} of PLAN_{name}; (6) dove il piano porta il livello di stato, riscrivere state.json atomicamente — attività completed, gate record, outcome record, hash del commit.

I sei passi formano un’unica transazione logica. Un agente interrotto a metà protocollo NON DEVE avviare l’attività successiva — deve terminare o annullare il completamento parziale prima.

Il protocollo di ripresa DWP

La ripresa DEVE essere possibile usando solo i file del piano più il git log, senza stato esterno. In un workspace senza git — vedi Archetipi §3 — il state.json del piano è OBBLIGATORIO e sostituisce il git log.

Un agente che riprende l’esecuzione — una nuova sessione, un agente diverso, un turno di daemon pianificato, o una sessione cloud che si sveglia — DEVE eseguire questo rituale, nell’ordine:

1. Ri-ancorare. Leggere il README del piano: obiettivo, linee guida globali, lista delle attività.
2. Individuare il checkpoint. Trovare la prima attività non spuntata nel README; leggere il git log e git status (oppure il checkpoint di state.json dove git è assente).
3. Riconciliare lo stato. Dove esiste state.json, confrontarlo con le caselle del README; in caso di desincronizzazione, rigenerarlo dal markdown prima di continuare.
4. Ispezionare la giuntura. Leggere la sezione Completion & Log dell’attività al punto di ripresa e l’ultima voce di PROGRESS.md — l’ultimo terreno verificato della sessione precedente.
5. Smoke-test. Eseguire la validazione permanente più economica del repository per confermare che il mondo funzioni ancora prima di costruirci sopra. Un smoke test che fallisce viene investigato prima, non ignorato.
6. Continuare atomicamente. Eseguire esattamente la prossima attività; non procedere in batch.

L’agente DEVE fidarsi dei segni completati ([x]) e NON DEVE rivalidare le attività completate, a meno che l’utente non lo richieda esplicitamente o lo smoke test fallisca in un modo che implica un’attività completata.

Il ciclo di esecuzione

DWP definisce cinque operazioni:

• create — Genera un nuovo piano da un obiettivo.
• execute — Esegue il piano attività per attività.
• refine — Modifica un piano esistente.
• resume — Riprende un piano interrotto.
• status — Riferisce sullo stato del piano senza eseguire.

Workspace di output

Spazio di lavoro di output

• .dwp/ ignorato da git · usa e getta
• plans/
• PLAN_<name>/
• README.md
• PROGRESS.md
• <n>.task_<slug>.md
• analysis_results/ report
• SECURITY_REVIEW.md revisione di sicurezza
• EXECUTIVE_REPORT.md report esecutivo

Tutti gli artefatti DWP DEVONO vivere in una directory .dwp/ esclusa da git nella radice del repository.

Stato del piano leggibile dalle macchine

Un piano PUÒ portare il livello di stato leggibile dalle macchine — manifest.json (identità statica) e state.json (stato live per attività, gate record di validazione, outcome record, checkpoint, stato bloccato). Il piano in markdown rimane la fonte di verità; il livello JSON è una proiezione derivata, rigenerata nei punti di protocollo e riconciliata alla ripresa.

Il livello di stato è RACCOMANDATO per i nuovi piani, OBBLIGATORIO per l’esecuzione non presidiata e OBBLIGATORIO per i workspace agente senza git. Vedi la definizione normativa completa in Stato del piano.

Rigore proporzionale

Il rigore DEVE essere proporzionale al lavoro. La cerimonia su cambiamenti banali è un fallimento della metodologia, non una sicurezza in più. Ogni lavoro ricade esattamente in un livello:

Un agente a cui viene chiesto di creare un piano per un lavoro di livello micro DEVE dire che un piano è sproporzionato e offrire invece la forma inline. Una cartella del piano NON DEVE essere creata per un cambiamento banale a un singolo file.

Il lavoro di livello micro mantiene comunque i non negoziabili: un obiettivo esplicito, un validation gate che viene eseguito e superato, e la disciplina di test per le modifiche al comportamento. Il livello cambia il packaging, mai i gate.

Quando l’ambito cresce in corsa — un’attività micro scopre una portata reale, un piano standard genera sotto-repository — l’agente DEVE fermarsi e promuovere il lavoro al livello successivo anziché estendere quello corrente.

Compatibilità

I piani e i repository di versioni precedenti restano conformi, e un checker di conformità DEVE distinguere un artefatto legacy noto (accettato) da un artefatto che dichiara questa versione ed è oggettivamente invalido sotto di essa (rifiutato):

Versionamento

Questa specifica segue il versionamento semantico.