feat: brain-template v2.0 — BSI-v3 complet + tiers documentés

- README reécrit : tiers free/pro/full + modèle clé API + multi-instance - Sync agents/ (57 agents, kernel-isolation validated) - Sync scripts/ BSI-v3 (file-lock, preflight, human-gate, brain-status) - KERNEL.md v0.7.0 — zones + délégation + rendering + isolation - brain-compose.yml v0.7.0 — rendering mode + kerneluser - workflows/ — template + brain-engine exemple - locks/.gitkeep + claims/.gitkeep - helloWorld : RAG boot tier full only (bsi-rag retiré du template)
2026-03-16 23:26:38 +01:00
parent 0b0e6649c2
commit 878886cd51
110 changed files with 7656 additions and 680 deletions
--- a/README.md
+++ b/README.md
@@ -1,101 +1,152 @@
 # brain-template

-> Système de mémoire versionnée pour Claude — template universel.
-> Cloner ce repo pour démarrer un brain depuis zéro.
+> Système de coordination multi-instances pour Claude — protocole BSI-v3.
+> Forke ce repo pour démarrer ton propre brain.

 ---

 ## Ce que c'est

-Un brain est un **système de contexte persistant** pour les sessions Claude — git + agents calibrés + gestion de contexte. Chaque session repart d'un état connu, pas de zéro.
+Un brain est un **système de contexte persistant et coordonné** pour Claude.
+Chaque session repart d'un état connu. Plusieurs instances peuvent travailler en parallèle sans conflit.

 ```
-MVCC (git) + agents calibrés + gestion de contexte
-= IA qui ne répète pas les mêmes erreurs
-  et devient plus précise avec le temps
+Git (MVCC) + Agents calibrés + Protocole BSI-v3
+= Claude qui ne répète pas les mêmes erreurs
+  qui coordonne plusieurs instances simultanées
+  qui respecte ton périmètre de travail
 ```

 ---

+## Tiers
+
+| Tier | Accès | Activation |
+|------|-------|-----------|
+| **free** | Kernel complet + BSI-v3 + agents fondamentaux | Fork public — aucune clé |
+| **pro** | + Agents métier (code-review, security, vps, ci-cd…) | Clé API `tier: pro` |
+| **full** | + Distillation locale (brain-engine) + instances rendering | Clé API `tier: full` |
+
+### Tier free — ce que tu as sans rien demander
+
+```
+Agents : coach, scribe, debug, mentor, helloWorld, brainstorm, orchestrator,
+         todo-scribe, interprete, aside, recruiter, agent-review
+
+Protocole BSI-v3 complet :
+  - Multi-instances sans conflit (file-lock.sh + preflight-check.sh)
+  - Human gate + pause cascade (human-gate-ack.sh)
+  - Vue live multi-instances (brain-status.sh)
+  - Theme branches + workflows déclarés
+  - Tiered-close + exit triggers
+
+Modes brain-compose : prod, dev, brainstorm, coach, debug, HANDOFF…
+```
+
+### Tier pro — avec clé API
+
+```
+Agents supplémentaires : code-review, security, testing, refacto,
+                         vps, ci-cd, monitoring, pm2, migration,
+                         frontend-stack, optimizer-*, toolkit-scribe,
+                         coach-scribe, git-analyst, capital-scribe,
+                         i18n, doc, mail, config-scribe
+
+→ Ajouter dans brain-compose.local.yml :
+    api_key: <ta-clé>
+    tier: pro
+```
+
+### Tier full — avec clé API full
+
+```
+Tout pro +
+  - brain-engine en local (distillation 2-pass, résumés compressés)
+  - Mode rendering : instances autonomes sur tes projets
+  - RAG sur l'historique brain
+  - Toutes les optimisations de contexte (BE-*)
+
+→ brain-engine s'installe localement
+→ Valide la clé au démarrage contre l'endpoint d'autorisation
+→ Sans clé valide : brain fonctionne en free, distillation inactive
+→ Clé liée à ton fork — non redistribuable
+```
+
+> **Obtenir une clé :** contact@tetardtek.com *(beta privée — partage limité)*
+
+---
+
 ## Installation — 15 minutes

 ### Prérequis

 - Git
