GOV-SYSTEM — Plan d'implémentation (reverse-engineering)¶

Objet : Documentation exhaustive du système de gouvernance IA ProbatioVault, produite par reverse-engineering du code existant. Ce document suit le format standard des plans d'implémentation PD-XX.

1. Découpage en composants¶

#	Composant	Responsabilité	Fichiers	Dépendances
C1	Orchestrateur principal	Boucle séquentielle des 11 étapes, gestion des exit codes, garde constitutionnelle	`scripts/gov-workflow.sh`	C2, C3, C4, C5
C2	Exécuteur d'étape	Lit l'assignee Jira pour déterminer dynamiquement l'executor (Claude/ChatGPT/Gate/Multi-agent), assemble le prompt, exécute ou délègue. Fallback hardcodé si Jira inaccessible.	`scripts/gov-step.sh`	C4, C5, C6, C7, C8
C3	Affichage d'état	Lecture Jira + local, synthèse lisible	`scripts/gov-status.sh`	C4
C4	Gestionnaire d'état	Abstraction Jira (source de vérité) + `.gov-local.json` (données locales)	`scripts/lib/state.sh`	C5
C5	Client API Jira	Fonctions bas niveau REST (GET/POST), transitions, commentaires, lecture assignee, mapping executor	`scripts/lib/jira-api.sh`	—
C6	Assembleur de prompts	Injection de documents, ordering cache-first, substitution de placeholders	`scripts/assemble-prompt.sh`, `scripts/lib/inject-docs.sh`	C9
C7	Orchestrateur multi-agents	Parsing du manifest, dispatch agents (Claude auto / ChatGPT manuel), validation TS inter-agent	`scripts/lib/agents.sh`	C6, C5
C8	Vérificateur constitutionnel	Scan automatisé des violations Articles I-VII avant verdict de gate	`scripts/constitutional-check.sh`	C4
C9	Résolveurs projet/epic	Cascade de résolution du chemin projet et du dossier epic	`scripts/lib/resolve-project.sh`, `scripts/lib/resolve-epic.sh`	—
C10	Revue documentaire	Vérifie 12/12 artefacts (6 MD + 6 YAML) avant clôture Jira	`scripts/check-docs.sh`	C4
C11	Skills Claude Code	Prompts structurés invocables par `/gov`, `/gov-step`, `/gov-gate`, etc.	`.claude/commands/gov*.md`, `.claude/commands/gate.md`	C1–C10
C12	Machine d'états (FSM)	Définition formelle des 19 statuts Jira, 24 transitions, gardes, actions	`data/fsm.yaml`	—
C13	Templates de prompts	Prompts versionnés pour chaque étape et sous-phase	`templates/prompts/*.md`	—
C14	Templates de sortie	Structures cibles des artefacts produits	`templates/outputs/*.md`	—
C15	Définitions d'agents	System prompts des agents spécialisés (developer, adversarial, SRE, QA, etc.)	`config/agents/*.md`	—
C16	Registre d'agents	État des agents de production et en évaluation (shadow mode, A/B)	`data/agent-registry.yaml`	—
C17	Base de métriques	Historique des stories terminées (temps, gates, écarts, complexité)	`data/metrics.jsonl`	—
C18	Base de learnings	Apprentissages extraits des gates et REX, indexés par embeddings	`data/learnings.jsonl`, `data/learnings-*.npy`, `scripts/index-learnings.py`	—
C19	Data-index YAML	Index structuré de tous les artefacts par story/projet/domaine	`data/specs-index/*/.yaml`	—
C20	Dashboards	Tableaux de bord agrégés (gouvernance, métriques)	`dashboards/*.md`, `scripts/regenerate-dashboard.sh`	C4, C17
C21	Constitution	Règles inviolables (Articles I-VII), injectées dans toutes les gates	`governance/CONSTITUTIONAL.md`	—
C22	Session recording	Journalisation JSONL de chaque événement par story	`data/sessions/*-session.jsonl`, `scripts/session-log.sh`	—
C23	Intégration OpenCode	Wrapper ChatGPT (capture variable, sandbox filesystem)	`scripts/opencode-run.sh`, skill `/opencode`	—
C27	Reviews parallèles	Lance 3 sessions OpenCode concurrentes (code, tests, sécurité) pour l'acceptabilité step 7	`scripts/parallel-reviews.sh`	C6, C23
C28	Détection régression inter-stories	Collecte les invariants des stories sœurs (même epic/domaine) depuis le data-index YAML et les injecte dans les prompts de review et d'agents	`scripts/collect-sibling-invariants.py`	C19
C24	Intégration Ollama	LLM local pour tâches sensibles et indexation embeddings	skill `/ollama`	—
C25	Pipeline de cohérence	Vérification Prolog inter-besoins (contradictions, ambiguïtés)	skill `/coherence`	C18, C19
C26	Pipeline de traçabilité	Catalogue RFC, mapping test/story, matrice RTM, détection gaps	`scripts/traceability/`, skill `/traceability`	C19

Architecture technique¶

