n0ctx/dag-engineering

DAG Engineering

Transforme les tâches d'ingénierie logicielle de grande envergure en sous-tâches dépendantes (nœuds) ; chaque nœud est implémenté par un sous-agent dans son propre worktree et sa propre branche, et l'agent principal les fusionne et les valide un par un dans le worktree d'intégration. Cette isolation s'applique également aux reprises : les sous-agents ne modifient ni ne valident dans le worktree d'intégration. L'agent principal est responsable de l'enquête, de la planification, de la distribution, de l'intégration, de l'organisation des reprises et de la validation finale ; les sous-agents d'enquête répondent uniquement en lecture seule à des questions spécifiques ; les sous-agents de nœud doivent d'abord affiner la tâche (refine), puis l'implémenter et valider un seul nœud ; les sous-agents de révision examinent en lecture seule.

La profondeur de l'enquête, le nombre de sous-agents et l'étendue de la validation sont déterminés par la complexité réelle de la tâche ; ne pas décomposer pour utiliser des sous-agents s'il n'y a pas de travail indépendant.

Codex définit explicitement fork_turns="none" lors de la distribution de tout sous-agent.

0. Reprendre un plan existant

Avant de commencer, vérifiez .dag/ dans le répertoire de travail principal. S'il existe un plan avec le statut "plan : en cours", lisez-le, et en fonction de l'état réel de Git, continuez à partir de l'avancement actuel, sans le redécomposer. Si le plan ne correspond pas à l'état de Git, corrigez le plan en fonction de l'état vérifié du code.

1. Si le worktree d'intégration contient MERGE_HEAD (git -C <wt_int> rev-parse -q --verify MERGE_HEAD) : l'intégration a été interrompue, les résultats de la validation sont inconnus ; exécutez git merge --abort, puis réintégrez ce nœud en tant que submitted.
2. Vérifiez chaque nœud un par un :
   • done : confirmez que la validation du nœud a été fusionnée dans la branche d'intégration (git -C <wt_int> merge-base --is-ancestor <validation> HEAD), ne l'exécutez pas à nouveau.
   • submitted : si la validation du nœud a déjà été fusionnée dans la branche d'intégration, marquez-la directement comme done (la validation de fusion n'est générée qu'après la réussite de la validation) ; sinon, intégrez-la selon l'étape 6.
   • running : si l'agent de la session en cours exécute encore le nœud, continuez à attendre. Si l'agent n'existe plus, examinez les validations et les modifications non validées du worktree du nœud, et affectez un nouvel agent au même worktree pour continuer à partir des résultats existants, sans créer un nouveau worktree.
   • blocked : lisez la raison, déterminez si la condition est déjà levée.
   • pending : planifiez selon l'étape 5. Si le nœud utilise encore l'ancien format (objectif, périmètre, étapes, vérification, validation), réécrivez-le selon le modèle de l'étape 4 avant de le distribuer.
3. Si tous les nœuds sont done : passez à l'étape 7.

En cas d'état incertain, ne supprimez pas les worktrees, les branches ou les modifications non validées.

1. Créer le worktree d'intégration

Créez un worktree d'intégration et une branche pour chaque DAG, modifiés uniquement par l'agent principal ; le répertoire de travail principal n'est pas modifié.

git worktree add "../<repo>-<plan-id>" -b "dag/<plan-id>"

• <plan-id> : utilisez une brève description en kebab-case pour le travail en cours ; si la branche ou le répertoire existe déjà, choisissez un autre nom.
• Si le répertoire de travail principal contient des modifications non validées, informez l'utilisateur que ces modifications ne seront pas intégrées dans le worktree et laissez-le décider de les valider d'abord ou de continuer.
• Si les commandes de validation dépendent d'étapes d'installation (par exemple node_modules, environnements virtuels), effectuez d'abord l'installation dans le worktree d'intégration.
• Enregistrez la validation de départ (git rev-parse HEAD) comme référence pour la révision globale.

2. Enquête et conception clé

Ordre : analyse des besoins → enquête de code ciblée → conception clé unifiée.

L'agent principal identifie d'abord l'implémentation existante, les modules concernés, les relations d'appel et les tests en fonction des besoins, et liste les questions inconnues qui affectent la planification. Si les ambiguïtés modifient l'objectif, la portée ou les critères de validation, demandez d'abord à l'utilisateur ; sinon, incluez les incertitudes dans les "hypothèses" du plan.

S'il existe plusieurs questions d'enquête indépendantes, distribuez des sous-agents d'enquête en lecture seule dans le même message pour enquêter en parallèle ; si les questions sont peu nombreuses ou interdépendantes, l'agent principal enquête lui-même. L'enquête est divisée en questions spécifiques (implémentations existantes et réutilisation, interfaces clés et chaînes d'appel, état partagé et ressources externes, tests et contraintes d'ingénierie, etc.), pas mécaniquement par répertoire. Les sous-agents d'enquête lisent directement le worktree d'intégration ; ils n'ont pas besoin de leur propre worktree. Les instructions précisent :

