PD-85 — 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é : - Workflow extrêmement rapide : 4.2h total pour une story complexe (14 invariants, 40 TC), le plus rapide du projet pour ce niveau de complexité - Étapes LLM (½) quasi-instantanées : la spécification et les tests produits en <5 min chacun via ChatGPT gpt-5.3-codex, qualité suffisante pour Gate 3 RESERVE en 2 itérations - Implémentation Git-first efficace : 54 fichiers, 4744 insertions en 24 min avec 0 erreur ESLint après 16 corrections automatiques - Capitalisation des REX précédents : le piège createVerify vs crypto.verify(null, ...) (PD-282) a été anticipé dans le plan (§9.3) et correctement implémenté - Gate 5 et 8 en v1 : aucune itération de correction nécessaire, ce qui indique une bonne qualité du plan et de l'implémentation en première passe

4. Points difficiles¶

Obstacles rencontrés (sans justification) : - Étape 0 longue (65 min vs 30 estimées) : la rédaction du besoin a pris plus de temps que prévu, probablement lié à la complexité fonctionnelle (export probatoire multi-composant avec validations RFC) - SonarQube injoignable : la phase 1.5 (scan Sonar) n'a pas pu être exécutée, laissant un angle mort de qualité - Coverage sous seuil : 82.72% statements (seuil 85%), principalement dû au controller à 0% de couverture et aux tests S3 mock absents - OpenCode sandbox bloquant en Gate 8 : fallback sur Claude -p nécessaire (session line 49), source de latence supplémentaire

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

Hypothèses non explicites découvertes en cours de workflow : - HT-03 (encrypted_size absent en base) — découverte à l'étape 6 : le champ n'existe pas sur les entités, nécessitant un fallback à 1 MB par document pour l'estimation de taille. Stub documenté avec story destination. - Rôle LEGAL_GUARDIAN non détectable dynamiquement — découverte à l'étape 6 : le mécanisme de détection du rôle dans le JWT n'est pas encore en place, hardcodé à USER. - documentType non résolvable depuis metadata — découverte à l'étape 6 : DocumentSecure ne contient pas le type de document enrichi, fallback à OTHER.

6. Invariants complexes¶

Invariants difficiles à implémenter ou sensibles aux régressions : - INV-85-03 (integrityHash SHA3-256 JCS) — TC-INV-8503 : la canonicalisation RFC 8785 + SHA3-256 (pas SHA-256) requiert une attention particulière ; réutilisation de json-canonicalize mais hash distinct de celui du TSA existant - INV-85-05 (audit fail-closed) — TC-INV-8505 : l'écart E-01 (BLOQUANT) montre que le pattern try/catch absorbe l'échec d'audit au lieu de propager l'erreur — nécessite un refactoring du catch block - INV-11 (envelopeSeal ECDSA) — TC-INV-11 : implémenté en mode structural (vérification présence des champs) plutôt que cryptographique complet, ce qui est un compromis V1 documenté - INV-85-04 (TTL borné) — TC-INV-8504 : la borne Joi valide la configuration, mais le code service ne clamp pas la valeur runtime — écart E-02 (MAJEUR)

7. Dette technique¶

Compromis acceptés et non bloquants : - extractProofHash() retourne '0'.repeat(64) en fallback — impact: moyen (hash non probant si sha3_256 absent dans anchoringEvidenceRef) - resolveDocumentType() retourne OTHER — impact: faible (enrichissement cosmétique, pas d'impact probatoire) - Rôle hardcodé à USER — impact: moyen (bloque le cas réel LEGAL_GUARDIAN jusqu'à V2) - estimateTotalSize utilise 1 MB/doc — impact: moyen (peut rejeter 413 à tort pour des fichiers légers avec beaucoup de preuves, ou accepter des fichiers très lourds) - Controller à 0% coverage — impact: faible (logique dans le service, controller est thin) - N+1 queries checkOwnership — impact: moyen (2×500 requêtes DB possibles, optimisable avec IN clause)