- Claude Code (ou Claude avec accès aux fichiers)
- Un compte Gitea ou GitHub (pour les remotes)
+- Claude Code CLI
+- Un repo Git (Gitea, GitHub…)

-### Étape 1 — Cloner le template
+### 1. Forker le template

 ```bash
-git clone git@<GITEA_URL>:<USERNAME>/brain-template.git ~/Dev/Docs
-cd ~/Dev/Docs
+git clone git@<TON_GITEA>:<USERNAME>/brain-template.git ~/Dev/Brain
+cd ~/Dev/Brain
+git remote rename origin upstream   # garder le lien vers les updates kernel
+git remote add origin git@<TON_GITEA>:<USERNAME>/mon-brain.git
+git push -u origin main
 ```

-### Étape 2 — Configurer CLAUDE.md
+### 2. Configurer CLAUDE.md

 ```bash
+# Copier vers le profil global Claude
 cp profil/CLAUDE.md.example ~/.claude/CLAUDE.md
-# Remplacer les deux variables machine
-sed -i 's|<BRAIN_ROOT>|/home/<user>/Dev/Docs|g' ~/.claude/CLAUDE.md
-sed -i 's|<BRAIN_NAME>|prod|g' ~/.claude/CLAUDE.md
-# Choisir un nom parlant : prod / dev-laptop / template-test
-# Ce nom identifie l'instance — critique si plusieurs brains sur la même machine
+
+# Éditer ~/.claude/CLAUDE.md :
+#   brain_root: /home/<user>/Dev/Brain
+#   brain_name: prod
 ```

-### Étape 2b — Initialiser brain-compose
+### 3. Configurer les chemins machine
+
+```bash
+# Éditer PATHS.md — remplacer les placeholders :
+#   <BRAIN_ROOT>     → /home/<user>/Dev/Brain
+#   <GITEA_URL>      → git@git.example.com
+#   <USERNAME>       → ton username
+#   <PROJECTS_ROOT>  → /home/<user>/Dev/Projects
+```
+
+### 4. Personnaliser brain-compose.local.yml

 ```bash
 cp brain-compose.local.yml.example brain-compose.local.yml
-# Éditer brain-compose.local.yml :
-# - kernel_path → ton chemin réel
-# - instances.prod.path → ton chemin réel
-# - instances.prod.brain_name → même valeur que brain_name dans CLAUDE.md
+# Éditer : kernel_path, instances, [api_key si tier pro/full]
 ```

