GOV-SYSTEM — Retour d'experience (REX)¶

1. Resume executif¶

2. Metriques de convergence¶

2.1 Volume et couverture¶

2.2 Scores de convergence par gate (moyenne 29 stories)¶

Pattern de convergence : Le systeme converge de facon previsible — Gate 3 est la plus couteuse en iterations (2.2 en moyenne), Gate 8 la plus efficace (76% first-pass GO). Le delta de convergence diminue au fil du workflow : la specification absorbe la majorite de l'effort d'alignement.

2.3 Ecarts par categorie (536 ecarts cumules, 29 stories)¶

Observations : - ECT domine (36.6%) : les specifications manquent souvent de bornes numeriques, SLA temporels et formats de donnees en v1. Le template de specification a ete enrichi 6 fois pour contrer ce pattern. - DIV est concentre en Gate 8 (divergences code/spec detectees a l'acceptabilite). - AMB est concentre en Gate ⅗ (ambiguites de specification et de plan). - SEC represente 11% — principalement detecte en Gate 8, pattern attendu. - PERF quasi-absent : les stories ProbatioVault sont orientees conformite/securite, pas performance.

2.4 Repartition par projet et domaine¶

2.5 Complexite¶

3. Points fluides¶

• Convergence des gates : Le taux Gate 8 first-pass GO de 76% demontre que le systeme filtre efficacement les ecarts en amont (gates 3 et 5). Les stories qui passent Gate 5 GO atteignent Gate 8 GO en 1 iteration dans 3 cas sur 4.

• Capitalisation learnings → invariants : Le mecanisme de transformation learning → invariant contractuel (ex: INV-177-20 PostgreSQL subquery, INV-177-21 BullMQ deprecated) est le plus efficace. Les invariants issus de learnings ont un taux de reussite de 100% aux gates suivantes (aucun ecart observe sur un invariant deja capitalise).

• Injection proactive des learnings : Le skill /gov-learnings-inject injecte les 5 learnings les plus pertinents au demarrage de chaque story (etape 0). Cela a elimine les regressions connues des stories 15+ (periode 2026-02 → 2026-03).

• Validation croisee Claude/ChatGPT : L'alternance P1/P2 entre Claude et ChatGPT en gates fonctionne comme prevu. Les biais de chaque LLM sont compenses par l'autre. ChatGPT detecte mieux les ambiguites formelles (Gate 3), Claude detecte mieux les divergences d'implementation (Gate 8).

• Multi-agents step 6 : L'architecture Git-first avec decomposition DAG + agents sequentiels + verification TypeScript incrementale fonctionne. 29 stories sans conflit de merge bloquant.

• Machine d'etats Jira : La migration de WORKFLOW-STATE.md vers Jira (19 statuts, 24 transitions) a supprime les inconsistances d'etat. Jira est la source de verite, .gov-local.json stocke les donnees locales (iteration, substeps, historique).

4. Points difficiles¶

• Gate 3 systematiquement NON_CONFORME en v1 pour le domaine blockchain : PD-55 (6.25/10), PD-52 (7.50/10), PD-177 (6.50/10). Le formalisme requis (codes erreur, politiques confirmations, formats preuve) depasse les capacites des specifications initiales. Le template de specification a du etre enrichi avec des sections specifiques.

• Stagnation delta=0 : 9 stories (31%) ont atteint 3+ iterations sur au moins une gate. La regle de stagnation (delta=0 sur 2 iterations consecutives → ESCALADE) a ete ajoutee apres les REX PD-250 et PD-81 ou les gates tournaient en boucle sans progression.

• OpenCode (ChatGPT) en mode agentic involontaire : Les prompts > 30KB ou contenant des chemins absolus declenchent un mode agentic involontaire dans OpenCode/ChatGPT. Necessite sanitisation des prompts (suppression chemins absolus) et limitation de taille. Contournement : claude -p comme reviewer principal pour les prompts longs.

• Faux positifs LLM en review securite : Les reviewers LLM (7a/7b/7c) ne distinguent pas naturellement barriere primaire (KMS/HSM) vs defense-in-depth (interceptor/guard). Genere ~30% de faux positifs sur les invariants securite. Mitigation : injection du contexte defense-in-depth dans les prompts de review.

• Sonar local vs pipeline : L'indisponibilite frequente de sonar-scanner local a retarde plusieurs stories. La phase 1.5 (Sonar local) a ete rendue bloquante apres 8 stories avec corrections post-Gate 8 causees par Sonar QG FAILED.

• Prompts templates sans versioning initial : Les 20 premiers commits ne versionaient pas les prompts. Les modifications non tracees ont cause des regressions silencieuses. Le header prompt_id: X | version: X.Y.Z a ete introduit apres le REX PD-55.

5. Hypotheses revelees tardivement¶

• HYP-GOV-01 : Les LLM ne sont pas deterministes entre sessions — decouverte au fil des 29 stories. Un meme prompt produit des resultats significativement differents selon la session. Les gates iteratives (v1→v2→v3) convergent malgre cette variabilite grace au mecanisme de delta/scoring.

• HYP-GOV-02 : Le prompt caching a un TTL de 5 minutes — decouverte a l'etape 6 des premieres stories multi-agents. Les agents sequentiels doivent partager un prefixe identique byte-par-byte pour beneficier du cache. Documentee dans workflow-rules.md.

• HYP-GOV-03 : Les fichiers temporaires de claude -p sont purges entre appels — decouverte lors de PD-283. Le subprocess claude -p cree des fichiers via ses tools (Write/Edit) au lieu de tout renvoyer sur stdout. Il faut toujours verifier le fichier cible sur disque.

• HYP-GOV-04 : ALTER TYPE ADD VALUE PostgreSQL necessite une transaction separee — decouverte lors de PD-282. Erreur 55P04 si la nouvelle valeur d'enum est utilisee dans la meme transaction. Necessaire pour toute migration ajoutant des valeurs aux enums.

• HYP-GOV-05 : createVerify double-hashe pour HSM CKM_ECDSA — decouverte lors de PD-282. crypto.createVerify('SHA3-384').update(hash) re-hashe silencieusement. Le correctif est crypto.verify(null, hash, key, sig).

6. Invariants complexes¶

• Art. I — Scoring mathematique : GO >= 8.0, RESERVE >= 7.0, NON_CONFORME < 7.0. Plafond 3 iterations. Delta=0 → ESCALADE. Cet invariant est le plus teste (29 stories × 3 gates = 87 evaluations). Aucune violation.

• Art. II — Validation croisee : L'auteur ne valide jamais son propre travail. Claude produit (steps 0, 4, 6, 9, 10), ChatGPT valide (gates 3, 5, 8 en P1). Et inversement pour les reviews LLM (7a/7b/7c). Aucune violation. Derogation documentee pour prompts > 30KB (OpenCode mode agentic).

• Art. III — Tracabilite : Sync Jira a chaque evenement. 19 statuts, 24 transitions dirigees. Journal local .gov-local.json. Session recording data/sessions/. Aucune violation depuis la migration Jira.

• Art. IV — Non-regression : Les quality gates ne sont jamais contournables. Aucun bypass observe sur 29 stories. Le hook guard-push.sh bloque les push non conformes.

• Art. VII — Skills a force constitutionnelle : Les 32 skills Claude Code sont invoques automatiquement par /gov. Aucune deviation manuelle observee.

7. Dette technique¶

• Prompts non versionnes avant PD-55 — impact : faible (historique non recoverable, mais le versionning actuel fonctionne).
• Scripts shell vs Python — impact : moyen. Les scripts shell (state.sh, jira-api.sh, constitutional-check.sh) sont fragiles. Les scripts Python (index-learnings.py, reindex-all.py) sont plus robustes. Pas de migration prevue.
• Sonar local non automatise — impact : moyen. sonar-scanner doit etre lance manuellement. Devrait etre integre dans les scripts de gouvernance.
• Dashboard GOVERNANCE-DASHBOARD.md genere manuellement — impact : faible. Le script regenerate-dashboard.sh existe mais necessite un appel explicite.
• n8n bridge obsolete — impact : faible. scripts/n8n-bridge.sh reference encore WORKFLOW-STATE.md. Non critique car non utilise activement.
• Templates d'output non versionnes — impact : faible. Seuls les prompts templates ont un header de version. Les output templates (PD-XX-rex.md, etc.) n'en ont pas.

8. Risques residuels¶

8bis. Matrice de delegation inter-PD¶

8ter. Bugs de tests¶

Non applicable — le systeme de gouvernance n'a pas de tests contractuels propres. La validation est empirique (29 stories).

8quater. Corrections post-Gate 8¶

Non applicable — pas de Gate 8 sur le systeme de gouvernance lui-meme.

9. Patterns recurrents detectes¶

9.1 Patterns confirmes (observes sur 3+ stories)¶

• [Spec] Bornes numeriques absentes en v1 — PD-86, PD-81, PD-277, PD-264, et ~15 autres. Le template de specification a ete enrichi 6 fois avec des sections obligatoires (bornes, SLA, formats, transitions inverses, migration DDL, atomicite multi-composant, protection distribuee). Pattern structural : les LLM ne contractualisent pas les bornes numeriques sans instruction explicite.

• [Blockchain] Gate 3 NON_CONFORME en v1 — PD-52, PD-55, PD-177, PD-275. Le formalisme blockchain (codes erreur, politiques confirmations, formats preuve) requiert systematiquement 2+ iterations en Gate 3. Budget a prevoir : 2 iterations.

• [NestJS] Confusion guard vs interceptor — PD-55, PD-177. Le fail-closed sur les responses HTTP = interceptor RxJS, pas guard. Learning capitalise en invariant.

• [Crypto] Validation format ≠ validation fonctionnelle — PD-283, PD-282, PD-265. Un champ securite valide en format (regex, longueur) mais jamais utilise fonctionnellement (compare, verifie). Pattern dangereux car les tests passent.

• [Process] Learnings → invariants = capitalisation la plus efficace — PD-177 (INV-177-20/21), PD-282, PD-265, PD-283. Un learning archive dans learnings.jsonl est facilement oublie. Un invariant contractuel est verifie par les gates.

• [Security] Anti-catch-absorb pour audit fail-closed — PD-85, PD-63, PD-250, PD-262, PD-265 (5 occurrences). Un catch qui absorbe l'erreur d'audit casse le fail-closed. Regle : finally { await audit() } ou catch { await audit(); throw; }.

• [PostgreSQL] ALTER TYPE ADD VALUE en transaction separee — PD-282, PD-279. Erreur 55P04 si utilisation dans la meme transaction. Regle : commitTransaction() avant tout WHERE sur la nouvelle valeur.

• [Machine d'etats] Flags-as-source-of-truth — PD-82, PD-250, PD-264, PD-279, PD-280, PD-278, PD-282, PD-265 (8 occurrences). Pour ≥ 3 conditions de degradation, stocker les flags individuels et deriver l'etat par calcul.

9.2 Nouveaux patterns identifies¶

• [Workflow] La retrospective (step 10) merite son propre statut Jira — Detecte lors de la revue GOV-SYSTEM. Le bundling REX+RETROSPECTIVE dans un seul statut rendait le step 10 invisible dans Jira. Corrige : statut RETROSPECTIVE (id: 10150), transition rex_termine (tid: 24).

• [Workflow] Le nombre de sections obligatoires dans le template de specification croit lineairement — 6 ajouts en 29 stories. Si le pattern continue, le template deviendra trop lourd (> 200 lignes d'instructions). Surveiller la charge cognitive.

• [Process] Les corrections post-Gate 8 sont concentrees sur Sonar — 8 stories avec corrections Sonar post-merge. La phase 1.5 (Sonar local bloquant) a ete introduite pour contrer ce pattern.

• [Workflow] Routage dynamique via assignee Jira — Le mapping etape → agent etait hardcode dans gov-step.sh (case 0|4|9 → claude, 1|2|7 → chatgpt). Remplace par lecture de l'assignee Jira a chaque etape, avec mapping declaratif. 3 utilisateurs Jira (Claude, ChatGPT, Loic Pontani) + automation rules par transition. Changer d'agent = modifier la rule Jira, zero modification de code.

• [Workflow] Reviews LLM parallelisees — Les 3 reviews d'acceptabilite (code, tests, securite) etaient sequentielles (~45 min). Test de concurrence OpenCode valide (3 sessions simultanees, 5 secondes). parallel-reviews.sh lance les 3 en parallele. Gain estime : ~30-40 min/story.

• [Bug] check_prerequisites inversee — Le garde-fou state.sh:755 autorisait un step futur si Jira etait en arriere (jira_step -le step_num au lieu de step_num -le jira_step). Corrige. Le test n'avait jamais ete declenche car le skill /gov respectait deja l'ordre.

• [Bug] Fallback permissif si Jira down — get_step_state et get_current_step retournaient PENDING_STEP / 0 si Jira etait inaccessible, autorisant le workflow a continuer sans validation. Corrige : retour erreur (return 1). Le workflow ne demarre plus sans Jira.

• [Workflow] Detection regression inter-stories — Le workflow verifiait chaque story en isolation. Rien ne detectait qu'une story PD-280 cassait un invariant pose par PD-265. collect-sibling-invariants.py collecte les invariants des stories soeurs (meme domaine/epic) depuis le data-index YAML et les injecte dans les prompts de review (step 7) et d'agents (step 6b). 1695 invariants au total, filtres par domaine (~137 pour crypto-proof).

10. Ameliorations du workflow¶

10.1 Ameliorations des prompts/templates¶

10.2 Ameliorations des agents¶

10.3 Ameliorations du processus¶

• Automatiser la verification fsm.yaml ↔ Jira : Ajouter un script qui probe les transitions Jira et verifie la coherence avec data/fsm.yaml. Utilise pour detecter le statut RETROSPECTIVE manquant.
• Versionner les output templates : Comme les prompt templates, ajouter <!-- template_id: X | version: X.Y.Z --> dans les fichiers templates/outputs/.
• Nettoyer les references WORKFLOW-STATE.md residuelles : scripts/n8n-bridge.sh, scripts/morning-review.sh, scripts/regenerate-dashboard.sh, docs/workflow-documentation.md.
• Migrer les scripts shell critiques vers Python : state.sh (850+ lignes), constitutional-check.sh, jira-api.sh — plus testables et maintenables en Python.
• Nettoyage automatique post-workflow : .workspace/ accumule les fichiers temporaires (952 fichiers, 49 MB). Script de cleanup integre en fin de gov-workflow.sh (fichiers de la story + review orphelins a la racine).

11. Enseignements cles¶

1. Les gates mathematiques fonctionnent — 29 stories, 87 evaluations de gates, score moyen final 8.45/10. Le seuil GO >= 8.0 avec plafond 3 iterations force la convergence sans bloquer indefiniment. Le taux Gate 8 first-pass GO de 76% montre que les gates amont (3, 5) filtrent efficacement.

2. La capitalisation learning → invariant est le seul mecanisme qui resiste a l'oubli — Les learnings archives dans learnings.jsonl sont facilement ignores. Les invariants contractuels (INV-XX) sont verifies mathematiquement par les gates. Sur 355 learnings, seuls ceux transformes en invariants ont un taux de regression de 0%.

3. La validation croisee LLM compense les biais individuels — ChatGPT excelle en detection d'ambiguites formelles, Claude excelle en detection de divergences d'implementation. L'alternance P1/P2 en gates produit des reviews plus equilibrees qu'un seul LLM.

4. Le template de specification est le document le plus critique du workflow — 6 enrichissements en 29 stories. Chaque section ajoutee (bornes numeriques, SLA temporels, formats, transitions inverses, migration DDL, protection distribuee) correspond a un pattern d'echec recurrent. Le template de specification est le compounding du systeme.

5. La machine d'etats formelle (Jira FSM) elimine les inconsistances — La migration de WORKFLOW-STATE.md (fichier Markdown mutable) vers Jira (19 statuts, 24 transitions, gardes) a supprime une classe entiere de bugs (etats incoherents, transitions invalides, race conditions sur fichier partage).

12. Metriques cumulatives (auto-calculees)¶

Date de cloture : 2026-03-28 Auteur : Claude Opus 4.6 Statut : CLOS