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

1. Resume executif¶

2. Metriques de convergence¶

2.1 Temps et iterations¶

Note : duree reelle = temps effectif d'execution (hors pause de ~2h53 entre Gate 5 v1 RESERVE et correction v2). Wall-clock total : ~4h47.

2.2 Scores de convergence par gate¶

2.3 Ecarts par categorie¶

Note : les ecarts sont comptes en cumul brut (avant reclassement confrontation). Apres confrontation Gate 8, 4 ecarts MINEUR retenus + 7 faux positifs rejetes.

3. Points fluides¶

Ce qui a bien fonctionne :

• Gate 3 GO en v1 (8.94/10) : la specification ChatGPT etait suffisamment precise pour passer la gate de conformite du premier coup. C'est la premiere story du projet doc avec ce resultat.
• Gate 8 GO en v1 (9.13/10) : l'implementation a ete validee sans iteration supplementaire. Score le plus eleve des stories recentes.
• Step 6 en 13 min : l'implementation mono-agent sur un perimetre doc-only (Python/Shell/Z-notation) a ete tres rapide. Le scope reduit et le plan bien decompose ont permis une execution directe.
• Discrimination faux positifs LLM en acceptabilite : 7 faux positifs sur 12 ecarts ChatGPT rejetes en Gate 8, tous lies a l'application de grilles backend (Jest, .spec.ts, @Roles, REST) sur un projet doc-only. Le pattern de reclassement est desormais stabilise.
• Injection de learnings efficace : 3 learnings injectes (PD-250, PD-37, PD-35) ont evite des ecarts connus des l'etape 0.

4. Points difficiles¶

Obstacles rencontres (sans justification) :

• Gate 5 RESERVE v1 (7.75/10) : 3 ecarts a corriger (ECT-01 TimestampBatchStatus, AMB-01 normes, AMB-02 pseudo-code). Le pseudo-code du plan utilisait une cle entite seule au lieu du couple entite+colonne, et la decision sur TimestampBatchStatus vs BatchState n'etait pas alignee avec la spec.
• Divergence referentiel normes (Spec §5.1 vs filesystem) : la Spec liste des normes qui n'existent pas (etsi-119-xxx, eidas, rgpd) et ignore des normes reelles (rfc-5054, pv-audit, pv-proof). Cet ecart, documente comme AMB-01r, n'a jamais ete corrige dans la Spec canonique.
• Faux positifs LLM systematiques sur projets doc-only : ChatGPT applique des grilles d'evaluation backend (Jest, TypeScript, REST endpoints, Sonar) sur un perimetre Python/Shell/Z-notation. Le cout de tri des faux positifs est significatif.
• Reference epique jamais propagee : l'identifiant PD-217 est connu dans WORKFLOW-STATE.md mais reste "A clarifier" dans la Spec et "EPIC-XX" dans les Tests.

5. Hypotheses revelees tardivement¶

Hypotheses non explicites decouvertes en cours de workflow :

• Coexistence BatchState / TimestampBatchStatus dans RFC_3161.zed — decouverte a l'etape 4 (plan). RFC_3161.zed contenait deja BatchState avec les memes valeurs que TimestampBatchStatus. La decision d'ajouter TimestampBatchStatus explicitement (conformement a la Spec §5.3) a ete prise en correction Gate 5.
• Multi-enum par entite — decouverte a l'etape 4. _collect_zlint_entities() ecrasait les enums precedents d'une meme entite. La modification pour stocker une liste d'enums par entite etait necessaire pour le filtre de discrimination.
• deposit.status absent des faits Prolog — confirme a l'etape 6 (C4). La branche conditionnelle DepositStatus n'a pas ete executee. Cela a leve la reserve des tests (TC-NOM-06/TC-NOM-07).

6. Invariants complexes¶

Invariants difficiles a implementer ou sensibles aux regressions :

• INV-281-01 (discrimination) — TC-NOM-01/02/03 : la discrimination status vs type/category necessitait un filtre sur le couple (entite, colonne) et non sur l'entite seule. Le pseudo-code du plan v1 etait incorrect sur ce point.
• INV-281-04 (non-regression Anchor entity) — TC-NOM-10, TC-NR-01 : la modification de _collect_zlint_entities() risquait d'alterer le dict entities utilise pour les checks Anchor entity. Le mecanisme de separation des dicts a ete verifie par diff avant/apres.
• INV-281-05 (idempotence) — TC-NOM-09 : le passage au multi-enum risquait d'introduire un non-determinisme si les valeurs n'etaient pas triees. Verifie par double execution.

7. Dette technique¶

Compromis acceptes et non bloquants :

• Spec §5.1 norm_id non alignee avec le filesystem — impact: faible. La Spec liste 3 normes inexistantes et omet 3 normes reelles. Le pipeline fonctionne sur les normes reelles. La mise a jour de la Spec canonique est hors perimetre PD-281.
• Coexistence BatchState / TimestampBatchStatus dans RFC_3161.zed — impact: faible. Deux types Z avec les memes valeurs coexistent. Le linter ne valide que les types references par expected_z_type, donc pas de conflit fonctionnel.
• Reference epique non propagee dans les documents canoniques — impact: faible. Cosmetique, ne bloque pas l'execution.

