PD-103 — Retour d'expérience (REX)¶

1. Résumé exécutif¶

2. Métriques de convergence¶

2.1 Temps et itérations¶

2.2 Scores de convergence par gate¶

2.3 Écarts par catégorie¶

3. Points fluides¶

Ce qui a bien fonctionné :

• Injection learnings proactive : 4 learnings injectés (PD-101 upload iOS, PD-248 screenshot, PD-251 PENDING_SIGNATURE guard, PD-79 B2C mineurs) ont permis de contractualiser la garde SEALED dès le besoin v1.
• Spec v3 exhaustive : 39 invariants, machine à états à 8 états avec transitions exhaustives autorisées/interdites, payload canonique d'idempotence normé — qualité de spécification élevée.
• Implémentation multi-agents en 4 waves : 16 agents, 0 erreur TypeScript post-génération, architecture modulaire propre (M1-M15 bien découplés).
• Convergence Gate 3→Gate 8 décroissante : delta d'amélioration 2.25 → 0.625 → 0.375, montrant que chaque gate corrige de moins en moins (convergence saine).
• Sonar QG OK d'emblée : coverage 80.2% sans retouche, pas de blocage phase 1.5.

4. Points difficiles¶

Obstacles rencontrés (sans justification) :

• Gate 3 NON_CONFORME en v1 (5.75/10) : 3 BLOQUANTS sur le key exchange DEK/KEK non contractualisé, la reprise différée sans redemande URL, et l'absence de multipart. Score le plus bas du workflow, nécessitant 3 itérations.
• Step 6 à 9h48 (145% de dépassement) : 16 agents séquencés en 4 waves, complexité réelle du module capture sous-estimée (crypto pipeline + upload single/multipart + FSM + reconciliation + idempotence + keyring).
• Gate 8 : 3 BLOQUANTS pré-correction : E-01 (notification SEALED manquante), E-02 (schema migration↔entités incompatible), E-03 (enum DB incomplète). Corrigés avant soumission Gate 8 mais révèlent un gap entre step 6 output et la spec v3.
• 8 MAJEURS résiduels Gate 8 : Dont E-04 (@HttpCode forçant 202), E-06 (incohérence multipart object_key), S-02 (fuite ocr_text en clair dans AsyncStorage), T-01/T-02 (tests auth manquants).

5. Hypothèses révélées tardivement¶

• SHA3-256 non natif React Native — découverte à l'étape 1 (spec). Polyfill @noble/hashes/sha3 ou react-native-quick-crypto requis, non anticipé dans le besoin initial.
• react-native-quick-crypto potentiellement incompatible SHA3 — découverte à l'étape 4 (plan). Fallback @noble/hashes documenté comme dérogation avec benchmark P95 obligatoire.
• Limitation zéroïsage mémoire JS — découverte à l'étape 3 (Gate 3 v2, ECT-05-v2). TypedArray.fill(0x00) n'offre aucune garantie d'effacement physique (GC non déterministe V8/Hermes).
• upload_object_key absent du payload canonique initial — découverte à l'étape 3 (Gate 3 v3, ECT-01-v3). Nécessaire pour discriminer des uploads S3 différents du même fichier.

6. Invariants complexes¶

Invariants difficiles à implémenter ou sensibles aux régressions :

• INV-103-37 (idempotency-canonical-fingerprint) — TC-INV-06 : sérialisation JSON déterministe avec clés triées, normalisation lowercase, exclusion OCR optionnel. 4 variantes de test (A/B/C/D). Risque de régression sur toute modification du payload.
• INV-103-34 (kek-keyring-rotation) — TC-INV-13, TC-NOM-16 : le keyring doit couvrir deferredUploadTtl + dedupWindow (24h + 24h min). Profondeur insuffisante = 422 sur captures différées après rotation.
• INV-103-32 (dek-zeroization) — TC-INV-12 : limitation fondamentale du runtime JS. Test buffer === 0x00 vérifie le buffer applicatif mais pas la mémoire physique.
• INV-103-33 (s3-orphan-gc) — TC-INV-11 : scan S3 par prefix dépend du bucket config Terraform (M15). Orphelin non détecté si prefix mismatch.
• INV-103-08 (sealed-guard) — TC-NOM-08, TC-ERR-08 : double condition signature_status='SIGNED' AND hsm_signature_ref IS NOT NULL. Fenêtre PENDING_SIGNATURE critique.

7. Dette technique¶

Compromis acceptés et non bloquants :

