PD-294 — Retour d'expérience¶
1. Résumé¶
Story : Aligner le format Merkle proof sur RFC 9162 (inclusion proof) Projet : ProbatioVault-backend Durée workflow : ~3h (étapes 0-8) Verdict final : Gate 8 RESERVE (8.25/10)
2. Gates¶
| Gate | Verdict | Score | Itérations | Points clés |
|---|---|---|---|---|
| G3 | GO | 8.75 | 3 (v1 NC, v2 NC, v3 GO) | Algo RFC incomplet v1, spec/tests désynchronisés v2, résolu v3 |
| G5 | RESERVE | 7.375 | 1 | Endpoint verify optionnel, coverage INV-294-06 |
| G8 | RESERVE | 8.25 | 1 | test_coverage 7.5 (STUB controller tracé PD-56) |
3. Learnings¶
L1 — Corriger spec ET tests simultanément en boucle de correction¶
Contexte : Gate 3 a consommé 3 itérations au lieu de 2 parce que la v2 n'a corrigé que la spec sans resynchroniser les tests. Impact : +1 itération, +327s de temps LLM, risque de plateau delta < 0.5. Recommandation : Quand le prompt de correction liste des écarts entre spec et tests, produire les deux documents corrigés dans le même appel LLM.
L2 — Architecture extension non-intrusive pour refactors de format¶
Contexte : Le module merkle/v2/ est créé en sous-module sans toucher au code existant (MerkleProofService de PD-56 reste intact). Impact : Zéro régression sur le code existant, merge sans conflit. Recommandation : Privilégier ce pattern pour les stories de normalisation/format.
L3 — Story de contrat vs story d'implémentation¶
Contexte : PD-294 est une story de contrat (format, règles, migration). Le controller est un STUB tracé (PD-56). La coverage globale < 80% est attendue et acceptable si les composants logiques sont couverts >= 85%. Impact : Gate 8 RESERVE au lieu de GO à cause de test_coverage 7.5. Recommandation : Pour les stories de contrat, documenter explicitement le STUB et sa story destination dans les prérequis d'acceptabilité. Le reviewer ne doit pas pénaliser un STUB tracé.
L4 — Prompt assemblé injecte la review v2 alors que la v3 est déjà corrigée¶
Contexte : Le subprocess claude -p pour step 6a a reçu le fichier PD-294-specification-review.md (review v2 avec 3 bloquants) et a refusé de produire la décomposition, pensant que la Gate 3 n'était pas passée. Impact : Décomposition manuelle requise à la place du subprocess. Recommandation : Le script assemble-prompt.sh devrait injecter le verdict final (YAML) plutôt que la review intermédiaire, ou ne pas injecter de review quand le verdict est GO.
L5 — Inner while-loop RFC 9162 §2.1.3.2 — placement critique¶
Contexte : L'algorithme de vérification RFC 9162 a une inner while-loop qui doit être UNIQUEMENT dans la branche (LSB(fn)==1 OU fn==sn). Mal placée, elle rejette des preuves valides pour tout fn pair strict. Impact : 2 itérations de Gate 3 pour converger sur le bon placement. Recommandation : Pour tout alignement RFC crypto, produire un test de non-régression avec un vecteur fn pair strict dès la spec (ex: leaf_index=2 dans un arbre de 4 feuilles).
4. Métriques¶
| Métrique | Valeur |
|---|---|
| Fichiers créés | 11 |
| Lignes ajoutées | 726 |
| Tests | 22/22 pass |
| Itérations Gate 3 | 3 |
| Itérations Gate 5 | 1 |
| Itérations Gate 8 | 1 |
| Appels LLM (Codex) | ~8 (spec, tests, correction v2, correction v3, review G5, 3 reviews accept) |
| Appels LLM (Claude -p) | ~4 (review G3 v1, review G3 v2, plan, décomposition) |
5. Recommandations process¶
- Script assemble-prompt.sh : ajouter un flag
--skip-review-if-gopour éviter l'injection de reviews intermédiaires quand le verdict final est GO - Correction boucle Gate : le prompt de correction doit explicitement demander de corriger TOUS les documents listés dans les écarts (pas juste la spec)
- Template vecteur test RFC crypto : ajouter un champ "vecteur de non-régression obligatoire" dans le template spec pour les stories crypto/RFC