ProbatioVault-ia-governance/
├── scripts/                        # C1-C10 : Shell scripts exécutables
│   ├── gov-workflow.sh             # C1  : Orchestrateur principal
│   ├── gov-step.sh                 # C2  : Exécuteur d'étape
│   ├── gov-status.sh               # C3  : Affichage d'état
│   ├── check-docs.sh               # C10 : Revue documentaire
│   ├── assemble-prompt.sh          # C6  : Assemblage prompts
│   ├── constitutional-check.sh     # C8  : Vérification constitutionnelle
│   ├── session-log.sh              # C22 : Session recording
│   ├── regenerate-dashboard.sh     # C20 : Dashboards
│   ├── opencode-run.sh             # C23 : Wrapper OpenCode
│   ├── parallel-reviews.sh         # C27 : Reviews parallèles step 7
│   ├── index-learnings.py          # C18 : Indexation embeddings
│   └── lib/
│       ├── state.sh                # C4  : Gestionnaire d'état
│       ├── jira-api.sh             # C5  : Client API Jira
│       ├── resolve-project.sh      # C9  : Résolution projet
│       ├── resolve-epic.sh         # C9  : Résolution epic
│       ├── inject-docs.sh          # C6  : Injection documents
│       └── agents.sh               # C7  : Multi-agents
├── .claude/commands/               # C11 : Skills Claude Code
│   ├── gov.md                      # Skill principal /gov
│   ├── gov-step-0.md               # Step 0 (besoin)
│   ├── gov-step.md                 # Steps génériques
│   ├── gov-impl.md                 # Step 6 (multi-agents)
│   ├── gov-accept.md               # Step 7 (acceptabilité)
│   ├── gov-gate.md                 # Gates PMO (3/5/8)
│   ├── gov-retrospective.md        # Step 10
│   ├── gov-compounder.md           # Métriques/capitalisation
│   ├── gov-check-plan.md           # Pre-Gate 5
│   └── gov-check-docs.md           # Pre-clôture
├── .claude/rules/                  # Règles injectées automatiquement
│   ├── procedures.md               # Procédures par étape
│   ├── integrations.md             # Outils externes
│   ├── learnings.md                # Patterns appris
│   └── workflow-rules.md           # Versioning, caching
├── governance/
│   └── CONSTITUTIONAL.md           # C21 : Articles I-VII
├── data/
│   ├── fsm.yaml                    # C12 : FSM formelle
│   ├── agent-registry.yaml         # C16 : Registre agents
│   ├── metrics.jsonl               # C17 : Métriques
│   ├── learnings.jsonl             # C18 : Learnings
│   ├── sessions/                   # C22 : Sessions JSONL
│   └── specs-index/                # C19 : Data-index YAML
├── templates/
│   ├── prompts/                    # C13 : Templates prompts (versionnés)
│   └── outputs/                    # C14 : Templates de sortie
├── config/
│   └── agents/                     # C15 : Définitions agents
├── dashboards/                     # C20 : Dashboards
├── CLAUDE.md                       # Instructions projet
└── CLAUDE.local.md                 # Credentials (non commité)

2. Flux techniques¶

2.1 Flux nominal : Story complète (happy path)¶

┌─────────────┐
│  Utilisateur │
│  /gov PD-XX  │
└──────┬───────┘
       │
       ▼
┌──────────────────────────────────────────────────────────────────────┐
│  C11 Skill /gov                                                       │
│  1. Probe capabilities (claude-p, opencode, ollama, vault)            │
│  2. Search learnings pertinents (C18)                                 │
│  3. Read Jira metadata (C5)                                           │
│  4. Resolve project + epic (C9)                                       │
│  5. Init state (C4) — Jira + .gov-local.json                         │
│  6. Display state (C3)                                                │
│  7. Determine next step                                               │
│  8. Delegate to step skill                                            │
└──────┬───────────────────────────────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────────────────────────────────────┐
│  BOUCLE PRINCIPALE (steps 0 → 10)                                     │
│                                                                        │
│  Pour chaque step :                                                    │
│    1. gov-step.sh détermine le type d'étape                           │
│    2. Assemble le prompt (C6) via templates (C13)                     │
│    3. Exécute selon le type :                                         │
│       • Claude steps (0, 4, 9)     → claude -p ou clipboard          │
│       • ChatGPT steps (1, 2)       → opencode run (C23)              │
│       • Gate steps (3, 5, 8)       → 4 phases (voir §2.2)            │
│       • Multi-agent step (6)       → 3 phases (voir §2.3)            │
│       • Acceptabilité (7)          → QG auto + Sonar + 3 reviews     │
│       • Retrospective (10)         → pattern analysis + CLAUDE.md     │
│    4. Détecte l'artefact produit                                      │
│    5. Met à jour l'état (C4 → Jira transition + .gov-local.json)      │
│    6. Génère le YAML data-index (C19)                                 │
│    7. Log session (C22)                                               │
│    8. Passe à l'étape suivante                                        │
│                                                                        │
│  Exit codes :                                                          │
│    0 → succès (GO ou RESERVE)                                         │
│    2 → NON_CONFORME (workflow en pause)                               │
│    3 → ESCALADE (décision humaine requise)                            │
└──────┬───────────────────────────────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────────────────────────────────────┐
│  POST-WORKFLOW                                                         │
│  1. check-docs.sh — vérifie 12/12 artefacts (C10)                    │
│  2. Compounder — metrics.jsonl + learnings + dashboard (C17, C18)     │
│  3. Jira transition → Done (tid 31) (C5)                              │
└──────────────────────────────────────────────────────────────────────┘

