scribe: propagation sess-20260315-0200-quick-wins — +coach, architecture-scribe, ADRs 001-007, commit/todo-context

profil/commit-context.md

@@ -0,0 +1,89 @@
+# commit-context.md — Règles commits sémantiques
+
+> **Type :** Invariant — règles d'écriture git du brain
+> Rédigé : 2026-03-15
+> Propriétaire : scribe (brain/), scribes satellites pour leurs repos
+> Source de vérité pour : tous les agents qui commitent
+
+---
+
+## Problème résolu
+
+Sans règle formalisée, les messages de commit dérivent. En 10 sessions : `update`, `fix`, `misc`, `wip`. L'historique devient illisible. Les ADRs ne peuvent pas être détectés automatiquement. L'architecture-scribe n'a pas de matière.
+
+---
+
+## Types de commits — convention
+
+Voir aussi `KERNEL.md ## Commit types` pour le mapping zone → scribe → type.
+
+| Type | Zone | Usage | Exemple |
+|------|------|-------|---------|
+| `kernel:` | KERNEL | Modification contrat fondateur | `kernel: KERNEL.md — zones typées` |
+| `feat:` | KERNEL agents/ | Nouvelle capacité, nouvel agent | `feat: architecture-scribe — pipeline ADR` |
+| `fix:` | KERNEL agents/ | Correction comportement ou bug | `fix: brain-bot — filter open claims only` |
+| `bsi:` | BRAIN-INDEX | Open/close claim, signal | `bsi: open claim sess-XXX` |
+| `scribe:` | INSTANCE + profil/ | brain update (focus, projets, profil) | `scribe: focus.md — Sprint 2 ✅` |
+| `metabolism:` | progression/ | Métriques session | `metabolism: sess-XXX — health 1.07` |
+| `todo:` | todo/ | Intentions fermées/ouvertes | `todo: VITAL contexts/ ✅, preAlpha todos` |
+| `toolkit:` | toolkit/ | Pattern validé en prod | `toolkit: api-error — status typed` |
+| `config:` | INSTANCE | PATHS, compose, machine config | `config: PATHS.md — machine laptop` |
+
+---
+
+## Règles
+
+**1. Un commit = une intention**
+Ne jamais mélanger types dans un commit. `feat:` + `fix:` = deux commits.
+
+**2. Message : action concrète, pas description**
+```
+✅  feat: session-orchestrator — lifecycle boot 4 couches + close séquencé
+❌  feat: update session orchestrator file
+```
+
+**3. Scope optionnel entre parenthèses**
+```
+feat(agents): architecture-scribe — pipeline git-analyst → ADR
+fix(bot): filter claims by open status — was showing 11 instead of 2
+```
+
+**4. `bsi:` est non négociable**
+Tout open/close claim = commit `bsi:` immédiat + push. Sans push, VPS aveugle.
+
+**5. Satellites commitent dans leur repo**
+`scribe:` sur brain/ ne commit pas dans profil/. Chaque scribe = son repo.
+
+**6. Preuve d'écriture = git blame**
+Le commit message doit permettre à `architecture-scribe` de détecter si une décision architecturale a été prise. Être explicite sur le "pourquoi" dans le message.
+
+---
+
+## Ordre de commit canonique (fin de session)
+
+```
+1. bsi: close claim <sess-id>        ← toujours en dernier sur brain/
+2. metabolism: <sess-id>              ← progression/ satellite
+3. todo: <résumé>                     ← todo/ satellite
+4. scribe: focus.md + projets/        ← brain/ (avant bsi close)
+```
+
+Voir `profil/scribe-system.md` pour l'ordre complet multi-satellites.
+
+---
+
+## Trigger de chargement
+
+```
+Propriétaire : tous les scribes
+Trigger      : invocation d'un scribe → charger avant d'écrire
+Section      : Sources au démarrage (scribes) — conditionnel (agents métier si commit requis)
+```
+
+---
+
+## Changelog
+
+| Date | Changement |
+|------|------------|
+| 2026-03-15 | Création — types, règles, ordre canonique, mapping KERNEL.md zones |

