GOV-SYSTEM — Spécification canonique contractuelle¶

Objet : Spécification exhaustive du système de gouvernance IA ProbatioVault, produite par reverse-engineering du code existant. Ce document suit le format standard des spécifications PD-XX (sections 1–10).

1. Objectif¶

Le système de gouvernance IA ProbatioVault orchestre un workflow en 11 étapes (0–10) qui encadre le cycle de vie complet d'une user story, de l'expression de besoin jusqu'à la rétrospective. Le système DOIT garantir :

• La séparation des pouvoirs entre agents producteurs et agents validateurs (aucun agent ne valide son propre travail).
• La traçabilité probatoire de chaque événement (état, transition, artefact, verdict) dans Jira et sur disque.
• L'application non négociable de quality gates mathématiques aux étapes de validation (gates 3, 5, 8).
• La capitalisation systématique des apprentissages pour améliorer le processus de manière continue.

Le workflow suit le principe : Les agents produisent. Claude orchestre. Le PMO juge. L'humain tranche.

2. Périmètre / Hors périmètre¶

Inclus¶

• Orchestration séquentielle des 11 étapes du workflow de gouvernance.
• Gestion d'état hybride : Jira comme source de vérité (19 statuts custom, 24 transitions) + données locales (.gov-local.json).
• Assemblage de prompts cache-first pour les LLM (Claude, ChatGPT, Ollama).
• Exécution multi-agents (step 6) avec décomposition, dispatch séquentiel et synthèse.
• Gates PMO (steps 3, 5, 8) : review croisée, confrontation, dossier de conformité, verdict YAML.
• Acceptabilité automatisée (step 7) : quality gates (lint, format, types, tests, Sonar) + reviews LLM.
• Capitalisation : métriques (metrics.jsonl), learnings (learnings.jsonl), dashboards, amélioration process.
• Vérification constitutionnelle automatisée (Articles I–VII).
• Revue documentaire pré-clôture (12/12 artefacts).
• Intégrations : Jira REST API, OpenCode (ChatGPT), Ollama (LLM local), GitLab CI/CD, HashiCorp Vault.

Exclu¶