8. Risques residuels¶

8bis. Matrice de delegation inter-PD¶

8ter. Bugs de tests¶

Aucun bug de test rencontre. Le perimetre PD-281 est doc-only (Python/Shell/Z-notation) sans framework Jest/Vitest.

8quater. Corrections post-Gate 8¶

Aucune correction post-Gate 8 necessaire. Gate 8 GO en v1.

9. Patterns recurrents detectes¶

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

• Format non contractualise dans spec v1 bloque en Gate 3 — aussi dans PD-32, PD-250, PD-264, PD-251, PD-277, PD-276, PD-275. Ici : le referentiel des 9 normes dans la regex Spec §5.1 ne correspondait pas au filesystem reel.
• Faux positifs LLM systematiques en reviews — aussi dans PD-251, PD-276, PD-277, PD-275. Ici : 7/12 ecarts ChatGPT rejetes car grilles backend appliquees a un projet doc-only.
• Stubs inter-PD acceptes en Gate 8 si documentes avec story destination — aussi dans PD-63, PD-82, PD-250, PD-251, PD-277, PD-276. Ici : la mise a jour de la Spec §5.1 (referentiel normes) est un stub documente, sans story destination explicite.

9.2 Nouveaux patterns identifies¶

• Projet doc-only : Sonar Phase 1.5 non applicable — PD-281 est le premier projet doc avec le workflow complet post-Phase 1.5 obligatoire. Sonar n'est pas pertinent pour les scripts Python/Shell de verification formelle. A surveiller pour les prochaines stories doc.
• Grilles d'evaluation LLM inadaptees au perimetre doc-only — les prompts de review (7a/7b/7c) et de gate (8) appliquent systematiquement des criteres backend (Jest, TypeScript, REST, Sonar) aux projets doc-only. Pattern candidat a 1 occurrence, mais tres couteux en faux positifs.
• TimestampBatchStatus vs BatchState : types Z dupliques dans un meme .zed — la coexistence de deux types Z avec les memes valeurs n'a pas cause de conflit, mais n'est pas contractualisee. A surveiller si le linter evolue.

10. Ameliorations du workflow¶

10.1 Ameliorations des prompts/templates¶

10.2 Ameliorations des agents¶

10.3 Ameliorations du processus¶

• Phase 1.5 Sonar : detection automatique du type de projet : pour les projets doc sans sonar-project.properties, la Phase 1.5 devrait etre automatiquement marquee N/A au lieu de necessiter une justification manuelle.
• Propagation de la reference epique : quand le WORKFLOW-STATE.md contient l'identifiant epique (PD-217), il devrait etre automatiquement injecte dans les prompts de spec et tests pour eviter les placeholders "A clarifier" / "EPIC-XX".
• Correction de la Spec canonique apres Gate 5 : quand une divergence documentaire (type AMB-01r) est identifiee en Gate 5 et que la correction est purement documentaire, l'orchestrateur devrait proposer une mise a jour de la Spec avant de continuer. Aujourd'hui, la Spec reste inchangee et la divergence est tracee mais jamais corrigee.

11. Enseignements cles¶

1. Les projets doc-only necessitent des grilles d'evaluation specifiques — les prompts de review ChatGPT appliquent des criteres backend (Jest, TypeScript, REST) qui generent 7/12 faux positifs. Le cout de reclassement est disproportionne par rapport au risque reel sur un perimetre Python/Shell.

2. Gate 3 GO en v1 est un marqueur de qualite de specification — PD-281 est la premiere story doc avec Gate 3 GO en v1 (8.94/10). L'injection de learnings (3 points) et la qualite de l'expression de besoin (etape 0 en 28 min) ont contribue a ce resultat.

3. Le filtre de discrimination doit operer au niveau du couple (entite, colonne) — le pseudo-code initial operait au niveau de l'entite seule, ce qui etait incorrect pour les entites multi-enum. L'ecart a ete detecte en Gate 5 (AMB-02) et corrige en v2. Enseignement : pour toute regle de filtrage multi-dimensionnelle, contractualiser la dimension la plus fine des l'etape 1.

4. La divergence documentaire non corrigee persiste — le referentiel des 9 normes dans la Spec §5.1 reste incorrect malgre la detection en Gate 5. Le processus ne prevoit pas de correction de la Spec canonique apres Gate 3 GO. A corriger dans le workflow.

5. Temps d'execution record sur projet doc-only — 2.5h effectives pour un workflow complet a 11 etapes. Le perimetre reduit (scripts Python, fichiers .zed, configs YAML) et l'absence de complexite backend (pas de DB, pas d'API, pas de tests Jest) expliquent cette performance.

12. Metriques cumulatives (auto-calculees)¶

Document genere le 2026-03-01. Story PD-281, projet ProbatioVault-doc, domaine legal-compliance.