2.2 Flux Gate PMO (steps 3, 5, 8)¶

                   ┌──────────────────┐
                   │  Gate déclenchée  │
                   │  (step 3/5/8)    │
                   └────────┬─────────┘
                            │
              ┌─────────────▼──────────────┐
              │  Phase 1 — Review (P1)      │
              │                             │
              │  Gate 3 : P1=Claude          │
              │  Gate 5 : P1=ChatGPT         │
              │  Gate 8 : P1=ChatGPT         │
              │                             │
              │  → PD-XX-review-stepN.md    │
              └─────────────┬──────────────┘
                            │
              ┌─────────────▼──────────────┐
              │  Phase 2 — Confrontation    │
              │  (P2, LLM opposé à P1)      │
              │                             │
              │  Gate 3 : P2=ChatGPT         │
              │  Gate 5 : P2=Claude          │
              │  Gate 8 : P2=Claude          │
              │                             │
              │  → PD-XX-confrontation.md   │
              └─────────────┬──────────────┘
                            │
              ┌─────────────▼──────────────┐
              │  Phase 3 — Dossier          │
              │  Synthèse des écarts        │
              │  + constitutional-check (C8) │
              │                             │
              │  → PD-XX-dossier-conformite │
              └─────────────┬──────────────┘
                            │
              ┌─────────────▼──────────────┐
              │  Phase 4 — Verdict          │
              │                             │
              │  Scoring (Art. I) :          │
              │  • All ≥ 8.0 → GO           │
              │  • Mean ≥ 7.0 → RESERVE     │
              │  • Mean < 7.0 → NON_CONFORME│
              │  • Blockers → ESCALADE       │
              │                             │
              │  → PD-XX-verdict-stepN-vI   │
              └─────────────┬──────────────┘
                            │
             ┌──────────────┼──────────────────┐
             │              │                   │
        ┌────▼────┐   ┌────▼─────┐   ┌────────▼────────┐
        │   GO    │   │ RESERVE  │   │  NON_CONFORME   │
        │ (ou     │   │ Humain   │   │  ou ESCALADE    │
        │ RESERVE │   │ tranche) │   │                 │
        │ auto)   │   │          │   │ iteration++     │
        └────┬────┘   └────┬─────┘   │ (max 3, Art. I) │
             │              │         │ delta=0 → ESC   │
             ▼              ▼         └────────┬────────┘
        Continue        Continue               │
        step N+1        step N+1          ┌────▼────┐
                                          │Correction│
                                          │(retour   │
                                          │ step N-1)│
                                          └──────────┘

2.3 Flux Multi-agents (step 6)¶

┌────────────────────────────────────────────────────────────────────┐
│  Phase 0 — Git Init                                                 │
│  git checkout -b feature/{STORY-ID}-{slug}                          │
│  git push -u origin feature/{STORY-ID}-{slug}                       │
└────────────────────────────┬───────────────────────────────────────┘
                             │
┌────────────────────────────▼───────────────────────────────────────┐
│  Phase 6a — Décomposition                                           │
│                                                                      │
│  Input : spec + tests + plan + code-contracts                        │
│  Agent : Claude (mode équilibré)                                     │
│  Output : PD-XX-decomposition.md (manifest CSV)                      │
│                                                                      │
│  Format manifest :                                                   │
│  | Agent | Module | Description | Livrable | Fichiers autorisés |   │
│  |-------|--------|-------------|----------|---------------------|   │
│  | agent-developer | auth-module | Impl auth | src/auth/ | ... |    │
└────────────────────────────┬───────────────────────────────────────┘
                             │
┌────────────────────────────▼───────────────────────────────────────┐
│  Phase 6b — Exécution séquentielle des agents                       │
│                                                                      │
│  Pour chaque ligne du manifest :                                     │
│    1. Assembler prompt agent (C6) — cache-first :                    │
│       [Bloc stable] Spec + Tests + Plan + TOUS code-contracts        │
│       [Bloc variable] Identité agent + Mission + Contract module     │
│    2. Exécuter :                                                     │
│       • Claude agents → claude -p (auto)                             │
│       • ChatGPT agents → opencode run (auto) ou clipboard (>30KB)   │
│    3. Sauvegarder livrable : PD-XX-agent-{agent}-{module}.md         │
│    4. Vérification TS : npx tsc --noEmit (si applicable)             │
│       → Si erreur TS : corriger AVANT agent suivant                  │
│    5. Commit intermédiaire sur la feature branch                     │
│    6. Mettre à jour sous-étape .gov-local.json (6b-N → DONE)        │
└────────────────────────────┬───────────────────────────────────────┘
                             │
┌────────────────────────────▼───────────────────────────────────────┐
│  Phase 6c — Synthèse                                                 │
│                                                                      │
│  Claude orchestre le merge final :                                    │
│    1. Lit tous les livrables agents                                   │
│    2. Résout les conflits d'interface                                 │
│    3. Écrit le code final dans le projet cible                        │
│    4. Commit + push sur feature branch                                │
│                                                                      │
│  → Transition Jira : IMPLEMENTATION → ACCEPTABILITE (tid 9)          │
└────────────────────────────────────────────────────────────────────┘

2.4 Flux Acceptabilité (step 7)¶

┌──────────────────────────────────────┐
│  Phase 1 — Quality Gates automatisés  │
│                                        │
│  npm run lint          (ESLint)        │
│  npm run format:check  (Prettier)      │
│  npx tsc --noEmit      (TypeScript)    │
│  npm test              (Jest)          │
│  npm run test:cov      (Coverage ≥80%) │
│                                        │
│  → Tout rouge = STOP                   │
└──────────────────┬───────────────────┘
                   │ ✅ tout vert
┌──────────────────▼───────────────────┐
│  Phase 1.5 — Sonar Quality Gate       │
│                                        │
│  sonar-scanner (local)                 │
│  → QG ERROR = STOP (BLOQUANT)          │
│  → QG PASSED = continue                │
└──────────────────┬───────────────────┘
                   │ ✅ QG PASSED
┌──────────────────▼───────────────────┐
│  Phase 2 — Reviews LLM (3 parallèles)│
│                                        │
│  7a : Review Code (structure, DRY)     │
│  7b : Review Tests (couverture, edge)  │
│  7c : Review Sécurité (OWASP, crypto)  │
│                                        │
│  Injection stubs connus + TODO tracés  │
│  (réduction faux positifs, REX PD-55)  │
└──────────────────┬───────────────────┘
                   │
┌──────────────────▼───────────────────┐
│  Phase 3 — Synthèse                   │
│                                        │
│  → PD-XX-acceptability.md              │
│  → Transition Jira : ACCEPTABILITE     │
│    → GATE CLOSURE (tid 10)             │
└──────────────────────────────────────┘

2.5 Flux Compounder (post step 9)¶

