tour 0001 (claude, implementer) : fondation — README, PROTOCOL v0, config, backlog B-1..B-13
Disput-Turn: 0001 Disput-Participant: claude Disput-Role: implementer Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5.5
+228
@@ -0,0 +1,228 @@
|
||||
# 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`) :
|
||||
|
||||
```markdown
|
||||
+++
|
||||
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` :
|
||||
|
||||
```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 :
|
||||
|
||||
```toml
|
||||
[[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.
|
||||
Reference in New Issue
Block a user