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

1. Résumé¶

Story : One Ring — orchestration multi-stories via claude-peers + contrôle iPhone Projet : ia-governance (tooling) Durée : ~4h (session unique 2026-03-30/31) Gates : G3 RESERVE (v2, 7.875), G5 RESERVE (v1, 7.375), G8 RESERVE (v1, 7.875)

2. Points forts¶

Architecture LOTR claire : La métaphore Sovereign/One Ring/Ringbearers a facilité la conception. L'invariant INV-293-01 (scope guard) est le pilier — implémenté en une seule fonction lord_assert_scope().
Stack Bash cohérente : Réutilisation du pattern existant (scripts/lib/*.sh), bats-core pour les tests. Pas de nouvelle dépendance lourde.
FSM robuste : 21 tests exhaustifs couvrant les 8×8 transitions possibles. Le passage de declare -A à case/esac a résolu l'incompatibilité bats.
Codex plugin : Remplacement d'OpenCode par Codex a éliminé les problèmes de sandbox et de mode agentic pour les prompts < 50KB. Les reviews de gate sont fiables.

3. Écarts et corrections¶

Écart	Gate	Impact	Correction
Fallback claude -p pour étapes ChatGPT	G3 v1	Violation Art. II (validation croisée)	INTERDIT — règle mémorisée, OpenCode remplacé par Codex
Code-contracts dupliqués	G8	2 fichiers concurrents	Unifié en un seul `code-contracts.yaml` aligné sur l'implémentation
Plan écrasé par ChatGPT agentic	G5	Fichier 30KB → 776 bytes	Backup systématique + migration vers Codex
`declare -A` incompatible bats	Step 6	Tests échouent (bash 3.2)	Migration vers `case/esac`
search-learnings.py KeyError	Step 0	21/355 items sans clé `learning`	Fallback sur clé `summary`
Ollama URL localhost	Step 0	404 sur IA-Server	Revert — local correct, IA-Server n'a pas le même modèle
Python pyenv vs system	Step 0	numpy absent	Utiliser `/usr/bin/python3` (system, a numpy+faiss)

4. Learnings¶

L4-01 : INTERDIT fallback claude -p pour étapes ChatGPT¶

Sévérité : CRITIQUE Pattern : Quand OpenCode/ChatGPT échoue (mode agentic, sandbox), ne JAMAIS substituer par claude -p → violation Art. II. Action : Règle mémorisée dans memory/feedback_no_claude_fallback_art2.md. Migration vers Codex plugin.

L4-02 : Code-contracts doivent être extraits DU plan, pas écrits avant¶

Sévérité : HAUTE Pattern : Créer un code-contracts.yaml avant que le plan soit généré produit systématiquement des divergences (noms, composants, interfaces). Action : Learning capturé en Gate 5.

L4-03 : Codex plugin > OpenCode pour les gates¶

Sévérité : HAUTE Pattern : Codex fonctionne sans sandbox filesystem, ne corrompt pas les fichiers du repo, et supporte les gros prompts (>100KB). Action : integrations.md mis à jour — Codex en priorité 1, OpenCode en fallback.

L4-04 : bash `declare -A` incompatible avec bats-core¶

Sévérité : MOYENNE Pattern : Les associative arrays Bash ne fonctionnent pas quand sourcés dans bats (contexte subshell). Utiliser case/esac pour les FSM. Action : Implémentation corrigée.

L4-05 : `/usr/bin/python3` pour scripts governance (pas pyenv)¶

Sévérité : MOYENNE Pattern : pyenv intercepte python3 avec une version qui n'a pas numpy/faiss. Le python système macOS a les dépendances. Action : Mémorisé dans memory/feedback_python_path.md.

5. Métriques¶

Métrique	Valeur
Gates passées	3 (G3 RESERVE v2, G5 RESERVE v1, G8 RESERVE v1)
Itérations totales	4 (G3: 2, G5: 1, G8: 1)
Fichiers créés	29
Tests	45/45
Composants	7 (C1-C7)
Score moyen gates	7.71

6. Améliorations process proposées¶

Protéger les artefacts contre l'écrasement ChatGPT : Avant chaque appel LLM externe, backup des fichiers critiques dans .workspace/.
Forcer codex exec au lieu de opencode run : Mettre à jour tous les scripts d'assemblage.
Tests integration C3-C5 : Prévoir comme stories séparées ou comme dette technique tracée.