-> Si tu as plusieurs brains sur la même machine (prod + dev-laptop) :
-> ajouter chaque instance dans brain-compose.local.yml.
-> Switcher d'instance : `brain-compose, active l'instance dev-laptop`
+### 5. Cold boot

-### Étape 3 — Configurer PATHS.md
-
-Ouvrir `PATHS.md` et remplacer tous les placeholders :
-
-| Placeholder | Remplacer par |
-|-------------|---------------|
-| `<BRAIN_ROOT>` | Chemin absolu du brain (ex: `/home/alice/Dev/Docs`) |
-| `<GITEA_URL>` | URL de ton Gitea (ex: `git@git.example.com`) |
-| `<USERNAME>` | Ton username Gitea |
-| `<PROJECTS_ROOT>` | Dossier de tes projets (ex: `/home/alice/Dev/Github`) |
-| `<HOME>` | Ton home (ex: `/home/alice`) |
-
-### Étape 4 — Configurer la collaboration
-
-```bash
-cp profil/collaboration.md.example profil/collaboration.md
-# Éditer profil/collaboration.md — personnaliser langue, ton, règles spécifiques
-```
-
-### Étape 5 — Créer les satellites (optionnel mais recommandé)
-
-```bash
-# Créer sur Gitea : brain-profil, brain-todo, toolkit, brain-agent-review, progression-coach
-# Puis :
-git clone <GITEA_URL>:<USERNAME>/toolkit.git ~/Dev/Docs/toolkit
-git clone <GITEA_URL>:<USERNAME>/brain-profil.git ~/Dev/Docs/profil
-git clone <GITEA_URL>:<USERNAME>/brain-todo.git ~/Dev/Docs/todo
-git clone <GITEA_URL>:<USERNAME>/brain-agent-review.git ~/Dev/Docs/reviews
-git clone <GITEA_URL>:<USERNAME>/progression-coach.git ~/Dev/Docs/progression
-```
-
-### Étape 6 — Vérification cold boot
-
-Ouvrir une session Claude et vérifier :
+Ouvrir Claude Code dans le dossier brain et taper :
 ```
 Bonjour — démarre le brain (helloWorld)
 ```

-Signal de succès : contexte posé en < 3 échanges sans redemander qui tu es.
+Signal de succès : contexte posé en < 3 échanges, sans redemander qui tu es.
+
+---
+
+## Multi-instances — le protocole
+
+Plusieurs fenêtres Claude Code sur le même brain, sans conflit :
+
+```bash
+# Fenêtre 1 — coach/discussion
+bash scripts/brain-status.sh          # voit tout ce qui se passe
+
+# Fenêtre 2 — travail terrain (ex: projet superoauth/)
+# Elle ouvre un claim, pre-flight check avant chaque écriture,
+# mutex si fichier partagé → BRAIN-INDEX.md synchronise tout
+```
+
+Guide complet : `wiki/multi-instance.md`

 ---

@@ -103,80 +154,76 @@ Signal de succès : contexte posé en < 3 échanges sans redemander qui tu es.

 ```
 brain/
