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

1. Resume executif¶

2. Metriques de convergence¶

2.1 Temps et iterations¶

Note : le wall clock total est ~13h (incluant ~7h d'attente validation PO etape 0 et ~1h20 entre Gate 8 GO et lancement REX). Le temps actif est ~5h. Le pipeline post-merge a necessite 3 commits correctifs supplementaires (migration DDL — voir section 8quater).

2.2 Scores de convergence par gate¶

Convergence moyenne finale : (8.25 + 7.875 + 9.125) / 3 = 8.42/10

Detail des scores par critere :

2.3 Ecarts par categorie¶

Les 3 ecarts BLOQUANTS de Gate 8 v1 etaient tous de categorie SEC (E-01 double-hash) ou DIV (E-02 structure JSONB, S-01 trust anchor bypass). Leur resolution complete a permis de passer a GO en une seule iteration supplementaire.

3. Points fluides¶

• La decomposition en 4 modules (entity, seal, verification, verifier) a fourni une structure claire et parallelisable. Chaque agent avait des frontieres de responsabilite nettes.
• Le pattern INSERT-only impose par le trigger PD-272 a ete correctement anticipe dans le plan (DA-02), evitant un refactoring majeur lors de l'implementation.
• La correction Gate 8 v1 → v2 a ete particulierement efficace (+1.94 en 1 iteration) grace a des ecarts bien identifies et actionnables par les reviews croisees ChatGPT.
• Les 259 tests contractuels ont ete ecrits et passaient des la v1 de Gate 8 — la couverture contractuelle etait solide malgre les ecarts crypto.
• La reutilisation des services existants (HashService, HsmSignatureService, JsonCanonicalizeService) a accelere l'implementation sans duplication.
• Le mecanisme de detection de secrets (INV-282-06) a ete implemente proprement via pattern matching sur une liste exhaustive de tokens interdits.

4. Points difficiles¶

• Double-hash crypto (E-01) : le pipeline sign/verify etait incompatible — createVerify('SHA3-384') re-hash le buffer deja hashe, tandis que le HSM utilise CKM_ECDSA (raw sign). La resolution via crypto.verify(null, hash, key, sig) est non triviale et non documentee dans la plupart des guides Node.js/HSM. Cout estime : ~30 min de debug.
• Structure JSONB imbriquee (E-02) : le wrapper SealedProofEnvelope etait stocke dans la colonne envelope_seal au lieu de EnvelopeSeal directement. La confusion des niveaux d'abstraction (objet de transport vs objet persistable) est un bug silencieux — les tests mockaient la DB et ne detectaient pas le desalignement.
• Bypass trust anchor (S-01) : trustedRoots optionnel dans le verifier permettait la verification avec un certificat auto-signe. L'hypothese H-01 etait documentee dans la spec mais l'implementation ne l'enforc,ait pas.
• Gates interleaving avec implementation : les Gates 3v3 et 5v3 ont ete relancees apres le debut de l'implementation (step 6), creant un flux non lineaire inhabituel. La correction de la spec pendant l'impl cree de la confusion sur la version de reference.
• Triple NON_CONFORME en v1 : les 3 gates ont demarre en dessous du seuil GO (6.56, 6.69, 7.19), necessitant 8 iterations totales — pattern caracteristique d'une story a complexite conceptuelle elevee.
• Pipeline post-merge migration : apres merge sur main, la migration PD-279/PD-278 a echoue (PostgreSQL erreur 55P04 — ALTER TYPE ... ADD VALUE et clause WHERE dans la meme transaction). Resolution en 3 commits avec le pattern commitTransaction/startTransaction pour separer les phases DDL. Non lie a PD-282 mais impactant le pipeline CI.

5. Hypotheses revelees tardivement¶

• H-01 (trust-store verificateur) : l'hypothese etait documentee dans la spec (section 9) mais l'implementation ne la respectait pas (trustedRoots optionnel) — decouverte a l'etape 7 lors de la review securite ChatGPT.
• Interoperabilite SHA3-384 sign(HSM)/verify(Node.js) : la compatibilite du pattern pre-hash + raw sign n'etait pas prouvee avant l'implementation. Identifiee comme risque dans le plan (§8 risque 2) mais materialisee en ecart BLOQUANT.
• INV-282-03 perimetre trop large : la formulation couvrait potentiellement envelopeSeal alors que INV-282-02 l'exclut explicitement — ambiguite clarifiee en Gate 5 v3.
• CKM_ECDSA vs CKM_ECDSA_SHA3_384 : le HSM CloudHSM ne supporte que le raw sign (CKM_ECDSA). L'hypothese sur le mode de signature HSM n'etait pas explicite dans la spec et a conditionne toute la resolution du double-hash.

6. Invariants complexes¶

• INV-282-01/02/03 (integrite cryptographique) — TC-NOM-01/02. Le trio canonicalisation JCS + exclusion envelopeSeal + SHA3-384 + ECDSA P-384 forme une chaine ou chaque maillon doit etre byte-identical entre sign et verify. Le moindre desalignement (algorithme de hash, encodage DER/IEEE-P1363, niveau de canonicalisation) invalide toute la preuve.
• INV-282-04 (verification offline Mode A) — TC-NOM-04. La suffisance du verificationMaterial pour Mode A depend de la completude des chaines de certificats ET de la presence obligatoire de trusted roots — deux dimensions testees independamment. Mode A est satisfait. Mode B reste une dette technique.
• INV-282-07 (artefacts crypto temporaires) — TC-INV-07. Satisfait par conception (pipeline full-memory, cle privee dans HSM) mais non testable par assertions I/O classiques — preuve par audit statique du code. Acceptable.
• INV-282-09/10 (SEALED terminal) — relies au trigger PD-272. L'etat SEALED est terminal par construction DB (pas d'UPDATE possible). La machine a etats en memoire est coherente avec la persistance.