profil/decisions/001-bsi-locking-optimiste.md

@@ -0,0 +1,33 @@
+# ADR-001 — Locking optimiste BSI — claims + TTL vs mutex strict
+
+> Date : 2026-03-14
+> Statut : actif
+> Décidé par : session brain sess-20260314-1810-brain
+
+## Contexte
+
+Plusieurs sessions Claude en parallèle peuvent modifier les mêmes fichiers brain sans se voir. Un mutex strict (une seule session à la fois) bloque le workflow multi-agent.
+
+## Décision
+
+Locking optimiste via `BRAIN-INDEX.md` — chaque session déclare un claim avec TTL. On ne bloque pas, on déclare. Le watchdog détecte les conflits et alerte. L'humain décide.
+
+## Alternatives considérées
+
+| Option | Raison du rejet |
+|--------|----------------|
+| Mutex strict (une session) | Bloque le dual-agent et le pattern supervisor |
+| Pas de locking | Collisions silencieuses sur focus.md, projets/ |
+| Branches git par session | Overhead de merge, perd le temps réel |
+
+## Conséquences
+
+**Positives :** multi-sessions en parallèle, pattern supervisor possible, brain-watch détecte les stales automatiquement.
+
+**Négatives / trade-offs :** un conflit rare peut passer si les deux sessions commitent avant que le watchdog notifie. Accepté — le brain est un système coopératif, pas adversarial.
+
+## Références
+
+- `profil/bsi-spec.md`
+- `BRAIN-INDEX.md`
+- `agents/orchestrator-scribe.md`

profil/decisions/002-session-as-identity.md

@@ -0,0 +1,31 @@
+# ADR-002 — Session-as-identity — slug IS le rôle
+
+> Date : 2026-03-14
+> Statut : actif
+> Décidé par : session brain
+
+## Contexte
+
+Pour faire travailler plusieurs rôles en parallèle (build, review, test), l'option naïve est de forker un brain par rôle. Explosion de configurations, de syncs, de dérive.
+
+## Décision
+
+Le slug de session IS l'identité de routage. Un seul brain par machine. N sessions nommées. `sess-20260314-0900-build@desktop` = rôle build. `orchestrator-scribe` route les signaux par `sess-id@machine`.
+
+## Alternatives considérées
+
+| Option | Raison du rejet |
+|--------|----------------|
+| Un brain par rôle | Explosion configs, sync impossible |
+| Tags git par rôle | Pas de communication inter-session |
+
+## Conséquences
+
+**Positives :** un seul brain à maintenir, N rôles simultanés, signaux inter-sessions via BSI.
+
+**Négatives :** le slug doit être discipliné — un slug générique (`-brain`) perd le contexte du rôle.
+
+## Références
+
+- `profil/bsi-spec.md ## session-as-identity`
+- `BRAIN-INDEX.md ## Claims`

profil/decisions/003-scribe-pattern-non-contamination.md

@@ -0,0 +1,32 @@
+# ADR-003 — Scribe Pattern — non-contamination, un scribe = un territoire
+
+> Date : 2026-03-14
+> Statut : actif
+> Décidé par : session brain
+
+## Contexte
+
+Sans règle d'écriture, chaque agent modifie ce qu'il veut. Résultat : focus.md écrasé par un agent vps, todo/ pollué par un agent debug. Dérive garantie sur 10 sessions.
+
+## Décision
+
+Un agent métier ne commit jamais directement dans le brain. Il signal → le scribe compétent écrit → dans sa zone uniquement. 8 scribes, 8 territoires exclusifs.
+
+## Alternatives considérées
+
+| Option | Raison du rejet |
+|--------|----------------|
+| Chaque agent écrit où il veut | Dérive immédiate, historique illisible |
+| Un seul scribe global | Goulot d'étranglement, perd la granularité |
+
+## Conséquences
+
+**Positives :** historique git lisible par scribe, responsabilité claire, zero dérive entre zones.
+
+**Négatives :** friction légère — un agent doit "signaler" plutôt qu'écrire directement. Accepté.
+
+## Références
+
+- `profil/scribe-system.md`
+- `profil/architecture.md ## Le Scribe Pattern`
+- `KERNEL.md ## Commit types`

