Fusion OpenSpec

Que fait Fusion OpenSpec ?

Fusionne plusieurs dossiers de capacités liés dans openspec/specs/ en un seul spec de fonctionnalité principal, via un workflow en deux phases (préparation/approbation). Rien sous openspec/specs/<capacité>/ n'est jamais touché tant qu'un humain n'a pas explicitement approuvé la fusion.

Quand l'utiliser

Le workflow d'archivage d'OpenSpec synchronise les deltas dans openspec/specs/<capacité>/spec.md par changement. Lorsque des changements liés sont archivés sous des noms de capacités différents (souvent parce qu'ils ont été construits par étapes, par exemple user-show, user-detail, user-permissions), vous vous retrouvez avec plusieurs dossiers de spec décrivant ce qui est fonctionnellement une seule fonctionnalité. Cette compétence fusionne ceux-ci en un seul, via une zone de préparation qui nécessite une validation humaine avant que quoi que ce soit de réel ne soit remplacé.

Les deux phases

• Phase A — Préparation : lire les specs sources, écrire un brouillon fusionné dans openspec/specs/.merged-specs/<fonctionnalité>/spec.md avec Approved-by-human: no. Rien d'autre ne change.
• Phase B — Application : déclenchée lorsque l'utilisateur a basculé le frontmatter en Approved-by-human: yes. Remplace les dossiers source par le contenu approuvé et supprime le fichier de préparation.

Toujours détecter quelle phase s'applique : si openspec/specs/.merged-specs/<fonctionnalité>/ existe déjà, vérifiez d'abord son champ Approved-by-human au lieu de recommencer la préparation depuis zéro.

Phase A — Préparation

1. Identifier les dossiers candidats

Listez openspec/specs/* et cherchez les dossiers qui :

• Partagent un préfixe de nom commun ou un mot de domaine (user-show, user-detail, user-permissions)
• Référencent la même entité/ressource dans leurs exigences (même modèle, mêmes points d'API, même page UI)
• Ont été archivés proches dans le temps (vérifiez les dates dans openspec/changes/archive/)

Si l'utilisateur a nommé explicitement des dossiers spécifiques, utilisez-les plutôt que de deviner.

Si plus d'un groupement plausible existe, arrêtez-vous et demandez à l'utilisateur quels dossiers appartiennent ensemble avant de préparer quoi que ce soit.

2. Lire chaque spec.md candidat en entier

Pour chaque dossier, lisez l'intégralité du spec.md, pas seulement les en-têtes. Notez les noms d'exigences, les scénarios, les marqueurs de dépréciation, et tout ce qui semble modifier/remplacer une exigence dans un autre dossier candidat.

3. Déduire le nom de la capacité cible

Dérivez-le du préfixe commun ou du nom de domaine partagé parmi les dossiers candidats (par exemple user-show + user-detail + user-permissions → user, ou user-management si cela semble plus naturel).

• Préfixe/domaine commun clair → l'utiliser, pas besoin de demander.
• Pas de nom partagé évident (par exemple checkout-flow et invoice-export liés uniquement par un thème vague de "facturation") → demander à l'utilisateur de nommer la capacité cible avant de continuer.

Indiquez le nom déduit explicitement dans votre sortie afin que l'utilisateur puisse le remplacer.

4. Fusionner les exigences

Règles, dans l'ordre :

• Union des exigences AJOUTÉES : chaque exigence distincte de chaque dossier source est conservée.
• Exigences conflictuelles/dupliquées (même nom, ou même comportement décrit deux fois) : conserver la version la plus complète/récente, en fusionnant les détails non conflictuels plutôt que d'en supprimer un silencieusement.
• Exigences SUPPRIMÉES/dépréciées : exclure du spec fusionné.
• Ne jamais inventer d'exigences. Signaler les ambiguïtés ou contradictions en ligne (par exemple <!-- CONFLIT : la source A dit X, la source B dit Y — nécessite une décision humaine -->) plutôt que de choisir silencieusement.
• Conserver le texte du scénario original lorsque c'est possible ; ne réécrire la prose que lors de la fusion de deux exigences qui se chevauchent.

5. Écrire le fichier de préparation

Écrire dans :

openspec/specs/.merged-specs/<nom-déduit>/spec.md

Avec ce frontmatter en haut :

---
Approved-by-human: no
merged-from:
  - user-show
  - user-detail
  - user-permissions
---

Suivi du contenu fusionné du spec.

6. Informer l'utilisateur, brièvement

• Quels dossiers source ont été fusionnés, et le nom cible déduit
• Tous les conflits signalés en ligne nécessitant une décision
• Exactement quoi faire ensuite : ouvrir openspec/specs/.merged-specs/<nom-déduit>/spec.md, le réviser, modifier si nécessaire, et définir Approved-by-human: yes dans le frontmatter une fois satisfait
• Que rien sous openspec/specs/<capacité>/ n'a encore été touché

Phase B — Application

Déclencheur : l'utilisateur demande d'appliquer/finaliser une fusion, ou vous remarquez que openspec/specs/.merged-specs/<fonctionnalité>/spec.md a Approved-by-human: yes.

1. Relire le fichier de préparation et confirmer Approved-by-human: yes. S'il est toujours no, arrêtez-vous et dites à l'utilisateur qu'il a d'abord besoin d'approbation — n'appliquez pas.
2. Lire merged-from depuis le frontmatter pour savoir quels dossiers source remplacer.
3. Supprimer le frontmatter du contenu préparé (les deux champs), laissant un spec.md propre sans frontmatter.
4. Remplacer les dossiers source par le résultat fusionné :
   • Créer/écraser openspec/specs/<nom-déduit>/spec.md avec le contenu sans frontmatter.
   • Supprimer les autres dossiers source listés dans merged-from qui ne sont pas le nom cible lui-même.
5. Supprimer le dossier de préparation openspec/specs/.merged-specs/<nom-déduit>/.
6. Confirmer à l'utilisateur ce qui a été remplacé/supprimé, pour faciliter la vérification par rapport à git diff avant de commiter.

N'effectuez jamais l'étape 4 sans un Approved-by-human: yes explicite déjà présent dans le fichier — ne demandez pas à l'utilisateur d'approuver verbalement dans le chat comme substitut ; l'approbation doit être le champ frontmatter lui-même.

Exemple

Phase A — Entrée : openspec/specs/user-show/, openspec/specs/user-detail/, openspec/specs/user-permissions/ — décrivant tous différents aspects de la même fonctionnalité de profil utilisateur.

Sortie : openspec/specs/.merged-specs/user/spec.md :

---
Approved-by-human: no
merged-from:
  - user-show
  - user-detail
  - user-permissions
---

# User

## Exigence : ...
...

Message à l'utilisateur : fusionné depuis user-show, user-detail, user-permissions vers la capacité déduite user (renommez le dossier si vous préférez user-management) ; aucun conflit trouvé ; révisez openspec/specs/.merged-specs/user/spec.md et définissez Approved-by-human: yes quand vous êtes prêt.

Phase B — Une fois que l'utilisateur définit Approved-by-human: yes et demande d'appliquer : openspec/specs/user/spec.md est créé/écrasé avec le contenu fusionné sans frontmatter, user-show/, user-detail/, user-permissions/ sont supprimés, et openspec/specs/.merged-specs/user/ est supprimé.