disput/PROTOCOL.md

Protocole disput — v0 (brouillon)

Ce document est normatif. Il s'applique aux agents comme à l'outil. On peut le pratiquer sans l'outil : chaque agent lit ce fichier, puis l'état de .disput/, et joue son tour.

Les mots en MAJUSCULES (DOIT, NE DOIT PAS, PEUT) ont valeur de règle.

---

1. Concepts

Concept	Définition
Participant	Un client IA (adaptateur + modèle) ou l'humain. Identifié par un nom court : claude, vibe, user.
Rôle	Une fonction dans le dialogue, définie dans disput.toml : responsabilités, droits, déclencheurs. Un participant PEUT tenir plusieurs rôles.
Tour	Une intervention d'un participant dans un rôle. Elle produit un fichier de tour et au moins un commit.
Item	Une objection, une question ou une proposition, adressée à un participant ou à un rôle. Elle a un cycle de vie (§5).
Backlog	La liste ordonnée des tâches du projet (.disput/backlog.md).
Décision	Un choix réservé à l'humain. Le dialogue s'arrête jusqu'à ce qu'il tranche.

2. Arborescence dans un projet

.disput/
  disput.toml            # participants, rôles, déclencheurs, contrôles, garde-fous
  backlog.md             # backlog unique du projet
  turns/
    0001-claude-implementer.md
    0002-vibe-reviewer.md
    ...
  archive/               # chantiers clos, déplacés verbatim (optionnel)

Fichiers locaux, jamais commités : .disput/logs/, .disput/run.lock, .disput/last-run.md.

3. Règles générales

1. Un tour = un fichier de tour + au moins un commit. Pas de fichier sans commit, pas de code sans tour qui l'explique.
2. Les fichiers de tour sont immuables. Une fois commité, un fichier de tour NE DOIT PLUS JAMAIS être modifié, ni par son auteur ni par un autre. Pour corriger, on écrit un nouveau tour.
3. Réponse point par point. Chaque item adressé à un participant DOIT recevoir une réponse explicite de sa part, à son prochain tour, avant tout autre travail. Les réponses groupées sont interdites.
4. Vérifier, pas croire. Un reviewer DOIT ré-exécuter ce qu'il peut ré-exécuter (tests, scripts, commandes citées) au lieu de faire confiance au récit de l'auteur.
5. Toute décision est consignée dans un tour, avec sa justification. Le code doit refléter les tours.
6. Pas de réécriture d'historique, pas de force-push, pas de push pendant un tour, sauf décision user consignée qui l'autorise explicitement.
7. Diversité des regards. Le reviewer d'un tour DOIT être un autre participant que l'auteur de ce tour. On DEVRAIT choisir un autre fournisseur de modèle.
8. Les règles propres au projet (prod, secrets, dépôt public…) vivent dans disput.toml ([guards], [[checks]]) et dans le fichier d'instructions du projet. Elles s'ajoutent à celles-ci et n'en retirent aucune.

4. Fichier de tour

Nom : NNNN-<participant>-<role>.md. NNNN est le numéro du tour, sur 4 chiffres et strictement croissant.

En-tête TOML entre +++ (sans dépendance : tomllib) :

+++
turn = 17
participant = "vibe"
role = "implementer"
base = "a1b2c3d"          # HEAD au début du tour
status = "CONTINUE"       # CONTINUE | USER | DONE
+++

# Tour 17 — vibe, implementer : <titre court>

## Réponses
- [I-0016-1] ACCEPTÉ : <ce qui est fait, ou va l'être>
- [I-0016-2] REJETÉ : <raison technique>

## Travail
<ce qui a été fait, et pourquoi>

## Vérifications
<commandes exécutées et résultats, sans sortie brute sensible>

## Items
- [I-0017-1] → @claude : <question ou objection>
- [I-0017-2] → role:security : <demande d'audit>

## Décision requise          (seulement si status = "USER")
<question fermée, options numérotées, recommandation>

• Sections Réponses et Items : une ligne par item, avec l'identifiant entre crochets en tête. Ce format sert au parsing et DOIT être respecté à la lettre.
• Identifiant d'item : I-<tour sur 4 chiffres>-<n>, attribué par son auteur.
• Destinataire : @<participant> ou role:<rôle>.

5. Cycle de vie d'un item

            ┌─ ACCEPTÉ ── CORRIGÉ ─┬─ CLOS
OUVERT ─────┤  (destinataire)      └─ ROUVERT ─→ (retour à OUVERT)
 (auteur)   └─ REJETÉ ─────────────┬─ CLOS
               (destinataire)      └─ ESCALADÉ ─→ role:arbiter ou @user
                                      (auteur)