-├── README.md                    ← ce fichier
-├── PATHS.md                     ← chemins machine (à personnaliser)
-├── BRAIN-INDEX.md               ← registre BSI (locking sessions parallèles)
-├── agents/
-│   ├── _template.md             ← template pour créer un agent
-│   ├── AGENTS.md                ← index complet des agents
-│   ├── coach.md                 ← présence permanente — coaching progression
-│   ├── scribe.md                ← gardien du brain
-│   ├── brainstorm.md            ← exploration et décisions
-│   ├── aside.md                 ← convention /btw
-│   └── [30+ agents spécialisés]
-└── profil/
-    ├── CLAUDE.md.example        ← bootstrap Claude (copier vers ~/.claude/)
-    ├── collaboration.md.example ← règles de travail (à personnaliser)
-    ├── memory-architecture.md   ← TTL, Sectionnarisation, Stratification
-    ├── bsi-spec.md              ← Brain Session Index — spec locking sessions
-    ├── context-hygiene.md       ← chargement sélectif du contexte
-    ├── anti-hallucination.md    ← règles globales anti-hallucination
-    ├── memory-integrity.md      ← règles d'écriture dans le brain
-    ├── scribe-pattern.md        ← pattern Scribe — agents écrivants
-    └── scribe-system.md         ← cartographie des scribes
+├── agents/               ← 57 agents calibrés (index : agents/AGENTS.md)
+├── scripts/              ← BSI-v3 protocol (index : scripts/README.md)
+│   ├── brain-status.sh   ← vue live multi-instances
+│   ├── preflight-check.sh← 6 checks avant écriture
+│   ├── file-lock.sh      ← mutex fichier
+│   ├── human-gate-ack.sh ← gate humain + pause cascade
+│   └── ...
+├── workflows/            ← chaînes de satellites déclarées
+├── wiki/                 ← guides (multi-instance, patterns, concepts…)
+├── locks/                ← registre mutex fichiers (BSI-v3-7)
+├── claims/               ← sessions BSI (vide au démarrage)
+├── BRAIN-INDEX.md        ← état global — lu par toutes les instances
+├── KERNEL.md             ← loi des zones (ne pas modifier seul)
+├── brain-compose.yml     ← modes, feature flags, agents autorisés
+├── brain-compose.local.yml← config machine (non versionné)
+└── PATHS.md              ← chemins machine (à personnaliser)
 ```

 ---

-## Agents inclus
+## BSI-v3 — protocole de coordination

-| Catégorie | Agents |
-|-----------|--------|
-| **Présence permanente** | `coach` |
-| **Brain maintenance** | `scribe`, `todo-scribe`, `toolkit-scribe`, `coach-scribe` |
-| **Navigation** | `orchestrator`, `interprete`, `aside`, `helloWorld` |
-| **Exploration** | `brainstorm`, `mentor`, `recruiter`, `agent-review` |
-| **Code** | `code-review`, `security`, `testing`, `debug`, `refacto` |
-| **DevOps** | `vps`, `ci-cd`, `monitoring`, `pm2`, `migration` |
-| **Frontend** | `frontend-stack`, `optimizer-frontend`, `i18n`, `doc` |
-| **Backend** | `optimizer-backend`, `optimizer-db` |
-| **Infrastructure mail** | `mail` |
-| **Capital / CV** | `capital-scribe`, `git-analyst` |
-| **Configuration** | `config-scribe`, `brain-compose` |
+Le protocole qui permet plusieurs instances sans collision :
+
+| Composant | Rôle |
+|-----------|------|
+| `claims/*.yml` | Chaque session déclare son scope — visible par toutes |
+| `BRAIN-INDEX.md` | Registre global — état en temps réel |
+| `file-lock.sh` | Mutex fichier — empêche les écritures simultanées |
+| `preflight-check.sh` | 6 checks avant d'écrire (scope, zone, lock, circuit breaker…) |
+| `human-gate-ack.sh` | Pause planifiée ou urgence — cascade sur les instances enfants |
+| `brain-status.sh` | Vue live : qui travaille où, quels fichiers lockés, quels signaux |

 ---

-## Architecture — pourquoi ça marche
+## Zones — ce que tu peux modifier

-**3 couches combinées :**
-
-1. **Git = MVCC gratuit** — toute décision versionnée, traçable, réversible
-2. **Agents calibrés** — chaque agent a un scope déclaré, des sources conditionnelles, un cycle de vie
-3. **Brain = couche de coordination** — chargement sélectif, mémoire sectionnarisée, procédures de reprise
-
-Voir `profil/memory-architecture.md` pour les 3 piliers (TTL, Sectionnarisation, Stratification).
+| Zone | Contenu | Règle |
+|------|---------|-------|
+| **kernel** | `agents/` `scripts/` `KERNEL.md` `brain-compose.yml` | Décision humaine — `preflight` bloque les agents |
+| **project** | `todo/` `workspace/` `projets/` | Libre — rendering mode ici |
+| **personal** | `profil/capital` `progression/` | Ton contenu, non distribué |

 ---

-## Personnalisation
+## Recevoir les updates kernel

-Après installation, créer à la racine :
-
-```
-focus.md        ← état de tes projets actifs
-projets/        ← une fiche par projet (template dans profil/memory-architecture.md)
-infrastructure/ ← config VPS, Docker, etc.
+```bash
+git fetch upstream
+bash scripts/kernel-update-check.sh --remote  # détecte conflits vs updates
+# Appliquer les non-conflictuels :
+bash scripts/kernel-update-check.sh --remote --apply
 ```

+`kernel.lock` — checksums SHA-256 des fichiers kernel.
+Permet de savoir exactement ce qui a divergé avant de puller.
+
 ---

-## Brain Session Index (BSI)
+## Roadmap

-Le `BRAIN-INDEX.md` permet de travailler sur plusieurs machines en parallèle sans collision.
-Le scribe gère les claims — voir `profil/bsi-spec.md`.
+- [x] BSI-v3 multi-instances (v3-1b → v3-8)
+- [x] Rendering mode — instances autonomes projet
+- [x] kernel.lock + isolation check
+- [ ] Validation clé API (tier pro/full)
+- [ ] kernel-orchestrator (v3-9) — routage autonome entre satellites
+- [ ] brain-engine hosted (distillation managée)

 ---

 ## Licence

-MIT — utilise, forke, adapte.
+MIT — kernel libre. brain-engine (distillation) non inclus dans ce template.