---
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-06-25
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.

---

<a id="risque-story-completed-taches-echec"></a>
## 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

---

<a id="risque-story-done-file-list-vide"></a>
## 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

---

<a id="risque-file-list-hors-perimetre"></a>
## 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

---

<a id="risque-file-list-approximative"></a>
## 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

---

<a id="risque-story-review-non-alignee-git"></a>
## 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

---

<a id="risque-quality-gate-declaratif"></a>
## 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

---

<a id="risque-ac-hors-contrat-technique"></a>
## 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

---

<a id="risque-validation-taches-tests-textuels"></a>
## 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

---

<a id="risque-agents-autonomes-derive-contrats"></a>
## 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

---

<a id="risque-completion-notes-incoherentes"></a>
## 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

---

<a id="risque-story-convention-absente-code-projet"></a>
## 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

---

<a id="risque-strategie-fix-suite-e2e-en-masse"></a>
## Stratégie de fix d'une suite E2E qui rote en masse (post-refactor)

### Risques

- Quand un projet enchaîne plusieurs refactors UI/lifecycle sans run E2E entre chaque, on découvre souvent N fails (10-20) d'un coup
- Tentation de fixer fail-by-fail dans l'ordre où ils apparaissent — erreur : on se disperse sur N causes-racines mélangées et chaque commit n'est pas reviewable
- Sans capitalisation immédiate des patterns, on perd le bénéfice de la session pour les futurs refactors

### Symptômes

- 13 fails d'un coup après une période de refactor intense
- Tentative de fix fail-par-fail qui produit un commit géant difficile à reviewer
- Capitalisation reportée → patterns oubliés à la session suivante

### Bonnes pratiques / mitigations

**Process recommandé** :

1. **Run complet en mode list** d'abord : `playwright test --reporter=list`. On veut **la liste exhaustive** des fails, pas un comptage one-shot par fichier (qui peut masquer des fails qui apparaissent uniquement quand on lance la suite entière à cause d'effets de bord seed).

2. **Catégoriser par cause-racine** plutôt que par fichier (cf. `knowledge/frontend/risques/tests.md` — Tests E2E qui rotent — 6 causes-racines récurrentes) :
   - testid changé sans MAJ tests
   - label métier changé (lifecycle, statut)
   - menu/dropdown conditionnel
   - feature supprimée (query param, route)
   - refactor visuel (texte → icône)
   - cleanup post-test à rendre best-effort

3. **1 commit = 1 cause-racine**. Pas "fix 19 fails" en un commit géant. Permet :
   - Review plus simple (chaque commit a un thème clair)
   - Revert chirurgical si une cause-racine s'avère mal diagnostiquée
   - Capitalisation : chaque commit message documente le pattern

4. **Validation entre commits** : run la suite complète après chaque commit pour savoir avant le push que le commit n'a pas régressé d'autres tests.

5. **Capitaliser les patterns à > 2 occurrences** : si on voit le même type de fail 3 fois sur 3 fichiers différents, c'est un pattern. Le poser dans `knowledge/frontend/risques/tests.md` immédiatement, pas plus tard.

**Anti-pattern à éviter** : "je fixe les 5 fails P1 d'abord, je verrai les P2 après". Si la cause-racine est la même (ex : labels lifecycle v3), on perd 30 min à re-comprendre quand on retourne sur les P2 plus tard. Mieux : grouper par cause-racine, pas par priorité.

**Métrique de référence** : 19 fails fixés en 4 commits / ~3 h dont 1 h de capitalisation. Effort par fail : ~6 min de fix + 4 min de validation.

- Contexte technique : Playwright / refactor UI — RL799_V2 25-04-2026

---

<a id="risque-statut-bmad-correct-narratif-obsolete"></a>
## Statut BMAD correct mais sections narratives obsolètes

### Risques

- Une story peut afficher `Status: done` ou `review` tout en conservant des sections narratives (`Story Completion Status`, `Completion Notes`) qui contredisent le statut courant
- Le reviewer lit alors un fichier BMAD incohérent : seul le champ `Status` a été mis à jour, pas le récit qui résume l'état réel de la story
- Risque d'accepter une story dont les notes décrivent un état antérieur (génération de contexte) plutôt que l'implémentation finale

### Symptômes

- `Status: done` mais `Story Completion Status` mentionne encore `ready-for-dev`
- `Completion Notes` décrivant une simple génération de contexte au lieu de l'implémentation réalisée
- Contradiction entre `Status`, `Senior Developer Review` et `Change Log`

### Bonnes pratiques / mitigations

- En code review, recroiser systématiquement `Status`, `Story Completion Status`, `Completion Notes`, `Senior Developer Review` et `Change Log` : ces cinq sources doivent raconter le même état
- **Règle** : toute transition BMAD (`ready-for-dev` → `in-progress` → `review` → `done`) doit mettre à jour aussi les sections narratives qui résument l'état de la story, pas seulement le champ `Status`
- Traiter une divergence narrative comme un signal de doute sur la complétion réelle, pas comme un simple oubli cosmétique

- Contexte technique : BMAD / workflow agent — app-alexandrie 01-04-2026