┌─────────────────────────────────────────────┐
│  Phase 1 — metrics.jsonl                     │
│  Append : story, project, domain, gates,     │
│  scores, écarts, complexité, durée           │
├─────────────────────────────────────────────┤
│  Phase 2 — learnings.jsonl                   │
│  Extraction automatique depuis REX + verdicts│
│  Reindex embeddings (Ollama BGE-M3)          │
├─────────────────────────────────────────────┤
│  Phase 3 — Dashboards                        │
│  regenerate-dashboard.sh                     │
├─────────────────────────────────────────────┤
│  Phase 4 — Améliorations process             │
│  REX section 10 → Edit CLAUDE.md / rules     │
│  Si CLAUDE.md modifié → validation humaine   │
├─────────────────────────────────────────────┤
│  Phase 5 — Learnings-as-invariants           │
│  Patterns récurrents → nouveaux invariants   │
├─────────────────────────────────────────────┤
│  Phase 6 — Traçabilité                       │
│  RTM update, detect-gaps.py, gaps.jsonl      │
└─────────────────────────────────────────────┘

3. Mapping invariants → mécanismes¶

Invariant ID	Exigence	Mécanisme	Composant	Observable	Risque
INV-GOV-01	Scoring non négociable (Art. I) : GO ≥ 8 partout, RESERVE ≥ 7 moyenne, NON_CONFORME sinon	Calcul numérique dans le verdict YAML, gardes FSM dans `data/fsm.yaml` (`iteration < 3`)	C12 (FSM), C11 (skill /gov-gate)	Verdict YAML contient `scores` et `verdict` vérifiables	Contournement si le skill est bypassé manuellement
INV-GOV-02	Plafond 3 itérations (Art. I) : max 3 tentatives par gate	Compteur `iteration` dans `.gov-local.json`, garde `iteration >= 3 → ESCALADE`	C4 (state.sh), C12 (FSM)	`.gov-local.json` field `iteration`, commentaire Jira	Corruption du fichier local
INV-GOV-03	Delta stagnation (Art. I) : delta=0 sur 2 itérations consécutives → ESCALADE	Calcul `score_mean(vN) - score_mean(vN-1)`, stocké dans `.gov-local.json` field `last_delta`	C4, C11 (skill /gov-gate)	Commentaire Jira "delta=0, ESCALADE"	Scores arrondis masquant un delta réel
INV-GOV-04	Validation croisée (Art. II) : l'auteur ne valide jamais son propre travail	Mapping P1/P2 par gate : Gate 3 (Claude/ChatGPT), Gate 5 (ChatGPT/Claude), Gate 8 (ChatGPT/Claude)	C11 (skill /gov-gate)	Review et confrontation par LLM différents, tracé dans le dossier	Pas de vérification automatisée du mapping P1/P2
INV-GOV-05	Traçabilité Jira (Art. III) : sync à CHAQUE événement, ne JAMAIS attendre	`jira_transition()` et `jira_post_comment()` appelés dans `update_step_status()`	C4, C5	Historique Jira visible, commentaires horodatés	Jira indisponible (timeout 15s → fallback dégradé)
INV-GOV-06	Non-régression (Art. IV) : QG JAMAIS contournables	Phase 1 (lint/format/tsc/test) et Phase 1.5 (Sonar) BLOQUANTES dans step 7	C11 (skill /gov-accept)	Exit code non-zero bloque le workflow	Agent peut ne pas exécuter le skill correctement
INV-GOV-07	Acceptabilité complète (Art. V) : Phase 1 + 1.5 + 2 obligatoires	Séquence imposée dans skill `/gov-accept` : auto → Sonar → LLM reviews	C11	PD-XX-acceptability.md contient les 3 phases	Skip possible si skill invoqué partiellement
INV-GOV-08	Responsabilité totale (Art. VI) : aucun bug "pré-existant"	Pas de mécanisme automatisé — règle de comportement pour l'agent	C21 (CONSTITUTIONAL)	Traces dans REX, learnings	Règle comportementale non enforcée par le code
INV-GOV-09	Skills = force constitutionnelle (Art. VII)	Skills chargés dans le contexte Claude Code avec priorité sur les instructions par défaut	C11	Skill `.md` chargé en system prompt	Dépend du runtime Claude Code
INV-GOV-10	Isolation inter-étapes : chaque étape dans un contexte propre	`gov-step.sh` exécute chaque étape en sous-processus ; `claude -p` pour les steps Claude	C1, C2	Processus séparés, pas de variable partagée	Steps ChatGPT via clipboard partagent le même navigateur
INV-GOV-11	Cache-first ordering : contenu statique en premier, dynamique en dernier	`assemble-prompt.sh` et `inject-docs.sh` ordonnent : template → docs → rules → agent identity → task	C6	Prompt assemblé vérifiable dans `.workspace/`	Réordonnancement accidentel casse le cache
INV-GOV-12	12/12 artefacts avant clôture	`check-docs.sh` vérifie 6 MD + 6 YAML avant transition Done	C10	Exit code 0/1, message explicite	Artefact présent mais vide ou tronqué
INV-GOV-13	Vérification TS inter-agent (step 6)	`npx tsc --noEmit` après chaque agent 6b, correction avant agent suivant	C7 (agents.sh)	Exit code tsc, erreurs listées	Projet sans TypeScript (stories Python, Terraform)
INV-GOV-14	Sonar QG BLOQUANT (step 7)	Phase 1.5 : si QG ERROR → STOP avant reviews LLM	C11 (skill /gov-accept)	Sonar dashboard, acceptability.md section 1.5	sonar-scanner non installé → fallback interdit
INV-GOV-15	Stubs inter-PD avec story destination	Chaque stub documente la story cible (ex: `// STUB: PD-37`)	C11 (skill /gov-impl), C13	Grep `STUB:` dans le code produit	Agent oublie d'annoter le stub
INV-GOV-16	Prompt versioning	Chaque template porte un header `prompt_id \| version \| updated \| changelog`	C13	Header lisible, versions enregistrées dans `.gov-local.json`	Oubli de bump après modification
INV-GOV-17	Session recording	Chaque événement logué dans `data/sessions/{story}-session.jsonl`	C22	Fichier JSONL vérifiable	Script oublié dans un chemin d'exécution
INV-GOV-18	Cohérence inter-EB	Pipeline Prolog vérifie les contradictions entre besoins après step 0	C25	Rapport Prolog, contradictions listées	Modèle Prolog incomplet