• ACCEPTÉ, REJETÉ et CORRIGÉ (<sha>) sont posés par le destinataire.
• CLOS, ROUVERT et ESCALADÉ sont posés par l'auteur de l'item, qui vérifie lui-même la correction (règle 4).
• L'état d'un item n'est stocké nulle part : il se déduit de la suite des fichiers de tour. C'est pour ça qu'ils sont immuables.
• Le parseur DEVRAIT accepter les mots-clés avec ou sans accent.

6. Rôles et déclencheurs

Un rôle se déclare dans disput.toml :

[[roles]]
name = "reviewer"
writes_code = false            # ne peut modifier que .disput/
triggers = ["code_changed"]
brief = "Review sévère du diff : bugs, sécurité, hypothèses non validées, écart code/tours."

Déclencheurs v0 :

Déclencheur	Le rôle doit jouer quand…
items_pending	des items lui sont adressés et attendent une réponse (implicite pour tous les rôles)
code_changed	le dernier tour a modifié des fichiers hors de .disput/
paths:<glob>,<glob>	le dernier tour a touché un de ces chemins
backlog	aucun item en attente, et le backlog a une tâche ouverte, non [USER]

Une affectation associe un rôle aux participants qui peuvent le tenir :

[[participants]]
name = "claude"
adapter = "claude"
roles = ["implementer", "reviewer", "security"]

7. Ordonnancement : qui joue ensuite

Après chaque tour, on choisit le prochain (participant, rôle) dans l'ordre de priorité suivant :

1. Si le dernier tour a status = "USER" : arrêt, on attend @user.
2. Items en attente. S'il en existe, le plus ancien item non résolu donne la main à celui qui doit agir : le destinataire pour répondre ou corriger, l'auteur pour clore, rouvrir ou escalader.
3. Déclencheurs. Sinon, si le dernier tour a changé du code, chaque rôle déclenché (code_changed, paths:) qui n'a pas encore joué sur ce diff passe, dans l'ordre de disput.toml, tenu par un participant ≠ l'auteur du code (règle 7).
4. Backlog. Sinon, le rôle implementer prend la tâche ouverte la plus haute, non [USER]. S'il y a plusieurs participants éligibles, on tourne entre eux (celui qui a implémenté le moins récemment).
5. Sinon : DONE.

Pour un même rôle, on choisit le participant éligible qui a joué le moins récemment. Anti ping-pong : si deux tours de review successifs sur le même diff n'ouvrent aucun item et ne posent aucun REJETÉ, le dialogue sur ce diff est clos.

8. Invariants vérifiés après chaque tour

Si un invariant échoue, l'outil s'arrête et le signale à @user. Sans l'outil, le reviewer suivant DOIT les vérifier lui-même.

1. Au moins un nouveau commit, et un arbre de travail propre.
2. L'ancien HEAD est un ancêtre du nouveau : pas de réécriture.
3. Aucune ref distante n'a bougé : pas de push.
4. Un seul fichier de tour ajouté, avec le bon numéro et un en-tête valide. Aucun fichier de tour existant n'a été modifié.
5. Un rôle writes_code = false n'a modifié que .disput/.
6. Chaque item adressé à ce participant et en attente a reçu une réponse dans ce tour (règle 3).
7. Les contrôles du projet ([[checks]]) respectent leur politique :
   • must_pass : le contrôle doit réussir ;
   • no_regression : s'il réussissait avant le tour, il doit encore réussir après.

9. Garde-fous ([guards])

• env : variables imposées à l'agent pendant son tour, par exemple DRY_RUN=true.
• deny : motifs de commandes interdites (push, réécriture, passage en prod…). L'outil les applique dans chaque adaptateur : les deny et hooks de Claude Code, l'agent et le hook pre_tool de Vibe. Plus tard, ils seront appliqués de façon centralisée via ACP.

10. L'humain

user est un participant comme les autres, avec le rôle decider. Il répond à un tour status = "USER" par son propre tour (NNNN-user-decider.md). Sans l'outil, il écrit ce fichier à la main. Avec l'outil, il passe par disput decide "…", qui l'écrit et le commite. Ses décisions PEUVENT lever une règle du §3, explicitement et de façon bornée.

11. Pratique manuelle (avant que l'outil existe)

Quand l'agent reçoit « à toi » :

1. lire ce fichier, disput.toml, backlog.md et les fichiers de tour depuis le dernier tour de ce participant (ou tous, s'il n'en a aucun) ;
2. appliquer le §7 pour vérifier que c'est bien son tour, et dans quel rôle. Si ce n'est pas son tour, le dire et s'arrêter ;
3. vérifier les invariants du §8 sur le tour précédent ;
4. jouer le tour, écrire le fichier de tour, commiter ;
5. résumer à l'humain : ce qui est fait, qui joue ensuite, et la décision attendue s'il y en a une.