Piloter tâches et arbitrages depuis ton agent

Deux types de travail, un seul outil de création

Une tâche OrgGen est soit une tâche ORDINAIRE (un travail confié, avec une échéance possible), soit un ARBITRAGE (une question posée avec des réponses pré-définies, que quelqu'un doit trancher). Les deux se créent par le même outil, `create_tasks` — un arbitrage se distingue par un champ `arbitrage: { question, options }` supplémentaire.

create_tasks({
  title: "Quelle stratégie de refacturation entre filiales ?",
  cellId: "filiale-tech",
  arbitrage: {
    question: "Refacturation au coût réel ou au forfait mensuel ?",
    options: [
      { id: "cout-reel", label: "Au coût réel, mesuré chaque mois" },
      { id: "forfait", label: "Forfait mensuel fixe" },
    ],
  },
})

L'agent peut aussi proposer jusqu'à deux options recommandées, chacune avec sa justification (`recommended: { justification }`) — une aide à la décision, jamais une décision prise à l'avance.

Le cycle : qui a le droit de poser quelle étape

Un arbitrage traverse jusqu'à six étapes, et chacune appartient à un camp précis — jamais l'un à la place de l'autre.

Le trajet normal est `propose → arbitre → en_cours → clos`. Si l'humain conteste au lieu d'arbitrer, l'agent reformule la question (`repropose`) et le cycle repart de `propose`. Rien ne force un aller simple : une question mal posée se corrige sans perdre l'historique.

Le verrou : deux vocabulaires qui ne se rencontrent jamais

`validate`, `choose` et `contest` — les trois verbes qui font AVANCER un arbitrage vers une décision — n'existent, dans le code, que dans un type accessible à l'interface humaine. L'agent appelle une fonction DIFFÉRENTE, qui n'accepte qu'un second vocabulaire : `start`, `close`, `repropose`, `moot`, et quatre autres verbes décrits plus bas (`clarify`, `record_external_decision`, `yield`, `declineReconsider`).

update_task({ taskId: "tk-refacturation", arbitrageAction: { type: "start" } })

update_task({
  taskId: "tk-refacturation",
  arbitrageAction: { type: "close", summary: "Migré vers le coût réel, effectif ce mois." },
})

Il ne s'agit pas d'une règle qu'un développeur pourrait oublier d'appliquer un jour : les deux vocabulaires sont deux unions Zod disjointes, consommées par deux fonctions distinctes. Passer `type: "choose"` à la fonction agent est une erreur de TYPE — le code ne compile pas. Le verrou tient à la compilation, pas à la discipline de qui l'a écrit.

Le cinquième verbe : répondre à « il me faut plus d'explications »

Un humain n'est pas toujours prêt à trancher : le panneau lui offre « Il me faut plus d'explications ». La question reste à `propose` — aucune étape neuve — mais l'arbitrage porte alors un signal que l'agent relève en un appel, `list_tasks({ awaitingClarification: true })`. `clarify` y répond : il pose l'explication, lève le signal, et ne change pas d'étape — l'humain tranche ensuite.

update_task({
  taskId: "tk-refacturation",
  arbitrageAction: {
    type: "clarify",
    explanation: "Le coût réel suit l'activité mais exige un suivi mensuel ; le forfait est simple mais fige un écart.",
  },
})

Le sixième verbe : une décision déjà prise ailleurs

Le cycle formel suppose que la question soit tranchée VIA le panneau — quelqu'un clique une option. Mais une décision se prend parfois en conversation, avant même que l'agent ait ouvert un panneau d'arbitrage. `record_external_decision` couvre exactement ce cas : il clôt un arbitrage directement depuis `propose`, sans passer par `arbitre`/`en_cours`, à condition de citer la preuve.

update_task({
  taskId: "tk-refacturation",
  arbitrageAction: {
    type: "record_external_decision",
    verbatim: "On part au coût réel, Marc l'a validé en réunion ce matin.",
    source: "Réunion produit du 12/09",
    decidedAt: "2026-09-12",
  },
})

Ce que ce verbe ne fait PAS : il ne marque jamais l'arbitrage comme « validé via le panneau » (le champ `decision` réservé à ce mécanisme reste intact). La preuve rapportée par l'agent et une validation formelle humaine restent deux faits distincts, pour toujours, dans l'historique de la tâche. Il est aussi REFUSÉ sur un arbitrage que l'humain a rouvert (`decisionHistory` non vide) : la décision retirée se remplace par un geste du panneau.

Quand l'humain revient sur sa décision : céder ou poursuivre

Un humain peut rouvrir une décision tant qu'aucune trace d'exécution n'existe, la réviser (un NOUVEL arbitrage remplace l'ancien, `revises` / `supersededBy`), ou — pendant ton travail — te DEMANDER DE RECONSIDÉRER. Les deux premiers gestes sont réservés au site : tu les vois dans l'arbitrage (`decisionHistory`, `supersededBy`), tu ne les poses pas. La demande de reconsidération apparaît dans `reconsider` (`status: "requested"`, `reason`, `addressedTo` : ta clé, ou `null` = à tout agent du projet). Tu y réponds, par l'un des deux verbes, et SEULEMENT si elle t'est adressée.

update_task({
  taskId: "tk-refacturation",
  arbitrageAction: { type: "yield", workSummary: "Branche migration-cout-reel poussée, 3 tests verts, reste la doc." },
})

update_task({
  taskId: "tk-refacturation",
  arbitrageAction: { type: "declineReconsider", justification: "Livré à 90 % ; reprendre coûterait plus que finir." },
})