profil/decisions/004-trois-couches-kernel-instance-personnel.md

@@ -0,0 +1,32 @@
+# ADR-004 — 3 couches kernel/instance/personnel
+
+> Date : 2026-03-14
+> Statut : actif
+> Décidé par : session brain
+
+## Contexte
+
+Un brain utilisable sur plusieurs machines avec des configs radicalement différentes. Un brain exportable (brain-template) sans exposer de données personnelles.
+
+## Décision
+
+3 couches séparées : kernel (universel, exportable), instance (machine-spécifique, jamais exporté), personnel (intime, jamais partagé). Chaque couche a son repo satellite.
+
+## Alternatives considérées
+
+| Option | Raison du rejet |
+|--------|----------------|
+| 2 couches kernel/perso | La config machine pollue le kernel ou le perso |
+| Monorepo unique | Export impossible sans exposer données perso |
+
+## Conséquences
+
+**Positives :** brain-template = kernel pur exportable, multi-machine sans friction, isolation des accès granulaire.
+
+**Négatives :** 6 repos à maintenir. Offset par les scripts brain-compose et PATHS.md.
+
+## Références
+
+- `profil/architecture.md ## Les 3 couches`
+- `PATHS.md`
+- `brain-template/`

profil/decisions/005-zones-typees-kernel-loi-active.md

@@ -0,0 +1,33 @@
+# ADR-005 — Zones typées + protection graduée — KERNEL.md comme loi active
+
+> Date : 2026-03-14
+> Statut : actif
+> Décidé par : session brain sess-20260315-0000-brain-template + coach
+
+## Contexte
+
+Le brain a grandi sans loi formalisée sur qui peut écrire quoi. Les agents peuvent dériver entre zones. Sans capstone architectural, le système vieillit mal.
+
+## Décision
+
+KERNEL.md à la racine = loi active chargée Couche 0. 4 zones typées (KERNEL, SATELLITES, INSTANCE, WORK) avec protection graduée. Flux unidirectionnel : satellite → kernel, jamais l'inverse. ARCHITECTURE.md archivé dans profil/ comme mémoire épisodique.
+
+## Alternatives considérées
+
+| Option | Raison du rejet |
+|--------|----------------|
+| profil/kernel-zones.md | Trop périphérique — la loi doit être visible à la racine |
+| Enrichir ARCHITECTURE.md | Confond décisions passées et lois actives |
+| Pas de fichier de loi | Dérive garantie sur 20+ agents |
+
+## Conséquences
+
+**Positives :** tout agent au boot sait sa zone, sa protection, son commit type. Maintenabilité longue durée. Base pour le modèle de licence par zone.
+
+**Négatives :** KERNEL.md lui-même ne peut pas être modifié sans décision humaine — friction assumée et voulue.
+
+## Références
+
+- `KERNEL.md`
+- `profil/architecture.md`
+- Session brainstorm coach 2026-03-14

profil/decisions/006-vision-produit-brain-as-a-service.md