Enquête en lecture seule <wt_int>, ne modifiez aucun fichier, ne distribuez pas d'autres agents. Objectif : <...>. Périmètre : <...>. Réponses nécessaires : . Arrêtez une fois les questions répondues, n'explorez pas au-delà du périmètre. Rapports uniquement : faits clés et leurs emplacements (fichier:symbole), implémentations existantes réutilisables, contraintes d'ingénierie, éléments non confirmés ; distinguez les faits confirmés des suppositions.

L'agent principal intègre les résultats, traite les conclusions contradictoires et ne comble les lacunes affectant la planification que par des enquêtes complémentaires. Arrêtez l'enquête une fois que les faits sont suffisants pour rédiger le goal, le scope, le verify et le stop d'un nœud ; laissez les détails des steps aux sous-agents de nœud lors de leur mise en œuvre (étape 5). L'enquête lors de la planification ne va que jusqu'à la profondeur nécessaire pour définir les limites des nœuds : utilisez des requêtes structurelles (fichiers et nombres de lignes, relations d'appel, arêtes de dépendance, entrées de liste) pour répondre, ne lisez pas l'implémentation des fonctions ; la lecture de l'implémentation est la tâche du sous-agent de nœud.

Les faits inter-modules (qui appelle un symbole donné, de quoi dépend un module, la taille d'un groupe de fichiers avec ses dépendances) sont recherchés à l'aide du serveur de langage, d'ast-grep ou de la recherche sur demande, sans lire l'intégralité du code source déductivement ; une fois trouvés, enregistrez-les pour les réutiliser. Les faits trouvés par l'agent principal ou les sous-agents d'enquête sont écrits dans le résultat de l'affinage (refine) ou une note du nœud concerné. Les sous-agents de nœud listent les nouveaux faits inter-modules découverts dans leur rapport ; l'agent principal les enregistre dans l'affinage des nœuds en aval qui les utiliseront. Lorsque ces nœuds aval commencent, ils consultent d'abord ces enregistrements ; s'ils sont insuffisants ou potentiellement obsolètes (le code concerné a été modifié par un nœud suivant), ils recherchent à nouveau.

Ensuite, déterminez et écrivez la "conception clé" dans le plan :

• Comportement cible et non-cible ;
• Implémentations existantes, dépendances ou capacités de la plateforme directement réutilisables ;
• Attribution des fonctionnalités et du code ;
• Interfaces, structures de données et contraintes architecturales qui doivent être cohérentes entre les nœuds ;
• Ressources partagées et conditions d'intégration.

Ne fixez que la conception nécessaire à la collaboration entre les nœuds ; l'implémentation interne des nœuds est laissée aux sous-agents de nœud. N'ajoutez pas d'abstractions pour des besoins futurs, ne réimplémentez pas les capacités existantes.

3. Décomposer le DAG

• Granularité du nœud : basée sur une unité de comportement pouvant être validée indépendamment, incluant les connexions nécessaires pour la rendre exécutable et vérifiable. La configuration, l'échafaudage et la documentation, s'ils ne sont utilisés que par un seul nœud, sont fusionnés dans ce nœud ; s'ils sont utilisés par plusieurs nœuds, ils sont transformés en un nœud en amont. Un travail fortement couplé, dont la séparation créerait des états intermédiaires non vérifiables ou une duplication importante des modifications, est fusionné en un seul nœud ; un travail faiblement couplé est séparé pour permettre le parallélisme. Ne décomposez pas de force pour augmenter le parallélisme.
• Vérification élément par élément : lorsqu'un nœud doit couvrir un grand nombre de fichiers ou d'entrées, identifiez d'abord les éléments à vérifier et les critères de validation individuels ; les plages pouvant être vérifiées indépendamment sont confiées à des sous-agents en lecture seule pour un traitement parallèle, puis les lacunes sont résumées avant la mise en œuvre. Si les conclusions d'une vérification précédente sont toujours valides, réutilisez-les sans nouvelle analyse.
• Dépendances : n'écrivez une dépendance que lorsque le nœud aval a réellement besoin du code, de la décision ou du comportement vérifié du nœud amont, ou si l'échec du nœud amont rendrait le nœud aval inutile. Si l'interface partagée a déjà été déterminée dans la conception clé et que les deux parties peuvent l'implémenter et la tester indépendamment, n'écrivez pas de dépendance, permettez le parallélisme et laissez la vérification d'intégration vérifier la concordance réelle. N'inventez pas de dépendances pour contrôler l'ordre.
• Conflits : marquez un conflit uniquement pour les nœuds qui, bien que sans dépendance, ne peuvent pas être exécutés en toute sécurité en parallèle : modifications qui s'affectent logiquement, ressources d'exécution partagées (bases de données, ports), ressources qui doivent être allouées en série (numéros de migration). Un chevauchement ordinaire de modifications sur le même fichier n'est pas considéré comme un conflit ; le parallélisme est autorisé et Git gère la fusion. Ne marquez un conflit que si le chevauchement est concentré et que le coût de la fusion est nettement plus élevé que l'exécution en série.
• Schémas nécessitant encore une expérimentation pour être déterminés : créez un nœud d'enquête qui produit une conclusion ; les nœuds en aval en dépendent.

Chaque nœud est écrit selon le modèle de l'étape 4. Lors de la planification, écrivez goal, scope, verify, stop, refine ; les steps sont élaborés par le sous-agent de nœud lors de sa mise en œuvre selon le refine (étape 5). Vous pouvez écrire d'abord les étapes déjà déterminables lors de la planification.

• goal : une ou deux phrases décrivant le comportement qui sera établi une fois le travail terminé.
• scope : fichiers ou répertoires qu'il est permis de modifier, parties qu'il est explicitement interdit de modifier, ainsi que la conception clé et les contraintes métier à respecter.
• verify : résultats de validation observables et commandes réelles directement exécutables, incluant les garde-fous existants affectés par les modifications de ce nœud (comme la taille de la documentation, la complexité du code, les vérifications de couches et de contrats). Privilégiez les points d'entrée étroits ; s'il n'y en a pas, exécutez une vérification complète, sans la lancer en concurrence avec d'autres validations.
• stop : conditions spécifiques à ce nœud pour s'arrêter et faire rapport, par exemple "impossible de déterminer l'attribution selon les règles" ou "une certaine interface n'existe pas". Les conditions générales sont déjà dans les instructions de distribution, ne les répétez pas.
• refine : éléments à éclaircir pour les steps, formulés comme des requêtes exécutables, par exemple "listez toutes les entrées sous le préfixe X et leurs modules de dépendance non traités" ou "listez tous les appelants de Y". Ces requêtes sont exécutées par le sous-agent de nœud dans la première phase de son travail. Si des conclusions ont déjà été tirées lors de la planification ou de l'enquête, écrivez-les directement dans refine en les marquant comme déjà vérifiées ; le sous-agent les utilise directement sans revérifier ; refine ne laisse que les questions non encore répondues comme requêtes. S'il n'y a rien à vérifier, écrivez "aucun".
• steps : étapes ordonnées, chacune faisant une seule chose vérifiable, écrites au niveau du module, de la commande, de l'interface : quoi faire, où, quel est le comportement externe. Au niveau de la fonction, n'écrivez que les limites : si le même fichier doit être partagé entre différents nœuds, ou si l'attribution d'une fonction est contestée, listez les fonctions de chaque côté.

Les valeurs, conditions et limites déjà déterminées à partir des documents sources et de la conception clé sont directement écrites dans les nœuds concernés, sans être laissées à la déduction du sous-agent. Les fichiers, symboles et commandes doivent provenir du code réel, ne les inventez pas. Remplacez les formulations suivantes :

• Descriptions inexécutables comme "implémenter selon les besoins" ou "gérer les cas limites" ;
• Critères de validation qui ne font que répéter l'action d'implémentation, comme "X a été implémenté" ;
• Validation comportementale basée uniquement sur l'existence d'un fichier, une importation réussie ou une recherche par mot-clé ;
• Classification ou sélection qui ne fait que référencer un nom de règle ou une section de document (par exemple "selon D7"), sans écrire l'action par défaut et les conditions d'exception.

Avant la distribution, vérifiez le plan en répondant à deux séries de questions.

Une fois le plan entièrement terminé, les critères de validation globaux sont-ils nécessairement atteints. Vérifiez les lacunes selon les points suivants :

1. Le périmètre est énuméré à partir des sources réelles, pas seulement déduit des besoins : code concerné, configuration, fichiers hors du dépôt et état de la machine, installation et déploiement, autres plateformes d'exécution, appelants externes. Chaque élément appartient exactement à un nœud ou est écrit comme non-objectif.
2. Chaque validation est valide : peut être exécutée dans l'environnement cible ; n'écrit pas dans les données de production ou les systèmes externes lors de l'exécution (les nœuds qui doivent le faire précisent la méthode d'isolement) ; réussir la validation implique la conclusion correspondante ; l'outil de validation lui-même a déjà été validé.
3. Les exemptions temporaires, les couches de compatibilité, les données transitoires et les outils introduits par le plan ont tous un nœud responsable de leur suppression ou de leur officialisation.
4. Les chemins impliquant des systèmes externes, le basculement vers l'environnement de production ou l'exécution uniquement sur d'autres plateformes doivent être exécutés au moins une fois dans un environnement réel par un nœud avant la livraison.
5. Les interfaces entre les nœuds et l'architecture sont cohérentes ; les dépendances et les conflits sont corrects et complets ; l'intégration entre les nœuds a un nœud responsable ; le refine de chaque nœud peut produire ses steps, et le verify peut être exécuté.

