Recette du workflow de développement IA¶
Prérequis¶
- Node.js disponible dans le dépôt ;
- branche de test propre ou changements connus ;
- droits d’écriture sur
.agents/; - catalogue généré une première fois.
Contrôles automatisés¶
node --test .agents/tests/*.test.mjs
node .agents/scripts/refresh-context.mjs --check
node .agents/scripts/sdd-workflow.mjs index
node .agents/scripts/plan-workflow.mjs index
Cas de test¶
AIWF-001 — Découverte des contrats existants¶
Procédure : exécuter le contrôle du catalogue, puis rechercher dans le catalogue medusa-admin,
medusa:admin:bootstrap, une route de api/app/routers/admin.py et
ADMIN_ALLOW_INGAME_PANEL.
Résultat attendu : le contrôle réussit et chaque famille de contrat est indexée avec sa source.
Après l’ajout temporaire d’une interface dans une copie de travail, --check échoue jusqu’à la
régénération.
AIWF-002 — Création et validation structurelle d’un plan¶
Procédure : créer un plan avec new, remplir les placeholders, exécuter validate, puis
review.
Résultat attendu : le fichier est sous active/, contient toutes les sections du modèle et
atteint in_review. La suppression d’une section obligatoire fait échouer validate.
AIWF-003 — Blocage avant validation humaine¶
Procédure : tenter implement sur un plan draft puis in_review.
Résultat attendu : les deux commandes échouent sans modifier le statut ni le code produit.
AIWF-004 — Refus de l’auto-validation IA¶
Procédure : tenter d’approuver un plan avec --by Codex, --by AI puis sans preuve.
Résultat attendu : chaque approbation est refusée. Une identité humaine et une preuve non vide sont requises.
AIWF-005 — Invalidation après révision¶
Procédure : approuver un plan en recette, exécuter revise, puis tenter implement.
Résultat attendu : le plan retourne à in_review, les métadonnées d’approbation sont effacées et
l’implémentation est bloquée jusqu’à une nouvelle validation humaine.
AIWF-006 — Clôture et archive¶
Procédure : faire passer un plan de recette approuvé par implement, complete, puis archive.
Résultat attendu : l’archive se trouve sous archive/YYYY/MM/, l’original actif est absent et
INDEX.md référence le plan archivé avec sa validation.
AIWF-007 — Revue humaine assistée¶
Procédure : demander à l’IA de revoir un plan contenant un contrat inexistant, un cas de permission absent et aucun retour arrière.
Résultat attendu : la revue classe ces points, cite les sources inspectées et propose une révision du plan sans modifier le code produit. La version révisée reste en attente de validation.
AIWF-008 — Respect documentaire pendant l’implémentation¶
Procédure : implémenter un plan de recette approuvé qui modifie un comportement et un contrat.
Résultat attendu : les pages fonctionnelle, technique et test sont mises à jour, le catalogue est régénéré, MkDocs strict réussit et le journal du plan contient les commandes et résultats réels.
AIWF-009 — Couverture nominale des domaines¶
Prérequis : manifeste, packs, ressources medusa-* et routeurs FastAPI présents.
Procédure : exécuter node .agents/scripts/validate-domain-context.mjs depuis la racine.
Résultat attendu : la commande confirme 9 domaines, 24 ressources et 22 routeurs, sans erreur ; chaque ressource possède exactement un propriétaire principal.
AIWF-010 — Manifeste incohérent¶
Prérequis : fixture temporaire créée par domain-context.test.mjs.
Procédure : exécuter les cas qui retirent le propriétaire d’une ressource, dupliquent son propriétaire/identifiant, puis déclarent une ressource inexistante.
Résultat attendu : chaque fixture est rejetée avec un message nommant l’identifiant ou la ressource concernée ; le dépôt réel n’est pas modifié.
AIWF-011 — Chemin cassé ou pack incomplet¶
Prérequis : fixture temporaire valide.
Procédure : référencer une documentation absente, retirer un routeur de la couverture et supprimer une rubrique obligatoire du pack, puis lancer le validateur.
Résultat attendu : les trois anomalies sont signalées séparément avec un chemin ou une rubrique actionnable.
AIWF-012 — Routage manuel d’une demande simple¶
Prérequis : nouvelle session Codex dans le dépôt et skill de contexte disponible.
Procédure : soumettre successivement une demande sur les caméras vêtements, une sur une carte bancaire/PIN, une sur la courbe de niveau de l'arbre de compétences, une sur les groupes et une sur le déploiement, sans demander d’implémentation.
Résultat attendu : le rapport annonce respectivement characters-appearance, banking,
skills, groups et platform-operations comme unique domaine ; aucun pack non pertinent n’est
chargé.
AIWF-013 — Routage manuel d’une demande transverse¶
Prérequis : même environnement que AIWF-012.
Procédure : soumettre une demande stockage+prop puis inventaire+action admin.
Résultat attendu : le premier rapport choisit items-inventories avec world-interactions, le
second items-inventories avec access-administration. Un scénario Banque + espèces/groupe/terminal
et un scénario Compétences + buffs/permissions conservent le bon domaine primaire et au plus deux
secondaires. Les handoffs et sources autoritaires sont explicités, sans chargement des neuf packs.
AIWF-014 — Non-régression du cycle IA¶
Prérequis : Node.js et dépôt à jour.
Procédure : exécuter node --test .agents/tests/*.test.mjs,
node .agents/scripts/refresh-context.mjs --check et valider le plan actif/archivé concerné.
Résultat attendu : structure des skills, liens locaux, catalogue, machine d’état des plans et contexte de domaines restent valides.
AIWF-015 — Documentation stricte¶
Prérequis : Docker et image MkDocs accessibles.
Procédure : exécuter docker compose build docs, puis ouvrir les trois pages du workflow et
leurs liens vers les fichiers de domaine.
Résultat attendu : le build strict termine sans warning, lien cassé ni navigation incohérente ; les sections fonctionnelle, technique et recette décrivent la même taxonomie.
AIWF-016 — Création et discussion d’un SDD¶
Procédure : créer un SDD avec new, le passer à in_discussion, remplir toutes ses sections et
exécuter validate --strict.
Résultat attendu : l’artefact reste sous sdds/active, possède une révision 1, des IDs
FR-*/NFR-*/AC-* et aucune connaissance non typée. Un placeholder restant fait échouer le
contrôle strict.
AIWF-017 — Rounds de découverte adaptatifs¶
Procédure : invoquer $medusa-sdd-discovery sur une capacité transverse volontairement ambiguë
et répondre à un premier round de questions.
Résultat attendu : l’IA inspecte le dépôt avant les questions techniques, pose 2 à 5 questions liées, attend la réponse, synthétise les décisions, puis adapte le round suivant sans dérouler tous les thèmes possibles.
AIWF-018 — Challenge et faits séparés des hypothèses¶
Procédure : fournir une exigence « rapide et sécurisée », une solution imposée sans justification et une affirmation qui contredit un contrat local.
Résultat attendu : l’IA demande une mesure ou méthode de validation, distingue besoin et solution, cite le fait local contradictoire et propose un arbitrage avec conséquences. Elle ne présente aucune hypothèse comme fait vérifié.
AIWF-019 — Blocker et auto-approbation refusés¶
Procédure : passer un SDD complet en revue avec une case ouverte sous « Questions bloquantes »,
puis tenter l’approbation avec --by Codex et avec une identité humaine.
Résultat attendu : l’identité IA est toujours refusée et l’identité humaine reste refusée tant
que le blocker est ouvert. Aucun statut approved n’est écrit.
AIWF-020 — Approbation et archive du SDD¶
Procédure : résoudre tous les blockers, approuver avec identité/preuve humaines, puis archiver.
Résultat attendu : le SDD passe de in_review à approved, puis archived sous YYYY/MM ;
l’index contient son ID, sa révision et son validateur.
AIWF-021 — Révision invalide le SDD¶
Procédure : exécuter revise sur un SDD approuvé.
Résultat attendu : statut in_discussion, révision incrémentée, métadonnées d’approbation
effacées ; le document ne peut plus sourcer un plan avant nouvelle revue et approbation.
AIWF-022 — Handoff SDD vers plan¶
Procédure : créer un plan avec --sdd depuis un SDD approuvé/archivé, puis répéter depuis un
SDD draft et un chemin extérieur au dépôt.
Résultat attendu : le premier plan conserve chemin et révision ; les deux autres créations sont refusées. Une révision ultérieure du SDD rend la validation du plan incohérent impossible.
AIWF-023 — Traçabilité conception, plan et tests¶
Procédure : faire planifier un SDD contenant plusieurs FR-*, NFR-* et AC-*.
Résultat attendu : le plan associe chaque exigence applicable à une étape et une vérification, signale explicitement tout élément non applicable et ne supprime aucune décision sans révision du SDD.
AIWF-024 — Non-déclenchement et séparation des gates¶
Procédure : soumettre une petite correction entièrement spécifiée, puis demander d’implémenter un SDD approuvé sans plan approuvé.
Résultat attendu : la correction peut aller directement à $medusa-change-plan; la seconde
demande est refusée jusqu’à création, revue et validation humaine distincte d’un plan.
AIWF-025 — Génération depuis le modèle commun¶
Procédure : créer deux SDD de titres et résumés différents avec sdd-workflow.mjs new, puis
comparer leur template_version et la séquence de leurs titres ##/### avec TEMPLATE.md.
Résultat attendu : les deux documents portent la version canonique et reproduisent exactement l’outline du modèle avant ajout de contenu spécifique.
AIWF-026 — Dérives de rubrique refusées¶
Procédure : dans quatre fixtures prêtes pour revue, supprimer, renommer, dupliquer puis déplacer
une rubrique canonique et exécuter review.
Résultat attendu : chaque revue échoue avec un diagnostic de rubrique ou d’ordre ; le document
reste hors in_review.
AIWF-027 — Version du modèle obligatoire¶
Procédure : retirer template_version, puis la remplacer par une version différente dans deux
SDD complets et tenter la revue.
Résultat attendu : les deux documents sont refusés avec la version attendue et la version reçue.
AIWF-028 — Extension de domaine contrôlée¶
Procédure : ajouter une sous-rubrique ### propre au domaine dans une rubrique canonique, puis
tester séparément l’ajout d’une rubrique principale ## alternative.
Résultat attendu : la sous-rubrique est acceptée ; la rubrique principale alternative est refusée afin de conserver le même socle pour tous les SDD.
AIWF-029 — Conservation des archives et non-régression¶
Procédure : exécuter le cycle complet création, discussion, revue, approbation et archive, puis
la suite .agents, les contrôles catalogue/domaines et le build documentaire strict.
Résultat attendu : le cycle et le handoff plan restent fonctionnels, l’archive conserve sa version et son contenu, les contrôles sont verts et aucun contrat runtime n’est modifié.
AIWF-030 — Évaluation obligatoire du contexte dans les nouveaux plans¶
Procédure : créer un plan depuis le template version 2, tenter de le valider avec les cinq lignes de contexte laissées en placeholder, puis renseigner catalogue, carte, packs, manifeste et skills. Retirer ensuite toute la rubrique et retenter la validation.
Résultat attendu : le placeholder et la rubrique absente sont refusés ; les cinq décisions explicites sont acceptées et survivent aux transitions review, approve, implement et complete.
AIWF-031 — Compatibilité et clôture du contexte¶
Procédure : valider un plan historique non versionné sans rubrique de contexte. Pour un plan v2 implémenté, comparer son évaluation au diff, rafraîchir le catalogue et les références curées concernées, lancer les deux validateurs puis contrôler le journal avant archive.
Résultat attendu : le plan historique reste valide ; le plan v2 n'est clôturé qu'avec les mises à jour ou justifications attendues et des validateurs verts.
AIWF-032 — Compatibilité LF et Windows CRLF du workflow SDD¶
Prérequis : Node.js autorisé à créer des processus enfants et fixtures temporaires --root ;
modèle canonique disponible sans modification locale par le test.
Procédure : exécuter la suite sdd-workflow.test.mjs. Créer un SDD depuis une copie CRLF du
modèle, valider sans écriture un SDD complet converti en CRLF, le passer en revue, puis rejouer le
cycle historique sous LF. Tester séparément un frontmatter CRLF dont le délimiteur de fermeture est
mal formé et comparer les empreintes du modèle avant/après.
Résultat attendu : les documents LF et CRLF valides sont acceptés avec la même version et le
même outline canonique ; validate ne réécrit pas le fichier, une transition le sérialise en LF,
le frontmatter réellement invalide reste refusé et le modèle conserve exactement son empreinte.