@@ -0,0 +1,124 @@
+# ADR-006 — Vision produit : brain as a service — matrice instanciable
+
+> Date : 2026-03-15
+> Statut : vision — implémentation post v1.0.0
+> Décidé par : session brainstorm coach sess-20260315-0100-vision-kernel
+
+---
+
+## Contexte
+
+Le brain est une matrice de fichiers structurés qui instancie une intelligence contextuelle dans n'importe quel LLM. Le LLM est interchangeable — il est le moteur, pas le produit. Le produit est la matrice.
+
+Trois insights émergés en session :
+1. Le typage fort des agents (zones, protection, RFC contexts) rend la matrice défendable
+2. BYOK existe déjà dans le brain (MYSECRETS, brain-compose.yml feature_set)
+3. La première instance publique = fenêtre d'avance avant que d'autres reproduisent
+
+---
+
+## Décision
+
+Construire `brain.tetardtek.com` — service web self-hosted — comme premier point d'entrée public. L'utilisateur apporte sa clé API (BYOK). Le brain fournit la matrice. La subscription contrôle les zones accessibles.
+
+**Ne pas open-sourcer avant d'être sur les radars.** Apparaître d'abord, décider ensuite.
+
+---
+
+## Architecture produit
+
+```
+brain.tetardtek.com
+  ├── Interface web (session browser)
+  ├── BYOK — utilisateur fournit sa clé API LLM
+  ├── Matrice servie depuis infra tetardtek (zones contrôlées)
+  ├── BSI géré côté serveur (multi-tenant)
+  └── Subscription → feature_set → zones débloquées
+```
+
+### Tiers d'accès (granulaire par zone)
+
+| Tier | Zones accessibles | Ce que ça donne |
+|------|------------------|-----------------|
+| **Free** | Agent de base + personnalité + quelques tricks | Assez pour voir la valeur |
+| **Pro** | + profil/ + progression/ | Mémoire personnelle, coach, capital |
+| **Stack** | + agents par stack (React, Node, Docker...) | Expertise domaine |
+| **Protocol** | + contexts/protocol.md (RFC) | Agents mail, OAuth, sécurité RFC |
+| **Enterprise** | Tout + multi-sessions BSI + supervisor | Workflows parallèles |
+
+### Modèle économique
+
+```
+Utilisateur  →  apporte sa clé API LLM (BYOK)
+tetardtek    →  fournit la matrice + les zones + les updates kernel
+              →  facture la valeur ajoutée, pas le compute
+```
+
+---
+
+## Ce qui existe déjà (prérequis couverts)
+
+| Composant | État |
+|-----------|------|
+| KERNEL.md zones + protection | ✅ v0.6.0 |
+| feature_set dans brain-compose.yml | ✅ |
+| BYOK pattern (MYSECRETS) | ✅ |
+| metabolism/ usage tracking | ✅ |
+| BSI claims + sessions | ✅ |
+| VPS + SSL + Apache + Docker | ✅ |
+| brain-template exportable | ✅ v0.6.0 |
+
+---
+
+## Ce qui manque (prérequis à construire)
+
+| Composant | Priorité |
+|-----------|----------|
+| Interface web (session browser) | Prérequis #1 |
+| Multi-tenant BSI (isolation par user) | Prérequis #2 |
+| Auth token signé cryptographiquement | Prérequis #3 |
+| brain-template v1.0.0 (interface contractuelle stable) | Gate de lancement |
+| Billing intégration (subscription → feature_set) | Post-lancement |
+
+---
+
+## Le moat défendable
+
+La matrice se copie. La longueur d'avance vient de :
+1. **Distribution** — premier sur brain.tetardtek.com
+2. **Mémoire des décisions** — 6 ADRs, les "pourquoi" ne se copient pas
+3. **Écosystème** — toolkit/ patterns validés en prod, toolkit-scribe, progression/
+4. **Instanciable** — pas de dépendance à un seul LLM provider
+
+---
+
+## Risque principal
+
+D'autres voient le code source et reproduisent. Mitigation : apparaître sur les radars avant de rendre le code accessible. La fenêtre d'avance = distribution + réputation établie.
+
+---
+
+## Alternatives considérées
+
+| Option | Raison du rejet |
+|--------|----------------|
+| Open source immédiat | Perd la fenêtre d'avance avant distribution établie |
+| API propriétaire (pas BYOK) | Coût compute à absorber + dépendance fournisseur |
+| CLI only (pas web) | Friction trop élevée pour adoption grand public |
+
+---
+
+## Conséquences
+
+**Positives :** modèle économique viable, BYOK = zéro coût compute, zones = granularité billing naturelle, brain-template = produit exportable.
+
+**Négatives / trade-offs :** multi-tenant BSI = complexité infra. Accepté — c'est l'investissement technique pour le moat.
+
+---
+
+## Références
+
+- `KERNEL.md` — zones et protection = base du modèle de licence
+- `brain-compose.yml ## feature_set` — mécanisme d'accès existant
+- `profil/metabolism-spec.md` — usage tracking = base billing
+- Session brainstorm coach 2026-03-15

profil/decisions/007-kernel-package-distribution.md

