Spécification DWP

Version 4.0.0. Statut : stable. Ce document est la spécification normative de la méthodologie Deep Work Plan (DWP). Les mots-clés MUST, MUST NOT, SHOULD, SHOULD NOT et MAY doivent être interprétés comme décrit dans la RFC 2119.

Additif en 2.4.0, sans changement de rupture. (1) La section Surface touchée — le contrat entre ce qu’une tâche modifie et ce qui doit être validé, avec sélection de la porte par classe de risque (isolée / couture / partagée-cœur / inconnue) ; (2) la validation complète devient une exigence d’état final exécutée dans l’unique Final Review obligatoire du plan, avec des règles explicites de réutilisation des preuves ; (3) les décisions de skills par tâche rejoignent la tâche qui les motive, et l’Executive Report devient optionnel, sur demande ; (4) un flux create conscient du mode — le mode trust matérialise directement tout en conservant l’analyse et les contrôles de qualité ; (5) matérialisation Lite-first des plans — le create guidé produit directement un plan Lite exécutable au lieu d’une ébauche non exécutable, promouvable en plan Full à tout moment (voir Plans Lite) ; et (6) une matrice de compatibilité explicite : les plans et dépôts des versions antérieures restent conformes.

Standard 4.0.0. Le saut de version aligne le numéro du standard sur la ligne de produits — 2.x est historique et il n’existe pas de standard 3.x — et ne change aucune exigence par rapport à 2.4.0. Les plans et dépôts des versions antérieures restent conformes.

Définition

Un Deep Work Plan est un artefact structuré, exclusivement en Markdown, qui décrit une tâche d’ingénierie complexe décomposée en unités de travail séquentielles et relisibles, conçu pour être créé, exécuté et maintenu par des agents de code IA travaillant de manière autonome.

DWP est piloté par la spécification : le plan est la spécification, et les agents MUST s’exécuter face à ses critères d’acceptation explicites et à ses portes de validation plutôt que d’improviser. La spécification — et non une transcription de discussion — est la source de vérité durable, de sorte que le travail est vérifiable et reprenable d’une session et d’un agent à l’autre. C’est aussi de l’ingénierie de harness rendue portable : le contexte, la boucle de contrôle, les garde-fous et l’état reprenable qui rendent un agent fiable sont installés dans le dépôt lui-même sous forme de simple Markdown, de sorte que tout agent conforme MAY piloter le dépôt sans framework propre à un outil.

Flux create — une seule étape, conscient du mode

Le flux create recueille une seule fois l’objectif, le contexte, les contraintes et l’esquisse des tâches, effectue son analyse des exigences (périmètre, ordonnancement des dépendances entre tâches, sélection de la validation à partir de la Surface touchée, niveau de rigueur proportionnelle), puis matérialise selon le mode choisi par le développeur :