7. Dette technique¶

Note sur les echecs CI pre-existants : les 12 echecs CI identifie en post-merge sont independants de PD-282 et appartiennent a deux suites de tests pre-existantes (destruction-audit — permissions schema, pd275-concurrency — table manquante). Ils n'affectent pas les 259 tests du module legal-pre.

8. Risques residuels¶

8bis. Matrice de delegation inter-PD¶

8ter. Bugs de tests et corrections crypto¶

8quater. Corrections post-Gate 8¶

Corrections Gate 8 v1 → v2 (3 BLOQUANTS)¶

Corrections pipeline post-merge (migration DDL)¶

Reserves restantes apres Gate 8 v2 (MAJEUR — non bloquantes)¶

9. Patterns recurrents detectes¶

9.1 Patterns confirmes (deja vus dans d'autres stories)¶

• Double NON_CONFORME Gate 3+5 v1 = complexite conceptuelle elevee — aussi dans PD-280, PD-278. Confirme (3eme occurrence, pattern stable). Prevision fiable : 3+ iterations de gate et corrections structurelles requises.
• Machine a etats explicite avec transitions interdites — SEALED terminal (INV-282-09/10). 11eme occurrence dans le projet.
• Guard de securite fail-closed obligatoire — S-01 trust anchor bypass = absence de fail-closed. 11eme occurrence.
• Format non contractualise dans spec v1 — testability 4.75 en Gate 3 v1 (regex/taille manquants pour envelopeSeal et verificationMaterial). 12eme occurrence.
• Atomicite multi-composant : ACID sync + INSERT-only — pattern PD-272 trigger. 8eme occurrence.
• Stubs inter-PD acceptes si documentes avec story destination — OCSP client stub, Mode B partiel. 11eme occurrence.
• Faux positifs LLM en reviews — reviews securite signalant des INV dependant de PD-272 externe. 9eme occurrence.
• Migration DDL + enum dans meme transaction = erreur PostgreSQL 55P04 — aussi dans PD-279/PD-278. 2eme occurrence. Pattern : separer toujours ALTER TYPE ADD VALUE dans une transaction distincte.

9.2 Nouveaux patterns identifies¶

• Double-hash crypto pipeline (pre-hash + HSM raw sign) — createVerify('ALG') de Node.js ajoute toujours un hash sur les donnees passees. Incompatible avec un HSM qui fait du CKM_ECDSA (raw sign sur hash pre-calcule). Solution : crypto.verify(null, hash, key, sig) qui bypass le hachage interne. A documenter comme invariant pour toutes les futures stories HSM.
• Structure JSONB imbriquee (wrapper vs objet direct) — confondre le wrapper de transport (SealedProofEnvelope) avec l'objet a persister (EnvelopeSeal) cause un bug de lecture silencieux depuis la DB. Les tests avec mocks ne le detectent pas.
• SSRF via AIA certificate extensions — les URLs de responders OCSP extraites des extensions AIA des certificats ne sont pas fiables. Tout appel HTTP vers ces URLs sans allowlist/denylist est un vecteur SSRF.
• Gate 8 delta massif apres corrections BLOQUANTES multiples — corriger 3 ecarts BLOQUANTS en une iteration fait passer le score de 7.19 a 9.125 (+1.94). Les ecarts BLOQUANTS bien identifies et actionnables permettent une convergence rapide.
• Spec corrigee pendant l'implementation = flux non lineaire — les Gates 3v3 et 5v3 ont ete relancees apres debut de step 6. Anti-pattern a eviter : terminer toutes les gates avant de demarrer l'implementation.

10. Ameliorations du workflow¶

10.1 Ameliorations des prompts/templates¶

10.2 Ameliorations des agents¶

10.3 Ameliorations du processus¶

• Ne pas demarrer step 6 avant que Gates 3 et 5 soient terminales : le flux non lineaire (gates relancees pendant l'impl) cree de la confusion sur la version de reference de la spec et du rework. Le gain de temps illusoire est annule par les corrections.
• Pour stories crypto : test d'interoperabilite sign/verify en CI avec HSM reel : les mocks HSM ne detectent pas les incompatibilites crypto reelles (double-hash, dsaEncoding, CKM algorithm).
• Test round-trip DB pour toute colonne JSONB complexe : ajouter un test d'integration (INSERT + SELECT + asserter la structure attendue) avant soumission a Gate 8.
• Pattern commitTransaction/startTransaction pour migrations DDL avec enum : documenter ce pattern dans les templates de migration pour eviter les erreurs PostgreSQL 55P04. ALTER TYPE ADD VALUE doit toujours etre dans une transaction separee.
• Tracer les echecs CI pre-existants : maintenir un registre des tests CI en echec pre-existants par module pour ne pas les confondre avec des regressions introductes par la story en cours.

11. Enseignements cles¶

1. crypto.verify(null) pour raw ECDSA matching CKM_ECDSA — createVerify('SHA3-384').update(hash) applique SHA3-384 sur le buffer, produisant un double-hash quand le buffer est deja un hash SHA3-384. Pour un HSM qui signe en raw (CKM_ECDSA sans hachage interne), utiliser crypto.verify(null, hash, { key, dsaEncoding: 'ieee-p1363' }, signature) qui transmet le hash directement sans re-hashage. Ce pattern est distinct de createVerify et non-intuitif sans connaissance du fonctionnement interne de Node.js crypto.

2. Stocker l'objet direct, pas le wrapper — une colonne JSONB doit contenir exactement l'objet attendu a la lecture (EnvelopeSeal), pas un wrapper de transport (SealedProofEnvelope {envelopeSeal, verificationMaterial}). La confusion entre objet de transport et objet persistable est un bug silencieux : les tests avec mocks DB ne le detectent pas car ils retournent le mock directement, pas une deserialisation JSON.

3. trustedRoots optionnel = bypass silencieux — tout service de verification de certificats doit exiger un trust-store non vide et echouer explicitement si absent (raison: no_trusted_roots). Un parametre optionnel permet la verification avec des certificats auto-signes, annulant toute garantie d'ancrage de confiance.

4. Triple NON_CONFORME v1 = indicateur fiable de complexite elevee — quand les 3 gates demarrent en NON_CONFORME (aucun GO ni RESERVE en v1), prevoir 8+ iterations totales et des corrections structurelles (pas incrementales). Ce pattern est maintenant confirme sur 3 stories (PD-280, PD-278, PD-282).

5. Terminer les gates avant l'implementation — relancer des gates pendant l'implementation cree un flux non lineaire, du rework et de la confusion sur la version de reference de la spec. La tentation d'avancer en parallele nuit a la qualite globale du workflow.

6. ALTER TYPE ADD VALUE PostgreSQL dans sa propre transaction — combiner ALTER TYPE ... ADD VALUE (enum extension) avec des clauses WHERE utilisant la nouvelle valeur dans la meme transaction provoque l'erreur PostgreSQL 55P04. Le pattern correct : commitTransaction() apres le ALTER TYPE, puis startTransaction() pour les operations suivantes. Documenter dans les templates de migration TypeORM.

12. Metriques cumulatives (auto-calculees)¶

Calculs bases sur les 9 stories mesurees avec donnees completes (PD-251, PD-277, PD-276, PD-275, PD-281, PD-279, PD-280, PD-278, PD-282) :