@@ -0,0 +1,111 @@
+# ADR-007 — Kernel package distribution — brain install
+
+> Date : 2026-03-15
+> Statut : vision — prérequis v1.0.0
+> Décidé par : session brainstorm coach sess-20260315-0100-vision-kernel
+
+---
+
+## Contexte
+
+Le brain est distribué aujourd'hui via 6 git clones manuels. Friction trop élevée pour une adoption large. La question : peut-on hardcoder le kernel pour simplifier l'installation sans perdre la valeur de la matrice fichiers ?
+
+Tension identifiée : le brain est entièrement éditable aujourd'hui (force pour le dev, faiblesse pour la distribution et le modèle de licence).
+
+---
+
+## Décision
+
+Architecture hybrid kernel/instance :
+
+```
+~/.brain/kernel/     ← installé par package (brew/npm/curl), read-only, mis à jour via brain update
+~/Dev/Docs/          ← instance personnelle (focus.md, todo/, progression/, projets/)
+CLAUDE.md            ← pointe vers kernel + instance (brain_root: ~/.brain/kernel/)
+```
+
+Le kernel devient physiquement read-only par installation — ce qui **enforce KERNEL.md zones** au niveau filesystem, pas seulement par convention.
+
+---
+
+## Modèle d'installation cible
+
+```bash
+# Installation
+brew install brain          # ou npm install -g brain / curl brain.tetardtek.com/install | sh
+
+# Premier setup
+brain init ~/Dev/Docs       # crée l'instance locale + CLAUDE.md configuré
+
+# Mise à jour kernel
+brain update                # git pull kernel → nouvelle version
+
+# Par tier
+brain install --tier=pro    # débloque zones profil/ + progression/
+brain install react node    # ajoute agents stack React + Node
+```
+
+---
+
+## Pourquoi hybrid et pas fat CLAUDE.md
+
+| Option | Raison du rejet |
+|--------|----------------|
+| CLAUDE.md fat (tout embarqué) | Perd granularité zones, versioning fin, mise à jour partielle |
+| Monorepo unique | Friction 6 clones = barrière adoption |
+| **Hybrid kernel/instance** | ✅ Read-only kernel enforced, instance libre, `brain update` propre |
+
+---
+
+## Conséquences sur le modèle de licence
+
+```
+Licence = version du kernel distribué
+  brain install --tier=free      → kernel zones free (agent base + tricks)
+  brain install --tier=pro       → + profil/ + progression/ + coach
+  brain install --tier=stack=react → + agents React + toolkit React
+  brain install --tier=protocol  → + contexts/protocol.md (RFC)
+```
+
+La licence contrôle quelle version du package s'installe. Pas un token à dropper — le package manager enforce.
+
+---
+
+## Conséquences sur KERNEL.md zones
+
+Le kernel read-only filesystem = KERNEL.md zone KERNEL protection maximale enforced par design, pas par convention. Un utilisateur ne peut pas modifier un agent kernel sans `sudo` — signal fort que c'est hors périmètre.
+
+Les zones SATELLITES et INSTANCE restent dans `~/Dev/Docs/` — entièrement libres.
+
+---
+
+## Distribution v1 → v2
+
+```
+v1 : git clone (aujourd'hui — devs Claude Code, early adopters)
+     "clone ce repo, configure ton CLAUDE.md"
+     → Marché : devs qui comprennent immédiatement
+
+v2 : brain install (post v1.0.0)
+     → Marché : tous les devs + brain.tetardtek.com pour non-devs
+```
+
+---
+
+## Prérequis techniques
+
+| Composant | Priorité |
+|-----------|----------|
+| brain-template v1.0.0 (interface contractuelle stable) | Gate #1 |
+| `brain` CLI (init, install, update, sync) | Prérequis #2 |
+| Package registry (Homebrew formula / npm) | Prérequis #3 |
+| Tier system dans brain-compose.yml | Existe déjà (feature_set) — à étendre |
+
+---
+
+## Références
+
+- `KERNEL.md` — zones et protection = contrat du package
+- `ADR-006` — vision produit brain-as-a-service (web + BYOK)
+- `brain-compose.yml ## feature_set` — mécanisme tier existant
+- Todo `brain new / brain sync` — CLI en cours de vision

