PD-81 — Retour d'experience (REX)¶

Story : PD-81 — Creer module Legal PRE pour acces judiciaire Projet : ProbatioVault-backend (NestJS/TypeScript) Domaine : crypto-proof Epic : PD-189 (Cryptographie, preuves et acces legaux) Complexite : complex (19 taches, 55 fichiers, 6203 lignes, 79 tests) Date : 2026-02-23

1. Resume executif¶

PD-81 implemente le module Legal PRE permettant un acces judiciaire exceptionnel, temporaire et tracable a des documents chiffres. Le workflow a necessite 9 iterations de gates cumulees (3+2+4) pour atteindre le verdict GO. La specification a converge rapidement apres une v1 tres faible (4.25/10), tandis que Gate 8 a exige 4 iterations pour passer de 6.13 a 8.15/10. Les ecarts dominants sont de type ECT (7) et DIV (7), avec un volume SEC (6) revelateur de la surface d'attaque elevee d'un module a vocation judiciaire. Six dettes techniques sont tracees, toutes non bloquantes et rattachees a des stories de dependance.

2. Metriques du workflow¶

Chronologie¶

* Interruption de session detectee entre 11:44 et 14:10 (probe capability degraded). ** Estimations basees sur le volume de corrections (4 commits, 79-52=27 tests ajoutes).

Repartition du temps¶

Observation : 63% du temps total est consacre a l'acceptabilite et Gate 8 (corrections iteratives).

3. Metriques de convergence¶

Gate 3 — CONFORMITY_CHECK¶

Convergence : +5.00 en 3 iterations. Delta v1->v2 exceptionnellement eleve (+3.75), indicateur d'une specification v1 insuffisante soumise trop tot.

Gate 5 — AMBIGUITY¶

Convergence : +0.75 en 2 iterations. Ecart v1 concentre sur risk_mitigation (6/10).

Gate 8 — CLOSURE¶

Convergence : +2.02 en 4 iterations. Convergence lente entre v2 et v4 (delta < 0.40 par iteration), indicateur de corrections incrementales plutot que structurelles.

Detail des scores Gate 8¶

Axe le plus faible : test_coverage (5.5 -> 8.0, delta cumulé +2.5). Axe le plus stable : traceability (7.0 -> 8.2, peu de corrections necessaires).

4. Bilan des ecarts¶

Repartition : ECT 35%, DIV 35%, SEC 30%. Absence d'ecarts AMB et PERF.

5. Analyse des ecarts majeurs¶

Ecart 1 : Gate 3 v1 — NON_CONFORME (4.25/10)¶

• Categorie : Spec
• Cause : Specification v1 soumise avec 3 bloquants et 12 ecarts majeurs. Definitions insuffisantes (destructionDeadline, validationTtl, bobPublicKey, rate limiting non contractualises).
• Impact : 2 iterations supplementaires de Gate 3 (+3.75 de delta pour atteindre 8.00).
• Resolution : Corrections v2 et v3 par ChatGPT avec ajout de 7 definitions, 5 corrections INV, et formalisation du comportement concurrent.

Ecart 2 : Gate 8 v1 — test_coverage (5.5/10)¶

• Categorie : ECT
• Cause : 52 tests a l'issue du step 6, couverture des erreurs E01-E18 a 11/18. Assertions trop generiques (LegalPreException sans code specifique).
• Impact : 4 commits de corrections, +27 tests pour atteindre 79 (progression de 52%).
• Resolution : T-01 (codes ERR-81-XX precis), T-02 (couverture E01-E18 complete), T-05 (SERIALIZABLE asserte), T-06 (edge cases TTL).

Ecart 3 : S-04 — kfrags non chiffres au repos¶

• Categorie : SEC (CRITIQUE)
• Cause : Implementation initiale (step 6) ne chiffrait pas les key fragments avant persistance.
• Impact : Ecart critique identifie en review securite step 7. Corrige commit 4972e70 avec AES-256-GCM envelope encryption.
• Resolution : encryptKfrags()/decryptKfrags() implementes dans legal-rekey-manager.service.ts.

Ecart 4 : S-01/S-02/S-03 — Faiblesses d'autorisation¶