• Mode guidé (par défaut). Le flux matérialise un plan Lite directement — une proposition compacte et déjà exécutable avec des enregistrements de tâche {#task-N} en ligne, relisible en une seule passe — et demande au développeur de le conserver en Lite, de le promouvoir en plan Full, de demander des modifications, ou d’arrêter. Aucune ébauche intermédiaire non exécutable n’est produite.
• Mode trust (trust / auto). Le flux matérialise la représentation choisie (Lite, ou Lite suivi immédiatement d’une promotion vers Full) directement, sans étape de relecture — le développeur y a renoncé. L’analyse des exigences, l’ordonnancement des dépendances et un contrôle de qualité du plan s’exécutent toujours : trust renonce à la relecture, pas à l’analyse. Un plan en mode trust est enregistré comme pré-approuvé pour une exécution sans surveillance.

Les deux modes décident du format du plan (Lite ou Full) dans le cadre de la même analyse des exigences, jamais après coup. Voir Plans Lite pour le cycle de vie complet de représentation, de création-et-sélection, et de promotion.

Structure du plan

Un plan MUST être un répertoire sous .dwp/plans/ nommé PLAN_<slug>/, selon l’une de deux représentations :

• Full. Le répertoire MUST contenir README.md (vue d’ensemble du plan, objectif, tableau des tâches et statut), un fichier par tâche nommé <n>.task_<slug>.md, et PROGRESS.md (un journal d’exécution continu).
• Lite. Des enregistrements de tâche compacts et totalement exécutables vivent en ligne dans README.md derrière des ancres stables {#task-N} au lieu de fichiers de tâche séparés — chaque enregistrement porte toujours un objectif, une Surface touchée, des critères d’acceptation, une validation et un Completion & Log. PROGRESS.md reste REQUIRED. Un plan Lite MAY être promu en Full à tout moment. Voir Plans Lite pour le cycle de vie complet plutôt que de le dupliquer ici.

Un plan MAY également porter la couche d’état lisible par machine : manifest.json (identité statique, écrit une fois à la matérialisation) et state.json (état d’exécution en direct par tâche). La couche d’état est RECOMMENDED pour les nouveaux plans et REQUIRED pour l’exécution sans surveillance et pour les espaces de travail d’agents sans git. Voir État du plan.

Anatomie d’une tâche

Fichier de tâche

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

Chaque fichier de tâche MUST contenir ces dix sections, dans l’ordre :

1. Goal — un énoncé d’un paragraphe de ce que la tâche accomplit.
2. Context — le contexte, les liens et la raison d’être de cette tâche.
3. Surface touchée — le contrat entre ce que la tâche modifie et ce qui doit être validé.
4. Steps — des actions ordonnées et concrètes à réaliser.
5. Acceptance criteria — une liste de contrôle des conditions qui définissent « fait ».
6. Validation — les commandes ou tests à exécuter pour vérifier, sélectionnés à partir de la Surface touchée.
7. Files — les chemins censés être créés ou modifiés.
8. Dependencies — les autres tâches ou prérequis externes.
9. Risks — ce qui pourrait mal tourner, et les mesures d’atténuation.
10. Completion & Log — un marqueur de statut accompagné de notes chronologiques.

Une tâche MAY également inclure une section Delta (RECOMMENDED pour les changements de comportement sur du code existant — voir ci-dessous) et une section Rollback (RECOMMENDED pour les migrations, les changements d’infrastructure ou les déploiements).

La Surface touchée

La Surface touchée est le contrat entre ce qu’une tâche modifie et ce qui doit être validé. Elle existe pour que la validation soit sélectionnée par effet, non par habitude, et pour qu’un lecteur ultérieur puisse voir pourquoi une porte a été choisie. Une tâche qui change le comportement MUST consigner :

• Surface planifiée — les chemins, modules, paquets ou configurations que la tâche entend modifier, écrits avant l’édition.
• Surface réelle — la liste réconciliée après l’édition, tirée du diff réel. L’agent MUST réconcilier les surfaces planifiée et réelle avant de sélectionner la porte.
• Consommateurs affectés — les modules, paquets ou services qui dépendent de la surface réelle, dans la mesure où le mappage documenté du dépôt permet de l’établir. Là où il ne le permet pas, l’entrée MUST le dire.
• Classe de risque — l’une de : isolée (confinée à un module et à ses tests) ; couture (altère un contrat, la persistance, le routage, la sérialisation, l’authentification ou le câblage du framework entre collaborateurs) ; partagée/cœur (largement importée, ou un changement de dépendance, de migration, de configuration de build/tests, de schéma ou de chaîne d’outils) ; inconnue (le mappage est absent, obsolète ou non vérifié).
• Mappage de tests utilisé — quel mappage ou outil documenté a produit la sélection.
• Porte sélectionnée et raison — les commandes exactes et pourquoi elles couvrent la surface réelle.

Les fichiers de configuration, schémas, manifestes de dépendances, gabarits, fixtures, migrations et fichiers d’instructions d’agent peuvent changer le comportement et MUST être classés par leur effet, jamais par extension de fichier. Une tâche qui ne modifie que de la prose, des commentaires ou des artefacts de recherche MAY déclarer la surface non applicable et exécute tout de même les vérifications non runtime du dépôt.

La section Delta (changements sur du code existant)

La plupart du travail réel modifie un comportement existant plutôt qu’en créant un nouveau. Une tâche qui change le comportement d’un système existant SHOULD porter une section Delta décrivant le changement comme un contrat avant/après explicite, en utilisant trois en-têtes de liste :

• ADDED — comportement qui existe après la tâche et n’existait pas avant.
• MODIFIED — comportement présent dans les deux états, formulé comme was: … → now: ….
• REMOVED — comportement qui existait avant et est intentionnellement absent après.

Chaque entrée MUST être un comportement observable — la réponse d’un endpoint, un indicateur CLI, un état d’interface, une valeur par défaut — et non un détail d’implémentation. La section Delta est le diff du relecteur au niveau comportemental : les critères d’acceptation vérifient les entrées ADDED/MODIFIED, et les entrées REMOVED sont la licence explicite de suppression. Tout ce qui n’est pas listé comme REMOVED MUST continuer à fonctionner.

Portes de validation — sélectionnées par classe de risque

La validation est la porte qui transforme une affirmation d’achèvement en preuve de celui-ci : une tâche MUST NOT être marquée comme achevée tant que chaque commande de sa section Validation n’a pas été exécutée avec succès. La porte d’une tâche qui change le comportement est sélectionnée à partir de sa Surface touchée réconciliée, par classe de risque :

Un changement de comportement MUST produire une sélection de tests non vide et pertinente — un sélecteur invalide ou un exécuteur qui a sélectionné zéro test n’est pas une couverture. Lorsque la carte de tests du dépôt est obsolète, l’invocation correcte est dérivée et la mise à jour du mappage consignée ; une petite commande manquante n’exige jamais une exécution complète d’onboarding. Là où aucune invocation ciblée n’existe, la suite complète applicable s’applique — comportement hérité, jamais une erreur.

Lorsqu’une tâche ajoute une nouvelle fonctionnalité centrale ou modifie matériellement un comportement existant, ses critères d’acceptation MUST inclure une couverture de tests automatisés pour le comportement nouveau ou modifié, et sa validation exécute les tests du dépôt conjointement avec les vérifications de lint, de typage et de format — pas le build seul. Les tests existants MUST rester au vert.

Validation de l’état final

Les portes par tâche valident ce que chaque tâche a touché ; elles ne remplacent pas la validation du plan dans son ensemble. Avant qu’un plan ne s’achève, la validation complète applicable du dépôt MUST s’exécuter et réussir sur l’état final pertinent, après le dernier changement substantiel — dans le Final Review. Les exécutions plus larges antérieures ont lieu aux frontières d’intégration ou après des changements partagés/cœur, non selon un calendrier fondé sur le nombre de tâches. Un résultat réussi MAY être réutilisé uniquement avec la preuve que les entrées pertinentes sont équivalentes ; sinon il est réexécuté. Chaque exécution de porte laisse une trace concise : commande, périmètre, révision, résultat et un chemin de preuve.

Discipline de sécurité

La sécurité est de premier ordre au même titre que les tests, et elle suit le même modèle à deux couches : une discipline par tâche pendant le déroulement du travail, plus la passe de sécurité du Final Review sur l’ensemble des changements à la fin. Chaque fois qu’une tâche touche à l’authentification ou à l’autorisation, au traitement des entrées, aux secrets ou à la configuration, à la surface réseau, fichier ou shell, ou aux dépendances :

• Ses critères d’acceptation MUST énoncer les attentes de sécurité du changement — entrée validée et échappée, aucun élément secret dans le code ou les fixtures, contrôles d’authentification préservés ou renforcés — en cohérence avec docs/SECURITY.md.
• Chaque commit MUST être confirmé exempt de secrets ou d’identifiants avant d’être intégré, fixtures de test et exemples de documentation compris. Un secret présent dans un commit déjà poussé MUST être considéré comme divulgué et faire l’objet d’une rotation, et pas simplement supprimé.
• Lorsque le travail sensible à la sécurité est substantiel, une tâche de durcissement dédiée SHOULD être placée immédiatement après les tâches d’implémentation et avant la tâche de tests exhaustifs, afin que les constats soient corrigés avant que les tests n’encodent le comportement et que chaque constat devienne un cas de régression plutôt qu’une reprise.

Cette discipline par tâche ne remplace pas la passe de sécurité du Final Review : les vérifications par tâche détectent les problèmes dans le commit où ils naissent, tandis que la porte finale audite l’ensemble du plan — y compris les tâches de tests et de documentation elles-mêmes.

Cycle de vie du plan — le Final Review

Tout plan conforme rédigé sous cette version se termine par exactement une tâche obligatoire : le Final Review (tâche N). Deux responsabilités que les versions antérieures plaçaient dans des tâches de clôture distinctes sont relocalisées : les décisions de skills rejoignent la tâche qui a produit le motif, et l’Executive Report devient un artefact optionnel, sur demande. Rien de la passe de sécurité n’est relâché.

Le Final Review MUST, dans l’ordre :

(a) Passe de sécurité — relire l’ensemble accumulé des changements du plan à la recherche de secrets en dur, de risques d’injection, de nouvelle surface d’attaque, d’authentification affaiblie et de données sensibles dans les journaux ou la documentation ; auditer les dépendances introduites ; vérifier que docs/SECURITY.md reflète toujours la réalité ; rédiger le rapport de revue de sécurité même lorsqu’il est vierge. Un constat critique est corrigé — ou explicitement accepté par l’utilisateur — avant que le plan ne s’achève.

(b) Validation de l’état final — la validation complète applicable du dépôt s’exécute et réussit sur l’état final pertinent.

(c) Réconciliation des skills — chaque tâche porte une disposition de skills et chaque candidate consignée a une disposition ; pas de second rapport de découverte.

(d) Achèvement — rendre compte de l’achèvement avec les livrables, les preuves de validation et les limites ; proposer l’Executive Report une seule fois. Le plan est achevé, que la proposition reçoive une réponse ou non.

Le Final Review s’exécute séquentiellement après toutes les autres tâches et n’est jamais placé dans un groupe parallèle.

Décisions de skills par tâche

La question « ce travail a-t-il créé un motif réutilisable méritant un skill ou un agent ? » se répond à l’intérieur de la tâche qui a produit le motif, tant que ses preuves sont dans le contexte. Le Completion & Log de chaque tâche porte une disposition de skills : aucune, mettre à jour un skill existant, créer un artefact nommé, ou un report avec motif. La rédaction justifiée a lieu à l’intérieur de cette tâche, avant sa porte de validation et son commit, après vérification des doublons dans le catalogue existant.

Executive Report — optionnel, sur demande

L’Executive Report n’est plus une tâche obligatoire. À l’achèvement, l’agent le propose une fois ; il n’est généré que sur demande explicite, satisfait à partir de preuves durables sans rejouer le plan. Sans réponse, ou lors d’une exécution sans surveillance, le plan reste achevé sans qu’aucun rapport ne soit généré.

Protocole d’achèvement de tâche

Après avoir passé la validation et avant de passer à la tâche suivante, l’agent MUST, dans l’ordre : (1) marquer la tâche [x] dans le README du plan ; (2) incrémenter le compteur de statut du plan ; (3) remplir la section Completion & Log de la tâche sans valeur de substitution ; (4) ajouter une entrée de 3 à 5 puces dans PROGRESS.md ; (5) commiter (lorsque le plan commit) avec le format {type}({scope}): {description} — Task {N} of PLAN_{name} ; (6) lorsque le plan porte la couche d’état, réécrire state.json de façon atomique — tâche completed, enregistrements de portes, enregistrement de résultat, hash de commit.

Les six étapes forment une transaction logique unique. Un agent interrompu en cours de protocole MUST NOT démarrer la tâche suivante — il doit d’abord terminer ou annuler l’achèvement partiel.

Le protocole de reprise DWP

La reprise MUST être possible à partir des seuls fichiers du plan et du journal git, sans état externe. Dans un espace de travail sans git — voir Archétypes §3 — le state.json du plan est REQUIRED et remplace le journal git.

Un agent reprenant — une nouvelle session, un agent différent, un tour de daemon planifié, ou une session cloud se réveillant — MUST réaliser ce rituel, dans l’ordre :

1. Ré-ancrage. Lire le README du plan : objectif, directives globales, liste des tâches.
2. Localiser le point de reprise. Trouver la première tâche non cochée dans le README ; lire le journal git et le statut git (ou le checkpoint de state.json en l’absence de git).
3. Réconcilier l’état. Lorsque state.json existe, le comparer aux cases du README ; en cas de désynchronisation, le régénérer depuis le markdown avant de continuer.
4. Inspecter la jonction. Lire la section Completion & Log de la tâche de reprise et la dernière entrée de PROGRESS.md — le dernier terrain vérifié de la session précédente.
5. Smoke test. Exécuter la validation permanente la moins coûteuse du dépôt pour confirmer que le monde fonctionne encore avant de construire dessus. Un smoke test en échec est d’abord investigué, pas ignoré.
6. Continuer de façon atomique. Exécuter exactement la tâche suivante ; ne pas regrouper en avance.

L’agent MUST faire confiance aux marqueurs [x] achevés et MUST NOT re-valider les tâches achevées, sauf si l’utilisateur le demande explicitement ou si le smoke test échoue d’une façon qui implique une tâche achevée.

La boucle d’exécution

DWP définit cinq opérations :

• create — Génère un nouveau plan à partir d’un objectif.
• execute — Exécute le plan tâche par tâche.
• refine — Modifie un plan existant.
• resume — Reprend un plan interrompu.
• status — Rend compte du statut du plan sans exécuter.

Espace de travail de sortie

Espace de travail de sortie

• .dwp/ ignoré par git · jetable
• plans/
• PLAN_<name>/
• README.md
• PROGRESS.md
• <n>.task_<slug>.md
• analysis_results/ rapports
• SECURITY_REVIEW.md revue de sécurité
• EXECUTIVE_REPORT.md rapport exécutif

Tous les artefacts DWP MUST résider sous un répertoire .dwp/ ignoré par git, à la racine du dépôt.

État du plan lisible par machine

Un plan MAY porter la couche d’état lisible par machine — manifest.json (identité statique) et state.json (état en direct par tâche, enregistrements de portes de validation, enregistrements de résultats, point de reprise, état bloqué). Le plan markdown reste la source de vérité ; la couche JSON est une projection dérivée, régénérée aux points de protocole et réconciliée à la reprise.

La couche d’état est RECOMMENDED pour les nouveaux plans, REQUIRED pour l’exécution sans surveillance, et REQUIRED pour les espaces de travail d’agents sans git. Voir la définition normative complète dans État du plan.

Rigueur proportionnelle

La rigueur MUST être proportionnelle au travail. La cérémonie sur des changements triviaux est un échec de la méthodologie, pas une sécurité supplémentaire. Chaque travail appartient exactement à un niveau :

Un agent invité à créer un plan pour un travail de niveau micro MUST dire qu’un plan est disproportionné et proposer la forme en ligne à la place. Un dossier de plan MUST NOT être créé pour un changement trivial d’un seul fichier.

Le travail de niveau micro conserve quand même les non-négociables : un objectif explicite, une porte de validation qui s’exécute et passe, et la discipline de test pour les changements de comportement. Le niveau change le conditionnement, jamais les portes.

Lorsque le périmètre grandit en cours d’exécution — une tâche micro révèle un périmètre réel, un plan standard fait apparaître des sous-dépôts — l’agent MUST s’arrêter et promouvoir le travail au niveau suivant plutôt que d’étirer le niveau actuel.

Compatibilité

Les plans et dépôts des versions antérieures restent conformes, et un vérificateur de conformité MUST distinguer un artefact hérité connu (accepté) d’un artefact qui déclare cette version et se révèle objectivement invalide sous elle (rejeté) :

Versionnage

Cette spécification suit le versionnage sémantique.