profil/todo-context.md

@@ -0,0 +1,115 @@
+# todo-context.md — Workflow et lifecycle des todos
+
+> **Type :** Invariant — règles du système todo du brain
+> Rédigé : 2026-03-15
+> Propriétaire : todo-scribe
+> Source de vérité pour : tout agent qui lit ou écrit dans todo/
+
+---
+
+## Problème résolu
+
+Sans règle formalisée, les todos s'accumulent, ne se ferment jamais, ou se ferment silencieusement sans trace. En 20 sessions : liste ingérable, perte de contexte sur pourquoi un todo existe.
+
+---
+
+## Convention todo
+
+### Statuts
+
+| Symbole | Sens | Qui peut changer |
+|---------|------|-----------------|
+| `⬜` | Ouvert — à faire | todo-scribe sur signal |
+| `✅` | Fermé — livré | todo-scribe sur confirmation humaine |
+| `🔄` | En cours — session active dessus | session-orchestrator au boot |
+| `⏸` | Suspendu — bloqué ou déprioritisé | Décision humaine |
+| `❌` | Annulé — ne sera pas fait | Décision humaine + raison documentée |
+
+### Format d'un todo
+
+```markdown
+## ⬜ <Titre court — verbe + sujet>
+
+> Capturé : YYYY-MM-DD — <contexte de capture>
+> Priorité : haute | moyenne | basse
+> Dépend de : <autre todo ou prérequis si applicable>
+
+**L'intention :**
+<Pourquoi ce todo existe. Le problème qu'il résout.>
+
+**Implémentation :**
+1. <étape concrète>
+2. <étape concrète>
+```
+
+---
+
+## Lifecycle d'un todo
+
+```
+Émergé en session → capturé par todo-scribe (⬜)
+    → Session dédiée → todo passe 🔄
+    → Livré → todo-scribe ferme ✅ + commit todo:
+    → Bloqué → ⏸ + raison documentée
+    → Décision de ne pas faire → ❌ + raison
+```
+
+**Règle d'or :** un todo fermé n'est jamais supprimé — il passe ✅. L'historique est une mémoire.
+
+---
+
+## Règles
+
+**1. Capture immédiate**
+Un todo émergé en session = capturé avant la fin de session. Pas "je me souviendrai".
+
+**2. Un todo = une intention atomique**
+Si un todo nécessite 5 sessions → le décomposer en sous-todos liés.
+
+**3. Titre = verbe d'action**
+```
+✅  ## ⬜ Forger agent architecture-scribe
+❌  ## ⬜ architecture-scribe
+```
+
+**4. Priorité explicite**
+Haute = bloque autre chose ou fort impact immédiat.
+Moyenne = important mais pas urgent.
+Basse = nice-to-have, ne pas planifier.
+
+**5. Ne pas fermer sans livrable**
+`✅` = quelque chose a été produit, commité, poussé. Pas juste "on en a parlé".
+
+**6. Débat interdit dans todo/**
+Les todos capturent des intentions, pas des discussions. Le débat va dans une session brainstorm ou un ADR.
+
+---
+
+## Todos et KERNEL.md zones
+
+| Todo concerne | Zone | Commit type à la fermeture |
+|--------------|------|---------------------------|
+| Nouvel agent | KERNEL agents/ | `feat:` |
+| Patch agent | KERNEL agents/ | `fix:` |
+| Profil/spec | KERNEL profil/ | `scribe:` ou `kernel:` |
+| Focus/projet | INSTANCE | `scribe:` |
+| Pattern toolkit | SATELLITES | `toolkit:` |
+| Vision produit | ADR → decisions/ | `kernel:` |
+
+---
+
+## Trigger de chargement
+
+```
+Propriétaire : todo-scribe
+Trigger      : invocation todo-scribe → charger avant lecture/écriture
+Section      : Sources au démarrage (todo-scribe)
+```
+
+---
+
+## Changelog
+
+| Date | Changement |
+|------|------------|
+| 2026-03-15 | Création — statuts, lifecycle, règles, mapping zones |