4. Mapping critères d'acceptation → mécanismes¶

Critère ID	Description	Mécanisme(s)	Composant	Observable
CA-GOV-01	Une story peut traverser les 11 étapes de bout en bout sans intervention manuelle (hors gates)	Boucle `while` dans `gov-workflow.sh`, exit codes 0/⅔, `gov-step.sh` par type	C1, C2	Story complète dans Jira (To Do → Done)
CA-GOV-02	Le statut Jira reflète l'étape courante en temps réel	`update_step_status()` appelle `jira_transition()` à chaque changement	C4, C5	Statut Jira vérifié vs `.gov-local.json`
CA-GOV-03	Les gates produisent 4 artefacts : review, confrontation, dossier, verdict	Séquence imposée dans skill `/gov-gate` (4 phases)	C11	4 fichiers dans le dossier epic
CA-GOV-04	Le verdict YAML contient les scores individuels, la moyenne, le delta, et le verdict final	Template `verdict-stepN-vI.yaml` dans `templates/outputs/`, rempli par le skill	C11, C14	Fichier YAML parseable avec tous les champs
CA-GOV-05	Un verdict NON_CONFORME revient à l'étape de correction et incrémente le compteur	Transition Jira (tid 8/17/12), `.gov-local.json` `iteration++`	C4, C12	Jira en CORRECTION/NON_CONFORME, compteur incrémenté
CA-GOV-06	L'ESCALADE bloque le workflow et attend une décision humaine	Transition vers ESCALADE_SPEC/PLAN/CLOSURE (tid 18/19/20), exit code 3	C4, C12, C2	Jira en ESCALADE_*, workflow en pause
CA-GOV-07	Le multi-agents (step 6) produit un manifest puis exécute chaque agent séquentiellement	Phase 6a → 6b → 6c, manifest CSV parsé, boucle sur agents	C7	Fichiers `PD-XX-decomposition.md` + `PD-XX-agent--.md`
CA-GOV-08	Les prompts sont assemblés en mode cache-first (contenu statique en tête)	`assemble-prompt.sh` + `inject-docs.sh` : ordering imposé	C6	Prompt dans `.workspace/` vérifiable
CA-GOV-09	Les learnings sont extraits automatiquement après chaque story	Compounder Phase 2 : extraction depuis REX + verdicts, reindex embeddings	C18, C11	Nouvelles entrées dans `learnings.jsonl`
CA-GOV-10	Le dashboard se régénère après chaque transition	`regenerate-dashboard.sh` appelé dans le compounder	C20	`dashboards/GOVERNANCE-DASHBOARD.md` mis à jour
CA-GOV-11	Les données locales (iteration, substeps, history) survivent à un crash/reprise	`.gov-local.json` écrit sur disque à chaque mutation via `_write_local_json()`	C4	Fichier JSON persistant dans le dossier epic
CA-GOV-12	La revue documentaire bloque la clôture si un artefact manque	`check-docs.sh` retourne 1 si < 12 documents, `gov-workflow.sh` bloque	C10, C1	Message explicite + exit code 1
CA-GOV-13	Les agents spécialisés reçoivent TOUS les code-contracts (pas seulement le leur)	`assemble-prompt.sh` injecte le fichier `code-contracts.yaml` complet dans le bloc stable	C6	Prompt contient le YAML complet
CA-GOV-14	La validation croisée alterne les LLM entre review et confrontation	Mapping codé en dur dans `/gov-gate` : Gate 3 (Claude→ChatGPT), Gate 5 (ChatGPT→Claude), Gate 8 (ChatGPT→Claude)	C11	Dossier de conformité mentionne les 2 LLM
CA-GOV-15	Le pipeline de cohérence inter-EB détecte les contradictions Prolog	Skill `/coherence check PD-XX` après step 0, rapport avec contradictions critiques	C25	Rapport Prolog, STOP si contradiction critique

5. Mapping tests → mécanismes + observables¶