Transformez les lacunes en nœuds. Si cela n'est pas possible, ou si le coût de la correction nécessite une décision de l'utilisateur, écrivez-le dans la section "Lacunes d'achèvement" du plan et soumettez-le à l'utilisateur.

La conception gaspille-t-elle du temps.

6. Chaque nœud produit quelque chose utilisé par un autre nœud (y compris la validation) ; supprimez les nœuds inutiles.
7. Les nœuds qui nécessitent une décision ou la présence de l'utilisateur, ou qui modifient le comportement existant, ne doivent pas faire attendre les autres nœuds ; si des nœuds en aval doivent les attendre, divisez-les en une partie qui ne modifie pas le comportement (à faire d'abord) et une partie qui le modifie (à faire ensuite).
8. Une capacité ou un outil utilisé par plus de deux nœuds doit être transformé en un nœud en amont, afin que chaque nœud ne le fasse pas individuellement. Vérifiez pour chaque nœud sur quoi repose sa validation : si plus de deux nœuds utilisent le même moyen de validation (comparaison ancien/nouveau, rejeu, comparaison de produits, etc.), transformez-le également en un nœud d'outil en amont, dont la validation inclut la preuve qu'un échantillon connu comme différent peut produire une différence. Si plus de deux nœuds doivent consulter à plusieurs reprises les mêmes documents volumineux (listes, tables de correspondance, documents de décision) et que le projet n'a pas de point d'entrée pour les interroger sur demande, créez également un nœud en amont pour y remédier.
9. Estimez le volume de code à lire et à modifier pour chaque nœud (en fonction des fichiers dans le scope plus le code non encore traité dont il dépend). Si le volume est trop important pour qu'un seul sous-agent puisse le gérer de manière fiable, ou s'il s'étend sur des modules non liés pouvant être validés indépendamment, divisez-le ; si la cohésion est forte et que la division créerait un état intermédiaire non vérifiable, ne divisez pas même si le volume est important. Le nombre de lignes n'est qu'un indicateur, pas un seuil fixe. Si l'estimation est impossible, incluez ce qui doit être calculé dans le refine, et demandez au sous-agent de nœud de l'estimer lors de sa première phase ; la méthode de division doit être déterminée avant la création du worktree, en envoyant d'abord un sous-agent d'enquête pour estimer selon l'étape 5.
10. Aucune capacité existante n'est réimplémentée, il n'y a pas de division inutile ou de sur-ingénierie, et les nœuds pouvant être parallélisés en toute sécurité ne sont pas sérialisés.

