PD-293 — Rapport de confrontation (Étape 5 — Gate Plan)¶

Ce rapport est produit par l'orchestrateur Claude avant la gate PMO 5. Il confronte les documents produits pour identifier convergences, divergences et zones d'ombre.

1. Sources confrontées¶

2. Convergences¶

• Machine d'états : Les 8 états contractuels (STARTING, RUNNING, ESCALADED, PAUSED, DONE, ABORTED, CRASHED, START_FAILED) sont identiques dans les 4 documents. Les transitions autorisées et les terminaux sont cohérents.
• 14 invariants : Les INV-293-01 à INV-293-14 sont repris sans altération de sens entre spec, tests et plan. Chaque invariant a au moins un test dédié (matrice de couverture complète dans le document tests).
• 12 critères d'acceptation : CA-01 à CA-12 sont couverts par des tests dans le document tests et mappés à des mécanismes dans le plan.
• Limite 5 Ringbearers : Unanime (spec INV-293-04, tests TC-NOM-02/TC-ERR-01, plan §2.1 garde 1, contracts count_active_stories).
• FIFO escalades : Traitement ordonné par created_at sans remplacement, cohérent dans les 4 documents (INV-293-13).
• Idempotence : Mécanisme key + payload_hash avec 3 résultats (NEW/REPLAY/CONFLICT), TTL 24h — cohérent entre spec §5.1 et plan §3.
• Isolation inter-story : Process claude -p séparé par Ringbearer, aucun partage — convergent.
• Broker comme unique canal : INV-293-02 respecté dans le plan (C3 unique point de contact) et les contracts.
• Reconnexion exponentielle bornée : 1s, 2s, 4s, 8s, 10s max — identique spec §5.3 et plan.
• Crash detection ≤ 2 cycles : INV-293-08 implémenté via missed_polls dans le plan, testé par TC-NOM-06/TC-ERR-07.
• Exclusion ESCALADE_PENDING/ESCALADE_EXPIRED en v1 : Unanime (spec §4.1, plan §10, contracts forbidden).
• Stack Bash/jq/YAML-JSON : Plan et contracts cohérents avec la stack du repo ia-governance.

3. Divergences¶

Les conflits ne doivent JAMAIS être lissés. Chaque divergence est rendue visible.

DIV-01 : Noms de fichiers des modules — incohérence entre plan et code contracts standalone

• Plan (§1, table composants) : scripts/lib/lord-state-machine.sh
• Code contracts standalone : scripts/lib/lord-fsm.sh
• Plan (§1) : scripts/lib/lord-persistence.sh
• Code contracts standalone : scripts/lib/lord-state.sh
• Impact : Ambiguïté pour les agents step 6b — quel nom de fichier créer ? Risque de fichiers dupliqués ou d'imports cassés.

DIV-02 : Décomposition modulaire — 7 composants (plan) vs 9 modules (code contracts standalone)

• Plan : 7 composants (C1-C7) avec C4=persistence (regroupe état+logs+FIFO+idempotency) et C5=orchestrator (regroupe commandes+supervision+réconciliation).
• Code contracts standalone : 9 modules — state-store + logger (C4 éclaté), supervisor + command-router (C5 éclaté), plus logger comme module autonome.
• Code contracts intégrés au plan : 7 modules cohérents avec le découpage C1-C7.
• Impact : Deux versions de code-contracts en conflit. Les agents recevront des contrats contradictoires sur la granularité des fichiers et les responsabilités.

DIV-03 : Validation timestamp — trois positions différentes

• Spec §5.1 : horodatage UTC parseable (suffixe Z ou offset UTC) — accepte Z ET les offsets UTC.
• Plan H-TECH-08 : strictement Z uniquement. Tout offset non-zero est rejeté.
• Code contracts standalone (validator) : seuls Z et +00:00 acceptés — accepte Z ET +00:00.
• Code contracts intégrés au plan (validator) : seul le suffixe Z est accepté (décision H-TECH-08).
• Impact : Le validateur C2 implémentera une regex différente selon le contrat suivi. Si +00:00 est rejeté alors que la spec l'autorise, des messages valides seront perdus.

DIV-04 : Valeur sentinelle peer_id en état STARTING

