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

1. Resume executif¶

Story hybride doc+backend : 26 fichiers TypeScript, 8 suites de tests, 1 document protocole normatif (~2000 LOC), 8 composants architecturaux. Le protocole couvre les 3 types de migration (support, provider, region) avec machine d'etats formelle a 10 etats et 6 codes metier.

2. Metriques de convergence¶

2.1 Scores de convergence par gate¶

Score moyen final : 7.79/10

2.2 Ecarts par categorie¶

3. Points fluides¶

• Machine d'etats formelle : specification rigoureuse des 10 etats et transitions des la v1. Tests exhaustifs TC-INV-10A/10B couvrent 100% des paires etat×transition.
• Canonicalisation JSON : choix RFC 8785 (JCS) a l'etape 4 a resolu proactivement l'ambiguite R-03 de Gate 3.
• Separation codes metier / etats formels : distinction nette entre etats machine (DRAFT, PRECHECK_RUNNING...) et codes de reponse (INVALID_INPUT, CONCURRENT_EXECUTION_DENIED...).
• Couverture tests : 225 tests unitaires, 81 tests structurels couvrant les 45 cas contractuels. Aucune regression.

4. Points difficiles¶

• Gate 3 v1 NON_CONFORME (6.375/10) : score completeness a 5.5. Cause : spec ne definissait pas MANIFEST_STALE comme code metier ni la transition POSTCHECK_RUNNING -> DRAFT. Corrige en v2.
• 3 erreurs TypeScript bloquantes (E-01) : Map constructor mal type, verdict type string au lieu de 'GO' | 'KO', import path incorrect. Pattern recurrent des agents multi-fichiers.
• ManifestIntegrityCheck non appele (E-02) : ManifestService.revalidate() implemente mais VerificationEngine ne l'invoquait pas. Corrige post-acceptabilite.
• Regex readability_pass_rate incorrecte (D-01) : regex simplifiee acceptait 1.0001-1.9999. Corrige avec regex spec stricte.

5. Hypotheses revelees tardivement¶

• H-T01 : MANIFEST_STALE comme 6e code metier — non defini dans spec §3. Implemente en anticipation.
• H-T02 : Impossibilite POSTCHECK_RUNNING -> DRAFT — contourne via POSTCHECK_RUNNING -> ROLLED_BACK puis nouvelle campagne.
• H-T03 : Canonicalisation JSON — spec ne specifie pas la methode. Choix RFC 8785 au plan.
• H-T04 : Detection PRECHECK_EXPIRED en mode LAZY — verification au moment du cutover.

6. Invariants complexes¶

• INV-254-03 (Global Root Hash) — tri lexicographique hex lowercase. Implementation utilise localeCompare (D-04 mineur).
• INV-254-05 (Lisibilite) — 3 criteres simultanes (I/O, MIME, decodage 1024 octets).
• INV-254-09 (Reproductibilite) — seed sampling, horloge controlee, dataset identique.
• INV-254-10 (Transitions explicites) — matrice 10×10 exhaustive.
• INV-254-12 (Integrite manifest) — hash SHA3-256 + signature HSM, revalides au postcheck.

7. Dette technique¶

• MigrationModule non enregistre dans AppModule (D-06) — impact faible, TODO trace.
• WormGuard no-op (D-05) — protection WORM via service, guard = squelette.
• Attestation JSON.stringify vs RFC 8785 (D-03) — divergence convention, pas de rupture fonctionnelle.
• GRH localeCompare (D-04) — risque theorique en locale non-ASCII.

8. Risques residuels¶

9. Patterns recurrents detectes¶

9.1 Patterns confirmes¶

• Erreurs TypeScript post-generation multi-agents — aussi dans PD-282, PD-265, PD-283, PD-85. Les agents ne valident pas le build final.
• Imports/variables inutilises — pattern recurrent sur 5+ stories. Le learning ESLint (PD-265) insuffisamment applique.
• Divergence chemins contracts/implementation — aussi dans PD-283. Code-contracts non mis a jour quand la structure finale diverge.
• Validation format vs fonctionnelle — aussi dans PD-283, PD-282, PD-265. Regex passe mais champ pas utilise fonctionnellement.

9.2 Nouveaux patterns¶

• Story hybride doc+backend — premiere story combinant document normatif et module backend. Gate 3 a score bas car spec couvre les deux perimetres.
• Hypotheses techniques comme contournement de bloquants spec — 6 hypotheses contournent des lacunes spec non corrigees. Risque de dette invisible.

10. Ameliorations du workflow¶

10.1 Process¶

• Ajouter validation npx tsc --noEmit apres chaque agent step 6b (pas seulement step 7).
• Exiger la definition formelle des codes metier dans la spec (section obligatoire).
• Pour les stories hybrides multi-projets, decomposer en 2 specs distinctes.

10.2 Agents¶

• Injecter npx tsc --noEmit dans la checklist de sortie de chaque agent step 6b.
• Le prompt agent verification doit lister explicitement tous les checks a integrer (pas seulement implementer en isolation).

11. Enseignements cles¶

1. Build verification obligatoire a chaque agent — 26 fichiers generes par agents multiples ne compilent pas. Verification incrementale eviterait accumulation d'erreurs.
2. Codes metier dans la spec, pas dans le plan — Le cout de correction augmente exponentiellement avec le numero d'etape.
3. Le check implemente n'est pas le check integre — Service parfaitement implemente et teste en isolation, mais jamais appele dans le flux principal. Pattern "roundtrip" applicable aux flux de verification.
4. Les stories hybrides meritent une spec decomposee — Gate 3 v1 a 6.375, le plus bas recent, car perimetre trop large.
5. Les hypotheses techniques non validees sont de la dette invisible — 6 hypotheses documentees mais aucune formellement validee par la spec.

REX produit le 2026-03-13.