Si le nombre de nœuds est inférieur ou égal à 5, l'agent principal vérifie. Si le nombre est supérieur à 5, écrivez d'abord le projet selon l'étape 4 dans .dag/<plan-id>.md, puis distribuez un sous-agent de révision en lecture seule qui reçoit uniquement le plan, les besoins et les emplacements du code, sans les raisonnements de l'agent principal :

Révision en lecture seule <chemin du plan>, ne modifiez aucun fichier, ne distribuez pas d'autres agents. Besoins : <besoins d'origine ou leur emplacement>. Code : <wt_int>. Vérifiez élément par élément selon les points suivants : <texte des points 1 à 10 ci-dessus>. Rapports uniquement : lacunes pour atteindre l'objectif, conceptions qui font perdre du temps, points nécessitant une décision de l'utilisateur ; pour chaque élément, donnez l'emplacement, la preuve (fichier:symbole, sortie de commande ou texte du plan) et une suggestion de modification minimale ; distinguez les problèmes certains des suppositions.

L'agent principal ne modifie que les problèmes étayés par des preuves concrètes.

4. Enregistrer le plan

Écrivez le plan dans le répertoire de travail principal sous .dag/<plan-id>.md, sans le placer dans aucun worktree, pour éviter qu'il ne soit validé. Si .dag/ n'est pas ignoré par Git, ajoutez-le à .git/info/exclude.

# <plan-id>

- Objectif :
- Critères de validation globaux :
- Non-objectifs :
- Hypothèses :
- Lacunes d'achèvement : <parties qui ne peuvent toujours pas être garanties après la fin du plan, et décision de l'utilisateur ; si aucune, écrire "aucune">
- Conception clé :
- Statut du plan : en cours
- Worktree d'intégration : <chemin>   Branche : dag/<plan-id>   Point de départ : <sha>
- Fichier d'enregistrement des interfaces : `.dag/<plan-id>-interfaces.md`

## Nœuds

### N1 <titre>
#### goal
#### scope
#### steps
<À élaborer par le sous-agent de nœud lors de sa mise en œuvre>
#### verify
#### stop
#### refine
#### state
- Dépendances : aucune
- Conflits : aucun
- Statut : pending
- Worktree :   Branche :   Validation :

