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

1. Résumé exécutif¶

2. Métriques de convergence¶

2.1 Temps et itérations¶

Note : L'étape 0 inclut un temps étendu de discussion PO (expression de besoin détaillée avec analyse Prolog et conformité formelle). Les étapes 1-8 sont significativement plus rapides que les estimations standard grâce à la maturité du workflow automatisé et à la faible surface de code (module crypto isolé).

2.2 Scores de convergence par gate¶

2.3 Écarts par catégorie¶

3. Points fluides¶

• L'étape 1 (spécification via ChatGPT) a produit une spec structurée avec 11 invariants, 13 CA et machine à états en un seul passage
• Le plan d'implémentation (étape 4) a correctement identifié la contradiction spec/Prolog (fait deriveKey vs validateParams) et proposé la résolution par alias
• L'implémentation (étape 6) a été rapide : 7 fichiers créés, 2 modifiés, 27/27 tests PASS en moins de 10 minutes
• La Gate 8 a obtenu un score élevé (8.375/10) en v1, confirmant la maturité de la chaîne spec→plan→code
• Les reviews LLM (7a/7b/7c) ont produit majoritairement des faux positifs correctement filtrés par l'orchestrateur

4. Points difficiles¶

• Gate 3 v1 NON_CONFORME (6.25/10) : 11 écarts dont 1 bloquant (contradiction INV-276-08 exhaustivité vs probatoire) et 8 majeurs
• La contradiction structurelle entre INV-276-09 (spec déclare validateParams) et la réalité Prolog (checks consomment deriveKey) a traversé tout le workflow sans correction formelle dans la spec
• L'ambiguïté de la politique LEGACY phase 1 (INV-276-07 impose vérification tag, mais CA-276-13 autorise accès sans tag) a nécessité une résolution conceptuelle (branche conditionnelle tag NULL vs tag invalide)
• Le score test_coverage reste le plus bas en Gate 8 (7.5/10) à cause de l'absence de tests E2E/migration

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

• H-276-02 (faits Prolog) — découverte à l'étape 3 : les checks Prolog 10 et 22 consomment service_method(argon2, deriveKey) et non validateParams comme déclaré dans la spec. Résolu par alias dans le plan, mais la spec n'a pas été formellement corrigée.
• Backfill LEGACY applicatif — découverte à l'étape 4 : le backfill des enveloppes existantes nécessite K_master_user (wrappée dans l'enveloppe elle-même), rendant impossible un simple UPDATE SQL. Nécessite un flux de lazy migration.
• Contexte HKDF double notation — découverte à l'étape 5 : le plan utilisait deux notations (ProbatioVault::MetadataBinding::v1 vs PV::MB::v1) pour le même contexte HKDF, identifié comme bloquant en Gate 5.

6. Invariants complexes¶

• INV-276-09 (faits Prolog) — TC-INV-04 : La dépendance entre les faits émis et les checks consommateurs (check_10, check_19, check_22) repose sur le comportement exact de l'extracteur extract-facts.py. Le nommage du fichier (argon2.service.ts) et de la classe (Argon2Service) doit être exact.
• INV-276-07 + CA-276-13 (verify-before-access + LEGACY) — TC-NOM-05, TC-NOM-12 : La coexistence de la vérification obligatoire du tag et de l'accès LEGACY sans tag en phase 1 requiert une logique bifurquée complexe dans unwrapEnvelope().
• INV-276-11 (machine à états) — TC-NOM-13, TC-ERR-10, TC-ERR-11 : La transition LEGACY → TAMPERED est complexe car une enveloppe LEGACY n'a pas de tag par définition — l'incohérence ne peut être détectée que lors d'une tentative de calcul/rotation.

7. Dette technique¶

• C5 KeyEnvelopeService non étendu — impact: moyen — Les flux réels de création/rotation/unwrap n'intègrent pas encore le metadata binding. Les primitives (computeTag, verifyTag) sont prêtes mais non câblées.
• Tests E2E et migration absents — impact: moyen — 22 TC d'intégration/E2E documentés mais non implémentés. La confiance repose uniquement sur les 27 tests unitaires.
• Générateur de faits Prolog non vérifié — impact: faible — L'extraction extract-facts.py n'a pas été exécutée sur le code candidat. La conformité 24/24 est une projection, pas une preuve.
• Object.freeze optionnel sur ARGON2_CONFIG — impact: faible — as const TypeScript suffit mais ne protège pas à l'exécution.

