Converge - Réintégration des spécifications après QA

Que fait Converge - Réintégration des spécifications après QA ?

Fermez la boucle d'exécution : une tâche qui a passé la QA devient partie intégrante de la spécification vivante. Ce skill représente le rôle ConvergeTool dans le cycle de vie. Il définit le processus ; les règles propres au dépôt pour les agents gèrent toujours les permissions, et ce skill n'accorde jamais d'accès supplémentaire.

Position dans le pipeline : dev -> qa -> converge -> bundle archivé + spécification mise à jour.

À utiliser lorsque

• Le fichier 03-qa-verification.md du bundle de tâche enregistre un verdict QA_PASSED coché.
• 02-dev-workspace.md contient le tableau des écarts d'implémentation figé (lignes ou une ligne None explicite).
• Le comportement confirmé de la tâche doit être intégré dans .specs/02-tech-spec.md, le bundle archivé et la proposition de modification d'origine clôturée.

Ne pas utiliser lorsque

• L'implémentation ou la QA est encore en cours, le marqueur de transfert n'est pas coché, ou REWORK_REQUIRED est actif - attendez un verdict QA_PASSED stable.
• Le journal des écarts est vide ou manquant - renvoyez la tâche à Dev plutôt que de deviner.
• Vous devriez inventer du contenu de spécification ou réécrire du texte de spécification existant ; cela relève d'un changement de planification, pas d'une convergence.

Entrées

• tasks/<task-id>/01-contract.md - titre, ancres de traçabilité, change_id optionnel.
• tasks/<task-id>/02-dev-workspace.md - le tableau des écarts d'implémentation (format figé).
• tasks/<task-id>/03-qa-verification.md - le verdict QA_PASSED coché et les preuves.
• tasks/<task-id>/04-process.md - carte de statut dérivée et journal des événements.
• .specs/02-tech-spec.md - la spécification technique vivante.
• .specs/changes/<change-id>/proposal.md - la proposition de modification d'origine, lorsqu'elle existe.

Sorties

• Une entrée datée et attribuée par tâche dans la section Modifications convergées de la spécification.
• Un marqueur de convergence par tâche : <!-- converged: <task-id> sha256:<hash> -->.
• 04-process.md avec macro_status: "CONVERGED" et une ligne d'événement TASK_CONVERGED (acteur ConvergeTool).
• Le bundle de tâche déplacé (jamais supprimé) vers tasks/archive/<task-id>/.
• .specs/changes/<change-id>/convergence.md plus le statut de proposition archived, lorsque une proposition existe.

Vérifier -> appliquer -> vérifier

1. Vérifier. Classifiez les bundles avant d'écrire quoi que ce soit : python .agents/skills/converge/scripts/converge.py check --tasks-dir ./tasks --json Un bundle est prêt pour la convergence uniquement lorsque la QA est réussie, qu'aucun remaniement n'est actif, que le tableau des écarts comporte au moins une ligne ou une ligne None explicite, et que la spécification ne porte pas déjà son marqueur.
2. Appliquer. Conversez un bundle : python .agents/skills/converge/scripts/converge.py apply --task tasks/<task-id> Utilisez d'abord --dry-run pour inspecter les écritures planifiées. L'assistant refuse avec un code de sortie 1 lorsque le bundle n'est pas prêt pour la convergence, et refuse une destination d'archive existante sauf avec --force.
3. Vérifier. Réexécutez check, confirmez la présence du marqueur, 04-process.md indique CONVERGED, le bundle est archivé, et --spec-sha256 correspond à la valeur CI attendue : python .agents/skills/converge/scripts/converge.py --spec .specs/02-tech-spec.md --spec-sha256

Solution de secours manuelle (sans Python)

Lorsque l'assistant n'est pas disponible, effectuez les mêmes étapes manuellement et conservez les marqueurs exacts :

1. Confirmez que QA_PASSED est coché dans 03 et qu'aucun REWORK_REQUIRED n'est actif.
2. Lisez les lignes d'écart dans 02 ; rejetez un journal vide.
3. Ajoutez (ne modifiez pas) une entrée dans la section Modifications convergées de la spécification : un en-tête ### <task-id>, le tableau des écarts, et le marqueur <!-- converged: <task-id> sha256:<hash> -->. Calculez le hachage avec n'importe quel outil SHA-256 sur l'ID de tâche normalisé et les lignes.
4. Définissez macro_status sur CONVERGED dans 04 et ajoutez la ligne TASK_CONVERGED / ConvergeTool.
5. Déplacez, jamais supprimé, le bundle vers tasks/archive/<task-id>/ ; archivez la proposition et écrivez convergence.md lorsqu'une proposition de modification existe.
6. Réexécutez l'étape de vérification et enregistrez les preuves.

Conditions de refus

Arrêtez-vous et signalez au lieu de converger lorsque l'une de ces conditions est vraie :

• QA non réussie - 03 n'a pas de QA_PASSED coché, ou REWORK_REQUIRED est encore actif.
• Remaniement non résolu - les preuves de nouvelle tentative montrent que la tâche est en cours de remaniement ; attendez un nouveau verdict.
• Journal des écarts vide - le tableau des écarts d'implémentation est manquant ou n'a pas de ligne DEV ni de ligne None explicite.
• Dérive de la spécification - un écart modify/remove pointe vers une ancre #sec-* que la spécification ne contient pas ; la spécification et le journal des écarts sont en désaccord. Exécutez check/apply avec --strict dans la CI pour transformer cet avertissement en refus.
• Collision d'archive - tasks/archive/<task-id>/ existe déjà et --force n'a pas été fourni.

Les écarts structurels (nouveaux modules, limites modifiées, nouvelles décisions de niveau ADR) doivent être remontés à spec-generator ; ils ne sont jamais convergés silencieusement.

Historique et attribution

La convergence ne réécrit jamais l'historique : elle ajoute une section datée et attribuée au lieu de modifier le texte de spécification existant. Les entrées existantes restent stables octet par octet, et chaque entrée nomme la tâche source, le verdict QA et l'acteur ConvergeTool. Ne modifiez jamais une ancienne entrée de convergence pour faire correspondre une nouvelle tâche ; ajoutez une nouvelle entrée et enregistrez le conflit.

Références

• references/convergence-protocol.md - machine à états, qui écrit quoi, disposition de l'archive, marqueurs d'idempotence, règles de conflit et escalade structurelle.
• Limites des rôles : references/role-boundaries.md — périmètre d'écriture, invariants et modèle d'application honnête (intégré ; aucun fichier externe nécessaire).
• Format du bundle de tâche et cycle de vie des rôles : skill task-decomposition (lorsqu'il est installé).
• Entrée de transfert : skill dev ; entrée de verdict : skill qa.
• Règles du dépôt : lisez AGENTS.md et les éventuels fichiers de règles de rôle lorsque le projet adoptant les définit ; ils peuvent ajouter des exigences mais ne sont pas requis pour ce skill.

Limites honnêtes

Ce skill n'accorde pas d'accès en écriture et ne peut pas imposer l'isolation des rôles. Là où le dépôt dispose d'une CI (par exemple un audit de rôle basé sur git) ou d'une protection de branche, c'est la couche faisant autorité. L'assistant intégré est un assistant déterministe optionnel ; les marqueurs et les preuves écrites constituent le contrat.