• Plan H-TECH-09 : "pending-{story_id}" (ex: "pending-PD-42").
• Code contracts standalone (state-store) : "__pending__" (valeur fixe).
• Impact : Le schema §5.4 impose peer_id required minLength:1. Les deux sont conformes, mais les tests et la réconciliation (INV-293-11) doivent connaître la convention exacte pour ne pas signaler des faux écarts.

DIV-05 : Localisation du fichier .gov-lord-state.json

• Plan §7 (sécurité) : racine du repo ia-governance, ajouté au .gitignore. Citation : "c'est un état runtime global, pas un artefact de story".
• Code contracts standalone (state-store, invariants) : dossier epic (docs/epics/tooling/PD-293-one-ring-orchestration/).
• Plan §9.4 (décision spec-review) : confirme racine du repo.
• Code contracts intégrés au plan (persistence) : confirme racine du repo.
• Impact : Contradiction directe entre les deux versions de code-contracts. L'agent agent-state recevra une instruction contradictoire.

DIV-06 : Convention message_type pour les rejets de commandes Sovereign dans les logs §6.1

• Plan §6 (gestion erreurs) : message_type = nom de la commande en MAJUSCULES ("START", "RESPOND", "PAUSE", etc.).
• Code contracts standalone (logger) : message_type = 'COMMAND' (valeur unique pour toutes les commandes).
• Code contracts intégrés au plan (validator) : message_type = nom de la commande en majuscules.
• Impact : Les logs de rejet auront un format différent selon le contrat suivi. Affecte la testabilité de TC-ERR-03 et l'auditabilité.

DIV-07 : Préfixage des interfaces — convention de nommage

• Plan : toutes les interfaces sont préfixées lord_ (ex: lord_transition(), lord_validate_story_id(), lord_broker_list_peers()).
• Code contracts standalone : interfaces non préfixées pour certains modules (ex: transition(), validate_story_id(), broker_list_peers()).
• Code contracts intégrés au plan : préfixe lord_ systématique.
• Impact : Incohérence dans les appels entre modules. Faible individuellement, mais cumulé sur ~30 interfaces, source de bugs d'intégration.

DIV-08 : Test TC-NOM-14 — ajouté dans le plan mais absent du document tests