## Journal d'exécution
- N1 : <sha de la validation de fusion> <résultat en une phrase>.<reprise, anomalie ou problème restant ; si rien, ne pas écrire>

Le fichier d'enregistrement des interfaces est placé avec le plan ; une section est ajoutée après chaque fusion de nœud ; les sous-agents de nœud peuvent le lire en lecture seule :

## N1 (<sha de la validation de fusion>)
- <Interface, nom et emplacement> : <forme et utilisation>

Le journal d'exécution ne contient que les résultats et les problèmes restants ; les interfaces externes sont écrites dans le fichier d'enregistrement des interfaces ; les faits inter-modules sont écrits dans le refine des nœuds en aval qui les utiliseront ; les détails des comparaisons, etc., restent dans le message de validation et le fichier de rapport du nœud.

goal à refine sont transmis au sous-agent de nœud ; state est à usage exclusif de l'agent principal.

Valeurs de l'état :

• pending : non distribué ;
• running : le sous-agent est en train de l'implémenter ou de le reprendre ;
• submitted : le sous-agent a validé, en attente d'intégration ;
• done : fusionné dans la branche d'intégration et validé par l'agent principal ;
• blocked : impossible de continuer, la raison est écrite dans le journal d'exécution.

Le plan est modifié uniquement par l'agent principal. Chaque changement d'état est immédiatement mis à jour ; c'est la base pour continuer le travail entre les sessions.

Après l'enregistrement, présentez brièvement à l'utilisateur les nœuds, les dépendances, les nœuds parallélisables, les lacunes d'achèvement et tous les points nécessitant une décision de l'utilisateur (listez tout en une fois, ne posez pas de questions en plusieurs tours). Si l'utilisateur ne demande qu'un plan, arrêtez-vous ici ; sinon, continuez l'exécution.

5. Distribution dynamique

Les nœuds pending dont toutes les dépendances sont done et qui n'ont pas de conflit avec les nœuds running/submitted sont des nœuds prêts. Identifiez tous les nœuds prêts et distribuez-les en parallèle dans le même message, sans limite de concurrence fixe ; la concurrence réelle est déterminée par la capacité de l'outil et de l'agent. Ensuite, chaque fois qu'un nœud devient done, identifiez immédiatement les nouveaux nœuds prêts et distribuez-les, sans attendre la fin des autres nœuds indépendants.

Avant de distribuer chaque nœud, l'agent principal effectue une vérification préalable : listez les décisions, interfaces, noms et règles en amont utilisés par ce nœud et confirmez qu'ils ont tous été fusionnés dans le HEAD de la branche d'intégration. Si l'un de ces éléments doit encore être modifié par un nœud running ou pending, ajoutez une dépendance à ce nœud et ne le distribuez pas encore.

Les requêtes de refine sont exécutées par le sous-agent de nœud dans sa première phase ; l'agent principal ne les exécute pas lui-même. Deux exceptions : suivez d'abord l'étape 2 pour distribuer un sous-agent d'enquête en lecture seule qui ne collecte que les conclusions :

• Un nœud peut devoir être divisé en plusieurs nœuds parallélisables, et la méthode de division doit être déterminée avant la création du worktree : le sous-agent d'enquête estime le volume et le couplage selon le refine, puis l'agent principal divise selon le point 9 de l'étape 3 avant de distribuer séparément.
• Plusieurs nœuds prêts doivent répondre à la même question : distribuez un seul sous-agent d'enquête pour répondre à tous en même temps, pas un sous-agent par nœud.

Ensuite, créez le worktree du nœud à partir du HEAD actuel de la branche d'intégration (la dernière validation d'intégration validée), écrivez le chemin et la branche dans le plan et marquez-le comme running :

git -C <wt_int> worktree add "../<repo>-<plan-id>-<id-noeud>" -b "dag-node/<plan-id>/<id-noeud>" HEAD

Si la validation dépend d'étapes d'installation, demandez dans les instructions au sous-agent de nœud de les effectuer d'abord dans son propre worktree.

Les instructions pour le sous-agent de nœud sont organisées dans l'ordre suivant et ne contiennent que ces éléments :

1. Chemin et branche du worktree.
2. Texte original du goal, scope, steps (si existants), verify, stop, refine de ce nœud dans le plan.
3. note (écrit uniquement dans les instructions, pas dans le plan) :
   • Chemin absolu du fichier d'enregistrement des interfaces ; donnez uniquement le chemin, ne répétez pas les interfaces en amont.
   • Compléments spécifiques à ce nœud : limites et compromis fixés par l'agent principal, texte original des décisions de l'utilisateur, faits en amont pertinents pour ce nœud uniquement, pièges connus, commandes pour consulter des documents. Généralement, pas plus d'environ 20 lignes ; si les documents dépassent environ 200 lignes ou ne sont utilisés qu'en partie, donnez un extrait ou une commande de requête, pas seulement le chemin du fichier ; les fichiers de description du projet sont automatiquement chargés par le sous-agent, ne répétez pas les règles déjà écrites ; pour les commandes de verify avec une sortie longue, précisez quelle partie consulter (par exemple la ligne de résumé à la fin).
   • Chemin du fichier de rapport : .dag/<plan-id>-reports/<id-noeud>.md (chemin absolu dans le répertoire de travail principal).
