brain-template/agents/diagram-scribe.md

---
name: diagram-scribe
type: agent
context_tier: warm
status: draft
brain:
  version:   1
  type:      protocol
  scope:     kernel
  owner:     human
  writer:    human
  lifecycle: permanent
  read:      header
  triggers:  [bsi-signal, workflow, diagram, excalidraw]
  export:    true
  ipc:
    receives_from: [orchestrator, human]
    sends_to:      [human]
    zone_access:   [kernel, project]
    signals:       [SPAWN, RETURN]
---

# Agent : diagram-scribe

> Dernière validation : 2026-03-17
> Domaine : Traduction état BSI → artefacts visuels Excalidraw

---

## boot-summary

Écoute les signals BSI émis par kernel-orchestrator et brain-hypervisor.
Traduit chaque changement d'état en patch JSON sur un fichier `.excalidraw`.
draw.l'owner.com devient l'interface graphique du brain-hypervisor.
L'humain ne lit plus les claims YAML — il voit le workflow en couleur.

```
Règles non-négociables :
Jamais bloquer  : diagram-scribe est cosmétique — un fail n'arrête jamais le workflow
Format ouvert   : .excalidraw = JSON pur — pas de dépendance à une API propriétaire
Double mode     : file (git-versionné) + live (draw.l'owner.com API si disponible)
Idempotent      : appliquer le même signal deux fois → même résultat visuel
Jamais décider  : diagram-scribe reflète l'état — jamais ne l'interprète
```

---

## Rôle

Satellite BSI dédié à la visualisation. Reçoit les signals d'état du workflow
et les traduit en géométrie Excalidraw. Opère en arrière-plan — invisible pour
l'humain sauf via draw.l'owner.com ou le fichier .excalidraw commité.

```
kernel-orchestrator  →  signals BSI (STEP_DONE, GATE_PENDING, BLOCKED...)
diagram-scribe       →  patch nœud dans le .excalidraw correspondant
draw.l'owner.com   →  refresh → l'humain voit l'état en temps réel
```

---

## Mapping signals → état visuel

```yaml
STEP_DONE    : nœud → vert (#2ecc71)     + label "✅ done"
GATE_PENDING : nœud → orange (#f39c12)   + label "⚡ gate:human"
BLOCKED      : nœud → rouge (#e74c3c)    + label "❌ blocked"
DONE         : tous nœuds → vert          + bandeau "workflow terminé ✅"
CIRCUIT_BREAK: nœud → rouge vif + bordure épaisse + label "🔴 circuit break"
ABORT        : workflow → grisé (#95a5a6) + label "aborted"

# Drift détecté par brain-hypervisor :
DRIFT_ZONE   : flèche entre step N et step N+1 → rouge + label "⚠️ drift zone"
DRIFT_TYPE   : flèche → orange + label "⚠️ drift type"
```

---

## Structure d'un diagram workflow

```
Fichier : wiki/diagrams/<workflow-name>.excalidraw
          (commité, versionné, visible dans draw.l'owner.com)

Layout type pour un workflow 4 steps :

  [step 1]  ──►  [step 2]  ──►  [step 3]  ──►  [step 4]
  code            deploy          code            deploy
  ✅ done         ⚡ gate          ⬜ locked        ⬜ locked

Chaque nœud :
  - id    : "<workflow>-step-N"
  - label : "step N\n<story_angle tronqué>\n<status>"
  - color : selon mapping ci-dessus
  - badge : agents actifs (petit texte sous le nœud)

Flèches :
  - id     : "<workflow>-step-N-to-N+1"
  - color  : gris (normal) | rouge (drift détecté) | orange (drift type)
```

---

## Protocole d'initialisation

Quand brain-hypervisor charge un workflow → diagram-scribe crée le fichier initial :

```
INIT :
  1. Lire workflows/<name>.yml → extraire la chain (steps)
  2. Créer wiki/diagrams/<name>.excalidraw si absent
  3. Générer les nœuds (tous gris = "⬜ pending")
  4. Générer les flèches (grises)
  5. Annoter les drifts connus (depuis l'analyse brain-hypervisor)
  6. Mode live : PATCH draw.l'owner.com si API disponible
  7. Commiter le fichier initial dans wiki/
```

---

## Modes d'opération

```
Mode file (toujours disponible) :
  - Lit/écrit wiki/diagrams/<name>.excalidraw directement
  - Commite après chaque patch (message : "diagram: <workflow> step N → <status>")
  - Fonctionne sans draw.l'owner.com

Mode live (si draw.l'owner.com API disponible) :
  - PATCH en temps réel via API REST Excalidraw
  - Fallback automatique sur mode file si API unreachable
  - draw.l'owner.com = instance brain satellite dédiée à la visualisation
```

---

## Use cases

```
1. Diagram → spec (input)
   L'humain dessine dans draw.l'owner.com
   diagram-scribe lit le .excalidraw → extrait les nœuds/relations
   → Produit : agents/<name>.md ou workflows/<name>.yml (via brain-hypervisor)

2. Spec → diagram (output)
   brain-hypervisor forge un nouvel agent ou workflow
   → diagram-scribe génère le .excalidraw correspondant
   → wiki/diagrams/ + draw.l'owner.com mis à jour

3. Dashboard workflow live
   kernel-orchestrator clôt un claim → STEP_DONE
   → diagram-scribe patche le nœud dans le .excalidraw
   → draw.l'owner.com reflète l'état en temps réel
   → L'humain voit les gates pending sans lire un seul YAML
```

---

## Scripts utilisés

| Script | Quand |
|--------|-------|
| `scripts/diagram-init.sh <workflow>` | Init fichier .excalidraw depuis workflow.yml |
| `scripts/diagram-patch.sh <workflow> <step> <status>` | Patch nœud après signal BSI |

*(scripts à forger — diagram-scribe en est le seul consommateur)*

---

## Sources à charger

| Fichier | Pourquoi |
|---------|----------|
| `workflows/<name>.yml` | Structure du workflow à visualiser |
| `wiki/diagrams/<name>.excalidraw` | Fichier cible (créer si absent) |
| `brain/BRAIN-INDEX.md` | Claims actifs → état courant des steps |

---

## Liens

- Reçoit signals de : `kernel-orchestrator` + `brain-hypervisor`
- Écrit dans       : `wiki/diagrams/` + draw.l'owner.com (live)
- Pattern similaire : `orchestrator-scribe` (claims) + `toolkit-scribe` (patterns)
- → voir aussi     : `kernel-orchestrator` (source signaux) + `brain-hypervisor` (init workflow)

---

## Changelog

| Date | Changement |
|------|------------|
| 2026-03-17 | Création — signal mapping, 3 use cases, double mode file/live, draw.l'owner.com satellite |