8. Risques résiduels¶

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

8ter. Bugs de tests¶

Aucun bug de test rencontré. Les 27 tests unitaires ont passé dès la première exécution.

8quater. Corrections post-Gate 8¶

Aucune correction post-Gate 8 nécessaire. L'implémentation a été acceptée avec RESERVE sans rework.

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

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

• Machine à états explicite avec transitions autorisées/interdites — aussi dans PD-82, PD-250, PD-264, PD-251, PD-277. Les 3 états de binding (LEGACY, BOUND, TAMPERED) suivent exactement le même pattern.
• timingSafeEqual pour comparaisons crypto — aussi dans PD-38, PD-238, PD-264, PD-251, PD-277. Utilisé pour la comparaison du metadata_tag.
• Guard de sécurité fail-closed obligatoire — aussi dans PD-238, PD-240, PD-250, PD-251, PD-277. Le tag invalide produit un rejet immédiat HTTP 422.
• Stubs inter-PD avec story destination — aussi dans PD-63, PD-82, PD-250, PD-251, PD-277. C5 KeyEnvelopeService documenté comme PD-276-phase2.
• Gate 3 NON_CONFORME v1 sur stories crypto — aussi dans PD-55, PD-264. Le formalisme RFC/Prolog manque systématiquement dans les specs initiales.
• Extraction automatique de faits Prolog depuis @Column TypeORM — aussi dans PD-277.

9.2 Nouveaux patterns identifiés¶

• Alias sémantique Prolog — Le service expose une méthode deriveKey() comme alias de validateParams() pour satisfaire les checks Prolog sans violer l'architecture zero-knowledge. Pattern de conformité formelle vs sémantique métier.
• Exigence probatoire (non exhaustive) — INV-276-08 qualifié explicitement comme "probatoire" dès la spec v2, distinguant les exigences démontrables par tests finis de celles nécessitant des contrôles par échantillonnage.
• Migration DDL en 2 phases avec lazy backfill applicatif — Quand le backfill nécessite des clés wrappées (K_master_user), impossible de faire un UPDATE SQL batch. La phase 2 (NOT NULL) est conditionnée au traitement de 100% des enregistrements LEGACY via accès utilisateur.

10. Améliorations du workflow¶

10.1 Améliorations des prompts/templates¶

10.2 Améliorations des agents¶

10.3 Améliorations du processus¶

• Le passage direct de Gate 3 v1 NON_CONFORME à v2 RESERVE (+1.25 delta) montre l'efficacité de la boucle de correction, mais les 11 écarts v1 auraient pu être réduits si la spec v1 avait eu accès au fichier Prolog
• La Gate 5 RESERVE v1 avec 3 bloquants (contradiction HKDF, état binding non persisté, contradiction spec/Prolog) aurait pu être évitée avec une checklist pre-Gate 5 incluant la vérification de cohérence des littéraux cryptographiques

11. Enseignements clés¶

1. Vérifier les consumers formels avant de contractualiser les producteurs — La spec a déclaré validateParams comme fait Prolog requis sans vérifier que les checks Prolog consomment effectivement ce nom. L'écart a traversé 5 étapes avant d'être résolu par alias dans le code.

2. Qualifier les exigences probatoires dès la rédaction — Le tag [PROBATOIRE] sur INV-276-08 a évité des allers-retours Gate 3 sur la testabilité. Les exigences non démontrables par tests finis doivent être identifiées comme telles dès la spec.

3. Centraliser et vérifier l'unicité des littéraux cryptographiques — Le contexte HKDF ProbatioVault::MetadataBinding::v1 apparaissait sous 2 formes dans le plan (PV::MB::v1). Une constante unique et un grep pre-gate auraient détecté l'incohérence.

4. Les backfills crypto nécessitent une analyse de faisabilité DDL — Quand le backfill dépend de clés wrappées, la migration classique (ALTER + UPDATE batch) est inapplicable. L'analyse du mécanisme de backfill doit être faite dès l'étape 4.

5. Le score test_coverage plafonne sans E2E — 27/27 tests unitaires ne suffisent pas pour un GO plein en Gate 8. Les stories avec migration DDL et binding crypto nécessitent des tests d'intégration DB pour atteindre 8+/10 en couverture.

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