feat(checkpoint): CHECKPOINT signal — snapshot mid-session, reprise sans perte

2026-03-14 03:30:31 +01:00
parent 80c59dc13d
commit 06a61f77f6
3 changed files with 93 additions and 20 deletions
--- a/BRAIN-INDEX.md
+++ b/BRAIN-INDEX.md
@@ -1,16 +1,17 @@
 # BRAIN-INDEX.md — Registre de claims

 > Système de locking optimiste — Brain Session Index (BSI).
-> Mis à jour par le **scribe uniquement**. Ne jamais éditer manuellement.
+> **Claims** : scribe uniquement. **Signals** : orchestrator-scribe uniquement.
+> Ne jamais éditer manuellement.
 > Spec complète : `brain/profil/bsi-spec.md`

 ---

 ## Claims actifs

-| Session | Portée | Niveau | Ouvert le | Expire le | État |
-|---------|--------|--------|-----------|-----------|------|
-| — | — | — | — | — | — |
+| Session | Instance | Portée | Niveau | Ouvert le | Expire le | État |
+|---------|----------|--------|--------|-----------|-----------|------|
+| — | — | — | — | — | — | — |

 *Aucun claim actif.*

@@ -18,21 +19,46 @@

 ## Claims stale — contrôle humain requis

-| Session | Portée | Expiré le | Action requise |
-|---------|--------|-----------|----------------|
+| Session | Instance | Portée | Expiré le | Action requise |
+|---------|----------|--------|-----------|----------------|

 *Aucun claim stale.*

 ---

+## Signals — Bus inter-sessions
+
+> Écrit par `orchestrator-scribe`. Lu par toutes les instances au démarrage.
+> Un signal livré reste 24h pour audit, puis archivé.
+
+| ID | De | Pour | Type | Concerné | Payload | État |
+|----|----|------|------|----------|---------|------|
+| — | — | — | — | — | — | — |
+
+*Aucun signal en attente.*
+
+**Types de signaux :**
+- `READY_FOR_REVIEW` — instance A termine, demande review à instance B
+- `REVIEWED` — review terminée, résultats dans `reviews/`
+- `BLOCKED_ON` — instance A attend que instance B libère un scope
+- `HANDOFF` — passage de main, instance B reprend depuis un point précis
+- `CHECKPOINT` — snapshot mid-session (A→A), reprise après compactage ou coupure
+- `INFO` — message sans action requise
+
+---
+
 ## Historique — 30 derniers jours

-| Session | Portée | Ouvert | Fermé | Statut |
-|---------|--------|--------|-------|--------|
+| Session | Instance | Portée | Commits | Ouvert | Fermé | Statut |
+|---------|----------|--------|---------|--------|-------|--------|

 *Aucun historique.*

 ---

-> **Règle watchdog :** au démarrage de chaque session brain, le scribe scanne ce fichier.
-> TTL expiré → déplacer vers "Claims stale". Jamais auto-release — contrôle humain toujours.
+> **Règle watchdog :** au démarrage, le scribe scanne Claims + Signals.
+> Claims TTL expiré → stale. Signals pending adressés à cette instance → alerter.
+>
+> **Format session ID :** `sess-YYYYMMDD-HHMM-<slug>`
+> **Format signal ID :** `sig-YYYYMMDD-<seq>` (ex: `sig-20260314-001`)
+> **Format instance :** `brain_name@machine` — ex: `prod@desktop`, `template-test@laptop`
--- a/agents/orchestrator-scribe.md
+++ b/agents/orchestrator-scribe.md
@@ -115,6 +115,7 @@ archived  → 24h après delivered, retiré de ## Signals et mis dans ## Histori
 | `REVIEWED` | B → A | A lit `reviews/<fichier>.md`, continue son travail |
 | `BLOCKED_ON` | A → B | B prend connaissance, libère le scope si possible |
 | `HANDOFF` | A → B | B charge le contexte et reprend depuis le point précis |
+| `CHECKPOINT` | A → A | Même session — snapshot mid-session, reprise après compactage ou coupure |
 | `INFO` | A → B | B prend connaissance, aucune action requise |

 ---
@@ -150,6 +151,42 @@ prod@laptop   →  reçoit HANDOFF
               →  continue sans perte de contexte
 ```

+### CHECKPOINT — snapshot mid-session
+
+Déclenché par l'utilisateur (`checkpoint`, `/checkpoint`, `pose un checkpoint`) ou par scribe à un breakpoint naturel.
+
+```
+Format payload CHECKPOINT :
+  Tâche en cours  : <ce qu'on était en train de faire>
+  Fichiers touchés: <liste des fichiers modifiés depuis ouverture du claim>
+  Commits         : <git log --oneline depuis début session>
+  Prochaine étape : <exactement quoi faire au redémarrage — précis, actionnable>
+  Contexte non-git: <décisions, discussions, intentions pas encore commitées>
+```
+
+```
+Procédure :
+1. Générer ID signal : sig-YYYYMMDD-<seq>
+2. De  : sess-YYYYMMDD-HHMM-<role>@machine  (session actuelle)
+   Pour : sess-YYYYMMDD-HHMM-<role>@machine  (même session — HANDOFF vers soi)
+3. Type : CHECKPOINT
+4. Remplir payload structuré ci-dessus
+5. État : pending
+6. Confirmer : "Checkpoint posé — reprise depuis : <prochaine étape>"
+```
+
+Watchdog au redémarrage — détection CHECKPOINT :
+```
+1. Lire ## Signals — filtrer Type == CHECKPOINT, De == instance active
+2. Si trouvé :
+   → Afficher le payload complet AVANT tout autre action
+   → "Checkpoint détecté [date] — Prochaine étape : <prochaine étape>"
+   → Demander : reprendre depuis ce point ?
+3. Marquer delivered après confirmation
+```
+
+---
+
 ### Sessions parallèles — même brain, rôles distincts

 ```
