Signaux Agent

Emettre des signaux structurés depuis un desk vers l'opérateur ou d'autres desks.

Quand les utiliser

• Un desk a besoin de l'attention de l'opérateur (hands-up, blocked)
• Le travail est terminé et prêt pour révision (done)
• Progression significative qui vaut la peine d'être notée (checkpoint)
• Deux desks sont en désaccord et ne peuvent pas le résoudre (hands-up)
• Le TA rend compte de la qualité de coordination (partnership)

Types de signaux

hands-up

Deux desks sont en désaccord et ne peuvent pas le résoudre par rapport aux faits externes. C'est le système qui fonctionne — l'opérateur lit où les desks divergent, non pas où ils affichent de la confiance.

blocked

Un desk ne peut pas continuer sans apport — accès manquant, périmètre ambigu, besoin d'une décision que seul l'opérateur peut prendre.

done

Le travail est terminé et prêt pour révision. Les artefacts sont sur le bench.

checkpoint

Progression significative que l'opérateur devrait connaître, mais le travail continue. Ni bloqué, ni terminé — juste un marqueur.

partnership

Utilisé par le TA (coordinateur de salle) pour rendre compte de la qualité de coordination. Les scores d'auto-évaluation reflètent la coordination, non la précision du code :

• intent — a compris ce que l'opérateur avait besoin
• confidence — le bon travail a été assigné aux bons desks
• accuracy — le travail assigné a produit le bon résultat
• completeness — rien n'est tombé à travers les mailles

Comment émettre

1. Écrivez un fichier signal JSON dans .signals/

C'est la sortie principale — c'est ce que le dashboard lit. Créez desks/<desk-name>/.signals/<timestamp>.json :

{
  "signal_type": "execution",
  "subtype": "checkpoint",
  "timestamp": "2026-07-19T21:30:00Z",
  "run_id": "<optional; set to pair this with an outcome signal>",
  "agent_name": "<desk-name>",
  "self_assessment": {
    "intent": 4,
    "confidence": 5,
    "accuracy": 4,
    "completeness": 3
  },
  "patterns": {
    "what_worked": "description of what went well",
    "what_was_hard": "description of challenges",
    "skill_gap": "areas for improvement"
  },
  "escalation": {
    "reason": null,
    "blocked_on": null,
    "recommendation": null
  }
}

Correspondance des types de signaux

Le champ subtype préserve l'état spécifique du signal pour les consommateurs du dashboard. signal_type contrôle la priorité de tri (escalation → premier).

Note : L'extension canvas signals-dashboard lit subtype quand il est présent et se rabat sur signal_type pour l'affichage. Si vous consommez des signaux dans votre propre outil, préférez subtype pour l'état spécifique.

Ordonnancement : incluez un timestamp (ISO 8601 UTC). Le dashboard trie les signaux par ordre chronologique et se rabat sur le mtime du fichier seulement quand il est absent — un git clone/checkout réinitialise les mtimes, donc mtime seul n'est pas une horloge fiable.

2. Notez le signal dans le journal

Ajoutez aussi une courte marque au journal du desk pour la persistance :

## <date> — [signal:<type>] <summary>
- <key details>

La note du journal est la trace. Le fichier JSON est le signal lisible par machine.

Signaux de résultat (calibration)

Le signals-dashboard peut associer l'auto-évaluation d'un desk avec un résultat — une évaluation indépendante du résultat réalisé — et afficher l'écart d'honnêteté (à quel point la confiance du desk était éloignée de la qualité livrée). Les signaux de résultat sont optionnels et sont généralement émis par un relecteur/évaluateur, non par le desk lui-même.

Écrivez-les dans le même répertoire .signals/ :

{
  "signal_type": "outcome",
  "run_id": "<same run_id as the signal it rates>",
  "agent_name": "<reviewer name>",
  "quality_rating": 4,
  "effort_to_merge": "minimal",
  "issues_found": ["optional short strings"],
  "timestamp": "2026-07-19T22:00:00Z"
}

• run_id met en corrélation un résultat avec le signal d'exécution/partnership qu'il évalue — fixez le même run_id sur les deux. S'il est absent, le dashboard se rabat sur le résultat le plus proche émis peu après le dernier signal.
• quality_rating (0–5) est la qualité réalisée ; le dashboard la compare à la confidence auto-évaluée du desk pour calculer l' écart d'honnêteté.
• effort_to_merge — "minimal", "moderate", ou "significant".
• issues_found — tableau optionnel de courtes chaînes.

Principes

• Les signaux sont structurés, non bavards. Brefs, factuels, actionnables.
• hands-up n'est pas un échec — c'est le signal le plus précieux. Cela signifie que le système a détecté quelque chose qu'un seul cadre aurait manqué.
• N'émettez pas pour la progression de routine. Les signaux sont pour les changements d'état qui affectent la salle, pas des mises à jour de statut.
• blocked signifie vraiment bloqué — non pas « je préférerais un apport ». Si vous pouvez continuer avec une valeur par défaut raisonnable, continuez et notez-le.
• Les scores d'auto-évaluation doivent être honnêtes, non optimistes. Un 3/5 c'est bien. Un 5/5 sur tout est suspect.