scribe: propagation sess-20260315-0200-quick-wins — +coach, architecture-scribe, ADRs 001-007, commit/todo-context
This commit is contained in:
33
profil/decisions/001-bsi-locking-optimiste.md
Normal file
33
profil/decisions/001-bsi-locking-optimiste.md
Normal file
@@ -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`
|
||||
31
profil/decisions/002-session-as-identity.md
Normal file
31
profil/decisions/002-session-as-identity.md
Normal file
@@ -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`
|
||||
32
profil/decisions/003-scribe-pattern-non-contamination.md
Normal file
32
profil/decisions/003-scribe-pattern-non-contamination.md
Normal file
@@ -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`
|
||||
@@ -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/`
|
||||
33
profil/decisions/005-zones-typees-kernel-loi-active.md
Normal file
33
profil/decisions/005-zones-typees-kernel-loi-active.md
Normal file
@@ -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
|
||||
124
profil/decisions/006-vision-produit-brain-as-a-service.md
Normal file
124
profil/decisions/006-vision-produit-brain-as-a-service.md
Normal file
@@ -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
|
||||
111
profil/decisions/007-kernel-package-distribution.md
Normal file
111
profil/decisions/007-kernel-package-distribution.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user