--- title: Workflow — Risques & vigilance : Story tracking domain: workflow bucket: risques tags: [bmad, story, file-list, review, completion] applies_to: [analysis, implementation, review] severity: high validated_on: 2026-04-07 source_projects: [app-alexandrie, app-template-resto, RL799_V2] --- # Workflow — Risques & vigilance : Story tracking > Extrait de la base de connaissance Lead_tech. Voir `knowledge/workflow/risques/README.md` pour l'index complet. --- ## Story "completed" avec tâches ❌ auto-déclarées ### Risques - Un agent sette `Status: completed` alors que son propre Dev Agent Record liste des items ❌ non implémentés - Le store mobile, service ou tests peuvent être déclarés manquants par l'agent lui-même mais la story semble terminée ### Symptômes - Dev Agent Record contient `❌ store mobile non implémenté` mais `Status: completed` - Code review découvre des ACs non satisfaits ### Bonnes pratiques / mitigations - Avant de setter `Status: completed`, vérifier que le Dev Agent Record ne contient aucun ❌ - En cas de doute ou d'item manquant, setter `Status: review` pour déclencher la code review - **Règle** : `Status: completed` = zéro ❌ auto-déclaré dans le Dev Agent Record - Contexte technique : BMAD / workflow agent — app-alexandrie 20-03-2026 --- ## Story "done" sans aucun fichier source dans la File List ### Risques - Un agent peut halluciner la completion d'une story en produisant une note générique sans écrire de code - La File List ne contient que des fichiers `_bmad-output/` mais aucun `src/`, `prisma/`, `tests/` ### Symptômes - Completion note générique du type "Ultimate context engine analysis completed" - File List réduite à 2 fichiers meta (story file, sprint-status) - `git log --follow src/` ne montre aucun commit lié à la story ### Bonnes pratiques / mitigations - Lors d'une code review, si la File List ne contient aucun fichier source : traiter comme non implémentée - Vérifier avec `git log --follow src/` avant d'accepter le `Status: done` - Ne pas faire confiance au status `done` sans preuve dans le code - Contexte technique : BMAD / agent Codex — app-template-resto 21-03-2026 --- ## Story validée avec changements hors périmètre non documentés ### Risques - Le reviewer valide un faux scope ou rejette à tort une story correcte. - Des changements source non tracés (working tree dirty) peuvent masquer une implémentation partielle ou des effets de bord. ### Symptômes - Tâches `[x]` et File List propre, mais `git status` montre des fichiers modifiés hors story - Aucun bloc "hors périmètre" dans le Dev Agent Record alors que des fichiers non liés ont été touchés ### Bonnes pratiques / mitigations - Si des changements hors story sont présents dans le working tree, documenter un bloc **"hors périmètre"** explicite dans le Dev Agent Record (liste courte + justification). - Ne marquer `done` qu'après clarification de périmètre. - **Règle** : le reviewer croise systématiquement `git diff --name-only` avec la File List avant d'accepter. - Contexte technique : BMAD / workflow agent — 30-03-2026 --- ## File List approximative — chemins faux ou fichiers source absents ### Risques - Validation d'une implémentation avec traçabilité mensongère. - Chemins fictifs dans la File List non détectés si le reviewer ne croise pas avec `git`. ### Symptômes - File List courte ou générique alors que le diff réel touche de nombreux fichiers source - Fichier listé avec un chemin qui n'existe pas dans le repo ### Bonnes pratiques / mitigations - **Règle review** : comparer la File List du Dev Agent Record au `git diff --name-only` réel. - Tout fichier source modifié absent de la File List → signaler en **MEDIUM**. - Tout fichier listé avec un chemin inexistant en git → signaler en **HIGH**. - Contexte technique : BMAD / workflow agent — app-template-resto 31-03-2026 --- ## Story "review" non alignée avec la réalité du diff ### Risques - La File List, les Completion Notes et les tâches `[x]` ne reflètent pas la réalité de `git diff` / `git status` - Des régressions de tests passent inaperçues si le statut `review` est accordé sans croisement avec le diff - Des fichiers créés dans un commit antérieur (ex: commit de refonte UI) sont listés dans la story sans traçabilité explicite ### Symptômes - `git diff --name-only` montre des fichiers absents de la File List (ou inversement) - Completion Notes contenant des déclarations contredites par le diff réel - Tâches `[x]` "tests impactés passent" alors que des tests cassent sur des fichiers modifiés dans la story - Fichiers listés dans la File List absents de `git diff HEAD~1..HEAD` pour le commit story ### Bonnes pratiques / mitigations - **Avant passage en review** : comparer `File List` vs `git diff --name-only` + `git status --porcelain` - Refuser le statut `review` si un fichier source de la story manque de la File List - Exiger une section "preuves de validation" quand une tâche mentionne une validation UX/Dev - Exiger un run de tests sur le périmètre touché, avec mention explicite des échecs non liés - Si des fichiers sont répartis sur plusieurs commits, mentionner explicitement dans la File List le commit d'introduction de chaque fichier - Contexte technique : BMAD / workflow agent — RL799_V2 02-04-2026 --- ## Quality gate déclaratif non exécutable ### Risques - Une story impose un gate process (PR template, checklist obligatoire) mais aucun mécanisme de contrôle vérifiable n'existe - En review, cela crée un faux sentiment de contrôle et laisse passer des PR non conformes ### Symptômes - Story qui déclare un quality gate via documentation/template sans CI check, script de validation, ni evidence review tracée - AC marqués ✅ sur la base d'un template rempli mais sans preuve d'exécution ### Bonnes pratiques / mitigations - La review doit vérifier au moins un mécanisme de contrôle actionnable (CI check, script de validation, required field policy, ou evidence review tracée) - Sans ce mécanisme, classer les AC comme PARTIAL et repasser la story en `in-progress` - Contexte technique : BMAD / workflow agent — RL799_V2 02-04-2026 --- ## AC dépendante d'une capacité non supportée par le contrat technique ### Risques - Un AC demande un comportement impossible avec le contrat courant (ex: multi-rôles alors que le JWT expose un rôle scalaire) - Sans clarification explicite dans la story, la review crée des allers-retours et des faux écarts ### Symptômes - AC mentionnant une capacité que le token, le schéma ou l'API ne supporte pas actuellement - Dev qui implémente un workaround non documenté pour satisfaire l'AC ### Bonnes pratiques / mitigations - Si un AC dépend d'une capacité non supportée par le contrat actuel (token, schéma, API), documenter explicitement la contrainte dans la story - Marquer la capacité hors-scope tant que le contrat n'est pas migré - Exiger une note Dev Notes + alignement Tasks/Tests sur cette contrainte - Contexte technique : BMAD / workflow agent — RL799_V2 02-04-2026 --- ## Tâches [x] validées par tests textuels au lieu de tests comportementaux ### Risques - Une story passe en review avec des tâches `[x]` dont la preuve repose uniquement sur des assertions textuelles (`content.includes(...)`) sans exécuter le flux réel - Les tests de présence textuelle valident des labels mais pas les cibles de navigation, ni les transitions d'état ### Symptômes - Tests qui passent en vérifiant uniquement la présence de chaînes dans les fichiers source - AC fonctionnels non réellement garantis (toast, mise à jour réactive, soumission) malgré un statut story en `review` - Tests `content.includes(...)` valident des labels mais pas les `to`/`href` de navigation ### Bonnes pratiques / mitigations - Toute tâche de test marquée `[x]` doit inclure au moins un test comportemental exécutable (pas seulement `content.includes(...)`) - En cas de tests purement textuels, classer la tâche comme non validée et repasser la story en `in-progress` - Pour toute AC mentionnant "clic" ou "navigation", imposer une vérification des cibles (`:to`, `href`, route name) - **Règle** : un test qui ne vérifie que des helpers adjacents ou des chaînes statiques ne peut pas clôturer une tâche d'intégration - Contexte technique : BMAD / workflow agent — RL799_V2 02-04-2026 --- ## Agents autonomes et dérive des contrats partagés ### Risques - Après une session multi-agents, les types/DTOs sont redéfinis localement dans chaque service au lieu d'utiliser le package shared - La dérive est détectée uniquement lors d'une review globale de cohérence, pas pendant l'implémentation ### Symptômes - Types définis localement dans `apps/frontend/src/services/` au lieu d'être importés depuis `packages/shared` - Plusieurs services avec le même type défini indépendamment, avec des divergences subtiles - Détection : `grep -r 'type.*=' apps/frontend/src/services/ | grep -v 'import'` ### Bonnes pratiques / mitigations - Inclure dans le prompt d'agent une instruction explicite : "créer les DTOs dans `packages/shared` AVANT d'écrire le service frontend" - Ajouter une review globale de cohérence après toute session multi-stories - **Règle review** : tout type défini localement qui correspond à un DTO existant dans shared est une régression - Contexte technique : BMAD / agents autonomes — RL799_V2 07-04-2026 --- ## Incohérence entre Completion Notes et réalité du code ### Risques - Les dev agents documentent des métriques dans les Completion Notes (nombre de tests, nombre de routes) sans les vérifier en fin d'implémentation - Le reviewer passe du temps à réconcilier des chiffres qui ne matchent pas ### Symptômes - "20 tests RBAC" revendiqués dans les Completion Notes alors que le fichier test n'en contient que 11 - Route `DELETE /api/favorites` listée dans le rapport d'audit mais inexistante dans le code ### Bonnes pratiques / mitigations - Avant de passer une story en `review`, le dev agent doit vérifier que les chiffres dans les Completion Notes correspondent exactement au code - `grep -c 'test(' fichier.test.ts` pour le nombre de tests - `grep -c 'export' fichier.routes.ts` pour le nombre de routes - **Règle** : toute métrique dans les Completion Notes doit être vérifiable par une commande simple - Contexte technique : BMAD / workflow agent — RL799_V2 08-04-2026 --- ## Story impose une convention absente du code projet ### Risques - Divergence silencieuse entre specification story et implémentation réelle. ### Symptômes - Le dev adapte une convention introuvable sans la tracer dans la story/notes de review. ### Bonnes pratiques / mitigations - Si une convention prescrite n'existe pas dans le repo, documenter explicitement l'adaptation retenue. - Mettre à jour la story (Change Log / Completion Notes) avec justification et impact. - Contexte technique : BMAD / traçabilité adaptation story — RL799_V2 15-04-2026 ---