• Pipeline scellement en STUB — impact: élevé. STUB: PD-55 (TSA), PD-56 (Merkle), PD-41 (blockchain). Les transitions PENDING_SEAL → SEALED → ANCHOR_CONFIRMED non testables E2E.
• Fichiers manquants (E-09) — impact: moyen. CaptureProgress.tsx, tests app côté mobile, module infra S3 (M15) non générés par les agents step 6.
• @HttpCode(202) conditionnel (E-04) — impact: faible. Workaround pour supporter 200 idempotent + 202 nouveau. Pattern non standard NestJS.
• ocr_text en clair dans AsyncStorage (S-02) — impact: moyen. Les captures différées stockent ocr_text non chiffré dans AsyncStorage. À corriger dans une story de hardening.
• Tests auth 401/403 absents (T-01/T-02) — impact: faible. Guard @Roles et auth 401 non couverts par tests explicites PD-103.

8. Risques résiduels¶

8bis. Matrice de délégation inter-PD¶

8ter. Bugs de tests¶

8quater. Corrections post-Gate 8¶

9. Patterns récurrents détectés¶

9.1 Patterns confirmés (déjà vus dans d'autres stories)¶

• Key exchange non contractualisé en v1 — aussi dans PD-282 (ProofEnvelope HSM), PD-277 (anti-rejeu PKI). Les flows crypto côté client requièrent une contractualisation DEK/KEK dès la spécification initiale, pas en correctif Gate 3.
• Gate 3 NON_CONFORME en v1 sur stories crypto — aussi dans PD-56 (6.5/10), PD-282 (6.56/10), PD-276 (6.0/10). Les stories avec crypto complexe sous-performent systématiquement en Gate 3 v1.
• Schema migration/entités divergent — aussi dans PD-282, PD-279. Quand migration et entités sont générés par des agents différents (ou à des moments différents), les noms divergent.
• purgeStale() au démarrage du flux — pattern confirmé et validé depuis PD-283, PD-262. Systématiquement exigé pour toute story manipulant des artefacts temporaires sensibles.
• Limitation zéroïsage mémoire JS — aussi dans PD-97, PD-98. Pattern documenté et accepté comme limitation fondamentale du runtime.

9.2 Nouveaux patterns identifiés¶

• Payload canonique d'idempotence avec fingerprint SHA-256 — pattern nouveau pour PD-103. Sérialisation JSON déterministe (clés triées, normalisation lowercase, exclusion champs optionnels) comme contrat d'idempotence. À surveiller pour réutilisation dans d'autres APIs backend.
• KEK keyring avec kek_id pour rotation transparente — pattern nouveau. Permet de déchiffrer les uploads différés après rotation de clé. Rétention minimum deferredUploadTtl + dedupWindow.
• GC orphelins S3 par réconciliation cron — pattern nouveau. Scan S3 vs DB pour détecter et supprimer les objets sans enregistrement backend correspondant.
• Step 6 à 16 agents en 4 waves — plus grande implémentation multi-agents à date. Temps réel 9h48 pour 15 modules. Facteur déterminant du temps total.

10. Améliorations du workflow¶

10.1 Améliorations des prompts/templates¶

10.2 Améliorations des agents¶

10.3 Améliorations du processus¶

• Estimation step 6 pour stories >10 modules : le ratio estimé/réel est de 1:2.5 (4h estimé vs 9h48 réel). Pour les stories avec >10 modules, multiplier l'estimation par 2.5.
• Vérification TypeScript incrémentale post-wave : confirmé fonctionnel (0 erreur TS). Le pattern Wave 1->Wave 4 avec npx tsc --noEmit entre chaque wave est validé.
• Pre-check enum DB avant Gate 8 : ajouter une vérification automatique que tous les états utilisés dans le code existent dans les migrations DDL.

11. Enseignements clés¶

1. Contractualiser le key exchange crypto dès le besoin — Pour toute story avec chiffrement client-side, le protocole DEK/KEK (algorithme, wrapping, zeroization, rotation) doit être dans le besoin v1. L'ajout en correctif Gate 3 coûte 2 itérations supplémentaires et cascade sur tous les documents.

2. L'idempotence déterministe nécessite un contrat de sérialisation normé — Un simple capture_id comme clé d'idempotence ne suffit pas. Le fingerprint canonique (JSON clés triées, normalisation, exclusion champs optionnels) est le seul contrat testable pour distinguer 200 vs 409.

3. Les stories >10 modules nécessitent un budget step 6 de 2.5x l'estimation standard — PD-103 (15 modules, 4 waves, 16 agents) a pris 9h48 vs 4h estimé. Le parallélisme inter-waves ne compense pas la complexité séquentielle intra-wave.

4. Migration et entités doivent être générées par le même agent — La séparation en agents distincts (migration vs service) produit des divergences de nommage (table, colonnes, types enum) qui deviennent des BLOQUANTS Gate 8.

5. Le pattern purgeStale() + suppression immédiate post-UPLOADED est le standard sécurité mobile — Purge au démarrage (résilience crash) + purge immédiate après ACK (réduction surface) + TTL watchdog (garde ultime). Trois niveaux de défense couvrant tous les scénarios de rétention locale.

12. Métriques cumulatives (auto-calculées)¶