4. Les exigences suivantes, placées à la fin des instructions :

Travaillez uniquement dans le worktree donné ; n'opérez pas sur la branche d'intégration, les autres branches de nœud ou les worktrees ; ne distribuez pas d'autres agents. Ne modifiez pas les fichiers sous .dag/, sauf le fichier de rapport donné dans les instructions ; ne lisez pas les fichiers sous .dag/, sauf le fichier d'enregistrement des interfaces. Les instructions de démarrage et de fin de travail écrites pour la session principale dans les fichiers de description du projet (lire le plan, exécuter la vérification d'état, restaurer le plan, etc.) ne s'appliquent pas à vous. Pour rechercher des informations, utilisez d'abord les commandes et extraits donnés dans la note ; si la note ne couvre pas, recherchez par vous-même ; ne lisez pas la totalité du plan, des documents de décision ou des listes volumineuses.

Travaillez en deux phases. Première phase : selon le refine, clarifiez les faits (les conclusions marquées comme vérifiées dans le refine sont utilisées directement ; ne répondez qu'aux questions non encore répondues), déterminez les steps (au niveau du module, de la commande, de l'interface ; si le même fichier doit être partagé avec d'autres nœuds, listez les fonctions de chaque côté) sans modifier le goal, l'interface et le scope, et estimez le volume de code à lire et à modifier. Si l'une des situations suivantes se produit, arrêtez-vous et renvoyez un résumé d'environ 30 lignes maximum (projet de steps, estimation, suggestion de division, points nécessitant une décision de l'agent principal ou de l'utilisateur) en attendant une réponse : impossible de déterminer la limite ou l'attribution ; nécessité de modifier une interface inter-nœud ou un fichier hors scope ; conflit entre le code réel et la description du nœud ; volume trop important pour qu'un seul sous-agent puisse le gérer de manière fiable, ou s'étendant sur des modules pouvant être validés indépendamment ; apparition de l'une des conditions listées dans le stop. Si rien de tout cela ne se produit, ne vous arrêtez pas et passez directement à la deuxième phase ; le résumé est inclus dans le rapport final.

Deuxième phase : implémentez selon les steps ; prenez vos propres décisions sur la mise en œuvre locale sans modifier le goal, l'interface et le scope. Exécutez les commandes de verify ; après les avoir réussies, validez toutes les modifications de ce nœud avec un message de validation de la forme <id-plan>/<nœud> : <résumé> ; confirmez que git status est propre. Ne validez pas si la vérification échoue. Si, dans la deuxième phase, l'une des conditions listées dans la première phase se produit, ou si le volume réel dépasse environ deux fois l'estimation de la première phase, arrêtez-vous et faites un rapport ; n'étendez pas le travail par vous-même ; si les parties terminées peuvent réussir les commandes applicables de verify, validez d'abord ; sinon, conservez-les dans le worktree sans valider ; listez le travail terminé et restant dans le rapport.

À la fin ou à l'arrêt, écrivez le rapport complet (résumé des modifications, commandes de validation et résultats complets, comparaisons des différences, explication des écarts) dans le fichier de rapport ; ne renvoyez à l'agent principal qu'environ 40 lignes maximum : état (DONE : terminé et validé ; DONE_WITH_CONCERNS : terminé mais avec des doutes ; BLOCKED : impossible de terminer ou arrêté), sha de validation, résultat de la validation en une ligne, nouvelles interfaces ou modifications d'interfaces externes, nouveaux faits inter-modules découverts (par exemple quels autres modules utilisent un symbole donné, quelle est la forme réelle d'une interface), raisons des doutes ou du blocage, points nécessitant une décision.

Lorsque le sous-agent s'arrête dans la première phase et renvoie un résumé, l'agent principal vérifie les limites et les points nécessitant une décision (demandez d'abord à l'utilisateur si nécessaire), écrit les steps confirmés dans le plan, puis utilise la capacité de reprise de l'outil (SendMessage de Claude Code ; Codex envoie une entrée ultérieure au même agent) pour que le même sous-agent continue dans la deuxième phase, sans distribuer un nouvel agent, pour éviter qu'il ne relise le code déjà parcouru. Si une division est suggérée, suivez la règle de l'étape 6 "plan lui-même erroné" : l'agent d'origine continue une partie, le reste devient un nouveau nœud distribué à partir de l'étape 5. Si l'agent d'origine ne peut pas être repris, distribuez un nouvel agent dans le même worktree et joignez le résumé.

Après le retour de la validation par le sous-agent, écrivez le sha de la validation dans le plan, marquez-le comme submitted et passez à l'étape 6.

Règles d'attente (applicables également aux sous-agents d'enquête et de révision) :

• S'il y a un travail concret et indépendant qui n'entre pas en conflit avec le périmètre du sous-agent (par exemple l'intégration d'un nœud validé), terminez-le d'abord ; sinon, passez à l'attente native.
• Claude Code utilise les notifications d'achèvement des agents en arrière-plan ou l'attente native. Codex appelle directement l'outil d'agent, sans utiliser functions.exec ou functions.wait ; pour wait_agent, définissez timeout_ms=600000 ; si l'outil ne prend pas en charge cette valeur, utilisez la durée d'attente maximale autorisée. Si l'outil ne peut renvoyer les résultats qu'en batch, traitez selon sa capacité, ne simulez pas de notifications inexistantes.
• N'utilisez pas de boucles avec sleep court, d'interrogation de la liste des agents ou de vérification répétée de l'état Git pour remplacer l'attente ; ne raccourcissez pas l'attente pour envoyer des mises à jour de progression.
• Traitez immédiatement les résultats ou les messages de l'utilisateur dès qu'ils arrivent. Un délai d'attente dépassé ne signifie pas un échec ; continuez à attendre, ne redistribuez pas un nœud encore en cours d'exécution.

6. Validation et intégration nœud par nœud

L'agent principal intègre un nœud submitted à la fois dans le worktree d'intégration ; les autres sous-agents continuent leur travail. Ne vous fiez pas directement au rapport du sous-agent :

1. git -C <wt_int> diff --stat HEAD...<branche_du_noeud> : les fichiers modifiés sont tous dans le scope du nœud ; git status dans le worktree du nœud ne montre aucune modification non validée restante. Examinez ensuite le diff complet des fichiers partagés avec d'autres nœuds (modules publics, configuration, lignes de base des garde-fous, listes, tests de contrat) pour confirmer la conformité avec le goal et la conception clé. Le nouveau code propre au nœud est évalué via les validations de l'étape 3 et le comportement mesuré, pas par une lecture ligne par ligne ; si des détails sont nécessaires, consultez les sections pertinentes du fichier de rapport.
2. Fusionnez mais ne validez pas encore :

   git -C <wt_int> merge --no-ff --no-commit "dag-node/<id-plan>/<id-noeud>"
   

3. Dans le worktree d'intégration, exécutez les commandes du verify du nœud, ainsi que les vérifications d'intégration affectées par la fusion ; vérifiez un par un les résultats de validation du verify, en testant au moins un comportement réellement. Les nouvelles échecs des garde-fous affectés sont corrigés dans ce nœud, sans être reportés à la validation finale ; les échecs préexistants sont enregistrés séparément, sans assouplir les seuils ou les lignes de base. N'exigez pas à chaque fois l'exécution complète de la suite de tests.
4. Si tout réussit : git -C <wt_int> commit --no-edit, marquez le nœud comme done, écrivez une ligne de journal d'exécution, ajoutez les interfaces externes au fichier d'enregistrement des interfaces, écrivez les faits inter-modules dans le refine des nœuds en aval qui les utiliseront, puis revenez à l'étape 5 pour distribuer les nouveaux nœuds déverrouillés.

Pour les validations de type couverture de liste, enregistrez un par un les conclusions vérifiées, les éléments en attente de vérification et les lacunes. Un nœud ne peut être marqué done que si l'ensemble du périmètre déclaré a été vérifié et satisfait aux critères de validation ; l'existence d'un fichier, un contenu non vide ou une vérification par sondage ne remplacent pas une couverture exhaustive.

En cas de conflit de fusion, si le chevauchement est ordinaire et que l'intention des deux parties est claire, l'agent principal le résout directement, puis passe à l'étape 3.

Pour les autres conflits ou les vérifications échouées, annulez la fusion non terminée (git -C <wt_int> merge --abort) ; la branche d'intégration reste sur la dernière validation validée ; la validation du nœud reste sur sa branche. Traitez selon l'origine du problème :

• Défaut d'implémentation du nœud : remettez le nœud à running, renvoyez le problème spécifique au sous-agent de nœud d'origine pour correction dans le même worktree, puis refaites la validation ; si l'agent d'origine ne peut pas être repris, distribuez un nouvel agent dans le même worktree pour continuer. L'agent principal ne réécrit pas par défaut l'implémentation du nœud.
• Conflit nécessitant que le nœud se réfère aux derniers résultats d'intégration : demandez au sous-agent de nœud de fusionner dag/<plan-id> dans son propre worktree, de résoudre le conflit, de revalider et de valider à nouveau.
• Conflit d'interface ou de logique entre nœuds : l'agent principal détermine la conception correcte, met à jour la conception clé du plan et les nœuds concernés, puis les transmet aux sous-agents des nœuds concernés pour ajustement.
• Plan lui-même erroné (scope, steps, dépendances ou verify ne correspondent pas au code réel) : en fonction des faits de code nouvellement découverts, ne modifiez que les nœuds, dépendances et validations affectés ; conservez les résultats déjà valides ; ne reconcevez pas l'ensemble du DAG. Si la modification affecte les critères de validation globaux ou les non-objectifs, demandez d'abord à l'utilisateur.
• Le sous-agent rapporte DONE_WITH_CONCERNS : si les doutes affectent les critères de validation, traitez comme un échec ; sinon, intégrez normalement et écrivez les doutes dans le journal d'exécution.
• Le sous-agent s'arrête parce que le volume réel dépasse l'estimation : si la partie déjà validée peut être validée indépendamment, modifiez le goal, le scope et le verify du nœud en fonction de la partie terminée, intégrez-la selon cette étape ; le travail restant est traité comme un "plan lui-même erroné" et divisé en un nouveau nœud distribué à partir de l'étape 5. Si la partie déjà validée ne peut pas être validée indépendamment, ne l'intégrez pas ; le nœud reste running, écrivez le travail restant dans ses steps, et distribuez un nouvel agent dans le même worktree pour continuer à partir des résultats existants.
• Le sous-agent rapporte BLOCKED ou le nœud ne peut pas continuer : marquez-le comme blocked et enregistrez la raison spécifique ; les nœuds qui en dépendent ne sont pas distribués ; les autres nœuds continuent. S'il n'y a plus de nœuds prêts ou en cours d'exécution, mais qu'il reste des nœuds blocked, arrêtez-vous, signalez la raison du blocage à l'utilisateur et attendez sa décision avant de continuer ; ne passez pas à l'étape 7.

Une fois le nœud done, nettoyez son worktree et sa branche. Si le worktree contient des modifications non validées, arrêtez-vous et vérifiez ; n'utilisez pas --force ou -D :

git -C <wt_noeud> status --porcelain
git -C <wt_int> worktree remove "<wt_noeud>"
git -C <wt_int> branch -d "dag-node/<id-plan>/<id-noeud>"

Les nœuds blocked, en cours de reprise ou dont l'état est incertain conservent leur worktree et leur branche.

7. Révision globale

Une fois tous les nœuds done, distribuez un sous-agent de révision en lecture seule pour examiner les modifications complètes de la branche d'intégration :

Révision en lecture seule de toutes les modifications de <sha_départ>..HEAD dans <wt_int>, ne modifiez aucun fichier, ne distribuez pas d'autres agents. Vérifiez selon les objectifs, critères de validation globaux et non-objectifs suivants : couverture des besoins, cohérence des interfaces et du comportement entre les nœuds, implémentations dupliquées, architecture s'écartant de la conception clé, défauts d'exactitude, code de débogage ou temporaire restant, tests importants manquants ou ne couvrant pas réellement le comportement prétendu. Pour chaque problème, donnez l'emplacement, la preuve et les nœuds concernés ; distinguez les problèmes certains des suppositions ; listez également les points nécessitant une décision de l'utilisateur.

Joignez dans les instructions l'objectif, les critères de validation globaux, les non-objectifs et la conception clé du plan.

L'agent principal vérifie chaque problème et organise la correction selon l'attribution : les problèmes nécessitant une implémentation sont créés comme nœuds de correction (par exemple F1) dans le plan, distribués et intégrés selon les étapes 5–6 ; les petits problèmes locaux et évidents (comme une instruction de débogage restante) peuvent être directement modifiés et validés par l'agent principal dans le worktree d'intégration. Les points nécessitant une décision de l'utilisateur ne sont pas tranchés par l'agent principal ; ils sont écrits dans le rapport.

8. Validation finale et rapport

L'agent principal effectue les vérifications suivantes dans le worktree d'intégration :

1. Examinez le diff complet de <sha_départ>..HEAD pour confirmer qu'il n'y a pas de modifications dépassant l'objectif du plan.
2. Exécutez les commandes de verify de tous les nœuds, ainsi que les tests, la construction et les commandes de lint qui couvrent les modules modifiés dans le projet.
3. Vérifiez un par un les critères de validation globaux.

En cas d'échec d'une vérification : si le problème est dans le périmètre de l'objectif du plan, corrigez-le selon les règles d'attribution de l'étape 7, puis refaites la vérification ; si le problème n'est pas dans le périmètre de l'objectif du plan (par exemple un test déjà échoué au départ), ne le corrigez pas et écrivez-le dans le rapport. Une fois tout terminé, modifiez le "statut du plan" en "terminé".

Le rapport final comprend : les nœuds terminés et leurs validations de fusion correspondantes, les découvertes et traitements de la révision, les résultats de la validation, les éléments non terminés ou à risque, les points nécessitant une décision de l'utilisateur, le chemin et la branche du worktree d'intégration, et les worktrees de nœud conservés. La fusion dans la branche cible et la suppression du worktree d'intégration ne sont effectuées que si l'utilisateur le demande.