• Categorie : SEC
• Cause : Authz bypass sur audit proof (S-01), identity venant du body au lieu du JWT (S-02), absence de verification BOLA/IDOR (S-03).
• Impact : 3 ecarts securite corriges dans le meme commit, JWT binding ajoute sur 3 endpoints.
• Resolution : extractActorIdentity(req.user.sub), ownership check via validationAdapter, BOLA prevention.

Ecart 5 : R-02/R-03/S-06 — GET avec side effects et absence de SERIALIZABLE¶

• Categorie : DIV + SEC
• Cause : Controller initial appelait consultDocument() depuis un endpoint GET (side effects). Transactions de mutation hors niveau SERIALIZABLE.
• Impact : Corriges des le premier round de corrections (commit 6d284f0). Faux positif en reviews subsequentes (code deja corrige non pris en compte par le reviewer LLM).
• Resolution : Controller refactored read-only, SERIALIZABLE sur revoke/expire/close.

6. Tests et couverture¶

Progression des tests¶

Taux d'augmentation : +52% (52 -> 79) pendant la phase d'acceptabilite.

Couverture par type¶

Couverture fonctionnelle¶

• Erreurs E01-E18 : 18/18 (100%) — atteint a l'iteration v2
• Invariants INV-81-01 a INV-81-12 : testes directement ou indirectement
• Coverage module : ~57% (faible car Jest mesure le projet entier)

7. Patterns recurrents¶

Patterns observes dans PD-81¶

Patterns cross-stories (domaine crypto-proof)¶

8. Risques residuels¶

Dettes techniques tracees¶

Stubs documentes¶

Risque Sonar¶

• Quality Gate non executee localement (token Sonar absent dans Vault).
• A verifier en pipeline GitLab CI/CD apres merge sur dev.
• Risque estime faible (ESLint + tsc clean, pas de patterns Sonar connus).

9. Learnings¶

L1 — Les specs crypto-judiciaires exigent une formalisation exhaustive des SLA temporels¶

Contexte : Gate 3 v1 = 4.25/10. Les definitions de destructionDeadline, validationTtl, rate limiting, et bobPublicKey etaient absentes ou vagues. Learning : Pour tout module a contrainte judiciaire/reglementaire, chaque transition d'etat temporelle DOIT avoir un SLA configurable avec borne min/max et valeur par defaut. Lister ces SLA comme checklist obligatoire dans le prompt de specification. Tags : #legal-pre, #eidas, #sla-temporal, #spec-completeness

L2 — L'encryption at-rest des artefacts cryptographiques temporaires n'est pas implicite¶

Contexte : S-04 (kfrags non chiffres) = ecart CRITIQUE detecte en review securite, absent des tests initiaux. Learning : Tout artefact cryptographique temporaire (ReKey, kfrags, DEK) DOIT etre chiffre at-rest. Ajouter un invariant explicite INV-XX-envelope-encryption dans les specs crypto. Le prompt de specification crypto doit inclure "envelope encryption at-rest" comme invariant par defaut. Tags : #crypto, #envelope-encryption, #at-rest, #invariant-candidate

L3 — Le binding JWT sur les endpoints d'action doit etre systematique des le step 6¶

Contexte : S-02 (identity venant du body), corrige tardivement au commit 4972e70 (step 7 v3). Learning : L'extraction de l'identite de l'acteur DOIT provenir du JWT (req.user.sub), jamais du body de la requete. Ajouter dans le template de code-contracts une regle explicite : "actorIdentity = JWT subject, never request body". Tags : #security, #jwt-binding, #authorization, #code-contracts

L4 — Les reviews LLM produisent des faux positifs massifs sur code deja corrige¶

Contexte : 5 ecarts (R-02, R-03, R-04, S-04, S-06) signales comme MAJEUR alors que le code etait deja corrige dans des commits precedents. Learning : Les prompts de review LLM (7a/7b/7c) doivent inclure la liste des corrections deja appliquees (commits + descriptions) pour eviter les faux positifs. Le triage consomme du temps et complexifie les dossiers de conformite. Tags : #review-llm, #faux-positifs, #prompt-engineering, #acceptabilite

L5 — Gate 8 a convergence lente indique des corrections incrementales insuffisantes¶

Contexte : Gate 8 v2->v3 = +0.30, v3->v4 = +0.35. Convergence sous 0.40/iteration. Learning : Quand le delta entre iterations est < 0.50, les corrections sont trop incrementales. Regrouper les ecarts par theme (securite, tests, completude) et les corriger par lot plutot qu'un par un. Seuil d'alerte : si delta < 0.50 apres 2 iterations, reconsiderer l'approche de correction. Tags : #gate-convergence, #correction-strategy, #efficiency