• Plan §5 : TC-NOM-14 (ajouté) couvre CA-02 (démarrage nominal complet jusqu'à RUNNING). Détaillé avec mécanismes et observables.
• Document tests : TC-NOM-14 n'existe pas. La matrice de couverture mappe CA-02 à TC-NOM-08 (idempotence).
• Spec §8 : TC-NOM-14 absent des scénarios Given/When/Then.
• Impact : CA-02 n'a pas de test nominal dédié dans le document tests. Le plan identifie cette lacune et y remédie, mais le document de tests officiel ne l'intègre pas.

DIV-09 : Garde supplémentaire "story déjà active" dans le flux start

• Spec §5.1 / INV-293-14 : 3 gardes pour start — quota → doublon idempotence → validation format complète.
• Plan §2.1 : 4 gardes pour start — quota → idempotence → format → story déjà active (doublon story).
• Impact : Le plan ajoute une 4ème garde non mentionnée dans l'invariant INV-293-14. Cette garde est nécessaire (couverte par ERR-293-02) mais son positionnement après le format n'est pas contractualisé dans la spec.

DIV-10 : Interface lord_count_open_escalades() dans le plan mais absente des code contracts standalone

• Plan C4 interfaces : lord_count_open_escalades(story_id) -> integer — utilisée pour la logique multi-escalade (transition ESCALADED→RUNNING uniquement quand toutes les OPEN sont traitées).
• Code contracts standalone (state-store) : cette interface n'existe pas.
• Impact : La logique multi-escalade du plan §2.2 nécessite cette interface. Sans elle, l'invariant INV-293-13 est implémentable mais la transition retour ESCALADED→RUNNING manque de précision contractuelle.

DIV-11 : Interface validate_summary_text() — présente dans le plan mais absente des contracts standalone

• Plan C2 interfaces : lord_validate_summary_text(value) -> OK | REJECTED.
• Spec §5.1 : summary_text est un champ du modèle canonique avec regex ^[^\p{C}]{1,512}$.
• Code contracts standalone (validator) : pas de validate_summary_text() dans la liste des interfaces.
• Impact : Un champ du modèle canonique ne serait pas validé. Faible en pratique (le Ringbearer émet les summary_text), mais c'est une violation de INV-293-05 ("tout message doit être validé selon §5.1").

4. Zones d'ombre¶

ZO-01 : Deux jeux de code contracts coexistent. Le plan inclut un code-contracts.yaml intégré (cohérent avec le plan), ET un document standalone code-contracts.yaml séparé avec des divergences significatives (DIV-01 à DIV-07, DIV-10, DIV-11). Quel document fait foi pour les agents step 6b ? Sans clarification, les agents recevront des contrats contradictoires.

ZO-02 : Mécanisme exact d'interaction avec claude-peers-mcp. Le plan mentionne C3 comme couche d'abstraction, mais le risque R2 (§9.1) signale que le Ringbearer "ne produit pas de STATUS_UPDATE (protocole non natif dans /gov)". La spec H-293-04 pose la même hypothèse. Aucun des 4 documents ne décrit comment le Ringbearer émet des messages au broker. Le workflow /gov existant ne connaît pas claude-peers-mcp. Si cette hypothèse est fausse, le système entier est bloqué (STARTING→START_FAILED systématique).

ZO-03 : Supervision loop et traitement de commandes en parallèle. Le plan §2.4 décrit une boucle infinie lord_supervision_loop(). Le plan §9.3 mentionne le risque de contention (flock). Mais aucun document ne décrit comment les commandes CLI /gov-lord sont reçues pendant que la supervision loop tourne. Est-ce un seul process Bash qui alterne supervision et commandes ? Deux process avec lock partagé ? Le skill Claude Code interrompt-il la boucle ?

ZO-04 : Test E2E TC-NR-01 — le plan et les tests le déclarent obligatoire (baseline /gov standalone vs orchestré), mais aucun document ne décrit la procédure concrète pour exécuter une story complète /gov dans un contexte de test contrôlé. Durée estimée ? Story de test ? Mock des gates ?

ZO-05 : Purge idempotency_cache au redémarrage. La spec Q-293-05 pose la question. Le plan mentionne une purge opportuniste (§2.4 étape 6) et le contrat standalone mentionne purge_expired_idempotency(). Mais la politique au redémarrage du One Ring n'est pas tranchée : purge complète ? Conservation ? Impact sur la forensique si purge ?

ZO-06 : Format d'export probatoire TC-NOM-04. Le test exige un "export probatoire" des 100 mesures SLA P95. Aucun document ne définit le format exact de cet export (CSV ? JSONL ? champs ?) ni sa localisation.

ZO-07 : validate_message(json_payload) dans contracts standalone — interface composite qui valide un message complet. Absente du plan. Le plan valide champ par champ dans C5. Si l'agent-validator implémente cette interface, il crée une dépendance non prévue par l'orchestrateur C5.

5. Recommandation¶

• Procéder — convergence confirmée, aucun conflit bloquant
• Rework nécessaire — divergences à résoudre avant de continuer
• Escalade — décision humaine requise sur un point structurant

Justification¶

2 divergences bloquantes : - DIV-02 (deux décompositions modulaires incompatibles) : Les agents step 6b recevront des contrats contradictoires sur la structure des fichiers. L'un des deux jeux de code-contracts doit être retiré ou aligné. - ZO-01 (coexistence de deux code-contracts) : Conséquence directe de DIV-02. Le document faisant foi doit être désigné explicitement.

3 divergences majeures : - DIV-03 (timestamp Z vs Z+offset) : Affecte directement le validateur et les tests négatifs. - DIV-04 (sentinelle peer_id) : Affecte la réconciliation et les tests. - DIV-05 (localisation state file) : Contradiction directe entre les deux contracts.

1 zone d'ombre structurante : - ZO-02 (émission messages par Ringbearer) : Si le Ringbearer ne peut pas émettre de STATUS_UPDATE via le broker, le système est non fonctionnel. Le risque R2 du plan identifie le problème mais ne le résout pas.