@@ -221,3 +258,4 @@ Ne pas invoquer si :
 |------|------------|
 | 2026-03-14 | Création — bus Signals, cycles coworking, patterns HANDOFF/READY_FOR_REVIEW, frontière scribe/orchestrator-scribe |
 | 2026-03-14 | `Pour` accepte `sess-id@machine` — sessions parallèles sans fork de brain, pattern N sessions / 1 brain |
+| 2026-03-14 | Signal `CHECKPOINT` — snapshot mid-session A→A, payload structuré, watchdog reprise |
--- a/agents/scribe.md
+++ b/agents/scribe.md
@@ -104,6 +104,8 @@ Fin de session
 ## Triggers — quand intervenir

 **Automatique (le scribe doit réagir sans qu'on le demande) :**
+- L'utilisateur dit `checkpoint`, `/checkpoint` ou `pose un checkpoint` → déclencher le protocole CHECKPOINT via orchestrator-scribe (payload structuré + signal posé dans BRAIN-INDEX.md)
+- Breakpoint naturel atteint en session longue (item important terminé, avant une pause) → proposer un checkpoint
 - Une tâche listée dans `focus.md` vient d'être complétée → la marquer ✅
 - Un projet vient d'être déployé → mettre à jour la fiche projet + focus
 - Une décision d'architecture importante est prise → la documenter
@@ -166,10 +168,14 @@ Le scribe est le **gardien unique** du BSI. Il est le seul à écrire dans `BRAI
 ### Watchdog — début de session (automatique)

 ```
-1. Lire brain/BRAIN-INDEX.md ## Claims actifs
-2. Pour chaque claim : vérifier si "Expire le" < maintenant
-3. Si expiré → déplacer vers ## Claims stale, annoter raison
-4. Reporter : "[N] actifs, [M] stale détectés"
+1. Lire brain/BRAIN-INDEX.md ## Signals — filtrer Type == CHECKPOINT, De == instance active
+   → Si trouvé : afficher payload AVANT tout autre action
+   → "Checkpoint détecté [date] — Prochaine étape : <prochaine étape>"
+   → Demander : reprendre depuis ce point ? (oui → marquer delivered, continuer)
+2. Lire brain/BRAIN-INDEX.md ## Claims actifs
+3. Pour chaque claim : vérifier si "Expire le" < maintenant
+4. Si expiré → déplacer vers ## Claims stale, annoter raison
+5. Reporter : "[N] actifs, [M] stale détectés"
   → stale > 0 : demander action humaine avant de continuer
 ```

@@ -178,11 +184,12 @@ Le scribe est le **gardien unique** du BSI. Il est le seul à écrire dans `BRAI
 ```
 Signal : "scribe, ouvre un claim sur <scope>"
 1. Générer ID : sess-YYYYMMDD-HHMM-<4chars>
-2. Choisir TTL : 2h (court) / 4h (deep) / 8h (archi) — selon contexte
-3. Vérifier conflit dans ## Claims actifs (scope A ∩ scope B ≠ ∅)
+2. Lire brain_name + machine depuis brain-compose.local.yml → instance = brain_name@machine
+3. Choisir TTL : 2h (court) / 4h (deep) / 8h (archi) — selon contexte
+4. Vérifier conflit dans ## Claims actifs (scope A ∩ scope B ≠ ∅)
   → Conflit → alerter humain, NE PAS créer
-4. Ajouter dans ## Claims actifs
-5. Confirmer : "Claim ouvert — [scope] / [session ID] / expire [TTL]"
+5. Ajouter dans ## Claims actifs avec colonne Instance
+6. Confirmer : "Claim ouvert — [instance] / [scope] / [session ID] / expire [TTL]"
 ```

 ### Fermer un claim
@@ -190,8 +197,9 @@ Signal : "scribe, ouvre un claim sur <scope>"
 ```
 Signal : "scribe, ferme le claim <session-id>" ou fin de session
 1. Retirer de ## Claims actifs
-2. Ajouter dans ## Historique : session, scope, ouvert, fermé, statut=completed
-3. Confirmer : "Claim fermé — [session ID]"
+2. Récupérer les commits de la session : git log --oneline --since="<ouvert le>"
+3. Ajouter dans ## Historique : session, scope, ouvert, fermé, commits, statut=completed
+4. Confirmer : "Claim fermé — [session ID] — [N commits]"
 ```

 ### Règles BSI non négociables
@@ -280,3 +288,4 @@ Ne pas invoquer si :
 | 2026-03-13 | [CONFIRMÉ] Non-overlap coach-scribe + gap infra signal + vérifier AGENTS.md fin de session |
 | 2026-03-13 | Fondements — Sources conditionnelles structurées, Écrit où, Cycle de vie |
 | 2026-03-14 | BSI — Brain Session Index intégré : watchdog, open/close claim, règles non négociables |
+| 2026-03-14 | CHECKPOINT — watchdog détecte CHECKPOINT au démarrage, trigger utilisateur + auto breakpoints, commits dans Historique |