Test ID	Référence	Mécanisme(s)	Point(s) d'observation	Niveau
TC-WF-01	INV-GOV-01 (scoring)	Verdict YAML avec scores calculés	Fichier verdict : `verdict == "GO"` si tous scores ≥ 8	Integration (dry-run gate)
TC-WF-02	INV-GOV-02 (plafond 3)	`.gov-local.json` iteration ≥ 3 → ESCALADE	Transition Jira vers ESCALADE après 3 NON_CONFORME	Integration
TC-WF-03	INV-GOV-03 (delta stagnation)	Calcul delta entre v1 et v2, si delta=0 → ESCALADE	`.gov-local.json` last_delta=0, Jira commentaire	Integration
TC-WF-04	INV-GOV-04 (validation croisée)	Gate 3 : review par Claude, confrontation par ChatGPT	Dossier conformité liste les 2 LLM utilisés	Manual (vérification du dossier)
TC-WF-05	INV-GOV-05 (sync Jira)	`jira_get_status()` après `update_step_status()`	Statut Jira correspond à l'étape courante	Integration (appel API)
TC-WF-06	INV-GOV-06 (non-régression)	Exit code non-zero de lint/tsc/test bloque step 7	Workflow stoppé, message d'erreur affiché	Integration
TC-WF-07	INV-GOV-10 (isolation)	Chaque `gov-step.sh` est un sous-processus	`ps` montre des PIDs distincts, pas de variable partagée	Manual
TC-WF-08	INV-GOV-12 (12/12 docs)	`check-docs.sh` avec 11/12 docs → exit 1, 12/12 → exit 0	Exit code, message listant le document manquant	Unit (script test)
TC-WF-09	INV-GOV-13 (vérif TS inter-agent)	`npx tsc --noEmit` entre agents 6b-1 et 6b-2	Exit code tsc, erreurs TS listées avant correction	Integration
TC-WF-10	INV-GOV-14 (Sonar bloquant)	Sonar QG ERROR → workflow stoppé avant reviews LLM	acceptability.md section 1.5 = ERROR, pas de section 2	Integration
TC-WF-11	CA-GOV-01 (bout en bout)	Story test (PD-290 ?) traversant 11 étapes	Jira passe de To Do à Done, 12 artefacts produits	E2E (dry-run complet)
TC-WF-12	CA-GOV-05 (correction loop)	Verdict NON_CONFORME → Jira en CORRECTION → retour step 7	Statut Jira CORRECTION, puis retour ACCEPTABILITE	Integration
TC-WF-13	CA-GOV-06 (escalade)	Verdict ESCALADE → Jira en ESCALADE_*, exit code 3	Workflow en pause, message affiché	Integration
TC-WF-14	CA-GOV-07 (multi-agents)	Manifest parsé, agents exécutés séquentiellement	N fichiers `PD-XX-agent--.md`, sous-étapes dans `.gov-local.json`	Integration
TC-WF-15	CA-GOV-11 (reprise crash)	Kill workflow mid-step, relancer → reprend au bon endroit	`get_current_step()` retourne l'étape correcte après redémarrage	Resilience
TC-WF-16	INV-GOV-16 (prompt versioning)	Template modifié sans bump → détectable	Diff entre `prompts_versions` dans `.gov-local.json` et header actuel	Unit
TC-WF-17	INV-GOV-18 (cohérence Prolog)	Besoin contradictoire → Prolog détecte	Rapport Prolog avec `contradiction: true`	Integration

6. Gestion des erreurs¶

Code erreur	Condition	Composant	Traitement	Observable
EXIT 0	Étape terminée avec succès	C2 (gov-step)	Continue vers étape suivante	Jira transitionné, artefact produit
EXIT 2	Verdict NON_CONFORME	C2	Workflow en pause, message correction	Jira en CORRECTION/NON_CONFORME
EXIT 3	Verdict ESCALADE ou décision humaine	C2	Workflow en pause, attend décision PO	Jira en ESCALADE_*
EXIT 1	Erreur technique (script, réseau, etc.)	C1, C2	Demande utilisateur : continuer ?	Message d'erreur affiché
JIRA_UNAVAILABLE	Timeout API Jira (15s)	C5	`jira_get_status()` retourne "JIRA_UNAVAILABLE", fallback `.gov-local.json`	Message warning
TS_BUILD_FAIL	`npx tsc --noEmit` échoue entre agents	C7	STOP agent suivant, corriger erreurs TS	Erreurs tsc listées
SONAR_QG_ERROR	Sonar Quality Gate en erreur	C11	STOP avant reviews LLM	acceptability.md Phase 1.5 = ERROR
DOCS_MISSING	< 12 artefacts à la clôture	C10	Bloquer transition Jira → Done	Liste des documents manquants
OPENCODE_TIMEOUT	ChatGPT ne répond pas	C23	Retry 1 fois, puis clipboard fallback	Message "Timeout OpenCode"
PROLOG_CONTRADICTION	Contradiction critique inter-EB	C25	STOP avant step 1, résolution obligatoire	Rapport Prolog
ITERATION_MAX	3 itérations gate atteintes	C4	ESCALADE automatique (Art. I)	`.gov-local.json` iteration=3, Jira ESCALADE
DELTA_ZERO	Stagnation scores (delta=0, 2 itérations)	C4	ESCALADE immédiate (Art. I)	Commentaire Jira "stagnation"

7. Impacts sécurité¶

Risque	Sévérité	Mitigation	Composant
Credentials Jira en clair dans `jira-api.sh`	CRITIQUE	Fichier non commité (`.gitignore`), `CLAUDE.local.md` pour les secrets	C5
Token Vault en clair dans `CLAUDE.local.md`	CRITIQUE	`.gitignore`, accès restreint au poste développeur	C5
Injection de prompt via artefacts	MOYEN	Les artefacts sont lus comme documents, pas exécutés ; constitutional-check détecte les violations	C6, C8
Contournement des gates par skill bypass	MOYEN	Art. IV et VII : règles constitutionnelles, skill = force obligatoire	C21
Fichiers temporaires sensibles dans `/tmp`	FAIBLE	Prompts assemblés dans `.workspace/` (dans le repo), pas de données client	C6
API Jira sans rate limiting côté client	FAIBLE	Timeouts configurés (10s connect, 15s max), pas de boucle retry agressive	C5
Commentaires Jira exposent des détails techniques	FAIBLE	Commentaires structurés sans données sensibles (pas de credentials, pas de code)	C5

8. Hypothèses techniques¶