10. Ameliorations process¶

10.1 — Checklist SLA temporels dans le prompt de specification (haute priorite)¶

Fichier cible : templates/prompts/1 Specification.md Description : Ajouter une section obligatoire "SLA temporels" dans le template de specification pour les modules a contrainte reglementaire. Chaque transition d'etat avec dimension temporelle doit specifier : valeur par defaut, borne min, borne max, configurabilite. Justification : Gate 3 v1 PD-81 = 4.25/10, principalement a cause de SLA manquants. Pattern recurrent sur PD-55 et PD-39. Priorite : haute

10.2 — Injection des corrections dans les prompts de review LLM (haute priorite)¶

Fichier cible : templates/prompts/7a Review Code.md, templates/prompts/7b Review Tests.md, templates/prompts/7c Review Security.md Description : Ajouter dans les templates 7a/7b/7c une section "Corrections deja appliquees" qui liste les commits de correction avec leur description. Instruire le reviewer LLM de ne pas signaler comme ecart un probleme deja corrige. Justification : 5 faux positifs MAJEUR dans PD-81 sur code corrige. Pattern identique dans PD-55 et PD-63. Priorite : haute

10.3 — Invariant envelope encryption dans les specs crypto (moyenne priorite)¶

Fichier cible : templates/prompts/1 Specification.md Description : Pour tout module du domaine crypto-proof ou crypto, ajouter un invariant par defaut : "Tout artefact cryptographique temporaire (cle, fragment, DEK) est chiffre au repos (AES-256-GCM ou HSM envelope)". Justification : S-04 PD-81 = ecart CRITIQUE. Pattern similaire PD-35 (key-wrapping). Cout de correction tardive eleve. Priorite : moyenne

10.4 — Seuil d'alerte convergence lente dans les gates (moyenne priorite)¶

Fichier cible : CLAUDE.md (section Guardrails) Description : Ajouter une regle : "Si delta entre 2 iterations consecutives de gate < 0.50, l'orchestrateur DOIT regrouper les ecarts restants par theme et produire un batch de corrections plutot que des corrections unitaires". Justification : PD-81 Gate 8 : 4 iterations avec convergence lente (v2->v3 = 0.30, v3->v4 = 0.35). Priorite : moyenne

11. Conclusion¶

PD-81 est une story complexe (19 taches, 55 fichiers, 6203 lignes) qui a converge vers un verdict GO (8.15/10) en 4 iterations de Gate 8. La complexite du domaine judiciaire/crypto a genere un volume d'ecarts significatif (20 ecarts dont 6 SEC) mais tous ont ete resolus ou documentes comme dette technique non bloquante.

Points forts : - Architecture claire (controller thin, orchestration centralisee, services decouples) - Pipeline probatoire complet (hash + HSM + TSA + ancrage) - 79 tests avec couverture E01-E18 complete (18/18) - 12 invariants contractuels tous couverts

Points faibles : - Specification v1 soumise trop tot (4.25/10 en Gate 3) - Encryption at-rest des kfrags oubliee en implementation initiale - JWT binding absent sur 3 endpoints en step 6 - Convergence lente Gate 8 (4 iterations)

Verdict : GO confirme. Dettes techniques tracees et rattachees a PD-37 (HSM) et DocumentsModule. Aucun bloquant residuel.

12. Metriques JSONL¶

{"story":"PD-81","project":"backend","domain":"crypto-proof","title":"Créer module Legal PRE pour accès judiciaire","completed_at":"2026-02-23","total_time_hours":18,"gate_iterations":{"gate3":3,"gate5":2,"gate8":4},"convergence_scores":{"gate3_v1":4.25,"gate3_v2":8.00,"gate3_final":9.25,"gate5_v1":7.75,"gate5_final":8.50,"gate8_v1":6.13,"gate8_v2":7.50,"gate8_v3":7.80,"gate8_final":8.15},"deviations":{"ECT":7,"DIV":7,"AMB":0,"SEC":6,"PERF":0},"complexity":"complex","tests":{"passed":79,"total":79,"suites":7,"coverage_module":57},"tasks":19,"files":55,"lines":6203,"debt_items":6}