8. Risques résiduels¶

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

8ter. Bugs de tests¶

Aucun bug de test rencontré. Les 68 tests passent en première exécution après corrections ESLint.

8quater. Corrections post-Gate 8¶

Gate 8 en RESERVE — corrections E-01 à E-05 attendues avant merge et push. Pas encore de pipeline exécuté.

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

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

• Audit fail-closed insuffisant dans catch — aussi dans PD-282 (double-hash absorbé silencieusement) : le pattern try { ... } catch { log.error(); throw new ExportException() } absorbe l'erreur d'audit. Solution : await strict sur l'audit AVANT toute autre opération.
• Coverage sous seuil 85% — aussi dans PD-265, PD-278 : le controller thin et les tests d'intégration S3 manquants font chuter le coverage. Pattern récurrent sur les stories avec endpoints REST.
• SonarQube injoignable — aussi dans PD-262 : le serveur Sonar dev reste instable. 2ème occurrence en 2 stories.
• SHA3-256 vs SHA-256 confusion — anticipé grâce au REX PD-282. Le plan le mentionnait explicitement (§9.1). Pattern prouvé utile.
• Stubs V1 avec story destination — aussi dans PD-251, PD-72 : les 4 stubs documentés avec contexte n'ont pas été flaggés MAJEUR en Gate 8.

9.2 Nouveaux patterns identifiés¶

• Anti-énumération sur IDs de ressource : messages d'erreur 404 distincts ("not found" vs "not accessible") permettent de profiler l'existence. Pattern à capitaliser pour TOUTE story avec lookup par ID externe.
• Configuration Joi vs clamp runtime : la validation Joi garantit que la config est valide au démarrage, mais ne protège pas contre une modification runtime ou un bypass. Ajouter un clamp dans le code métier pour les bornes de sécurité (TTL, taille, rate limit).
• Workflow 4h pour story complexe : première story backend avec 14 invariants livrée en <5h. La capitalisation des REX précédents (crypto, audit, Zero-Knowledge) a permis d'anticiper les pièges.

10. Améliorations du workflow¶

10.1 Améliorations des prompts/templates¶

10.2 Améliorations des agents¶

10.3 Améliorations du processus¶

• Monitorer la disponibilité SonarQube avant étape 7 : si serveur down, déclencher un fallback ESLint+tsc renforcé (2ème occurrence)
• Ajouter un pre-check coverage estimée en fin d'étape 6 : lancer vitest --coverage immédiatement après l'implémentation, avant l'acceptabilité, pour corriger les lacunes plus tôt

11. Enseignements clés¶

1. Audit fail-closed : vérifier le catch, pas juste le try — Un await auditLog() dans le try ne garantit pas le fail-closed si le catch absorbe l'erreur et retourne une exception métier. Le pattern correct est : finally { await audit() } ou audit avant toute exception.

2. Joi valide la config, le code valide le runtime — Une borne Joi max(30) ne suffit pas si le code utilise la valeur sans clamp. Toujours doubler la validation Joi avec un Math.min() dans le code métier pour les bornes de sécurité.

3. Anti-énumération sur les messages 404 — Distinguer "not found" et "not accessible" dans les messages d'erreur permet le profilage d'existence des ressources. Utiliser un message unique ("Proof not found or not accessible") pour TOUT lookup par ID externe.

4. La capitalisation REX accélère le workflow — L'anticipation du piège createVerify vs crypto.verify(null, ...) grâce au REX PD-282 a évité un cycle de correction en Gate 8. Le ROI des learnings est mesurable : 4.2h total pour 14 invariants.

5. Les stubs documentés avec story destination passent les gates — 4 stubs V1 tracés avec contexte et story destination n'ont généré aucun écart MAJEUR en Gate 8. Le pattern est confirmé (3ème story consécutive).

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