ID	Hypothèse	Validation	Impact si faux
H-GOV-01	Jira est toujours accessible depuis la machine locale	`jira_get_status()` avec timeout 15s	Fallback `.gov-local.json` dégradé (pas de transition)
H-GOV-02	Claude Code est le runtime principal (extension VSCode)	Skills `.claude/commands/` chargés automatiquement	Si CLI standalone : skills non disponibles, usage scripts shell uniquement
H-GOV-03	OpenCode est installé et authentifié ChatGPT Plus	`which opencode` + test connexion	Steps ChatGPT impossibles → clipboard fallback (interdit par règle)
H-GOV-04	Ollama est accessible sur IA-Server (192.168.1.82)	`curl http://192.168.1.82:11434/api/tags`	Indexation learnings impossible, pas de shadow evals
H-GOV-05	Le projet cible a une structure `docs/epics/{domain}/`	`resolve-epic.sh` cherche ce pattern	Epic non trouvé → création interactive
H-GOV-06	`python3` est disponible pour le parsing JSON	Utilisé dans `jira-api.sh` pour parser les réponses	Fallback `jq` non implémenté
H-GOV-07	`sonar-scanner` est installé localement	`which sonar-scanner`	Phase 1.5 impossible → STOP (substitution ESLint+tsc interdite)
H-GOV-08	Les templates de prompts sont stables entre les étapes d'une story	Versioning header dans chaque template	Si template change mid-story : incohérence prompt/artefact
H-GOV-09	Le Team-managed Jira project expose les transitions via API REST	Transitions découvertes empiriquement (PD-290)	Si Jira change le workflow : TIDs incorrects → transitions échouent
H-GOV-10	Un seul workflow actif par story à la fois	Pas de verrou (mutex) sur `.gov-local.json`	Race condition si 2 sessions parallèles sur la même story

9. Points de vigilance (risques, dette, pièges)¶

9.1 Risques identifiés¶

#	Risque	Probabilité	Impact	Mitigation
R1	Race condition sur `.gov-local.json` : 2 sessions Claude concurrentes sur la même story	Moyenne	Corruption d'état	Pas de mutex implémenté — convention : 1 session par story
R2	TIDs Jira hardcodés : si le workflow Jira est modifié (ajout/suppression de statut), les TIDs changent	Faible	Transitions échouent silencieusement (curl -sf ignore les erreurs)	Redécouvrir les TIDs via `jira_list_transitions()`
R3	Dépendance ChatGPT via OpenCode : si API ChatGPT down, 5 étapes bloquées (1, 2, gates P1/P2)	Moyenne	Workflow complètement bloqué	Pas de fallback LLM local pour ces étapes
R4	Prompts > 30KB : ChatGPT bascule en mode agentic involontaire	Connue	Réponse inutilisable (tool-calling au lieu de texte)	Sanitisation paths + `claude -p` comme fallback pour prompts longs
R5	Constitutional check non exhaustif : scan heuristique, pas de vérification formelle complète	Moyenne	Violation constitutionnelle non détectée	Vérification formelle Prolog disponible mais pas intégrée dans le flow automatique

9.2 Dette technique¶

#	Dette	Sévérité	Localisation
D1	`scripts/n8n-bridge.sh` référence encore `WORKFLOW-STATE.md` (non migré vers Jira)	Basse	`scripts/n8n-bridge.sh`
D2	`scripts/morning-review.sh` et `scripts/regenerate-dashboard.sh` scannent les `WORKFLOW-STATE.md` (obsolètes)	Basse	`scripts/morning-review.sh`, `scripts/regenerate-dashboard.sh`
D3	`docs/workflow-documentation.md` documente l'ancienne architecture (WORKFLOW-STATE.md, table parsing)	Moyenne	`docs/workflow-documentation.md`
D4	`config/claude/commands/` contient des copies obsolètes des skills	Basse	`config/claude/commands/gov*.md`
D5	Pas de test automatisé du workflow (aucun TC-WF-* implémenté)	Haute	Aucun fichier de test
D6	`python3` utilisé pour parser JSON dans `jira-api.sh` au lieu de `jq` (plus fragile)	Basse	`scripts/lib/jira-api.sh`
D7	Credentials Jira dupliqués : `jira-api.sh` ET `CLAUDE.local.md`	Moyenne	2 fichiers avec le même token
D8	Pas de health-check au démarrage du workflow (Jira, OpenCode, Ollama, sonar-scanner)	Moyenne	`scripts/gov-workflow.sh`
D9	Les `WORKFLOW-STATE.md` existants dans les projets cibles ne sont plus lus mais pas supprimés	Basse	`ProbatioVault-/docs/epics/*/WORKFLOW-STATE.md`

9.3 Pièges connus¶

claude -p depuis Claude Code : nécessite unset CLAUDECODE && en préfixe, sinon conflit de session.
OpenCode sandbox : bloque les redirections stdout directes (> file). Toujours capturer en variable shell.
Jira Team-managed : le workflow n'est pas exposé via l'API classique /rest/api/3/workflow/search. Les TIDs sont découverts empiriquement.
Multi-step Jira : SPECIFICATION couvre steps 1-2 (le champ current_substep dans .gov-local.json disambiguë). REX et RETROSPECTIVE ont chacun leur propre statut Jira.
Prompt caching TTL 5 min : si le temps entre 2 appels dépasse 5 min, le cache est perdu. Les gates itératives (v1→v2) bénéficient du cache si exécutées rapidement.

10. Hors périmètre¶

#	Exclusion	Justification
HP-01	CI/CD du repo de gouvernance : pas de pipeline GitLab pour le repo `ia-governance` lui-même	Le repo est un outil interne, pas un livrable
HP-02	Tests automatisés du workflow : aucun test unitaire/intégration des scripts shell	Complexité d'un test harness pour un orchestrateur multi-LLM
HP-03	Multi-utilisateur : le workflow suppose un seul développeur/PO	Pas de gestion de permissions, verrous, ou merge de `.gov-local.json`
HP-04	Rollback Jira : pas de mécanisme pour annuler une transition Jira incorrecte	Les transitions globales (In Progress tid 21, To Do tid 11) permettent un reset manuel
HP-05	Versioning des skills : les skills `.claude/commands/` ne sont pas versionnés (pas de header comme les prompts)	Versionnés par Git, pas par convention interne
HP-06	Monitoring/alerting : pas de système de surveillance du workflow en production	Dashboard manuel (`/morning`), pas de Prometheus/Grafana
HP-07	Gestion des secrets centralisée : les credentials sont dupliqués dans `jira-api.sh` et `CLAUDE.local.md`	Migration vers Vault seul identifiée mais non priorisée