• HP-01 : CI/CD du repo de gouvernance lui-même (pas de pipeline GitLab pour ia-governance).
• HP-02 : Tests automatisés du workflow (pas de test harness pour l'orchestrateur multi-LLM).
• HP-03 : Multi-utilisateur (un seul développeur/PO, pas de verrous concurrents).
• HP-04 : Monitoring/alerting du workflow en production (dashboard manuel uniquement).
• HP-05 : Gestion centralisée des secrets (credentials dupliqués entre jira-api.sh et CLAUDE.local.md).
• HP-06 : Rollback automatique de transitions Jira incorrectes (transitions globales manuelles uniquement).

3. Définitions¶

4. Invariants (non négociables)¶

5. Flux nominaux¶

Flux N1 — Workflow complet (happy path)¶

1. L'utilisateur invoque /gov PD-XX [projet].
2. Le système probe les capabilities disponibles (claude-p, opencode, ollama, vault).
3. Le système interroge Jira pour le statut courant de PD-XX.
4. Le système résout le projet cible et localise le dossier epic.
5. Le système initialise l'état : Jira (transition si nécessaire) + .gov-local.json (création si absent).
6. Le système affiche les règles constitutionnelles et l'état des 11 étapes.
7. Pour chaque étape non terminée (0 → 10) :
8. Le système assemble le prompt approprié (cache-first).
9. Le système exécute l'étape selon son type (Claude / ChatGPT / Gate / Multi-agent).
10. Le système détecte l'artefact produit.
11. Le système met à jour Jira (transition + commentaire) et .gov-local.json.
12. Le système génère le YAML data-index correspondant.
13. Le système logue l'événement dans la session.
14. Après l'étape 10, le système exécute la revue documentaire (12/12 artefacts).
15. Le système exécute le compounder (métriques, learnings, dashboards, améliorations process).
16. Le système transitionne Jira → Done (tid 31).

Flux N2 — Gate PMO (steps 3, 5, 8)¶

1. Le système assemble le prompt de review et l'envoie au reviewer P1.
2. P1 produit un document de review.
3. Le système assemble le prompt de confrontation et l'envoie au reviewer P2 (LLM différent de P1).
4. P2 produit un document de confrontation comparant les documents focaux avec la review P1.
5. Le système synthétise le dossier de conformité (écarts, scoring).
6. Le système exécute la vérification constitutionnelle automatisée.
7. Le verdict est produit avec scores individuels, moyenne, delta (si itération > 1), et verdict final.
8. Selon le verdict :
9. GO : transition vers l'étape suivante.
10. RESERVE : pause, validation humaine requise (Option A ou B).
11. NON_CONFORME : transition vers correction, iteration++.
12. ESCALADE : transition vers ESCALADE_*, workflow en pause.

Flux N3 — Multi-agents (step 6)¶

1. Phase 0 : création de la feature branch Git (feature/{story-id}-{slug}).
2. Phase 6a : Claude génère le manifest de décomposition (table CSV : agent, module, description, livrable, fichiers autorisés).
3. Phase 6b : pour chaque ligne du manifest, le système :
4. Assemble le prompt agent (bloc stable : spec + tests + plan + TOUS code-contracts ; bloc variable : identité agent + mission + contract du module).
5. Exécute l'agent (Claude auto via claude -p, ChatGPT auto via opencode run).
6. Sauvegarde le livrable.
7. Exécute npx tsc --noEmit (si applicable). Si erreur → correction avant agent suivant.
8. Commit intermédiaire sur la feature branch.
9. Met à jour la sous-étape dans .gov-local.json.
10. Phase 6c : Claude orchestre la synthèse finale, résout les conflits d'interface, écrit le code dans le projet.

Flux N4 — Acceptabilité (step 7)¶

1. Phase 1 : Quality gates automatisés (lint, format, TypeScript, tests, couverture ≥ 80%).
2. Phase 1.5 : Sonar Quality Gate local. Si ERROR → STOP.
3. Phase 2 : 3 reviews LLM parallèles (code, tests, sécurité). Injection des stubs connus et TODO tracés pour réduire les faux positifs.
4. Phase 3 : synthèse dans PD-XX-acceptability.md.

Flux N5 — Correction (NON_CONFORME)¶

1. Le verdict NON_CONFORME liste les écarts à corriger.
2. Le système transitionne Jira vers l'état de correction approprié (NON_CONFORME SPEC/PLAN/CLOSURE).
3. L'agent qui a produit le document original corrige (même LLM, même type).
4. Le step amont est relancé (step 7 pour Gate 8, step 4 pour Gate 5, step 1 pour Gate 3).
5. La gate est relancée (itération v2, v3).
6. Si 3 NON_CONFORME consécutifs → ESCALADE automatique (INV-GOV-02).

Flux N6 — ESCALADE¶

1. Le verdict ESCALADE ou le plafond 3 itérations transitionne Jira vers ESCALADE_SPEC/PLAN/CLOSURE.
2. Le workflow se met en pause (exit code 3).
3. Le PO examine la situation et prend une décision.
4. L'humain relance le workflow ou transitionne manuellement (tid 22/23/24 → retour gate).

Flux N7 — Reprise après interruption¶

1. L'utilisateur relance /gov PD-XX.
2. Le système interroge Jira pour le statut courant.
3. Le système lit .gov-local.json pour les données locales (iteration, substeps).
4. Le système détermine la prochaine étape non terminée et reprend le workflow.

Flux N8 — Compounder (post step 9)¶

1. Append métriques story dans data/metrics.jsonl.
2. Vérifier/compléter data/learnings.jsonl (extraction depuis REX + verdicts).
3. Régénérer les dashboards (dashboards/GOVERNANCE-DASHBOARD.md).
4. Appliquer les améliorations process issues du REX : haute priorité (immédiat), moyenne (fin step 9).
5. Si modification CLAUDE.md ou CONSTITUTIONAL.md → validation humaine obligatoire.
6. Mettre à jour la matrice de traçabilité (RTM).

6. Cas d'erreur¶

7. Critères d'acceptation (testables)¶

8. Scénarios de test (Given / When / Then)¶

ST-GOV-01 — Gate GO : scoring conforme¶

Given une gate 3 avec review P1 et confrontation P2
When tous les scores individuels sont ≥ 8.0/10
Then le verdict est "GO"
And Jira transitionne de GATE SPEC vers PLAN (tid 7)
And l'artefact PD-XX-verdict-step3-v1.yaml contient verdict: GO

ST-GOV-02 — Gate RESERVE : score moyen suffisant, un axe faible¶

Given une gate 5 avec score moyen = 7.5 et un axe à 7.0
When le verdict est calculé selon INV-GOV-01
Then le verdict est "RESERVE"
And le workflow se met en pause
And l'humain doit explicitement accepter (Option A ou B) avant continuation

ST-GOV-03 — Gate NON_CONFORME : score insuffisant¶

Given une gate 8 avec score moyen = 6.5
When le verdict est calculé selon INV-GOV-01
Then le verdict est "NON_CONFORME"
And Jira transitionne vers NON_CONFORME CLOSURE (tid 12)
And .gov-local.json iteration est incrémenté de 1

ST-GOV-04 — Plafond 3 itérations déclenche ESCALADE¶

Given une gate 3 avec iteration = 3 et verdict = NON_CONFORME
When le système vérifie INV-GOV-02
Then le système déclenche ESCALADE au lieu d'une 4e itération
And Jira transitionne vers ESCALADE SPEC (tid 18)
And le workflow s'arrête avec exit code 3

ST-GOV-05 — Stagnation delta=0 déclenche ESCALADE¶

Given une gate 5 v2 avec score moyen = 7.2
And gate 5 v1 avait score moyen = 7.2 (delta = 0)
When le système vérifie INV-GOV-03
Then le système déclenche ESCALADE immédiatement
And Jira transitionne vers ESCALADE PLAN (tid 19)
And un commentaire "stagnation delta=0" est posté sur Jira

ST-GOV-06 — Validation croisée Gate 3¶

Given une gate 3 déclenchée
When le review P1 est exécuté
Then P1 est Claude (factual)
And P2 (confrontation) est ChatGPT (factual, température 0.1)
And le dossier de conformité identifie les 2 LLM distincts

ST-GOV-07 — Multi-agents : vérification TS inter-agent¶

Given un step 6b avec 3 agents dans le manifest
When l'agent 1 est terminé et produit du code TypeScript
Then npx tsc --noEmit est exécuté
And si des erreurs TS sont détectées, l'agent 2 n'est pas lancé
And les erreurs sont corrigées avant de continuer

ST-GOV-08 — Acceptabilité : Sonar bloquant¶

Given un step 7 avec Phase 1 (QG auto) = PASS
When Sonar Quality Gate retourne ERROR
Then les reviews LLM (Phase 2) ne sont PAS exécutées
And le workflow s'arrête avec un message "Sonar QG ERROR"

ST-GOV-09 — Revue documentaire : document manquant¶

Given une story avec 11/12 artefacts (rex.yaml manquant)
When check-docs.sh est exécuté
Then le script retourne exit code 1
And la transition Jira → Done n'est pas exécutée
And le message liste "MISSING: rex.yaml"

ST-GOV-10 — Reprise après interruption¶

Given un workflow PD-42 interrompu au step 4 (Jira en PLAN)
When l'utilisateur relance /gov PD-42
Then le système interroge Jira, obtient statut PLAN
And get_current_step() retourne 4
And le workflow reprend au step 4 sans re-exécuter 0-3

ST-GOV-11 — ESCALADE : déblocage humain¶

Given un workflow PD-42 en ESCALADE PLAN (Jira)
When l'humain transitionne Jira de ESCALADE PLAN vers GATE PLAN (tid 23)
And l'utilisateur relance /gov PD-42
Then le système détecte statut GATE PLAN
And la gate 5 est relancée (itération v2)

ST-GOV-12 — Cohérence inter-EB : contradiction critique¶

Given un step 0 produit un besoin PD-XX-besoin.md
When le pipeline Prolog détecte une contradiction critique avec PD-YY
Then le step 1 n'est PAS démarré
And un rapport de contradiction est affiché
And l'utilisateur doit résoudre la contradiction avant de continuer

ST-GOV-13 — Cache-first : bloc stable identique entre agents¶

Given un step 6b avec agents A1 et A2
When les prompts de A1 et A2 sont assemblés
Then les N premières lignes (bloc stable) sont byte-identical
And seul le bloc variable (identité agent, tâche) diffère

ST-GOV-14 — Compounder : métriques et learnings¶

Given un step 9 terminé pour PD-XX
When le compounder s'exécute
Then metrics.jsonl contient une nouvelle ligne pour PD-XX
And learnings.jsonl contient les learnings extraits
And dashboards/GOVERNANCE-DASHBOARD.md est régénéré

ST-GOV-15 — RESERVE Option B : justification tracée¶

Given un verdict RESERVE avec 2 axes < 8.0
When l'humain choisit Option B (accepter les réserves)
Then l'humain fournit une justification écrite
And .gov-local.json contient accepted_reserves avec la justification
And un commentaire Jira documente la décision
And le workflow continue vers l'étape suivante

9. Hypothèses explicites¶

10. Points à clarifier¶

Références¶

• Epic : GOV-SYSTEM (meta — système de gouvernance lui-même)
• Repos concernés : ProbatioVault-ia-governance (principal), tous les projets ProbatioVault (cibles)
• Documents associés :
• CONSTITUTIONAL.md — Articles I-VII (racine du depot ia-governance)
• GOV-SYSTEM-plan.md — Plan d'implementation (reverse-engineered)
• data/fsm.yaml — Machine d'etats formelle avec mapping Jira
• CLAUDE.md — Instructions projet (racine du depot ia-governance)
• CLAUDE.local.md — Credentials (non commite)

Machine d'états¶

           ┌──────────┐
           │  To Do   │
           │ (10033)  │
           └────┬─────┘
                │ tid 4
           ┌────▼─────┐
           │  BESOIN   │
           │ (10137)  │
           └────┬─────┘
                │ tid 5
       ┌────────▼─────────┐
       │  SPECIFICATION    │  ◄──── tid 8 (NON_CONFORME)
       │  (10138)         │
       └────────┬─────────┘
                │ tid 6
       ┌────────▼─────────┐         ┌──────────────────┐
       │   GATE SPEC      │──tid 18──▶ ESCALADE SPEC   │
       │   (10139)        │         │  (10147)         │
       └──┬─────────┬─────┘         └────────┬─────────┘
          │         │                         │ tid 22
     tid 7│    tid 8│                         │
          │         │              ◄──────────┘
     ┌────▼─────┐   │
     │   PLAN   │   │
     │  (10145) │   │
     └────┬─────┘   │
          │ tid 15  │
     ┌────▼─────────┐         ┌──────────────────┐
     │  GATE PLAN   │──tid 19──▶ ESCALADE PLAN   │
     │  (10146)     │         │  (10148)         │
     └──┬─────┬─────┘         └────────┬─────────┘
        │     │                        │ tid 23
   tid 16   tid 17                     │
        │     │             ◄──────────┘
   ┌────▼──────────────┐
   │  IMPLEMENTATION   │
   │  (10140)          │
   └────────┬──────────┘
            │ tid 9
   ┌────────▼──────────┐
   │  ACCEPTABILITE    │ ◄──── tid 13 (depuis NON_CONFORME CLOSURE)
   │  (10141)          │
   └────────┬──────────┘
            │ tid 10
   ┌────────▼──────────┐         ┌──────────────────────┐
   │  GATE CLOSURE     │──tid 20──▶ ESCALADE CLOSURE    │
   │  (10142)          │         │  (10149)             │
   └──┬─────┬──────────┘         └────────┬─────────────┘
      │     │                             │ tid 24
 tid 14   tid 12                          │
      │     │                  ◄──────────┘
      │  ┌──▼───────────────────────┐
      │  │  NON_CONFORME CLOSURE    │
      │  │  (10143)                 │──── tid 13 ──▶ ACCEPTABILITE
      │  └──────────────────────────┘
      │
 ┌────▼─────┐
 │   REX    │
 │  (10144) │
 └────┬─────┘
      │ tid 24
 ┌────▼──────────────┐
 │  RETROSPECTIVE    │
 │  (10150)          │
 └────┬──────────────┘
      │ tid 31
 ┌────▼─────┐
 │   Done   │
 │  (10035) │
 └──────────┘

Transitions globales : tid 11 (→ To Do), tid 21 (→ In Progress), tid 2 (→ DONE with anomaly), tid 3 (→ REJECTED).