Annexe A — Diagramme de dépendances entre composants¶

C21 (CONSTITUTIONAL)
  │
  ├──▶ C8 (constitutional-check)
  │
  ├──▶ C11 (skills) ──────▶ C1 (gov-workflow)
  │       │                       │
  │       ├──▶ C2 (gov-step) ◀────┘
  │       │       │
  │       │       ├──▶ C6 (assemble-prompt) ──▶ C13 (templates prompts)
  │       │       │       │
  │       │       │       └──▶ C9 (resolve-project/epic)
  │       │       │
  │       │       ├──▶ C7 (agents) ──▶ C15 (agent definitions)
  │       │       │
  │       │       ├──▶ C23 (opencode)
  │       │       │
  │       │       └──▶ C4 (state) ──▶ C5 (jira-api)
  │       │                │
  │       │                └──▶ C12 (FSM yaml)
  │       │
  │       ├──▶ C10 (check-docs)
  │       │
  │       ├──▶ C18 (learnings) ──▶ C24 (ollama)
  │       │
  │       └──▶ C17 (metrics)
  │
  └──▶ C25 (cohérence Prolog)

Annexe B — Matrice LLM par étape¶

Étape	Agent producteur	Agent reviewer (P1)	Agent confrontation (P2)	Température
0	Claude	—	—	Créatif (system prompt)
1	ChatGPT (balanced 0.4)	—	—	0.4
2	ChatGPT (balanced 0.4)	—	—	0.4
3	—	Claude (factual)	ChatGPT (factual 0.1)	0.1
4	Claude	—	—	Équilibré (system prompt)
5	—	ChatGPT (factual 0.1)	Claude (factual)	0.1
6a	Claude	—	—	Équilibré
6b	Claude multi-agents	—	—	Factuel (system prompt)
6c	Claude	—	—	Factuel
7	Claude (auto) + ChatGPT (reviews)	—	—	0.1
8	—	ChatGPT (factual 0.1)	Claude (factual)	0.1
9	Claude	—	—	Créatif
10	Claude	—	—	Créatif

Annexe C — Table des transitions Jira¶

TID	De	Vers	Événement déclencheur
4	To Do	BESOIN	Démarrage workflow
5	BESOIN	SPECIFICATION	Step 0 DONE
6	SPECIFICATION	GATE SPEC	Steps 1-2 DONE
7	GATE SPEC	PLAN	Gate 3 GO/RESERVE
8	GATE SPEC	NON_CONFORME SPEC	Gate 3 NON_CONFORME
18	GATE SPEC	ESCALADE SPEC	Gate 3 ESCALADE
15	PLAN	GATE PLAN	Step 4 DONE
16	GATE PLAN	IMPLEMENTATION	Gate 5 GO/RESERVE
17	GATE PLAN	NON_CONFORME PLAN	Gate 5 NON_CONFORME
19	GATE PLAN	ESCALADE PLAN	Gate 5 ESCALADE
9	IMPLEMENTATION	ACCEPTABILITE	Step 6 DONE
10	ACCEPTABILITE	GATE CLOSURE	Step 7 DONE
14	GATE CLOSURE	REX	Gate 8 GO/RESERVE
12	GATE CLOSURE	NON_CONFORME CLOSURE	Gate 8 NON_CONFORME
20	GATE CLOSURE	ESCALADE CLOSURE	Gate 8 ESCALADE
13	NON_CONFORME CLOSURE	ACCEPTABILITE	Correction terminée
31	REX	Done	Steps 9-10 DONE
11	*	To Do	Reset (global)
21	*	In Progress	Reprise (global)
22	ESCALADE SPEC	GATE SPEC	Décision PO
23	ESCALADE PLAN	GATE PLAN	Décision PO
24	ESCALADE CLOSURE	GATE CLOSURE	Décision PO
2	*	DONE (with anomaly)	Clôture avec anomalie (global)
3	*	REJECTED	Rejet (global)

Annexe D — Artefacts par étape¶

Étape	Artefact principal	Artefacts secondaires	Data-index YAML
0	`PD-XX-besoin.md`	—	`besoin.yaml` + `index.yaml`
1	`PD-XX-specification.md`	—	`specification.yaml`
2	`PD-XX-tests.md`	—	`tests.yaml`
3	—	`PD-XX-review-step3.md`, `PD-XX-confrontation-step3.md`, `PD-XX-dossier-conformite-step3.md`, `PD-XX-verdict-step3-v{I}.yaml`	`verdict-step3-v{I}.yaml`
4	`PD-XX-plan.md`	`PD-XX-code-contracts.yaml`	`plan.yaml`
5	—	`PD-XX-review-step5.md`, `PD-XX-confrontation-step5.md`, `PD-XX-dossier-conformite-step5.md`, `PD-XX-verdict-step5-v{I}.yaml`	`verdict-step5-v{I}.yaml`
6	—	`PD-XX-decomposition.md`, `PD-XX-agent-{agent}-{module}.md` (×N)	`decomposition.yaml`
7	`PD-XX-acceptability.md`	—	`acceptability.yaml`
8	—	`PD-XX-review-step8.md`, `PD-XX-confrontation-step8.md`, `PD-XX-dossier-conformite-step8.md`, `PD-XX-verdict-step8-v{I}.yaml`	`verdict-step8-v{I}.yaml`
9	`PD-XX-rex.md`	—	`rex.yaml` + `index.yaml` (workflow_state: DONE)
10	`PD-XX-retrospective.md`	—	—